Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Macros

Macros are C language definitions that typically take one or more arguments and expand into inline C code when the source file is preprocessed. The following sections introduce the Open Client macros by presenting them in their functional contexts.

Decoding a message number

Client-Library and CS-Library message numbers are CS_INT sized integers that consist of four components: layer, origin, severity, and number. The macros CS_LAYER, CS_ORIGIN, CS_SEVERITY, and CS_NUMBER unpack the components from a message number. See "Client-Library message numbers" for more information.

Manipulating bits in a CS_CAP_TYPE structure

Capabilities describe features that a client/server connection supports. Each connection's capability information is stored in a CS_CAP_TYPE structure.

The macros CS_CLR_CAPMASK, CS_SET_CAPMASK, and CS_TST_CAPMASK manipulate the bits in a CS_CAP_TYPE structure. See "Setting and retrieving multiple capabilities" for descriptions of these macros.

Using the sizeof operator

The C sizeof operator returns the size of a specified item in bytes. Because the datatype of its return value varies from platform to platform, specifying sizeof in place of a CS_INT argument to a Client-Library routine may result in a compiler error or warning if the type returned is not the same base type as CS_INT.

Client-Library provides the following macro to enable an application to use the sizeof function when calling Client-Library routines

CS_SIZEOF(variable) - casts a sizeof return value to CS_INT.

This macro is defined in the header file cstypes.h.

Prototyping functions

Some C compilers require each function to be declared with an ANSI-style prototype that indicates the placement and datatype of each argument received by the function. Other compilers do not recognize ANSI-style prototypes.

The PROTOTYPE macro allows forward declarations that are agreeable to both ANSI and non-ANSI compilers. This macro is used in forward declarations of C functions as:

PROTOTYPE (( argument_list ));

where argument_list is the ANSI-style argument list. PROTOTYPE is conditionally defined. If the compiler supports ANSI-style prototypes, then PROTOTYPE echos the argument list into the compiled code. Otherwise, PROTOTYPE echos nothing.

The following example illustrates the use of PROTOTYPE:

extern CS_RETCODE CS_PUBLIC ex_clientmsg_cb PROTOTYPE((

         CS_CONTEXT *context,

         CS_CONNECTION *connection,

         CS_CLIENTMSG *errmsg

));

CS_RETCODE CS_PUBLIC

 ex_clientmsg_cb(context, connection, errmsg)

 CS_CONTEXT      *context;

 CS_CONNECTION   *connection;

 CS_CLIENTMSG    *errmsg;

    ... function body goes here ...

CS_PUBLIC is used in callback function prototypes to make sure that machine-specific declaration requirements are satisfied. See "Declare callbacks with CS_PUBLIC " for more information.


	Expand Search