Sets tracing on or off for a specified transaction.
% INCLUDE SYGWPLI;
01 IHANDLE PTR, 01 RETCODE FIXED BIN(31), 01 TRACE_STATUS FIXED BIN(31), 01 TRACE_OPTIONS FIXED BIN(31), 01 TRANSACTION_ID CHAR(n), 01 TRANSACTION_ID_LENGTH FIXED BIN(31);
CALL TDSETSPT (IHANDLE, RETCODE, TRACE_STATUS, TRACE_OPTIONS, TRANSACTION_ID, TRANSACTION_ID_LENGTH);
(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-36.
(I) Trace indicator for the specified transaction. This is a Boolean value that turns tracing on or off for the specified transaction.
Assign this argument one of the following values:
TDS_TRUE (1) |
Turn on tracing for this transaction. |
TDS_FALSE (0) |
Turn off tracing for this transaction. |
(I) Type of tracing to be enabled for the specified transaction.
Assign this argument one of the following values:
TDS_SPT_API_TRACE (0x08) |
Trace all Gateway-Library calls. |
TDS_SPT_ERRLOG (0x02) |
Enable error log recording. |
TDS_SPT_TDS_DATA (0x01) |
Enable TDS packet-tracing recording. |
(I) Mainframe transaction identifier of the affected transaction.
Under CICS: This is the TRANSID from the CICS Program Control Table (PCT).
Under IMS TM: This is the transaction name defined when the system is generated.
Under MVS: This is the APPC transaction name defined in the transaction profile.
(I) Length of the TRANSACTION_ID.
For graphic datatypes, this is the number of double-byte characters; for other datatypes, it is the number of bytes. This value is returned by TDINFSPT.
Under CICS: For CICS Version 1.7, This value is always 4 or less. For later versions, it is the actual length of the transaction ID, which can be greater than 4.
Under IMS TM: This value is always 8 or less.
Under MVS: This is the APPC transaction name defined in the transaction profile. This value is normally 8 or less.
The RETCODE argument can contain any of the return values listed in Table 3-36.
Return value |
Meaning |
|---|---|
TDS_OK (0) |
Function completed successfully. |
TDS_DUPLICATE_ENTRY (-9) |
Duplicate column description. You attempted to describe the same column twice with a TDESCRIB statement. The operation failed. |
TDS_ENTRY_NOT_FOUND (-8) |
The specified column number, transaction number, or parameter does not exist. |
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_INVALID_STATUS (-174) |
Invalid status value. The value entered in the STATUS field is invalid. |
TDS_SOS (-257) |
Memory shortage. The host subsystem was unable to allocate enough memory for the control block that Gateway-Library tried to create. The operation failed. |
The following code fragment illustrates the use of TDSETSPT to turn on specific tracing at the beginning of an application. This example is taken from the sample program in Appendix C, “Sample Language Application for CICS.”
/* ------------------------------------------------------------*/
/* establish gateway environment */
/* ------------------------------------------------------------*/
CALL TDINIT (DFHEIBLK, GWL_RC, GWL_INIT_HANDLE);
/* ------------------------------------------------------------*/
/* turn on local tracing if not on globally or locally */
/* ------------------------------------------------------------*/
CALL TDINFLOG (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);
IF GWL_INFLOG_GLOBAL ^= TDS_TRACE_ALL_RPCS &
GWL_INFLOG_GLOBAL ^= TDS_TRACE_SPECIFIC_RPCS THEN
DO;
TRACING_SET_SW = TRACING_SET;
CALL LOCAL_TRACING;
END;
/*------------------------------------------------------------------*/
LOCAL_TRACING: PROC;
/*------------------------------------------------------------------*/
CALL TDSETSPT (GWL_INIT_HANDLE, GWL_RC,
TRACING_SET_SW,
GWL_SETSPT_TRACE_LEVEL,
GWL_SETSPT_RPC_NAME,
GWL_SETSPT_RPC_NAME_L);
RETURN;
END LOCAL_TRACING;
This function turns tracing on or off for the specified transaction.
Transaction-level tracing occurs when TDSETLOG sets the global trace flag to TDS_TRACE_SPECIFIC_RPCS and sets one or more types of tracing (for example, API tracing or header tracing). Use TDINFLOG to determine the setting of the global trace flag and to learn which types of tracing are currently enabled. Call TDSETLOG to change those settings.
If you request tracing for a transaction, and tracing is already on for that transaction, TDSETSPT returns TDS_DUPLICATE_ENTRY.
You can turn on transaction-level tracing for up to eight (8) transactions at a time.
Since eight is the maximum number of transactions for which tracing can be enabled at one time, you must turn tracing off for one of these transactions before you can enable tracing for an additional transaction. If you request tracing for a transaction, and eight transactions already have tracing turned on, TDSETSPT returns TDS_SOS.
If you try to turn tracing off for a transaction for which tracing is not enabled, TDSETSPT returns TDS_ENTRY_NOT_FOUND.
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
