Previous Topic Table Of Contents Parent Topic Next Topic |  | # SWSTOKEN Function Related Topics Web Server API Function Index
| May be used in Shadow/REXX
| May be used from Other REXX Interpreters
| High-level language interface available
The SWSTOKEN built-in function 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). ## SWSTOKEN Syntax The basic syntax of the SWSTOKEN function is: `var = SWSTOKEN( func, arg2, arg3, arg 4 )` The first argument, func, to the SWSTOKEN function specifies the sub-function to be performed. The values which may be coded for the func argument are: CREATE Create a new token and save the associated data. GET Retrieve data associated with a token value. PUT Update the data associated with an existing token value. REPLACE Replace the data associated with an existing token value. DELETE Delete a token and the associated data. ## CREATE Service The sub-function creates a new token value and saves data associated with the token. The data can later be retrieved or updated, using the token value. ### Syntax Example The create service is invoked by coding: `newtok = SWSVALUE('CREATE',data,timeout,userdata)` The arguments to the CREATE service call are: data The data to be associated with the token. This operand is required. Once the token is created, the size of the data can only be altered using the REPLACE token service (PUT cannot be used to change the data size). When invoked from Shadow/REXX, the maximum size of the data area is limited to 32,000 bytes. timeout A expiration timeout value to be associated with the token, specified in seconds. If the token value is unaccessed for this length of time, the token value (and associated data) is discarded by the system. Any access to the token value causes this expiration timer to be restarted. If this argument to the function call is omitted, the system uses the value set for the `TOKENTIMEOUT` product parameter. userdata Specifies an optional character string which is associated with the token. If this operand is not specified, the user data value is set to the value of the original URL under which the token was created. This character string is displayed on the active tokens ISPF display, but has no other purpose. This argument is optional. ### Return Value The token CREATE service always returns the 24-byte token value. A run-time error is generated if the token cannot be created. Top ## GET Service The sub-function retrieves the data associated with a previously created token. ### Syntax Example The get service is invoked by coding: `data = SWSVALUE('GET',token)` The arguments to the GET service call are: token The token value returned from the CREATE function. ### Return Value The token GET service returns the data associated with the token when it was created. The length of the data returned is always equal to the length of the data associated with the token when it was created. If the input token value is unknown the function returns a NULL string. This can occur because another application has caused the token to be explicitly deleted or because the token timeout period has expired. ## PUT Service The sub-function updates the data associated with a previously created token. ### Syntax Example The PUT service is invoked by coding: `rc = SWSVALUE('PUT',token,newdata)` The arguments to the PUT service call are: token The token value returned from the CREATE function. newdata The new data value to be written to the token. If this data value is longer than the value originally written, it is truncated to the length of the original data value. If the new value is shorter than the previous value, it overlays only the front portion of the value. Note that the REPLACE service must be used to alter the size of the data associated with a token. ### Return Value The token PUT service returns one of the following numeric values: 0 The newdata value was saved. 100 The token value is unknown or invalid. For example, the token has been explicitly deleted or the timeout period has elapsed. Top ## REPLACE Service The sub-function replaces the data associated with a previously created token. ### Syntax Example The REPLACE service is invoked by coding: `rc = SWSVALUE('REPLACE',token,newdata)` The arguments to the REPLACE service call are: token The token value returned from the CREATE function. newdata The new data value to be written to the token. This data completely replaces the data associated with the token. ### Return Value The token REPLACE service returns one of the following numeric values: 0 The newdata value was saved. 100 The token value is unknown or invalid. For example, the token has been explicitly deleted or the timeout period has elapsed. ## DELETE Service The sub-function deletes a token and associated data and removes is from the system. ### Syntax Example The DELETE service is invoked by coding: `rc = SWSVALUE('DELETE',token)` The arguments to the DELETE service call are: token The token value returned from the CREATE function. ### Return Value The token DELETE service returns one of the following numeric values: 0 The token has been deleted. 100 The token value is unknown or invalid. For example, the token has been explicitly deleted or the timeout period has elapsed. Top