Chapter 3: Topics

Buffers

Description

A number of arguments used in Client-Library functions affect the contents of buffers: ACTION, BUFFER, BUFFER-LEN, BUFBLANKSTRIP, OUTLEN.

These arguments are described individually below. For a summary of argument values and their interaction, see Table 3-1.

Arguments

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 BUFFER-LEN to 0 and executing the function. When this is done, 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 is assigned 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.

Summary of buffer entries

Table 3-1 summarizes the interaction between ACTION, BUFFER, BUFFER-LEN, and OUTLEN.

**Table 3-1: 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.

View this book as PDF

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

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.