CICS Runtime Configuration Files

Overview

The administration of CICS Runtime is based on Tuxedo native tools with the addition of a limited number of configuration tables for features that are specific to CICS. In CICS configurations, resources are nowadays defined in the CSD when previously they were defined as independent tables. This latter approach is the one used with CICS Runtime.

Each resource configuration table describes a resource of a particular type: transaction, transaction class, program, file, TS Queue model, etc. Each table contains the specific parameters relevant to the resource.

Shared Responsibilities Between Tuxedo and Resource Files

A CICS resource like a transaction with all its characteristics (first program, restartable, …) is described in resource configuration files. The Tuxedo configuration elements, like how many servers of which group on which machine will offer this transaction is described in the Tuxedo configuration file UBBCONFIG.

This way the responsibilities are clearly distributed:

•	Configuration of the resources guaranties the functional behavior of a CICS application.

•	Configuration of the Tuxedo system guaranties optimal performance and robustness in production.

Resource Definition Directory

All resource configuration files are stored in a common directory indicated by a well known environment variable: ${KIXCONFIG}.

Each table describing CICS type of information is stored in a file read by servers at start time.

Presentation of Configuration Files

General Content

Each resource configuration table describes a resource type: transaction, transaction class, program, files, TS Queue, …, with all the specific parameters relevant to this resource.

The central file defines the lists of resource groups. When configuring a ART CICS server, the administrator specifies which lists to load. A single list may contain a few tens of resource groups that include hundreds or thousands of individual resources.

Structure

Each resource table contains three columns of parameters:

 

Field Name	Type	Values	Description
Name of the parameter in the table.	The data type of the field.	When specific values are required they are listed here.	Description of the purpose of the field, and its usage

The rest of this section describes in detail each of these configuration files:

•	List of Groups Configuration File

•	Transaction Configuration File

•	Tranclasses Configuration File

•	Programs Configuration File

•	TS Queue Model Configuration File

•	ENQ-Model Configuration File

•	TD Queue Extra Partition Configuration File

•	TD Queue Intra Partition Configuration File

•	Mapset Configuration File

•	System Configuration File

•	Terminal Configuration File

•	Typeterm Configuration File

•	Connection Configuration File

•	Web Service Configuration File

•	Programs List Configuration File

•	POOL Definition File

•	TCP/IP Socket Listener Configuration File

•	URIMAP Configuration File

List of Groups Configuration File

Table 4‑1 defines the lists of resource groups that may be loaded by application servers.

The filename is list_of_groups.desc.

The format of a list_of_groups.desc definition is:

List_name;group_name

List_name;group_name

… …

List_name;group_name

For example,

LIST1;SIMPAPP

LIST1;SIMPAPP1

 

Table 4‑1 Group List Parameters

Field Name	Type	Values	Description
LIST	X(10)	Mandatory	Name of the list. Referred by - L options of the application servers
GROUP	X(10)	Mandatory	Name of the group to be included in the list. This table contains one line per group to in a list. The same group may present in more than one list.

Transaction Configuration File

Table 4‑2 lists the transactions available to application users, with their characteristics.

The filename is transactions.desc.

 

Table 4‑2 Transaction Parameters

Field Name	Type	Values	Description
TRANSACTION	X(4)	Mandatory	Name of the transaction.
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
DESCRIPTION	X(60)	Optional	A small textual comment zone for description of the resource.
PROGRAM	X(8)	Mandatory	Name of the first program to be called for this transaction.
ALIAS	X(4)	Optional	Reserved for future use. Used to define an alias for the transaction (usually lower case).
CMDSEC	X(1)	N|Y	Reserved for future use. The ESM to be called for system programming requests. The default value is N.
CONFDATA	X(1)	N|Y Optional	Reserved for future use. As in confidential data: specifies whether CICS is to suppress user data from CICS trace entries when the CONFDATA system initialization parameter specifies HIDETC. If the system initialization parameter specifies CONFDATA=SHOW, CONFDATA on the transaction definition is ignored. The default value is N.
PRIORITY	9(3)	1 | n Optional	Reserved for future use. Specifies the transaction priority. This 1-to 3-digit decimal value from 0 to 255 is used in establishing the overall transaction processing priority. (Transaction processing priority is equal to the sum of the terminal priority, transaction priority, and operator priority, not exceeding 255.) The higher the number, the higher the priority. The default value is 1.
RESSEC	X(1)	N|Y	Specifies whether resource security checking is to be used for resources accessed by this transaction. The default value is N.
RESTART	X(1)	N|Y Optional	Reserved for future use. Specifies whether the transaction restart facility is to be used to restart those tasks that terminate abnormally and are subsequently backed out by the dynamic transaction backout facility. The default value is N.
STATUS	X(10)	ENABLED| DISABLED	Specifies the transaction status. • ENABLED: Allows the transaction to be executed normally. • DISABLED: Prevents the transaction being executed. The default value is ENABLED.
TASKDATAKEY	X(5)	USER |CICS	Reserved for future use. The default value is USER.
TPNAME	X(64)	Optional	Reserved for future use. Specifies the name of the transaction that may be used by an APPC partner, if the 4-character length limitation of the TRANSACTION attribute is too restrictive. This name can be up to 64 characters in length.
TRACE	X(1)	Y|N Optional	Reserved for future use. Specifies whether the activity of this transaction is to be traced. The default value is Y.
TRANCLASS	X(8)	Optional	Specifies the name of the transaction class to which the transaction belongs. Transactions belonging to a transaction class are subject to scheduling constraints before they are allowed to execute. See Tranclasses Configuration File for more information on the usage of this parameter on the target platform. A Transaction with no tranclass defined will have no other scheduling constraints than the number of servers offering it.
TWASIZE	9(5)	Optional	Specifies the size (in bytes) of the transaction work area to be acquired for this transaction. Specify a 1-to 5-digit decimal value in the range 0 through 32767. The default value is 0.
REMOTESYSTEM	X(4)	Optional	Specifies the name that identifies the intercommunication link on which the transaction attach request is sent.

Each transaction is advertised as an Oracle Tuxedo service by CICS Runtime servers, e.g. ARTSTRN, ARTATRN…. You can divide the transactions into different groups and assign the groups to different servers using option "–l", so that each server just advertise its own services.

Note:

It is not recommended to define all transactions to one group, as it causes every service to be advertised by every server and results in enormous consumption of Oracle Tuxedo services.

Tranclasses Configuration File

Table 4‑3 lists and defines tranclasses available to regulate parallel transactions activities.

The filename is tranclasses.desc.

 

Table 4‑3 Transclass Parameters

Field Name	Type	Values	Description
TRANCLASS	X(8)	Mandatory	Name of the transaction class. A tranclass defines a category of transactions, which should not be running in parallel; probably because they use some resources in a non-serializable way.
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
DESCRIPTION	X(60)	Optional	A small textual comment zone for description of the resource.
MAXACTIVE	9(3)	0 - 999	Defines the degree of parallelism of execution. The only value for which we do a special processing is value 1, see below for more information.

Semantic Information

Native Source CICS Definition

Transactions that are defined as belonging to a transaction class are subject to scheduling constraints before they are allowed to execute. If transactions belonging to an active transaction class are already running, any new transactions are queued. Use the MAXACTIVE attribute to specify the maximum number of transactions that you want to run. To limit the size of the queue, you can use the PURGETHRESH attribute.

By putting your transactions into transaction classes, you can control how CICS dispatches tasks.

Mapping to Target Platform Concepts

On Tuxedo, the scheduling of transactions and the affectation of resources to groups of transactions is performed differently; it is the number of servers offering given transactions which manages the scheduling of transactions, and the relative amount of resources affected to a group of transactions.

The Special Case of MAXACTIVE 1

This case is very specific, because it impacts the functional characteristics of the application.

It ensures that two transactions of this class will never execute concurrently. It defines a mutually exclusive behavior that is preserved on the target platform to guarantee the correct behavior of the application.

A single server ARTSTR1 will offer the transactions belonging to one TRANCLASS with MAXACTIVE = 1.

Programs Configuration File

Table 4‑4 lists and defines programs available to be referenced either as first program of a transaction, or being invoked by EXEC CICS LINK and XCTL.

The filename is programs.desc.

 

Table 4‑4 Programs Parameters

Field Name	Type	Values	Description
PROGRAM	X(8)	Mandatory	Name of the program.
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
DESCRIPTION	X(60)	Optional	A small textual comment zone for description of the resource.
LANGUAGE	X(8)	COBOL | C | C++	The language of the program, required to know how to communicate with it. Current release supports COBOL and C.
EXECKEY	X(4)		Reserved for future use. Concerns memory protection of CICS shared structures.
STATUS	X(10)	ENABLED|DISABLED	Specifies the program status. • ENABLED: Allows the program to execute normally. • DISABLED: Prevents the program being executed.
REMOTESYSTEM	X(4)	Optional	Specifies that the program is not offered locally but in a DPL server.
REMOTENAME	X(10)	Optional	Specifies for a DPL program the name of the program on the distant site. Useful only if the remote name is different from the local name.
RESCOUNT-STAT	X(10)	ENABLED|DISABLED	Specifies whether to enable the RESCOUNT information for the specified program. The default value is DISABLED, which is used when this field is not specified.
IN-TYPE	X(64)	Optional	Program input type. It describes the COMMAREA that is passed to the program. It must be the same as the subtype of the Tuxedo buffer that you use. It is only supported in ARTDPL when it is called with Tuxedo RECORD buffer.
OUT-TYPE	X(64)	Optional	Program output type. It describes the COMMAREA that the program returns. It must be the same as the subtype of the Tuxedo buffer that you use. It is only supported in ARTDPL when it is called with Tuxedo RECORD buffer.

TS Queue Model Configuration File

Table 4‑5 lists and defines theTS Queue models available to be referenced by the CICS application.

The filename is tsqmodel.desc

 

Table 4‑5 TS Queue Parameters

Field Name	Type	Values	Description
TSMODEL	X(8)	Mandatory	Name of the TS Queue model.
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
DESCRIPTION	X(60)	Optional	A small textual zone for description of the resource.
LOCATION	X(9)	AUXILIARY | MAIN	Specifies the kind of storage to use. • AUXILIARY (default): Both RDBMS-based location and file-based location are supported. If RECOVERY is set to Y, database-based location is used; If RECOVERY is set to N, file-based location is used. • MAIN: TSQ in main storage is used. This can get better access performance. TSQ data stored in main storage is unrecoverable.
PREFIX XPREFIX	X(16)	Mandatory	Specifies the character string that is to be used as the prefix for this model. The prefix may be up to 16 characters in length.
RECOVERY	X(1)	N|Y	Specifies whether or not queues matching this model are to be recoverable. • Y: Queue is stored in the RDBMS to provide recovery capabilities. • N (default): Queue is stored in file or main storage, and does not support recovery capabilities.
POOLNAME	X(8)	Optional	Deprecated. There are other ways on target to arrive to the same result. Specifies the 8-character name of the shared TS pool definition that you want to use with this TSMODEL definition.
REMOTESYSTEM	X(4)	Optional	Reserved for future use. On source platform, specifies the name of the connection that links the local system to the remote system where the temporary storage queue resides. On the target platform, used only in case of TS shipping to another system, either another TUXEDO system or native CICS system.
REMOTEPREFIX XREMOTEPREFIX	X(16)	Optional	Reserved for future use. Specifies the character string that is to be used as the prefix on the remote system. The prefix may be up to 16 characters in length. These options are useful (on source and target platforms) only if one wants to translate queue name when shipping TS Queue access from one system to another.
SECURITY	X(1)	N|Y	Reserved for future use. Specifies whether security checking is to be performed for queues matching this model. The default value is N.

ENQ-Model Configuration File

Table 4‑6 lists and defines ENQ Models available to be referenced by the CICS application.

The filename is enqmodel.desc.

 

Table 4‑6 ENQ Model Parameters

