![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 30 March 2001 | |
|
|
|
|
|
|
| Previous | Contents | Index |
The LBR$SET_LOCATE routine sets the record access of LBR subroutines to locate mode.
LBR$SET_LOCATE library_index
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.
library_index
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.
Librarian 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 (the default), LBR$GET_RECORD copies the requested record to the specified user buffer. If locate mode is set, the record is not copied. Instead, the outbufdes descriptor is set to reference the internal LBR subroutine buffer that contains the record.
LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open.
The LBR$SET_MODULE routine reads, and optionally updates, the module header associated with a given record's file address (RFA).
LBR$SET_MODULE library_index ,rfa [,bufdesc] [,buflen] [,updatedesc]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.
library_index
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.rfa
OpenVMS usage: vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
Record's file address (RFA) associated with the module header. The rfa argument is the address of a 2-longword array containing the RFA returned by LBR$PUT_RECORD or LBR$LOOKUP_KEY.bufdesc
OpenVMS usage: char_string type: character string access: write only mechanism: by descriptor
Buffer that receives the module header. The bufdesc argument is the address of a string descriptor pointing to the buffer that receives the module header. The buffer must be the size specified by the symbol MHD$B_USRDAT plus the value of the CRE$L_UHDMAX create option. The MHD$ and CRE$ symbols are defined in the modules $MHDDEF and $CREDEF, which are stored in SYS$LIBRARY:STARLET.MLB.buflen
OpenVMS usage: longword_signed type: longword (signed) access: write only mechanism: by reference
Length of the module header. The buflen argument is the address of a longword receiving the length of the returned module header.updatedesc
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Additional information to be stored with the module header. The updatedesc argument is the address of a string descriptor pointing to additional data that the Librarian stores with the module header. If you include this argument, the Librarian updates the module header with the additional information.
If 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.You define the maximum length of the update information (by specifying a value for CRE$L_UHDMAX) when you create the library. The Librarian zero-fills the information if it is less than the maximum length or truncates it if it exceeds the maximum length.
LBR$_HDRTRUNC Buffer supplied to hold the module header was too small. LBR$_ILLCTL Specified library control index not valid. LBR$_ILLOP Error. The updatedesc argument was supplied and the library was a Version 1.0 library or the library was opened only for read access. LBR$_INVRFA Specified RFA does not point to a valid module header. LBR$_LIBNOTOPN Specified library not open.
The LBR$SET_MOVE routine sets the record access of LBR subroutines to move mode.
LBR$SET_MOVE library_index
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.
library_index
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.
Librarian 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.
LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open.
This chapter describes the C language application programming interface (API) to the Lightweight Directory Access Protocol (LDAP). This API supports Version 3 of the LDAP API (LDAPv3), and includes support for controls, information hiding, and thread safety. The LDAP API is available on OpenVMS Alpha only.
The C LDAP API is designed to be powerful, yet simple to use. It
defines compatible synchronous and asynchronous interfaces to LDAP to
support a wide variety of applications. This chapter gives a brief
overview of the LDAP model, and describes how the application program
uses the API to obtain LDAP information. The API calls are described in
detail, followed by a section that provides some example code
demonstrating the use of the API.
12.1.1 Overview of the LDAP Model
LDAP is the lightweight directory access protocol, which is based on a client-server model. In this model, a client makes a TCP connection to an LDAP server, over which it sends requests and receives responses.
The LDAP information model is based on the entry, which contains information about some object (for example, a person). Entries are composed of attributes, which have a type and one or more values. Each attribute has a syntax that determines what kinds of values are allowed in the attribute (for example, ASCII characters or a jpeg photograph) and how those values behave during directory operations (for example, whether case is significant during comparisons).
Entries may be organized in a tree structure, usually based on political, geographical, or organizational boundaries. Each entry is uniquely named relative to its sibling entries by its relative distinguished name (RDN) consisting of one or more distinguished attribute values from the entry. At most, one value from each attribute may be used in the RDN. For example, the entry for the person Babs Jensen might be named with the Barbara Jensen value from the commonName attribute.
A globally unique name for an entry, called a distinguished name or DN, is constructed by concatenating the sequence of RDNs from the entry up to the root of the tree. For example, if Babs worked for the University of Michigan, the DN of her U-M entry might be the following:
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.
12.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 12.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.
12.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.
12.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.
12.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.
12.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.
12.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;
.
.
.
|
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 4493PRO_026.HTML | ||