Previous Topic Table Of Contents Parent Topic Next Topic |  | # High-Level Language SWSTRACE (SWCPTM) Function Related Topics Web Server API Function Index
| 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.

Top

## 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.

Top