Installing Natural CICS Interface on z/OS

#### Search Results

Search

# Installing Natural CICS Interface on z/OS

This document describes the steps for installing Natural CICS Interface (product code NCI) on z/OS.

- Prerequisites

- Installation Medium

- Prefix Used for Natural CICS Interface Components

- Installation Procedure

- CICS Startup Parameters

- CICS Resource Definitions

- Installation Verification

#### Related Topics:

For information on how to operate Natural in a CICS environment, see Using Natural with TP Monitors and Natural under CICS in the TP Monitor Interfaces documentation and the following topics:

- NCISCPCB Generation Parameters

- CICSP - Environment Parameters for Natural CICS Interface (`NTCICSP` macro) in the Parameter Reference documentation

- Customization of VSAM RRDS Roll Files

- NCISCPRI Warnings and Error Messages

#### Notation vrs or vr:

When used in this document, the notation `vrs` or `vr` represents the relevant product version (see also Version in the Glossary).

## Prerequisites

A supported version of the following product must be installed before you can install the Natural CICS Interface:

- Adabas CICS Interface (product code ACI), version as specified under Software AG Product Versions Supported by Natural in the current Natural Release Notes for Mainframes.

See also General Prerequisites and System Support in the section Overview of the Installation Process.

## Installation Medium

The installation medium contains the following data sets required for product installation:

Data Set Name | Contents
--- | ---
`NCIvrs.LOAD` | Load modules
`NCIvrs.SRCE` | Source modules and macros
`NCIvrs.OBJS` | Object modules
`NCIvrs.JOBS` | Sample installation jobs
`NCIvrs.LICS` | Product license file for Natural for CICS for zIIP For information on the license file and product licensing, see Software AG Mainframe Product Licensing.

Copy the data sets into your environment as described in Copying Data Sets to a z/OS Disk in the section Installing Natural.

#### Sample Jobs

Sample installation jobs are contained in the `NATvrs.JOBS` data set and are prefixed with the product code. The data set is provided on the installation medium supplied for base Natural.

## Prefix Used for Natural CICS Interface Components

When used in this document, `prefix` denotes a common Natural CICS Interface prefix of 1 to 5 characters, for example, `NCIvr`. This prefix is determined by the value of the parameter `PREFIX` in the `NTCICSP` macro of the Natural parameter module, for example, in Step 5 of the Installation Procedure. `NTCICSP` and `PREFIX` are described in the Parameter Reference documentation.

`prefix` is followed by specific characters to make up the names of the following objects:

`prefixCB` | Natural CICS Interface system directory, for example, `NCIvrCB`
`prefixR1` to `prefixR9` | Natural CICS Interface VSAM RRDS roll files (optional)
`prefixXFA` | Natural CICS Interface 3270 Bridge `XFAINTU` exit

## Installation Procedure

Before you start the installation procedure for the Natural CICS Interface, be sure to read the following:

- System Control under CICS in the TP Monitor Interfaces documentation

- Installation Process and Major Natural Features

The installation procedure comprises the following:

- Step 1: Customize CICS

- Step 2: Prepare, Convert, Assemble and Link the License File for Natural for CICS for zIIP

- Step 3: Allocate the VSAM RRDS Roll Files for the Natural CICS Interface

- Step 4: Build the Natural CICS Interface System Directory Module

- Step 5: Build the Natural Parameter Module

- Step 6: Link the Environment-Dependent Nucleus

- Step 7: Link the Natural CICS Interface System Directory

- Step 8: Link the Natural CICS Interface External CALLNAT Interface Module

- Step 9: Link the Natural CICS Interface Node Error Program

- Step 10: Link the Natural CICS Interface XFAINTU Exit

- Step 11: Link the Natural CICS Interface zIIP Shutdown Statistics Program

- Step 12: Link the Natural RPC Server Front-End

- Step 13: Initialize the VSAM Roll Files

### Step 1: Customize CICS

(Job I005, Steps 2211 - 2216, 2230 - 2235, 2240 - 2245)

1. Steps 2211 - 2216 and 2230 - 2235:

   Create CICS RDO entries as described in CICS Resource Definitions and apply the batch resource definitions with the DFHCSDUP utility program.

2. Steps 2240 - 2245 (optional):

   These steps are only required if you want to dynamically load an ICU data item without using the SVC instruction on request during a Natural session instead of an entire ICU data library:

   Set `CFICU=(DATITEM=NONE)` and add one PPT entry for each ICU data item.

   See also the corresponding step in Installing International Components for Unicode for Software AG.

   ICU data items and ICU data libraries are described in the Unicode and Code Page Support documentation.

### Step 2: Prepare, Convert, Assemble and Link the License File for Natural for CICS for zIIP

(Job I007, Steps 2201, 2202, 2204)

This step is optional and only required if you want to install Natural for CICS for zIIP.

You must install a valid Natural license file. An additional license file is required if you want to install Natural for CICS for zIIP to enable support of the IBM z/IIP (IBM System z Integrated Information Processor).

For detailed information on the license file and product licensing, see Software AG Mainframe Product Licensing.

1. Copy the license file from the supplied installation medium to disk or transfer it from the PC as described in Transferring a License File from PC to a z/OS Host Using FTP in Software AG Mainframe Product Licensing.

