meta (metacp)

[meta] addentry
    -entry entry_handle
    [-updateattr attribute_list]

[meta] appendresult
    -source source_search_result_handle
    -target target_search_result_handle

[meta] createindexlist
    [-exactaction]
    -conn connection_handle
    -handle index_list_handle
    [-type distinguished_name_syntax]

[meta] encryptdata
    -result result_handle
    -databindid data_bind_id
    -keybindid key_bind_id
    [-oldserialnumber old_serial_number]

[meta] encryptvalue string

[meta] escapechar string
    -characters characters

[meta] findentry
    -result result_handle
    -name distinguished_name or attribute_value
    -entry entry_handle
    [-getattr flag]
    [-tag tag]
    [-numbermatches number_variable]

[meta] getchangelog
    -name distinguished_name
    -changetype operation_change_type
    -changes list of changes
    -source handle_to_pseudo_LDIF-file
    -target entry_handle

[meta] getentry
    -source source_handle
    {-target entry_handle [-tag tag] [-mark]
    [-name distinguished_name [-countmatches flag]] |
    -reset}

[meta] gethandle
    -entry entry_handle
    -conn connection_handle

[meta] getnumentries
    -result result_handle

[meta] getstatistic statistic_variable

meta help [operation | -verbose]

[meta] initialize
    -file trace_file
    [-tracelevel level]
    [-maxtracerecords recordnumber]
    [-maxentries number]
    [-mode initialization_mode]
    [-nostatistics]

[meta] modifydn
    -entry entry_handle

[meta] modifyentry
    -newentry entry_handle
    [-oldentry entry_handle]
    [-tag tag]
    [-allowrename rename_flag]
    [-updateinfo update_flag]
    [-updateattr attribute_list]

[meta] openconn
    -type directory_type
    [-file filename -mode file_open_mode
    [-format file_format] [encoding encoding]]
    [-attribute attribute_list [-processallattr]]
    -attrconf attr_conf_handle
    -conn connection_handle
    [-bindid binding_id]
    [-ldifhandle LDIF_file_handle]

[meta] openldif
    -file filename
    -ldifhandle LDIF_file_handle

meta operations

[meta] readattrconf
    -file filename
    -attrconf attr_conf_handle
    [-encoding encoding]

[meta] releasehandle handle

[meta] removeentries
    -handle handle
    [-tag tag]

[meta] sortindexlist -handle index_list_handle
    [-keepnames index_list_access_flag]

[meta] sortresult
    -result result_handle
    -order sort_order
    [-key sort_key]

[meta] supinfo
    -rdn attribute_type
    {-attribute attribute_value | -remove}
    [-bindid binding_id]

[meta] terminate

[meta] unescapechar string

[meta] writeindexlist
    -handle index_list_handle
    -name distinguished_name
    -entry entry_handle

[meta] writerecord
    -entry entry_handle

[meta] writetext
    -conn connection_handle
    -text string
    [-nonewline flag]

[meta] writetrace
    -text string
    [-handle handle]

A metacp object that performs directory synchronization operations.

Creates a new entry in the Identity store (a connected directory of type LDAP). The syntax is as follows:

[meta] addentry
    -entry entry_handle
    [-updateattr attribute_list]

The addentry operation adds the entry associated with entry_handle into the Identity store (a connected directory of type LDAP). The Tcl variable array associated with entry_handle must contain a value for the Directory-Distinguished-Name (DDN) attribute. The add entry operation uses this value for the entry name when it creates the entry. The attributes that the operation creates for the entry correspond to the set of attributes present in the Tcl variable array associated with entry_handle.

The addentry operation creates the necessary superior entries when creating the entry provided that the required attribute information has been specified with a supinfo operation.

If the underlying connection handle (derived from entry_handle) is an LDAP directory with the parameter -ldifhandle set, the addentry is not applied to the LDAP directory; instead, an LDIF-CHANGE operation is created in the LDIF-CHANGE file associated with -ldifhandle parameter.

metacp automatically propagates a JMS message (containing the SPML add request) if at the beginning of a synchronization scenario ats initialize has been called with the options -topicprefix, -type, -cluster, and -resource. (See ats initialize for details.)

Check the Tcl variable errorCode for error details. If this variable is not set or its value is empty, the entry was successfully created. Otherwise the error is logged in the trace file and the entry was not created.

Example

gethandle, initialize, openconn, openldif, supinfo, ats initialize

Appends a new search result to an already existing search result. The syntax is as follows:

[meta] appendresult
    -source source_search_result_handle
    -target target_search_result_handle

The appendresult operation appends a search result (identified by the source_search_result_handle) to an already existing target search result. If the target result does not exist as yet, the target search result handle will be created and consists of all the entries from the source search result.

The two search results can only be merged if the following conditions are satisfied:

Only if these conditions are satisfied, the final search result is consistent again.

If the target search result was already sorted (using meta sortresult), then the final search result will be sorted again with the same sort criterias.

None.

obj search

Creates a handle to an index list. The syntax is as follows:

[meta] createindexlist
    [-exactaction]
    -conn connection_handle
    -handle index_list_handle
    [-type distinguished_name_syntax]

The createindexlist operation initializes an empty index list template, creates a handle to it, and assigns it the name specified with the -handle option. The index list can then be used to sort the entries in the connected directory, rather than sorting the connected directory (which is a file) itself. The process for using an index list to sort directory entries is as follows:

You can then continue the directory synchronization process using the sorted index list rather than using the connected directory. For example, you can perform meta getentry operations on the sorted index list by specifying its index handle rather than specifying the connection handle to the connected directory.

The createindexlist operation stores the distinguished name syntax keyword specified in the -type option in the index list handle. The meta sortindexlist operation uses this information to determine how to process the distinguished names in the index list. If the -type option is not specified, the operation uses DAP distinguished name processing.

None.

getentry, sortindexlist, writeindexlist

Performs data encryption for a search result handle based on the private keys and certificates stored for the server (IdS-C) admistrator object cn=server_admin,dxmc=DirXmetahub. There is a support of both an initial mode (encryption of cleartext data with the public key having the highest serial number) and a migration mode which includes

The command syntax is as follows:

[meta] encryptdata
    -result result_handle
    -databindid data_bind_id
    -keybindid key_bind_id
    [-oldserialnumber old_serial_number]

None.

An encryptdata operation for initial encryption:

An encryptdata operation for migration from old serial number 6E to current serial number:

obj bind, obj search, initialize, encryptvalue

Performs data encryption for a string based on the certificates stored for the Server (IDS-C) administrator object cn=server_admin,dxmc=DirXmetahub. It uses the public key (certificate) with the highest serial number.

That function is only available when metacp runs in encryption mode.

The syntax is as follows:

[meta] encryptvalue string

none

The encrypted string.

In case of errors, an error message is returned and the errorCode variable is set.

The encryptvalue operation

returns the encrypted value base on the currently available public key.

encryptdata

Escapes one or more characters in a string. The syntax is as follows:

[meta] escapechar string
    -characters characters

The escapechar operation escapes one or more characters by prefixing them with the backslash character (\) and returns the escaped string as a result. The backslash character itself is escaped as well.

Use the -characters option to escape only those characters specified in characters. To avoid conflicts with the Tcl shell escape mechanism, enclose the string that contains the characters to be escaped in curly braces (\{ }). If curly braces are to be a part of the string, they must be escaped.

The escaped string.

The escapechar operation

returns the string f\{1\}\=2

unescapechar

Retrieves an entry from the sorted results of an obj search operation. The syntax is as follows:

[meta] findentry
    -result result_handle
    -name distinguished_name or attribute_value
    -entry entry_handle
    [-getattr flag]
    [-tag tag]
    [-numbermatches number_variable]

The findentry operation attempts to match the entry specified in the -name option to an entry within the directory search results specified in the -result option. On success, the operation creates an entry handle associated with the matched entry and assigns it the name specified in the -entry option. By default, the entry handle created by meta findentry is not associated with a Tcl variable array. Use the -getattr option to associate the handle with a Tcl variable array.

0 The entry was found

1 The entry was not found

getentry, modifyentry, removeentries, obj search

Processes an LDIF change log entry as provided, for example, by iPlanet or Oracle Internet Directory (OID). The syntax is as follows:

[meta] getchangelog
    -name distinguished_name
    -changetype operation_change_type
    -changes list of changes
    -source handle_to_pseudo_LDIF-file
    -target entry_handle

Both iPlanet and OID store all the changes of directory entries and attributes in the directory itself as directory entries (changelog entries). The getchangelog operation processes a change log entry that has been read either from an iPlanet or OID directory using an obj search operation. The relevant attributes (targetDN, changetype, changes) of such a changelog entry are passed to getchangelog; as the format of these parameters are exactly the same as if an LDIF change file had been read, getchangelog will internally concatenate the values of these parameters as a byte stream in memory and then use its internal LDIF file parser. (Therefore, a handle to a pseudo LDIF file must be passed as -source handle.)

