This document describes the Natural CICS generation parameters.

For the parameters used to start the Natural CICS, see the section CICS Startup Parameters in Installing Natural CICS Interface on z/OS in the Natural Installation documentation.

References to CICS Tables:

Where appropriate, any references to CICS tables (DCT, FCT, PCT, PPT, TCT, TST, etc.) can be considered as references to the corresponding:

• assembly-type resource definitions,

• online resource definitions via CEDA,

• batch resource definitions via DFHCSDUP.

Related Topics:

• Installing Natural CICS Interface on z/OS in the Natural Installation documentation.

• SYSTP Utility - Natural utility which provides various TP monitor-specific functions.

• For information on operation and the individual components of Natural in a CICS environment, see the following sections in the Operations documentation:

  • Node Error Program and Timeout Considerations for Natural

  • CICS 3270 Bridge Considerations

  • Special Natural CICS Functionality

  • Natural CICS Sample Programs

  • NCIUIDEX User ID Exit Interface

  • Invoking Natural from User Programs

  • Asynchronous Natural Processing under CICS

  • Logging Natural Sessions under CICS

  • Performance Considerations

  • Natural CICS Interface Debugging Facilities

  • Natural Print and Work Files Under CICS

This document covers the following topics:

• NCISCPCB Generation Parameters

• NCMDIR Macro Parameters

• NCMTGD Macro Parameters

• NTSWPRM Macro Parameters

• NTCICSP Macro Parameters

---

NCISCPCB Generation Parameters

The Natural CICS Interface system directory is generated by assembling and linking the NCISCPCB source module; see the corresponding step in Installing Natural CICS Interface on z/OS in the Natural Installation documentation.

NCISCPCB contains the following macros:

• NCMDIR

• NCMTGD

• NTSWPRM

The purpose of these macros and the individual parameters which can be specified in the macros NCMDIR and NCMTGD are described in the following sections.

NCMDIR Macro Parameters

The NCMDIR macro is mandatory and must be specified as the first macro in the NCISCPCB source module. It contains various options for the system. The individual parameters which can be specified in the NCMDIR macro are described below.

CICSPLX | ROLLSRV | SIPSERV | SUBSID | TSKEY | TSRECSZ | USERS

CICSPLX - Switching of CICS Application Region

This parameter is applicable under z/OS only.

Possible values are:

Value	Explanation
YES	Natural CICS Interface keeps all session relevant data as the Session Information Records (SIRs) and the session data over a pseudo-conversational screen I/O outside of a local CICS Application Owning Region (AOR), thus enabling the switching of CICS AORs. Setting this parameter to YES also requires the profile parameter ADAMODE to be set to greater than 0.
MODE	This setting almost has the same meaning as YES; the only exception is that CICSPLX=MODE allows an ADAMODE=0 profile parameter specification, that is, CICS AOR switching is not possible, but a Natural session may survive the restart of a CICS AOR in an MRO environment.
NO	Vital Natural session data is kept in the local CICS AOR, which in fact disables CICS AOR switching. This is the default value.

Natural PLEX support means that a Natural CICS session removes all its footprints that exist in a CICS application region at CICS task end, as it might never come back into this region. Therefore all Natural CICS session relevant data must be kept outside of a CICS application region, that is, Natural under CICS passes its session information records (SIRs) to the Authorized Services Manager's SIP handler and the session data to the Natural Roll Server at CICS task end. In addition to that, all modules "held", that is, modules not linked to Natural but directly invoked via standard linkage conventions as RCA modules or the Adabas linkage module, have to be released at CICS task end. It also requires that the restart information is kept in a CICS terminal owning region (TOR) in case of COMARET=YES, or in a CICS data owning region (DOR), which is shared by all participating CICS AORs, in case of COMARET=NO, see the COMARET parameter for details.

If YES or MODE has been specified, and the NCMDIR SUBSID parameter has not been set, the value of the Natural profile parameter SUBSID in effect for the Natural session initializing the NCI environment will be taken.

ROLLSRV - Roll Server Rolling

This parameter is applicable under z/OS only.

Possible values are:

