Previous Topic Table Of Contents Parent Topic Next Topic |  | # High-Level Language SWSExciDplReq (SWCPED) 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 SWCPED
SWSExciDplReq is the Web Server API function used to disconnect 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
## SWCPED Call Arguments The SWSExciDplReq (SWCPED) 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 | CHAR * | PIC X(4) | CHAR(4) | Input | CICS Transaction Name. The name of the mirror transaction with which the target program is to run.
5 | exci_return_code * | EXCI-RETURN-CODE | EXCI_RETURN_CODE | Output | The CICS EXCI Return Code Copybook layout for the output return code area.
6 | CHAR * | PIC X(4) | CHAR(4) | Input | CICS Program Name. The program to run and interact with the DPL request.
7 | CHAR * | PIC X(1 - 32704) | CHAR(1 - 32704) | Input/Output | CICS COMMAREA
8 | LONG | PIC S9(5) COMP | FIXED BIN(31) | Input | CICS COMMAREA Length. The total length of the COMMAREA.
9 | LONG | PIC S9(5) COMP | FIXED BIN(31) | Input | Input data length. The total length of the data within the COMMAREA.
11 | CHAR * | PIC X(8) | CHAR(8) | Input | User ID. This is used as a work field and should be spaces upon entry to the API call.
12 | LONG | PIC S9(5) COMP | FIXED BIN(31) | Input | User Token.
13 | LONG | PIC S9(5) COMP | FIXED BIN(31) | Input | Pipe Token.
14 | exci_dpl_retarea * | EXCI-DPL-RETAREA | EXCI_DPL_RETAREA | Output | The CICS EXCI DPL Return area Copybook layout for the output return area.

Top

## Return Values

SWSExciDplReq 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  PIPE_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 SWSEXCIDPLREQ(STMTHDL             /* STATEMENT HANDLE       */
                           SWS_CICS_TYPE_EXCI, /* CONNECTION TYPE        */
                           CONNECTION_NAME,    /* CONNECTION NAME        */
                           TRANS_ID,           /* TRANSACTION ID         */
                           EXCI_RETURN_CODE,   /* CICS EXCI RETURN AREA  */
                           PROGRAM_NAME,       /* PROGRAM NAME           */
                           COMMAREA,           /* COMMAREA               */
                           SIZEOF(COMMAREA),   /* COMMAREA LENGTH        */
                           STRLEN(COMMAREA),   /* COMMAREA LENGTH        */
                           NULL,               /* UNIT OF WORK ID AREA   */
                           USER_ID,            /* USER ID                */
                           USERTOKEN,          /* USER TOKEN             */
                           PIPETOKEN,          /* PIPE TOKEN             */
                           EXCI_DPL_RETAREA)   /* DPL RETURN CODE AREA   */

        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     */
        exci_dpl_retarea exciDPL;           /* cics exci DPL return area */
           .
           .
           .
           .
        long RC;                            /* return code             */
        long stmtHDL;                       /* statement handle        */
        long userTOKEN;                     /* user token              */
        long pipeTOKEN;                     /* user token              */
        char commarea[32704];               /* Connection Name         */
        char connection_name[] = "EWST";    /* Connection Name         */
        char trans_id[] = "EXCI";           /* Transaction id          */
        char user_id[] = "        ";        /* userid                  */

        CALL SWSExciDplReq(stmtHDL,            /* statement handle       */
                           SWS_CICS_TYPE_EXCI, /* connection type        */
                           connection_name,    /* connection name        */
                           trans_id,           /* transaction id         */
                           exciRET,            /* cics exci return area  */
                           program_name,       /* program name           */
                           commarea,           /* commarea               */
                           sizeof(commarea),   /* commarea length        */
                           strlen(commarea),   /* commarea length        */
                           NULL,               /* unit of work id area   */
                           user_id,            /* user id                */
                           userTOKEN,          /* user token             */
                           pipeTOKEN,          /* pipe token             */
                           exciDPL)            /* DPL Return Code Area   */

        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 TRANS-ID                PIC X(4) VALUE IS 'EXCI'.
         77 PROGRAM-NAME            PIC X(8) VALUE IS 'DFH$AXCS'.
         77 FILL-8                  PIC X(8) VALUE IS SPACES.
         77 STATEMENT-HANDLE        USAGE IS POINTER.
         77 USER-TOKEN              PIC S9(5) COMP VALUE IS ZERO.
         77 PIPE-TOKEN              PIC S9(5) COMP VALUE IS ZERO.
         77 CICS-BUFFER-INPUT-LENGTH PIC S9(5) COMP VALUE IS ZERO.
         77 CICS-BUFFER-COMMAREA-LENGTH  PIC S9(5) COMP VALUE IS ZERO.
         01 UOWID                   USAGE IS POINTER.
         01 CICSBUFFER.
           05 CICS-BUFFER-COMMAREA.
             10 CICS-BUFFER-COMMAREA-RETURNCD  PIC S9(5) COMP.
             10 CICS-BUFFER-COMMAREA-FILENAME  PIC X(8).
             10 CICS-BUFFER-COMMAREA-RIDFIELD  PIC X(6).
             10 CICS-BUFFER-COMMAREA-RECORD    PIC X(512).
             .
             .
             .
             .

         SET SWS-CICS-TYPE-EXCI TO TRUE.
         CALL 'SWCPED' USING STATEMENT-HANDLE
                             SWS-CICS-TYPE
                             CONNECTION-NAME
                             TRANS-ID
                             EXCI-RETURN-CODE
                             PROGRAM-NAME
                             CICS-BUFFER-COMMAREA
                             CICS-BUFFER-COMMAREA-LENGTH
                             CICS-BUFFER-INPUT-LENGTH
                             UOWID
                             FILL-8
                             USER-TOKEN
                             PIPE-TOKEN
                             EXCI-DPL-RETAREA.

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

Top