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