API({CICSAPI|OPENAPI})
specifies which API is to be used by the program. The API attribute applies to: - User application programs
- PLT programs
- User-replaceable programs
- Task-related user exit programs. For more information, see the CICS® Customization Guide.
The API attribute does not apply to global user exits. - CICSAPI
- The program uses CICS application programming interfaces only.
CICS
determines whether the program runs on the quasi-reentrant (QR) TCB, or on
another TCB. This depends upon the value of the CONCURRENCY attribute in the
PROGRAM resource definition. If the program is defined as threadsafe it may
run on whichever TCB, in use by CICS at the time, is determined as suitable.
- OPENAPI
- The program is not restricted to the CICS application
program interfaces.
- CICS executes the program on its own L8 or L9 mode open TCB dependent
upon the value of the EXECKEY attribute in the PROGRAM resource definition.
If, while executing a CICS command, CICS requires a switch to the QR TCB,
it returns to the open TCB before handing control back to the application
program.
OPENAPI requires the program to be coded to threadsafe standards
and defined with CONCURRENCY(THREADSAFE). The primary use for OPENAPI programs
is to allow application workloads to be moved off QR TCB and onto multiple
open TCBs allowing better exploitation of machine resources to achieve better
throughput.
Use of other (non CICS) APIs in OPENAPI programs is possible.
This is because, if an open TCB is blocked by an operating system wait, then
only the single application is affected not the whole of CICS. Such OPENAPI
programs are not permitted to execute 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. See the CICS Application
Programming Guide.
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 NOEDFCEDF 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})
- 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:
- 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-reentrancy
rules. For details of these, seethe CICS Application
Programming Guide.
This value is supported for all executable
programs.
CICS ensures that the program always executes under the QR
TCB, even when control is returned after it has invoked 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, and when it accesses shared
resources it takes into account the possibility that other programs may be
executing concurrently and attempting to modify the same resources. The program,
therefore, uses appropriate serialization techniques when accessing any shared
resources.
Note that JVM programs
and any C and C++ programs
compiled with the XPLink option
must be defined as threadsafe.
For
information about CICS DB2® application programs, see the CICS DB2 Guide.
For information
about writing threadsafe application programs, see the CICS Application Programming Guide.
This
value is supported for all executable programs. Threadsafe programs must be Language Environment®-conforming, or be assembler programs.
You can also specify the program CONCURRENCY attribute
using a program autoinstall exit, if program autoinstall is active.
- DATALOCATION({BELOW|ANY})
- Commands using 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 16MB if DATALOCATION(BELOW)
is specified or allowed to default, but may be greater than 16MB if DATALOCATION(ANY)
is specified. Note that DATALOCATION does not affect the operation of the
GETMAIN command. See the CICS Application
Programming Reference for programming information about where CICS
obtains storage in response to a GETMAIN command.
- ANY
- The program can handle 31-bit addresses. The address of the data can be
above or below the 16MB line. The values specified for the DATALOCATION attribute
are independent of the addressing mode of the link-edited program. Programs
link-edited with addressing mode AMODE=24 cannot access data above 16MB; you
should therefore ensure that the value you specify is compatible with the
addressing mode of the link-edited application program. For example:
- You are recommended to specify ANY for all 31-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 16MB, 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 16MB line. If necessary, data is copied below
the 16MB line before passing its address to the application program.
- DESCRIPTION(text)
- You can provide a description of the resource 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 one. 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 invoked.
For a distributed program link (DPL) request,
the server region on which the program is to execute must be specified explicitly
on the REMOTESYSTEM attribute of the PROGRAM definition 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 invoked. Providing that a remote server region is not named
explicitly 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 execute.
The DYNAMIC attribute takes precedence over the REMOTESYSTEM
attribute—see the description of the REMOTESYSTEM attribute.
For guidance
information about the dynamic routing of DPL requests, see the CICS Intercommunication Guide.
- EXECKEY({USER|CICS})
- specifies the key in which CICS gives control to the program, and determines
whether the program can modify CICS-key storage. For all except reentrant
programs (that is, programs link-edited with the RENT attribute), EXECKEY
also defines, in conjunction with the residency mode, into which of the DSAs
CICS loads the program (see note 2).
- CICS
- This specifies that CICS is to give control to the program in CICS key
when it is invoked. 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
(see note 2).
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 or not transaction isolation is active.
- USER
- This specifies that CICS is to give control to the program in user key
when it is invoked. 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 (see Note 2 below).
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).
However,
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.
Note: - First-level global user exit programs, task-related user exit programs,
user-replaceable programs, and PLT programs always execute in CICS key, regardless
of the EXECKEY definition.
- 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, regardless of the EXECKEY
attribute. 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 execute in the same
key as the caller, regardless of the EXECKEY definition.
- 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 the CICS Application Programming Guide 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:
- 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.
- 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
lower case characters you enter are converted to upper case. |
The GROUP name can be up to eight characters in length. Lowercase
characters are treated as uppercase characters. Do not use group names beginning
with DFH, because these characters are reserved for use by CICS.
- JVM({NO|YES})
- specifies whether or not the program is a Java program that has to execute
in a Java Virtual Machine (JVM).
- NO
- The program is not to operate under a JVM.
- YES
- The program is to operate under a JVM. Specify a class name in the JVMCLASS
attribute if you specify JVM(YES).
Note: In addition to YES and NO, you can also specify DEBUG,
but in compatibility mode only (see
Compatibility mode (CSD file sharing)). DEBUG is valid only in
CICS Transaction Server for OS/390®, Version 1 Release 3.
- JVMCLASS(class)
- specifies the
fully qualified name of the main class in a Java program to be run under the
control of a JVM. The fully qualified name is the class name qualified by
the package name. For example, the package example.HelloWorld contains
the class HelloCICSWorld; in this case, the fully qualified
class name is example.HelloWorld.HelloCICSWorld.
The names
are case-sensitive and must be entered with the correct combination of upper
and lower case letters. For example, com.ibm.cics.iiop.RequestProcessor is
the class specified for the CICS IIOP request processor program, DFJIIRP.
The CEDA panels accept mixed case input for the JVMCLASS field irrespective
of your terminal's UCTRAN setting. However, this does not apply when values
for this field are supplied on the CEDA command line, or by using another
CICS transaction such as CEMT or CECI. If you need to enter a class name in
mixed case when you use CEDA from the command line or when you use another
CICS transaction, ensure that the terminal you use is correctly configured,
with upper case translation suppressed.
The value for JVMCLASS can
include the following characters:
Acceptable characters:A-Z a-z 0-9 $ @ # . / - _ % & ¢ ? ! : | " = ¬ , ; < >
For information about entering mixed case information,
see Entering mixed case attributes. |
If the program uses a single-use JVM (that is, with a JVM profile
that specifies the option REUSE=NO or the older option Xresettable=NO), you
can also use the user-replaceable program DFHJVMAT to override the JVMCLASS
specified on the installed PROGRAM resource definition (see the CICS Customization Guide). On
the PROGRAM resource definition, the limit for the JVMCLASS attribute is 255
characters, but you can use DFHJVMAT to specify a class name longer than 255
characters. Note that this attribute applies only to Java applications
running under the control of a JVM. If you specify JVM(NO), then at program
execution time CICS ignores any value specified in the JVMClass field.
- JVMPROFILE({DFHJVMPR|jvmprofile})
- specifies
the name (up to 8 characters in length) of a JVM profile. The JVM profile
is a file in the HFS directory that is specified by the system initialization
parameter JVMPROFILEDIR. Alternatively, the file can be in another place in
the HFS file system, and be referenced by a UNIX soft link from the JVMPROFILEDIR directory.
The profile contains the JVM options for the execution of the program.
If
you do not specify a JVM profile for the program, the default JVM profile
is the CICS-supplied sample JVM profile DFHJVMPR. You can customize this sample
JVM profile, or substitute your own. If you want the JVM for this program
to use the shared class cache, you can use this option to name the alternative
supplied sample JVM profile DFHJVMPC, or your own version of this profile. Java™ Applications in CICS tells you how to select
or create JVM profiles.
PROGRAM resource definitions for CICS-supplied
system programs, in particular the default request processor program DFJIIRP
(used by the CICS-supplied CIRP request processor transaction), specify the
JVM profile DFHJVMCD. This profile is reserved for use by CICS-supplied system
programs, to make them independent of any changes you make to the default
JVM profile DFHJVMPR. Only make the changes to DFHJVMCD that are necessary
to run your applications, as described in Java Applications
in CICS.
Do not specify this profile for JVMs that are to be used by your own applications.
The
supplied sample JVM profiles DFHJVMPR and DFHJVMPC, and the JVM profile DFHJVMCD
for CICS-supplied system programs, are in the HFS directory /usr/lpp/cicsts/cicsts31/JVMProfiles,
where cicsts31 is the value that you chose for the CICS_DIRECTORY
variable used by the DFHIJVMJ job during CICS installation.
The name
of a JVM profile can include the following characters:
Acceptable characters:A-Z 0-9 $ @ #
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
If you create your own JVM profiles, do not give them names
beginning with DFH, because these characters are reserved for use by CICS.
As
JVM profiles are HFS files, case is important. When you specify the name of
the JVM profile, you must enter it using the same combination of upper and
lower case characters that is present in the HFS file name. The CEDA panels
accept mixed case input for the JVMPROFILE field irrespective of your terminal's
UCTRAN setting. However, this does not apply when values for this field are
supplied on the CEDA command line, or by using another CICS transaction such
as CEMT or CECI. If you need to enter the name of a JVM profile in mixed case
when you use CEDA from the command line or when you use another CICS transaction,
ensure that the terminal you use is correctly configured, with upper case
translation suppressed.
- LANGUAGE({COBOL|ASSEMBLER|LE370|C|PLI})
- specifies the
program language.
- ASSEMBLER
- This is an assembler language program
which was not
translated using the LEASM translator option. LEASM is used to translate those
assembler programs which are to be Language Environment-conforming MAIN programs.
- C
- This is a C/370™ program
not compiled by a Language Environment-conforming compiler.
COBOL
This is a COBOL program.
- LE370
- The program exploits multi-language support, or has been compiled by a
Language Environment-conforming
compiler,
or it is an assembler MAIN program which was translated using the LEASM option
to produce a Language Environment-conforming program.
- PLI
- This is a PL/I program.
In most cases, you do not need to specify the LANGUAGE attribute,
because the CICS program manager deduces the correct language and ignores
the value you have specified. However, in the following cases, CICS cannot
deduce the language, and you must specify the appropriate value: - Programs written in assembler that do not have the DFHEAI stub
If the language is not specified, and CICS cannot deduce it, transactions
that attempt to use the program will aband with code ALIG. Although, in
most cases, you do not need to specify a value for this attribute, you should
be aware that the value specified is returned in the LANGDEDUCED and LANGUAGE
options of the INQUIRE
PROGRAM command. Programs that use this command may be affected if
you change the value of this attribute.
This attribute is irrelevant
for JVM programs; CICS deduces that the program is a Java program to run under
the control of a JVM when JVM(YES) is specified.
If you intend to share
the CSD file with a level of CICS prior to CICS/ESA 4.1, do not leave this field
blank, because — in the earlier release — the default value is COBOL, which
may not be correct.
- 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 you enter are converted
to uppercase. |
Do not use program names beginning with DFH, because these characters
are reserved for use by CICS. To use the program in an active CICS
system, it must have been link-edited into one of the libraries specified
as part of the DFHRPL DD statement or, if it is reentrant, it may have been
placed in the link pack area (LPA). For more information about installing
application programs, see the CICS Application
Programming Guide.
- 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 FREEMAINs are not issued,
areas of the DSA/EDSA become tied up with inaccessible program copies, potentially
causing storage shortage or fragmentation.
RELOAD(YES) can be used to
load tables or control blocks that are modified by execution of any associated
programs. It should not be specified for the first program loaded for a task.
This is because the task would have no way of issuing a FREEMAIN for the program.
You
must specify RELOAD(YES) for nonreentrant programs.
For more information about the RELOAD attribute, see CICS Performance Guide.
- REMOTENAME(program)
- specifies, if the program resides on a remote system, the name by which
the program is known in 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).
- REMOTESYSTEM(connection)
- specifies the name of a remote CICS region, if you want CICS to ship a
distributed program link (DPL) request to another CICS region. The name you
specify must be the name of the connection resource definition for the link
to the remote CICS.
Note
that, besides the REMOTESYSTEM attribute of the program definition, the DPL
server region can also be specified by:
- 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 EXEC CICS 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 invoked for notification only—it cannot re-route 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:
- If the installed program definition specifies DYNAMIC(YES)—or there is
no installed program definition—the dynamic routing program is invoked, 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.
- 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 the CICS Performance
Guide.
- 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 may not be used.
- ENABLED
- The program may be used.
- TRANSID(name)
- If the program is dynamic, this is the default TRANSID used for the distributed
program link (DPL) request. If the program is not dynamic, this 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 executes the DPL program
under one of the following CICS-supplied default mirror transactions:
- CPMI
- This is the CICS mirror transaction for LU6.2 connections that specify
data conversion.
- CSMI
- This is the CICS ISC mirror transaction for MRO and LU6.2 connections
with sync level 2.
- CVMI
- This is the CICS/VM mirror
transaction for LU6.2 connections with synclevel 1.
- USAGE({NORMAL|TRANSIENT})
- specifies when the storage for this program is released. This attribute
does not apply to JVM programs.
- NORMAL
- When the use count for this program reaches zero, it becomes eligible
for removal from storage as part of the normal dynamic program compression
process.
This value must be specified if RELOAD(YES) is specified.
- TRANSIENT
- When the use count for this program becomes zero, the storage for this
program is released. This value should be specified 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 guidance on this, see the CICS Transaction Server for z/OS® Installation
Guide.