Program Definitions (PD)

The Program Definitions (PD) identify the application programs, map sets, and tables that are required in a CICS® region, including those supplied by CICS. You can define remote and local programs in the PD. The Program Definitions (PD) include the following attributes:
Note: Attribute names appear as they are used on the command line, followed in parentheses by the descriptions that are used by the AIX® System Management Interface Tool (SMIT).
<Key>
This attribute specifies a unique program, map set, or table. The key can have no more than eight characters for programs and tables and no more than seven characters for map sets. The characters A through Z, a through z, 0 through 9, dollar ($), and at sign (@) can be used. (CICS converts all lowercase characters to uppercase). Names cannot begin with the sequence “DFH” because this prefix is reserved for CICS internal use. Program names do not have National Language Support (NLS). On all permanent database operations and runtime database insert operations, CICS performs class-specific validation of the bytes that form the database key.

If you are using the IBM TXSeries Administration Console, SMIT (CICS for AIX), to set this value, see Restrictions on the use of characters.

ActivateOnStartup (Activate resource at cold start?)
This attribute specifies whether a resource definition is always copied from the permanent database to the runtime database at the cold start of a region. If the attribute is set to yes, the resource definition is always copied from the permanent database to the runtime database. If the attribute is set to no, the resource definition is not copied to the runtime database, unless its group has been specified in the Groups attribute of the Region Definitions (RD). The default value is yes.
AmendCounter (Number of updates)
This attribute is reserved for CICS internal use.
EnableStatus (Program enable status)
This attribute specifies whether the program is available for use. Set the value to enabled if the program is available for use, and the value to disabled if the program is not available for use. The default value is enabled.
GroupName (Group to which resource belongs)
This attribute specifies the name of a group to which this resource definition belongs. The name is specified in an eight-byte string. For cold starts, you can specify that CICS copies, from the permanent database to the runtime database, resource definitions that belong to groups that are named in the Groups attribute of the Region Definitions (RD). (This can be done in addition to setting the ActivateOnStartup attribute to yes for resources whose definitions are to be copied on startup from the permanent database to the runtime database.) The default value is "", which specifies no group.
PathName (Program pathname)
This attribute specifies the directory path and file name for the program, mapset, or table. The default value is "".

You can specify the path in three different ways:

  • An absolute path name to the file, followed by the file name.
  • A relative path name to the file, followed by the file name. CICS interprets the path name as relative to /var/cics_regions/regionName/bin (for Open Systems) or rootDir\var\cics_regions\regionName\bin (for Windows).
  • A file name string that does not contain any slash character (/) (for Open Systems) or backslash character (\) (for Windows).

    To find a program specified as a string, CICS searches the directories in the following sequence:

    1. /var/cics_regions/regionName (for Open Systems) or rootDir\var\cics_regions\regionName (for Windows)
    2. $CICSPATH/bin (for Open Systems)

    For CICS to find a mapset that is specified as a string, the file name must have the extension .map. CICS searches the directories in the following sequence:

    1. /var/cics_regions/regionName/maps/locale (for Open Systems) or rootDir\var\cics_regions\regionName\maps\locale (for Windows)
    2. /var/cics_regions/regionName/maps/prime (for Open Systems) or rootDir\var\cics_regions\regionName\maps\prime (for Windows)
    3. $CICSPATH/maps/locale (for Open Systems) or rootDir\opt\cics\maps\locale (for Windows)
    4. $CICSPATH/maps/prime (for Open Systems) or rootDir\opt\cics\maps\prime (for Windows)

    where locale is the language that is specified for the system.

    User-defined path: You can specify the user-defined path through the environment variable CICS_PROGRAM_PATH. The CICS_PROGRAM_PATH environment variable supports standard operating-system behavior for paths. Therefore, on Windows platforms, the paths are delimited with a semicolon (;) and on Open Systems platforms, they are delimited with a colon (:).

    When a Program Definition PathName attribute specifies a file name that does not contain any slash (/) for open systems, or (\) for Windows, and the program cannot be found in the locations that are mentioned above, CICS searches the paths that are mentioned to try to load the program or map. For this search, CICS uses the CICS_PROGRAM_PATH environment variable and the PathName attribute.

    If the cicsteld command is used to connect users, the -l option can also be used to specify the language.

    To find a table that is specified as a string, CICS searches the directory /var/cics_regions/regionName/data (for Open Systems) or rootDir\var\cics_regions\regionName\data (for Windows).

For programs that are written in a language other than Java™, the file name that is specified in the PathName attribute might not contain an extension. For programs written in Java, the file name must include the .class suffix. CICS searches for the program file based on its installed extension in the following sequences:

  • On CICS for Open Systems when Micro Focus COBOL Animator is not used (not all languages are available on all operating systems):
    1. C program files (no extension).
    2. IBM COBOL files (with extension .ibmcob).
    3. Micro Focus COBOL native code files (with extension .gnt).
    4. Micro Focus COBOL intermediate code files (with extension .int).
    5. IBM PL/I files (with extension .ibmpli).
    6. IBM® C++ files (with extension .ibmcpp).
    7. COBOL-IT files (with extension .so).
  • On CICS for Open Systems when Micro Focus COBOL Animator is used (not all languages are available on all operating systems):
    1. C program files (no extension).
    2. IBM COBOL files (with extension .ibmcob).
    3. Micro Focus COBOL intermediate code files (with extension .int).
    4. Micro Focus COBOL native code files (with extension .gnt).
    5. IBM PL/I files (with extension .ibmcob).
    6. IBM C++ files (with extension .ibmcpp).
    7. COBOL-IT files (with extension .so).
  • On Windows systems:
    1. Micro Focus COBOL files (with extension .cbmfnt, .int, or .gnt); see the following note.
    2. C program files (with extension .dll).
    3. IBM COBOL files (with extension .ibmcob).
    4. IBM PL/I files (with extension .ibmpli).
    5. IBM C++ files (with extension .ibmcpp).
    6. Microsoft C++ files (with extension .cpp).

      If you have COBOL applications compiled using both COBOL-IT and Micro Focus COBOL compilers in the same directory, then extension of executable (.gnt for Micro Focus and .so for COBOL IT) is mandatory in the PathName attribute. If extension is not provided, it might result in APCT abend.