On success, getchangelog creates a handle to the entry and associates it with the name in the target option. The entry’s DN and its attributes become accessible as an array of Tcl variables. For details, see the description of getentry.

0 The entry was successfully processed

1 The entry could not be processed

In this example, the change log entry has been read by obj search and its data is available in the Tcl array named chlog:

getentry, Chapter: Processing of ChangeLogEntries

Reads the next entry from a connected directory, a search results list, or an index list, reads a specific entry from an index list, or resets a search results list or index list. The syntax is as follows:

[meta] getentry
    -source source_handle
    {-target entry_handle [-tag tag] [-mark]
    [-name distinguished_name [-countmatches flag]] |
    -reset}

Use the getentry operation to:

Specify the -reset option to reset an index list or a search results list to the beginning of the list.

Specify the -target option to read an entry from a connected directory, a search results list, or an index list into the metacp workspace. On success, the operation creates a handle to the entry and associates it with the name specified in the -target option. When the getentry operation reads an entry into the metacp workspace, the entry’s attributes to be synchronized become accessible as an array of Tcl variables. Each Tcl variable in the array represents a specific attribute to be synchronized; the variable is a Tcl list of the attribute’s values. The Tcl variable array corresponds to the set of attributes to be synchronized (SSA); the SSA is defined:

The Tcl variable array created by the getentry operation also contains two special attributes:

Use the Tcl notation $*entry_handle(abbreviation)* to reference an element of the Tcl variable array, where entry_handle is the name of the handle and abbreviation is the attribute abbreviation for the attribute defined in the Abbreviation (Abbr) field of the attribute configuration file. For example, suppose that:

Then the indexes to the values for these attributes in the Tcl array are

$eh(DDN) - to access the attribute value(s) for Directory-Distinguished-Name

$eh(LCHNGTYPE) - to access the attribute value for the entry operation code

$eh(givenName) - to access the attribute value(s) for Given Name

$eh(sn) - to access the attribute value(s) for Surname

$eh(telephoneNumber) - to access the attribute value(s) for Telephone Number

An attribute with a single value is represented as a Tcl list with one element. A multi-valued attribute is represented as a Tcl list of multiple elements, one for each value. Use Tcl statements for accessing list variables to manipulate the values in the Tcl variable array; for example, lindex.

For the "add" "delete" and "modify DN" LDIF change operations, each variable in the Tcl array contains a list of attribute values. For "modify" operations, each variable in the Tcl array contains a list of attribute changes. Each change is of the form:

{ changetype [ values] }

where changetype is

to indicate the three different types of attribute value modifications. The Tcl list:

represents the addition of two attribute values and the removal or one attribute value for a specific attribute. If the variable eh(telephoneNumber) has this list value, the changes apply to the attribute telephoneNumber. The first element of eh(telephoneNumber) is:

The "add" and "replace" Tcl lists must contain one or more attribute values as elements that follow the changetype element. A "delete" Tcl list with one element (the changetype) indicates that the attribute itself is to be removed.

The Tcl variable array for a "modify DN" LDIF operation contains three additional attributes:

The attribute abbreviations for these attributes are specified in the attribute configuration file.

The elements of the Tcl variable array remain accessible as Tcl variables until they are unset with the Tcl unset command or until the handle to the entry is released with meta releasehandle.

If the -target option specifies a result handle to a search results list, use the MARKED keyword in the -tag option to read the next entry from the Identity store (a connected directory of type LDAP) that the meta modifyentry or meta findentry operations have marked as "processed" in the results list. Use the NOTMARKED keyword to read the next entry that has not been marked by meta modifyentry or meta findentry.

If the -target option specifies an index list handle to an index list, and a meta sortindexlist operation with the -keepnames option has been performed on the index list specified in the -source option, you can use the -name option to read an entry with a specific distinguished name from the list. If there is more than one entry in the index list that matches the specified distinguished name, the entry handle returned by the operation represents the first matched entry in the index list. To retrieve the next matching entry, use the meta getentry operation without any options. Use the mark option to mark the entry in the index list before meta getentry is going to return that entry. Use the tag option in order to decide which entries should be returned from the index list: use the MARKED keyword, if an already marked entry should be returned once again; use the NOTMARKED keyword, if the next unmarked entry has to be returned.

