Previous Topic
Table Of Contents
Parent Topic
Next Topic

High-Level Language SWSExciConnect (SWCPEC) 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 SWCPEC

SWSExciConnect is the Web Server API function used to create 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

SWCPEC Call Arguments

The SWSExciConnect (SWCPEC) function arguments are described in the table which follows. All parameters are required.

Arg. No.	HLL Argument Type			I/O	Description of Argument
Arg. No.	C	COBOL	PL/I	I/O	Description of Argument
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)	Input	User Token.
6	LONG	PIC S9(5) COMP	FIXED BIN(31)	Output	Pipe Token.

Top

Return Values

SWSExciConnect 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 SWSEXCICONNECT(STMTHDL         /* STATEMENT HANDLE        */
                  SWS_CICS_TYPE_EXCI,   /* connection type         */
                  CONNECTION_NAME,      /* connection name         */
                  EXCI_RETURN_CODE,     /* cics exci return area   */
                  USER_TOKEN,           /* user token              */
                  PIPE_TOKEN)           /* pipe 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              */
    long pipeTOKEN;                     /* user token              */
    char connection_name[] = "EWST";    /* Connection Name         */
 
    CALL SWSExciConnect(stmtHDL,            /* statement handle       */
                        SWS_CICS_TYPE_EXCI, /* connection type        */
                        connection_name,    /* connection name        */
                        exciRET,            /* cics exci return area  */
                        userTOKEN,          /* user token             */
                        pipeTOKEN)          /* pipe 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.
    77 PIPE-TOKEN              PIC S9(5) COMP VALUE IS ZERO.
        .
        .
        .
        .
 
    SET SWS-CICS-TYPE-EXCI TO TRUE.
    CALL 'SWCPEC' USING STATEMENT-HANDLE
                        SWS-CICS-TYPE
                        CONNECTION-NAME
                        EXCI-RETURN-CODE
                        USER-TOKEN
                        PIPE-TOKEN.
 
    MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
    IF NOT SWS-SUCCESS
        GOBACK.

Top