Field Name	Type	Values	Description
ENQMODEL	X(8)	Mandatory	Name of the ENQ model.
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
DESCRIPTION	X(60)	Optional	A small textual zone for description of the resource.
ENQNAME	X(255)	Mandatory	Specifies the 1 to 255-character resource name.
ENQSCOPE	X(4)	Optional	If omitted or specified as blanks, matching enqueue models will have a local scope, else they will have a global scope
STATUS	X(1)	E|D	Reserved for future use. E = Enabled. D = Disabled.

TD Queue Extra Partition Configuration File

Table 4‑7 lists and defines extra partitions TD queues available to the CICS application.

The filename is tdqextra.desc.

 

Table 4‑7 TD Queue Parameters

Field Name	Type	Values	Description
TDQUEUE	X(4)	Mandatory	Specifies the 1- to 4-character name of a transient data queue.
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
DESCRIPTION	X(60)	Optional	A small textual zone for description of the resource.
DDNAME	X(8)	Mandatory	Specifies a 1-to 8-character value that may refer to a data set defined in the startup JCL.
DISPOSITION	X(3)	Optional	Specifies the disposition of the data set. • MOD: ART-CICS first assumes that the data set exists. For an existing sequential data set, MOD causes the read/write mechanism to be positioned after the last record in the data set. The read/write mechanism is positioned after the last record each time the data set is opened for output. If ART-CICS cannot find volume information for the data set: – On the DD statement. A data set allocated dynamically in this way is deleted when the queue is closed, and all records are lost. For a new data set, MOD causes the read/write mechanism to be positioned at the beginning of the data set. • OLD: The data set existed before this job step. • SHR: The data set existed before this job step and can be read by other concurrent jobs.
ERRORPTION	X(1)	I | S	UNSUPPORTED Specifies the action to be taken if an I/O error occurs. This can be one of the following: • I = IGNORE: The block that caused the error is accepted. • S = SKIP: The block that caused the error is skipped.
OPENTIME	X(1)	D | I	UNSUPPORTED Specifies the initial status of the data set. The initial status can be one of the following: • D = DEFERRED: The data set remains closed until you indicate that you want to open it by using the CEMT INQUIRE|SET TDQUEUE command. • I = INITIAL: The data set is to be opened at install time. However, if the DSNAME attribute is not specified, and the data set name is not specified in the DD statement in the startup JCL, the transient data queue is allocated to JES during CICS startup.
RECORDFORMAT	X(1)	F | V	Specifies the record format of the data set. • F= FIXED: Fixed records. If you specify RECORDFORMAT FIXED, you must also specify a block format. • V= VARIABLE: Variable records. If you specify RECORDFORMAT VARIABLE you must also specify a block format.
PRINTCONTROL	X(1)	A |	UNSUPPORTED Specifies the control characters to be used. There is no default. If you allow RECORDFORMAT to default to blank, you cannot specify anything in the PRINTCONTROL field. The control characters that can be used are: • A= ASA: ASA control characters. • blank: No control characters are to be used.
RECORDSIZE	9(4) COMP	Optional	Specifies the record length in bytes, in the range 0 through 32767.
TYPEFILE	X(6)	Optional	Specifies the type of data set the queue is to be associated with: • INPUT: An input data set. • OUTPUT: An output data set.
DSNAME	X(80)	Optional	Specifies the name of the file that is to be used to store records written to this extrapartition queue. This file must exist even if empty.
SYSOUTCLASS	X(1)	Optional	UNSUPPORTED Instead of allocating an extra partition queue to a physical data set, you can allocate it to a system output data set (referred to as SYSOUT). Use the SYSOUT CLASS attribute to specify the class of the SYSOUT data set. A..Z|0..9 A single alphabetic or numeric character that represents an output class that has been set up on the z/OS system on which the CICS Runtime job is to run.
TRT	X(1)	S | I	New optional CICS Runtime argument, allowing integrators and customers to make their own specific implementation of extra partition queues. No value or S (for Standard) will invoke normal CICS Runtime TDQueue functionalities Setting the value I, will trigger the call to a function td_extra_actions_int, which must be provided by the integrator.
INTRDR	X(1)	Y | N	Specifies whether to define the TDQ as internal reader for JCL. • Y: The extra TDQ is internal reader for JCL. • N or Not specified: Normal TDQ.
BLOCKFORMAT	X(1)	B | U	Specifies the BLOCK format: • B: Block format • U: Unblocked format

TD Queue Intra Partition Configuration File

Table 4‑8 lists and defines intra partitions TD queues available to the CICS application.

The filename is tdqintra.desc.

 

Table 4‑8 TD Queue Parameters

Field Name	Type	Values	Description
TDQUEUE	X(4)	Mandatory	Specifies the 1- to 4-character name of a transient data queue.
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
DESCRIPTION	X(60)	Optional	A small textual zone for description of the resource.
RECOVSTATUS	X(8)	NO | LOGICAL	Specifies if the queue is logically recoverable or not. If a queue is logically recoverable, its elements will be written to tuxedo /Q in the context of the transaction and will be rolled back with the rest of the transaction in case of a rollback. If the queue is non-recoverable, then each enqueue in the /Q queue will be permanent and not rolled back in case of a rollback or abort.
TRANSID	X(4)	Optional	Specifies the name of the transaction that is to be automatically initiated when the trigger level is reached. Transactions are initiated in this way to read records from the queue. If the TRANSID attribute is not specified (or if TRIGGERLEVEL(0) is specified), you must use another method to schedule transactions to read records from transient data queues.
TRIGGERLEVEL	X(1)	1 | n	Specifies the number of records to be accumulated before a task is automatically initiated to process them. (This number is known as the trigger level.) If you specify the TRANSID attribute, TRIGGERLEVEL defaults to 1. Specify a trigger level of 0 if you want to disable ATI processing. If you do not specify a transaction ID, the trigger level is ignored. For logically recoverable transient data queues, the ATI task is not attached until the task commits forward. This may mean that the trigger level is far exceeded before ATI occurs.
USERID	X(8)	Optional	Specifies the userid you want CICS to use for security checking when verifying the trigger-level transaction specified in the TRANSID field.
WAIT	X(1)	YES | NO	INACTIVE field accepted only in the resource loading
WAITACTION	X(6)	REJECT | QUEUE	INACTIVE field Accepted only in the resource loading.
QSPACENAME	X(15)	Mandatory	New mandatory CICS Runtime argument, specifying the name of the tuxedo /Q QSPACE into which this queue is physically stored. Consult your Tuxedo /Q documentation for more information on qspaces and queue administration.
TRT	X(1)	S | I	New optional CICS Runtime argument, allowing integrators and customers to make their own specific implementation of intra-partition queues. No value or S (for Standard) will invoke normal CICS Runtime TSQueue functionalities Setting the value I, will trigger the call to a function td_intra_actions_int, which must be provided by the integrator.
ATIFACILITY	X(1)	T	Indicates a TERMINAL when it is set to T.
FACILITYID	X(4)	Optional	The terminal name when ATIFACILITY is set to T.

