CICS® provides a number of sample programs that are designed to help you in writing your own application programs. To help with writing programs that use the external CICS interface, CICS provides sample MVS™ client programs and a sample CICS server program.
The samples show you how to code client applications that use both the EXCI CALL interface and EXEC CICS LINK command.
The sample external CICS interface programs are included on the CICS Transaction Server for z/OS distribution tape.
Two sample MVS client programs are supplied. One is provided in assembler language, COBOL, C, and PL/I. The other is only provided in assembler. The sample CICS server program is provided in assembler only. Assembler language programs are in source and executable form. COBOL, PL/I, and C programs are provided in source form only. Each version of the client program has basically the same function, but programming methods vary somewhat according to the language used.
The sample programs, shown in Table 23, are supplied in source form in CICSTS31.CICS.SDFHSAMP. The sample assembler server program is also supplied in executable form in CICSTS31.CICS.SDFHLOAD. The assembler client program is supplied in CICSTS31.CICS.SDFHEXCI.
Language | Name | Type of program |
---|---|---|
Assembler | DFH$AXCC | Client program |
Assembler | DFH$ATXC | Client program |
Assembler | DFH$AXCS | Server program |
COBOL | DFH0CXCC | Client program |
PL/I | DFH$PXCC | Client program |
C | DFH$DXCC | Client program |
The sample client programs show you how to code a simple MVS client application using the EXCI CALL interface and the EXEC CICS LINK command.
Each version of the client is divided into three separate sections as follows:
If the file is in a suitable state, processing continues to sections two and three, which together provide complete examples of the use of the EXCI CALL interface.
Some of the parameters used on the EXCI CALL and EXEC CICS LINK commands in the client program need to be tailored for your own target CICS server region. Change these as required, then retranslate, compile (or assemble), and link-edit the program.
The variables and their values specified in the sample programs are given in Table 24.
Variable name in sample program | Default value |
---|---|
TARGET_FILE | FILEA |
TARGET_TRANSID | EXCI |
TARGET_SYSTEM | DBDCCICS (applid) |
TARGET_PROGRAM | DFH$AXCS |
TARGET_USERID | Defaults to batch region's user ID |
APPLICATION | BATCHCLI |
The assembler versions of the client programs are supplied pregenerated in an executable form. All versions of the program accept two run-time parameters, as follows:
For the pregenerated assembler versions this avoids you having to reassemble the programs to specify the applid of your own CICS server region. You can also use the sample client programs with different CICS regions without needing to modify the programs each time.
You specify these positional parameters on the PARM statement, separated by a comma.
Data is passed between the sample client and server programs using a standard CICS communications area (COMMAREA) for passing data between programs. The definitions of this COMMAREA are identical on each side of the EXCI link to ensure that data is mapped correctly.
The sample client program DFH$AXCC minimizes data transmission by specifying a specific data length to avoid sending the whole COMMAREA over the link. The data length option specifies a binary value that is the length of a contiguous area of storage, from the start of the COMMAREA, to be passed to the server program. This is because the amount of data being passed to the server is small, but the COMMAREA itself is much larger so that the server can return the requested records from FILEA. Specifying a data length when the amount of data being passed is smaller than the COMMAREA improves performance.
Sample program DFH$ATXC passes the full COMMAREA to the server program because it makes changes to the file records and the whole of the changed record needs to be passed to the server.
The first and third sections of the sample client programs define the COMMAREA as only 18 bytes (no data is requested from the server in these sections). For the second section, the sample client program defines the COMMAREA as 98 bytes, the extra 80 bytes being required for the sample server program to return a record from FILEA. In all sections, the data length is defined as 18 bytes. The COMMAREA structure is defined in the sample programs as follows:
Bytes | Data type | Field description |
---|---|---|
0-3 | Fullword | Call type code. |
4-11 | Char(8) | Target file name. |
12-17 | Char(6) | Ridfield identifier. |
18-97 | Char(80) | FILEA record data area. |
Note that, although the COMMAREA structure is described in both the client and server programs, the actual size of the COMMAREA made available by CICS to the server is determined by the client program. If you modify the sample programs to work with one of your own application programs, make sure you specify a COMMAREA large enough to handle the maximum amount of data the server is expected to return to the client. The server must not attempt to return data that is larger than the COMMAREA specified by the client.
For more information about using a COMMAREA for passing data between CICS programs, see the CICS Application Programming Guide.
Resource definitions that support the EXCI sample programs are included in the CICS system definition file (CSD) in groups DFH$EXCI and DFH$FILA.
Note that the sample definitions, while included in the CSD, are not included in the IBM-defined group list DFHLIST. Thus, if CICS is initialized with GRPLIST=DFHLIST, you must install the EXCI resource definition groups before using the samples. Alternatively, you can add the sample groups to your startup group list, so that they are installed automatically at system initialization.
Transactions that are to be linked to from the batch program need
to specify the mirror program (DFHMIRS) as the program name in their transaction
definitions.
The resource definition groups that must be installed are as follows:
Only one server program is included--in assembler language, called DFH$AXCS.
The sample application is designed to run the transaction EXCI, which is defined to invoke the DFHMIRS mirror program and references profile DFHCICSA. The required transaction definition for EXCI is included in the group.
Sample CONNECTION and SESSIONS definitions for specific and generic connections are included.
If you want to run the external CICS interface sample programs without any security active, you must alter the connection resource definitions to specify ATTACHSEC(LOCAL).
Once these are installed, you must ensure that interregion communication (IRC) is open. If IRC is not opened during CICS initialization, set it open using the CEMT SET IRC OPEN command.
If you want to use the COBOL, PL/I, or C version of the EXCI client program, you must translate, compile, and link-edit the program into a suitable library.
You can use the sample JCL shown in Figure 22 as a basis for creating your own batch job to run the client program.
If you use the pregenerated assembler version, specify the APPLID of your target CICS server region as a parameter on the EXEC statement for the client program, as follows:
//*===============================================================*
//ASM EXEC PGM=DFH$AXCC,PARM='applid,userid'
Where: applid is the applid of the CICS server region userid is the userid for the DPL_request call. Note: If you omit applid, you must keep the comma preceding the userid.
Change PGM=DFH$AXCC to PGM=DFH$ATXC to run the other client sample program.
An example of the output produced by successful execution of the pregenerated assembler version of the client program, DFH$AXCC, is shown in Figure 23.
*===================== EXCI Sample Client Program =============================*
* *
* EXEC Level Processor. *
* Setting up the EXEC level call. *
* The Link Request has successfully completed. *
* Server Response: *
* The file is set to a browsable state. *
* *
* CALL Level Processor. *
* Initialize_User call complete. *
* Allocate_Pipe call complete. *
* Open_Pipe call complete. *
* The connection has been successful. *
* The target file follows: *
* *
*=========================== Top of File ======================================*
000102F. ALDSON WARWICK, ENGLAND 9835618326 11 81$1111.11Y00007300
000104S. BOWLER LONDON,ENGLAND 1284629326 11 81$0999.99Y00007400
000106B. ADAMS CROYDON, ENGLAND 1948567326 11 81$0087.71Y00007500
000111GENE BARLOWE SARATOGA,CALIFORNIA 4612075301 02 74$0111.11Y00007600
000762GEORGE BURROW SAN JOSE,CALIFORNIA 2231212101 06 74$0000.00Y00007700
000983H. L. L. CALL WASHINGTON, DC 3451212021 04 75$9999.99Y00007800
003210B.CREPIN NICE, FRANCE 1234567026 11 81$3349.99Y00008100
003214HUBERT C HERBERT SUNNYVALE, CAL. 3411212000 06 73$0009.99N00008200
003890PHILIPPE SMITH, JR NICE, FRANCE 0000000028 05 74$0009.99N00008300
004004STAN SMITH DUBLIN, IRELAND 7111212102 11 73$1259.99N00008400
004445S. GALSON SOUTH BEND, S.DAK. 6121212026 11 81$0009.99N00008500
004878D.C. CURRENT SUNNYVALE, CALIF. 3221212010 06 73$5399.99N00008600
005005J. S. LAVERENCE SAN FRANCISCO, CA. 0000000101 08 73$0009.99N00008700
005444JEAN LAWRENCE SARATOGA, CALIF. 6771212020 10 74$0809.99N00008800
005581JOHN ALDEN III BOSTON, MASS. 4131212011 04 74$0259.99N00008900
006016DR W. T. KAR NEW DELHI, INDIA 7033121121 05 74$0009.88Y00009000
006670WILLIAM KAPP NEW YORK, N.Y. 2121212031 01 75$3509.88N00009100
06968D. CONRAD WARWICK, ENGLAND 5671382126 11 81$0009.88Y00009200
007248B. C. WILLIAMSON REDWOOD CITY, CALF. 3331212111 10 75$0009.88N00009400
007779MRS. W. WELCH SAN JOSE, CALIF. 4151212003 01 75$0009.88Y00009500
100000G. NEADS TORONTO, ONTARIO 0341512126 11 81$0010.00Y00009600
111111C. MEARS OTTAWA, ONTARIO 5121200326 11 81$0011.00Y00009700
200000A. BONFIELD GLASCOW, SCOTLAND 6373829026 11 81$0020.00Y00009900
300000K. TRENCHARD NEW YORK, U.S. 6473980126 11 81$0030.00Y00010000
333333D. MYRING CARDIFF, WALES 7849302026 11 81$0033.00Y00010100
400000W. TANNER MILAN, ITALY 2536373826 11 81$0040.00Y00010200
444444A. FISHER CALGARY, ALBERTA 7788982026 11 81$0044.00Y00010300
500000J. DENFORD MADRID, SPAIN 4445464026 11 81$0000.00Y00010400
555555C. JARDINE KINGSTON, N.Y. 3994442026 11 81$0005.00Y00010500
600000F. HUGHES DUBLIN, IRELAND 1239878026 11 81$0010.00Y00010600
666666A. BROOKMAN LA HULPE, BRUSSELS 4298384026 11 81$0016.00Y00010700
700000A. MACALLA DALLAS, TEXAS 5798432026 11 81$0002.00Y00010800
777777D. PRYKE WILLIAMSBURG, VIRG. 9187613126 11 81$0027.00Y00010900
800000H. BRISTOW WESTEND, LONDON 2423338926 11 81$0030.00Y00011000
888888B. HOWARD NORTHAMPTON, ENG. 2369163926 11 81$0038.00Y00011100
900000D. WOODSON TAMPA, FLA. 3566812026 11 81$0040.00Y00011200
999999R. JACKSON RALEIGH, N.Y. 8459163926 11 81$0049.00Y00011300
*=========================== End of File ======================================*
* *
* Closing Dpl Request has been attempted. *
* Close_Pipe call complete. *
* Deallocate_Pipe call complete. *
* *
*=================== End of EXCI Sample Client Program ========================*
*===================== EXCI Sample Client Program =============================*
* *
* EXEC Level Processor. *
* Setting up the EXEC level call. *
* The Link Request has failed. Return codes are; *
* Resp = 00000088 Resp2 = 00000203 Abend Code: *
* >>>> Aborting further processing <<<< *
* *
*=================== End of EXCI Sample Client Program ========================*
*===================== EXCI Sample Client Program =============================*
* *
* EXEC Level Processor. *
* Setting up the EXEC level call. *
* The Link Request has successfully completed. *
* Server Response: *
* The file could not be found. *
* >>>> Aborting further processing <<<< *
* *
*=================== End of EXCI Sample Client Program ========================*
*===================== EXCI Sample Client Program =============================*
* *
* EXEC Level Processor. *
* Setting up the EXEC level call. *
* The Link Request has failed. Return codes are; *
* Resp = 00000088 Resp2 = 00000414 Abend Code: *
* A message was received from the target CICS system: *
* *
DFHAC2001 04/29/93 16:43:03 IYAHZCAZ Transaction 'BAD_' is unrecognized. Check
that the transaction name is correct.
* *
* >>>> Aborting further processing <<<< *
* *
*=================== End of EXCI Sample Client Program ========================*
If an error occurs while running the application, then, assuming the error is not severe, messages are written to the SYSPRINT output log displaying the reasons and/or return codes that cause processing to be aborted. Several examples of error-invoked output are shown in Figure 24, Figure 25, and Figure 26.
An example of the output produced by a successful execution of the pregenerated assembler version of the client program DFH$ATXC is shown in Figure 27. If an error occurs while running the application, errors are produced as for DFH$AXCC.
After running DFH$ATXC, program DFH$AXCC should be re-run. The output should be as shown in Figure 28. The changes up to and including records with RIDFLD values of 500000 were committed using an SRRCMIT call to tell RRS to tell CICS to perform commit processing. Later changes were backed out by issuing an SRRBACK call. This caused RRS to tell CICS to perform a ROLLBACK of these changes.
Clearly, FILEA is changed as a result of running DFH$ATXC. It should be restored to its original state by running the LOADFILE step of DFHDEFDS.
*==================== TEXCI Sample Batch Client Program =======================*
*
* EXEC Level Processor.
* Setting up the EXEC level call.
* The Link Request has successfully completed.
* Server Response:
* The file is set to a browsable state.
*
* CALL Level Processor.
* Initialise_User call complete.
* Allocate_Pipe call complete.
* Open_Pipe call complete.
* The connection has been successful.
* The changed target file follows:
*
*=========================== Top of File ======================================*
000100W. DAVIS SURREY, ENGLAND 3215677826 11 81$0100.11COMMITTED
000102F. ALDSON WARWICK, ENGLAND 9835618326 11 81$1111.11COMMITTED
000104S. BOWLER LONDON,ENGLAND 1284629326 11 81$0999.99COMMITTED
000106B. ADAMS CROYDON, ENGLAND 1948567326 11 81$0087.71COMMITTED
000111GENE BARLOWE SARATOGA,CALIFORNIA 4612075301 02 74$0111.11COMMITTED
000762GEORGE BURROW SAN JOSE,CALIFORNIA 2231212101 06 74$0000.00COMMITTED
000983H. L. L. CALL WASHINGTON, DC 3451212021 04 75$9999.99COMMITTED
003210B.CREPIN NICE, FRANCE 1234567026 11 81$3349.99COMMITTED
003214HUBERT C HERBERT SUNNYVALE, CAL. 3411212000 06 73$0009.99COMMITTED
003890PHILIPPE SMITH, JR NICE, FRANCE 0000000028 05 74$0009.99COMMITTED
004004STAN SMITH DUBLIN, IRELAND 7111212102 11 73$1259.99COMMITTED
004445S. GALSON SOUTH BEND, S.DAK. 6121212026 11 81$0009.99COMMITTED
004878D.C. CURRENT SUNNYVALE, CALIF. 3221212010 06 73$5399.99COMMITTED
005005J. S. LAVERENCE SAN FRANCISCO, CA. 0000000101 08 73$0009.99COMMITTED
005444JEAN LAWRENCE SARATOGA, CALIF. 6771212020 10 74$0809.99COMMITTED
005581JOHN ALDEN III BOSTON, MASS. 4131212011 04 74$0259.99COMMITTED
006016DR W. T. KAR NEW DELHI, INDIA 7033121121 05 74$0009.88COMMITTED
006670WILLIAM KAPP NEW YORK, N.Y. 2121212031 01 75$3509.88COMMITTED
006968D. CONRAD WARWICK, ENGLAND 5671382126 11 81$0009.88COMMITTED
007248B. C. WILLIAMSON REDWOOD CITY, CALF. 3331212111 10 75$0009.88COMMITTED
007779MRS. W. WELCH SAN JOSE, CALIF. 4151212003 01 75$0009.88COMMITTED
100000G. NEADS TORONTO, ONTARIO 0341512126 11 81$0010.00COMMITTED
111111C. MEARS OTTAWA, ONTARIO 5121200326 11 81$0011.00COMMITTED
200000A. BONFIELD GLASGOW, SCOTLAND 6373829026 11 81$0020.00COMMITTED
300000K. TRENCHARD NEW YORK, U.S. 6473980126 11 81$0030.00COMMITTED
333333D. MYRING CARDIFF, WALES 7849302026 11 81$0033.00COMMITTED
400000W. TANNER MILAN, ITALY 2536373826 11 81$0040.00COMMITTED
444444A. FISHER CALGARY, ALBERTA 7788982026 11 81$0044.00COMMITTED
500000J. DENFORD MADRID, SPAIN 4445464026 11 81$0000.00COMMITTED
555555C. JARDINE KINGSTON, N.Y. 3994442026 11 81$0005.00BACKEDOUT
600000F. HUGHES DUBLIN, IRELAND 1239878026 11 81$0010.00BACKEDOUT
666666A. BROOKMAN LA HULPE, BRUSSELS 4298384026 11 81$0016.00BACKEDOUT
700000A. MACALLA DALLAS, TEXAS 5798432026 11 81$0002.00BACKEDOUT
777777D. PRYKE WILLIAMSBURG, VIRG. 9187613126 11 81$0027.00BACKEDOUT
800000H. BRISTOW WESTEND, LONDON 2423338926 11 81$0030.00BACKEDOUT
888888B. HOWARD NORTHAMPTON, ENG. 2369163926 11 81$0038.00BACKEDOUT
900000D. WOODSON TAMPA, FLA. 3566812026 11 81$0040.00BACKEDOUT
*=========================== End of File ======================================*
*
* Closing Dpl Request has been attempted.
* Close_Pipe call complete.
* Deallocate_Pipe call complete.
*
*================== End of TEXCI Sample Batch Client Program ==================*
*===================== EXCI Sample Batch Client Program =======================*
*
* EXEC Level Processor.
* Setting up the EXEC level call.
* The Link Request has successfully completed.
* Server Response:
* The file is set to a browsable state.
*
* CALL Level Processor.
* Initialise_User call complete.
* Allocate_Pipe call complete.
* Open_Pipe call complete.
* The connection has been successful.
* The target file follows:
*
*=========================== Top of File ======================================*
000100W. DAVIS SURREY, ENGLAND 3215677826 11 81$0100.11COMMITTED
000102F. ALDSON WARWICK, ENGLAND 9835618326 11 81$1111.11COMMITTED
000104S. BOWLER LONDON,ENGLAND 1284629326 11 81$0999.99COMMITTED
000106B. ADAMS CROYDON, ENGLAND 1948567326 11 81$0087.71COMMITTED
000111GENE BARLOWE SARATOGA,CALIFORNIA 4612075301 02 74$0111.11COMMITTED
000762GEORGE BURROW SAN JOSE,CALIFORNIA 2231212101 06 74$0000.00COMMITTED
000983H. L. L. CALL WASHINGTON, DC 3451212021 04 75$9999.99COMMITTED
003210B.CREPIN NICE, FRANCE 1234567026 11 81$3349.99COMMITTED
003214HUBERT C HERBERT SUNNYVALE, CAL. 3411212000 06 73$0009.99COMMITTED
003890PHILIPPE SMITH, JR NICE, FRANCE 0000000028 05 74$0009.99COMMITTED
004004STAN SMITH DUBLIN, IRELAND 7111212102 11 73$1259.99COMMITTED
004445S. GALSON SOUTH BEND, S.DAK. 6121212026 11 81$0009.99COMMITTED
004878D.C. CURRENT SUNNYVALE, CALIF. 3221212010 06 73$5399.99COMMITTED
005005J. S. LAVERENCE SAN FRANCISCO, CA. 0000000101 08 73$0009.99COMMITTED
005444JEAN LAWRENCE SARATOGA, CALIF. 6771212020 10 74$0809.99COMMITTED
05581JOHN ALDEN III BOSTON, MASS. 4131212011 04 74$0259.99COMMITTED
06016DR W. T. KAR NEW DELHI, INDIA 7033121121 05 74$0009.88COMMITTED
006670WILLIAM KAPP NEW YORK, N.Y. 2121212031 01 75$3509.88COMMITTED
006968D. CONRAD WARWICK, ENGLAND 5671382126 11 81$0009.88COMMITTED
007248B. C. WILLIAMSON REDWOOD CITY, CALF. 3331212111 10 75$0009.88COMMITTED
007779MRS. W. WELCH SAN JOSE, CALIF. 4151212003 01 75$0009.88COMMITTED
100000G. NEADS TORONTO, ONTARIO 0341512126 11 81$0010.00COMMITTED
111111C. MEARS OTTAWA, ONTARIO 5121200326 11 81$0011.00COMMITTED
200000A. BONFIELD GLASGOW, SCOTLAND 6373829026 11 81$0020.00COMMITTED
300000K. TRENCHARD NEW YORK, U.S. 6473980126 11 81$0030.00COMMITTED
333333D. MYRING CARDIFF, WALES 7849302026 11 81$0033.00COMMITTED
400000W. TANNER MILAN, ITALY 2536373826 11 81$0040.00COMMITTED
444444A. FISHER CALGARY, ALBERTA 7788982026 11 81$0044.00COMMITTED
500000J. DENFORD MADRID, SPAIN 4445464026 11 81$0000.00COMMITTED
555555C. JARDINE KINGSTON, N.Y. 3994442026 11 81$0005.00Y00010500
600000F. HUGHES DUBLIN, IRELAND 1239878026 11 81$0010.00Y00010600
666666A. BROOKMAN LA HULPE, BRUSSELS 4298384026 11 81$0016.00Y00010700
700000A. MACALLA DALLAS, TEXAS 5798432026 11 81$0002.00Y00010800
777777D. PRYKE WILLIAMSBURG, VIRG. 9187613126 11 81$0027.00Y00010900
800000H. BRISTOW WESTEND, LONDON 2423338926 11 81$0030.00Y00011000
888888B. HOWARD NORTHAMPTON, ENG. 2369163926 11 81$0038.00Y00011100
900000D. WOODSON TAMPA, FLA. 3566812026 11 81$0040.00Y00011200
*=========================== End of File ======================================*
*
* Closing Dpl Request has been attempted.
* Close_Pipe call complete.
* Deallocate_Pipe call complete.
*
*=================== End of EXCI Sample Batch Client Program ==================*