Skip to content

CMNCICS1 - CICS NEWCOPY

Utility program CMNCICS1 refreshes an application load module in a CICS region after ChangeMan ZMF has updated that program in a DFHRPL library.

CMNCICS1 is the driver program for CICS newcopy in ChangeMan ZMF. It validates SYSIN input by verifying that the keyword parameters are grouped and sequenced properly, and then it calls subprogram CMNCICS2 to initiate newcopy commands.

Note

"Newcopy" is used as a generic term that refers to the CICS load module refresh process that includes PHASEIN as well as NEWCOPY. Where sample commands here show subparameter NEWCOPY or NEW, you can substitute PHASEIN or PHA. NEWCOPY is the default where nothing is specified.

Subprogram CMNCICS2 executes newcopy processing in CICS regions that run on the same LPAR as the batch job that executes CMNCICS1. CMNCICS2 calls subprogram CMNEMTP using the CICS external call interface (ECI) to execute newcopy processing in CICS regions that run on different LPARs in the same SYSPLEX.

CMNCICS1 or CMNEMTP verifies whether the program to be newcopied is present in a specified library in the DFHRPL concatenation unless this function is suppressed by a CMNCICS1 execution parameter.

Executing CICS newcopy processing

There are six options for executing CICS newcopy processing:

Option Description
SRB Compatibility: CICS/ESA 4.1 and below
LPAR: The batch job that executes CMNCICS1 must be on the same LPAR as the CICS region where the program is refreshed.
Method: CMNCICS2 schedules SRB to the CICS region to alter the PPT and force a program refresh.
CICS Trans ID: None
Comments: If used with CICS Transaction Server 1.2 and above, CMNCICS1 gives RC=0 but the target CICS program is not refreshed.
ESA Compatibility: CICS/ESA 4.1 and below
LPAR: The batch job that executes CMNCICS1 must be on the same LPAR as the CICS region where the program is refreshed.
Method: CMNCICS2 uses access registers of the CICS address space to alter the PPT and force a program refresh.
CICS Trans ID: None
Comments: If used with CICS Transaction Server 1.2 and above, CMNCICS1 gives RC=0 but the target CICS program is not refreshed.
OPR Compatibility: All CICS releases
LPAR: The batch job that executes CMNCICS1 must be on the same LPAR as the CICS region.
Method: CMNCICS2 issues an operator modify command to execute CICS supplied operator transaction CEMT under the master console terminal control in the target CICS region: F CICS cicsid,’CEMT SET PROG(pgmname) NEW’
CICS Trans ID: CEMT
Comments: CEMT returns many messages to the master console for each NEWCOPY
OPS Compatibility: CICS TS 1.2 and above
LPAR: The batch job that executes CMNCICS1 must be on the same LPAR as the CICS region where the program is refreshed.
Method: CMNCICS2 issues an operator modify command to execute ChangeMan ZMF transaction SEMT that is processed by program CMNEMTP in the target CICS region: F CICS cicsid,’SEMT SET PROG(pgmname) NEW’
CICS Trans ID: SEMT
- Processed by ZMF program CMNEMTP
- Executes a subset of CEMT commands
- Executes with the same authority as CEMT
- Returns only one message to the OS console
OPQ Compatibility: CICS TS 1.2 and above
LPAR: The batch job that executes CMNCICS1 must be on the same LPAR as the CICS region where the program is refreshed.
Method: CMNCICS2 issues an operator modify command to execute ChangeMan ZMF transaction SEMQ that is processed by program CMNEMTP in the target CICS region: F CICS cicsid,’SEMQ SET PROG(pgmname) NEW’
CICS Trans ID: SEMQ
- Processed by ZMF program CMNEMTP
- Executes a subset of CEMT commands
- Executes with the same authority as CEMT
- Suppresses all messages to the OS console
XCI Compatibility: CICS TS 1.2 and above
LPAR: The batch job that executes CMNCICS1 must be on the same SYSPLEX as the CICS region where the program is refreshed, but it may be on a different LPAR.
Method: CMNCICS2 uses the CICS EXCI facility to call program CMNEMTP in the target CICS region. CMNEMTP issues command: EXEC CICS SET PROGRAM(program) NEWCOPY
CICS Trans ID: SEML – This is a dummy transaction ID required for the EXCI interface.
Comments: XCI is the only way to issue a NEWCOPY in a CICS region that is running on a different LPAR than the batch job that executes CMNCICS1.

...

Important

XCI is the only option where RC=0 indicates that the newcopy was executed successfully. Options OPR, OPS, and OPQ issue operator commands which do not return a status code.

CMNCICS1 Input

  • PARM execution parameters

  • SYSIN keyword parameter statements

Output

  • Altered PPT or MODIFY commands or EXEC CICS SET PROGRAM... commands, all to initiate newcopy.

  • Program execution listing

  • Program return code

Sample JCL

JCL to execute program CMNCICS1 is file tailored from skeleton CMN$$CNC, which you customize and imbed as needed in skeletons for promotion, demotion, installation, backout, baseline ripple, and reverse baseline ripple.

//JOBLIB    DD  DISP=SHR,DSN=CMNTP.S4.V710.CMNZMF.CUSTOM.LOAD
//          DD  DISP=SHR,DSN=CMNTP.S4.V710.CMNZMF.LOAD
//          DD  DISP=SHR,DSN=CMNTP.S4.V710.SERCOMC.CUSTOM.LOAD
//          DD  DISP=SHR,DSN=CMNTP.S4.V710.SERCOMC.LOAD
//          DD  DISP=SHR,DSN=SYS2.CICSTS22.CICS.SDFHEXCI *FOR XCI ONLY
...
//CILCNC  EXEC  PGM=CMNCICS1,       *** CICS NEWCOPY FOR CIL
//              COND=(4,LT),
//              PARM=(XCI)
//SYSPRINT  DD  DISP=(,PASS),DSN=&&LISTCNC,
//              UNIT=SYSDA,SPACE=(CYL,(5,5),RLSE),
//              DCB=(RECFM=FA,LRECL=133,BLKSIZE=133)
//SYSIN     DD  *
TARGET=CICSC102
  DFHRPL=CMNTP.S4.V610.PROD.ACTP.CIL
    PROGRAM=GNLCIS10
