Previous Topic Table Of Contents Parent Topic Next Topic |  | # High-Level Language SWSSET (SWCPSO) Function Related Topics Web Server API Function Index
| May be used in Shadow/REXX. See RETURN RESCAN or RETURN FLUSH.
| May be used from Other REXX Interpreters.
| High-Level Language entry point name is SWCPSO.
The SWSSET built-in function allows the caller to control various run-time environmental options. Following is a list of functions that may be specified:
Function Name | Description
--- | ---
SWS_OPTION_RESCAN | This function provides a new URL value which the Server will use during the rescan operation. The rescan operation does not actually begin until after the current application program terminates normally. The rescan function provides high-level language programs with an equivalent functionality which the Shadow/REXX Interpretor intrinsically provides. For Shadow/REXX, the equivalent function is performed by using the RESCAN option of the RETURN statement.
SWS_OPTION_FLUSH | This function allows the user to send the current "buffered" output. This function will normally occur after the current application program terminates normally.
SWS_OPTION_NOFLUSH | This function allows the user to inhibit the sending of the "buffered" output. This function will occur after the current application program terminates normally.
SWS_OPTION_SENDTRACE | This function allows the user to specify the output tracing option.
SWS_OPTION_PARSETRACE | This function allows the user to specify the URL tracing option.
SWS_OPTION_RESPMODE | This function allows the user to specify the server parsing mode.
SWS_OPTION_DPRTY | This function allows the user to adjust the current processing priority of their TCB within the Shadow Server address space. This may be a positive or negative whole number which will be added to the TCB's current dispatching priority.
SWS_OPTION_AUTOFLUSH | This function allows the user to specify the maximum number of buffers to allow before automatically sending them. Value must be specified as a whole number between 0 and 32767.
SWS_OPTION_MAXRESPBYTES | This function allows the user to specify the maximum number of bytes that can be sent in response to a single URL. Value must be specified as a whole number between 0 and 2147483647.
SWS_OPTION_MAXRESPBUFFERS | This function allows the user to specify the maximum number of buffers that can be sent in response to a single URL. Value must be specified as a whole number between 0 and 32767.
SWS_OPTION_USERDATA1 | This function allows the user to specify information to be added to the Shadow OS/390 Web Server SMF record.
SWS_OPTION_USERDATA2 | This function allows the user to specify information to be added to the Shadow OS/390 Web Server SMF record. This option may only be executed from a WWW Master rule.
SWS_OPTION_ASCIIEBCDICMAP | This function allows the user to specify a language conversion value to be used for translating any subsequent output generated by this rule.
## CALL Arguments The SWSSET function takes four arguments.
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 flag word indicating the function which the SWSSET invocation should perform. You must specify one of the aforementioned functions for this parameter.
3 | PTR | PIC X(nnn) | CHAR(nnn) | Input | The data value to be set. The format of this argument varies, depending on the value supplied for the second argument.
Function | Value
--- | ---
SWS_OPTION_RESCAN | Specify a 1-to-128 byte URL rescan value. The rescan URL value may be a null terminated string.
SWS_OPTION_FLUSH | Parameter not required.
SWS_OPTION_NOFLUSH | Parameter not required.
SWS_OPTION_SENDTRACE | YES to turn the option on. NO to turn the option off.
SWS_OPTION_RESPMODE | NONE for Non-parsed headers. SERVER for Server-parsed headers.
SWS_OPTION_DPRTY | A value from -255 to 255.
SWS_OPTION_AUTOFLUSH | A value from 0 to 32767.
SWS_OPTION_MAXRESPBYTES | A value from 0 to 2147483647.
SWS_OPTION_MAXRESPBUFFERS | A value from 0 to 32767.
SWS_OPTION_PARSETRACE | YES to turn the option on. NO to turn the option off.
SWS_OPTION_USERDATA1 | Any text string from 1 to 256 bytes long.
SWS_OPTION_USERDATA2 | Any text string from 1 to 256 bytes long.
SWS_OPTION_ASCIIEBCDICMAP | Any valid 3 or 4 character language code string.
4 | SDWORD | PIC S9(5) COMP | FIXED BIN(31) | Input | This argument specifies the size of the function data given by the third argument. The required size varies depending on the function specified by the second argument. If the data specified as parameter 3 is a null-terminated string, you may specify the manifest constant `SWS_NTS`.

