SET PROGRAM

Change a PROGRAM, MAPSET, or PARTITIONSET definition.

SET PROGRAM

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 cannot use the SET PROGRAM command for PROGRAM resources that were defined and installed from a CICS bundle. If you attempt to modify a dynamically generated PROGRAM resource that was installed by a CICS bundle, an INVREQ response with a RESP2 value of 300 is issued.

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:

The program resource is itself bundle defined
The program resource has been modified by the install of a bundle that modifies the program to be used as an entry point
The program resource is a CICS program, that is program resources beginning with DFH

To notify CICS that a program is no longer to be used as an entry point, specify a value of a space character for the OPERATION option.

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.

You cannot specify SHARESTATUS for a remote program. Any value that is specified for Java programs is ignored.

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.