Mapset Configuration File

Table 4‑9 lists and defines mapsets available to be referenced by the CICS application. For more information, see tcxmapgen(1) in System Commands and Transactions.

The filename is mapsets.desc.

The format of a MAPSET definition is:

[mapset]

<field_name_1>=<field_value_1>

<field_name_2>=<field_value_2>

… …

<field_name_n>=<field_value_n>

For example,

[mapset]

name=ABANNER

filename=abanner.mpdef

 

Table 4‑9 Mapset Parameters

Field Name	Type	Values	Description
NAME	X(8)	Mandatory	Name of the mapset.
DESCRIPTION	X(60)	Optional	A small textual comment zone for description of the resource.
FILENAME	X(79)	Mandatory	This specifies the physical (binary) file name of the mapset, which is generated by the tcxmapgen tool. It will be searched in directories defined by the KIX_MAP_PATH environment variable if the absolute path is not specified. If this field is not specified, the default mapset binary file name <MAPSET_name>.mpdef will be used, in which the <MAPSET_name> is the MAPSET name parameter specified in CICS MAP related APIs.
RESIDENT	X(3)	NO | YES	Specifies the residence status of the map set. • NO: The map set is not to be permanently resident. • YES: The map set is to be loaded on first reference and is then to be permanently resident in virtual storage, but is to be pageable by the system.
swastatus	X(10)	ENABLED|DISABLED	Specifies the resource status. • If set to ENABLED, the resource is available. • If set to DISABLED, the resource is unavailable for use by the system.
Usage	X(10)	NORMAL | TRANSIENT	This attribute specifies the caching scheme to be used once the MAPSET is loaded. NORMAL keeps the MAPSET loaded in a cache. Unload it when the cache overflows and it is the oldest, least used MAPSET in the cache. TRANSIENT unloads the MAPSET if it is not being used.

 

System Configuration File

Table 4‑10 lists and defines system available to the CICS application.

The filename is system.desc.

The format of a system.desc definition is:

[SYSIDNT]

<field_name_1>=<field_value_1>

<field_name_2>=<field_value_2>

… …

For example,

[KIXA]

APPLID = DBDCKIXA

INITPARM =(DBCONNA=’instance1,database1,artuser1,abc123’)

[KIXB]

APPLID = DBDCKIXB

INITPARM =(DBCONNA=’instance2,database2,artuser2,123abc’)

Notes:

Blank lines and comment lines are supported. You can use an asterisk in column 1 to code comments, or to remove temporarily an initialization parameter from a particular execution of CICS.

Using a “\”, you can continue parameters on another line. Oracle Tuxedo Application Runtime for CICS concatenates the operands, omitting the remaining blanks after “\” in the current line. In this usage, only blank characters can appear after “\” in the current line; otherwise, ”\” will be treated as a backslash.

Load/Discover the Defined System Initialization Parameters

To load and/or discover the defined system initialization parameters, CLOPT “-s” is required to specify.

For example,

ARTSTRN

CLOPT=”-- -s KIXA”

In this example, ARTSTRN will only load the system section named KIXA (KIXB will not be loaded).

Define APPLID of Current CICS Region

To define APPLID of current CICS region, you can either specify CLOPT “-a” (Listing 4‑1) or specify APPLID parameters in system.desc (Listing 4‑2).

Listing 4‑1 Example to Specify CLOPT "-a"

*SERVERS

CLOPT=”-- -a abcdefgh“

 

Listing 4‑2 Example to Specify APPLID

[KIXR]

APPLID=1234567a

 

Oracle Tuxedo Application Runtime for CICS will firstly check whether CLOPT “-a” is specified. If it is, its value will be used as JOBNAME; otherwise, the value of APPLID set in system.desc file will be used as JOBNAME. If neither “-a” nor APPLID in system.desc is set, default value DBDCCICS will be used.

In either ways, if the value is more than 8 characters, it will be truncated to contain only the first 8 characters; if the value is less than 8 characters, APPLID will be padded spaces afterwards to be just 8 characters.

Specify GMTEXT

See this example to specify GMTEXT.

Listing 4‑3 Example of Specifying GMTEXT

[KIXR]

APPLID=DBDCKIXR

GMTEXT='An Information Development CICS Terminal'

 

GMTEXT has the following two formats.

•	Mainframe CICS format

The whole message must be enclosed by a pair of single delimiting apostrophes. You can use apostrophes as punctuation in your text; to do that, you must code two successive apostrophes to represent a single apostrophe.

For example:

GMTEXT='User''s logon message text.'

•	ART for CICS format

Apostrophe does not act as an escape character. (This way is an easier way to edit your message.)

For example:

GMTEXT=User's logon message text.

 

Table 4‑10 System Parameters