Top

## Return Values

SWSSET always sets a signed numeric return code value. Possible values are:

SWS_SUCCESS
  The operation succeeded.
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_INVALID_HANDLE
  The connection handle is invalid. No error information is available.

## PL/I Example

        DCL  TCONN     PTR;                 /* Connection Handle       */
        DCL  TDATA     CHAR(256);           /* data buffer area        */
        DCL  TSIZE     FIXED BIN(31);       /* data length             */
        DCL  RC        FIXED BIN(31);       /* return code             */
        DCL  DMHX      FIXED BIN(31) BASED; /* Dummy Handle field      */

        ADDR(TCONN)->DMHX = 0;              /* Clear Connection Handle */

        TDATA    = 'SYSTEM/ERROR/500';      /* Set rescan URL value    */
        TSIZE    = 16;                      /* set length              */
        CALL SWSSET( TCONN                  /* Set rescan URL value    */
                     SWS_OPTION_RESCAN,
                     TDATA,
                     TSIZE );

        RC = PLIRETV();                     /* get return code         */
        IF RC ^= SWS_SUCCESS THEN           /* if bad RC, then go      */
           GOTO ERROR_LABEL;                /* report the error or     */
                                            /* abort the transaction   */

        CALL PLIRETC(0);                    /* Rescan URL is set up, so*/
        RETURN(0);                          /* let Server do re-match  */

        Other function call formats:

            CALL SWSSET( TCONN
                         SWS_OPTION_FLUSH);

            CALL SWSSET( TCONN
                         SWS_OPTION_NOFLUSH);

            TSIZE    = 3;
            CALL SWSSET( TCONN,
                         SWS_OPTION_SENDTRACE,
                         SWS_OPTION_YES,
                         TSIZE );

            TSIZE    = 2;
            CALL SWSSET( TCONN,
                         SWS_OPTION_PARSETRACE,
                         SWS_OPTION_NO,
                         TSIZE );

            TSIZE    = 4;
            CALL SWSSET( TCONN,
                         SWS_OPTION_RESPMODE,
                         SWS_OPTION_NONE,
                         TSIZE );

            TDATA    = '5'
            TSIZE    = 1;
            CALL SWSSET( TCONN,
                         SWS_OPTION_DPRTY,
                         TDATA,
                         TSIZE );

            TDATA    = '100'
            TSIZE    = 3;
            CALL SWSSET( TCONN,
                         SWS_OPTION_AUTOFLUSH,
                         TDATA,
                         TSIZE );

            TDATA    = '32000'
            TSIZE    = 5;
            CALL SWSSET( TCONN,
                         SWS_OPTION_MAXRESPBYTES,
                         TDATA,
                         TSIZE );

            TDATA    = '55';
            TSIZE    = 2;
            CALL SWSSET( TCONN,
                         SWS_OPTION_MAXRESPBUFFERS,
                         TDATA,
                         TSIZE );

            TDATA    = 'USER DATA MESSAGE';
            TSIZE    = 17;
            CALL SWSSET( TCONN,
                         SWS_OPTION_USERDATA1,
                         TDATA,
                         TSIZE );

            TDATA    = 'SECURED USER DATA MESSAGE';
            TSIZE    = 25;
            CALL SWSSET( TCONN,
                         SWS_OPTION_USERDATA2,
                         TDATA,
                         TSIZE );

            TDATA    = 'FRA2'
            TSIZE    = 4;
            CALL SWSSET( TCONN,
                         SWS_OPTION_ASCIIEBCDICMAP,
                         TDATA,
                         TSIZE );

Top

