Chapter 3: Functions

TDWRTLOG

Description

Writes a user-created message or a system entry to the trace and error log.

Syntax

COPY SYGWCOB.

01 TDPROC         PIC S9(9)  USAGE COMP SYNC.
01 RETCODE        PIC S9(9)  USAGE COMP SYNC.
01 DATETIME-FLAG  PIC S9(9)  USAGE COMP SYNC.
01 MESSAGE        PIC X(x).
01 MESSAGE-LENGTH  PIC S9(9)  USAGE COMP SYNC.

CALL 'TDWRTLOG’ USING TDPROC, RETCODE, DATETIME-FLAG,
                MESSAGE, MESSAGE-LENGTH.

Parameters

TDPROC: (I) Handle for this client/server connection. This must be the same value specified in the associated TDACCEPT call. The TDPROC handle corresponds to the connection and command handles 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-48.

DATETIME-FLAG

(I) Timestamp indicator. This flag indicates whether or not the log message should begin with the current date and time. Assign this argument one of the following values:

TDS-TRUE (1)	Include date and time.
TDS-FALSE (0)	Do not include date and time.

MESSAGE: (I) User-written message. This is the text of the message to be written to the trace file.

MESSAGE-LENGTH: (I) Length of the user-written message. The message must be less than or equal to 80 bytes in length. For graphic datatypes, this is the number of double-byte characters; for other datatypes, it is the number of bytes.

Returns

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

**Table 3-48: TDWRTLOG return values**
Return value	Meaning
TDS-OK (0)	Function completed successfully.
TDS-LOG-ERROR(-258)	Attempt to write to the log file failed.
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-TDPROC (-18)	Error in specifying a value for the TDPROC argument.
TDS-WRONG-STATE (-6)	This function cannot be used in the current communication state. For example, your program tried to send a reply before it read in all of the client parameters. The application was still in RECEIVE state and could not send. The operation failed.

Examples

Example 1

The following code fragment writes an entry to the trace log after checking to see that tracing is enabled. It is taken from the sample program in Appendix G, “Sample Tracing and Accounting Program” which runs under CICS.

	*   ------------------------------------------------------------- 
 	*   Determine whether tracing is on or off. 
 	*   ------------------------------------------------------------- 
      PERFORM GET-TRACE-STATUS THRU GET-TRACE-STATUS-EXIT. 
  
 *   ------------------------------------------------------------- 
 *   Write a log entry only if logging is enabled. 
 *   ------------------------------------------------------------- 
      IF TRACING-ON THEN 
          CALL 'TDWRTLOG' USING GWL-PROC, 
                                GWL-RC, 
                                TDS-TRUE, 
                                GWL-WRTLOG-MSG, 
                                GWL-WRTLOG-MSG-L 
  
          IF GWL-RC NOT = TDS-OK THEN 
              MOVE 'N'        TO SEND-DONE-SW 
              MOVE 'TDWRTLOG' TO MSG-SRVLIB-FUNC 
              GO TO TDWRTLOG-EXIT 
          END-IF 
      ELSE 
          MOVE 'N'        TO SEND-DONE-SW 
          MOVE 'LOGNOTON' TO MSG-SRVLIB-FUNC 
      END-IF.

Usage

You use this function to write a message to the trace and error log.
Traces and error messages are written to the same log. The transaction processing system determines the log used for tracing and the type of tracing being done:
- Under CICS: The trace and error log is a VSAM ESDS file.
  
  As installed, the CICS trace log is named SYTDLOG1. You can change the name of this file with TDSETLOG. To find out the name of the current trace log, use TDINFLOG.
- Under IMS TM: Header, data, and API tracing information are all written to the IMS TM system log.
- Under MVS: The information is written to a sequential file.
The log must be open for this function to execute successfully.
- Under CICS: TDSETLOG opens the trace and error log when it turns tracing on.
- Under IMS TM: The IMS TM system log is always open, but TDSETLOG does a logical OPEN by turning tracing on.
- Under MVS: Gateway-Library opens the log, but TDSETLOG does a logical OPEN by turning tracing on.
This function can be used to send local messages to the trace and error log even when the connection is down.
See the Mainframe Connect Server Option Installation and Administration Guide for an explanation of the Gateway-Library tracing facility, instructions for using it, and the layout of the trace log.