Previous Topic
Table Of Contents
Parent Topic
Next Topic

High-Level Language SWSINFO (SWCPGI) 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 SWCPGI

SWSINFO is the Web Server API function used to fetch information about the current transaction execution environment and return it to the caller.

CALL Arguments

The SWSINFO function takes five arguments. All five arguments must be specified on the call.

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 binary integer indicating the information item to be returned by the function. Specify any one of the manifest constants, shown in the table below, to indicate the data item to be fetched.
3 UCHAR * PIC X(nnn) CHAR(nnn) Output The data buffer to receive the fetched information. Depending on the value of the second argument, the returned data may be a null-terminated string; a 16-bit integer value, a 32-bit flag-word value, or a 32-bit signed or unsigned integer.
4 SDWORD PIC S9(5) COMP FIXED BIN(31) Input The size of the data buffer area given by the third argument.
5 SDWORD * PIC S9(5) COMP FIXED BIN(31) Output Return area receiving the total size, in bytes, of the requested information value, regardless of whether the fetched value could be completely stored within the buffer area. For character format data items, which are null terminated, this value does not include the null termination byte.

For requests which return character data: If the total size of the requested information is greater than or equal to the size of the data buffer the returned character string is truncated, and a null termination byte is placed into the last available of the buffer area.

For requests which return any other data type: The value given by the forth argument is ignored. The size of the return buffer area is assumed to be at least four bytes.

The following table shows the values which can be specified for the second argument. Note that for COBOL, the value names contain hyphens instead of underbar characters.

Manifest Constant Value Returned  
SWS_GET_ASID Return the ASID as a 2-byte binary value.
SWS_GET_BYTES Return the number of saved bytes
SWS_GET_CLOCK Return the current TOD clock value as an 8-byte binary TOD format. Note that this is the unadjusted STCK value.
SWS_GET_CONNECTID Return the unique CONNECTION ID value as a 4-byte binary value.
SWS_GET_CPUDELTA Return the 8-byte task CPU time delta value.
SWS_GET_CPUTIME Return the 8-byte task CPU time value in TOD format. Divide by 4096 to get microseconds.
SWS_GET_DB2PLAN Return the DB2 plan name.
SWS_GET_DB2SUBSYS Return the DB2 subsystem name.
SWS_GET_EVENTTYPE Return an indication of the event type associated with the invocation of the rule/program.
SWS_GET_HOSTDOMAIN Return the host (server) domain associated with the current request.
SWS_GET_HOSTNAME Return the HOSTNAME (CLIENT) associated with the current request.
SWS_GET_HTTPDOMAIN Return a string containing the full server domain name, including the 'http://' prefix string, and TCP/IP port number. The port number is omitted if set to the standard HTTP port (80).
SWS_GET_HTTPSDOMAIN Return a string containing the full server domain name, including the 'https://' prefix string, and TCP/IP port number. The string returned can be used to construct HTML HREF tags which utilize an SSL connection. The port number is omitted in the string if set to the standard SSL HTTPS port (443).

A NULL string is returned if the server is not configured to support SSL connections.

SWS_GET_IPADDRESS Return the IP Address for the current connection. The returned value is 4-byte binary value.
SWS_GET_JOBNAME Return the MVS job name related to the current primary address space.
SWS_GET_LASTCONNECTID Return the last CONNECTION ID used on the current link.
SWS_GET_LASTUSERID Returns the last Userid used on the current link
SWS_GET_LINKTYPE Return the link type for the current request
SWS_GET_LU Return the LU NAME for the current request
SWS_GET_MAINPGM Return the name of the main REXX program or rule.
SWS_GET_MODE Return the mode name for the current request
SWS_GET_PRODUCT Return the Product Identification string
SWS_GET_PRODUCTSTATUS Returns the current product status
SWS_GET_PROGRAM Return the name of the REXX program or rule.
SWS_GET_ROWS Return the number of source rows
SWS_GET_SEFFEATURE Returns a single blank if SEF is not enabled.
SWS_GET_SUBSYS Return the accessed subsystem ID from the current OPMS image.
SWS_GET_SUBSYSASID Return the ASID of the active subsystem from the real OPMS as a two-byte binary value.
SWS_GET_SMFID Return the SMFID of the MVS system.
SWS_GET_TASKTYPE Return the task type.
SWS_GET_TRANSTYPE Return the transaction program type.
SWS_GET_USERID Return the Userid value.
SWS_GET_VERSION Return the version string of the product subsystem under which this rule/program is running. 

Top

Return Values

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

SWS_SUCCESS
The operation succeeded. The requested data has been fetched and placed into the buffer area. The actual size of the data is set into the sixth argument.
SWS_SUCCESS_WITH_INFO
The return buffer area was not large enough to store the fetched item. The fetched item was truncated. The size of the fetched item, before truncation, is returned to the sixth argument. For character data, a null termination byte is always placed into the last buffer position.
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 argument is invalid. No error information can be returned using SWSERROR.
 

PL/I Example

Note that SWSGETINFO may be used as an alias for the pre-processor symbol SWSINFO.


 
    DCL  SCONN     PTR;                 /* Connection Handle       */
    DCL  SBUFF     CHAR(256);           /* Return Buffer area      */
    DCL  SBFSZ     FIXED BIN(31) INIT(256);  /*  Size of buffer    */
    DCL  SRTSZ     FIXED BIN(31);       /* Actual item size        */
    DCL  RC        FIXED BIN(31);       /* return code             */
    DCL  DMHX      FIXED BIN(31) BASED; /* Dummy Handle field      */
 
    ADDR(SCONN)->DMHX = 0;              /* Clear Connection Handle */
 
    CALL SWSINFO( SCONN                 /* fetch the IP address    */
                  SWS_GET_IPADDRESS,
                  SBUFF,
                  SBFSZ,
                  SRTSZ );
    RC = PLIRETV();                     /* get return code         */
    IF RC ^= SWS_SUCCESS THEN           /* exit program if bad RC  */
       EXIT;
 

Top

C Example

Note that SWSGetInfo may be used as an alias for the pre-processor symbol SWSInfo.


 
    HDBC   sConn   = NULL;              /* Connection Handle       */
    char   sBuff[256];                  /* Return Buffer Area      */
    SDWORD sRTSZ;                       /* Return item size        */
    long   RC;                          /* return code             */
 
    rc = SWSInfo( &sConn,               /* obtain the IP Address   */
                  SWS_GET_IPADDRESS,
                  &sBuff[0],
                  (SDWORD) sizeof(sBuff),
                  &sRTSZ );
    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  SRTSZ                PIC S9(5) COMP.
 
 
    CALL 'SWCPGI' USING SCONN,
                  SWS-GET-IPADDRESS,
                  SBUFF,
                  SBFSZ,
                  SRTSZ.
    MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
    IF NOT SWS-SUCCESS GOBACK.
 

Top