Use the -countmatches option in conjunction with the -name option to select whether the meta getentry operation returns the number of entries that match the specified distinguished name, or whether it returns the status codes described in Return Values. The setting for the -countnames option affects how the operation’s return values are to be interpreted. For example, if the operation finds one matching entry, and -countnames is set to FALSE (or not specified at all), the operation returns 0, which represents success (and not the number of matching entries found). If the operation finds one matching entry, and -countnames is set to TRUE, the operation returns 1, which represents the number of matching entries found (and not "end of list".)

The type of handle specified in the -source option affects the handle dependencies for the handle created by getentry:

Note: If the meta getentry operation retrieves an entry from an LDIF change file that does not contain an LDIF operation code (ADD, DELETE, MODIFY, or MODIFY-DN), it creates an empty _ldif_opcode Tcl variable when it creates the Tcl variable array.

addentry, createindexlist, modifydn, modifyentry, obj search, openconn, removeentries, writerecord

Attribute Configuration File Format (Chapter 2)

Creates a handle to an empty entry. The syntax is as follows:

[meta] gethandle
    -entry entry_handle
    -conn connection_handle

The gethandle operation creates an entry handle associated with a "template" directory entry and assigns it the handle name specified in the -entry option. The "template" entry is an array of Tcl variables initialized as empty lists in the same format as that created by the getentry operation. Subsequent Tcl statements or meta operations (issued in the synchronization profile) read values into the array. The elements of the Tcl variable array remain accessible as Tcl variables until they are unset with the Tcl unset command or until the handle to the entry is released with meta releasehandle.

None.

meta gethandle -entry eh -conn ch

addentry, getentry, modifydn, modifyentry, openconn, removeentries, writerecord

Attribute Configuration File Format (Chapter 2)

Section Synchronization Profile (DirX Identity Connectivity Administration Guide)

Returns the number of entries in a search result. The syntax is as follows:

[meta] getnumentries
    -result result_handle

The getnumentries operation returns the number of entries contained in the results of a search operation.

None.

obj search

Returns the statistic information as a (global) TCL array, if the statistic was not turned off in meta initialize. The syntax is as follows:

[meta] getstatistic statistic_variable

none

Fills the given TCL array with the following components:

The function

sets the following TCL array:

Initialize

Returns help information about the meta object and its operations. The syntax is as follows:

meta help [operation | -verbose]

Used without an argument or option, the help command displays a list of the meta operations. The operations are listed in alphabetical order, except for help and operations, which are listed last. Use the operation argument to return a brief description of an operation and its associated options. Alternatively, you can use the -verbose option to return a description of the meta object itself.

None (The requested information is displayed).

The output of the sample command is as follows:

The output of the sample command is as follows:

Initializes the metacp workspace and opens a trace file for writing. The syntax is as follows:

[meta] initialize
    -file trace_file
    [-tracelevel level]
    [-maxtracerecords recordnumber]
    [-maxentries number]
    [-mode initialization_mode]
    [-nostatistics]

The initialize operation initializes metacp data structures and creates a metacp trace file to be used to store information about the directory synchronization process. A synchronization profile must invoke the initialize operation before it invokes any metacp operations that operate on meta handles.

When they are invoked in a synchronization profile, the meta addentry, meta modifydn, meta modifyentry and meta removeentries operations automatically write information about their operation into the trace file specified with the -file option. The writetrace operation can also be used to write explicit trace information into the trace file.

Use the -tracelevel option to control the level of trace information that the meta addentry, meta modifydn, meta modifyentry and meta removeentries operations write to the trace file. A trace level of 1 directs the operations to perform error tracing. An error trace on an operation traces:

With error tracing, if an error occurs on an entry being processed, the operation writes the entry as it appears in the original source file into the trace file together with the associated directory operation and error message, prefixed with the # character.

Here is a sample error trace record:

A trace level of 2 directs the operations perform full tracing. A full trace on an operation traces:

With full tracing, the operations write both error trace information and successful operation information to the trace file. Entries that are successfully processed are written to the file and delimited with # characters.

Here is an excerpt from a full trace operation:

For readability, the previous example shows the attributes added to the entry on separate lines; in the trace file, all the attributes added to an entry appear on a single line.

A trace level of 3 directs the operation to perform full tracing except for entries that are already up-to-date. For example, the "add" operation shown in the previous example appears in the trace file, but the "modify" operation for which no update was necessary does not appear in the trace file.

If the -tracelevel option is not specified, the operations by default perform level 1 (error) tracing.

Use the -maxtracerecords option to limit the maximum number of records in a trace file. recordnumber specifies the maximum number of records. If the option is missing or the value is 0 only one trace file is written with an unlimited number of records.

