Sets or retrieves connection handle properties.
%INCLUDE CTPUBLIC;
DCL 01 CONNECTION 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 CTBCONPR (CONNECTION, RETCODE, ACTION, PROPERTY, BUFFER, BUFFER_LEN, BUFBLANKSTRIP, OUTLEN);
(I) Handle for this connection. This connection handle must already be allocated with CTBCONALLOC. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
(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 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 “Properties”, 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 used by CTBCMDPROPS.
If ACTION is CS_GET, CTBCMDPROPS 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:
01 BUFFER FIXED BIN(n); 01 BUFFER CHAR(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, 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, CTBCMDPROPS 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.
(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. |
If you are setting a property value and the terminating character is the last non-blank character, assign CS_TRUE to BUFBLANKSTRIP.
(O) Length, in bytes, of the retrieved information. OUTLEN is an integer variable where CTBCONPROPS returns the length of the property value being retrieved.
If the retrieved information is larger than BUFFER_LEN in 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 zeroes.
CTBCONPROPS 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 the use of CTBCONPROPS. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
/*------------------------------------------------------------------*/
/* */
/* Subroutine to process input data */
/* */
/*------------------------------------------------------------------*/
PROCESS_INPUT: PROC ;
/*------------------------------------------------------------*/
/* allocate a connection to the server */
/*------------------------------------------------------------*/
CSL_CON_HANDLE = 0 ;
CALL CTBCONAL( CSL_CTX_HANDLE,
CSL_RC,
CSL_CON_HANDLE ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONALLOC failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* alter properties of the connection for user-id */
/*------------------------------------------------------------*/
CALL CTBCONPR( CSL_CON_HANDLE,
CSL_RC,
CS_SET,
CS_USERNAME,
PF_USER,
PF_USER_SIZE,
CS_FALSE,
OUTLEN ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONPROPS for user-id failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* alter properties of the connection for password */
/*------------------------------------------------------------*/
CALL CTBCONPR( CSL_CON_HANDLE,
CSL_RC,
CS_SET,
CS_PASSWORD,
PF_PWD,
PF_PWD_SIZE,
CS_FALSE,
OUTLEN ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONPROPS for password failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* alter properties of the connection for transaction */
/*------------------------------------------------------------*/
CALL CTBCONPR( CSL_CON_HANDLE,
CSL_RC,
CS_SET,
CS_TRANSACTION_NAME,
PF_TRAN,
PF_TRANL,
CS_FALSE,
OUTLEN ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONPROPS for transaction failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
/*------------------------------------------------------------*/
/* alter properties of the connection for Network driver */
/*------------------------------------------------------------*/
SELECT;
WHEN (PF_NETDRV = ' ')
NETDRIVER = CS_LU62 ;
WHEN (PF_NETDRV = 'LU62' | PF_NETDRV = 'lu62')
NETDRIVER = CS_LU62 ;
WHEN (PF_NETDRV = 'IBMTCPIP' | PF_NETDRV = 'ibmtcpip')
NETDRIVER = CS_TCPIP ;
WHEN (PF_NETDRV = 'INTERLIN' | PF_NETDRV = 'interlin')
NETDRIVER = CS_INTERLINK ;
WHEN (PF_NETDRV = 'CPIC' | PF_NETDRV = 'cpic')
NETDRIVER = CS_NCPIC ;
OTHERWISE
DO;
MSGSTR = 'Invalid Network driver entered';
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END;
END;
CALL CTBCONPR( CSL_CON_HANDLE,
CSL_RC,
CS_SET,
CS_NET_DRIVER,
NETDRIVER,
CS_UNUSED,
CS_FALSE,
OUTLEN ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBCONPROPS for Network driver failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE ;
END ;
CTBCONPROPS 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 CTBCMDPROPS 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 recognize 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 CTBCONNECT to establish the connection.
An application can use CTBCONPROPS 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:
