SWSTOKEN Function
Related Topics
 |
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.
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.
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.