Sets or retrieves context structure properties.
CS_RETCODE cs_config (context, action,property,
buffer, buf_len, outlen);
CS_CONTEXT *context;
CS_INT action;
CS_INT property;
CS_BYTE *buffer;
CS_INT buf_len;
CS_INT *outlen;
(I) A context structure for which the properties are being set or retrieved. The context structure is defined in the program call cs_ctx_alloc.
(I) Action this call takes. 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. Client-Library properties are listed under “Remote procedure calls (RPCs)”, with descriptions, possible values, and defaults.
Table 3-16 lists the properties that can be set or retrieved by cs_config.
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, cs_config takes the value from this buffer.
If action is CS_GET, cs_config 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:
CS_INT buffer; CS_CHAR buffer[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, buf_len should have a value of CS_UNUSED.
If action is CS_GET and buffer is too small to hold the requested information, cs_config sets outlen to the length of the requested information and returns CS_FAIL. To retrieve all the requested information, change the value of buf_len to the length returned in outlen and rerun the application.
If action is CS_CLEAR, this value is zeroes.
(O) Length, in bytes, of the retrieved information. outlen is an integer variable where cs_config returns the length of the property value being retrieved.
When the retrieved information is larger than buf_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 action is CS_SET or CS_CLEAR, this value is zeroes.
cs_config 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 cs_config arguments contains an illegal value. |
cs_config and ct_config both
set and retrieve context properties.
cs_config is used with global context
properties; ct_config is used with Client-Library properties.
cs_config can be used to set and retrieve the value of CS_EXTRA_INF and to retrieve the version number of Open Client currently in use.
Use ct_config to set and retrieve the values of Client-Library-specific context properties. Properties set through ct_config affect only Client-Library behaviors.
Extra information
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.
Version level
The CS_VERSION property represents the version of Client-Library behavior that an application requests through cs_ctx_alloc.
An application can only retrieve the value of CS_VERSION; it cannot assign a value to CS_VERSION.
User data
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.
Related functions
