action, buffer, buflen, and outlen

Many Client-Library routines use some combination of the parameters action, buffer, buflen, and outlen.

action – describes whether to set or retrieve information. For most routines, action can take the symbolic values CS_GET, CS_SET, and CS_CLEAR.

If action is CS_CLEAR, buffer must be NULL, and buflen must be CS_UNUSED.
buffer – typically a pointer to program data space.

If information is being set, buffer points to the value to use in setting the information.

If information is being retrieved, buffer points to the space in which the Client-Library routine places the requested information.

If information is being cleared, buffer must be NULL.

If the Client-Library routine returns CS_FAIL, *buffer remains unchanged.
buflen – the length, in bytes, of the buffer data space.

If information is being set and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.

If *buffer is a fixed-length value, a symbolic value, or a function, buflen must be CS_UNUSED.

If buffer is NULL, buflen must be 0 or CS_UNUSED.
outlen – a pointer to an integer variable.

outlen must be NULL if information is being set.

When information is being retrieved, outlen is an optional parameter. If supplied, Client-Library sets the variable to the length, in bytes, of the requested information.

If the information is longer than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.

Table 2-3 summarizes the interaction between action, buffer, buflen, and outlen:

**Table 2-3: Interaction between action, buffer, buflen, and outlen parameters**
action	buffer	buflen	outlen	What happens
CS_CLEAR	NULL	CS_UNUSED	NULL	The Client-Library information is cleared by resetting it to its default value.
CS_SET	A pointer to a null-terminated character string	CS_NULLTERM or the length of the string, not including the null terminator	NULL	The Client-Library information is set to the value of the *buffer character string.
CS_SET	A pointer to a character string that is not null-terminated	The length of the string	NULL	The Client-Library information is set to the value of the *buffer character string.
CS_SET	A pointer to a variable-length, noncharacter value (for example, binary data)	The length of the data	NULL	The Client-Library information is set to the value of the *buffer data.
CS_SET	A pointer to a fixed-length or symbolic value	CS_UNUSED	NULL	The Client-Library information is set to the value of the integer or symbolic value.
CS_SET	NULL	0 or CS_UNUSED	NULL	The Client-Library information is set to NULL.
CS_GET	A pointer to space large enough for the return character string plus a null terminator	The length of *buffer	Supplied or NULL	The return value is copied to *buffer. A null terminator is appended. If supplied, *outlen is set to the length of the return value, including the null terminator.
CS_GET	A pointer to space that is not large enough for the return character string plus a null terminator	The length of *buffer	Supplied or NULL	No data is copied to buffer. If supplied, outlen is set to the length of the return value, including the null terminator. The routine returns CS_FAIL.
CS_GET	A pointer to space that is large enough for the return variable-length, noncharacter data	The length of *buffer	Supplied or NULL	The return value is copied to *buffer. If supplied, *outlen is set to the length of the return value.
CS_GET	A pointer to space that is not large enough for the return variable-length, noncharacter data	The length of *buffer	Supplied or NULL	No data is copied to buffer. If supplied, outlen is set to the length of the return value. The routine returns CS_FAIL.
CS_GET	A pointer to space that is assumed to be large enough for a fixed-length or symbolic value	CS_UNUSED	Supplied or NULL	The return value is copied to *buffer. If supplied, *outlen is set to the length of the return value.