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