Previous Topic
Table Of Contents
Parent Topic
Next Topic

High-Level Language SWSTOKEN (SWCPTK) 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 SWCPTK

The SWSTOKEN service provides a means of saving and restoring transaction-oriented data using a server-created token value.

Transaction data can be saved before generating an outbound response to a Web transaction, and then be restored (using the token value) when the next transaction arrives.

The token service allows you to create complex, inter-active Web transactions which need a scratch-pad area to save state information between Web transaction boundaries.

All tokens have a timeout associated with them at creation time. If the token is not accessed within the timeout period the Server automatically deletes the token (along with the associated data).

CALL Arguments

The SWSTOKEN service takes from three to eight arguments, depending on the sub-function being requested.

The Create Sub-function

The create sub-function causes the Server to create a new token and save an initial data value. The service returns the 24-byte token identifier. The token identifier is used to request other operations against the token.

Token CREATE Sub-Function
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 SWS_TOKEN_CREATE Input A four-byte flag-word indicating the type of operation to be performed. The constant shown invokes the create sub-function
3 UCHAR * PIC X(25) CHAR(25) Output The buffer area where the service returns the 24-byte token identifier. The 24-byte token ID is returned with a 1-byte null terminator value in the 25th position.
4 PTR PIC X(nnn) CHAR(nnn) Input The buffer area containing the initial data to be saved when the the token is created. You may not specify a null-terminated string for this argument. The length of the data must be explicitly given by the fifth argument.
5 SDWORD PIC S9(5) COMP FIXED BIN(31) Input The size of the initial data to be saved for the token. You must explicitly provide the size of the forth argument; SWS_NTS is not a valid argument value.
6 SDWORD PIC S9(5) COMP FIXED BIN(31) Input The timeout value for the token, expressed in seconds. The token service deletes unreferenced tokens after some defined time period. The time period for auto-delete can be expressed using this argument.
7 PTR PIC X(nnn) CHAR(nnn) Input Optional argument. If used, this argument is the user data value to be associated with the token. The value can be a null-terminated string.
8 SDWORD PIC S9(5) COMP FIXED BIN(31) Input Optional argument. If used, this argument is the length of the user data given by the 7th argument. You may specify SWS_NTS to indicate that the user data value is a null terminated string.

The Delete Sub-function

The delete sub-function causes the Server to delete a token.

Token DELETE Sub-Function
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 SWS_TOKEN_DELETE Input A four-byte flag-word indicating the type of operation to be performed. The constant shown invokes the delete sub-function
3 UCHAR * PIC X(24) CHAR(24) Input The buffer area where the service obtains the 24-byte token identifier of the token to be deleted.

The Get Sub-function

The get sub-function retrieves the data associated with a token.

Token GET Sub-Function
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 SWS_TOKEN_GET Input A four-byte flag-word indicating the type of operation to be performed. The constant shown invokes the get sub-function
3 UCHAR * PIC X(24) CHAR(24) Input The buffer area where the service obtains the 24-byte token identifier of the token to be referenced.
4 PTR PIC X(nnn) CHAR(nnn) Output The buffer area where the service returns the data value associated with the token. If the actual token data is larger than this area, the returned value will be truncated to fit within this area.
5 SDWORD PIC S9(5) COMP FIXED BIN(31) Input The size of the return data area buffer, specified by the forth argument.
6 SDWORD * PIC S9(5) COMP FIXED BIN(31) Output The token service returns the actual size of the data value associated with the token into this area.

The Put Sub-function

The put sub-function updates part or all of the data value associated with a token. Note that the put sub-function cannot be used to alter the length of the data value associated with a token; only to re-write some or all of it.

