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.
1 – Background
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.
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.
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.
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).
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;
.
.
.
3 – Mixing Pointer Sizes
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.