Natural CICS Generation Parameters

#### Search Results

Search

# Natural CICS Generation Parameters

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.

#### 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 Support

  - 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

- 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`

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

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.

| Warning: Setting this parameter to `YES` or to `MODE` automatically sets `SIPSERV` and the `ROLLSRV` parameters to `YES`.

### ROLLSRV - Roll Server Rolling

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`).

For more information about choosing between the Natural Roll Server and the roll facilities supported by Natural CICS Interface, see Choosing between Roll Server and Roll Facilities and Choosing the Roll Facility.

### SIPSERV - Authorized Services Manager's Session Information Pool

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`).

| Warning: If `YES` is effective for this parameter, the `ROLLSRV` parameter is forced to `YES`, unless already specified.

### SUBSID - Sub-System ID

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 parentheses, 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.

| Warning: At least one transaction ID (in character or hexadecimal format) or one transaction initiating attention identifier must be specified for all groups, except for the first group, which is used as the default group.

### 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.

For more information about choosing between the Natural Roll Server and the roll facilities supported by Natural CICS Interface, see Choosing between Roll Server and Roll Facilities and Choosing the Roll Facility.

### 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 `GETMAIN`s 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 parentheses, for example, `TRAN=(NATU, XYZ)`.

| Warning: At least one transaction ID (in character or hexadecimal format) or one transaction initiating attention identifier must be specified for all groups, except for the first group, which is used as the default group.

### 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 parentheses, for example, `XTRAN=(D5C1E3E4, E7E8E9)`.

| Warning: At least one transaction ID (in character or hexadecimal format) or one transaction initiating attention identifier must be specified for all groups, except for the first group, which is used as the default group.

## 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.

### On this page

- NCISCPCB Generation Parameters
- NCMDIR Macro Parameters
- NCMTGD Macro Parameters
- NTCICSP Macro Parameters