Sets system-wide tracing for the mainframe server and rename the CICS trace log.
% INCLUDE SYGWPLI;
01 IHANDLE PTR,
01 RETCODE FIXED BIN(31),
01 GLOBAL_TRACE_FLAG FIXED BIN(31),
01 API_TRACE_FLAG FIXED BIN(31),
01 TDS_HEADER_TRACE_FLAG FIXED BIN(31),
01 TDS_DATA_TRACE_FLAG FIXED BIN(31),
01 TRACE_ID FIXED BIN(31),
01 TRACE_FILENAME CHAR(08) INIT(' '),
01 MAXNUM_TRACE_RECORDS FIXED BIN(31);
CALL TDSETLOG (IHANDLE, RETCODE, GLOBAL_TRACE_FLAG,
API_TRACE_FLAG, TDS_HEADER_TRACE_FLAG,
TDS_DATA_TRACE_FLAG, TRACE_ID,
TRACE_FILENAME, MAXNUM_TRACE_RECORDS);
(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.
(O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-31.
(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.s |
TDS_TRACE_SPECIFIC_RPCS (2) |
Turn on specific tracing. |
TDS_TRACE_ERRORS_ONLY (3) |
Log errors only. |
(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. |
(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. |
(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. |
(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.
(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.
(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. We recommend always using -1.
Under IMS TM: The IMS TM system log does not have a limit. We recommend 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.
The RETCODE argument can contain any of the return values listed in Table 3-31.
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. |
The following example illustrates the use of TDSETLOG to enable API tracing and header tracing. It is taken from the sample program in Appendix G, “Sample Tracing and Accounting Program,” which runs under CICS.
/*------------------------------------------------------------------*/
TDSETLOG_ON_PROC: PROC;
/*------------------------------------------------------------------*/
CALL TDINFLOG (GWL_INIT_HANDLE, GWL_RC,
GWL_INFLOG_GLOBAL,
GWL_INFLOG_API,
GWL_INFLOG_HEADER,
GWL_INFLOG_DATA,
GWL_INFLOG_TRACEID,
GWL_INFLOG_FILENAME,
GWL_INFLOG_RECORDS);
IF GWL_RC NE TDS_OK THEN
DO;
SEND_DONE = SEND_DONE_ERROR;
MSG_SRVLIB_FUNC = 'TDINFLOG';
GO TO TDSETLOG_ON_EXIT;
END;
/* ------------------------------------------------------------*/
/* turn on API (CICS Aux Trace) and Header tracing */
/* ------------------------------------------------------------*/
CALL TDSETLOG (GWL_INIT_HANDLE, GWL_RC,
TDS_TRACE_ALL_RPCS,
TDS_TRUE,
TDS_TRUE,
GWL_INFLOG_DATA,
GWL_INFLOG_TRACEID,
GWL_INFLOG_FILENAME,
GWL_INFLOG_RECORDS);
IF GWL_RC NE TDS_OK THEN
DO;
SEND_DONE = SEND_DONE_ERROR;
MSG_SRVLIB_FUNC = 'TDSETLOG';
GO TO TDSETLOG_ON_EXIT;
END;
/*------------------------------------------------------------------*/
TDSETLOG_ON_EXIT:
/*------------------------------------------------------------------*/
RETURN;
END TDSETLOG_ON_PROC;
The following example illustrates the use of TDSETLOG to disable API tracing and header tracing. It is taken from the sample program in Appendix G, “Sample Tracing and Accounting Program,” which runs under CICS.
/*------------------------------------------------------------------*/
TDSETLOG_OFF_PROC: PROC;
/*------------------------------------------------------------------*/
CALL TDINFLOG (GWL_INIT_HANDLE, GWL_RC,
GWL_INFLOG_GLOBAL,
GWL_INFLOG_API,
GWL_INFLOG_HEADER,
GWL_INFLOG_DATA,
GWL_INFLOG_TRACEID,
GWL_INFLOG_FILENAME,
GWL_INFLOG_RECORDS);
IF GWL_RC NE TDS_OK THEN
DO;
SEND_DONE = SEND_DONE_ERROR;
MSG_SRVLIB_FUNC = 'TDINFLOG';
GO TO TDSETLOG_OFF_EXIT;
END;
/* ------------------------------------------------------------*/
/* turn off API (CICS Aux Trace) and Header tracing */
/* ------------------------------------------------------------*/
CALL TDSETLOG (GWL_INIT_HANDLE, GWL_RC,
TDS_NO_TRACING,
TDS_FALSE,
TDS_FALSE,
GWL_INFLOG_DATA,
GWL_INFLOG_TRACEID,
GWL_INFLOG_FILENAME,
GWL_INFLOG_RECORDS);
IF GWL_RC NE TDS_OK THEN
DO;
SEND_DONE = SEND_DONE_ERROR;
MSG_SRVLIB_FUNC = 'TDSETLOG';
GO TO TDSETLOG_OFF_EXIT;
END;
/*------------------------------------------------------------------*/
TDSETLOG_OFF_EXIT:
/*------------------------------------------------------------------*/
RETURN;
END TDSETLOG_OFF_PROC;
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 the following communication font-ends:
Under CICS. The API tracing uses the CICS auxiliary trace facility.
Under IMS TM. The 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, and 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.
Global trace flag
The specified types of tracing described previously 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-TRAC-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 that is 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.
Related functions
Related documents
Mainframe Connect Server Option Installation and Administration Guide