2. Check, convert, assemble and link the license file supplied for Natural for CICS for zIIP:

   Step 2201 | Check license file `NCIvrs.LICS`. This job runs the CHECK function of the LICUTIL license utility (see below).
   Step 2202 | Convert license file into an assembler source. This job runs the MAKE function of the LICUTIL license utility (see below).
   Step 2204 | Assemble and link the assembler source to generate load module `NCILIC`. This module is then linked to the nucleus in Job I080.

   The functions and option settings provided by LICUTIL are described in Using the License Utility: LICUTIL in Software AG Mainframe Product Licensing.

### Step 3: Allocate the VSAM RRDS Roll Files for the Natural CICS Interface

(Job I008, Step 2200)

This step must be performed only if VSAM roll files are used as CICS roll facility.

- Allocate the VSAM RRDS roll files for the Natural CICS Interface.

  The Natural CICS Interface uses VSAM RRDS roll files for optimum performance, which means without CI/CA splits.

### Step 4: Build the Natural CICS Interface System Directory Module

(Job I070, Steps 2245, 2250)

- Edit, assemble and link the `NCISCPCB` module.

  The Natural CICS Interface system directory is generated by assembling and linking the source module `NCISCPCB`.

  A sample job is contained in the `NATvrs.JOBS` data set and a comprehensive sample source in the `NCIvrs.SRCE` data set.

  For descriptions of the individual macros and parameters contained in `NCISCPCB`, see NCISCPCB Generation Parameters in the TP Monitor Interfaces documentation.

### Step 5: Build the Natural Parameter Module

(Job I080, Steps 2210, 2220)

Build the Natural parameter module for the Natural CICS Interface:

1. The `NTCICSP` macro in the Natural parameter module contains parameters specific to the Natural CICS Interface. You can generally use the default values for all parameters.

   You can generally use the default values for all parameters. Modify only the values of those parameters whose default values do not suit your requirements. The only mandatory parameter without a default value is the common Natural CICS Interface prefix.

   To simplify the Natural parameter module installation process, the source module `NTCICSP` contains the `NTCICSP` macro request with parameter `PREFIX=&SYSPARM`. Thus, when generating a parameter module for the Natural CICS Interface, assemble the Natural parameter module with the assembler option `SYSPARM=prefix` rather than editing the source module.

   The individual `NTCICSP` macro parameters are described in CICSP - Environment Parameters for Natural CICS Interface in the Parameter Reference documentation.

2. Modify the settings of the supplied Natural profile parameters as required and in accordance with the settings you specified when building the Natural parameter module for batch mode during the Installation Procedure for base Natural.

   Make sure that the profile parameters `FNAT` and `FUSER` are set to the same values you specified when loading the system file. The parameters and corresponding macros (if applicable) are described in the Parameter Reference documentation.

3. Assemble and link the Natural parameter module.

Anmerkung
The parameters specified with the `NTCICSP` macro are copied into the Natural CICS Interface system directory module `NCISCPCB` (linked as described in Step 7) when this module is initialized by the first Natural session using it. To ascertain that parameter changes become effective immediately:

- build the Natural parameter module.

- link the environment-dependent nucleus as described in Step 6.

- issue `CECI RELEASE PROGRAM(...)` for the Natural CICS Interface system directory module.

- issue `CEMT SET PROGRAM(...) NEWCOPY` for both the environment-dependent nucleus and the Natural CICS Interface system directory module.

### Step 6: Link the Environment-Dependent Nucleus

(Job I080, Step 2230)

- Link the environment-dependent nucleus for the Natural CICS Interface with the `NCINUC` module and the Natural parameter module built in Step 5.

  Include the CICS stub module `DFHELII` (do not use `DFHEAI`).

  When linking the environment-dependent nucleus or its subcomponents, you may receive `IEW2646I` or `IEW2660W` messages, which can be ignored.

See also Natural Nucleus under CICS in the TP Monitor Interfaces documentation.

### Step 7: Link the Natural CICS Interface System Directory

(Job I080, Step 2250)

- Link the Natural CICS Interface system directory into your CICS user library under the module name `prefixCB` (see Prefix Used for Natural CICS Interface Components).

  The Natural CICS Interface system directory must be linked with the `NORENT` option.

### Step 8: Link the Natural CICS Interface External CALLNAT Interface Module

(Job I080, Steps 2270, 2271)

This step must be performed only if you want to use the external `CALLNAT` interface module of the Natural CICS Interface.

For more information, see Natural 3GL CALLNAT Interface - Purpose, Prerequisites, Restrictions in the Operations documentation.

- Link the external `CALLNAT` interface module `NCIXCALL`.

  See also Natural Nucleus under CICS in the TP Monitor Interfaces documentation.

  Step 2270 is needed if the `NCIXCALL` module has been installed in the same CICS region with a previous Natural version. The previous Natural version `NCIXCALL` module must then be assigned a new name, for example `NCIXCIOV`. Thus, you can preserve the name of the `NCIXCALL` module used in the previous version and need not link it to all your 3GL programs using it.

  Step 2271 links the module `NCIXCALL` for the current Natural version.

### Step 9: Link the Natural CICS Interface Node Error Program

(Job I080, Step 2275)

This step must be performed only if you want to use the node error program (NEP) of the Natural CICS Interface. See also CICS Node Error Program Considerations for Natural in the TP Monitor Interfaces documentation.

