Chapter 2: Functions

CTBGETFORMAT

Description

Returns the user-defined format for a result column.

This function is used with requests to Adaptive Server only.

Syntax

COPY CTPUBLIC.

01 COMMAND PIC S9(9) COMP SYNC.
01 RETCODE PIC S9(9) COMP SYNC.
01 COLUMN-NUM PIC S9(9) COMP SYNC.
01 BUFFER PIC S9(9) or PIC X(9)
01 BUFFER-LEN PIC S9(9) COMP SYNC.
01 OUTLEN PIC S9(9) COMP SYNC.

CALL 'CTBGETFO' USING COMMAND RETCODE COLUMN-NUM BUFFER BUFFER-LEN OUTLEN.

Parameters

COMMAND: (I) Handle for this client/server operation. This handle is defined in the associated CTBCMDALLOC call.

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.

COLUMN-NUM

(I) Number of the column for which the user-specified format is desired.

COLUMN-NUM refers to the select-list ID of the column. The first column in the select list of a select statement is column number 1, the second is column number 2, and so forth.

BUFFER

(O) Variable (“buffer”) in which CTBGETFORMAT places the requested information.

This argument is typically:

	01 BUFFER 	PIC X(n).

BUFFER-LEN

(I) Length, in bytes, of the buffer.

If BUFFER-LEN is too small to hold the requested information, CTBGETFORMAT sets OUTLEN to the length of the requested information, and returns CS-FAIL.

OUTLEN

(O) Length, in bytes, of the format string. OUTLEN is an integer variable where CTBGETFORMAT returns the total number of bytes being retrieved.

When the format string is larger than BUFFER-LEN bytes, an application uses this value to determine how many bytes are needed to hold the string.

If a format string is not associated with the specified column, CTBGETFORMAT sets OUTLEN to 0.

Returns

CTBGETFORMAT 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 CTBGETFORMAT arguments contains an illegal value.

Examples

Example 1

The following code fragment demonstrates the use of CTBGETFORMAT. This sample is not part of any sample program, so the working storage section is included here.

       01 CTX                      PIC S9(9) COMP SYNC VALUE +0.
    	   01 CON                      PIC S9(9) COMP SYNC VALUE +0.
    	   01 CMD                      PIC S9(9) COMP SYNC VALUE +0.
    	   01 RET                      PIC S9(9) COMP SYNC VALUE +0.
    01 RETCODE                  PIC S9(9) COMP SYNC VALUE +0.
    01 RESTYPE                  PIC S9(9) COMP SYNC VALUE +0.
    01 DATALEN                  PIC S9(9) COMP SYNC VALUE +0.
    01 COL-NUM                  PIC S9(9) COMP SYNC VALUE IS 0.
    01 FMT-BUFFER               PIC X(6).
    01 FMT-LEN                  PIC S9(9) COMP SYNC VALUE IS 0.
    01  SW-FETCH                PIC X(01).
        88  NO-MORE-ROWS VALUE 'N'.
        88  MORE-ROWS    VALUE 'Y'.
    
    01 STRLENPIC S9(9) COMP SYNC.
    01 OUTLENPIC S9(9) COMP SYNC.
    01 USER-DATAPIC X(30).
    01 USER-BUFPIC X(8).
    01 NUMROWSPIC S9(9) COMP SYNC.
    
    PROCEDURE DIVISION.
    P0.
    	 .
    	 .
    	 .
 RESULTS-PROCESSING.
 
 * SET UP THE RESULTS DATA
 
      CALL 'CTBRESUL' USING CMD RETCODE RESTYPE.
 
 * DETERMINE THE OUTCOME OF THE COMMAND EXECUTION
 
      EVALUATE RETCODE
        WHEN CS-SUCCEED
 
 * DETERMINE THE TYPE OF RESULT RETURNED BY THE CURRENT REQUEST
           EVALUATE RESTYPE
 
 * PROCESS ROW RESULTS
           WHEN CS-ROW-RESULT
               PERFORM RESULT-GETFMT
               PERFORM RESULT-CANCEL
               PERFORM RESULT-ROW-PROCESSING
               MOVE 'Y' TO SW-FETCH
               PERFORM FETCH-ROW-PROCESSING UNTIL NO-MORE-ROWS
 RESULT-ROW-PROCESSING.
 
 * FOR EACH COLUMN, BIND THE RESULT
      PERFORM BIND-ROW-PROCESSING.
 
 RESULT-GETFMT.
    MOVE 1 TO COL-NUM.
    MOVE LENGTH OF FMT-BUFFER TO FMT-LEN.
    CALL 'CTBGETFO' USING CMD RETCODE COL-NUM FMT-BUFFER FMT-LEN
           FMT-LEN OUTLEN.
    IF RETCODE NOT EQUAL CS-SUCCEED
        STRING 'CTBGETFO FAILED' DELIMITED BY SIZE INTO MSGSTR
        PERFORM PRINT-MSG.
 
 RESULT-CANCEL.
    CALL 'CTBCANCE' USING CON RETCODE CMD CS-CANCEL-ALL
           CS-UNUSED NUMROWS.
    IF RETCODE NOT EQUAL CS-SUCCEED
        STRING 'CTBCANCEL FAILED' DELIMITED BY SIZE INTO MSGSTR
        PERFORM PRINT-MSG.

Usage

CTBGETFORMAT returns the user-defined format, if any, for a result column. It indicates how the field should be formatted on screen.
An application can call CTBGETFORMAT after CTBRESULTS indicates results of type CS-ROW-RESULT.
For a description of how to add user-defined formats to Adaptive Server databases or Open Servers, see the Mainframe Connect Server Option Installation and Administration Guide.