PROGRAM attributes

Describes the syntax and attributes of the PROGRAM resource.

Attributes for non-Java programs

Attributes for Java programs

API({CICSAPI|OPENAPI})

Specifies which API is to be used by the program. The API attribute applies to the following programs:

User application programs
PLT programs
User-replaceable programs
Task-related user exit programs. For more information, see Task-related user exit programs.

The API attribute does not apply to global user exits.

CICSAPI

The program is restricted to use of the CICS® permitted application programming interfaces only.

If the program is defined with CONCURRENCY(QUASIRENT), it always runs on the quasi-reentrant (QR) TCB. If the program is defined with CONCURRENCY(THREADSAFE), it runs on whichever TCB is in use by CICS at the time that is determined as suitable, and if the program is defined with CONCURRENCY(REQUIRED), it always runs on an open TCB.

OPENAPI

The program is not restricted to the CICS application programming interfaces.

CICS runs the program on its own open TCB. The type of open TCB used depends on the value of the EXECKEY attribute and the language of the program.

If CICS requires a switch to the QR TCB when running a command, it returns to the open TCB before handing control back to the application program.

To specify the OPENAPI attribute, your program must be coded to threadsafe standards and defined with CONCURRENCY(REQUIRED). The primary use for OPENAPI programs is to move application workloads off the QR TCB and onto multiple open TCBs. You can benefit from better exploitation of server resources to achieve better throughput.

Note: The combination of CONCURRENCY(THREADSAFE) API(OPENAPI) supported in previous releases is deprecated but is kept for compatibility, and produces the same behavior as CONCURRENCY(REQUIRED) API(OPENAPI).

Use of other (non-CICS) APIs in OPENAPI programs is possible. If an open TCB is blocked by an operating system wait, only the single application is affected and not the whole of CICS. Such OPENAPI programs are not permitted to run on the QR TCB precisely because of this risk of blocking the TCB by an operating system wait and thus affecting the whole of CICS. Nevertheless, OPENAPI programs still have obligations to the CICS system as a whole. For more information, see Multithreading: Reentrant, quasi-reentrant, and threadsafe programs.

Important: Use of other (non-CICS) APIs within CICS is entirely at the discretion and risk of the user. No testing of other (non-CICS) APIs within CICS has been undertaken and use of such APIs is not supported by IBM® Service.

CEDF({YES|NO})

Specifies the action of the execution diagnostic facility (EDF) when the program is running under EDF control.

NO

The EDF diagnostic screens are not displayed.

YES

The EDF diagnostic screens are displayed. If the program is translated with the NOEDF option, only the program initiation and termination EDF screens are displayed. See Table 1.

Table 1. The effect on programs of CEDF(NO) and NOEDF
CEDF option on PROGRAM	EDF specified for translator	NOEDF specified for translator
YES	ALL EDF screens	Program initiation and termination screens only
NO	NO EDF screens	NO EDF screens
Note: The table shows how the CEDF option on the program resource definition interacts with the EDF option specified for the translator.

CONCURRENCY({QUASIRENT|THREADSAFE|REQUIRED})

Specifies whether the program is written to threadsafe standards, or is only quasi-reentrant. You can specify the CONCURRENCY attribute for all CICS executable program objects:

User application programs.
PLT programs.
User-replaceable programs.
Global user exit programs. For more information, see Global user exit programs.
Task-related user exit programs. For more information, see Task-related user exit programs.

Java programs and any C and C++ programs compiled with the XPLink option must be defined as CONCURRENCY(REQUIRED).

QUASIRENT

The program is quasi-reentrant only, and relies on the serialization provided by CICS when accessing shared resources.

The program is restricted to the CICS permitted programming interfaces, and must comply with the CICS quasi-reentrant rules. For more information, see Multithreading: Reentrant, quasi-reentrant, and threadsafe programs.

This value is supported for all executable programs.

CICS ensures that the program always runs under the QR TCB, even when control is returned after it has started a JVM or an open API task-related user exit, or when it interacts with threadsafe programs.