Value	Explanation
NO	This is the default value, if CICSPLX=NO and SIPSERV=NO. If CICSPLX or SIPSERV is YES, ROLLSRV=YES is forced.
YES	Specifying YES causes Natural CICS Interface to use the Natural Roll Server as roll facility only.

If the Natural Roll Server is to be used to save and restore the Natural session data over a screen I/O, this parameter must be set to YES, when the CICSPLX and SIPSERV parameters are both set to NO. If YES has been specified (or forced) and the NCMDIR SUBSID parameter has not been set, the value of the Natural profile parameter SUBSID in effect for the Natural session initializing the NCI environment will be taken.

Note that, for the purposes of Natural CICS Interface, the Natural profile parameter SUBSID is only honored if it is specified dynamically or in the Natural parameter module. It is ignored if it is specified in a parameter string by a profile parameter SYS or PROFILE or in an alternate parameter module (as specified with the profile parameter PARM).

SIPSERV - Authorized Services Manager's Session Information Pool

This parameter is applicable under z/OS only.

Possible values are:

Value	Explanation
NO	This is the default value, if CICSPLX=NO. If CICSPLX is not NO, SIPSERV=YES is forced.
YES	Causes Natural CICS Interface to keep its session information records (SIRs) in the Authorized Services Manager's session information pool.

With this parameter set or forced to YES, the Natural session information records are kept outside a CICS region, thus enabling Natural to switch a CICS application region after a pseudo-conversational screen I/O.

If YES is specified (or forced) and the NCMDIR SUBSID parameter has not been set, the value of the Natural profile parameter SUBSID in effect for the Natural session initializing the NCI environment will be taken.

Note that, for the purposes of Natural CICS Interface, the Natural profile parameter SUBSID is only honored if it is specified dynamically or in the parameter module. It is ignored if it is specified in a parameter string by a profile parameter SYS or PROFILE or in an alternate parameter module (as specified with the profile parameter PARM).

SUBSID - Sub-System ID

This parameter is applicable under z/OS only.

Possible values are:

Value	Explanation
xxxx	Defines the sub-system ID for the Natural Roll Server and/or for the Authorized Services Manager.

This parameter defines the Natural sub-system ID to be used for the Natural Roll Server and/or for the Authorized Services Manager. If this parameter is not specified, the value of the Natural profile parameter SUBSID will be taken.

Note that, for the purposes of Natural CICS Interface, the Natural profile parameter SUBSID is only honored if it is specified dynamically or in the Natural parameter module. It is ignored if it is specified in a parameter string by a profile parameter SYS or PROFILE or in an alternate parameter module (as specified with the profile parameter PARM).

TSKEY - Prefixes for Natural CICS Temporary Storage Key

This parameter defines the constant prefixes of the temporary storage queues (see explanation below).

This parameter has the same meaning as the TSKEY parameter in the NCIZNEP module (see the Natural Installation documentation) and must be specified identically.

Possible values are:

Value	Explanation
(xxxx,yyyy)	xxxx defines the prefix for roll data, whereas yyyy defines the prefix for pseudo-conversational restart data.
(NAT2,NCOM)	This is the default value.

When CICS temporary storage (main or auxiliary) is to be used for Natural CICS Interface roll facility or for the communication area for pseudo-conversational Natural tasks (as described with the COMARET parameter of the NTCICSP macro), names for queues of task dependent unique temporary storage must be specified.

These queue names consist of a constant 4-byte key and a task-related key. For terminal-dependent tasks, this task-related key corresponds to the terminal ID, for asynchronous non-terminal tasks it corresponds the CICS unique task number. The constant prefix of the temporary storage queue names is defined by the TSKEY parameter.

Natural CICS Interface requires two 4-byte prefixes: one for roll data and one for pseudo-conversational restart data. xxxx defines the prefix for roll data, yyyy defines the prefix for pseudo-conversational restart data. The two prefixes must be different from each other and exclusive for Natural under CICS.

When running in a CICSplex environment, the CICS temporary storage prefix for Natural session restart information must be defined in a CICS TST as REMOTE/SHARED to be accessible in all participating CICS regions.

TSRECSZ - Record Sizes for Main and Auxiliary Temporary Storage