- Link the Natural CICS Interface module `NCIZNEP`.

  See also Natural Nucleus under CICS in the TP Monitor Interfaces documentation.

### Step 10: Link the Natural CICS Interface XFAINTU Exit

(Job I080, Step 2280)

This step must be performed only if you want to use Natural with the CICS 3270 Bridge. See also CICS 3270 Bridge Support in the TP Monitor Interfaces documentation.

- Link the Natural CICS Interface module `NCIXFATU` under the name `prefixXFA` (see Prefix Used for Natural CICS Interface Components).

  See also Natural Nucleus under CICS in the TP Monitor Interfaces documentation.

### Step 11: Link the Natural CICS Interface zIIP Shutdown Statistics Program

(Job I080, Step 2285)

This step must be performed only if you want to install Natural for CICS for zIIP, and want to print Natural zIIP statistics when the CICS environment is shut down.

- Link the Natural CICS Interface zIIP shutdown statistics program.

### Step 12: Link the Natural RPC Server Front-End

(Job I080, Step 2290)

This step must be performed only if you want to use the Natural RPC server front-end under CICS.

- Link the Natural RPC server front-end module `NCIRSFE` under the defined name by using the `NCISFED` module.

### Step 13: Initialize the VSAM Roll Files

(Job I081, Step 2200)

This step must be performed only if VSAM roll files are used as CICS roll facility.

- Initialize the VSAM roll files.

  This step must be repeated for all roll files used if roll files are the primary roll facility.

  A VSAM RRDS file is a direct (random) access type file that must be formatted.

  For the Natural CICS Interface VSAM roll files, formatting is done by the `NCISCPRI` batch program. To execute `NCISCPRI`, the Natural roll file to be initialized has to be assigned the file name `ROLL` in the JCL DD statement. No other parameter input is required for `NCISCPRI`; all data required for file initialization is obtained by `SHOWCB` VSAM macro calls.

For descriptions of the messages that can be output during this step, see NCISCPRI Warnings and Error Messages in the TP Monitor Interfaces documentation.

## CICS Startup Parameters

The Natural CICS Interface modules described in this section use startup parameters to initialize Natural CICS Interface components. The `EXEC CICS ASSIGN` command retrieves the value set by these startup parameters with the `INITPARM` option using the following syntax:

INITPARM=(module='parameter',...)

where:

`module` is the name of the module that uses a startup parameter. This is the name indicated in the individual module link steps described in this Abschnitt.
`parameter` the name of the corresponding parameter.

The relevant Natural CICS Interface modules and corresponding parameters are described in the following section:

- NCIXCALL Module - External CALLNAT Interface

- NCIXFATU Module - CICS Global User Exit

- NCIZNEP Module - CICS Node Error Program

- NCIRSFE Module - Natural RPC Server Front-End

- Example of INITPARM

### NCIXCALL Module - External CALLNAT Interface

`parameter` is the name of an `NCIXCALL` module from a previous Natural version (for example, `NCIXCIOV`), if available. The `NCIXCALL` module from the previous Natural version must be linked to assign it a new and different name (see Step 8: Link the Natural CICS Interface External CALLNAT Interface Module).

For more information, see Natural 3GL CALLNAT Interface - Purpose, Prerequisites, Restrictions in the Operations documentation.

### NCIXFATU Module - CICS Global User Exit

`parameter` is the name of the Natural CICS Interface Node Error Program linked in Step 9: Link the Natural CICS Interface Node Error Program.

Even if you do not want to modify the default node error program (NEP) DFHZNEP provided by CICS that executes `NCIZNEP` and terminates a session when a user disconnects a terminal from the CICS region, you need to install and setup `NCIZNEP`.

The installation is described in Step 9: Link the Natural CICS Interface Node Error Program and the required startup parameters are described in NCIZNEP Module - CICS Node Error Program.

For further information, see CICS Node Error Program Considerations for Natural in the TP Monitor Interfaces documentation. For more information on the `NCIXFATU` module, see CICS 3270 Bridge Support in the TP Monitor Interfaces documentation.

### NCIZNEP Module - CICS Node Error Program

For information on the `NCIZNEP` module, see CICS Node Error Program Considerations for Natural in the TP Monitor Interfaces documentation.

The individual `NCIZNEP` parameters are described in the following section:

> MSGTRAN - Internal Message Switching Transaction ID

>   This parameter specifies the transaction ID internally used by the Natural message switching and asynchronous session flushing facilities.

>   This parameter has the same meaning as the `MSGTRAN` parameter in `NTCICSP` (see the Parameter Reference documentation) and must be specified identically.

>   The transaction ID specified with this parameter must be different from any transaction ID used to invoke Natural, and it must be defined in CICS.

>   Possible values are:

>   Value | Explanation
>   --- | ---
>   `transaction-id` | A CICS transaction ID for which the `PROGRAM` attribute specifies the name of the environment-dependent nucleus linked in Step 6: Link the Environment-Dependent Nucleus. The Natural CICS Interface clean-up function is done by starting an asynchronous task to resume the terminal session and to terminate it logically. Therefore, normally the original transaction ID of the session is used. This original transaction ID cannot be used if there is a front-end program calling Natural, as most likely the front-end is not prepared for being invoked asynchronously without a terminal. In such situations, the message switching transaction ID of the Natural CICS Interface is used to deal with Natural directly.
>   `NMSG` | This is the default value.