THREADSAFE

The program is written to threadsafe standards. When it accesses shared resources it takes into account the possibility that other programs might be running concurrently and attempting to modify the same resources. The program, therefore, uses appropriate serialization techniques when accessing any shared resources.

For information about CICS DB2® application programs, see Preparing CICS DB2 programs for execution and production.

For information about writing threadsafe application programs, see Threadsafe programs.

This value is supported for all executable programs.

REQUIRED

The program is written to threadsafe standards. CICS starts the program on an open TCB and ensures that the program always runs on an open TCB. If CICS switches to the QR TCB to run a CICS command, it returns to the open TCB before handing control back to the application program. The type of open TCB used depends on the API setting and the language of the program.

Java™ programs and OSGi bundles that run in a JVM server use a T8 TCB.
C or C++ XPLink programs operate like OPENAPI programs and use an X8 TCB if CICS key is set, and an X9 TCB if user key is set.
COBOL, PL/I, non-XPLink C or C++, and assembler language programs that also specify API(CICSAPI) use an L8 TCB because CICS commands can operate on this TCB irrespective of the execution key of the program.
COBOL, PL/I, non-XPLink C or C++, and assembler language programs that also specify API(OPENAPI) use an L8 TCB if CICS key is set or use an L9 TCB if user key is set.

REQUIRED is applicable to user application programs, PLT programs, and user-replaceable programs.

DATALOCATION({ANY|BELOW})

Commands that use the SET option can return a data address to an application program; this operand specifies the location of the data. For example, in the command EXEC CICS RECEIVE SET(ptr-ref), ptr-ref is less than 16 MB if DATALOCATION(BELOW) is specified, but might be greater than 16 MB if DATALOCATION(ANY) is specified. DATALOCATION does not affect the operation of the GETMAIN command. For more information about where CICS obtains storage in response to this command, see GETMAIN.

ANY

The program can handle 31-bit addresses. This is the default. The address of the data can be above or below the 16 MB line. The values specified for the DATALOCATION attribute are independent of the addressing mode of the link-edited program. Programs that are link-edited with addressing mode AMODE=24 cannot access data above 16 MB; ensure that the value you specify is compatible with the addressing mode of the link-edited application program:

Specify ANY for all 31-bit or 64-bit programs, unless they pass CICS data addresses on to other 24-bit programs.
Specify DATALOCATION(BELOW) for an AMODE=24 program, unless storage addresses are being passed to a program that can access storage above 16 MB, or the program explicitly switches addressing mode.

BELOW

The program can handle only 24-bit addresses and must therefore only be given data located below the 16 MB line. If required, data is copied below the 16 MB line before passing its address to the application program.

DATALOCATION does not affect the operation of the GETMAIN64 or GET64 CONTAINER commands. For more information about these commands, see GETMAIN64 and GET64 CONTAINER.

DESCRIPTION(text)

You can provide a description of the resource that you are defining in this field. The description text can be up to 58 characters in length. There are no restrictions on the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right parenthesis. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.

DYNAMIC({NO|YES})

Specifies whether, if the program is the subject of a program-link request, the request can be dynamically routed.

NO: If the program is the subject of a program-link request, the dynamic routing program is not started.
For a distributed program link (DPL) request, the server region on which the program is to run must be specified explicitly on the REMOTESYSTEM attribute or on the SYSID option of the EXEC CICS LINK command; otherwise it defaults to the local region.
YES: If the program is the subject of a program-link request, the CICS dynamic routing program is started. If a remote region is not named on the SYSID option of the EXEC CICS LINK command, the routing program can route the request to the region on which the program is to run.

The DYNAMIC attribute takes precedence over the REMOTESYSTEM attribute; see REMOTESYSTEM.

For guidance information about the dynamic routing of DPL requests, see Dynamically routing DPL requests.

EXECKEY({USER|CICS})