This parameter defines the maximum record length for rolling of data if CICS temporary storage is to be used as Natural CICS Interface roll facility.

Possible values are:

Value	Explanation
(nnnnn,mmmmm)	The first subparameter nnnnn applies to CICS main temporary storage and must be in the range of 4096 to 32763 or 0 or one of the keywords MAX, YES or NO; if numeric non-zero, this value is used unconditionally; if set to 0 or NO, CICS main temporary storage cannot be used for a Natural roll facility; if set to MAX or YES, a record size of 32763 is taken. The second subparameter mmmmm applies to CICS auxiliary temporary storage and must be in the range of 3976 to 32763 or 0 or one of the keywords MAX, YES or NO; if numeric non-zero, this value is used unconditionally; if set to MAX, a record size of 32763 is taken; if set to NO, CICS auxiliary temporary storage cannot be used for a Natural roll facility; if set to 0 or YES, Natural CICS Interface sets the record length which fits into an auxiliary temporary storage control interval, that is, CI size minus VSAM control information minus CICS control information. A user-defined record size greater than CI size results in fewer (logical) roll I/O operations at the expense of additional CICS overhead due to writing spanned records.
(32748,0)	This is the default value.

USERS - Session Information Record

This parameter specifies the number of session information record slots (SIRs).

Possible values are:

Value	Explanation
(nnnnn, mmm)	The subparameter nnnnn defines the number of SIRs to be held in the Natural CICS directory module itself. nnnnn must be in the range from 1 to 32767. When the SIR slots in the directory are occupied, Natural CICS Interface acquires a CICS shared storage segment, large enough to hold the number of SIRs defined by mmm, which must be in the range from 0 to 255. If the subparameter mmm is 0 or omitted, the system does not acquire additional storage for SIRs if no free SIR slot is available in the system directory. If so, the Natural CICS system is actually restricted to the number of users specified by the first subparameter. If a value other than 0 is specified for mmm, secondary storage segments are allocated automatically as required. Allocated secondary segments are freed again if they are no longer needed.
(100,20)	This is the default value.

Natural CICS Interface permanently holds information about all active Natural sessions. Per session a so-called Session Information Record (SIR) is maintained.

These SIRs are kept

• in a Coupling Facility when running in a z/OS Parallel Sysplex environment;

• in a data space of the Natural Authorized Services Manager when running in multiple CICS regions inside a single z/OS system;

• in a CICS region's main storage when running in a single CICS AOR (locally).

However, whenever a Natural session is active in a CICS region, it will occupy a SIR slot in the current application region.

When running locally in a single CICS AOR, the USERS parameter applies to all Natural sessions. When running in a CICSplex environment, USERS applies to the subset of Natural sessions which is currently active in each of the participating CICS AORs.

NCMTGD Macro Parameters

The NCMTGD macro is mandatory and must be specified for each thread group. Natural CICS Interface allows you to define groups of threads. These groups are controlled/chosen by the CICS transaction ID at session initialization. The common thread size for the various groups may differ and the groups can have different options. The thread group definitions are part of the Natural CICS system directory, as they are relevant to the whole system, not just to a single session.

The individual parameters which can be specified in an NCMTGD macro are described below.

PFKEY | PRIMERF | THRDSZE | THREADS | TRAN | TYPE | XTRAN

PFKEY - PF/PA Keys for Thread Group

This parameter defines a single CICS transaction or a list of them.

Possible values are:

Value	Explanation
xxx	Possible values for xxx are: PF1 to PF24, PA1 to PA3.
(xxx,xxx,...)	Also a list of keys can be specified. This has to be enclosed in parantheses, for example, PFKEY=(PF12, PF14).

No default value is provided.

When starting a session, Natural CICS Interface scans through all thread group definitions for the current transaction ID, or PF or PA key. If it cannot be found, the first thread group is taken as default.

PRIMERF - Natural CICS Primary Roll Facility

This parameter defines the Natural CICS Interface primary roll facility for all tasks defined in the associated thread group. Therefore, this parameter does not apply to thread groups with TYPE=NONE.

Possible values are:

Value	Explanation
VSAM	Natural CICS Interface VSAM RRDS roll files are taken as the primary roll facility. If no VSAM RRDS roll file is available in the CICS system, PRIMERF=AUX becomes effective. If the VSAM RRDS roll files become full or is unavailable, the following applies: PRIMERF=AUX becomes effective if auxiliary temporary storage is defined in the CICS system. PRIMERF=MAIN becomes effective if auxiliary temporary storage is not defined in the CICS system.
AUX	CICS auxiliary temporary storage is taken as primary roll facility of Natural CICS Interface. If auxiliary temporary storage is not defined in the CICS system, PRIMERF=MAIN becomes effective.
MAIN	CICS main temporary storage is taken as Natural CICS Interface primary roll facility. The record size is defined by the TSRECSZ parameter. The following applies on z/OS: CICS main temporary storage is memory allocated above the bar. This avoids VSAM I/O activity and communication with a temporary storage server. As a consequence, PRIMERF=MAIN is much faster than PRIMERF=AUX and is therefore recommended if no dynamic transaction routing is used for Natural sessions. However, the roll data is split into records with a maximum size of 32 KB. Natural CICS Interface can also use CICS memory objects as a roll facility. Memory objects are allocated above the bar. However, compared to PRIMERF=MAIN, roll data does not have to be split if it is moved to a memory object. If you want to use memory objects, specify PRIMERF=MAIN and specify MEMOBJR=ON (default setting) with the NTCICSP macro (see the Parameter Reference documentation).
NONE	The associated sessions do not roll at all. NONE is not valid for TYPE=SHR groups and for groups with TYPE=ALIAS redefining TYPE=SHR groups. Sessions that are associated with thread groups defined with PRIMERF=NONE cannot be rolled because there is no roll facility to perform this task. These sessions are therefore conversational.

No default value is provided.

This parameter is ignored when using the Natural Roll Server; if you force a Natural session with Roll Server to run conversationally with no rolling, value NONE is effective.

THRDSZE - Thread Size

This parameter defines the common thread size for TYPE=GETM and TYPE=SHR groups.

Possible values are:

Value	Explanation
nnnnn	The thread size nnnnn can be in the range from 40 KB (minimum) to 65532 KB (maximum).

No default value is provided.

Note that this parameter defines the logical thread size that is available to Natural. However, Natural CICS Interface adds another 2 KB to the logical thread size for internal administration purposes. This means that the physical thread size or length of the thread GETMAIN request is by 2 KB greater than the THRDSZE value.

In case of TYPE=GETM, additional 16 bytes for the heading and trailing CICS storage accounting areas (SAAs) have to be considered.

Important Notes:

1. For GETMAINs of more than 512 KB, CICS aligns these storages at MB boundaries.

2. When using transaction isolation (z/OS only), CICS internally uses 1 MB "pages" in the EUDSA (see the CICS Performance Guide for details).

These two facts lead to storage fragmentation and should be kept in mind when setting an appropriate EDSALIM in CICS.

THREADS - Number of Threads or Tasks Per Thread Group

This parameter specifies the number of threads or tasks as described below.

Possible values are:

Value	Explanation
nnn	The number of threads can be equal to 510 or less.

No default value is provided.

For TYPE=SHR thread groups, the THREADS parameter is mandatory and defines the number of threads which are to be allocated via GETMAIN (SVC or SHARED, depending on CICS version) during installation.

For TYPE=GETM and TYPE=NONE thread groups, the THREADS parameter is optional and determines the maximum number of concurrently active Natural tasks per thread group. For these thread group types, the THREADS parameter does not control storage usage in contrast to TYPE=SHR thread groups (see also Controlling Storage Usage).

The number of threads or the number of tasks per thread group is defined by providing thread control blocks (TCBs).

While for TYPE=SHR thread groups, each thread is closely connected to its TCB. Threads are shared by queueing up on the associated TCB. Thread groups of TYPE=GETM and TYPE=NONE only queue up on a TCB to get active.

While sessions with TYPE=SHR thread groups compete for threads, the other session types compete for TCBs with a thread already allocated (TYPE=GETM) or with no allocated thread at all (TYPE=NONE).

