SET PROGRAM

Change a PROGRAM, MAPSET, or PARTITIONSET definition.

Read syntax diagramSkip visual syntax diagramSET PROGRAM
 
>>-SET PROGRAM(data-value)--+------------------+---------------->
                            +-CEDFSTATUS(cvda)-+
                            +-CEDF-------------+
                            '-NOCEDF-----------'
 
>--+------------+--+--------------------+----------------------->
   +-COPY(cvda)-+  +-EXECUTIONSET(cvda)-+
   +-NEWCOPY----+  +-DPLSUBSET----------+
   '-PHASEIN----'  '-FULLAPI------------'
 
>--+------------------------------------+----------------------->
   '-JVMCLASS(255-character data-value)-'
 
>--+------------------------------------+--+---------------+---->
   '-JVMPROFILE(8-character data-value)-'  +-RUNTIME(cvda)-+
                                           +-JVM-----------+
                                           '-NOJVM---------'
 
>--+-------------------+--+--------------+--+---------------+--><
   +-SHARESTATUS(cvda)-+  +-STATUS(cvda)-+  '-VERSION(cvda)-'
   +-PRIVATE-----------+  +-DISABLED-----+
   '-SHARED------------'  '-ENABLED------'
 

Conditions: INVREQ, IOERROR, NOTAUTH, PGMIDERR

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

The SET PROGRAM command modifies the definition of a particular program, map set, or partition set installed in your CICS system. All of these resources are load modules and, therefore, CICS uses the same SET command for all three. To avoid confusion, we use the word module to refer to the object of your command, except when the option applies only to executable programs.

Options

CEDFSTATUS(cvda) (programs only)
specifies what action the execution diagnostic facility (EDF) is to take if this program is executed under EDF. CVDA values are:
CEDF
EDF diagnostic screens are to be displayed. If the program was translated with the EDF option, all EDF screens are displayed; if it was translated with NOEDF, only the program initiation and termination screens appear.
NOCEDF
No EDF screens are displayed.

You cannot specify CEDFSTATUS for a remote program.

COPY(cvda)
specifies that a new copy of the program is to be used the next time the module is requested. LINK, XCTL, LOAD, ENABLE, and BMS commands can cause a module request.

CICS does not load the module at this time, but it does ensure that a copy is available. If you have specified the SHARED option and the module is in the link-pack area, the LPA copy satisfies this requirement. Otherwise, CICS searches the concatenated DFHRPL libraries, and returns an IOERR exception if it cannot locate a copy there. CVDA values are:

NEWCOPY
The module is to be refreshed only if it is not currently in use; otherwise CICS returns an INVREQ exception instead. (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.)

Start of changeThis option is not valid for JVM programs, and is ignored if specified. You can achieve a synchronized replacement of a JVM program by using the command:

      SET JVMPOOL  PHASEOUT
End of change
PHASEIN
The refresh is to occur whether or not the module is in use. If it is, the copy or copies in use remain until they are no longer in use, but all requests that occur after the refresh use the new copy.

Start of changeThis option is permitted for JVM programs, but it is ignored if specified. You can achieve a synchronized replacement of a JVM program by using the command:

      SET JVMPOOL  PHASEOUT
End of change

COPY cannot be specified for any module currently loaded with the HOLD option, or for any program defined as remote.

EXECUTIONSET(cvda) (programs only)
specifies whether the program is to be restricted to executing the distributed program link (DPL) subset of the CICS API. EXECUTIONSET applies only to executable programs, and governs the API only when a program executes locally. (Programs are always restricted to this subset when invoked remotely--that is, when executing at or below the level of a program invoked by DPL.) CVDA values are:
DPLSUBSET
The program is always to be restricted. You cannot specify this value for CICS-supplied programs (those beginning with ‘DFH’).
FULLAPI
The program is not to be restricted unless invoked remotely.

The EXECUTIONSET attribute applies only:

  • to programs which are being linked to, and not to those which are the first to be given control by a transaction.
  • when the REMOTESYSTEM name is the same name as the local CICS region. Its purpose is to test programs in a local CICS environment as if they were running as DPL programs.
JVMCLASS(255-character data-value) (JVM programs only)
specifies the name of the main class in the Java program to be given control by the JVM. If you specify JVM in the RUNTIME option, you should specify a JVMCLASS value. If you specify NOJVM in the RUNTIME option, any value in the JVMCLASS option is ignored when the program is executed.
JVMPROFILE(8-character data-value) (JVM programs only)
specifies the name of a JVM profile that is to be used for the JVM in which this program runs. Any instances of this program that are currently running in a JVM with the old JVM profile are unaffected, and are allowed to finish running.

