Get String Information (CEEGSI) API

The Get String Information (CEEGSI) API retrieves string information about a parameter used in the call to this API. String information describes the elements of a parameter, such as the type and the length of the string.

Authorities and Locks

None.

Required Parameter Group

posn (input)

The ordinal position in the parameter list of the formal parameter whose operational descriptor is required. A value of 1 denotes the leftmost parameter.

datatype (output)

The binary value of the data type field. The possible values and their data types are:

1	(typeEsc) An element descriptor type (descElmt) that is not one of the following data types.
2	(typeChar) A string of SBCS characters with values in the range X'00' through X'FF'.
3	(typeCharZ) A string of SBCS characters with values in the range X'01' through X'FF' that ends with a null byte (X'00').
4	(typeCharV2) A string of SBCS characters prefixed by an unsigned 2-byte binary count field. The count field specifies the current length of the string in terms of the number of string elements, that is, the number of characters.
5	(typeCharV4) A string of SBCS characters prefixed by an unsigned 4-byte binary count field. The count field specifies the current length of the string in terms of the number of string elements, that is, the number of characters.
6	(typeBit) A string of bits with values of 0 or 1.
7	(typeBitV2) A string of bits prefixed by an unsigned 2-byte binary count field. The count field specifies the current length of the string in terms of the number of string elements, that is, the number of bits.
8	(typeBitV4) A string of bits prefixed by an unsigned 4-byte binary count field. The count field specifies the current length of the string in terms of the number of string elements, that is, the number of bits.
9	(typeGChar) A string of DBCS characters with values in the range X'0000' through X'FFFF'.
10	(typeGCharZ) A string of DBCS characters with values in the range X'0001' through X'FFFF' that end with a null byte (X'0000').
11	(typeGCharV2) A string of DBCS characters prefixed by an unsigned 2-byte binary count field. The count field specifies the current length of the string in terms of the number of string elements, that is, the number of characters.
12	(typeGCharV4) A string of DBCS characters prefixed by an unsigned 4-byte binary count field. The count field specifies the current length of the string in terms of the number of string elements, that is, the number of characters.

currlen (output)

A binary number containing the current number of elements in the string, as follows:

• For strings of typeEsc, this is the length from the descriptor, and is equal to the maximum length returned in maxlen.
• For strings of typeCharV2 and typeCharV4, this is the length from the argument (binary prefix) itself.
• For strings of typeCharZ, the API determines the current length (in number of characters, either SBCS or DBCS) of the string by scanning for the null character. If the length in the descriptor is nonzero (the compiler of the caller knew the extent), the search is confined to that length. Otherwise, the scan continues until a null character is found.
• If the data type was undefined, the contents of this field are undefined.

maxlen (output)

A binary number containing the maximum number of string elements, as follows:

• For strings of typeEsc, this is the length from the descriptor, and is equal to the current length returned in currlen.
• For strings of typeCharV2 and typeCharV4, this is the length from the descriptor (which does not include the length of the prefix).
• For strings of typeCharZ, the maximum length is the number of the characters excluding the null character. It is the maximum length from the descriptor minus 1 (to account for the SBCS or DBCS null character). If the length in the descriptor is zero, the maximum length is set equal to the current length.
• If the data type was undefined, the contents of this field are undefined.

Omissible Parameter

fc (output)

A 12-byte feedback code.

Feedback Codes and Conditions

Usage Notes

• It is an error to use CEEGSI to test an argument that is not a reference argument or that is preceded in the argument list by other arguments that are not reference arguments.

  Note: This error may not be diagnosed.

• The results are undefined if this API is used in a function that does not have operational descriptors specified.
• CEEGSI is implemented as a builtin and therefore cannot have its address taken or be called through a procedure pointer.