Mapping Functions

This section provides reference information for the mapping functions, presented in alphabetical order.

addAttributes

Returns a variable that contains an ADD attribute definition for an LDIF change file.

Synopsis:

  • addAttributes value1 value2 …​

Description:

Returns a list containing the string ADD-VALUE indicating to add the following values.

deleteAttributes

Returns a variable that contains a DELETE attribute definition for an LDIF change file.

Synopsis:

  • deleteAttributes value1 value2 …​

Description:

Returns a list containing the string DELETE-VALUE indicating to delete the following values.

hdmsCmd2dmsid

Extracts the DMS Identifier from the CMD field of an HDMS record.

Synopsis:

  • hdmsCmd2dmsid cmdfield

Description:

This function extracts the DMS identifier from the first field of an HDMS record (cmdfield).

Example:

The function applied on cmdfield="INSERT;PERS;29874" evaluates to

29874

hdmsdata2dn

Creates a DN from an HDMS entry.

Synopsis:

  • hdmsdata2dn handleName

Description:

By default, this function uses the field’s name (abbreviation NAME), Christian name (abbreviation CHN), org1 (abbreviation ORG1), company (abbreviation O) and country (abbreviation C) from an array that is defined by handleName to create a distinguished name.

Example:

With NAME=Mayer, CHN=John, ORG1=development, O=My-Company and C=de the resulting distinguished name is:

cn=Mayer John,ou=development,o=My-Company,c=de

hdmsData2telno

Gets a telephone or a facsimile telephone number as a concatenation of HDMS attributes.

Synopsis:

  • hdmsData2telno country extarea extnet extext

Description:

This function concatenates its four input arguments to a canonical four-part telephone (or fax) number with the blank delimiter. Using an internal table, the country is converted into the country code.

Example:

For instance, the input parameters country="DE", extarea="89", extnet="777" extext="12345" evaluates to

+49 89 777 12345

ifEqual

Checks a variable’s value and sets the result to one of two values.

Synopsis:

  • ifEqual variable value then-value else-value

Description:

If variable equals value, the result is set to then-value, else to else-value.

This function works on a single-valued list only.

ifNotEqual

Checks a variable’s value and sets the result to one of two values.

Synopsis:

  • ifNotEqual variable value then-value else-value

Description:

If variable does not equal value, the result is set to then-value, else to else-value.

This function works on a single-valued list only.

lADSpathCreate

Creates an ADS path.

Synopsis:

  • lADSpathCreate prefix type1 value1 type2 value2 …​

Description:

This routine is used to generate an ADSpath from a list of input field pairs. This routine is useful for mappings for import to ADS / Exchange. In order to be very flexible, the user needs to pass the types of the components of the ADS path, too.

The first argument prefix allows defining a constant value as the first part of the path.