Specifies the key in which CICS gives control to the program, and determines whether the program can modify CICS-key storage. Except for reentrant programs (that is, programs link-edited with the RENT attribute), EXECKEY also defines, with the residency mode, into which of the DSAs CICS loads the program.

CICS

CICS gives control to the program in CICS key when it is called. CICS loads the program into one of the CICS-key DSAs - either the CDSA or the ECDSA, depending on the residency mode specified for the program.

In a CICS region with storage protection active, a CICS-key program has read and write access to CICS-key and user-key storage of its own task and all other tasks, whether transaction isolation is active.

USER

CICS gives control to the program in user key when it is called. CICS loads the program into one of the user-key shared DSAs - either the SDSA or the ESDSA, depending on the residency mode specified for the program.

In a CICS region with storage protection only active, a user-key program has read and write access to all user-key storage, but read-only access to CICS-key storage.

In a storage protection and transaction isolation environment, a user-key program has read and write access to the user-key task-lifetime storage of its own task only, and to any shared DSA storage, if the transaction is defined with ISOLATE(YES).

If a transaction is defined with ISOLATE(NO) in a transaction isolation environment, its user-key programs also have read and write access to the user-key task-lifetime storage of other transactions that are defined with ISOLATE(NO).

User-key programs always have read-only access to CICS-key storage.

The EXECKEY attribute is ignored in the following cases:

First-level global user exit programs, task-related user exit programs, user-replaceable programs, and PLT programs always run in CICS key.
If the program is link-edited with the RENT attribute, CICS loads the program into one of the read-only DSAs - either the RDSA or the ERDSA, depending on the residency mode specified for the program. The read-only DSAs are allocated from read-only storage only if RENTPGM=PROTECT is specified as a system initialization parameter.
Programs called by COBOL dynamic CALL always run in the same key as the caller.

EXECUTIONSET({FULLAPI|DPLSUBSET})

Specifies whether you want CICS to link to and run a program as if it were running in a remote CICS region.

DPLSUBSET: Specify DPLSUBSET if you want CICS to link to the program and run it with the API restrictions of a remote DPL program. See Exception conditions for LINK command for details of the API restrictions for a DPL program.
FULLAPI: Specify FULLAPI if you want CICS to link to the program and run it without the API restrictions of a DPL program. The program can use the full CICS API.

The EXECUTIONSET attribute applies only in these cases:

To 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.

GROUP(groupname)

Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.

Acceptable characters: `A-Z 0-9 $ @ #` Any lowercase characters you enter are converted to uppercase.

The GROUP name can be up to eight characters in length. Lowercase characters are treated as uppercase characters.

JVM({NO|YES})

Specifies whether the program is a Java program that must run in a Java Virtual Machine (JVM).

NO: The program is not to run in a JVM.
YES: The program is to run in a JVM. Specify a class name in the JVMCLASS attribute if you specify JVM(YES).

In addition to YES and NO, you can also specify DEBUG, but in compatibility mode only (see Sharing the CSD between different releases of CICS).

If you set JVM to YES, and a value is also set for JVMPROFILE (an obsolete attribute), program installation is prevented.

JVMCLASS(class)

Specifies the name (up to 255 characters in length) of the service for a Java program.

For OSGi bundles that run in a JVM server, this value is the name of the OSGi service. The OSGi service is registered when you install the BUNDLE resource that contains the OSGi bundle. You can look up the name of the OSGi service in the Bundle Parts view in CICS Explorer®.
For Java programs that run in a JVM server, this value is the class name qualified by the package name.
For applications in a Liberty JVM server, this value is wlp:className#methodName. For example: wlp:com.ibm.cics.server.examples.tsq.ClassOne#myLinkMethod. The method name is optional.

The names are case sensitive and must be entered with the correct combination of uppercase and lowercase letters. If you use a terminal, ensure that uppercase translation is suppressed.

The value for JVMCLASS can include the following characters:

Acceptable characters: `A-Z a-z 0-9 $ @ # . / - _ % & ? ! : \| " = ¬ , ; < >`