> NEPTRAN - Transaction ID for the NCIZNEP Module

>   This parameter specifies the transaction ID for the Natural/CICS Interface node error program (NEP) `NCIZNEP` in an MRO environment, when the parameter `PURGE` (see below) is set to `YES`.

>   Possible values are:

>   Value | Explanation
>   --- | ---
>   `transaction-id` | A CICS transaction ID for which the `PROGRAM` attribute specifies the name of the `NCIZNEP` module linked in Step 9: Link the Natural CICS Interface Node Error Program.
>   `NETR` | This is the default value.

> PURGE - Purge Active Natural Task

>   This parameter defines how `NCIZNEP` is to treat Natural sessions currently active, when the Natural/CICS Interface node error program (NEP) is invoked.

>   Possible values are:

>   Value | Explanation
>   --- | ---
>   `NO` | This is the default value for compatibility reasons. The active Natural task is not purged. The active task will continue to run until a terminal I/O later on will result in abend `NT08` due to a CICS TERMERR condition, as the terminal no longer exists.
>   `YES` | The active Natural task is purged immediately.

>   In MRO environments, a node error program is triggered in the CICS TOR; as the Natural session most likely is active in a CICS AOR, the task purge cannot be done in the TOR. Therefore, a transaction ID is required (see `NEPTRAN` above) to start a "partner" NEP task in the AOR to do the task purge.

>   Anmerkung
>   `PURGE=YES` requires that the relevant Natural transactions are defined as purgeable (`SPURGE(YES)`).

> TSKEY - Prefix for Natural CICS Temporary Storage Key

>   This parameter defines the constant prefix of the temporary storage queue holding the Natural CICS Interface pseudo-conversational restart data.

>   Possible values are:

>   Value | Explanation
>   --- | ---
>   `xxxx` | `xxxx` defines the prefix for pseudo-conversational restart data.
>   `NCOM` | This is the default value.

>   This parameter has the same meaning as the second subparameter of the parameter `TSKEY` in the `NCMDIR` macro (see the TP Monitor Interfaces documentation) and must be specified identically.

### NCIRSFE Module - Natural RPC Server Front-End

> NATTRAN – CICS Transaction ID for Name of Environment-Dependent Nucleus

>   This parameter defines the CICS transaction ID that is used to retrieve the name of the environment-dependent nucleus linked in Step 6: Link the Environment-Dependent Nucleus if the name is not supplied as `START` data. The `PROGRAM` attribute of this transaction ID specifies the name of the environment-dependent nucleus.

>   Possible values are:

>   Value | Explanation
>   --- | ---
>   `transaction-id` | A CICS transaction ID for which the `PROGRAM` attribute specifies the name of the environment-dependent nucleus linked in Step 6: Link the Environment-Dependent Nucleus.
>   `NC83` | This is the default value.

> MSGDEST – Message Destination for Natural RPC Server Front-End

>   This parameter defines the message destination for the Natural RPC server front-end.

>   Possible values are:

>   Value | Explanation
>   --- | ---
>   `message-destination` | A CICS message destination ID to which the messages of the Natural RPC server front-end are to be sent.
>   `CSSL` | This is the default value.

> TRACE – Issue Trace Requests on Entry and Return

>   This parameter defines whether CICS trace requests are issued on entry to and return from the `NCIRSFE` module.

>   Possible values are:

>   Value | Explanation
>   --- | ---
>   `destination-id` | CICS trace requests are issued on entry to and return from `NCIRSFE`.
>   `CSSL` | CICS trace requests are not issued. This is the default value.

> GLOBAL – Establish Unique Natural RPC Server IDs

>   This parameter defines unique Natural RPC server IDs over more than one CICS region.

>   Possible values are:

>   Value | Explanation
>   --- | ---
>   `NO` | The Natural RPC server ID consists of the Natural RPC server front-end transaction ID padded with dollar signs ($). This is the default value.
>   `YES` | The Natural RPC server ID consists of the Natural RPC server front-end transaction ID appended to the CICS system ID, or in other words, to the local `SYSID`.

### Example of INITPARM

The following is an example of an `INITPARM` specification:

    INITPARM=(
      NCIXCALL='NCIXCOLD',                           * NCIXCALL module
      NCI22ATU='NCIZNEP',                            * NCIXFATU module
      NCIZNEP='MSGTRAN=NMSG,TSKEY=NCOM,PURGE=YES',   * NCIZNEP module
      NCI33SFE='NATTRAN=NC83,MSGDEST=CSSL'           * NCIRSFE module
    )

The example above assumes the following:

- `NCIXCALL` is the name of the `NCIXCALL` module linked in Step 8: Link the Natural CICS Interface External CALLNAT Interface Module.

- The `NCIXCALL` module from the previous Natural version has been linked to assign it the new name `NCIXCOLD`.

- `NCIZNEP` is the name of the `NCIZNEP` module linked in Step 9: Link the Natural CICS Interface Node Error Program.

- `NCI22ATU` is the name of the `NCIXFATU` module linked in Step 10: Link the Natural CICS Interface XFAINTU Exit.

- `NCI33SFE` is the name of the `NCIRSFE` module linked for the Natural RPC server in Step 12: Link the Natural RPC Server Front-End.

## CICS Resource Definitions

This section describes the resource definitions required or recommended for customizing your CICS system.

