PROGRAM attributes
Describes the syntax and attributes of the PROGRAM resource.
- 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.
- 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).
- 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.
- 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.
JVM programs and any C and C++ programs compiled with the XPLink option must be defined as threadsafe. For compatibility with previous releases, CONCURRENCY(THREADSAFE) is the default value for Java™ programs, but the preferred option to use is CONCURRENCY(REQUIRED).
For information about CICS DB2® application programs, see Application design and development considerations for CICS DB2.
For information about writing threadsafe application programs, see Threadsafe programs.
This value is supported for all executable programs. Threadsafe programs must confirm with Language Environment®, or be assembler language 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.
REQUIRED is applicable to user application programs, PLT programs, and user-replaceable programs, and is the preferred option for Java programs. The REQUIRED setting is also suitable for programs that access resource managers like DB2 and WebSphere® MQ, which also require an L8 TCB. However, for OPENAPI programs CICS must use an L9 TCB for user key programs and an L8 TCB for CICS key programs so that non-CICS API commands such as MVS™ requests operate correctly. The CICS-DB2 task-related user exit will use an L8 TCB if it is run with CONCURRENCY(REQUIRED) and API(OPENAPI) or it will run on any eligible key 8 open TCB if run with CONCURRENCY(REQUIRED) and API(OPENAPI).
You can also specify the program CONCURRENCY attribute using a program autoinstall exit, if program autoinstall is active.
- DATALOCATION({BELOW|ANY})
- 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. 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. No restrictions apply to 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:
Any lowercase characters that you enter are converted to uppercase.A-Z 0-9 $ @ #
The GROUP name can be up to 8 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 field at program execution time.
- 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.
- 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.
It is preferable not to use names that start with DFH because these characters are reserved for use by CICS.Acceptable characters:
Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.A-Z 0-9 $ @ #
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 Defining programs as resident, nonresident, or transient.
- REMOTENAME(program)
- Specifies the name of the program on the remote CICS region.
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).Acceptable characters:
Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.A-Z 0-9 $ @ #
- 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:
Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.A-Z 0-9 $ @ #
- 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.