$LDAPACS (access directory)
$LDAPACS provides authentication of connections to directory services, searching, entry acquisition, attribute acquisition, and other services that enable access to directory information. To use this embedded function for manipulating directory information, you must learn the methods and functions for accessing directory information.
- Organization of this page
Syntax
$LDAPACS(function-name,argument-1(,argument-2(,...)))
Values
-
function-name
Specifies the name of a function, either as a constant or a variable. A constant must be enclosed in single quotation marks ('').
-
argument
Specifies an argument for the function, either as a constant or a variable. A constant must be enclosed in single quotation marks ('').
Remarks
If information acquisition fails, a 0-byte character string is returned.
Detailed descriptions of functions that can be used to access directory information
The following table lists and describes the functions that can be used by the $LDAPACS embedded function.
Function name |
Description |
---|---|
CONNECT |
Authenticates connection to directory service. |
CONVERT |
Converts data to a character string used in searching directory information. |
DISCONNECT |
Releases a connection to directory service. |
FIRSTENTRY |
Acquires the first entry that was found. |
FREEENTRY |
Releases an entry. |
FREERESULT |
Releases a search result. |
GETDN |
Acquires an entry DN. |
NEXTENTRY |
Acquires the second and subsequent entries that were found. |
SEARCH |
Searches directory service. |
SELECTVALUE |
Acquires an attribute value. |
The following subsections provide a description of each of these functions, along with their syntax, arguments, and statuses. Status differs depending on the status acquired with the $GETSTATUS embedded function.
■ CONNECT
CONNECT authenticates connection to directory service, and returns a directory object.
- Syntax
$LDAPACS('CONNECT',LDAPOBJ,HOST,PORT,USERDN,PASSWD)
- Arguments
-
Argument
Type
Description
LDAPOBJ
Directory object
Specifies the name of the variable into which the directory object is set.
HOST
Variable or constant
Specifies the host name or IP address of the directory server.
PORT
Variable or constant
Specifies the port number of the directory server.
USERDN
Variable or constant
Specifies the user DN for authenticating a connection.
PASSWD
Variable or constant
Specifies the password for authenticating a connection.
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
—
ERROR
Invalid argument.
Script execution interrupted
Indicates one of the following:
-
An error occurred when an attempt was made to connect to the directory.
-
An authentication error occurred.
-
An error other than the above occurred.
-
■ CONVERT
CONVERT converts data to a character string for use in searching the directory service.
- Syntax
return-value=$LDAPACS('CONVERT',SOURCE)
-
return-value
Specifies the name of the variable into which the converted character string is set.
-
- Arguments
-
Argument
Type
Description
SOURCE
Variable or constant
Specifies the character string to be converted.
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
—
ERROR
Indicates one of the following:
-
Conversion failure.
-
Invalid argument.
Script execution interrupted
Indicates one of the following:
-
A variable is not defined.
-
An error other than the above occurred.
-
■ DISCONNECT
DISCONNECT releases the directory service connection and all objects under it.
- Syntax
$LDAPACS('DISCONNECT',LDAPOBJ)
- Argument
-
Argument
Type
Description
LDAPOBJ
Directory object
Specifies the directory object requested by CONNECT.
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
—
ERROR
LDAPOBJ does not match the directory object requested by CONNECT.
Script execution interrupted
Indicates one of the following:
-
A variable is not defined.
-
An error other than the above occurred.
-
■ FIRSTENTRY
FIRSTENTRY acquires the first entry object found from the search object. To release an acquired object, you must call FREEENTRY.
- Syntax
$LDAPACS('FIRSTENTRY',LDAPENT,LDAPRST)
- Arguments
-
Argument
Type
Description
LDAPENT
Entry object
Specifies the name of the variable into which the entry object is set.
LDAPRST
Result object
Specifies the result object.
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
No entry exists.
ERROR
Indicates one of the following:
-
LDAPRST does not match the search object requested by SEARCH.
-
Invalid argument.
Script execution interrupted
An error other than the above occurred.
-
■ FREEENTRY
FREEENTRY releases the specified entry object and all objects under it.
- Syntax
$LDAPACS('FREEENTRY',LDAPENT)
- Argument
-
Argument
Type
Description
LDAPENT
Entry object
Specifies an entry object.
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
—
ERROR
Indicates one of the following:
-
LDAPENT does not match the entry object requested by FIRSTENTRY or NEXTENTRY.
-
Invalid argument.
Script execution interrupted
An error other than the above occurred.
-
■ FREERESULT
FREERESULT releases the specified result object and all objects under it.
- Syntax
$LDAPACS('FREERESULT',LDAPRST)
- Argument
-
Argument
Type
Description
LDAPRST
Result object
Specifies a result object.
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
—
ERROR
Indicates one of the following:
-
LDAPRST does not match the search object requested by SEARCH.
-
Invalid argument.
Script execution interrupted
An error other than the above occurred.
-
■ GETDN
GETDN acquires the indicator (character string) from the entry object. The acquired character string cannot be released. You must use FREEENTRY to release its higher object.
- Syntax
$LDAPACS('GETDN',LDAPDN,LDAPENT)
- Arguments
-
Argument
Type
Description
LDAPDN
DN
Specifies the name of the variable into which the DN is set.
LDAPENT
Entry object
Specifies the entry object.
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
—
ERROR
Indicates one of the following:
-
LDAPENT does not match the entry object requested by FIRSTENTRY or NEXTENTRY.
-
Invalid argument.
Script execution interrupted
An error other than the above occurred.
-
■ NEXTENTRY
NEXTENTRY acquires the second and subsequent entry objects found in the result object. This function cannot be called without first calling FIRSTENTRY. To release the acquired object, you must call FREEENTRY.
- Syntax
$LDAPACS('NEXTENTRY',LDAPENT,LDAPRST)
- Arguments
-
Argument
Type
Description
LDAPENT
Entry object
Specifies the name of the variable into which the entry object is set.
LDAPRST
Result object
Specifies the result object.
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
—
ERROR
Indicates one of the following:
-
LDAPRST does not match the result object requested by SEARCH.
-
Invalid argument.
Script execution interrupted
An error other than the above occurred.
-
■ SEARCH
SEARCH performs a synchronous search on the LDAP server.
To release the result object, you must call FREERESULT to release its higher object.
- Syntax
$LDAPACS('SEARCH',LDAPRST,LDAPOBJ,BASE,FILTER,SCOPE)
- Arguments
-
Argument
Type
Description
LDAPRST
Result object
Specifies the variable name into which the result object is set.
LDAPOBJ
Directory object
Specifies the directory object acquired by CONNECT.
BASE
Variable or constant
Specifies the base object from which the search starts.
FILTER
Variable or constant
Specifies the search filter.
SCOPE
Variable or constant
Referenced to the base object, specifies to search one of the following directory information levels:
-
LDAP_SCOPE_SUBTREE (Search all objects under the base object)
-
LDAP_SCOPE_ONELEVEL (Search objects directly below the base object)
-
LDAP_SCOPE_BASE (Search the base object)
-
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
No matching data exists.
ERROR
Invalid argument.
Script execution interrupted
An error other than the above occurred.
■ SELECTVALUE
SELECTVALUE specifies an attribute name from an entry object, and acquires the value of the first attribute (character string).
The acquired character string cannot be released. You must use FREEENTRY to release its higher object.
- Syntax
$LDAPACS('SELECTVALUE',LDAPSEL,LDAPENT,KEYNAME)
- Arguments
-
Argument
Type
Description
LDAPSEL
Attribute value
Specifies the name of the variable into which the attribute value (character string) is set.
LDAPENT
Entry object
Specifies the entry object.
KEYNAME
Variable or constant
Specifies the name of the attribute you wish to acquire.
- Status
-
The following table lists and describes the possible statuses:
Status
Description
NORMAL
Normal end
NODATA
No value exists for the specified attribute.
ERROR
Indicates one of the following:
-
LDAPENT does not match the entry object requested by FIRSTENTRY or NEXTENTRY.
-
Invalid argument.
Script execution interrupted
An error other than the above occurred.
-
Example
The following example outputs the DN and name of the user whose attribute title;lang-ja is Supervisor, from users who are registered to the directory ou=people,o=xxxxxxx.co.us:
[VAR] STATUS MSG HOST PORT FILTER BASE SCOPE FIRST LDOBJ LDRST LDENT DN NAME [SET_VALUE] HOST = 'localhost' PORT = '389' BASE = 'ou=people,o=xxxxxxx.co.us' SCOPE= 'LDAP_SCOPE_ONELEVEL' [SET_VALUE] $LDAPACS('CONNECT',LDOBJ,HOST,PORT,'','') # CONNECT STATUS = $GETSTATUS() [SET_VALUE] FILTER = '(&(objectclass=*)(title;lang-ja=' FILTER = FILTER+$LDAPACS('CONVERT','Supervisor') # CONVERT FILTER = FILTER+'))' # FILTER=(&(objectclass=*)(title;lang-ja=\E4\B8\BB\E4\BB\BB)) $LDAPACS('SEARCH',LDRST,LDOBJ,BASE,FILTER,SCOPE) # SEARCH FIRST = 1 [DO] [IF] FIRST = 1 [THEN] [SET_VALUE] $LDAPACS('FIRSTENTRY',LDENT,LDRST) # GET FIRST ENTRY STATUS = $GETSTATUS() FIRST = 0 [ELSE] [SET_VALUE] $LDAPACS('NEXTENTRY',LDENT,LDRST) # GET NEXT ENTRY STATUS = $GETSTATUS() [IF_END] [IF] STATUS = NORMAL [THEN] [SET_VALUE] $LDAPACS('GETDN',DN,LDENT) # GET DN $LDAPACS('SELECTVALUE',NAME,LDENT,'cn') # GET VALUE OF CN MSG='DN ['+DN+'] is '+NAME $ECHO(MSG) $LDAPACS('FREEENTRY',LDENT) # FREE ENTRY OBJECT [ELSE] [SET_VALUE] $BREAK() [IF_END] [DO_END] [SET_VALUE] $LDAPACS('FREERESULT',LDRST) # FREE SEARCH OBJECT [SET_VALUE] $LDAPACS('DISCONNECT',LDOBJ) # FREE LDAP OBJECT
- Execution result:
-
DN [uid=user1, ou=people, o=xxxxxxx.co.us] is Smith
DN [uid=user3, ou=people, o=xxxxxxx.co.us] is Brown