descriptor

descriptor syntax

od_specifiers

Description

An operational descriptor is an optional piece of information that is associated with a function argument. This information is used to describe an argument's attributes, for example, its data type and length. The #pragma descriptor directive is used to identify functions whose arguments have operational descriptors.

Operational descriptors are useful when passing arguments to functions that are written in other languages that may have a different definition of the data types of the arguments. For example, C defines a string as a contiguous sequence of characters ended by and including the first null character. In another language, a string may be defined as consisting of a length specifier and a character sequence. When passing a string from a C function to a function written in another language, an operational descriptor can be provided with the argument to allow the called function to determine the length and type of the string being passed.

The ILE C/C++ compiler generates operational descriptors for arguments that are passed to a function specified in a #pragma descriptor directive. The generated descriptor contains the descriptor type, data type, and length for each argument that is identified as requiring an operational descriptor. The information in an operational descriptor can be retrieved by the called function using the ILE APIs CEEGSI and CEEDOD. For more information about CL commands, see the CL and APIs section in the Programming category at the IBM® i Information Center web site:

    http://www.ibm.com/systems/i/infocenter

For the operational descriptor to determine the correct string length when passed through a function, the string has to be initialized.

The ILE C compiler supports operational descriptors for describing strings.

Note: A character string in ILE C/C++ is defined by using any one of the following ways:

char string_name[n]
char * string_name
A string literal

Parameters

function_name

The name of the function whose arguments require operational descriptors.

od_specifiers

A list of symbols, that consists of "", void, or *, separated by commas, that specify which of a function's arguments are to have operational descriptors. An od_specifier list is similar to the argument list of a function except that an od_specifier list for a function can have fewer specifiers than its argument list.

If a string operational descriptor is required for an argument, "" or * should be specified in the equivalent position for the od_specifier parameter.
If an operational descriptor is not required for an argument then void is specified for that parameter in the equivalent position for the od_specifier list.

Notes on Usage

Do not specify #pragma descriptor together with #pragma argopt for the same declaration. The compiler supports using only one or the other of these pragmas at a time.

The compiler issues a warning and ignores the #pragma descriptor directive if any of the following conditions occur:

The identifier specified in the pragma directive is not a function.
The function is already specified in another pragma descriptor.
The function is declared as static.
The function has already been specified in a #pragma linkage directive.
The function specified is a user entry procedure, for example, main().
The function is not prototyped before its #pragma descriptor directive.
A call to the function occurs before its #pragma descriptor directive.

When using operational descriptors consider the following restrictions:

Operational descriptors are only generated for functions that are called by their function name. Functions that are called by function pointer do not have operational descriptors generated.
Operational descriptors are not allowed for C++ function declaration.
If there are fewer od_specifiers than function arguments, the remaining od_specifiers default to void.
If a function requires a variable number of arguments, the #pragma descriptor directive can specify that operational descriptors are to be generated for the required arguments but not for the variable arguments.
It is not valid to do pointer arithmetic on a literal or array while it is also used as an argument that requires an operational descriptor, unless explicitly cast to char *. For example, if F is a function that takes as an argument a string, and F requires an operational descriptor for this argument, then the argument on the following call to F is not valid: F(a + 1) where "a" is defined as char a[10].