Anmerkung
We generally recommend that you keep all Natural version-dependent components such as programs, transactions and files in a separate resource group. Such a group is represented by `natgroup` in this section.

- Program Definitions

- Transaction Definitions

- File Definitions

- Transient Data Destinations

- Temporary Storage Queues

- Other Definitions

### Program Definitions

To take full advantage of the CICS storage protection and transaction isolation facilities, it is strongly recommended that you specify `EXECKEY(USER)` as the default value for all programs. This section explains if `EXECKEY(CICS)` is required for a definition. In all other cases, use `EXECKEY(USER)`.

The following table provides information about the value combinations of the `API` and `CONCURRENCY` program attributes. The appropriate value combination must be specified consistently for all programs that call one another using direct branch (BASR) instructions:

#####

Program attributes | Remarks
--- | ---
`API(CICSAPI)` `CONCURRENCY(QUASIRENT)` | Use these attributes if not all affected programs are threadsafe.
`API(OPENAPI)` `CONCURRENCY(REQUIRED)` | Use these attributes if you want to take advantage of the CICS open transaction environment (OTE) and can confirm that all affected programs are threadsafe. For using the CICS OTE, adapt the program definitions as described in the following section. For general information on using Natural in the CICS OTE, see CICS Open Transaction Environment Considerations in the TP Monitor Interfaces documentation. For further information, see also Threadsafe Considerations in the TP Monitor Interfaces documentation.
`API(OPENAPI)` `CONCURRENCY(THREADSAFE)` | Same as `API(OPENAPI)` `CONCURRENCY(REQUIRED)`.
`API(CICSAPI)` `CONCURRENCY(REQUIRED)` | This attribute combination is not supported by the Natural CICS Interface.
`API(CICSAPI)` `CONCURRENCY(THREADSAFE)` | This attribute combination is not supported by the Natural CICS Interface.
`API(OPENAPI)` `CONCURRENCY(QUASIRENT)` | This attribute combination is prohibited by CICS.

The value combination affects all user-written 3GL programs, as well as front-end programs that call the environment-dependent nucleus of Natural. The front-end programs can be delivered with Natural add-on products or be user-written. Examples of affected programs include NCIRSFE (Natural RPC server front-end), NATCNRFE (Natural Web I/O Interface Server CICS Adapter and Natural Development Server CICS Adapter), and the programs supplied with the Natural CICS Interface listed in the following section.

- Environment-Dependent Nucleus
- Environment-Independent Nucleus
- Natural CICS Interface System Directory
- External CALLNAT Interface Module
- Routing Module for Quasi-Reentrant Standard Linkage Calls (%P=SQ)
- Node Error Program
- Global User Exit
- Natural RPC Server Front-End
- Natural zIIP Shutdown Statistics

#### Environment-Dependent Nucleus

- Add a program definition for the environment-dependent nucleus:

      DEFINE PROGRAM(dep-nuc) GROUP(natgroup) LANGUAGE(ASSEMBLER)         *
               DESCRIPTION(ENVIRONMENT-DEPENDENT NUCLEUS)

  where `dep-nuc` is the environment-dependent nucleus linked in Step 6: Link the Environment-Dependent Nucleus.

  The following attribute settings for the program definition are mandatory when using the CICS OTE and recommended otherwise:

      DATALOCATION(ANY)

      API(OPENAPI)

      CONCURRENCY(REQUIRED)

  Anmerkung
  If you use the CICS OTE and your application issues many Db2 requests, using `EXECKEY(CICS)` may improve performance because it prevents CICS from switching from an L9 to an L8 open TCB and back again for every SQL call.

#### Environment-Independent Nucleus

This definition is optional.

- Add a program definition for the environment-independent nucleus:

      DEFINE PROGRAM(ind-nuc) GROUP(natgroup) LANGUAGE(ASSEMBLER)           *
               DESCRIPTION(NATURAL ENVIRONMENT-INDEPENDENT NUCLEUS)

  where `ind-nuc` is the name of the environment-independent nucleus specified with the Natural profile parameter `NUCNAME`. The default name is `INDNUCvr`. You need not specify `API`, `CONCURRENCY`, `DATALOCATION` or `EXECKEY` for the environment-independent nucleus as all attributes of the environment-dependent nucleus are inherited since standard linkage conventions (direct branch using a BASR instruction) are used.

  To access the environment-independent nucleus in the ELPA, specify `USELPACOPY(YES)` for this program definition and `LPA=YES` in the CICS startup parameters.

#### Natural CICS Interface System Directory

- Add a program definition for the Natural CICS Interface system directory:

      DEFINE PROGRAM(prefixCB) GROUP(natgroup) LANGUAGE(ASSEMBLER)            *
               DESCRIPTION(NATURAL CICS INTERFACE SYSTEM DIRECTORY)

You need not specify `API`, `CONCURRENCY`, `DATALOCATION` or `EXECKEY` for this module as it is not executable. The attribute `EXECKEY` defaults to `EXECKEY(USER)` and must not be changed.

#### External CALLNAT Interface Module

This definition is optional.