Field Name	Type	Values	Description
SYSIDNT	X(4)	Mandatory	Name of a system section to define a CICS region. The length of name is 1 - 4 characters. The default name is CICS. The name of a system section and that of the defined CICS region should be the same. Note: If more than one sections share a same SYSIDNT, the final configuration for this CICS region will possess all the parameters defined in these sections. If a parameter is defined more than once in these sections, only the last one will make sense.
APPLID	X(8)	DBDCCICS|applid, Optional	Identifies the CICS region in the VTAM network. The length of name is 1 - 8 characters. The default value is DBDCCICS.
INITPARM	X(60)	Mandatory	Specifies initialization parameters in system initialization table (SIT) for each CICS application program that invokes ASSIGN INITPARM. The INITPARM format is INITPARM=(pgmname_1='parmstring_1'[,...,pgmname_n='parmstring_n']). We now support at most 255 sets of program=’parmstring’. The value of program should consist of 1 - 8 alphanumeric characters and will be truncated if exceeding the length limit. The value of parmstring should be at most 60 characters and will be truncated if exceeding the length limit. Parameter string should be enclosed by single quotes; any quotes imbedded in the string must be duplicated. Note: In each section, if INITPARM parameters are specified more than one time, only the last definition will take effect.
LGNMSG	X(3)	NO | YES, Optional	A system initialization parameter which specifies whether logon data is available to an application program.
GMTEXT	X(246)	Optional	GMTEXT is a system initialization parameter. GMTEXT specifies whether the default logon message text (Oracle Tuxedo Application Runtime for CICS) or your own message text is to be displayed on the logon screen. The message text is displayed by CSGM transaction when a terminal is logged on to ART for CICS. GMTEXT should be at most 246 characters long and is truncated if it is longer. (See Specify GMTEXT for an example.) To enable GMTEXT, it is required to configure CLOPT -s option with your [SYSIDNT] for ARTCNX server. For more information, see ARTCNX Configuration.
GMTRAN	X(4)	Optional	A system initialization parameter which specifies the name of the transaction that is initiated by ATI when terminals are logged on to ART CICS. The GMTRAN format is GMTRAN={CSGM|CESN|transaction-id}, where the default value is CSGM. Note: To enable GMTRAN, it's also required to specify LOGONMSG=YES in typeterms.desc; however, if LOGONMSG is specified to NO, the screen will be cleared.
BMS	X(60)	DDS|NODDS, Optional	Specifies whether to enable DDS (Device Dependent Support). The default value is DDS, meaning DDS is enabled. With DDS, BMS uses the following rules to select a physical map: • BMS appends the suffix specified in ALTSUFFIX to map set names if the screen size being used is the same as the alternate screen size. In other word, if a transaction has SCRNSIZE(ALTERNATE) specified in the TYPETERM definition, or if the default screen has the same size as the alternate screen, BMS map selection routines try to load the map set with the suffix specified in ALTSUFFIX. • If there is no such map set found, BMS tries to load an unsuffixed map set version.
TYPE	X(8)	ARTCICS | TMASNA	Optional. The default value is ARTCICS.
PLTPI	X(2)	Optional	Name of the PLT suffix. The length of SUFFIX is 1-2 characters.
PLTSD	X(2)	Optional	Name of the PLT suffix. The length of SUFFIX is 1-2 characters.
SRM_IPCKEY	9(6)	IPCKEY	Optional. SRM_IPCKEY specifies the IPCKEY (the identifier) of the shared memory segment. Use SRM_IPCKEY only when your ARTSRM server uses shared memory to store runtime information (if ARTSRM uses database, SRM_IPCKEY is ignored). If you do not specify SRM_IPCKEY when using shared memory, ARTSRM uses its Tuxedo group number to generate an IPCKEY. Within in a single CICS region, SRM_IPCKEY must be the same for every ARTSRM in this region, and all of these ARTSRM servers must run on the same machine.
SRM_LOCATION	X(32)	MEMORY|DB	Specifies the storage media for ARTSRM. • Memory (default): uses shared memory to store data • DB: uses database to store data
PGAIPGM	X(8)	INACTIVE|ACTIVE	The PGAIPGM system initialization parameter specifies the state of the program autoinstall function at initialization. • INACTIVE: The program autoinstall function is disabled. • ACTIVE (default): The program autoinstall function is enabled.
CICS_RELEASE	X(4)	Optional	Specifies CICS system code that returns in CICS INQUIRE SYSTEM RELEASE command. You can specify CICS system code either through environment variable KIX_CICS_RELEASE or through CICS_RELEASE in system configuration file. If both KIX_CICS_RELEASE and CICS_RELEASE in systems.desc are configured, the value in systems.desc is returned. If neither KIX_CICS_RELEASE nor CICS_RELEASE in systems.desc is configured, value '0660' (corresponding to CICS 4.1) is returned.

Note:

Section names and keys are case-insensitive; however, values are case-sensitive. The max length of each key is 64 characters and that of each value is 32767 characters.

Terminal Configuration File

Table 4‑11 lists and defines terminal available to the CICS application.

The filename is terminals.desc.

The format of a terminal definition is:

[terminal]

<field_name_1>=<field_value_1>

<field_name_2>=<field_value_2>

… …

For example,

[terminal]

name=0001

netname=CICS0001

katakana=YES

[terminal]

name=0002

netname=CICS0002

katakana=YES

ART CICS stores all the terminal runtime status by using Tuxedo /Q. For more information about configuring and using Tuxedo /Q, please see Implementing Asynchronous CICS Delayed Transactions.

 

Table 4‑11 Terminal Parameters

