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  StringResult
(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=NONEWill 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
0Success.
27Program ID error.  Misspelled program name?
70Not authorized. You are not  authorized for the transaction or the region.
88Link 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 ===============================================*