- Add a program definition for the external `CALLNAT` interface module:

      DEFINE PROGRAM(ncixcall) GROUP(natgroup) LANGUAGE(ASSEMBLER)            *
               DESCRIPTION(NATURAL CICS INTERFACE EXTERNAL CALLNAT MODULE)

  where `ncixcall` is the name of the `NCIXCALL` module specified in Step 8: Link the Natural CICS Interface External CALLNAT Interface Module.

  The following attribute settings for the program definition are mandatory when using the CICS OTE and recommended otherwise:

      DATALOCATION(ANY)
      API(OPENAPI)
      CONCURRENCY(REQUIRED)

  The values of `EXECKEY`, `CONCURRENCY` and `API` for `ncixcall` must be the same as for the environment-dependent nucleus because Natural is called by `ncixcall` using standard linkage conventions (direct branch using a BASR instruction) instead of the `EXEC CICS LINK` command.

#### Routing Module for Quasi-Reentrant Standard Linkage Calls (%P=SQ)

This definition is only required if you want to use the `%P=SQ` terminal command (see the Terminal Commands documentation) or the `PGP` profile parameter with the `STDLQ` property set (see the Parameter Reference documentation).

- Add a program definition for the routing module for quasi-reentrant standard linkage calls (`%P=SQ`) in a threadsafe environment:

      DEFINE PROGRAM(NCILINKQ) GROUP(natgroup) LANGUAGE(ASSEMBLER)           *
             CONCURRENCY(QUASIRENT) API(CICSAPI)                             *
                   DESCRIPTION(ROUTING MODULE FOR QUASI-REENTRANT SL CALLS)

  We recommend that you set the following parameter value in the CICS program definition:

      DATALOCATION(ANY)

#### Node Error Program

This definition is optional.

- Add a program definition for the node error program (NEP) of the Natural CICS Interface:

      DEFINE PROGRAM(nciznep) GROUP(natgroup) LANGUAGE(ASSEMBLER)            *
               EXECKEY(CICS)                                                 *
               DESCRIPTION(NATURAL CICS INTERFACE NODE ERROR PROGRAM)

  where `nciznep` is the NEP name specified in Step 9: Link the Natural CICS Interface Node Error Program.

#### Global User Exit

This definition is optional.

- Add a program definition for the `XFAINTU` global user exit:

      DEFINE PROGRAM(prefixXFA) GROUP(natgroup) LANGUAGE(ASSEMBLER)          *
               EXECKEY(CICS)                                                 *
               DESCRIPTION(NATURAL CICS INTERFACE XFAINTU GLUE)

#### Natural RPC Server Front-End

This definition is only required if you want to use the Natural RPC server front-end `ncisfe`.

- Add a program definition for the Natural RPC server front-end:

      DEFINE PROGRAM(ncirsfe) GROUP(natgroup) LANGUAGE(ASSEMBLER)            *
               DESCRIPTION(NATURAL RPC SERVER FRONT-END)

  where `ncirsfe` is the name of the `NCIRSFE` module specified for the Natural RPC server front-end in Step 12: Link the Natural RPC Server Front-End.

  The following attribute settings for the program definition are mandatory when using the CICS OTE and recommended otherwise:

      DATALOCATION(ANY)

      API(OPENAPI)

      CONCURRENCY(REQUIRED)

  The values of `API`, `CONCURRENCY` and `EXECKEY` for `ncirsfe` must be the same as for the environment-dependent nucleus because Natural is called by `ncirsfe` using standard linkage conventions (direct branch using a BASR instruction) instead of the `EXEC CICS LINK` command.

#### Natural zIIP Shutdown Statistics

These definitions are only required if you want to print Natural zIIP statistics when the CICS environment is shut down (see also zIIP Processing Reports Available in the Natural for zIIP documentation). Using Natural for zIIP requires using the CICS OTE.

The Natural zIIP shutdown statistics are written to the CSSL queue (directed to DD name `MSGUSR`).

1. Add a program definition to load the `NCIZPST` module:

       DEFINE PROGRAM(NCIZPST) GROUP(natgroup) LANGUAGE(ASSEMBLER)           *
                API(OPENAPI) CONCURRENCY(REQUIRED)                         *
                DESCRIPTION(NATURAL ZIIP SHUTDOWN STATISTICS)

   Add a program definition to load the `NATZPST` module:

       DEFINE PROGRAM(NATZPST) GROUP(natgroup) LANGUAGE(ASSEMBLER)           *
                DESCRIPTION(NATURAL ZIIP SHUTDOWN STATISTICS)

2. Add the `NCIZPST` module to the CICS PLTSD as a first phase PLT program.

### Transaction Definitions

We recommend that you define or choose a CICS profile for the Natural transactions similar to the following:

    DEFINE PROFILE(natprof) GROUP(natgroup)                                *
             DESCRIPTION(CICS PROFILE FOR NATURAL TRANSACTIONS)            *
             SCRNSIZE(ALTERNATE) INBFMH(ALL)

where `natprof` is the name of the CICS profile assigned to the Natural transactions.

We also recommend that you define a CICS transaction class for the Natural transactions similar to the following:

    DEFINE TRANCLASS(natclass) GROUP(natgroup) MAXACTIVE(999)              *
             DESCRIPTION(CLASS FOR NATURAL TRANSACTIONS)

where `natclass` is the name of the CICS transaction class assigned to the Natural transactions.

A CICS transaction class dedicated to Natural helps control storage usage by Natural (see also Controlling Storage Usage in the TP Monitor Interfaces documentation). Assign this transaction class to the definitions of all transactions that directly or indirectly call Natural.

