External Commands Reference

This chapter documents the external commands provided by the LDAP software.

LDAP Commands

Please note: where constant names are given, these must be specified as text. Classic style externals have no means of providing constants for the use with Omnis.

 

LDAP ADD ATT (Collection,Name,Value)

LDAP ADD ATT adds an attribute and its value to an attribute collection. Attribute collections are used for the attribute parameters in the LDAP ADD EXT S and LDAP MODIFY EXT S functions.

Collection (Char)    Specifies the collection.

Name (Char)    Specifies the name.

Value (Char)    Specifies the value.

Returns    The updated collection is returned.

See also LDAP ADD EXT S, LDAP MODIFY EXT S, LDAP SET ATT, LDAP GET ATT, LDAP GET ATT ARRAY ITEM

 

LDAP ADD EXT S (Session,DN,Attributes,ServerControls,ClientControls)

Synchronously adds an entry to the directory using LDAP client or server controls.

Session (Char)    Specifies the session (as returned by LDAP INIT).

DN (Char)    Specifies the distinguished name of the entry to add, for example "cn=kim".

Attributes (Char)    A collection of attributes and values to add with the entry. See LDAP ADD ATT.

ServCtrls (Char)    Reference to server controls. Specify an empty string if no server controls.

ClientCtrls (Char)    Reference to client controls. Specify an empty string if no client controls.

Returns    See LDAP Error Codes.

See also LDAP DELETE EXT S, LDAP MODIFY EXT S, LDAP ADD ATT

 

LDAP AVAILABLE ()

LDAP AVAILABLE returns a boolean state indicating whether the LDAP functions are available. If this returns kFalse then please refer to the installation instructions.

See also LDAP INIT

 

LDAP COMPARE S (Session,DN,Attributes,Value)

Synchronously determines whether a specified entry contains a specified attribute value.

Session (Char)    Specifies the session (as returned by LDAP INIT).

DN (Char)    Specifies the distinguished name of the entry to compare.

Attributes (Char)    Specifies the name of the attribute to compare.

Value (Char)    Specifies the string value of the attribute to compare.

Returns     0 (True), 1(False),2 (no such attribute), 3(No such object). If other value then see LDAP Error Codes.

 

LDAP COUNT ENTRIES (Session,Search Reference)

Counts the number of entries in the search.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the result chain as returned by LDAP RESULT or by a synchronous search function.

Returns     the number of LDAP messages that are of type LDAP_RES_SEARCH_ENTRY.

See also LDAP RESULT, LDAP SEARCH EXT S

 

LDAP COUNT MESSAGES (Session, Search Reference)

Counts the number of messages in the search.

Character Session    Specifies the session (as returned by LDAP INIT).

Character Reference    Reference to the result chain as returned by LDAP RESULT or by a synchronous search function.

Returns     the number of LDAP messages that are of any type.

See also LDAP RESULT, LDAP SEARCH EXT S

 

LDAP COUNT REFERENCES (Session, Search Reference)

Counts the number of references in the search.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the result chain as returned by LDAP RESULT or by a synchronous search function.

Returns     the number of LDAP messages that are of type LDAP_RES_SEARCH_REFERENCE.

See also LDAP RESULT, LDAP SEARCH EXT S

 

LDAP CREATE PERSISTENT SEARCH CONT (Session,Type,ChangesOnly,ReturnEntryChanges,IsCritical,Control)

Creates and encodes a persistent search control. The control can then be used in LDAP SEARCH EXT

Session (Char)    Specifies the session (as returned by LDAP INIT).

