High-Level Language SWSExciDplReq (SWCPED) Function
Related Topics
 |
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. |
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;
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;
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.