JP1 Version 12 JP1/IT Desktop Management 2 - Asset Console Creating an Access Definition File Guide

Previous
90 / 127
Next

Cover
5. Embedded Functions Used in Access Definition Files
$LDAPACS (access directory)

$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
Values
Remarks
Detailed descriptions of functions that can be used to access directory information
■ CONNECT
■ CONVERT
■ DISCONNECT
■ FIRSTENTRY
■ FREEENTRY
■ FREERESULT
■ GETDN
■ NEXTENTRY
■ SEARCH
■ SELECTVALUE
Example

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.

Table 5‒3: List of 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.

Legend:: —: Not applicable

■ 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.

Legend:: —: Not applicable

■ 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.

Legend:: —: Not applicable

■ 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.

Legend:: —: Not applicable

■ 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.

Legend:: —: Not applicable

■ 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.

Legend:: —: Not applicable

■ 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.

Legend:: —: Not applicable

■ 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

Previous
90 / 127
Next

Copyright (C) 2019, 2020, Hitachi, Ltd.

Copyright (C) 2019, 2020, Hitachi Solutions, Ltd.

Copyright, patent, trademark, and other intellectual property rights related to the "TMEng.dll" file are owned exclusively by Trend Micro Incorporated.