If required several trace files are written each of them containing at least recordnumber trace records. The maximum number of records written to the trace files may differ slightly from the specified number because the maximum number is checked after the complete information about a synchronization entry is written. For example the source entry, the entry in the directory, the generated operation, and the result of the operation represent a logical unit and is written completely to the trace file before the maximum number of records written is checked.

If more than one trace file is written an internal sequence number in the format -number is inserted into the filename of the next trace file when a trace file exceeds the maximum number of records. Use the wildcard character (*) in the -file file_name option to specify the position of this sequence number. For example you specify the following options:

After writing at least the 50000th record to the trace file currently in use the file is closed. A new trace file is created. The internal sequence number is inserted at the position of the wildcard character into the filename of the new file. After finishing the synchronization process you find for example the following trace files:

where "trace_file.trc" is the first trace file written and closed after exceeding the maximum number of records.

If you do not use a wildcard character to specify the position of the sequence number this number is appended to the filename (before its extension, if there is one), for example "trace_file-1.trc" or "trace-1".

Use the -maxentries option to set a limit on the number of entries in a search results list that will be processed by meta writetrace operations. When the -maxentries option is specified, the meta writetrace operation writes only the number of entries specified in number to the metacp trace file. If this option is not specified, the default is "no limit".

Use the -mode option to control whether or not metacp performs update operations on the Identity store (a connected directory of type LDAP) during an import process. When the -mode option is set to TRIAL, metacp logs update operations with the message "operation ignored" and does not make the changes to the Identity store. When the -mode option is set to REAL, metacp makes the updates to the Identity store.

The generated trace file contains the source entry information. Consequently, if errors occur during an import from a connected directory of type FILE into the Identity store (a connected directory of type LDAP), administrators can re-run the synchronization profile using the trace file as input (after first fixing the errors reported in the trace file)

See the "Return Values" section in the metacp reference page for a description of metacp error messages.

None.

meta initialize -file tracefile.log -tracelevel 2 -maxentries 10

addentry, modifydn, modifyentry, removeentries, terminate, writetrace

Section Synchronization Profile (Chapter 1, DirX Identity Connectivity Administration Guide)

Chapter 2, "Synchronization Templates", DirX Identity Connectivity Administration Guide

Modifies an entry’s name in the Identity store (a connected directory of type LDAP). The syntax is as follows:

[meta] modifydn
    -entry entry_handle

The modifydn operation modifies the distinguished name of the entry associated with entry_handle in the Identity store (a connected directory of type LDAP). The operation uses the following attributes of the Tcl variable array associated with entry_handle:

The modifydn operation changes the last RDN of an entry in the connected directory. The entry_handle(del_old_rdn) attribute controls whether or not the old RDN value should be preserved in the directory entry. If present, the entry_handle(new_sup) attribute directs modifydn to move the entry (or subtree) into a different subtree of the DIT. The pseudo attributes new_rdn, del_old_rdn, and new_sup must be selected with the -attribute option in the openconn operation.

If the underlying connection handle (derived from entry_handle) is an LDAP directory with the parameter -ldifhandle set, then the modifydn is not applied to the LDAP directory; instead an LDIF-CHANGE operation is created in the LDIF-CHANGE file associated with -ldifhandle parameter.

metacp automatically propagates a JMS message (containing the SPML add request) if at the beginning of a synchronization scenario ats initialize has been called with the options -topicprefix, -type, -cluster, and -resource. (See ats initialize for details.)

Check the Tcl variable errorCode for error details. If this variable is not set or its value is empty, the entry was successfully renamed. Otherwise, the error is logged in the trace file and the distinguished name was not modified.

gethandle, initialize, openconn, openldif, ats initialize

Attribute Configuration File Format (Chapter 2)

Updates the contents of an entry in the Identity store (a connected directory of type LDAP). The syntax is as follows:

[meta] modifyentry
    -newentry entry_handle
    [-oldentry entry_handle]
    [-tag tag]
    [-allowrename rename_flag]
    [-updateinfo update_flag]
    [-updateattr attribute_list]

The modifyentry operation updates the contents of an entry with the contents of the entry specified by -newentry entry_handle.

The modifyentry operation compares the new entry to the old entry, evaluates the connection handle for any synchronization flags set on the attributes to be processed, and generates the operations that are necessary to convert the contents of the old entry to the contents of the new entry (adding, replacing, and deleting the entry attributes, depending on the sync flags set with the -attribute option in the openconn operation).

