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