Each of the next pair of arguments is combined to a part of the path (for example "cn" and ldap.cn with a value of 'Huber Max' are combined to 'cn=Huber Max'. If the value field is empty, this part of the DN is omitted.

Examples:

The arguments

"LDAP://server1:389" "o" ldap.o "ou" ldap.ou "cn" ldap.cn

create with values
ldap.cn=Huber Max
ldap.ou=Development
ldap.o=My-Company

an ADS path: LDAP://server1:389/o=My-Company/ou=Development/cn=Huber Max

Error Handling

An error is returned in the global variable mapping_error when

  • One of the input values is a multi-valued string

lBaseDNreplace

Replaces the base DN in a DN.

Synopsis:

  • lBaseDNreplace string string1 string2

Description:

Replaces string1 by string2 in the string array string. Replacement is done starting at the end of the string.

lBool2Integer

Converts boolean values (TRUE and FALSE) to integer values (1 and 0).

Synopsis:

  • lBool2Integer boolean

Description:

FALSE will be mapped to "0". TRUE will be mapped to "1". For all other values, the value "" is generated.

lDate2GMT

Converts an list of dates into a list of GENERALIZED time strings.

Synopsis:

  • lDate2GMT date_list

Description:

This routine converts a list of dates into a list of generalized time strings (the LDAP format for date and time information).

These input formats can be converted:

JJJJMMDDhhmmssZ (generalized time format is a valid input format)
MM/DD/JJJJ hh:mm:ss
DD.MM.JJJJ hh:mm:ss
JJJJ-MM-DD hh:mm:ss

Examples:

20030228123822Z → 20030228123822Z
02/28/2003 12:38:22 → 20030228123822Z
28.02.2003 12:38:22 → 20030228123822Z
2003-02-28 12:38:22 → 20030228123822Z

Error Handling

An error is returned in the global variable mapping_error when

  • An invalid input date format is detected.

  • The date is outside the range from 1902-01-01 00:00:00 to 2037-12-31 00:00:00 (Tcl restriction).

lDNcreate

Creates a DN.

Synopsis:

  • lDNcreate type1 value1 type2 value2 …​ [typen valuen] | valuen

Description:

This routine is used to generate a distinguished name (DN) from a list of input field pairs. This routine is useful for import mappings. In order to be very flexible, the user needs to pass the types of the components of the DN, too.

Each of the pairs of arguments is combined to a part of the path (for example "cn" and ldap.cn with a value of 'Huber Max' are combined to 'cn=Huber Max'). The pair results are concatenated with commas.

When the number of arguments is a multiple of two, the path ends with a combination of type=value. When the number of arguments is not a multiple of two, the path ends with a constant (for example 'o=pqr'). If the value field is empty, this part of the DN is omitted.

Examples:

The arguments

"cn" ldap.cn "ou" ldap.ou "o" ldap.o

create with values
ldap.cn=Huber Max
ldap.ou=Development
ldap.o=My-Company

as result the DN:

cn=Huber Max,ou=Development,o=My-Company

"cn" ldap.cn "ou" ldap.ou "l=DE,o=pqr"

create with the same values as result the DN:

cn=Huber Max,ou=Development,l=DE,o=pqr

Error Handling

An error is returned in the global variable mapping_error when

  • one of the input values is a multi-valued string

lDNsplit

Splits a DN into the elements of a Tcl array.

Synopsis:

  • lDNsplit dn arrayname

Description:

This routine is used to split a distinguished name (DN) into the elements of a Tcl array. The first argument dn is split into elements by using the comma separator. These elements are split again into the element name and value.

Note that the result of this function is a return code and not the array. The return code is 0 if no errors occurred and 1 if syntax errors were detected.

Examples:

If DDN contains the value "cn=Huber\,Hans,ou=ICN,o=My-Company"

lDNsplit DDN "my_array"

creates a Tcl array with these elements:

cn=Huber\,Hans
ou=ICN
o=My-Company

You can access the elements with my_array(cn), my_array(ou), …​

Error Handling

An error is returned in the global variable mapping_error and in the return code when

  • An invalid syntax is detected (for example "abc/def") and results in a return code of '1'.

When an element in the DN occurs multiple times (for example, "cn=Huber,ou=SNS,ou=ICN,o=My-Company"), a number is added automatically to the field name:

cn=Huber
ou=SNS
ou1=ICN
o=My-Company

When accessing the array elements, you must be sure that they exist. Otherwise a Tcl error will be the result. You can test the availability of such an element with info exists.

lInteger2Bool

Converts integer values (0 and 1) to boolean values (FALSE and TRUE).

Synopsis:

  • lInteger2Bool integer

Description:

"0" will be mapped to FALSE. "1" will be mapped to TRUE. For all other values the value "" is generated.

listFirst

Returns the first element of a list as a string.

Synopsis:

  • listFirst list

Description:

Returns the first element of a list as a string.

listLast

Returns the last element of a list as a string.

Synopsis:

  • listLast list

Description:

Returns the last element of a list as a string.

lListAppend

Appends elements to a list.

Synopsis:

  • lListAppend list list …​

Description:

Appends all elements to a list.

lListFirst

Returns the first element of a list as a new single-valued list.

Synopsis:

  • lListFirst list

Description:

Returns the first element of a list as a new single-valued list.

lListLast

Returns the last element of a list as a new single-valued list.

Synopsis:

  • lListLast list

Description:

Returns the last element of a list as a new single-valued list.

lListNth

Returns the nth element of a list as a new single-valued list.

Synopsis:

  • lListNth list n

Description:

Returns the nth element of a list as a new single-valued list.

lListRest

Returns the second to last element of a list.

Synopsis:

  • lListRest list

Description:

Returns the second to last element of a list as a new list.

lPA2String

Replaces the $ characters with carriage returns.

Synopsis:

  • lPA2String list

Description:

Replaces the $ characters in a postal address field with carriage returns. Replacement is done for all the elements of the Tcl list.

lString2PA

Replaces carriage returns with $ characters.

Synopsis:

  • lString2PA list

Description:

Replaces carriage returns with $ characters in a postal address field. Replacement is done for all the elements of the Tcl list.

lStringAppend

Appends strings to all elements of a list.

Synopsis:

  • lStringAppend list string1 string2 …​

Description:

This routine takes the given list and appends to all its elements the given strings string1, string2, …​.

The result value of this routine is a Tcl list with all the appended values.

Note: The native TCL command append doesn’t work properly for Tcl lists. Therefore the wrapper function is needed.

lStringCompose

Composes an output string from a variable number of input strings.

Synopsis:

  • lStringCompose separator string1 string2 …​

Description:

The output string is composed of all values of the input strings (string1 …​ string n) separated by the defined separator. Be sure to have strings and not Tcl lists as input parameters (you can use, for example, the ListFirst function to extract the first string of a Tcl list).

If an input string has no value, it is simply omitted together with the separator value.

Examples:

lStringCompose ";" "abc" "def" "ghi" results in "abc;def;ghi"

If sn="Huber", givenName="" and employeeNumber="1234" then

lStringCompose " " sn givenName employeeNumber

results in "Huber 1234"

lStringConvertChars

Replaces UTF-8 characters with underlying vowels.

Synopsis:

  • lStringConvertChars value

Description:

lStringConvertChars replaces certain UTF-8 characters with their underlying vowels or other characters. This routine is useful for attributes that have a limited character set only; for example, PrintableString (as used in the attribute "mail").

The function takes a Tcl list of strings as input, performs the necessary replacements and returns a new Tcl list of the modified strings.

The following characters are substituted by the underlying vowel:

À Á Â Ã Å Æ -→ A

à á â ã å æ -→ a

Ä -→ AE

ä -→ ae

È É Ê Ë -→ E

è é ê ë -→ e

Ì Í Î Ï -→ I

ì í î ï -→ i

Ò Ó Ô Õ Ø -→ O

ò ó ô õ ø -→ o

Ö -→ OE

ö -→ oe

Ù Ú Û -→ U

ù ú û -→ u

Ü -→ UE

ü -→ ue

The following characters are substituted by an equivalent character:

Ç -→ C

ç -→ c

ß -→ ss

Ñ -→ N

ñ -→ n

Ý -→ Y

ý ÿ -→ y

Examples:

Müller -→ Mueller

Résidence -→ Residence

lStringEncrypt

Encrypts a Tcl list and returns the encrypted values as Tcl list.

Synopsis:

  • lStringEncrypt list

Description:

This routine takes the given list list and encrypts each of its values.

Use this function, for example, to generate default passwords that must be transferred to the target system in encrypted format. You can also use the function to encrypt data values before you write them into the directory.

See the user hook function uh::prolog description in the section "Understanding Tcl-based Workflows" in the DirX Identity Application Development Guide for more information how to initialize the certificate information.

Error Handling:

An error is returned in the global variable mapping_error and in the return code when

  • Encryption of one of the values fails (results in a return code of '1').

lStringEscape

Escapes the characters ;\{} in all elements of the list.

Synopsis:

  • lStringEscape list

Description:

Escapes the characters ;\{} in all elements of the list. This function is useful before working in Tcl with these variables. After other operations, the escaped character sequences can be removed with the reverse function lStringUnescape.

Note: This escaping is necessary because metacp uses some characters in a special way. The character ";" serves as a multi-value separator. The characters "\{" and "}" are needed to handle Tcl lists correctly and prevent unequal numbers of these characters in attribute values.

lStringEscapeLDIF

Converts elements of an LDIF content file or LDIF change file.

Synopsis:

  • lStringEscapeLDIF value ldif_opcode

Description:

Escapes the characters ;\{} in all elements of the list. This function is useful before working in Tcl with these variables. After other operations, the escaped character sequences can be removed with the reverse function lStringUnescape.

Note: This escaping is necessary because metacp uses some characters in a special way. The character ";" serves as a multi-value separator. The characters "\{" and "}" are needed to handle Tcl lists correctly and prevent unequal numbers of these characters in attribute values. In contrast to the mapping function lStringEscape, which is only appropriate for Tcl lists representing the full information of an attribute value, the function lStringEscapeLDIF is also applicable to lists representing LDIF changes.

If ldif_opcode is not "MODIFY", then behavior with respect to values is the same as for the lStringEscape mapping function.

Examples:

The following example session illustrates the difference between lStringEscapeLDIF and lStringEscape.

metacp> set x [llist ADD-VALUE "A\;B c"]

results in:

ADD-VALUE {A;B c}

metacp> set bad_mapping [lStringEscape $x]

results in

{ADD-VALUE \{A\;B c\}}

metacp> set good_mapping [lStringEscapeLDIF $x MODIFY]

results in

{ADD-VALUE {A\;B c}}

We can see the following information from this example:

  1. The source list x represents an attribute change Add value "A;B c"

  2. The list bad_mapping represents an attribute change Add values "{A;B", "c} (with ; and {} being escaped), that is inappropriate here.

  3. The list bad_mapping represents an attribute change Add value "A;B c" (with ; being escaped) that is correct.

lStringEscapeVar

Escapes the defined characters in all elements of the list.

Synopsis:

  • lStringEscapeVar list chars

Description:

Escapes the defined characters chars in all elements of the list. This function is useful before working in Tcl with these variables. After other operations, the escaped character sequences can be removed with the reverse function lStringUnescapeVar.

lStringModify

Replaces either 'n' or all occurrences of string A with string B in all elements of a list.

Synopsis:

  • lStringModify list string1 string2 ?n?

Description:

This routine takes the given list and replaces (n times) in each of its strings the substring string1 with substring string2.

If n is missing or set to 'all', then all of the matching substrings will be replaced.

The result value of this routine is a Tcl list with all the replacements made.

Examples:

lStringModify {{The weather is not fine} {It’s raining}} "i" "X" 1

will return the following Tcl list: {{The weather Xs not fine} {It’s raXning}}

lStringModify {{The weather is not fine} {It’s raining}} "i" "X" 2

will return the following Tcl list: {{The weather Xs not fXne} {It’s raXnXng}}

lStringPrefix

Adds a string before each element of a Tcl list.

Synopsis:

  • lStringPrefix string list

Description:

This routine takes the given list and prefixes each of its elements with the string string.

The result value of this routine is a Tcl list with all elements prefixed.

Examples:

lStringPrefix "cn=" {{Huber} {Maier}}

will return the following Tcl list: {{cn=Huber} {cn=Maier}}

lStringRange

Returns all the characters of each element in the list in the range from first to last.

Synopsis:

  • lStringRange list first last

Description:

The routine operates in the same way as the original Tcl function string range, except that it works for Tcl lists.

It returns all the characters of list in the range from first to last (inclusive).

lStringTrim

Drops leading and trailing characters from all elements of a list.

Synopsis:

  • lStringTrim list ?chars?

Description:

The routine operates in the same way as the original Tcl function string trim, except that it works for Tcl lists.

It drops leading and trailing characters from a string. If chars is not specified, then white spaces are removed (spaces, tabs, newlines, and carriage returns).

lStringTrimLeft

Drops leading characters from all elements of a list.

Synopsis:

  • lStringTrimLeft list ?chars?

Description:

The routine operates in the same way as the original Tcl function string trimleft, except that it works for Tcl-Lists.

It drops leading characters from a string. If chars is not specified, then white spaces are removed (spaces, tabs, newlines, and carriage returns).

lStringTrimRight

Drops leading and trailing characters from all elements of a list.

Synopsis:

  • lStringTrimRight list ?chars?

Description:

The routine operates in the same way as the original Tcl function string trimright, except that it works for Tcl lists.

It drops trailing characters from a string. If chars is not specified, then white spaces are removed (spaces, tabs, newlines, and carriage returns).

lStringUnescape

Unescapes the characters ;\{} in all elements of the list.

Synopsis:

  • lStringUnescape list

Description:

Unescapes the characters ;\{} in all elements of the list. This function is useful after working in Tcl with these variables. The reverse function is lStringEscape.

This escaping is necessary because metacp uses some characters in a special way. The character ";" serves as a multi—​value separator. The characters "\{" and "}" are needed to handle Tcl lists correctly and prevent unequal numbers of these characters in attribute values.

lStringUnescapeVar

Unescapes the defined characters in all elements of the list.

Synopsis:

  • lStringUnescapeVar list chars

Description:

Unescapes the defined characters chars in all elements of the list. This function is useful after working in Tcl with these variables. The reverse function lStringEscapeVar.

lWordCapitalize

The first character of all words is converted to uppercase, the rest in lowercase for all elements in the list.

Synopsis:

  • lWordCapitalize list

Description:

Converts the first character of each word in all elements in the list to uppercase and all other characters to lowercase.

lWordFirst

Retrieves the first word for all elements of the list.

Synopsis:

  • lWordFirst list

Description:

This routine takes the given list (list of strings) and extracts the first word from each of the strings. The result value of this routine is a list that contains the first word of each input string.

Example:

lWordFirst {{The weather is not fine} {It’s raining}}

will return the following list: {{The} {It’s}}

lWordLast

Retrieves the last word for all elements of the list.

Synopsis:

  • lWordLast list

Description:

This routine takes the given list (list of strings) and extracts the last word from each of the strings. The result value of this routine is a list that contains the last word of each input string.

Example:

lWordLast {{The weather is not fine} {It’s raining}}

will return the following list: {{fine} {raining}}

lWordNth

Retrieves the nth word for all elements of the list.

Synopsis:

  • lWordNth list n

Description:

This routine takes the given list (list of strings) and extracts the nth word from each of the strings. The result value of this routine is a list that contains the nth word of each input string.

If n is greater than the number of words in the strings then nothing is returned.

Example:

lWordNth {{The weather is not fine} {It’s raining}} 2

will return the following list: {{weather} {raining}}

lWordNth {{The weather is not fine} {It’s raining}} 3

will return the following list: {{is} {}}

RDNescape

Escapes the characters =,+;\{} in the RDN attribute value.

Synopsis:

  • RDNescape list

Description:

Escapes the characters =,+;\{} in the RDN attribute value. This function is useful before working in Tcl with this variable. After other operations, the escaped character sequences can be removed with the reverse function RDNunescape.

RDNunescape

Unescapes the characters =,+;\{} in the RDN attribute value.

Synopsis:

  • RDNunescape list

Description:

Unescapes the characters =,+;\{} in the RDN attribute value. This function is useful after working in Tcl with this variable. The reverse function is RDNescape.

replaceAttributes

Returns a variable that contains a REPLACE attribute definition for an LDIF change file.

Synopsis:

  • replaceAttributes value1 value2 …​

Description:

Returns a list containing the string REPLACE indicating to replace the following values.

This function is especially valuable when the whole entry must be replaced via an LDIF change file. In this case, all attributes should be handled with the replaceAttributes function.

StringAppend

Appends strings to the given string.

Synopsis:

  • StringAppend list string1 string2 …​

Description:

This routine takes the given list and appends to all its elements the given strings string1, string2, …​.

The result value of this routine is a list with all the appended values.

Note: The native Tcl command append doesn’t work properly for Tcl lists. Therefore the wrapper function is needed.

StringModify

Returns a string where either 'n' or all occurrences of string A are replaced with string B.

Synopsis:

  • StringModify list string1 string2 ?n?

Description:

This routine takes the given Tcl list and replaces (n times) in each of its strings the substring string1 with the substring string2. If n is missing or set to "all", then all of the matching substrings will be replaced.

The result value of this routine is a Tcl list with all the replacements made.

Examples:

StringModify "The weather is not fine" "i" "X" 1

will return the following Tcl string: "The weather Xs not fine"

StringModify "The weather is not fine" "i" "X" 2

will return the following string: "The weather Xs not fXne"