Type (Int)    Integer specifying changes (can be or'd). ADD(Value 1), DELETE (2), MODIFY (4), MODDN(8), ANY(15).

ChangesOnly (Bool)    If true, the initial search is only used to establish a result set on the server. No results are returned from this initial search.

RtnEntryChge (Bool)    If true, a entry change notification control is included with each entry. If 0, entry change notification controls are not included with the entries returned from the server.

IsCritical (Bool)    If true, the control is critical to the search operation. If the server does not support persistent searches, the server will return the error LDAP_UNAVAILABLE_CRITICAL_EXTENSION.

    If false, the control is not critical to the search operation. Even if the server does not support persistent searches, the search operation is still performed.

Control (Char)    Returned reference to the control which is created. When you are finished with this control, you must free the reference.   

Returns    See LDAP Error Codes.

See also LDAP SEARCH EXT

 

LDAP DELETE EXT S (Session,DN[,ServerControls, UserControls])

Synchronously deletes the specified entry using LDAP client or server controls.

Session (Char)    Specifies the session (as returned by LDAP INIT).

DN (Char)    Specifies the distinguished name of the entry to delete.

ServCtrls (Char)    Reference to the server controls. May be empty if no server controls.

UserCtrls (Char)    Reference to the user controls. May be empty if no user controls.

Returns    See LDAP Error Codes.

See also LDAP ADD EXT S, LDAP MODIFY EXT S

 

LDAP FIRST ATTRIBUTE (Session,Reference,BerElement Reference)

This returns the name of the first attribute in an entry.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the entry whose attributes are being read.

BerRef (Char)    Reference to the BerElement. Can be used in further LDAP NEXT ATTRIBUTE calls. This reference must be freed by using LDAP FREE.

Returns     the name of the first attribute in an entry.

See also LDAP NEXT ATTRIBUTE

 

LDAP FIRST ENTRY (Session,Search reference)

This returns the first entry of message type, LDAP_RES_SEARCH_ENTRY from a search result chain.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the result chain as returned by LDAP RESULT or by a synchronous search function.

Returns     character reference to the next entry in the chain or empty if no more entries or failure.

See also LDAP NEXT ENTRY

 

LDAP FIRST MESSAGE (Session, Reference)

This returns the first message in the result chain.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the result chain as returned by LDAP RESULT or by a synchronous search function.

Returns     a character reference to the first message in the chain, or empty if no more messages or failure. This may be of type LDAP_RES_SEARCH_ENTRY, LDAP_RES_SEARCH_RESULT or LDAP_RES_SEARCH_REFERENCE.

See also LDAP NEXT MESSAGE

 

LDAP FREE (Reference)

Free a Ber, Control or Search reference. This must be called after the reference is no longer required.

Reference (Char)    The reference to release.

No return

 

LDAP GET ATT (Collection,Name)

LDAP GET ATT returns the value of the attribute from an attribute collection. Attribute collections are used for the attribute parameters in the LDAP ADD EXT S and LDAP MODIFY EXT S functions.

Collection (Char)    Specifies the collection.

Name (Char)    Specifies the attribute name.

Returns    The attribute’s value.

See also LDAP ADD EXT S, LDAP MODIFY EXT S, LDAP SET ATT, LDAP ADD ATT, LDAP GET ATT ARRAY ITEM

 

LDAP GET ATT ARRAY ITEM (Collection,Name,Index)

LDAP GET ATT ARRAY ITEM returns the value of the nth attribute from an attribute collection. It is possible for a collection to contain more than one value for the same attribute. When this is the case, you use this command to retrieve the individual values of the same attribute. If the index is out of range, an empty value is returned. Attribute collections are used for the attribute parameters in the LDAP ADD EXT S and LDAP MODIFY EXT S functions.

Collection (Char)    Specifies the collection.

Name (Char)    Specifies the name.

Index (Int)    Specifies the index (from 1).

Returns    The updated collection is returned.

See also LDAP ADD EXT S, LDAP MODIFY EXT S, LDAP SET ATT, LDAP GET ATT, LDAP ADD ATT

 

LDAP GET DN (Session,Reference)

Obtains the distinguished name of an entry from a search result chain.

Session (Char)    Specifies the session (as returned by LDAP INIT.

Reference (Char)    Reference to the chain as returned by LDAP FIRST ENTRY or LDAP NEXT ENTRY.

Returns     name of the entry, or empty if failure.

See also LDAP FIRST ENTRY, LDAP NEXT ENTRY

 

LDAP GET OPTION (Session,Option)

LDAP get Option gets the value of the session-wide parameters.

Session (Char)    Specifies the session (as returned from LDAP INIT). This may be empty to get the global defaults.

Option (Char)    Option which may be one of the following:

LDAP_OPT_API_INFO

LDAP_OPT_DESC

LDAP_OPT_REFERRALS

LDAP_OPT_RESTART

LDAP_OPT_PROTOCOL_VERSION

LDAP_OPT_SERVER_CONTROLS

LDAP_OPT_CLIENT_CONTROLS

LDAP_OPT_API_FEATURE_INFO

LDAP_OPT_HOST_NAME

LDAP_OPT_RESULT_CODE

LDAP_OPT_ERROR_NUMBER

LDAP_OPT_ERROR_STRING

LDAP_OPT_MATCHED_DN

LDAP_OPT_DEBUG_LEVEL

LDAP_OPT_TIMEOUT

LDAP_OPT_REFHOPLIMIT

LDAP_OPT_NETWORK_TIMEOUT

LDAP_OPT_URI

LDAP_OPT_REFERRAL_LIST

LDAP_OPT_IO_FUNCS

LDAP_OPT_SESSION_REFCNT

Returns    Character or Integer (depending on the option) specifying the current value.

See also LDAP SET OPTION

 

LDAP GET VALUES (Session,Entry Reference,Attribute)

Obtains the string value of a specified attribute from an entry.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the message chain as returned by LDAP FIRST ENTRY or LDAP NEXT ENTRY.

Attribute (Char)    The attribute as returned from LDAP FIRST ATTIBUTE, LDAP NEXT ATTRIBUTE or the name of an attribute.

Returns     a comma-separated list. For binary data, use LDAP GET VALUES LEN.

See also LDAP GET VALUES LEN

 

LDAP GET VALUES LEN (Session,Entry Reference,Attribute)

Obtains the binary value of a specified attribute from an entry.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the message chain as returned by LDAP FIRST ENTRY or LDAP NEXT ENTRY.

Attribute (Char)    The attribute as returned from LDAP FIRST ATTIBUTE, LDAP NEXT ATTRIBUTE or the name of an attribute.

Returns    binary value.

See also LDAP GET VALUES

 

LDAP INIT (Host,Port)

LDAP Init opens the specified port on the host and returns a character string indicating the LDAP reference (empty on failure). You must call LDAP USE UTF8 with the appropriate setting prior to calling this command.

Host (Char)    Specifies the host.

Port (Int)    Specifies the port.

Returns     a character reference to the LDAP connection.

See also LDAP USE UTF8, LDAP AVAILABLE, LDAP UNBIND S

 

LDAP MODIFY EXT S (Session,DN,Mods,ServerControls,ClientControls)

Synchronously modifies the specified attributes of an entry on an LDAP server, using LDAP client or server controls.

Session (Char)    Specifies the session (as returned by LDAP INIT).

DN (Char)    Specifies the distinguished name of the entry to modify, for example "cn=kim".

Mods (Char)    Collection of attributes and values.

ServCtrls (Char)    Reference to server controls. Specify an empty string if no server controls.

ClientCtrls (Char)    Reference to client controls. Specify an empty string if no client controls.

Returns    See LDAP Error Codes.

See also LDAP ADD EXT S, LDAP DELETE EXT S, LDAP ADD ATT

 

LDAP MSGID (Message Reference)

Obtains the ID of the message.

Reference (Char)    Reference to the message.

Returns    The message ID or -1 if failure.

 

LDAP MSGTYPE (Message Reference)

Obtains the type of message.

Reference (Char)    Reference to the message.

Returns    The message type or -1 if failure.

 

LDAP NEXT ATTRIBUTE (Session,Reference,BerElement Reference)

This returns the name of the next attribute in an entry.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the entry whose attributes are being read.

BerRef (Char)    Reference to the BerElement. Can be used in further LDAP NEXT ATTRIBUTE calls. This reference must be freed by using LDAP FREE.

Returns     the name of the next attribute in an entry, or empty if no more attributes.

See also LDAP FIRST ATTRIBUTE

 

LDAP NEXT ENTRY (Session,Reference)

This returns the next entry of message type, LDAP_RES_SEARCH_ENTRY from a search result chain.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the chain as returned by LDAP FIRST ENTRY.

Returns     character reference to the next entry in the chain or empty if no more entries or failure.

See also LDAP FIRST ENTRY

 

LDAP NEXT MESSAGE (Session, Message Reference)

This returns the next message in the result chain.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Reference (Char)    Reference to the message chain as returned by LDAP FIRST MESSAGE.

Returns     a character reference to the next message in the chain or empty if no more messages or failure. This may be of type LDAP_RES_SEARCH_ENTRY, LDAP_RES_SEARCH_RESULT or LDAP_RES_SEARCH_REFERENCE.

See also LDAP FIRST MESSAGE

 

LDAP PARSE REFERENCE (Session,Message,Referral,ServerControl,FreeRes)

Extracts URLs and controls from a Message of type LDAP_RES_SEARCH_REFERENCE

Session (Char)    Specifies the session (as returned by LDAP INIT).

Message (Char)    Specifies the message reference.

Referral (Char)    Returned comma-separated string containing alternative LDAP server URLs.

SerControls (Char)    Returned server control references. You must free this reference.

FreeRes (Bool)    Boolean specifying whether you wish to release the resources. If you specify kFalse then you must free the Message.

Returns    See LDAP Error Codes.

 

LDAP PARSE RESULT (Session,Message,ErrorCode,MatchString,ErrorMsg,Referral,ServerControl,FreeRes)

Session (Char)    Specifies the session (as returned by LDAP INIT).

Message (Char)    Specifies the message reference.

Error code (Int)    Returned error code of last LDAP operation.

MatchString (Char)    Returned character string specifying how much of the name in the request was recognized.

ErrorMsg (Char)    Returned character string of error message associated with error code.

Referral (Char)    Returned comma-separated string containing alternative LDAP server URLs.

SerControls (Char)    Returned server control references. You must free this reference.

FreeRes (Bool)    Boolean specifying whether you wish to release the resources. If you specify kFalse then you must free the Message.

Returns    See LDAP Error Codes.

 

LDAP RESULT (Session,MsgId,All[,Timeout])

Obtains results from a previous asynchronously initiated operation.

Session (Char)    Specifies the session (as returned by LDAP INIT).

MsgId (Char)    Specifies the message ID returned. Can be LDAP_RES_UNSOLICITED or LDAP_RES_ANY.

All (Char)    Specifies how many messages to be retrieved in a single call to LDAP RESULT. Can be a number or "LDAP_MSG_ONE", "LDAP_MSG_ALL" or "LDAP_MSG_RECEIVED".

Timeout (Int)    Specifies how long (in seconds) to wait for the results to be returned.

Returns     a character reference to the results of the search. If no results are returned this may be 0 (time out) or -1 ( error ). Free this reference when you are done with it.

See also LDAP COUNT ENTRIES, LDAP COUNT REFERENCES, LDAP COUNT MESSAGES

 

LDAP SEARCH EXT (Session,Base,Scope [,Filter,Attrs,ServerControls,UserControls,AttrsOnly,Timeout])

Asynchronously searches the directory using LDAP client or server controls.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Base (Char)    Specifies the distinguished name of the entry from which to start the search.

Scope (Char)    Specifies the scope of the search and can be "LDAP_SCOPE_BASE", "LDAP_SCOPE_ONELEVEL" or "LDAP_SCOPE_SUBTREE".

Filter (Char)    Filter string if none is specified then the default filter ("objectclass=*") is used.

ServerControls (Char)    Reference to server controls, if any.

UserControls (Char)    Reference to user controls, if any.

Attrs (Char)    Comma-separated list specifies which attributes to return.

AttrsOnly (Char)    Specifies whether to return both attributes & values (default) or only attributes.

Timeout (Int)    Specifies the time out in seconds. Default is 10 seconds.

Returns    -1 if failure otherwise the message id of the operation.

See also LDAP SEARCH EXT S

 

LDAP SEARCH EXT S (Session,Base,Scope [,Filter,Attrs,ServerControls,UserControls,AttrsOnly,Timeout])

Synchronously searches the directory using LDAP client or server controls.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Base (Char)    Specifies the distinguished name of the entry from which to start the search.

Scope (Char)    Specifies the scope of the search and can be "LDAP_SCOPE_BASE", "LDAP_SCOPE_ONELEVEL" or "LDAP_SCOPE_SUBTREE".

Filter (Char)    Filter string if none is specified then the default filter ("objectclass=*") is used.

ServerControls (Char)     Reference to server controls, if any.

UserControls (Char)    Reference to user controls, if any.

Attrs (Char)    Comma-separated list specifies which attributes to return.

AttrsOnly (Bool)    Specifies whether to return both attributes & values (default) or only attributes.

Timeout (Int)    Specifies the time out in seconds. Default is 10 seconds.

Returns     a character reference to the result messages if successful; empty if otherwise.

See also LDAP SEARCH EXT, LDAP COUNT ENTRIES, LDAP COUNT MESSAGES, LDAP COUNT REFERENCES

 

LDAP SET ATT (Collection,Name,Value)

LDAP SET ATT sets the value of an existing attribute in the attribute collection. Attribute collections are used for the attribute parameters in the LDAP ADD EXT S and LDAP MODIFY EXT S functions.

Collection (Char)    Specifies the collection.

Name (Char)    Name of the existing attribute.

Value (Char)    Specifies the new value.

Returns    The updated collection is returned.

See also LDAP ADD EXT S, LDAP MODIFY EXT S, LDAP ADD ATT, LDAP GET ATT, LDAP GET ATT ARRAY ITEM

 

LDAP SETDEBUG (DebugLevel)

Sets the debug level of the Omnis external. Useful if you need verbose output.

DebugLevel (Int)    Specifies the debug level (0 Is off). Debug messages are written to LDAP.LOG file.

No return.

 

LDAP SET OPTION (Session,Option,Value)

LDAP Set Option sets the value of the session-wide parameters.

Session (Character)    Specifies the session (as returned from LDAP INIT). This may be empty to set the global defaults.

Option (Character)    Option which may be one of the following:

LDAP_OPT_API_INFO

LDAP_OPT_DESC

LDAP_OPT_REFERRALS

LDAP_OPT_RESTART

LDAP_OPT_PROTOCOL_VERSION

LDAP_OPT_SERVER_CONTROLS

LDAP_OPT_CLIENT_CONTROLS

LDAP_OPT_API_FEATURE_INFO

LDAP_OPT_HOST_NAME

LDAP_OPT_RESULT_CODE

LDAP_OPT_ERROR_NUMBER

LDAP_OPT_ERROR_STRING

LDAP_OPT_MATCHED_DN

LDAP_OPT_DEBUG_LEVEL

LDAP_OPT_TIMEOUT

LDAP_OPT_REFHOPLIMIT

LDAP_OPT_NETWORK_TIMEOUT

LDAP_OPT_URI

LDAP_OPT_REFERRAL_LIST

LDAP_OPT_IO_FUNCS

LDAP_OPT_SESSION_REFCNT

Value (Char/Int)        The new value.

Returns        LDAP_SUCCESS(0) or -1 on failure.

See also LDAP GET OPTION

 

LDAP SIMPLE BIND S (Session[,LoginDN,Password])

Synchronously authenticates the specified client to the LDAP server using a distinguished name and password.

Session (Char)    Specifies the session (as returned by LDAP INIT).

LoginDN (Char)    Distinguished name of the entry who is authenticating. For an anonymous authentication, do not specify this parameter.

Password (Char)    Client's password. For anonymous authentication, do not specify this parameter.

Returns    See LDAP Error Codes.

See also LDAP INIT, LDAP UNBIND S

 

LDAP UNBIND S (Session)

Unbinds from the directory, closes the connection.

Session (Char)    Specifies the session (as returned by LDAP INIT).

Returns     LDAP error codes.

See also LDAP INIT, LDAP SIMPLE BIND S

 

LDAP USE UTF8 (Flag) new for v1.2

Tells the LDAP external to send UTF8 characters to the server and expect UTF8 characters from the server. You should always set this to true prior to connecting to a LDAP version 3 compliant server.

Flag (Boolean)    If true, enable UTF8.

Returns     LDAP error codes.

See also LDAP INIT

 

 

LDAP Error Codes

LDAP_SUCCESS    0

LDAP_OPERATIONS_ERROR    1

LDAP_PROTOCOL_ERROR    2

LDAP_TIMELIMIT_EXCEEDED    3

LDAP_SIZELIMIT_EXCEEDED    4

LDAP_COMPARE_FALSE    5

LDAP_COMPARE_TRUE    6

LDAP_AUTH_METHOD_NOT_SUPPORTED    7

LDAP_STRONG_AUTH_NOT_SUPPORTED    LDAP_AUTH_METHOD_NOT_SUPPORTED

LDAP_STRONG_AUTH_REQUIRED    8

LDAP_PARTIAL_RESULTS    9

LDAP_REFERRAL    10

LDAP_ADMINLIMIT_EXCEEDED    11

LDAP_UNAVAILABLE_CRITICAL_EXTENSION    12

LDAP_CONFIDENTIALITY_REQUIRED    13

LDAP_SASL_BIND_IN_PROGRESS    14   

LDAP_NO_SUCH_ATTRIBUTE    16

LDAP_UNDEFINED_TYPE    17

LDAP_INAPPROPRIATE_MATCHING    18

LDAP_CONSTRAINT_VIOLATION    19

LDAP_TYPE_OR_VALUE_EXISTS    20

LDAP_INVALID_SYNTAX    21

LDAP_NO_SUCH_OBJECT    32

LDAP_ALIAS_PROBLEM    33

LDAP_INVALID_DN_SYNTAX    34

LDAP_IS_LEAF    35

LDAP_ALIAS_DEREF_PROBLEM    36

LDAP_INAPPROPRIATE_AUTH    48

LDAP_INVALID_CREDENTIALS    49

LDAP_INSUFFICIENT_ACCESS    50

LDAP_BUSY    51

LDAP_UNAVAILABLE    52

LDAP_UNWILLING_TO_PERFORM    53

LDAP_LOOP_DETECT    54

LDAP_SORT_CONTROL_MISSING    60

LDAP_INDEX_RANGE_ERROR    61

LDAP_NAMING_VIOLATION    64

LDAP_OBJECT_CLASS_VIOLATION    65

LDAP_NOT_ALLOWED_ON_NONLEAF    66

LDAP_NOT_ALLOWED_ON_RDN    67

LDAP_ALREADY_EXISTS    68

LDAP_NO_OBJECT_CLASS_MODS    69

LDAP_RESULTS_TOO_LARGE    70

LDAP_AFFECTS_MULTIPLE_DSAS    71

LDAP_OTHER    80

LDAP_SERVER_DOWN    81

LDAP_LOCAL_ERROR    82

LDAP_ENCODING_ERROR    83

LDAP_DECODING_ERROR    84

LDAP_TIMEOUT    85

LDAP_AUTH_UNKNOWN    86

LDAP_FILTER_ERROR    87

LDAP_USER_CANCELLED    88

LDAP_PARAM_ERROR    89

LDAP_NO_MEMORY    90

LDAP_CONNECT_ERROR    91   

LDAP_NOT_SUPPORTED    92   

LDAP_CONTROL_NOT_FOUND    93

LDAP_NO_RESULTS_RETURNED    94

LDAP_MORE_RESULTS_TO_RETURN    95

LDAP_CLIENT_LOOP    96

LDAP_REFERRAL_LIMIT_EXCEEDED    97