Previous Topic Table Of Contents Parent Topic Next Topic |  | # High-Level Language SWSVALUE (SWCPVL) 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 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. 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