Chapter 3: Functions

CTBCONFIG

Description

Sets or retrieves context properties.

Syntax

%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 BUFBLANKSTRI   FIXED BIN(31);
     01 OUTLEN          FIXED BIN(31);
 
CALL CTBCONFI (CONTEXT, RETCODE, ACTION, PROPERTY, BUFFER, BUFFER_LEN, BUFBLANKSTRIP, OUTLEN);

Parameters

CONTEXT

(I) A context structure. The context structure is defined in the program call CSBCTXALLOC. It corresponds to the IHANDLE structure in the Open ServerConnect Gateway-Library.

If this value is invalid or nonexistent, CTBCONFIG fails.

RETCODE: (O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns” in this section.

ACTION

(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.

PROPERTY: (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.

BUFFER

(I/O) Variable (buffer) that contains the specified property value.

If ACTION is CS_SET, the buffer contains the value used by CTBCONFIG.

If ACTION is CS_GET, CTBCONFIG 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);

BUFFER_LEN

(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, 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.

If ACTION is CS_CLEAR, set this value to zeroes.

BUFBLANKSTRIP

(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.

OUTLEN

(O) Length, in bytes, of the retrieved information. OUTLEN is an integer variable where CTBCONFIG 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. If the ACTION is CS_SET or CS_CLEAR, this value is zero.

Returns

CTBCONFIG returns one of the following values:

Value	Meaning
CS_SUCCEED (-1)	The routine completed successfully.
CS_FAIL (-2)	The routine failed.

Examples

Example 1

The following code fragment demonstrates how CTBCONFIG is used to determine the maximum number of connections. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”

/*      -------------------------------------------------------*/
/*      find out what the maximum number of connections is     */
/*      -------------------------------------------------------*/
          CALL CTBCONFIG (CSL_CTX_HANDLE,
                          CSL_RC,
                          CS_GET,
                          CS_MAX_CONNECT,
                          CF_MAXCONNECT,
                          STG(CF_MAXCONNECT),
                          CS_FALSE,
                          CF_OUTLEN);
 
          .
          .  [check return code]
          .
          /* display number of connections */
          OR2_MAXCONNECT = CF_MAXCONNECT;
 
          TITLEO = OUTPUT_ROW_STR2;

Usage

CSBCONFIG sets or retrieves the values of CS_EXTRA_INF and CS_VERSION. All other context properties are set or reset by CTBCONFIG. Context properties define aspects of Client-Library behavior at the context level.
All connections created within a context pick up default property values from the parent context. An application can override these default values by calling CTBCONPROPS to set property values at the connection level.
If an application changes context property values after allocating connections for the context, the existing connections do not recognize the new property values. Only new connections allocated after the new context property values are set use the new values as defaults.