Use the -oldentry option to identify the entry that is to be updated with the contents of the entry specified with the -newentry option. You do not need to specify -oldentry if -newentry entry_handle refers to an LDIF change file entry with the modify changetype. In this case, the entry handle contains the information about the entry that is to be modified. But in case you do provide an oldentry entry_handle for LDIF change files, only changes that still can be applied to the directory entry will be processed. Changes that cant be applied (e.g. removal of an attribute telephone number even if telephone number doesn’t exist) will be ignored.

The Tcl variable arrays associated with both -oldentry entry_handle and -newentry entry_handle must contain the entry’s distinguished name in the DDN attribute.

Use the -tag option to mark a modified entry as "processed" by a modifyentry operation. The removeentries operation uses the tag to determine which entries to remove.

Use the -allowrename option to control whether metacp modifies the DDN attribute of an entry when it updates its other attributes. When this option is set to FALSE (or is not used), the distinguished name in the DDN attribute of the entry that contains the update information must match the distinguished name in the DDN attribute of the entry to be updated.

Use the -updateinfo option to control the modifyentry return values. Specify NONE to return the values 0 (modification of the entry was successful) or 1 (modification of the entry failed). Specify SIMPLE to return the values 0 (success) 1 (failure) or 2 (no operation because the entry was already up-to-date). The extended return values (0,1,2) allow you to use the modifyentry function in more complex ways within your synchronization profiles.

If the underlying connection handle (derived from entry_handle) is an LDAP directory with the parameter -ldifhandle set, then the modifyentry is not applied to the LDAP directory; instead an LDIF-CHANGE operation is created in the LDIF-CHANGE file associated with -ldifhandle parameter.

metacp automatically propagates a JMS message (containing the SPML add request) if at the beginning of a synchronization scenario ats initialize has been called with the options -topicprefix, -type, -cluster, and -resource. (See ats initialize for details.)

Check the Tcl variable errorCode for error details. If this variable is not set or its value is empty, the entry was successfully modified and/or renamed. Otherwise, the error is logged in the trace file and the entry was not modified.

findentry, gethandle, getentry, initialize, openconn, openldif, removeentries, ats initialize

Opens a connected directory for synchronization. The syntax is as follows:

[meta] openconn
    -type directory_type
    [-file filename -mode file_open_mode
    [-format file_format] [encoding encoding]]
    [-attribute attribute_list [-processallattr]]
    -attrconf attr_conf_handle
    -conn connection_handle
    [-bindid binding_id]
    [-ldifhandle LDIF_file_handle]

The openconn operation opens a connected directory for synchronization, creates a connection handle for it, and assigns it the name specified in the -conn option. The connection handle points to an import file, an export file, an LDAP connection to a directory, depending on the -type option specified in the command line. If a LDAP connection to a directory is being opened, the synchronization profile must perform an obj bind operation with suitable protocol (LDAPv2 or LDAPv3) before the openconn operation. The meta controller does not check for the bind in the openconn operation itself; but it does check in the addentry, modifyentry, modifydn, removeentries operations (which operate on handles containing a nested connection handle) and in obj search (with connection handle specified).

When multiple binds are open to different LDAP directories, you can use the -bindid option to associate the connection handle with a specific bind. The binding_id argument to this option specifies binding ID assigned to the bind during the obj bind operation. If the -bindingid option is not used, the openconn operation associates the connection handle with the default bind.

Use the -attribute option to select specific attributes for synchronization from the connected directory’s attribute configuration file. The selected set becomes the set of synchronized attributes (SSA). Use the sync_flag argument (for connected directories of type LDAP only) to specify the operations that are allowed during synchronization on each attribute in the subset specified in the -attribute option. The sync_flag keywords have the following effects on the synchronization of attribute values:

Valid combinations of sync_flag are:

Use the -processallattr option to synchronize all of the connected directory’s attributes (when the -type option is LDAP). You can use this option in conjunction with the -attribute option to select certain attributes and assign special processing to them.

When the -type option is LDAP, the -attributes option must specify all of the naming attributes used in the connected directory, unless the -processallattr option is specified.

The connection handle created by openconn defines the set of attributes to be synchronized (SSA). This set is either the same as the set of attributes to be synchronized that is specified in the attribute configuration file (if the -attribute option is not specified, or if -processallattr is specified) or it is a subset of the SSAs specified in the attribute configuration file (if the -attribute option is specified).

None.

getentry, gethandle, openldif, readattrconf, obj bind obj search

Creates an LDIF-CHANGE file. The syntax is as follows:

[meta] openldif
    -file filename
    -ldifhandle LDIF_file_handle

