|
HP OpenVMS Systems Documentation |
|
OpenVMS Utility Routines Manual
LBR$SET_MODULE
The LBR$SET_MODULE routine reads, and optionally updates, the module header associated with a given record's file address (RFA). FormatLBR$SET_MODULE library_index ,rfa [,bufdesc] [,buflen] [,updatedesc] RETURNS
Arguments
DescriptionIf you specify bufdesc, the LBR routine returns the module header into the buffer. If you specify buflen, the routine also returns the buffer's length. If you specify updatedesc, the routine updates the header information. Condition Values Returned
LBR$SET_MOVE
The LBR$SET_MOVE routine sets the record access of LBR subroutines to move mode. FormatLBR$SET_MOVE library_index RETURNS
Argument
DescriptionLibrarian record access may be set to move mode (the default, set by LBR$SET_MOVE) or locate mode. The setting affects the operation of the LBR$GET_RECORD routine. If move mode is set, LBR$GET_RECORD copies the requested record to the specified user buffer. For details, see the description of LBR$GET_RECORD. Condition Values Returned
Chapter 13
|
cn=Barbara Jensen, o=University of Michigan, c=US |
Operations are provided to authenticate, search for and retrieve
information, modify information, and add and delete entries from the
tree. The next sections give an overview of how the API is used and
provide detailed descriptions of the LDAP API calls that implement all
of these functions.
13.1.2 Overview of LDAP API Use
An application generally uses the C LDAP API in four simple steps.
Operations can be performed either synchronously or asynchronously. The names of the synchronous functions end in _s. For example, a synchronous search can be completed by calling ldap_search_s() . An asynchronous search can be initiated by calling ldap_search() . All synchronous functions return an indication of the outcome of the operation (for example, the constant LDAP_SUCCESS or some other error code). The asynchronous functions make available to the caller the message id of the operation initiated. This id can be used in subsequent calls to ldap_result() to obtain the result(s) of the operation. An asynchronous operation can be abandoned by calling ldap_abandon() or ldap_abandon_ext() .
Results and errors are returned in an opaque structure called LDAPMessage. Functions are provided to parse this structure, step through entries and attributes returned. Functions are also provided to interpret errors. Later sections of this chapter describe these functions in more detail.
LDAPv3 servers may return referrals to other servers. By default, implementations of this API will attempt to follow referrals automatically for the application. This behavior can be disabled globally (using the ldap_set_option() call) or on a per-request basis through the use of a server control.
As in the LDAPv3 protocol, all DNs and string values that are passed into or produced by the C LDAP API are represented as UTF-8 characters. Conversion functions are described in Section 13.20.
For compatibility with existing applications, implementations of this API will, by default, use Version 2 of the LDAP protocol. Applications that intend to take advantage of LDAPv3 features will need to use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION switch set to Version 3.
The file LDAP_EXAMPLE.C in SYS$EXAMPLES contains an example program
that demonstrates how to use the LDAP API on OpenVMS.
13.1.3 LDAP API Use on OpenVMS Systems
This release of the LDAP API provides support for client applications written in C or C++.
In order to use the LDAP API, a program must use an include statement of the form:
#include <ldap.h> |
The LDAP.H header file includes prototypes and data structures for all of the functions that are available in the LDAP API.
The shareable image LDAP$SHR.EXE includes run-time support for LDAP applications. This shareable image resides in SYS$LIBRARY and should be included in the library IMAGELIB.OLB, which means that no special action is necessary to link or run your programs. For example:
$ type myprog.c
/* A not very useful program */
#include <stdio.h>
#include <ldap.h>
void main(int argc, char *argv[])
{
LDAP *ld;
if (argc != 2) {
printf("usage: %s <hostname>\n",argv[0]);
return;
}
ld = ldap_init(argv[1],LDAP_PORT);
if (ld != NULL) {
printf("ldap_init returned 0x%p\n",ld);
} else {
printf("ldap_init failed\n");
}
}
$ cc myprog
$ link myprog
$ myprog :== $mydisk:[mydir]myprog.exe
$ myprog fred
ldap_init returned 0xA6748
$
|
This section describes the LDAP 64-bit addressing support.
13.1.4.1 Background
OpenVMS Alpha provides support for 64-bit virtual memory addressing. Applications that are built using a suitable compiler may take advantage of the 64-bit virtual address space to map and access large amounts of data.
The OpenVMS LDAP API supports both 32- and 64-bit client applications. In order to allow this, separate entry points are provided in the library for those functions that are sensitive to pointer size.
When a user module is compiled, the header file LDAP.H determines the pointer size in effect and uses the C preprocessor to map the function names into the appropriate library entry point. This mapping is transparent to the user application and is effected by setting the /POINTER_SIZE qualifier at compilation time.
For LDAP API users, switching between different pointer sizes should need only a recompilation---no code changes are necessary.
This means that programs using the specification for the C LDAP API, as
described in the Internet Engineering Task Force (IETF) documentation,
can be built on OpenVMS with either 32-bit or 64-bit pointer size,
without having to change the source code.
13.1.4.2 Implementation
The OpenVMS LDAP library uses 64-bit pointers internally and is capable of dealing with data structures allocated by the caller from 64-bit address space.
Applications that use 32-bit pointers will use the 32-bit function entry points in the library. This means they can pass arguments that are based on 32-bit pointers and can assume that any pointers returned by the library will be 32-bit safe.
While the mapping performed by LDAP.H is designed to be transparent,
there may be occasions where it is useful (for example in debugging) to
understand the consequences of having both 32- and 64-bit support in
the same library.
13.1.4.2.1 Library Symbol Names
The symbols exported by the LDAP$SHR OpenVMS run-time library differ from those specified in the IETF C LDAP API specification.
The header file LDAP.H maps user references to LDAP API function names to the appropriate LDAP$SHR symbol name. Therefore, any application wishing to use the OpenVMS LDAP API must include the version of LDAP.H that ships with OpenVMS.
All of the functions in the OpenVMS LDAP library are prefixed with the facility code "LDAP$".
For those functions where the caller's pointer size is significant, the name of the 64-bit entry point will have a "_64" suffix, while the name of the 32-bit jacket will have a "_32" suffix. Functions that are not sensitive to pointer size have no special suffix.
For example, the function ldap_modify() is sensitive to the caller's pointer size (because one of its arguments is an array of pointers). Therefore, the library exports symbols for LDAP$LDAP_MODIFY_64 and LDAP$LDAP_MODIFY_32. For the function ldap_simple_bind() , which is not sensitive to the caller's pointer size, a single entry point, LDAP$LDAP_SIMPLE_BIND, exists in the library.
Because OpenVMS imposes a 31-character limit on the length of symbol
names, certain functions in the library have names which are
abbreviated versions of the public API name. For example, in the case
of the function
ldap_parse_sasl_bind_result()
, the library provides two entry points, namely
LDAP$LDAP_PRS_SASL_BIND_RES_32 and LDAP$LDAP_PRS_SASL_BIND_RES_64.
13.1.4.2.2 LDAP Data Structures
The LDAP API defines various data structures which are used to pass information to and from a client application. Some of these structures are opaque; that is, their internal layout is not visible to a client application. In such cases, the API may return a pointer to such a structure, but the only use of such a pointer to a client application is as a parameter to subsequent library calls.
Some structures are public. Their contents are defined by the API, and client applications may allocate and manipulate such structures or use them as parameters to LDAP functions.
All data structures used by the API are defined with "natural" alignment; that is, each member of a data structure will be aligned on an address boundary appropriate to its type.
Opaque Data Structures
The following data structures are opaque. Applications should not make any assumptions about the contents or size of such data structures.
typedef struct ldap
LDAP;
typedef struct ldapmsg
LDAPMessage;
typedef struct berelement
BerElement;
|
Public Data Structures
The following data structures are described in the IETF documents relating to the LDAP API, and definitions are provided for them in LDAP.H. Applications may allocate and manipulate such structures, as well as use them in calls to the LDAP API.
typedef struct berval { .. }
BerValue;
typedef struct ldapapiinfo { .. }
LDAPAPIInfo;
typedef struct ldap_apifeature_info { .. }
LDAPAPIFeatureInfo;
typedef struct ldapcontrol { .. }
LDAPControl;
typedef struct ldapmod { .. }
LDAPMod;
|
Note that the pointer size in effect at compilation time determines the layout of data structures, which themselves contain pointer fields. Since all of the public data structures listed here contain one or more pointers, their size and layout will differ depending on the pointer size.
For example, in the case of the structure berval, the API provides the following definition:
struct berval {
ber_len_t bv_len;
char *bv_val;
} BerValue;
|
(where ber_len_t is equivalent on OpenVMS to an unsigned 32-bit integer). For a module compiled using 32-bit pointer size, the layout of a BerValue at address A would look like this:
In the case of a 64-bit compilation, the layout would be:
The following code would therefore work correctly regardless of pointer size:
#include <ldap.h>
.
.
.
char *buff;
BerValue val;
.
.
.
buff = (char *)malloc(255);
.
.
.
val.bv_len = 255;
val.bv_val = buff;
.
.
.
|
Two modules that include LDAP.H can be compiled with different pointer sizes and linked together. While each module may use the LDAP API on its own, it may not be possible for both modules to share LDAP-related data.
None of the public LDAP data structures is directly compatible between 32- and 64-bit modules. For example, a BerValue that has been allocated by a 32-bit module does not have the same layout as a BerValue which a 64-bit module expects to see, and consequently cannot be exchanged between two such modules without some sort of data conversion taking place.
Opaque data structures (such as LDAP *) have only a single structure
definition inside the library, and so pointers to such structures may
be exchanged between 32- and 64-bit callers. Note that these structures
are allocated only by the library itself, and, in the case of a 64-bit
caller, these structures may be allocated in 64-bit space. So while the
LDAP handle returned to a 32-bit caller of
ldap_init()
could safely be used by a 64-bit module, the reverse may not be true.
13.1.5 Multithreading Support
The OpenVMS LDAP API may be used by a multi-threaded application. Two
of the functions in the library,
ldap_perror()
and
ldap_result2error()
, are not thread-safe.
13.2 Common Data Structures and Memory Handling
The following are definitions of some data structures that are common to several LDAP API functions.
typedef struct ldap LDAP;
typedef struct berelement BerElement;
typedef struct ldapmsg LDAPMessage;
typedef struct berval {
ber_len_t bv_len;
char *bv_val;
} BerValue;
struct timeval;
|
The LDAP structure is an opaque data type that represents an LDAP session. Typically, this corresponds to a connection to a single server, but it may encompass several server connections in LDAPv3 referrals.
The LDAPMessage structure is an opaque data type that is used to return entry, reference, result, and error information. An LDAPMessage structure may represent the beginning of a list or a chain of messages that contain a series of entries, references, and result messages that are returned by LDAP operations, such as search. LDAP API functions, such as ldap_parse_result() , that operate on message chains which may contain more than one result message, always operate on the first result message in the chain. See Section 13.17 for more information.
The BerElement structure is an opaque data type that is used to hold data and state information about encoded data.
The berval structure is used to represent arbitrary binary data, and its fields have the following meanings:
| bv_len | Length of data in bytes. |
| bv_val | A pointer to the data itself. |
The timeval structure is used to represent an interval of time, and its fields have the following meanings:
| tv_sec | Seconds component of time interval. |
| tv_usec | Microseconds component of time interval. |
All memory that is allocated by a function in this C LDAP API and returned to the caller should be disposed of by calling the appropriate free function provided by this API. The correct free function to call is documented in each section of this chapter where a function that allocates memory is described.
Memory that is allocated outside of the C LDAP API must not be disposed of using a function provided by this API.
The following is a complete list of free functions that are used to dispose of allocated memory:
ber_bvecfree() ber_bvfree() ber_free() ldap_control_free() ldap_controls_free() ldap_memfree() ldap_msgfree() ldap_value_free() ldap_value_free_len() |
| Previous | Next | Contents | Index |