Token PUT Sub-Function
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 SWS_TOKEN_PUT Input A four-byte flag-word indicating the type of operation to be performed. The constant shown invokes the put sub-function
3 UCHAR * PIC X(24) CHAR(24) Input The buffer area where the service obtains the 24-byte token identifier of the token to be updated.
4 PTR PIC X(nnn) CHAR(nnn) Output The buffer area where the service obtains the new data value to be written for the token. If the size of this area is smaller than the actual token data, this data will overwrite only the leading portion of the token's data value; the remainder will be unchanged. If this data value is larger than the actual token data, the service rewrites only the portion corresponding to the existing actual token data length. (I.E. This service cannot be used to enlarge the data area associated with a token.)
5 SDWORD PIC S9(5) COMP FIXED BIN(31) Input The size of the data area given by the forth argument.

The Replace Sub-function

The replace sub-function re-writes the data value associated with a token. The original data value is purged, and the new value becomes associated with the token. Use this sub-function (not the put sub-function) to change the size of the data associated with a token.

Token REPLACE Sub-Function
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 SWS_TOKEN_REPLACE Input A four-byte flag-word indicating the type of operation to be performed. The constant shown invokes the replace sub-function
3 UCHAR * PIC X(24) CHAR(24) Input The buffer area where the service obtains the 24-byte token identifier of the token to be replaced.
4 PTR PIC X(nnn) CHAR(nnn) Output The buffer area where the service obtains the new data value to be written for the token. The new data value completely replaces the existing data value.
5 SDWORD PIC S9(5) COMP FIXED BIN(31) Input The size of the data area given by the forth argument.

Top

Return Values

SWSTOKEN always sets a signed numeric return code value. Possible values are:

SWS_SUCCESS
The operation succeeded without error.
SWS_SUCCESS_WITH_INFO
The operation succeeded. This return value is set when data is truncated for the get sub-function.
SWS_NO_DATA_FOUND
The requested token could not be found.
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 argument is invalid. No error information can be returned using SWSERROR.
 

PL/I Example


 
    DCL  SCONN     PTR;                 /* Connection Handle       */
    DCL  STKID     CHAR(25);            /* token ID value          */
    DCL  SDATA     CHAR(256);           /* data value              */
    DCL  SSIZE     FIXED BIN(31);       /* data value size         */
    DCL  STMOU     FIXED BIN(31) INIT(300);  /* timeout value      */
    DCL  RC        FIXED BIN(31);       /* return code             */
    DCL  DMHX      FIXED BIN(31) BASED; /* Dummy Handle field      */
 
    ADDR(SCONN)->DMHX = 0;              /* Clear Connection Handle */
 
    SDATA    = 'Hello World!';          /* Set output area         */
    SSIZE    = 12;                      /* set length              */
    CALL SWSTOKEN( SCONN                /* create a token          */
                   SWS_TOKEN_CREATE,
                   STKID,
                   SDATA,
                   SSIZE,
                   STMOU );
    RC = PLIRETV();                     /* get return code         */
    IF RC ^= SWS_SUCCESS THEN           /* exit program if bad RC  */
       EXIT;

Top

C Example


 
    HDBC sConn   = NULL;                /* Connection Handle       */
    char sData[] = "Token Data Area";   /* data string definition  */
    char sTkid[25];                     /* Token ID return area    */
    long RC;                            /* return code             */
 
    rc = SWSToken( &sConn,              /* create the token        */
                   SWS_TOKEN_CREATE,
                   sTkid,
                   sData,
                   sizeof(sData) );
    if (rc ^= SWS_SUCCESS) return;      /* exit program if bad RC  */

COBOL Example


 
    77  SCONN                USAGE IS POINTER.
    77  STKID                PIC X(25).
    77  SDATA                PIC X(80).
    77  SSIZE                PIC S9(5) COMP.
    77  STMOU                PIC S9(5) COMP VALUE 300.
    77  SUSDA                PIC X(30) VALUE 'User Data Area'.
    77  SUSLN                PIC S9(5) COMP VALUE 30.
 
    MOVE 'HELLO WORLD!' TO SDATA.
    MOVE 12             TO SSIZE.
 
    CALL 'SWCPTK' USING SCONN,
                  SWS-CREATE-TOKEN,
                  STKID,
                  SDATA,
                  SSIZE,
                  STMOU,
                  SUSDA,
                  SUSLN );
    MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
    IF NOT SWS-SUCCESS GOBACK.

Top