The openldif operation opens the given file (as output file containg LDIF-CHANGE records) and associates that file with the given LDIF_file_handle. That handle can later on be used in meta openconn.

None.

addentry, modifydn, modifyentry, openconn, removeentries

Returns a list of operations that can be performed on the meta object. The syntax is as follows:

meta operations

The list of available operations is in alphabetical order except for help and operations, which are listed last.

The requested information.

The output of the sample command is as follows:

Reads an attribute configuration file. The syntax is as follows:

[meta] readattrconf
    -file filename
    -attrconf attr_conf_handle
    [-encoding encoding]

The readattrconf operation reads an attribute configuration file into the metacp workspace, creates a handle to it, and assigns it the name specified in the -attrconf option. An attribute configuration file defines the attributes that are present in a particular connected directory and supplies formatting information that metacp is to use when processing data files associated with the connected directory.

A synchronization profile generally contains two readattrconf operations: one to read the attribute configuration file associated with the source directory, and one to read the attribute configuration file of the target directory.

None.

meta readattrconf -file /homes/metadir/conf/mail/exchgattr.cfg \
-attrconf exchg_ah

openconn

Attribute Configuration File Format (Chapter 2)

Releases a meta handle. The syntax is as follows:

[meta] releasehandle handle

The releasehandle operation releases the meta handle specified in handle. See the handle argument description in this chapter for a list of meta handle types.

A meta handle’s context can be dependent on the context of another meta handle. For example, the entry handle context returned by a meta findentry operation is dependent on the context of a result handle returned by an obj search operation. In the case of handles with dependencies, you can only release a handle after you have first released all of its dependent handles. For example, you must release an entry handle before you can release the result handle on which it is dependent. Similarly, you must release a connection handle before you can release the attribute configuration file handle on which the connection handle is dependent. See the handle argument description for the list of handle dependencies.

None.

Removes an entry or removes entries in a sorted search results list from the Identity store (a connected directory of type LDAP). The syntax is as follows:

[meta] removeentries
    -handle handle
    [-tag tag]

The removeentries operation removes an entry specified by an entry handle or the entries in a results list specified by a result handle from the Identity store (a connected directory of type LDAP).

If the -handle option specifies a result handle to a search results list, use the MARKED keyword in the -tag option to remove all entries from the Identity store (a connected directory of type LDAP) that the meta modifyentry or meta findentry operations have marked as "processed" in the results list. Use the NOTMARKED keyword to remove all entries that have not been marked by meta modifyentry or meta findentry.

The meta controller will not remove an entry for which it has information that the entry has subordinates. The meta controller will have this information for an entry in two cases:

If the underlying connection handle (derived from entry_handle) is an LDAP directory with the parameter -ldifhandle set, then the removeentries is not applied to the LDAP directory; instead an LDIF-CHANGE operation is created in the LDIF-CHANGE file associated with -ldifhandle parameter.

metacp automatically propagates a JMS message (containing the SPML add request) if at the beginning of a synchronization scenario ats initialize has been called with the options -topicprefix, -type, -cluster, and -resource. (See ats initialize for details.)

Check the Tcl variable errorCode for error details. If this variable is not set or its value is empty, the entry (or all of the entries from the result list) was successfully removed. Otherwise the error is logged in the trace file and the entry (or entries) was not removed.

getentry, initialize, modifyentry, obj search, openconn, openldif, ats initialize

Sorts the entries in an index list. The syntax is as follows:

[meta] sortindexlist -handle index_list_handle
    [-keepnames index_list_access_flag]

The sortindexlist operation sorts the entries in the index list specified by the -handle option. The operation sorts the entries by distinguished name in alphabetical (ascending) order. Use the sortindexlist operation in conjunction with the meta createindexlist, meta getentry, and meta writeindexlist operations to create a sorted list (by distinguished name) of entries. Note that an index list can be sorted only once.

Use the -keepnames option to control whether the distinguished names specified in the -name option of previous meta writeindexlist operations can be used as indexes into the sorted index list, or whether only sequential access can be performed.

None.

getentry, createindexlist, writeindexlist

Sorts the results of a read or search operation. The syntax is as follows:

[meta] sortresult
    -result result_handle
    -order sort_order
    [-key sort_key]

-result result_handle

A required option that specifies a handle to a search results list. Specify the name of a result handle created by an obj search operation.

The sortresult operation sorts the entries in the search result specified by the -result option, updates the result data structure with information about how the result has been sorted, and returns a handle to the sorted result.

Use the -key option to sort the results list by distinguished name or by any other attribute type.

None.