You can define the following:

- Natural Transaction
- Natural Message Switching Transaction
- Node Error Program
- Natural RPC Server Front-End

#### Natural Transaction

- Add a definition for the Natural transaction:

      DEFINE TRANSACTION(ncitransact) GROUP(natgroup)                        *
               PROGRAM(dep-nuc) TWASIZE(128) DUMP(NO) SPURGE (YES)           *
               PROFILE(natprof) TRANCLASS(natclass)

  where:

  `ncitransact` is the name of the Natural CICS Interface user transaction ID.
  `dep-nuc` is the environment-dependent nucleus linked in Step 6: Link the Environment-Dependent Nucleus.

  We recommend that you set the following parameter values in the CICS transaction definitions:

      TASKDATALOC(ANY)

      ISOLATE(YES)

  `TASKDATALOC(ANY)` can have an impact on non-Natural programs called by Natural; for details, see the relevant IBM literature on CICS.

  For the impact of transaction isolation, see also THRDSZE - Thread Size in the TP Monitor Interfaces documentation.

#### Natural Message Switching Transaction

- Add a definition for the Natural internal message switching transaction:

      DEFINE TRANSACTION(nmsg) GROUP(natgroup)                               *
               PROGRAM(dep-nuc) TWASIZE(128) DUMP(NO) SPURGE (YES)           *
               PROFILE(natprof) TRANCLASS(natclass)

  where:

  `dep-nuc` is the environment-dependent nucleus linked in Step 6: Link the Environment-Dependent Nucleus.

  `nmsg` is the name of the Natural CICS Interface message switching transaction ID as defined with the `MSGTRAN` parameter in the `NTCICSP` macro described in the Parameter Reference documentation. The default name is `NMSG`.

  We recommend that you set the following parameter values in the CICS transaction definitions:

      TASKDATALOC(ANY)

      ISOLATE(YES)

  `TASKDATALOC(ANY)` can have an impact on non-Natural programs called by Natural; for details, see the relevant IBM literature on CICS.

  For the impact of transaction isolation, see also THRDSZE - Thread Size in the TP Monitor Interfaces documentation.

#### Node Error Program

This definition is optional.

- Add a definition for the node error program (NEP) of the Natural CICS Interface:

      DEFINE TRANSACTION(neptran) GROUP(natgroup)                            *
               PROGRAM(nciznep) DUMP(NO) PRIORITY(255)                       *
               TASKDATAKEY(CICS) TASKDATALOC(ANY)                            *
               PROFILE(natprof)

  where:

  `neptran` is the NEP transaction code defined with the `NEPTRAN` parameter of the `NCIZNEP` module linked in Step 9: Link the Natural CICS Interface Node Error Program.

  `nciznep` is the NEP name of the `NCIZNEP` module linked in Step 9: Link the Natural CICS Interface Node Error Program.

#### Natural RPC Server Front-End

- Add a definition for the Natural RPC server front-end transaction:

      DEFINE TRANSACTION(ncisfetransact) GROUP(natgroup)                     *
               PROGRAM(ncirsfe) TWASIZE(128) DUMP(NO) SPURGE (YES)           *
               PROFILE(natprof) TRANCLASS(natclass)

  where:

  `ncisfetransact` is the name of the Natural RPC server front-end transaction ID.
  `ncirsfe` is the name of the `NCIRSFE` module specified for the Natural RPC server front-end in Step 12: Link the Natural RPC Server Front-End.

### File Definitions

These definitions are only required if VSAM roll files are to be used.

- Add one entry in the FCT for each Natural CICS Interface VSAM roll file:

      DEFINE FILE(prefixR1) GROUP(natgroup)                                  *
               BROWSE(YES) ADD(YES) DELETE(YES) UPDATE(YES) READ(YES)        *
               RECORDFORMAT(F) STRINGS(3) DATABUFFERS(5)

  Local shared resources (LSR) should be used whenever possible. If multiple LSR pools are supported, one pool should be dedicated exclusively to Natural CICS Interface roll files.

### Transient Data Destinations

- Error Messages
- Natural NATRJE Utility
- Natural CICS Interface Session Statistics
- Natural CICS Interface Profile Parameter File

#### Error Messages

This definition is optional but highly recommended to log Natural CICS Interface informational messages and Natural abend codes and corresponding error messages.

Add entries in the DCT for the Natural CICS Interface error message logging facility. For Natural error messages, you can use:

- A destination that is already defined in CICS (for example, CSSL); in this case, no extra DCT entry is required.

- An extra partition destination as a synonym for an existing CICS message destination:

      DEFINE TDQUEUE(message-destination) GROUP(natgroup) TYPE(INDIRECT)     *
               INDIRECTNAME(name)

  where:

  `message-destination` is the name of the Natural CICS Interface error message destination as defined with the `MSGDEST` parameter in the `NTCICSP` macro described in the Parameter Reference documentation. The default name is `NERR`.

  `name` is the name of the corresponding indirect destination.

