High-Level Language SWSVALUE (SWCPVL) Function
Related Topics
 |
May be used in Shadow/REXX |
| |
May be used from Other REXX Interpreters |
| |
HLL entry point name is SWCPVL |
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.
|
| 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. |
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;
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 */
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.