Supplies attribute information for creating a superior entry in the Identity store (a connected directory of type LDAP). The syntax is as follows:

[meta] supinfo
    -rdn attribute_type
    {-attribute attribute_value | -remove}
    [-bindid binding_id]

The supinfo operation defines attribute information for the creation of superior entries in the Identity store. When it creates an entry in the Identity store (a connected directory of type LDAP), the meta addentry operation uses this information to create any required superior entries for the entry, if these superior entries do not already exist in the Identity store (a connected directory of type LDAP).

Use the -attribute option to specify the attributes to be applied to the superior entry. You must specify the ObjectClass (OCL for DAP connections, objectClass for LDAP connections) attribute as an attribute_list element; specifying additional attributes depends upon the object class (you must supply the mandatory attributes for the object class).

Use the -remove option to remove an attribute definition previously specified with supinfo.

When multiple binds are open to different LDAP directories, you can use the -bindid option to direct the supinfo operation to be applied to a specific bind. The binding_id argument to this option specifies the binding ID assigned to the bind during the obj bind operation. In this way, you can establish different sets of superior information, and then apply them to the appropriate connected directory. If the -bindid option is not used, the supinfo operation carries out the operation on the default bind.

Since there is no syntax checking, supinfo <→ openconn or supinfo <→ bind can be performed in any order. It is the responsibility of the user to keep supinfo/openconn/bind consistent for each bind ID.

addentry

Closes the metacp trace file and cleans up the metacp workspace. The syntax is as follows:

[meta] terminate

The terminate operation writes statistics to the trace file opened with the meta initialize operation (if -nostatistics not set) and closes it. Here is an example of the type of statistics written to the trace file:

Explanations:

If in meta initialize the parameter -nostatistics is set, the statistic information as listed above is not written to the tracefile.

In that case, the user is advised to integrate statistic information in his synchronization scripts. Before calling terminate, it’s his task to print this information using meta writetext.

None.

meta terminate

initialize, writetext

Unescapes one or more characters in a string. The syntax is as follows:

[meta] unescapechar string

The unescapechar operation "unescapes" one or more characters in a string by removing the backslash (\) prefix (previously inserted with meta escapechar or returned by an obj search operation). and returns the unescaped string as a result.

The unescaped string.

The unescapechar operation

returns the string f{1}=2

escapechar

Writes information about an entry into an index list. The syntax is as follows:

[meta] writeindexlist
    -handle index_list_handle
    -name distinguished_name
    -entry entry_handle

The writeindexlist operation writes an entry’s distinguished name and the entry handle into the index list specified in the -handle option. Obtain the distinguished name either from the Tcl variable created by meta getentry (if the distinguished name is stored in the entry) or from a Tcl mapping operation. Use the writeindexlist operation in conjunction with the meta createindexlist, meta getentry, and meta sortindexlist operations to create a sorted list (by distinguished name) of entries from a connected directory of type FILE for directory synchronization processing.

A writeindexlist operation cannot be performed on an index list that has already been sorted with the sortindexlist operation.

getentry, createindexlist, sortindexlist

Writes the contents of an entry into a connected directory. The syntax is as follows:

[meta] writerecord
    -entry entry_handle

The writerecord operation writes the contents of the entry associated with entry_handle into the connected directory of type FILE inherited by entry_handle. The data format generated depends on the -format option specified in the openconn operation (TAGGED or NON-TAGGED) and the syntax specified in the attribute configuration file.

gethandle, openconn, writetext

Attribute Configuration File Format (Chapter 2)

Writes text to a connected directory of type FILE that has been opened for WRITE or APPEND. The syntax is as follows:

[meta] writetext
    -conn connection_handle
    -text string
    [-nonewline flag]

The writetext operation writes the text string specified in the -text option to the output data file represented by the connection handle specified in the -conn option. Use the writetext operation to write headers, trailers and other text into a data file that contains entry information.

gethandle, openconn

Writes a trace message into the metacp trace file. The syntax is as follows:

[meta] writetrace
    -text string
    [-handle handle]

-handle handle The name of an entry handle or a result handle that holds additional information to be traced. To trace an entry handle, specify the name of an entry handle created by a meta getentry or a meta gethandle operation. To trace a result handle, specify the name of a result handle created by an obj search operation.

The writetrace operation writes the message specified in the -text option into the trace file created and opened by the meta initialize operation. Use the -handle option to trace the current entry in a connected directory or to trace the contents of a search results list. Use the meta initialize -maxentries option to set a limit on the number of entries to trace in a search results list.

getentry, gethandle, initialize, obj search