## C Example

        HDBC tConn   = NULL;                /* Connection Handle       */
        char tData[] = "SYSTEM/ERROR/500";  /* rescan URL value        */
        long RC;                            /* return code             */

        rc = SWSSet( &tConn,                /* set rescan URL value    */
                     SWS_OPTION_RESCAN,
                     tdata,
                     strlen(tdata) );

        if (rc ^= SWS_SUCCESS) return;      /* if bad RC from SWSSET   */
        {                                   /* perform some appl-dep.  */
           ...                              /* error recovery or abort */
        };                                  /* processing.             */
        else                                /* Otherwise, URL is set so*/
           return 0;                        /* let Server do re-match  */

        Other function call formats:

            rc = SWSSet( &tConn,
                         SWS_OPTION_FLUSH);

            rc = SWSSet( &tConn,
                         SWS_OPTION_NOFLUSH);

            rc = SWSSet( &tConn,
                         SWS_OPTION_SENDTRACE,
                         SWS_OPTION_NO,
                         strlen(SWS_OPTION_NO));

            rc = SWSSet( &tConn,
                         SWS_OPTION_PARSETRACE,
                         SWS_OPTION_NO,
                         strlen(SWS_OPTION_NO));

            rc = SWSSet( &tConn,
                         SWS_OPTION_RESPMODE,
                         SWS_OPTION_SERVER,
                         strlen(SWS_OPTION_SERVER));

            char tData[] = "-40";
            rc = SWSSet( &tConn,
                         SWS_OPTION_DPRTY,
                         tdata,
                         strlen(tdata) );

            char tData[] = "50";
            rc = SWSSet( &tConn,
                         SWS_OPTION_AUTOFLUSH,
                         tdata,
                         strlen(tdata) );

            char tData[] = "2000000";
            rc = SWSSet( &tConn,
                         SWS_OPTION_MAXRESPBYTES,
                         tdata,
                         strlen(tdata) );

            char tData[] = "80";
            rc = SWSSet( &tConn,
                         SWS_OPTION_MAXRESPBUFFERS,
                         tdata,
                         strlen(tdata) );

            char tData[] = "USER DATA MESSAGE";
            rc = SWSSet( &tConn,
                         SWS_OPTION_USERDATA1,
                         tdata,
                         strlen(tdata) );

            char tData[] = "SECURED USER DATA MESSAGE";
            rc = SWSSet( &tConn,
                         SWS_OPTION_USERDATA2,
                         tdata,
                         strlen(tdata) );

            char tData[] = "FRA2";
            rc = SWSSet( &tConn,
                         SWS_OPTION_ASCIIEBCDICMAP,
                         tdata,
                         strlen(tdata) );

## COBOL Example

        77  TCONN                USAGE IS POINTER.
        77  TDATA                PIC X(128).
        77  TSIZE                PIC S9(5) COMP.

        MOVE 'SYSTEM/ERROR/500' TO TDATA.
        MOVE 16                 TO TSIZE.

        CALL 'SWCPSO' USING TCONN,
                      SWS-OPTION-RESCAN,
                      TDATA,
                      TSIZE.
        MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.

        IF NOT SWS-SUCCESS PERFORM 9999-ABORT-PROCEDURE.

        MOVE 0 to RETURN-CODE.
        GOBACK.

        Other function call formats:

            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-FLUSH.

            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-NOFLUSH.

            MOVE 3                  TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-SENDTRACE,
                      SWS-OPTION-YES,
                      TSIZE.

            MOVE 2                  TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-PARSETRACE,
                      SWS-OPTION-NO,
                      TSIZE.

            MOVE 4                  TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-RESPMODE,
                      SWS-OPTION-NONE,
                      TSIZE.

            MOVE '-17'              TO TDATA.
            MOVE 3                  TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-DPRTY,
                      TDATA,
                      TSIZE.

            MOVE '100'              TO TDATA.
            MOVE 3                  TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-AUTOFLUSH,
                      TDATA,
                      TSIZE.

            MOVE '100000'           TO TDATA.
            MOVE 6                  TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-MAXRESPBYTES,
                      TDATA,
                      TSIZE.

            MOVE '255'              TO TDATA.
            MOVE 3                  TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-MAXRESPBUFFERS,
                      TDATA,
                      TSIZE.

            MOVE 'USER DATA MESSAGE' TO TDATA.
            MOVE 17                  TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-USERDATA1,
                      TDATA,
                      TSIZE.

            MOVE 'SECURED USER DATA MESSAGE' TO TDATA.
            MOVE 25                          TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-USERDATA2,
                      TDATA,
                      TSIZE.

            MOVE 'FRA2'                        TO TDATA.
            MOVE 4                             TO TSIZE.
            CALL 'SWCPSO'
                USING TCONN,
                      SWS-OPTION-ASCIIEBCDICMAP,
                      TDATA,
                      TSIZE.

Top