Chapter 3: Functions

TDSETLOG

Description

Sets system-wide tracing for the mainframe server and rename the CICS trace log.

Syntax

COPY SYGWCOB.

01 IHANDLE               PIC S9(9)  USAGE COMP SYNC.
01 RETCODE               PIC S9(9)  USAGE COMP SYNC.
01 GLOBAL-TRACE-FLAG     PIC S9(9)  USAGE COMP SYNC.
01 API-TRACE-FLAG        PIC S9(9)  USAGE COMP SYNC.
01 TDS-HEADER-TRACE-FLAG PIC S9(9)  USAGE COMP SYNC.
01 TDS-DATA-TRACE-FLAG   PIC S9(9)  USAGE COMP SYNC.
01 TRACE-ID              PIC S9(9)  USAGE COMP SYNC.
01 TRACE-FILENAME        PIC X(8)   VALUE IS SPACES.
01 MAXNUM-TRACE-RECORDS  PIC S9(9)  USAGE COMP SYNC.

CALL 'TDSETLOG' USING IHANDLE, RETCODE, 
                GLOBAL-TRACE-FLAG, API-TRACE-FLAG, 
                TDS-HEADER-TRACE-FLAG, 
                TDS-DATA-TRACE-FLAG, TRACE-ID, 
                  TRACE-FILENAME, MAXNUM-TRACE-RECORDS.

Parameters

IHANDLE: (I) A transaction-wide structure that contains information used to set up the Gateway-Library environment. This must be the same IHANDLE specified in the program’s initial TDINIT call. It corresponds to the context structure in Open Client Client-Library.

