SET PROGRAM
Change a PROGRAM, MAPSET, or PARTITIONSET definition.
Conditions: INVREQ, IOERR, NOTAUTH, PGMIDERR
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
This command is threadsafe.
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, the term module means the object of your command, except when the option applies only to executable programs.
- You can control the status of dynamically generated PROGRAM resources by enabling or disabling the BUNDLE resources that installed them.
- You can modify the definition of dynamically generated PROGRAM resources by using the resource editor in CICS Explorer®. To update the definition, replace the old version of the CICS bundle with the new one, following the instructions in Working with bundles in the CICS Explorer product documentation. CICS bundles that were deployed on their own or with a platform can be updated individually. If the CICS bundle was deployed as part of an application or with an application binding, update the whole application.
For information about application entry points and the PROGRAM resource, see Application entry points.
Options
- CEDFSTATUS(cvda) (programs only)
- Specifies
what action the execution diagnostic facility (EDF) is to take if
this program runs under EDF. This option has the following CVDA values:
- 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 are displayed.
- 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 that the
module is requested. LINK, XCTL, LOAD, ENABLE,
and BMS commands can cause a module request. You can choose to refresh
the module only if it is not currently in use (NEWCOPY), or to phase
in the new version of the module for all future requests (PHASEIN).
You cannot specify the COPY option for any module that is currently loaded with the HOLD option, or for any program that is defined as remote.
CICS does not load the module at the time you issue the command, but it does ensure that a copy is available. If you specified the SHARED option and the module is in the link-pack area, the LPA copy satisfies this requirement. Otherwise, CICS searches the DFHRPL or dynamic LIBRARY concatenations, and returns an IOERR exception if it cannot locate a copy there.
For Java™ programs that run in a JVM server, you cannot use the NEWCOPY or PHASEIN options of this command to refresh the program. To implement a new version of the program, replace the old version of the CICS bundle with an updated version. For more information, see Updating OSGi bundles in a JVM server.
For PROGRAM resources that were defined and installed from a CICS bundle, you cannot use the NEWCOPY or PHASEIN options of this command to refresh the program. To implement a new version of the program, replace the old version of the CICS bundle with an updated version. If the CICS bundle was deployed as part of an application or with an application binding, update the whole application.
This option has the following CVDA values:- 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 that the program is not in use.
- 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. All requests that occur after the refresh use the new copy.
- EXECUTIONSET(cvda) (programs only)
- Specifies
whether the program is to be restricted to running the distributed
program link (DPL) subset of the CICS API.
EXECUTIONSET applies only to executable programs, and governs the
API only when a program runs locally. Programs are always restricted
to this subset when called remotely; that is, when they are running
at or below the level of a program that is called by DPL. This option
has the following CVDA values:
- DPLSUBSET
- The program is always to be restricted. You cannot specify this value for CICS programs (programs beginning with ‘DFH').
- FULLAPI
- The program is not to be restricted unless called remotely.
The EXECUTIONSET attribute applies only in the following circumstances:- Programs that are being linked to and not to those programs that 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(data-value) (Java programs only)
- Specifies the 255-character name of the main class in the Java program to be given control by the JVM. If you specify JVM in the RUNTIME option, specify a JVMCLASS value. If you specify NOJVM in the RUNTIME option, any value in the JVMCLASS option is ignored when the program runs.
- JVMPROFILE(data-value) (Java programs only)
- Specifies
the 8-character name of a JVM profile that is to be used for the pooled
JVM in which this Java program
runs. Any instances of this program that are currently running in
a JVM with the old JVM profile are unaffected, and can finish running.
You cannot set this option for Java programs
that use a JVM server because the JVM profile is set on the JVMSERVER
resource.
When you use the name of a JVM profile anywhere in CICS, you must enter it using the same combination of uppercase and lowercase characters that are present in the z/OS® UNIX file name.
- OPERATION(data-value)
- Specifies the 64-character name of the application operation for which this program is to be defined as an application entry point. You cannot specify the OPERATION option if these conditions apply:
- PROGRAM(data-value)
- Specifies the 8-character name of the program, map set, or partition set definition to be changed.
- RUNTIME(cvda) (Java programs only)
- Specifies
whether the program is to run in a JVM. This option has the following
CVDA values:
- JVM
- The program is to run in a JVM. Specify a JVMCLASS value.
- NOJVM
- The program is not to run in 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, when its runtime environment is determined.
- SHARESTATUS(cvda)
- Specifies
where CICS obtains the module
the next time a new copy is required. A new copy request can result
from either an explicit request, for example SET PROGRAM
COPY, or from a command that requires the module that is
issued when CICS does not currently
have a copy. This option has the following CVDA values:
- PRIVATE
- The module is to be loaded from the concatenated libraries that are named on the DFHRPL or dynamic LIBRARY 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.
- STATUS(cvda)
- Specifies
whether the module is to be available for use. This option has the
following CVDA values:
- 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 called 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 called through a CICS program link request, but they have no effect if the program is called by a Java program through a method call.
- VERSION(cvda)
- Returns
a CVDA value that indicates 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 that is loaded from the DFHRPL or dynamic LIBRARY concatenations to the link-pack area copy or vice versa, or a copy that is loaded from a disk location different from the current copy. The SET PROGRAM command does not work for a program that was installed by a BUNDLE resource. The SET PROGRAM command has the following CVDA values:- NEWCOPY
- The new copy is different.
- OLDCOPY
- The new copy is not different. This value is always returned for Java programs.
Conditions
- INVREQ
- RESP2 values:
- 1
- DISABLED, DPLSUBSET, or OPERATION 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 specified an option that is invalid for a remote program (CEDFSTATUS, COPY, EXECUTIONSET, SHARESTATUS, or OPERATION).
- 18
- You specified an option that is invalid for a map set (CEDFSTATUS, EXECUTIONSET, or OPERATION).
- 19
- You specified an option that is invalid for a partition set (CEDFSTATUS, EXECUTIONSET, or OPERATION).
- 20
- EXECUTIONSET has an invalid CVDA value.
- 22
- RUNTIME has an invalid CVDA value.
- 23
- JVM was specified but no JVMCLASS was supplied.
- 25
- JVMCLASS contains embedded blanks or null (x'00') characters.
- 27
- The option is not valid for a Java program that runs in a JVM server.
- 28
- JVMPOOL is obsolete.
- 29
- SET PROGRAM COPY(NEWCOPY) is not valid for a Java program that runs in a JVM server.
- 30
- OPERATION specifies invalid characters.
- 31
- OPERATION cannot be overridden.
- 300
- You specified an operation that is invalid for a resource that is installed by a BUNDLE resource.
- 301
- You specified an operation that is invalid for a PROGRAM that was loaded from a CICS bundle defined LIBRARY.
- IOERR
- RESP2 values:
- 8
- Either the COPY option or the RUNTIME(NOJVM) option was specified but CICS was not able to locate the module.
- NOTAUTH
- RESP2 values:
- 100
- The user that is associated with the issuing task is not authorized to use this command.
- 101
- The user that is associated with the issuing task is not authorized to access this particular resource in the way that is required by this command.
- PGMIDERR
- RESP2 values:
- 7
- The program, map set, or partition set cannot be found.