Sets or retrieves connection handle properties.
CS_RETCODE ct_con_props(connection, action, property,
buffer, buf_len, outlen);
CS_CONNECTION *connection;
CS_INT action;
CS_INT property;
CS_BYTE *buffer;
CS_INT buf_len;
CS_INT *outlen;
(I) Handle for this connection. This connection handle must already be allocated with ct_con_alloc. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
(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 Client-Library 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 description, possible values, and defaults.
(I/O) Variable (buffer) that contains the specified property value.
If action is CS_SET, the buffer contains the value ct_cmd_props uses.
If action is CS_GET, ct_cmd_props returns the requested information to this buffer.
If action is CS_CLEAR, the buffer is reset to the default property value.
This argument is typically one of the following datatypes:
int buffer;
char buffer[n];
(I/O) 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, ct_cmd_props 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 GS_GET, you
can not use CS_UNUSED for buf_len.
You must provide some value for buf_len.
If action is CS_CLEAR, this value is zero.
(O) Length, in bytes, of the retrieved information. outlen is an integer variable where ct_con_props returns the length of the property value being retrieved.
If 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. If action is CS_CLEAR or CS_SET, this value is zero.
ct_con_props returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. |
TDS_CANNOT_SET_VALUE (-43) |
This property cannot be set by the application. |
TDS_INVALID_PARAMETER (-4) |
One or more arguments contain illegal values. |
The following code fragment demonstrates how to use ct_con_props. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”
/********************************************************************/
/* */
/* Subroutine to process input data */
/* */
/********************************************************************/
void proces_input ()
{
CS_INT rc;
CS_INT *outlen;
CS_INT buf_len;
CS_INT msglimit;
CS_INT netdriver;
/*------------------------------------------------------------*/
/* Allocate a connection to the server */
/*------------------------------------------------------------*/
rc = ct_con_alloc (context, &connection);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CONALLOC failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Alter properties of the connection for user-id */
/*------------------------------------------------------------*/
buf_len = user_size;
rc = ct_con_props (connection, (long)CS_SET,
(long)CS_USERNAME, username,
buf_len, outlen);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CON_PROPS for user-id failed",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Alter properties of the connection for password */
/*------------------------------------------------------------*/
buf_len = pwd_size;
rc = ct_con_props (connection, (long)CS_SET,
(long)CS_PASSWORD, pwd, buf_len, outlen);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CON_PROPS for password failed",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Alter properties of the connection for transaction */
/*------------------------------------------------------------*/
buf_len = tran_size;
rc = ct_con_props (connection, (long)CS_SET,
(long)CS_TRANSACTION_NAME,
tran, buf_len, outlen);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CON_PROPS for transaction failed",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Alter properties of the connection for network driver */
/*------------------------------------------------------------*/
netdriver = 9999; /* default value for non-regconized
driver name */
/* if no netdriver entered, default is LU62 */
if (strncmp(driver," ",9) == 0 &&
strncmp(driver,"LU62",4) == 0)
netdriver = CS_LU62;
else if (strncmp(driver,"INTERLINK",8) == 0)
netdriver = CS_INTERLINK;
else if (strncmp(driver,"IBMTCPIP",8) == 0)
netdriver = CS_TCPIP;
else if (strncmp(driver,"CPIC",4) == 0)
netdriver = CS_NCPIC;
rc = ct_con_props (connection, (long)CS_SET,
(long)CS_NET_DRIVER, (long) netdriver,
CS_UNUSED, outlen);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_CON_PROPS for network driver failed",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
ct_con_props sets or retrieves the values of properties for a connection handle. Connection properties define aspects of Client-Library behavior at the connection level.
All command structures allocated for a connection pick up default property values from the parent connection. An application can override these default values by calling ct_cmd_props at the command structure level.
If an application changes connection property values after allocating command structures for the connection, the existing command structures do not pick up the new property values. New command structures allocated for the connection use the new property values as defaults.
Some connection properties only take effect if they are set before an application calls ct_connect to establish the connection.
An application can use ct_con_props to set or retrieve the following properties:
CS_APPNAME
CS_CHARSETCNV
CS_COMMBLOCK
CS_EXTRA_INF
CS_HOSTNAME
CS_LOGIN_STATUS
CS_NET_DRIVER
CS_NETIO
CS_NOINTERRUPT
CS_PACKETSIZE
CS_PASSWORD
CS_TDS_VERSION
CS_TRANSACTION_NAME
CS_USERDATA
Related functions
Related topics
