Sets or retrieves context structure properties.
%INCLUDE CTPUBLIC;
DCL 01 CONTEXT FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 ACTION FIXED BIN(31); 01 PROPERTY FIXED BIN(31); 01 BUFFER type; 01 BUFFER_LEN FIXED BIN(31); 01 BUFBLANKSTRIP FIXED BIN(31); 01 OUTLEN FIXED BIN(31); CALL CSBCONFIG (CONTEXT, RETCODE, ACTION, PROPERTY, BUFFER, BUFFER_LEN, BUFBLANKSTRIP, OUTLEN);
(I) A context structure for which the properties are being set or retrieved. The context structure is defined in the program call CSBCTXALLOC.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(I) Action to be taken by this call. ACTION is an integer variable that indicates the purpose of this call. Assign ACTION one of the following symbolic values:
Value |
Meaning |
|---|---|
CS_GET (33) |
Retrieves the value of the property. |
CS_SET (34) |
Sets the value of the property. |
CS_CLEAR (35) |
Clears the value of the property by resetting the property to its default value. |
(I) Symbolic name of the property for which the value is being set or retrieved. Table 3-19 lists the properties that can be set or retrieved by CSBCONFIG.
Application action |
Property |
Indicates |
|---|---|---|
Set, retrieve, or clear |
CS_EXTRA_INF |
Whether to return the extra information required when processing messages in line, using the SQLCA or SQLCODE structures. |
Retrieve only |
CS_VERSION |
The version number of Open Client currently in use. |
(I/O) Variable (buffer) that contains the specified property value.
If ACTION is CS_SET, CSBCONFIG takes the value from this buffer.
If ACTION is CS_GET, CSBCONFIG returns the requested information to this buffer.
If ACTION is CS_CLEAR, this value is zeroes.
This argument is typically one of the following datatypes:
01 BUFFER FIXED BIN(n); 01 BUFFER CHAR(n);
(I) Length, in bytes, of the buffer.
If ACTION is CS_SET and the value in the buffer is a fixed-length or symbolic value, BUFFER_LEN should have a value of CS_ UNUSED. To indicate that the terminating character is the last non-blank character, an application sets BUFBLANKSTRIP to CS_TRUE.
If ACTION is CS_GET and BUFFER is too small to hold the requested information, CSBCONFIG sets OUTLEN to the length of the requested information and returns CS_FAIL. To retrieve all the requested information, change the value of BUFFER_LEN to the length returned in OUTLEN and rerun the application.
If ACTION is CS_CLEAR, this value is zeroes.
(I) Blank stripping indicator. Indicates whether trailing blanks are stripped. Assign this argument one of the following symbolic values:
Value |
Meaning |
|---|---|
CS_TRUE (1) |
Trailing blanks are stripped. The value in the buffer ends at the last non-blank character. |
CS_FALSE (0) |
Trailing blanks are not stripped. They are included in the value. |
(O) Length, in bytes, of the retrieved information. OUTLEN is an integer variable where CSBCONFIG returns the length of the property value being retrieved.
When the retrieved information is larger than BUFFER_LEN bytes, an application uses the value of OUTLEN to determine how many bytes are needed to hold the information.
OUTLEN is used only when ACTION is CS_GET. When the ACTION is CS_SET or CS_CLEAR, this value is zeroes.
CSBCONFIG returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. |
TDS_INVALID_PARAMETER (-4) |
One of the CSBCONFIG arguments contains an illegal value. The most likely cause for this code is that a property value is being set and the value assigned to BUFBLANKSTRIP is not CS_TRUE. |
CSBCONFIG and CTBCONFIG both
set and retrieve context properties. CSBCONFIG is
used with global context properties; CTBCONFIG is
used with Client-Library properties.
CSBCONFIG can be used to set and retrieve the values of CS_EXTRA_INF and to retrieve the version number of Open Client currently in use.
Use CTBCONFIG to set and retrieve the values of Client-Library-specific context properties. Properties set through CTBCONFIG affect only Client-Library behaviors.
CS_EXTRA_INF determines whether or not Client-Library returns the extra information that is required to fill in a SQLCA or SQLCODE structure.
If an application is not retrieving messages into a SQLCA or SQLCODE structure, the extra information is returned as ordinary Client-Library messages.
The CS_VERSION property represents the version of Client-Library behavior that an application requests through CSBCTXALLOC.
An application can only retrieve the value of CS_VERSION; it cannot assign a value to CS_VERSION.
The CS_USERDATA property defines user-allocated data. This property allows an application to associate user data with a particular connection or command structure. An application allocates a data space from which it can get this data when needed.
A PL/I program can use the WORK AREAS section to define this data.
Related functions:
