The SET PROGRAM command

Change the instance of an installed PROGRAM, in a CICS® system or group of CICS systems. Use this command with the PHASEIN option to phase in a new version of a PROGRAM without disrupting active tasks or NEWCOPY option to use a new copy of the PROGRAM when the PROGRAM ceases to be in use by any transaction.

Read syntax diagramSkip visual syntax diagramSET PROGRAM( data-value)SCOPE( data-value)NEWCOPYPHASEINTIMEOUT( 300)TIMEOUT( data-value)

Options

PROGRAM (data-value)
Specifies the name of the PROGRAM (up to 8 characters). Wildcards are supported.
NEWCOPY

CICS is to use a new copy of the program when the program ceases to be in use by any transaction. You can determine whether a module is in use from the RESCOUNT option in an INQUIRE PROGRAM command. A value of zero means the program is not in use. It is possible for CICS to replace the program with the new version during a single transaction, at a point when one use of the program has completed, and a subsequent use has yet to start.

CICS loads the new version either from the DFHRPL or dynamic LIBRARY concatenation, or uses an LPA-resident version, depending on the PRIVATE or SHARED options. PRIVATE is the default setting.

An error will be returned if you specify NEWCOPY for a PROGRAM which has the HOLD option.

An error will be returned if you specify NEWCOPY for a PROGRAM resource that was defined and installed in a CICS bundle.

PHASEIN

CICS uses a new copy of the program now for all new transaction requests. CICS continues to use the old copy for all currently running transactions until they finish (RESCOUNT equal to zero). CICS loads the new version either from the DFHRPL or dynamic LIBRARY concatenation, or uses an LPA-resident version, depending on the PRIVATE or SHARED options. PRIVATE is the default setting.

PHASEIN performs a REFRESH PROGRAM function to inform the loader domain that a new version of the program is cataloged and that this version of the named program must be used in all future ACQUIRE requests.

An error will be returned if you PHASEIN for a program which has the HOLD option.

An error will be returned if you specify PHASEIN for a Java program that runs in a JVM.

An error will be returned if you specify PHASEIN for a PROGRAM resource that was defined and installed in a CICS bundle. Use the SET BUNDLE PHASEIN command instead.

SCOPE (data-value)
Specifies the CICS System, or CICS System Group (up to 8 characters) where the PROGRAM is installed.
TIMEOUT ( 300 | data-value)
An optional numerical value that specifies the maximum amount of time in seconds (1 - 1800 inclusive) for the command to complete. For more information about how to choose an appropriate TIMEOUT value, see Troubleshooting the DFHDPLOY utility.
Note: The NEWCOPY and PHASEIN options are mutually exclusive.

For more information about CICS processing of the SET PROGRAM command, see SET PROGRAM.

Example

The following example connects to MYPLEX and phases in a new version of PROGRAM PROG1 and then performs a NEWCOPY against PROGRAM PROG2: 

//DFHDPLY1 JOB CLASS=A,MSGCLASS=A,NOTIFY=&SYSUID
//*
//DFHDPLOY EXEC PGM=DFHDPLOY
//*
//STEPLIB  DD DISP=SHR,DSN=CICSTS55.CICS.SDFHLOAD
//         DD DISP=SHR,DSN=CICSTS55.CPSM.SEYUAUTH
//SYSTSPRT DD SYSOUT=*
//SYSIN    DD *
SET CICSPLEX(MYPLEX);
*
SET PROGRAM(PROG1) SCOPE(AOR1) PHASEIN TIMEOUT(300);
*
SET PROGRAM(PROG2) SCOPE(AOR2) NEWCOPY TIMEOUT(300);
/*