High-Level Language SWSTRACE (SWCPTM) Function
Related Topics
 |
May be used in Shadow/REXX |
| |
May be used from Other REXX Interpreters |
| |
HLL entry point name is SWCPTM |
SWSTRACE is the Web Server API function used to write a message into the Shadow OS/390 Web Server's wrap-around trace browse dataset. The message can contain any text desired. If the message is too long to fit within a trace browse record, it is truncated. Truncation is not considered an error.
CALL Arguments
The SWSTRACE function takes four arguments. All four arguments must be specified on the call.
| Arg. No. |
HLL Argument Type | I/O | Description of Argument | ||
|---|---|---|---|---|---|
| c | COBOL | PL/I | |||
| 1 | HDBC | USAGE POINTER | PTR | Input | The Web Server connection handle. The connection handle is an opaque, four-byte address pointer. The connection handle is currently not used, and must be set to zero (NULL). |
| 2 | PTR | PIC X(nnn) | CHAR(nnn) | Input | The data value which is to be written to the trace browse wrap-around dataset. You may
specify a null terminated string, or explicitly provide the value length via the third
argument. The maximum useable length for a trace browse record is approximately 730 bytes. |
| 3 | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | The size of the data value given by the second argument which is to be written to the trace record. You may optionally specify SWS_NTS, to indicate that the data is a null terminated string. |
| 4 | UDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | This argument is currently not used, but may be in future releases. You must specify a zero value. |
Return Values
SWSTRACE always sets a signed numeric return code value. Possible values are:
- SWS_SUCCESS
- The operation succeeded. The specified data was written to the product's wrap-around trace.
- SWS_ERROR
- A parameter validation or run-time error was encountered. Error information is available using the SWSERROR function.
- SWS_ENVIRONMENT_ERROR
- The request can not be processed because of a run-time environmental error. For example, you invoked the API service outside of a Web transaction procedure or from outside the server's address space. Use the server's wrap-around trace to obtain diagnostic information.
- SWS_INVALID_HANDLE
- The connection handle is invalid. No error information is available.
- Any other value
- The operation failed.
PL/I Example
DCL TCONN PTR; /* Connection Handle */
DCL TDATA CHAR(256); /* Text output area */
DCL TSIZE FIXED BIN(31); /* Text length area */
DCL RC FIXED BIN(31); /* return code */
DCL DMHX FIXED BIN(31) BASED; /* Dummy Handle field */
DCL FB00 FIXED BIN(31) INIT(0); /* Dummy argument */
ADDR(TCONN)->DMHX = 0; /* Clear Connection Handle */
TDATA = 'Trace Message Text'; /* Set output area */
TSIZE = 18; /* set length */
CALL SWSTRACE( TCONN /* output trace message */
TDATA,
TSIZE,
FB00 );
RC = PLIRETV(); /* get return code */
IF RC ^= SWS_SUCCESS THEN /* exit program if bad RC */
EXIT;
C Example
HDBC tConn = NULL; /* Connection Handle */
char tData[] = "Null-terminated!"; /* Text string definition */
long RC; /* return code */
rc = SWSTrace( &tConn, /* output trace message */
tData,
SWS_NTS,
0 );
if (rc ^= SWS_SUCCESS) return; /* exit program if bad RC */
COBOL Example
77 TCONN USAGE IS POINTER.
77 TDATA PIC X(80).
77 TSIZE PIC S9(5) COMP.
77 FB00 PIC S9(5) COMP VALUE 0.
MOVE 'TRACE MESSAGE' TO TDATA.
MOVE 13 TO TSIZE.
CALL 'SWCPTM' USING TCONN,
TDATA,
TSIZE,
FB00.
MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
IF NOT SWS-SUCCESS GOBACK.