When you use the name of a JVM profile anywhere in CICS, you must enter it using the same combination of upper and lower case characters that is present in the HFS file name.

PROGRAM(data-value)
specifies the 8-character name of the program, map set, or partition set definition to be changed.
RUNTIME(cvda) (JVM programs only)
specifies whether the program is to run under the control of a JVM. CVDA values are:
JVM
The program is to run under the control of a JVM. You should specify a JVMCLASS value.
NOJVM
The program is not to run under the control of a JVM. Any value in the JVMCLASS option is ignored and the runtime environment of the changed program is unknown until the program is next loaded by CICS, at which point its language, and hence whether it will run with LE370, is determined.
SHARESTATUS(cvda)
specifies where CICS should obtain the module the next time a new copy is required. A new copy request can result from either an explicit request (SET PROGRAM COPY or the CEMT equivalent) or from a command that requires the module that is issued when CICS does not currently have a copy. CVDA values are:
PRIVATE
The module is to be loaded from the concatenated libraries named on the DFHRPL DD statement.
SHARED
The link-pack area copy is to be used, if one is available. If not, the module is loaded as if SHARESTATUS were PRIVATE.
You cannot specify SHARESTATUS for a remote program. Any value specified for JVM programs is ignored.
STATUS(cvda)
specifies whether the module is to be available for use. CVDA values are:
DISABLED
The module is to be unavailable. CICS programs (beginning with ‘DFH’) cannot be disabled.
ENABLED
The module is to be available.

For a program defined as remote, this option governs availability only when the program is invoked through the local CICS system; it does not change availability on the remote system.

The ENABLED and DISABLED option are honored for a program that is invoked through a CICS program link request, but they have no effect if the program is invoked by a Java program through a method call.

VERSION(cvda)
returns a CVDA value indicating whether the copy CICS located for a COPY request is different from the current copy. A value is returned only when the COPY option is also specified; in other cases the CVDA value is unchanged. For this purpose, CICS defines "different" to mean a switch from a copy loaded from the DFHRPL libraries to the link-pack area copy or vice-versa, or a copy loaded from a disk location different from that of the current copy. CVDA values are:
NEWCOPY
The new copy is different.
OLDCOPY
The new copy is not different. This value is always returned for JVM programs.

Conditions

INVREQ
RESP2 values:
1
DISABLED or DPLSUBSET was specified for a program beginning ‘DFH’.
2
STATUS has an invalid CVDA value.
3
NEWCOPY was specified and RESCOUNT is not equal to zero.
4
SHARESTATUS has an invalid CVDA value.
5
COPY has an invalid CVDA value.
6
COPY was specified for a module currently loaded with the HOLD option.
9
CEDFSTATUS has an invalid CVDA value.
17
You have specified an option that is invalid for a remote program (CEDFSTATUS, COPY, EXECUTIONSET or SHARESTATUS).
18
You have specified an option that is invalid for a map set (CEDFSTATUS or EXECUTIONSET).
19
You have specified an option that is invalid for a partition set (CEDFSTATUS or EXECUTIONSET).
20
EXECUTIONSET has an invalid CVDA value.
22
RUNTIME has an invalid CVDA value.
23
JVM was specified but no JVMCLASS has been supplied.
24
DEBUG was specified but RUNTIME was not set to JVM.
25
JVMCLASS contains embedded blanks or null (x'00') characters.
26
JVMPROFILE contains invalid characters or embedded blanks.
IOERR
RESP2 values:
8
Either the COPY option or the RUNTIME(NOJVM) option was specified but CICS could not locate the module.
NOTAUTH
RESP2 values:
100
The user associated with the issuing task is not authorized to use this command.
101
The user associated with the issuing task is not authorized to access this particular resource in the way required by this command.
PGMIDERR
RESP2 values:
7
The program, map set, or partition set cannot be found.

Examples

EXEC CICS SET PROGRAM ('PROGA')
              PHASEIN
              PRIVATE
              DISABLED

In this example, CICS is to make module PROGA unavailable for new requests, and to locate a new copy in one of the DFHRPL libraries. Any copies of PROGA with a non-zero RESCOUNT will remain until no longer in use, but new requests for PROGA will fail until PROGA is set to ENABLED status. On the first request after the module is enabled, CICS loads the new copy and makes it the current one.

[[ Contents Previous Page | Next Page Index ]]