Field Name	Type	Values	Description
ALTSUFFIX	X(1)	0-9|a-z|A-Z, Optional	Specifies a 1-character ALTSUFFIX name for the terminal. Only an alphanumeric character or a blank, which means no suffix, is accepted. The value is case-insensitive and will be converted to upper-case automatically.
KATAKANA	x (3)	NO | YES, Optional	Specifies whether KATAKANA support is required. NO: Default value. KATAKANA function is disabled. YES: KATAKANA function is enabled. Other values: Invalid values. System will automatically search KATAKANA in typeterms.desc.
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
NAME	X(4)	Mandatory	Terminal identifier. Note: When there are multiple entries with same TERMID, the last entry takes effect. If the length exceeds, the value will be ignored and warning message will be logged in ULOG; if the length is shorter than four characters, spaces will be padded on the right.
NETNAME	X(8)	Mandatory	Network name of the terminal. Note: The value of NETNAME must be unique; otherwise, ARTCNX server fails to boot and reports the error output in ULOG and stdout. If the length exceeds, the value will be ignored and warning message will be logged in ULOG; if the length is shorter than eight characters, spaces will be padded on the right.
INSERVICE	X(3)	NO | YES, Optional	Specifies the status of the terminal that is being defined. YES: Transactions may be initiated and messages may automatically be sent to the terminal. NO: The terminal can neither receive messages nor transmit input. The default value is YES. If this field is defined to neither of above values, it is treated as YES.
ATI	X(3)	NO | YES, Optional	Specify whether or not the terminal is available for use by transactions that are automatically initiated from within CICS. YES: The terminal is available for use by transactions that are automatically initiated from within CICS. NO: The terminal is not available for use by transactions that are automatically initiated from within CICS. If this field is defined to neither of above values, it is treated as UNKNOWN. However, in the event that the same field in typeterms.desc is defined to UNKNOWN as well, the final value of this field is YES.
TTI	X(3)	NO | YES, Optional	Specifies whether transactions can be initiated at the terminal by a user. YES: Transactions can be initiated at the terminal by a user. If you also specify ATI(YES), transactions can also be initiated automatically. In this case, the automatic transaction initiation, either by transient data control or interval control, sets a condition in an appropriate terminal control table terminal entry. If both ATI and TTI are specified as YES, and if there is no transaction at the terminal, terminal control initiates the user-defined task. This task is expected to send messages to the terminal. For a terminal used in the processing of transactions such as inquiries or order entries, specify TTI(YES) and ATI(NO). This also applies to a display station or hard-copy terminal to which no messages are sent without a terminal request and through which transactions are entered. Note that this is the only specification allowed for 3790 inquiry logical units. NO: Transactions cannot be initiated at the terminal by a user. If you specify NO, specify ATI(YES) to allow transactions to be initiated automatically. An example of this type of terminal is one that is located in a remote location, such as a warehouse, and is unattended but may receive messages. If this field is defined to neither of above values, it is treated as UNKNOWN. However, in the event that the same field in typeterms.desc is defined to UNKNOWN as well, the final value of this field is YES.

Notes:

The section name must be set to "terminal"; all keywords are case-insensitive.

ART CICS reserves "."; users can use it neither in NAME nor in NETNAME when defining terminals.desc.

Typeterm Configuration File

Table 4‑12 lists and defines Typeterms supported by ARTTCP.

The filename is typeterms.desc.

The format of a typeterm definition is:

[typeterm]

<field_name_1>=<field_value_1>

<field_name_2>=<field_value_2>

… …

<field_name_n>=<field_value_n>

For example,

[typeterm]

name=IBM-3278-2

userarealen=255

katakana=YES

 

Table 4‑12 Typeterm Parameters

Field Name	Type	Values	Description
ALTSCREENCOLUMN	9(3)	{80|132|…}	Specifies the terminal screen size total columns. If the SCRNSIZE=alternate, this parameter is mandatory.
ALTSCREENROW	9(3)	{24|32|43|27|…}	Specifies the terminal screen size total rows If the SCRNSIZE=alternate, this parameter is mandatory.
ALTSUFFIX	X(1)	0-9|a-z|A-Z Optional	Specifies a 1-character ALTSUFFIX name for the typeterm. Only an alphanumeric character or a blank which means no suffix is accepted. The value is case-insensitive and will be converted to upper-case automatically.
DESCRIPTION	X(79)	Optional	A small textual zone for description of the resource.
EXTERCODE	X(10)	{ibm-37 | ibm-1388|ibm-1380|…}	Specifies which encoding type of outbound data is used. The value of this attribute could be any EBCDIC encoding type used in z/OS platform. The default value is ibm-37.
INTERCODE	X(10)	{ASCII | UTF-8|Shift-JIS|…}	Specifies which encoding type of inbound data is used. The value of this attribute could be any encoding type used in universal platform. The default value is ASCII.
NAME	X(79)	Mandatory	Name of the typeterm.
PROGSYMBOLS	X(3)	NO | YES	Specifies whether the programmed symbol (PS) facility is supported or not. The default value is NO.
SCRNSIZE	X(9)	DEFAULT|ALTERNATE	Optional. Specifies whether to send/receive map/text with alternative screen size or not. The default value is DEFAULT which does not send/receive map/text with alternative screen size.
SOSI	X(3)	NO | YES	Specifies whether mixed EBCDIC and double-byte character set (DBCS) is supported or not. The default value is NO.
color	X(3)	NO | YES	Designates extended color attributes.
defscreencolumn	9(3)	80	Number of columns of the default screen size.
defscreenrow	9(3)	24	Number of rows of the default screen size.
hilight	X(3)	NO | YES	Indicates whether a terminal supports the highlight feature or not.
logonmsg	X(3)	NO | YES	Indicates whether the “Good Morning” (CSGM) transaction is automatically started on the terminal or not. Oracle Tuxedo ART provides a default CSGM transaction. Please refer to section for the configuration of the default “Good Morning” (CSGM) transaction.
outline	X(3)	NO | YES	Indicates whether the terminal supports field outlining or not.
swastatus	X(10)	ENABLED| DISABLED	Specifies the resource status. • If set to ENABLED, the resource is available. • If set to DISABLED, the resource is unavailable for use by the system
uctran	X(10)	NO | YES | TRAN	• YES: translate lowercase alphabetic characters to uppercase. • NO: do not translate lowercase alphabetic characters to uppercase • TRAN: only translate the transaction ID from lowercase to uppercase.
userarealen	9(3)	0 ~ 255	The terminal control table user area (TCTUA) area size for the terminal.
KATAKANA	x(3)	NO | YES, Optional	Specifies whether KATAKANA support is required. The default value is NO. KATAKANA function can be enabled only if KATAKANA is specified to YES. Note: You can either set KATAKANA in terminals.desc or typeterms.desc; however, only if KATAKANA in terminals.desc is not specified to YES or NO, KATAKANA specified in typeterms.desc will take effect.
ATI	X(3)	NO | YES, Optional	Specifies whether transactions can start at the terminal by automatic transaction initiation. YES: Transactions can start at the terminal by automatic transaction initiation. NO: Transactions cannot start at the terminal by automatic transaction initiation. ATI(YES) allows transactions to be started at the terminal by transient data control or by an EXEC CICS START command issued by another transaction. If there is already a transaction at the terminal, the ATI transaction is held until it ends. If you specify ATI(YES), you must specify an IOAREALEN of at least one byte, except for DEVICE(APPC) when ATI and IOAREALEN have forced default values of YES and 0. If ATI is specified as YES and CREATESESS is specified as YES, and if a transaction is initiated when the terminal is not ACQUIRED, it is automatically acquired. If this field is defined to neither of above values, it is treated as YES.
TTI	X(3)	NO | YES, Optional	Specifies whether transactions can be initiated at the terminal by a user. YES: Transactions can be initiated at the terminal by a user. If you also specify ATI(YES), transactions can also be initiated automatically. In this case, the automatic transaction initiation, either by transient data control or interval control, sets a condition in an appropriate terminal control table terminal entry. If both ATI and TTI are specified as YES, and if there is no transaction at the terminal, terminal control initiates the user-defined task. This task is expected to send messages to the terminal. For a terminal used in the processing of transactions such as inquiries or order entries, specify TTI(YES) and ATI(NO). This also applies to a display station or hard-copy terminal to which no messages are sent without a terminal request and through which transactions are entered. Note that this is the only specification allowed for 3790 inquiry logical units. NO: Transactions cannot be initiated at the terminal by a user. If you specify NO, specify ATI(YES) to allow transactions to be initiated automatically. An example of this type of terminal is one that is located in a remote location, such as a warehouse, and is unattended but may receive messages. If this field is defined to neither of above values, it is treated as YES.

