Previous Topic
Table Of Contents
Parent Topic
Next Topic
| |
Related Topics
Web Server API Function Index
SWSVALUE is the Web Server API function used to fetch or set transaction run-time
variable values. The HLL API can operate upon the following variable types:
Variable Type |
Fetch Existing Value |
Assign New/Changed Value |
GLOBAL. |
Yes |
Yes |
GLVEVENT. |
Yes |
Yes |
Event-Related |
Yes |
No |
CALL Arguments
The SWSVALUE function call requires either six or seven arguments. The seventh argument
is required for value fetch requests; It must be omitted for value update operations.
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 |
UDWORD |
PIC S9(5) COMP |
FIXED BIN(31) |
Input |
A four-byte flag-word indicating the sub-function to be performed. One of the
following manifest constants should be used to indicate the desired operation. The values
are mutually exclusive; only one may be used.
- SWS_VALUE_OBTAIN
- Fetch the current value of the named variable. If the variable is not initialized,
return an error (SWS_NO_DATA_FOUND) to the caller.
- SWS_VALUE_VALUE
- Fetch the current value of the named variable. If the variable is not initialized, the
upper-case name of the variable is returned as its current value. (This matches the
behavior of REXX-language procedures, where the value of an uninitialized variable is the
name of the variable, itself.)
- SWS_VALUE_UPDATE
- If the named variable already exists, replace its current value with the new value
specified by the caller. If the variable is uninitialized, create the variable and assign
the specified value to it.
|
3 |
UCHAR * |
PIC X(nnn) |
CHAR(nnn) |
Input |
The character name of the variable to be acted upon. The variable name string may be
null-terminated, or the size may be explicitly specified by the 'SVASZ' argument. The
maximum length of any variable name passed to the SWSVALUE API may not exceed 50 bytes. If
trailing blanks are passed as part of the variable name string, they are removed by the
API interface. |
4 |
SDWORD |
PIC S9(5) COMP |
FIXED BIN(31) |
Input |
The size of the variable name specified by the third argument. This argument can be an
integer fullword value in the range 5-to-50. You can also use the manifest constant,
SWS_NTS, to specify that variable name is a null-terminated string. Note that the API
interface automatically removes trailing blanks from the variable name string, regardless
of whether an explicit length or a null-terminated string is used. |
5 |
PTR |
PIC X(nnn) |
CHAR(nnn) |
InOut |
For the SWS_VALUE_OBTAIN or SWS_VALUE_VALUE sub-function, this
argument is the address of the data buffer which will receive the fetched variable value.
Fetched values are always returned as a null-terminated string, even if the value must be
truncated to fit within the supplied buffer space. For the SWS_VALUE_UPDATE
sub-function, this argument specifies the address of the value data to be assigned to the
new/updated variable.
Note: The implementation maximum size for the value of any variable is 32,000
bytes; 8,000 if used in HTML extension substitution processing. |
6 |
SDWORD |
PIC S9(5) COMP |
FIXED BIN(31) |
Input |
For the SWS_VALUE_OBTAIN or SWS_VALUE_VALUE sub-function, this
argument specifies the total size of the buffer area (argument five). For the SWS_VALUE_UPDATE
sub-function, this argument specifies the size of the variable value, given by the
argument five, which is to be assigned to the variable. |
7 |
SDWORD * |
PIC S9(5) COMP |
FIXED BIN(31) |
Output |
For the SWS_VALUE_OBTAIN or SWS_VALUE_VALUE sub-function, this
argument receives the actual size of the variable's value. If the return value is
shorter than the supplied buffer area, this argument receives the actual number of bytes
used to store the value within the output buffer.
If the number of bytes required to store the fetched value is greater than or equal
to the return buffer area size, then the fetched value is truncated, and a null
terminator is placed in the last buffer position. This argument receives the count of
bytes actually needed to save the entire value.
For the SWS_VALUE_UPDATE subfunction, C-language callers should code NULL
for this argument. COBOL and PL/I callers should omit this argument. |
Top
Return Values
SWSVALUE always sets a signed numeric return code value. Possible values are:
- SWS_SUCCESS
- The operation succeeded. The variable's value was fetched or updated as requested.
- SWS_SUCCESS_WITH_INFO
- The operation partially succeeded. This return code value is set for fetch operations
when the returned variable value has been truncated.
- 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_NO_DATA_FOUND
- For a SWS_VALUE_OBTAIN sub-function request, the named variable is not
initialized.
- 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 SVANA CHAR(50); /* variable name */
DCL SVASZ FIXED BIN(31) INIT(50); /* variable name size */
DCL SBUFF CHAR(256); /* buffer area */
DCL SBFSZ FIXED BIN(31) INIT(256); /* Buffer size */
DCL SRTSZ FIXED BIN(31); /* Fetched value size */
DCL RC FIXED BIN(31); /* return code */
DCL DMHX FIXED BIN(31) BASED; /* Dummy Handle field */
ADDR(SCONN)->DMHX = 0; /* Clear Connection Handle */
SVANA = 'WWW.VAR.FORMFIELD'; /* Set variable name */
CALL SWSVALUE( SCONN /* get the variable value */
SWS_VALUE_VALUE, /* subfunction = retrieve */
SVANA, /* variable name string */
SVASZ, /* maximum variable size */
SBUFF, /* return data buffer */
SBFSZ, /* maximum buffer size */
SRTSZ ); /* actual size return area */
RC = PLIRETV(); /* get return code */
IF (RC ^= SWS_SUCCESS & /* exit program if bad RC */
RC ^= SWS_SUCCESS_WITH_INFO) THEN
EXIT;
SVANA = 'GLVEVENT.FORMFIELD'; /* Set variable name */
SBUFF = 'Html Form Field Value'; /* set variable value data */
SBFSZ = 21; /* length of value data */
CALL SWSVALUE( SCONN /* create GLVEVENT variable*/
SWS_VALUE_UPDATE, /* subfunction = set value */
SVANA, /* variable name string */
SVASZ, /* size of SVANA */
SBUFF, /* value data buffer */
SBFSZ ); /* size of value data */
RC = PLIRETV(); /* get return code */
IF (RC ^= SWS_SUCCESS & /* exit program if bad RC */
RC ^= SWS_SUCCESS_WITH_INFO) THEN
EXIT;
Top
C Example
HDBC sConn = NULL; /* Connection Handle */
char sVana[] = "WWW.VAR.FORMDATA"; /* variable name */
char sVana2[] = "GLVEVENT.DATA"; /* variable name */
char sBuff[256]; /* return buffer area */
SDWORD sRtsz; /* return variable size */
long RC; /* return code */
rc = SWSValue( &sConn, /* get query variable value*/
SWS_VALUE_VALUE, /* subfunction = retrieve */
sVana, /* null-terminated name */
SWS_NTS, /* indicate null-terminated*/
sBuff, /* return buffer address */
sizeof(sBuff), /* maximum buffer size */
&sRtsz ); /* actual size return area */
if (rc ^= SWS_SUCCESS) return; /* exit program if bad RC */
rc = SWSValue( &sConn, /* set new variable value */
SWS_VALUE_UPDATE, /* subfunction = set value */
sVana2, /* null-terminated name */
SWS_NTS, /* indicate null-terminated*/
sBuff, /* value information buffer */
sRtsz, /* size of value data */
NULL); /* Must be NULL for UPDATE */
if (rc ^= SWS_SUCCESS) return; /* exit program if bad RC */
Top
COBOL Example
77 SCONN USAGE IS POINTER.
77 SBUFF PIC X(80).
77 SBFSZ PIC S9(5) COMP VALUE 80.
77 SVANA PIC X(50) VALUE 'WWW.INPUTURL'.
77 SVANA2 PIC X(50) VALUE 'GLVEVENT.ABC'.
77 SVASZ PIC S9(5) COMP VALUE 50.
77 SRTSZ PIC S9(5) COMP.
*
* Obtain input URL value
*
CALL 'SWCPVL' USING SCONN,
SWS-VALUE-VALUE,
SVANA,
SVASZ,
SBUFF,
SBFSZ,
SRTSZ.
MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
IF NOT SWS-SUCCESS GOBACK.
*
* Set GLVEVENT.ABC to the same value
*
MOVE SRTSZ TO SBFSZ.
CALL 'SWCPVL' USING SCONN,
SWS-VALUE-UPDATE,
SVANA2,
SVASZ,
SBUFF,
SBFSZ.
MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
IF NOT SWS-SUCCESS GOBACK.
Top
|