This attribute applies only to Java applications running under the control of a JVM. If you specify JVM(NO), CICS ignores any value specified in the JVMCLASS.

JVMPROFILE(jvmprofile)

This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. To run a Java program in a JVM server, use the JVMSERVER attribute instead.

JVMSERVER(jvmserver)

Specifies the name (up to 8 characters in length) of the JVMSERVER resource that contains the OSGi service. A JVMSERVER resource represents the JVM server runtime environment in CICS. The JVM server runs all programs in the CICS key.

Acceptable characters: `A-Z a-z 0-9 $ @ # . - _ % ? ! : \| = , ;`

LANGUAGE({COBOL|ASSEMBLER|LE370|C|PLI})

Specifies the program language.

ASSEMBLER: An assembler language program that was not translated using the LEASM translator option. LEASM is used to translate those assembler programs that are Language Environment-conforming MAIN programs.
C: A C or C++ program that was not compiled by a Language Environment-conforming compiler.
COBOL: A COBOL program.
LE370: A program that uses multi-language support, or has been compiled by a Language Environment-conforming compiler, or is an assembler MAIN program that was translated using the LEASM option to produce a Language Environment-conforming program.
PLI: A PL/I program.

In most cases, you do not have to specify the LANGUAGE attribute, because the CICS program manager deduces the correct language and ignores the value you specify. However, if the program is written in assembler language and does not have a DFHEAI or DFHEAG stub, CICS cannot deduce the language and you must specify the appropriate value: If the language is not specified and CICS cannot deduce it, transactions that attempt to use the program abend with code ALIG.

Although, you usually do not have to specify a value for this attribute, be aware that the value specified is returned in the LANGDEDUCED and LANGUAGE options of the INQUIRE PROGRAM command. Programs that use this command might be affected if you change the value of this attribute.

This attribute does not apply to JVM programs. CICS deduces that the program is a Java program to run under the control of a JVM when JVM(YES) is specified.

PROGRAM(name)

Specifies the name of this PROGRAM definition. The name can be up to eight characters in length.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

It is preferable not to use names that start with DFH because these characters are reserved for use by CICS.

CICS can delete or discard them and replace them with CICS resources when you upgrade or provide new function or fixes.

To use the program in an active CICS region, it must be link-edited into one of the libraries specified as part of the DFHRPL or dynamic LIBRARY concatenation. If the program is reentrant, you can place it in the link pack area (LPA). For more information about installing application programs, see Installing application programs.

RELOAD({NO|YES})

Specifies whether a program control link, load, or XCTL request is to bring in a fresh copy of a program. This attribute does not apply to JVM programs.

NO

Any valid copy of the program currently in storage is reused for the request.

YES

A fresh copy of the program is brought into storage for every request. Furthermore, each of these program copies must be removed from storage explicitly, using a storage control FREEMAIN request, when it is no longer required and before the transaction terminates. If the relevant FREEMAIN requests are not issued, areas of the DSA/EDSA become tied up with inaccessible program copies, potentially causing storage shortage or fragmentation.

Note: If a new version of the program has been placed in the LIBRARY concatenation, a NEWCOPY or PHASEIN must be issued for the program before the new version is loaded.

You can use RELOAD(YES) to load tables or control blocks that are modified by the execution of any associated programs. Do not specify this value for the first program loaded for a task, because the task does not have a way to issue a FREEMAIN request for the program.

You must specify RELOAD(YES) for nonreentrant programs.

For more information about the RELOAD attribute, see Controlling the use of modules from the MVS link pack area.

REMOTENAME(program)

Specifies the name of the program on the remote CICS region.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

If you specify REMOTESYSTEM and omit REMOTENAME, the REMOTENAME attribute defaults to the same name as the local name (that is, the program name on this resource definition).

REMOTESYSTEM(connection)

