Batch Invocations (NWBTRAN Program)
If you have any questions about the content of this page, please contact CICS Requests for clarification
We have a facility that allows you to invoke CICS programs from batch jobs.
Restrictions
- The CICS programs must be limited to the DPL command subset. That essentially means they must execute no “terminal” type commands.
- The terminal ID associated with this facility must not be used for anything meaningful. It will usually be the same value for all users, but may vary with heavy use. Either way, it has no meaning.
- The specified transaction must be a “mirror” transaction.
For more details, see CICS and the World Wide Web, particularly the section on EXCI (which is the technique these programs use).
Parameters
You must pass at least four parameter cards to the
NWBTRAN
program.
- VTAM application ID of the CICS region to receive the request. Contact NWRDC customer support for details.
- The "mirror" transaction under which it should run.
- The name of the CICS program to invoke.
- The length of the COMMAREA that will be passed to said program (5 digits, leading zeros required). Maximum value is 30720.
- As many cards (0 to 384) as it takes to specify the COMMAREA. Extra cards are ignored, too few will result in a space-filled COMMAREA.
The logon ID of the batch job will be used as the user ID in the target CICS region. That ID must have the ACF2 CICS signon attribute and be authorized for the transaction. The JCL EXEC statement parameter “PARM” is used to control the printed output of this program.
| PARM String | Result |
| (none) | All incoming parameters are printed. The input COMMAREA is scanned and as it is printed, each non-printable character is replaced with asterisk. The returned COMMAREA is also scanned for non-printable characters, and then printed. |
| PRINT=NONE | Will suppress all printed output unless an error occurs. Errors are always documented. |
| PRINT=OUTCA | Will print only the returned COMMAREA without a scan for non-printable characters. Thus, the SYSPRINT dataset can be specified as a temporary data set and passed to a subsequent program for analysis. |
The EXCI (the CICS facility this program uses) return code is posted as the JCL return code. Some common examples (see CICS.COBLIB:DFHXCRCO for the compete set) are:
| Code | Meaning |
| 0 | Success. |
| 27 | Program ID error. Misspelled program name? |
| 70 | Not authorized. You are not authorized for the transaction or the region. |
| 88 | Link failure. Non-mirror transaction, abend in CICS or unavailable region. |
Sample JCL:
We are going to invoke the CICS program NWREVER under the NWLX transaction. We will pass it a 100 byte commarea, two cards will be required for that. That program resides in the CICS region whose APPPLID is NWR1CT10. The whole process (batch and CICS) will run under the NWXXS logonid.
1.......10........20........30........40........50........60........70........80
//NWXXXEX JOB NWXXS
//STEP EXEC PGM=NWRBTRAN
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
NWR1CT10
NWLX
NWREVER
00100
A1B1C1D1E1F1G1H1I1J1K1L1M1N1O1P1Q1R1S1T1U1V1W1X1Y1Z1A2B2C2D2E2F2G2H2I2J2K2L2M2N2
O2P2Q2R2S2T2U2V2W2X2
//
Note: in this example, we invoke an NWR test application that simply reverses the incoming COMMAREA. The printed report produced by the job above would be as follows:
*===================== NWRDC BATCH TO CICS PROGRAM ======================*
* *
* >>>> TARGET CICS REGION: NWR1CT10 <<<< *
* *
*==============================================================================*
* *
* >>>> TARGET CICS TRAN: NWLX <<<< *
* *
*==============================================================================*
* *
* >>>> TARGET CICS PROGRAM: NWREVER <<<< *
* *
*==============================================================================*
* *
* >>>> TARGET CICS CALEN: 00100 <<<< *
* *
*==============================================================================*
* *
* >>>> TARGET CICS COMMAREA DATA <<<< *
A1B1C1D1E1F1G1H1I1J1K1L1M1N1O1P1Q1R1S1T1U1V1W1X1Y1Z1A2B2C2D2E2F2G2H2I2J2K2L2M2N2
O2P2Q2R2S2T2U2V2W2X2
* >>>> END OF PARAMETERS <<<< *
*==============================================================================*
* *
* *
* >>>> PROCESSING REQUEST <<<< *
* *
* *
*==============================================================================*
*======= RETURNED COMMAREA ====================================================*
2X2W2V2U2T2S2R2Q2P2O2N2M2L2K2J2I2H2G2F2E2D2C2B2A1Z1Y1X1W1V1U1T1S1R1Q1P1O1N1M1L1K
1J1I1H1G1F1E1D1C1B1A
*==============================================================================*
* *
* *
*=================== END OF JOB ===============================================*