Note: The sequence by which CICS searches through Micro Focus files depends upon the following:
  • Whether you are using Micro Focus COBOL
  • If you are using Micro Focus COBOL, whether you are using Animator
If you are using Micro Focus COBOL on Windows, CICS searches for the files in this sequence whether or not you are using Animator:
  1. Micro Focus COBOL generated code files (with extension .cbmfnt)
  2. Micro Focus COBOLnative code files (with extension .gnt)
  3. Micro Focus COBOL intermediate code files (with extension .int)
If you are using Micro Focus COBOL with Animator on Open Systems, CICS searches for Micro Focus files in this sequence:
  1. Micro Focus COBOL intermediate code files (with extension .int)
  2. Micro Focus COBOL native code files (with extension .gnt)
If you are using Micro Focus COBOL without Animator on Open Systems, CICS searches only for Micro Focus files that have the extensions .gnt and .int.

If you are using Micro Focus COBOLwithout Animator on Windows, CICS searches only for Micro Focus COBOL files that have the extensions .cbmfnt.

For programs that are written for JEE server, You must create a program definition entry for EJB application in TXSeries program definition file and provide program PathName as deployed enterprise application JNDI name and the EJB method name separated with ‘#’ character.

For Example: 
PathName=“eis/Firstbean#FirstMethod”
Permanent (Protect resource from modifications?)
This attribute specifies whether amending or deleting the permanent database entry is permitted. If the attribute is set to no, the entry can be amended or deleted. If the attribute is set to yes, the entry cannot be amended or deleted. To change the entry, first reset the attribute to no. After amending the entry, set the attribute back to yes. The default value is no.
ProgType (Program type)
This attribute specifies whether the entry is a program, mapset, or table. Specify one of the values: program, map, or table. The default value is program.
RemoteName (Name to use for program on remote system)
This attribute specifies the name for a program that is to be used on a remote system. If the program resides in a remote region, enter the name by which the program is known there. If you do not specify a value for this attribute, CICS sends the program's local identifier to the remote region. The default value is "".
RemoteSysId (Remote system on which to run program)
This attribute specifies a remote system on which this program runs. If the program resides in a remote region, enter the name of a Communications Definitions (CD) entry that defines a connection to the remote region. The default value is "", meaning that the program resides on the local region.
Resident (Is this a program that should be cached?)
This attribute specifies whether a program can reside in the application server's program cache after it has been loaded. If this attribute is set to yes, CICS caches the program if space is available in the program cache. The Region Definitions (RD) ProgramCacheSize attribute determines the maximum number of programs that can reside in the cache.

Defining a program cache can improve performance because a resident program is not loaded again until one of the following occurs:

  • A SET PROGRAM COPY(PHASEIN) or SET PROGRAM PHASEIN command is issued.
  • The value of the Resident attribute is changed to no.
  • The cache is full and the program is removed to make room for a new entry. In this case, the program that was used least recently is removed, leaving more-frequently used programs in the cache.

A program is given a fresh copy of static data only when it is loaded. Therefore, if a program modifies static data, the Resident attribute must be set to no.

This attribute is ignored for Java and Micro Focus COBOL.

The default value is no.

ResourceDescription (Resource description)
This attribute specifies this PD entry with a 30-byte string. The default value is “Program Definition”.
RSLKey (Resource Level Security Key)
This attribute specifies the resource security key for the program, represented by a number from 1 through 24. If the user whose transaction issues this request does not have this RSLKey value in the RSLKeylist attribute in the User Definitions (UD), CICS raises the NOTAUTH condition. Alternatively, you can specify the value public or private. With the value public, any user can access the file. With the value private, CICS allows access to the file only from transactions that have the attribute RSLCheck set to none in their Transaction Definitions (TD) entries. The default value is private.

For more information about resource security, see Authorizing user access to CICS resources.

TemplateDefined (Is a user conversion template defined?)
This attribute specifies whether a conversion template is defined for a program. If the program can be run from a remote non-ASCII CICS system by using Distributed Program Link (DPL), and the program is passed a COMMAREA, you need to set up a conversion template for the COMMAREA. If such a template exists, set this attribute to yes; if not, set this attribute to no. The default value is no.
TransId (Transaction name on remote system for program)
This attribute specifies a transaction to attach on the server system when DPL is used. EXEC CICS LINK TRANSID overrides the value that is specified here. The default value is "". If the default value is specified, the CPMI transaction is used.
UserExitNumber (User Exit number)
This attribute specifies the number of a user exit program. It is required if the program is a user exit program. The user exit number is the last three digits of the user exit name. You can omit any leading zeros in the number. For more details about user exit naming conventions and for a table of user exit numbers, see User exits. The default value is 0, meaning that this is not a user exit program.
UserExitSequence (Order of invocation of user exit)
This attribute specifies the order/sequence of this particular user exit program when it is invoked with multiple other programs at a single exit point. It is required only if multiple user exit programs are invoked at a single exit point. The UserExitSequence must be set to a value from 0 to n. The value 0 signifies that the particular program is called as the first one, the value 1 means that the program is called as the second one and so on. The default value is 0.