Specifies the name of an IPCONN or a CONNECTION resource that defines a link to the remote CICS region on which the program resides. Specify this attribute if you want CICS to ship a distributed program link (DPL) request to another CICS region.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

Besides the REMOTESYSTEM attribute of the program definition, the DPL server region can also be specified by the following:

The application program, using the SYSID option of the EXEC CICS LINK PROGRAM command
The dynamic routing program.

The rules of precedence are as follows:

If an application program issues a DPL request, and the SYSID option on the LINK command specifies a remote CICS region, CICS ships the request to the remote region.
If the installed program definition specifies DYNAMIC(YES), or there is no installed program definition, the dynamic routing program is called for notification only; it cannot reroute the request.
If an application program issues a DPL request, but the SYSID is the same name as the local CICS region or the SYSID option is not specified:
1. If the installed program definition specifies DYNAMIC(YES), or there is no installed program definition, the dynamic routing program is called and can route the request.
  The REMOTESYSTEM attribute of the program definition, if specified, names the default server region passed to the dynamic routing program.
2. If the installed program definition specifies DYNAMIC(NO), CICS ships the request to the remote system named on the REMOTESYSTEM attribute. If REMOTESYSTEM is not specified, CICS runs the program locally.

The rules for specifying the remote system name are the same as for the CONNECTION attribute of the CONNECTION resource definition.

Note: You must not specify remote attributes for any user-written CICS programs, such as the dynamic transaction routing or autoinstall user programs.

RESIDENT({NO|YES})

Specifies the residence status of the program. This attribute does not apply to JVM programs.

NO: The program is not to be permanently resident. This value must be specified if RELOAD(YES) is specified.
YES: The program is to be loaded on first reference and is then to be permanently resident in virtual storage, but is to be pageable by the operating system. When you specify RESIDENT(YES), CICS assumes a specification of USAGE(NORMAL).

For more information about the effects of the RESIDENT attribute, see Defining programs as resident, nonresident, or transient.

RSL

This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.

STATUS({ENABLED|DISABLED})

Specifies the program status.

DISABLED: The program cannot be used.
ENABLED: The program can be used.

This attribute is ignored for PROGRAM resources that are dynamically generated by a CICS bundle. The initial status of a PROGRAM resource is derived from the initial status of the bundle that defines the resource.

TRANSID(name)

If the program is dynamic, this value is the default TRANSID used for the distributed program link (DPL) request. If the program is not dynamic, this value specifies the name of the transaction you want the remote CICS to attach, and under which it is to run the remote program.

If you do not specify a transaction name on the TRANSID attribute, the remote region runs the DPL program under one of the following CICS-supplied default mirror transactions. If you have defined a user transaction in the remote region to call the mirror program, the DPL program runs under that transaction ID.

CPMI: The mirror transaction that is used for LU6.2 connections that require data conversion and for TCP/IP and IPIC requests from the CICS Transaction Gateway for Multiplatforms.
CSMI: The CICS mirror transaction for MRO and LU6.2 connections with sync level 2 and for EXCI and IPIC requests from the CICS Transaction Gateway for z/OS®.

USAGE({NORMAL|TRANSIENT})

Specifies when the storage for this program is released. This attribute does not apply to JVM programs.

NORMAL: When the resident use count (RESCOUNT) for this program reaches zero, it becomes eligible for removal from storage as part of the normal dynamic program storage compression process.
This value must be specified if RELOAD(YES) is specified.
TRANSIENT: When the resident use count (RESCOUNT) for this program becomes zero, the storage for this program is released. Specify this value for programs that are referenced infrequently.

USELPACOPY({NO|YES})

Specifies whether the program is to be used from the link pack area (LPA). This attribute does not apply to JVM programs.

NO: The program is not to be used from the LPA. It is loaded into the CICS address space.
YES: The program can be used from the LPA if LPA=YES is specified as a system initialization parameter. The use of the program from the LPA requires that it has been installed there and that the program is not named by the PRVMOD system initialization parameter. For more information, see Controlling the use of modules from the MVS link pack area.