Buffers

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

• 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.