- An extra file:

      DEFINE TDQUEUE(message-destination) GROUP(natgroup) TYPE(EXTRA)            *
               DDNAME(NATMSG) OPEN(INITIAL) TYPEFILE(OUTPUT)                     *
               RECORDFORMAT(VARIABLE) BLOCKFORMAT(UNBLOCKED)                     *
               RECORDSIZE(nnn)

  where `message-destination` is the name of the Natural CICS Interface error message destination as defined with the `MSGDEST` parameter in the `NTCICSP` macro described in the Parameter Reference documentation. The default name is `NERR`.

  You can, for example, change the `BLOCKFORMAT` format from `UNBLOCKED` to `BLOCKED`. Natural and the Natural CICS Interface messages have a length of up to 120 bytes. Therefore, the record size (`RECORDSIZE (nnn)`) should be at least 124 bytes for variable record format or 120 bytes for fixed record format.

  #### When using a disk file:

  Sufficient disk space must be reserved for this data set; a DD statement must be added to the CICS startup JCL.

#### Natural NATRJE Utility

- Add one entry in the DCT for the Natural NATRJE utility (described in the Utilities documentation). When submitting a job to JES with the following entry, the internal reader is started on `CLOSE` of the destination:

      DEFINE TDQUEUE(submit-destination) GROUP(natgroup) TYPE(EXTRA)         *
               DDNAME(NATRJE) OPEN(DEFERRED) TYPEFILE(OUTPUT)                *
               RECORDFORMAT(FIXED) BLOCKFORMAT(UNBLOCKED) RECORDSIZE(80)

  where:

  `submit-destination` is the name of the Natural CICS Interface submit destination as defined with the `RJEDEST` parameter in the `NTCICSP` macro described in the Parameter Reference documentation. The default name is `NRJE`.

  Additionally, add the following DD statement to the CICS startup JCL:

      //NATRJE DD SYSOUT=(*,INTRDR)

  When submitting a job to JES with the following two entries, the Natural CICS Interface deals with an indirect destination that will not be closed:

      DEFINE TDQUEUE (submit-destination) GROUP(natgroup) TYPE(INDIRECT)     *
               INDIRECTNAME(name)

      DEFINE TDQUEUE(name) GROUP(natgroup) TYPE(EXTRA)                       *
               DDNAME(NATRJE) OPEN(DEFERRED) TYPEFILE(OUTPUT)                *
               RECORDFORMAT(FIXED) BLOCKFORMAT(UNBLOCKED) RECORDSIZE(80)

  where:

  `submit-destination` is the name of the Natural CICS Interface submit destination as defined with the `RJEDEST` parameter in the `NTCICSP` macro described in the Parameter Reference documentation. The default name is `NRJE`.

  `name` is the name of the corresponding indirect destination.

  You can use either a `/*EOF` card as the very last card in the job stream or the corresponding `NATRJE` exit. When detecting the `/*EOF` card, JES submits the previous job stream.

#### Natural CICS Interface Session Statistics

This definition is optional.

- Add one entry in the DCT for the Natural CICS Interface session statistics:

      DEFINE TDQUEUE(log-destination) GROUP(natgroup) TYPE(EXTRA)            *
               DDNAME(NATLOG) OPEN(INITIAL) TYPEFILE(OUTPUT)                 *
               RECORDFORMAT(VARIABLE) BLOCKFORMAT(BLOCKED)                   *
               RECORDSIZE(4624) BLOCKSIZE(4628)

  where `log-destination` is the name of the Natural CICS Interface logging destination as defined with the parameter `LOGDEST` described in the Parameter Reference documentation. The default name is `NLOG`.

  Sufficient disk space must be reserved for this data set; a DD statement must be added to the CICS startup JCL.

#### Natural CICS Interface Profile Parameter File

This definition is optional.

- Add one entry in the DCT for the Natural CICS Interface profile parameter file:

      DEFINE TDQUEUE(parameter-destination) GROUP(natgroup) TYPE(EXTRA)      *
               DDNAME(CMPRMIN) OPEN(DEFERRED) TYPEFILE(INPUT)                *
               RECORDFORMAT(FIXED) BLOCKFORMAT(BLOCKED)                      *
               RECORDSIZE(80) BLOCKSIZE(nnn)

  where:

  `parameter-destination` is the name of the Natural CICS Interface profile parameter input destination as defined with the `PRMDEST` parameter in the `NTCICSP` macro described in the Parameter Reference documentation. The default name is `NPRM`.

  `nnn` is a multiple of 80.

  A DD statement must be added to the CICS startup JCL.

### Temporary Storage Queues

Using the prefix determined by the value of the parameter PREFIX in the NTCICSP macro of the Natural parameter module, the Natural CICS Interface creates temporary storage queues to store control records.

To exempt these temporary storage control records from automatic deletion, do not specify an expiry interval in the respective TSMODEL resource definition.

### Other Definitions

- Add the following system abend codes to a CICS System Recovery Table (SRT):

  `0D6` | Protects CICS against failing Natural Roll Server and Natural Authorized Services Manager requests (using PC instructions) by Natural.
  `01D` | Protects CICS against failing data space cache requests by Natural.
  `DC2` | Protects CICS against failing memory object cache requests by Natural.

## Installation Verification

You can verify the successful installation of the Natural CICS Interface by performing the following steps:

1. From a CICS session, type in the Natural transaction ID to start a Natural session.

2. Proceed with the steps described in the section Test Online Natural.

### On this page

- Prerequisites
- Installation Medium
- Prefix Used for Natural CICS Interface Components
- Installation Procedure
- CICS Startup Parameters
- CICS Resource Definitions
- Installation Verification