Connection Configuration File

Table 4‑13 lists and defines connections that can be loaded by ART CICS application servers. Connection configuration file is mandatory to set for ARTCTRN but optional to set for other servers.

The filename is connections.desc.

The format of a connection definition is:

[CONNID]

<field_name_1>=<field_value_1>

<field_name_2>=<field_value_2>

...

<field_name_n>=<field_value_n>

 

Table 4‑13 Connection Parameters

Field Name	Type	Values	Description
CONNID	X(4)	Mandatory	Name of the connection.
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
PROTOCOL	X(4)	Mandatory APPC | LU61	Specifies the type of protocol that implements the connection.
NETNAME	X(8)	Mandatory	Specifies the APPLID of a CICS region, which receives the connection.
MAXIMUM	0~999， 0~999	Mandatory (only for APPC)	Specifies the maximum number of sessions in the modeset. The format is MAXIMUM=value_1,value_2, where Value_1 must be greater than or equal to value_2.
RECEIVECOUNT	999	Mandatory (only for LU61)	Specifies the number of receive sessions; receive sessions can only receive before sending.
SENDCOUNT	999	Mandatory (only for LU61)	Specifies the number of send sessions; send sessions must send before they can receive.

Web Service Configuration File

Table 4‑14 defines the web services available to the CICS application.

The filename is webservice.desc.

 

Table 4‑14 Web Services Parameters

Field Name	Type	Values	Description
SERVICE	X(256)	Mandatory	Name of the service
REQUEST	X(256)	Mandatory	RECORD name of the request
RESPONSE	X(256)	Mandatory	RECORD name of the response
TRANSACTION	X(1)	N | Y Optional	Specifies the service to support or not support the transaction. If this field is not specified, the service does not support the transaction.

Programs List Configuration File

Table 4‑15 lists and defines programs list available to the CICS application server ARTDPL boot or shutdown.

The filename is program_list_table.desc.

The format of a program_list_table.desc definition is:

[plt]

<field_name_1>=<field_value_1>

<field_name_2>=<field_value_2>

...

<field_name_n>=<field_value_n>

For example,

[plt]

SUFFIX=p1

PROGRAM= RSSBT001, RSSBT002

Notes:

Blank lines and comment lines are supported. You can use an asterisk in column 1 to code comments, or to remove temporarily an initialization parameter from a particular execution of CICS.

Using a "\", you can continue parameters on another line. Oracle Tuxedo Application Runtime for CICS concatenates the operands, omitting the remaining blanks after "\" in the current line. In this usage, only blankcharacters can appear after "\" in the current line; otherwise, "\" is treated as a backslash

To load and/or discover the defined programs list, you have two ways: one is add "-b" or "-d" option in ARTDPL CLOPT, and the other is to define the SUFFIX in the system.desc PLTPI/PLTSD parameter.

For example:

ARTDPL CLOPT="-s KIXA -l SIMPAPP -b p1"

In this example, ARTDPL will load and execute the programs named RSSBT001, RSSBT002 during its initialization.

 

Table 4‑15 CICS Application Programs List

Field Name	Values	Type	Description
SUFFIX	X(2)	Mandatory	Name of the PLT suffix. The length of SUFFIX is 1-2 characters
PROGRAM	X(1024)	Mandatory	Specifies the program list. The format is: PROGRAM=program [,...,programn]. The value of program should consist of 1 - 8 alphanumeric characters.

If the programs in the PROGRAM is not defined or is disabled in programs.desc, when the application server boot or shutdown, it will ignore this program.

If more than one items in the Program_list_table.desc with the same SUFFIX are defined, only the first takes effect.

POOL Definition File

Table 4‑16 defines the pools available to the CICS application.

The filename is pool.desc.

The format of a pool.desc definition is:

[POOL]

<field_name_1>=<field_value_1>

<field_name_2>=<field_value_2>

…

For example,

[POOL]

NAME=TSPOOL1

 

Table 4‑16 POOL Parameters