When the THREADS parameter is non-zero, the Natural profile parameters DBROLL and MAXROLL and the calls to CMROLL are handled differently for TYPE=GETM/NONE thread groups: As threads cannot be released, the TCB resource held is released, which activates the session with the session data kept in storage.

TRAN - Transaction IDs for Thread Group

This parameter defines a single CICS transaction or a list of them.

Possible values are:

Value	Explanation
(see below)	One or more CICS transaction codes defined in the PCT for Natural.

No default value is provided.

The TRAN parameter expects transaction IDs to be in character format; transaction IDs with non-alphanumeric characters have to be enclosed in apostrophes.

When starting a session, Natural CICS Interface scans through all thread group definitions for the current transaction ID, or PF or PA key. If it cannot be found, the first thread group is taken as default.

A list of transaction IDs has to be enclosed in paranteses, for example, TRAN=(NATU, XYZ).

TYPE - Thread Type for Group

This parameter defines which type of thread is to be used for a given group.

Possible values are:

Value	Explanation
SHR	CICS shared storage threads are used. The threads available for a thread group are shared by all CICS transactions defined for this group. Thread selection when starting a CICS task is done by an ENQUEUE/DEQUEUE technique. If currently no thread is available, a wait queue for this thread group is maintained. This is the default value. When running in a z/OS Parallel Sysplex environment, the Natural parameter RELO=OFF forces sessions with TYPE=SHR threads to be conversational to prevent a CICS region switch.
GETM	Threads allocated via GETMAIN are used, which means that a thread is actually acquired performing a CICS GETMAIN operation - EXEC CICS GETMAIN FLENGTH - with the thread group's common thread size. Using threads allocated via GETMAIN, each Natural task has exclusive thread storage available until it is terminated; that is, for pseudo-conversational tasks from screen I/O to screen I/O. If the Natural parameter RELO=OFF or PSEUDO=OFF is specified, tasks using threads allocated via GETMAIN are forced to be conversational, as there is no guarantee that after a FREEMAIN of the thread a subsequent GETMAIN obtains the same storage in memory. As thread storage allocated via GETMAIN exclusively belongs to the owning task, however, such tasks can be defined as non-rollable (see the PRIMERF parameter), which means that a given thread belongs to a given task until the end of the Natural session. If so, the task is conversational by design and no rolling is done.
NONE	No threads are used by transactions defined in this thread group and all Natural GETMAIN requests are directly passed to CICS for an EXEC CICS GETMAIN FLENGTH request. By design, such tasks cannot roll and are therefore conversational.
ALIAS	The current NCMTGD macro provides different options for the thread group defined by the previous NCMTGD macro specification. However, only thread groups of TYPE=GETM and TYPE=SHR can be redefined by one or more NCMTGD TYPE=ALIAS macro requests. Up to 99 thread groups are supported, which means that up to 99 NCMTGD macro specifications with TYPE other than ALIAS are recognized.

XTRAN - Hexadecimal Transaction IDs for Thread Group

This parameter is equivalent to the TRAN parameter, but it expects the transaction ID to be in hexadecimal format.

Possible values are:

Value	Explanation
(see below)	Possible values: one or more CICS transaction codes defined in the PCT for Natural.

No default value is provided.

A list of transaction IDs in hexadecimal format has to be enclosed in parantheses, for example, XTRAN=(D5C1E3E4, E7E8E9).

NTSWPRM Macro Parameters

The NTSWPRM macro is used to define the various aspects of the swap pool. If no swap pool is to be used, omit this macro. For more information, see Natural Swap Pool in the Natural Operations documentation.

NTCICSP Macro Parameters

The parameters required for Natural CICS Interface are generated by assembling the Natural parameter module which holds the required NTCICSP macro definitions. The Natural parameter module is created in the corresponding installation step in Installing Natural CICS Interface on z/OS in the Natural Installation documentation.

The NTCICSP macro determines all Natural session options that are relevant in a CICS environment. The individual parameters contained in the NTCICSP macro are described in CICSP - Environment Parameters for Natural CICS Interface in the Parameter Reference documentation.