RETCODE: (O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-31.

GLOBAL-TRACE-FLAG

(I) Global or specific trace indicator. Use this argument to turn tracing on or off and to indicate whether tracing is global (trace all transactions) or applies to a specific set of transactions. If tracing is off, only errors are logged.

Specific tracing can be set for 1 through 8 transactions. To set tracing for a particular transaction, use TDSETSPT.

Assign this argument one of the following values:

TDS-NO-TRACING (0)	Turn off all tracing.
TDS-TRACE-ALL-RPCS (1)	Turn on global tracing.
TDS-TRACE-SPECIFIC-RPCS (2)	Turn on specific tracing.
TDS-TRACE-ERRORS-ONLY (3)	Log errors only.

API-TRACE-FLAG

(I) API tracing on/off indicator. This is a Boolean value that sets tracing on or off for Gateway-Library calls. Assign this argument one of the following values:

TDS-TRUE (1)	Turn on API tracing.
TDS-FALSE (0)	Turn off API tracing.

TDS-HEADER-TRACE-FLAG

(I) TDS header tracing on/off indicator. This is a Boolean value that sets tracing on or off for TDS headers. Assign this argument one of the following values:

TDS-TRUE (1)	Turn on header tracing.
TDS-FALSE (0)	Turn off header tracing.

TDS-DATA-TRACE-FLAG

(I) TDS data tracing on/off indicator. This is a Boolean value that sets tracing on or off for TDS data. Assign this argument one of the following values:

TDS-TRUE (1)	Turn on data tracing.
TDS-FALSE (0)	Turn off data tracing.

TRACE-ID

(I) The trace entry identifier.

Under CICS: This is the tag for the auxiliary file entry.

Under IMS TM and MVS: Leave this field blank. This argument is ignored.

TRACE-FILENAME

(I) Name of the trace/error log.

Under CICS: Specify the DATASET name from the CICS File Control Table (FCT) entry that describes the VSAM file used for this log. As installed, this name is SYTDLOG1. You can change the name of this log by specifying a new name here.

Under IMS TM and MVS: Leave this field blank. IMS TM and MVS ignore this value.

MAXNUM-TRACE-RECORDS

(I) Trace log record limit.

Under CICS: This is the maximum number of records to be allocated for this trace file. To indicate the system maximum, assign this argument a value of -1. Sybase recommends always using -1.

Under IMS TM: The IMS TM system log does not have a limit. Sybase recommends always using -1.

Under MVS: Use -1. The size of the log is determined by the space allocated to the sequential file used as the MVS log.

Returns

The RETCODE argument can contain any of the return values listed in Table 3-31.

**Table 3-31: TDSETLOG return values**
Return value	Meaning
TDS-OK (0)	Function completed successfully.
TDS-INVALID-IHANDLE (-19)	Invalid IHANDLE specification. Error in specifying a value for the IHANDLE argument.
TDS-INVALID-PARAMETER (-4)	Invalid parameter value. The value assigned to one or more of the arguments supplied in the call is not valid. The operation failed.
TDS-LOG-ERROR(-258)	Attempt to write to the log file failed.

Examples

Example 1

The following code fragment illustrates the use of TDSETLOG to enable TDS header and data tracing. This example is taken from the sample program SYICSAL2, which runs under IMS TM. This book does not contain a listing for SYICSAL2. It is, however, shipped on the product tape.

*    turn on local tracing if not on globally or locally

     CALL 'TDINFLOG' USING GWL-INIT-HANDLE, GWL-RC, 
                            GWL-INFLOG-GLOBAL, 
                            GWL-INFLOG-API, 
                            GWL-INFLOG-TDS-HEADER,  
                            GWL-INFLOG-TDS-DATA, 
                            GWL-INFLOG-TRACE-ID, 
                            GWL-INFLOG-FILENAME,
                            GWL-INFLOG-TOTAL-RECS. 
      .
      . [check return code]
      .
      IF GWL-INFLOG-GLOBAL NOT = TDS-TRACE-ALL-RPCS THEN
            PERFORM LOCAL-TRACING
      ENDIF.
      .
*----------------------------------------------------------------
  LOCAL-TRACING.
*----------------------------------------------------------------

*    turn on specific tracing for SYL2

     MOVE TDS-TRACE-SPECIFIC-RPCS to GWL-INFLOG-GLOBAL.
      MOVE TDS-TRUE TO GWL-INFLOG-TDS-HEADER,
                    GWL-INFLOG-TDS-DATA.
	 MOVE 99 TO GWL-INFLOG-TRACE-ID.
	 MOVE ’IMSLOG’ TO GWL-INFLOG-FILENAME.
	 MOVE -1 TO GWL-INFLOG-TOTAL-RECS.

	 CALL 'TDSETLOG' USING GWL-INIT-HANDLE, GWL-RC, 
                            GWL-INFLOG-GLOBAL,
                            GWL-INFLOG-API,
                            GWL-INFLOG-TDS-HEADER,
                            GWL-INFLOG-TDS-DATA, 
                            GWL-INFLOG-TRACE-ID, 
                            GWL-INFLOG-FILENAME, 
                            GWL-INFLOG-TOTAL-RECS..
      . [check return code]
      .
      CALL 'TDSETSPT' USING GWL-INIT-HANDLE, GWL-RC, 
                            TRACING-SET-SW,
	 GWL-SETSPT-TRACE-LEVEL,
	 GWL-SETSPT-RPC-NAME,
	GWL-SETSPT-RPC-NAME-L.

Usage

You use this function to turn on or off one or more kinds of tracing, and to specify whether tracing is global or for specific transactions only. The following kinds of tracing are supported:
- API call tracing: traces Gateway-Library calls.
  
  Under CICS: API tracing uses the CICS auxiliary trace facility.
  
  Under IMS TM: API tracing uses the IMS TM system log.
  
  Under MVS: MVS uses a sequential file.
- TDS header tracing: keeps track of the 8-byte TDS headers that are sent to and from the mainframe server.
- TDS data tracing: traces both incoming and outgoing TDS data.
The trace log is also the error log.
The trace flag is set to off when the Gateway-Library is initialized. It remains off until the program explicitly turns it on with TDSETLOG, then it remains on until the program explicitly turns it off with TDSETLOG. No other Gateway-Library functions turn tracing on or off.
Specific tracing can be set for up to eight transactions. To set tracing for a particular transaction, use TDSETSPT. To find out whether specific tracing is set for a particular transaction, call TDINFSPT. For a list of the transactions being specifically traced, call TDLSTSPT.
The specified types of tracing (API, TDS header, and/or TDS data) apply to all transactions if the GLOBAL-TRACE-FLAG is set to TDS-TRACE-ALL-RPCS. If the GLOBAL-TRACE-FLAG is set to TDS-TRACE-SPECIFIC-RPCS, tracing applies to only those transactions specified in TDSETSPT calls.
If the global trace flag is set to TDS-NO-TRACING or TDS-TRACE-ERRORS, the program ignores the settings for the API, TDS header, and TDS data flags and turns them off.
A transaction can call this function any time after TDINIT. To set tracing on for the entire transaction, code this function before TDACCEPT. To set tracing on for only a portion of a transaction, use TDSETLOG anywhere within your program.
TDSETLOG begins writing to the specified log when it turns tracing on. It appends each new trace or error record to the trace log.
If your program does not call this function, the trace flag remains in the state it was in before the transaction executed.
The log used for tracing depends upon the transaction processing system in use and the type of tracing being done:
- Under CICS: Header and data traces are written to the trace log. The trace log is a VSAM ESDS file.
  
  As installed, the CICS trace log is named SYTDLOG1. You can change the name of this file by specifying a different name in the TRACE-FILENAME argument. The new name must match an FCT DATASET entry. Note that an alternate log may already exist. An FCT entry for the alternate log SYTDLOG2 is included in the installation instructions.
  
  When the VSAM log fills up, you must explicitly empty or delete the log or specify an alternate log in the TRACE-FILENAME argument.
  
  API tracing uses the CICS auxiliary facility. CICS users can retrieve the auxiliary trace output with the CICS job stream or with third party packages designed for this purpose. Refer to your CICS documentation for details about this facility.
- Under IMS TM: Header, data, and API tracing information are all written to the IMS TM system log. The same log is used for errors, tracing, and accounting, so each record needs to indicate which type of record it is.
  
  The layout of this log is the same as the layout of the CICS log except for the header. For details about the IMS TM system log, refer to your IMS TM documentation.
- Under MVS: The layout of this log is the same as the layout of the CICS log.
This function governs tracing at the mainframe server. The TRS administrator can turn tracing on and off at the TRS. Tracing at the mainframe server and at the TRS are independent of each other.
See the Mainframe Connect Server Option Installation and Administration Guide for a general discussion of the Gateway-Library tracing facility, instructions for using it, and the layout of the trace log.