A number of arguments used in Client-Library functions affect the contents of buffers: ACTION, BUFFER, BUFFER_LEN, BUFBLANKSTRIP, and OUTLEN.These arguments are described individually below. For a summary of argument values and their interaction, see Table 2-1.
ACTION describes what is done to the data. For most functions, ACTION can take the following symbolic values:
CS_SET |
Assigns a value |
CS_GET |
Retrieves a value |
CS_CLEAR |
Clears the buffer, or, for functions that set properties, resets to the default property value |
BUFFER is a program variable, called a “buffer.”
When ACTION is CS_SET |
BUFFER is the data being read by the function. |
When ACTION is CS_GET |
BUFFER is the information retrieved by the function. |
When ACTION is CS_CLEAR |
BUFFER remains unchanged. |
BUFFER_LEN is the length, in bytes, of the BUFFER argument.
When the value in the buffer is a fixed-length or symbolic value: |
Assign BUFFER_LEN the actual length of the value or CS_UNUSED. |
When the value in the buffer is of variable length: |
Assign BUFFER_LEN the maximum number of bytes that the buffer can contain. |
If BUFFER_LEN is set to CS_GET and the buffer is too small to hold the returned value, the function returns CS_FAIL in the RETCODE argument and the actual length of the requested information in OUTLEN.
When this happens, you can query the length of the incoming data by setting CS_SET to 0 and executing the function. The actual length of the data is returned to the OUTLEN argument. Enlarge the buffer, assign the value in OUTLEN to BUFFER_LEN, and execute the function again.
BUFBLANKSTRIP is the blank stripping indicator. It indicates whether or not trailing blanks are stripped. This argument gets one of the following symbolic values:
CS_TRUE |
Trailing blanks are stripped. The value in the buffer ends at the last non-blank character it contains. |
CS_FALSE |
Trailing blanks are not stripped; they are included in the value. |
OUTLEN is an integer variable where the function returns the actual length, in bytes, of the data being retrieved during a CS_GET operation. For all other operations, OUTLEN is ignored.
When the retrieved data is longer than BUFFER_LEN bytes, an application can use the value of OUTLEN to determine how many bytes are needed to hold the information.
To do this, set the value of OUTLEN to 0 and call the function. Then set the value of BUFFER_LEN to the length returned in OUTLEN and call the function again.
Table 2-1 summarizes the interaction between ACTION, BUFFER, BUFFER_LEN, and OUTLEN.
For this ACTION |
When BUFFER |
BUFFER_LEN is |
OUTLEN is |
Result |
|---|---|---|---|---|
CS_CLEAR |
N/A |
CS_UNUSED |
Ignored |
The property reverts to its default value. |
CS_SET |
Contains a variable-length character string |
The length of the string |
Ignored |
The data in BUFFER is read by the function. |
CS_SET |
Contains a variable-length character string for which the terminating character is the last non-blank character |
The maximum length of the string |
Ignored |
The application sets the value of BUFBLANKSTRIP to CS_TRUE. The data in BUFFER is read by the function. |
CS_SET |
Contains a fixed-length character string or symbolic value |
CS_UNUSED |
Ignored |
The data in BUFFER is read by the function. |
CS_GET |
Is large enough for the return character string |
The length of the buffer |
Set by Client-Library |
The retrieved value is copied to the buffer. OUTLEN returns the length of the retrieved value. |
CS_GET |
Is not large enough for the return character string |
The length of the buffer |
Set by Client-Library |
No data is copied to the buffer. OUTLEN returns the length of the value being retrieved. The function returns CS_FAIL, indicating that you should assign the value returned here to the length argument and execute the program again. |
CS_GET |
Is assumed to be large enough for a fixed-length or symbolic value |
CS_UNUSED |
Set by Client-Library |
The retrieved value is copied to the buffer. OUTLEN returns the length of the value being retrieved. |