/*

...

DD Statements

This table describes the DD statements for program CMNCICS1.

DDNAME I/O Purpose
SYSIN Input Input file containing 80-byte keyword parameter records
SYSPRINT Output Report file that displays information from the execution of CMNCICS1
CMNIN Input Alternate for DD name SYSIN
CMNOUT Output Alternate for DD name SYSPRINT

...

PARM Options

The PARM parameter is required in the EXEC statement for CMNCICS1. The subparameters in the PARM statement are positional and are separated by commas.

//CILCNC EXEC PGM=CMNCICS1,
// PARM=(option,check,prefix)

This table describes CMNCICS1 options that are input through the PARM parameter.

Parameter Use Description
option Required 3 character code for the method used to execute the newcopy function. Valid values:
SRB
ESA
OPR
OPS
OPQ
XCI
Options are described in in this table.
check Optional Controls whether the library named in the DFHRPL= SYSIN statement is checked to see if it contains the load module named in the PROGRAM= SYSIN statement. Valid values:
CHECK: Check the RPL library for the presence of the module to be newcopied. This is the default value if this subparameter is not coded.
NOCHECK: Do not check the RPL library for the presence of the module to be newcopied.
DFHRPL verification is performed by CMNCICS1 for options SRB, ESA, OPR, OPS, and OPQ. Verification is performed by CMNEMTP for option XCI.
prefix Optional Code 3 characters to replace the first 3 characters of ChangeMan ZMF CICS transactions SEMT, SEMQ, and SEML. The resulting transIDs must be valid, and they must be defined in any CICS region where they will execute.
Note: Replacement characters may be coded in the PREFIX= keyword parameter for program CMNCICS1 instead of in the PARM statement. See SYSIN Parameters below.

...

SYSIN Parameters

Keyword parameters are input to CMNCICS1 through the SYSIN ddname. 

//SYSIN     DD *
PREFIX=prefix
TARGET=cicsid,setoption
  DFHRPL=loadlib
    PROGRAM=pgmname
    PROGRAM=pgmname
    PROGRAM=pgmname

...

  • Keyword parameters start in positions 1-60.

  • Keyword parameters may be indented to show hierarchy and groupings.

  • Each SYSIN record should contain only one keyword parameter.

  • Blank SYSIN records are permitted.

  • Comment records are designated by * in position 1.

  • A maximum of 65,535 DFHRPL= parameters may be input for each TARGET= parameter.

  • A maximum of 65,535 PROGRAM= parameters may be input for each TARGET= parameter.

This table describes keyword parameters that are input to CMNCICS1 through the SYSIN DD statement.

This list describes keyword parameters that are input to CMNCICS1 through the SYSIN DD statement.

  • * in Position 1 (Optional): Denotes a comment.

  • PREFIX= (Optional): Code 3 characters to replace the first 3 characters of ChangeMan ZMF CICS transactions SEMT, SEMQ, and SEML.
    The resulting transIDs must be valid, and they must be defined in any CICS region where they will execute.
    If multiple PREFIX records are input, only the last one is retained.
    Note: Replacement characters may be coded in the PARM statement for program CMNCICS1 instead of in this SYSIN keyword statement. See PARM Options.

  • TARGET= (Required): The TARGET keyword parameter can have two arguments separated by a comma:

    cicsid: An identifier for the target CICS region, 1-8 characters. The type of identifier depends on the option you are using.

    • CICS region name. Use the CICS region name if you are using options SRB, ESA, OPR, OPS, or OPQ.

    • VTAM APPLID. Use the CICS region VTAM APPLID for option XCI.

    setoption: The option to be executed by the SET PROGRAM(pgmname) command.

    • NEW. Execute NEWCOPY. This is the default option.

    • PHA. Execute PHASEIN. Examples:

      • TARGET=CICSA,PHA

      • TARGET=CICSA,NEW

      • TARGET=CICSA

Return Codes and Error Messages

Messages issued by ChangeMan ZMF are described in the ChangeMan ZMF Messages book. This section contains additional information that will be helpful in diagnosing problems with the CMNCICS1 newcopy utility.

Return Code Description
04 An error was detected before the newcopy method was executed, but the step was allowed to finish with non-fatal return code. See the messages in SYSPRINT.
Examples:
CMN7210E TARGET CICS not active on system
CMN7205E CMNCICS1 Group has no DFHRPL statements at all
08 An error was detected before the newcopy method was executed, and the step issued a fatal return code. See the messages in SYSPRINT.
Examples:
CMN7207E CMNCICS1 DFHRPL dataset failed to allocate
CMN7206E CMNCICS1 DFHRPL dataset does not exist
20 Problem allocating or opening the external CICS interface pipe; these types of errors indicate a problem with inter-system communications or the lack of an EXCI connection in the target CICS.
28 Indicates a problem with the DPL (Distributed Program Link) to program CMNEMTP; these types of problems indicate an error in the installation of the trans IDs or program within the target CICS.
36 With CICS abend AXFQ, indicates that the transaction profile parameter INBFMH is not set to ALL. See the CICS resource definition examples provided here.

...

Message Number Description
CMN7213E CICS RETURNED ERRORS | CICS regions returned errors when doing newcopy
Explanation: CMNCICS2 attempted a CICS NEWCOPY/PHASEIN for an application program, but the application program is not found in the target region. Only programs that have been defined in the CICS system definition file (CSD) and installed on the running CICS system are accessible to ZMF newcopy facilities.
Solution: Create a definition for the application program in the target CICS region.
CMN7214E EXCI FAILURE | Unable to establish EXCI session with target CICS
Explanation: CMNCICS2 is unable to allocate or open an EXCI connection to the target CICS region to perform a NEWCOPY/PHASEIN. The NEWCOPY is not performed.
Solution: Ensure the target CICS region is running, and that the EXCI connection has been properly installed.
CMN7215E INSTALL ERROR | ZMF newcopy support not installed in target CICS
Explanation: CMNCICS2 is unable to start the SEML transaction in the target CICS region to perform NEWCOPY/PHASEIN. The NEWCOPY is not performed.
Solution: See the ChangeMan ZMF Installation Guide for the steps to install the SEML transaction in the target CICS region.

...

Reporting

The SYSPRINT DD statement for CMNCICS1 displays the following information:

  • Program name and title.

  • Keyword parameter records input to SYSIN.

  • Information and error messages.

Example: 

CMNCICS1        CICS NEW PROGRAM UTILITY

  TARGET=CICSC101
    DFHRPL=USER.SERENA.CICSLOAD
      PROGRAM=ACCT01
                CMN7209E Program ACCT01 was not found in DFHRPL library

...

Notes and Comments

The examples below show the difference in message volume between option OPR and OPS. The SYSLOG output is also visible in the CICS JESMSGLG.

This is the JCL, and SYSPRINT output from option OPS, and SYSLOG output.

JCL:
//USER015B JOB ,,CLASS=A,NOTIFY=&SYSUID,
//        COND=(4,LT),MSGLEVEL=(1,1),MSGCLASS=X,
//        REGION=4M
//JOBLIB    DD  DISP=SHR,DSN=CMNTP.CMN810.LOAD
//          DD  DISP=SHR,DSN=CMNTP.SER810.LOAD
//*
//LCXCNC   EXEC PGM=CMNCICS1, *** CICS NEWCOPY
//              PARM=(OPS,CHECK)
//SYSPRINT  DD  SYSOUT=*
//SYSIN     DD  *
    TARGET=CICSC102,PHA
    DFHRPL=USER.SERENA.CICSLOAD
    PROGRAM=CMNEMTP
**************************** Bottom of Data *****

SYSPRINT:
CMNCICS1            CICS NEW PROGRAM UTILITY
TARGET=CICSC102,PHA
DFHRPL=USER.SERENA.CICSLOAD
PROGRAM=CMNEMTP
**************************** Bottom of Data *****

SYSLOG:
S0296623 00000080 +SEMT SET PROG(CMNEMTP) PHA
                            Set command completed normally
S0296623 00000080 +Resp=0000 Resp2=0000

...

This is the JCL and SYSPRINT output from option OPR, and also the output to the SYSLOG.

//USER015C  JOB ,,CLASS=A,NOTIFY=&SYSUID,
//          COND=(4,LT),MSGLEVEL=(1,1),MSGCLASS=X,
//          REGION=4M
//**********************************************
//* FROM USER015.JCL.CNTL(CICSJOB1)
//*
//* JOB TO DO A CICS NEWCOPY
//**********************************************
//JOBLIB    DD  DISP=SHR,DSN=CMNTP.CMN810.LOAD
//          DD  DISP=SHR,DSN=CMNTP.SER810.LOAD
//*
//LCXCNC   EXEC PGM=CMNCICS1,
//              PARM=(OPR,CHECK)
//SYSPRINT  DD  SYSOUT=*
//SYSIN     DD  *
    TARGET=CICSC102
    DFHRPL=USER.SERENA.CICSLOAD
    PROGRAM=CMNEMTP
**************************** Bottom of Data *****

CMNCICS1        CICS NEW PROGRAM UTILITY

    TARGET=CICSC102
    DFHRPL=USER.SERENA.CICSLOAD
    PROGRAM=CMNEMTP
******************************** BOTTOM OF DATA *

 SDSF OPERLOG C001   02/25/2015  0W      COLUMNS 41- 120
 COMMAND INPUT ===>                      SCROLL ===> CSR
S0296623    00000080 + 581
    581     00000080 Program(CMNEMTP)
    581     00000080 Length(0000009664)
    581     00000080 Language(Assembler)
    581     00000080 Progtype(Program)
    581     00000080 Status( Enabled )
    581     00000080 Sharestatus( Private )
    581     00000080 Copystatus( Notrequired )
    581     00000080 Cedfstatus( Cedf )
    581     00000080 Dynamstatus(Notdynamic)
S0296623    00000080 + Rescount(000) 582
    582     00000080 Usecount(0000000002)
    582     00000080 Dataloc(Any)
    582     00000080 Execkey(Uexeckey)
    582     00000080 Executionset( Fullapi )
    582     00000080 Concurrency(Quasirent)
    582     00000080 Remotesystem()
    582     00000080 Runtime( Notknown )
    582     00000080 Jvmclass(
    582     00000080 )
S0296623    00000080 + Jvmclass( 583
    583     00000080 )
    583     00000080 Jvmclass(
    583     00000080 )
    583     00000080 Jvmclass(
    583     00000080 )
    583     00000080 Jvmclass( )
    583     00000080 Hotpooling( Nothotpool )
    583     00000080 Jvmprofile(DFHJVMPR)
    583     00000080 NORMAL
S0296623    00000080 + RESPONSE: NORMAL TIME: 01.47.49 DATE: 02.25.15 584
    584     00000080 SYSID=C102 APPLID=CICSC102

...