Field Name	Type	Values	Description
NAME	X(8)	A-Z 0-9 $ @ # _	Mandatory. Specifies the 8-character pool name.
MAXSIZE	9(18)	number	Reserved for future use. Optional. Specifies the maximum size in Kilobytes allocated for the pool. The default value is 0, standing for no limit.
AUTOINCREASE	X(1)	Y|N	Reserved for future use. Optional. Specifies auto-increase space if no room is left. The default value is N.
ELEMENTWARN	9(3)	1-100	Reserved for future use. Optional. Specifies the percentage of space usage at which a warning message is uttered. The default value is 80.

TCP/IP Socket Listener Configuration File

This configuration file defines TCP/IP socket listener information. Table 4‑17 lists its parameters.

The file name is listener.desc; it does not support dynamic configuration. The format is:

[ListenerGroupID]

<field_name_1>=<field_value_1>

<field_name_2>=<field_value_2>

 

Table 4‑17 TCP/IP Socket Listener Parameters

Field Name	Type	Values	Description
AF	X(5)	Optional	Listener Address Family. Use INET (default) or INET6.
APPLID	X(8)	Optional	Reserved for future use. The APPLID for this listener.
BACKLOG	Short	Optional	The number of unaccepted connections that can be queued to this listener. The default value is 20.
CSDELAY	X(6)	Optional	Reserved for future use. This parameter is specific to the enhanced version of the listener and is applicable only if CSSTTYP is IC. It specifies the delay interval to be used on the EXEC CICS START command, in the form hhmmss (hours/minutes/seconds).
CSSTTYP	X(2)	Optional (Used in enhanced mode)	This parameter is specific to the enhanced version of the listener and specifies the default start method for the user transaction. Only supports KC value (default), indicating that the user transaction is started using EXEC CICS START with no delay interval.
CSTRAN	X(4)	Optional (Mandatory in enhanced mode)	This parameter is specific to the enhanced version of the listener and specifies the default transaction that the listener starts in ARTATRN/ARTATR1.
FORMAT	X(8)	Optional	Mode of the listener. The default value of STANDARD indicates that this is the original ART for CICS listener that requires the client to send the standard header. The value of ENHANCED indicates that this is the enhanced ART for CICS listener that does not expect the standard header from the client.
GIVTIME	Short	Optional	The time in seconds this listener waits for a response to a TAKESOCKET. If this time expires, the listener assumes that either the server transaction did not start or the TAKESOCKET failed. At this time, the listener sends the client a message indicating the server failed to start and close the socket (connection). The default value is 60.
IPADDRESS	X(46)	Optional	IP address.
MSGLEN	Short	Optional (Used in enhanced mode)	This parameter is specific to the enhanced version of the listener and specifies the length of the data to be received from the client. The valid range is 0 to 999 byte. If the value is 0, the listener does not read in any data from the client.
PEEKDAT	Short	Optional (Used in enhanced mode)	This parameter is specific to the enhanced version of the listener and applies only if MSGLEN is not 0. A value of NO indicates that the listener performs a normal read of the client data. The user transaction accesses this data in the data area-2 portion of the transaction input message (TIM). A value of YES indicates that the listener reads the data using the peek option; the data remains queued in TCP/IP and the user transaction actually read it in rather than accessing it through the TIM.
PORT	Short	Mandatory	The port number this listener uses for accepting connections.
REATIME	Short	Optional	The time in seconds this listener waits for a response to a RECV request. If this time expires, the listener assumes that the client has failed and terminates the connection by closing the socket. If this parameter is not specified, checking for read timeout is not performed.
TRANID	X(4)	Optional	Reserved for future use. The transaction name for this listener.
TYPE	X(3)	Optional	Type of the created socket. Only supports TCP.

URIMAP Configuration File

The resource definitions that match the URIs of HTTP and provide information on how to process the requests.

The file name is urimaps.desc.

 

Table 4‑18 URIMAP Parameters

Field Name	Type	Values	Description
UIRMAP	X(8)	Mandatory	Name of URIMAP
GROUP	X(10)	Mandatory	The group notion of CICS allowing a group of related resources to be declared and instantiated or not by a CICS system when starting.
DESCRIPTION	X(60)	Optional	A small textual comment zone for description of the resource.
STATUS	X(10)	ENABLED| DISABLED	This parameter describes URIMAP status. Default value is ENABLED.
PATH	X(255)	Mandatory	This parameter specifies the path component of the URI to which the URIMAP definition applies. PATH can be up to 255 characters, including the forward slash (/) at the beginning of the path component.
SCHEME	X(6)	HTTP|HTTPS	This parameter specifies the scheme component of the URI to which the URIMAP definition applies. Default value is HTTP.
USAGE	X(10)	CLIENT| SERVER| PIPELINE| ATOM	This parameter specifies whether this URIMAP definition is for CICS as an HTTP server (SERVER), CICS as an HTTP client (CLIENT), a Web service (PIPELINE), or an Atom feed (ATOM). Default value is SERVER. ART for CICS only supports CLIENT.

 

Table 4‑19 Client Parameters

Field Name	Type	Values	Description
HOST	X(116)	Mandatory	This parameter specifies the host name of the URI to which the URIMAP definition applies, or its IPv4 or IPv6 address.
PORT	X(8)	NO|Number	This parameter specifies the decimal number of the port used by a CICS application when it communicates with a server. PORT must be a number in the range 1 − 65535. Set NO to indicate that the attribute is not used.
CERTIFICATE	X(32)	Optional	Not supported. This parameter specifies the label of the X.509 certificate that is used as the SSL client certificate during the SSL handshake.
CIPHERS	X(56)	Optional	Not supported. This parameter specifies a string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.
AUTHENTICATE	X(10)	NO|BASIC	Not supported. This parameter specifies whether to send HTTP basic authentication information to the HTTP server. Default value is NO.
SOCKETCLOSE	X(6)	0|hhmmss	Not supported. This parameter specifies if, and for how long, CICS keeps a client HTTP connection open after the CICS application has finished using it.
SERVICE	X(64)	Mandatory	This parameter specifies Tuxedo SALT service name that maps for remote endpoint.