Previous Topic Table Of Contents Parent Topic Next Topic |  | # High-Level Language SWSExciInitUsr (SWCPEI) 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 SWCPEI
SWSExciInitUsr is the Web Server API function used to initialize a CICS EXCI Connection. In order to execute a CICS Transaction using this interface, you will need to execute the following API calls in the sequence listed below
Service Name | Service Description
--- | ---
SWSExciInitUsr | To initialize the CICS EXCI connection
SWSExciConnect | To connect to CICS through the EXCI interface
SWSExciDplReq | To issue a DPL request to CICS This API may be called repetitively in order to complete the processing required for the transaction.
SWSExciDisconn | To disconnect a CICS EXCI connection
## SWCPEI Call Arguments The SWSExciInitUsr (SWCPEI) function arguments are described in the table which follows. All parameters are required.
Arg. No. | HLL Argument Type | I/O | Description of Argument
--- | --- | --- | ---
C | COBOL | PL/I
1 | LONG | PIC S9(5) COMP | FIXED BIN(31) | Input | Statement Handle. Currently ignored however, it must contain zeros.
2 | LONG | PIC S9(5) COMP | FIXED BIN(31) | Input | CICS Connection Type. Must be set to SWS-CICS-TYPE-EXCI or SWS-CICS-TYPE-NEON. The "NEON" type is currently not supported.
3 | CHAR * | PIC X(4) | CHAR(4) | Input | CICS Connection Name. A field containing the name of a Defined Connection. The Connection Name must be defined (using the "DEFINE CONNECTION" command) in the Shadow OS/390 Web Server startup exec (SWS_IN00).
4 | exci_return_code * | EXCI-RETURN-CODE | EXCI_RETURN_CODE | Output | The CICS EXCI Return Code Copybook layout for the output return code area.
5 | LONG | PIC S9(5) COMP | FIXED BIN(31) | Output | User Token.

Top

## Return Values

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

SWS_SUCCESS
  The operation succeeded. The specified operation was performed.
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.
Any other value
  The operation failed. By using the SWSERROR interface, you may obtain the error message pertinent to the error.

## PL/I Example

        %INCLUDE DFHXCPLL
        %INCLUDE DFHXCRCL
        %INCLUDE SPCPHD
           .
           .
           .
           .
        DCL  STMTHDL         FIXED BIN(31);        /* Statement Handle */
        DCL  USER_TOKEN      FIXED BIN(31);        /* User Token       */
        DCL  CONNECTION_NAME       CHAR(4);        /* Connection Name  */
        DCL  RC              FIXED BIN(31);        /* RETURN CODE      */

        CONNECTION_NAME = 'EWST'                   /* SET name         */

        CALL SWSEXCIINITUSR(STMTHDL,        /* STATEMENT HANDLE        */
                      SWS_CICS_TYPE_EXCI,   /* connection type         */
                      CONNECTION_NAME,      /* connection name         */
                      EXCI_RETURN_CODE,     /* cics exci return area   */
                      USER_TOKEN)           /* user token              */

        RC = PLIRETV();                     /* GET RETURN CODE         */
        IF RC ^= SWS_SUCCESS THEN           /* EXIT PROGRAM IF BAD RC  */
           EXIT;

Top

## C Example

NOTE: The Neon Header file must be included after the CICS EXCI headers.

        #include "dfhxcplh.h"               /* CICS Return Area header */
        #include "dfhxcrch.h"               /* CICS Response Codes     */
        #include "sccphd.h"                 /* Neon headers            */

        exci_return_code exciRET;           /* cics exci return area   */
           .
           .
           .
           .
        long RC;                            /* return code             */
        long stmtHDL;                       /* statement handle        */
        long userTOKEN;                     /* user token              */
        char connection_name[] = "EWST";    /* Connection Name         */

        CALL SWSExciInitUsr(stmtHDL,            /* statement handle       */
                            SWS_CICS_TYPE_EXCI, /* connection type        */
                            connection_name,    /* connection name        */
                            exciRET,            /* cics exci return area  */
                            userTOKEN)          /* user token             */

        if (rc ^= SWS_SUCCESS)
             return rc;

Top

## COBOL Example

         COPY DFHXCPLO.                      CICS EXCI Return Areas
         COPY DFHXCRCO.                      CICS EXCI Response Codes
         COPY SBCPHD.                        Neon Copybook
             .
             .
             .
             .
         77 CONNECTION-NAME         PIC X(4) VALUE IS 'EWST'.
         77 STATEMENT-HANDLE        USAGE IS POINTER.
         77 USER-TOKEN              PIC S9(5) COMP VALUE IS ZERO.
             .
             .
             .
             .

         SET SWS-CICS-TYPE-EXCI TO TRUE.
         CALL 'SWCPEI' USING STATEMENT-HANDLE
                             SWS-CICS-TYPE
                             CONNECTION-NAME
                             EXCI-RETURN-CODE
                             USER-TOKEN.

         MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
         IF NOT SWS-SUCCESS
             GOBACK.

Top