Chapter 2: Functions

CTBCONFIG

Description

Sets or retrieves context properties.

Syntax

COPY CTPUBLIC.

01 CONTEXT PIC S9(9) COMP SYNC.
01 RETCODE PIC S9(9) COMP SYNC.
01 ACTION PIC S9(9) COMP SYNC.
01 PROPERTY PIC S9(9) COMP SYNC.
01 BUFFER type.
01 BUFFER-LEN PIC S9(9) COMP SYNC.
01 BUFBLANKSTRIP PIC S9(9) COMP SYNC.
01 OUTLEN  PIC S9(9) COMP SYNC.

CALL 'CTBCONFI' USING 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 “Return value,” 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  PIC S9(9) COMP SYNC. 
	01 BUFFER  PIC X(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, this value is ignored.

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

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 to use CTBCONFIG to determine the maximum number of connections. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests.”

	 *--------------------------------------------------------------
	 *  find out what the maximum number of connections is
	 *--------------------------------------------------------------
            CALL 'CTBCONFI'  USING CSL-CTX-HANDLE,
                                   CSL-RC,
                                   CS-GET,
                                   CS-MAX-CONNECT,
                                   CF-MAXCONNECT,
                                   CF-FOUR,
                                   CS-FALSE,
                                   CF-OUTLEN.
            IF CSL-RC NOT EQUAL CS-SUCCEED
              THEN
                MOVE SPACES TO MSGSTR
                STRING 'CTBCONFI CS-GET failed' DELIMITED BY SIZE
                                                       INTO MSGSTR
                PERFORM PRINT-MSG
                PERFORM ALL-DONE
            END-IF.

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.