Installing Natural CICS Interface on z/VSE

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

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:

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:

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

Installation Medium

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

Data Set Name Contents
NCIvrs.LIBR Source modules, macros, phases and object modules

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

Sample Jobs

Sample installation jobs are contained in the NATvrs.LIBJ 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 4 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:

The installation procedure comprises the following:

Step 1: Customize CICS

(Job I005, Steps 2211, 2212, 2230)

  1. Steps 2211 and 2212:

    Create the CICS tables and RDO entries as described in CICS Resource Definitions.

  2. Step 2230 (optional):

    This step is 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: 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 3: Build the Roll-File Initialization Module

(Job I070, Step 2205)

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

Step 4: Build the Natural CICS Interface Parameter Module

(Job I070, Steps 2220, 2225)

  • Edit, assemble and catalog the Natural CICS Interface parameter module NCIPARM.

    The Natural CICS Interface parameter module NCIPARM contains a macro named NCMPRM which contains parameters specific to the Natural CICS Interface.

    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 CICS Interface parameter module installation process, the source module NCIPARM contains the NCMPRM macro request with parameter PREFIX=&SYSPARM. Thus, when generating a Natural CICS Interface parameter module, assemble the NCIPARM source module with assembler option SYSPARM=prefix rather than editing the source module.

    The individual parameters are described in the section NCMPRM Macro Parameters in the TP Monitor Interfaces documentation.

Step 5: Build the Natural CICS Interface Starter Module NCISTART

(Job I070, Step 2230)

  • Make sure that the IBM Language Environment macro library is available in the SYSLIB chain in the assembler step.

  • Translate, assemble and catalog the Natural CICS Interface starter module NCISTART. Repeat these steps after you have installed a new CICS version.

    If you are not using the most recent CICS version, the translate step may result in a non-zero return code (4 - 16, depending on your CICS version) because of CICS commands being used that are unknown to your CICS translator. This return code can be ignored as long as the subsequent assembly step will end with a return code of 0 by using conditional assemblies to bypass potential CICS translator messages.

Step 6: Build the Natural CICS Interface Root Module NCIROOT

(Job I070, Step 2235)

  • Translate, assemble and catalog the Natural CICS Interface module NCIROOT. Repeat these steps after you have installed a new CICS version.

    If you are not using the most recent CICS version, the translate step may result in a non-zero return code (4 - 16, depending on your CICS version) because of CICS commands being used that are unknown to your CICS translator. This return code can be ignored as long as the subsequent assembly step will end with a return code of 0 by using conditional assemblies to bypass potential CICS translator messages.

Step 7: Build the Natural CICS Interface System Directory Module

(Job I070, Steps 2245, 2250)

  • Edit, assemble and catalog the NCISCPCB module.

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

    A sample job is provided with the NCII070(J) member in the NATvrs.LIBJ library.

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

Step 8: Build the Natural CICS Interface External CALLNAT Interface Module

(Job I070, Step 2270)

This step must be performed only if you want to use the external CALLNAT interface module of the Natural CICS Interface. See also Environment Dependencies in Natural 3GL CALLNAT Interface - Purpose, Prerequisites, Restrictions in the Operations documentation.

  • Translate, assemble and catalog the external CALLNAT interface module NCIXCALL. See also NCIXCALL as described for the CALLNAT in Environment Dependencies in the Operations documentation.

    Repeat these steps after you have installed a new CICS version.

    If you have an NCIXCALL module from a previous Natural version, specify a new name for this module (for example, NCIXCIOV) by using the SYSPARM parameter contained in NCIXCALL. The NCIXCALL module from the previous Natural version must be linked (see Step 16: Link the Natural CICS Interface External CALLNAT Interface Module) to assign it the new name.

    If you are not using the most recent CICS version, the translate step may result in a non-zero return code (4 - 16, depending on your CICS version) because of CICS commands being used that are unknown to your CICS translator. This return code can be ignored as long as the subsequent assembly step will end with a return code of 0 by using conditional assemblies to bypass potential CICS translator messages.

Step 9: Build the Natural CICS Interface Node Error Program

(Job I070, Step 2275)

This step must be performed only if you want to use the node error program (NEP) of the Natural CICS Interface.

  • Translate, assemble and catalog the Natural CICS Interface module NCIZNEP. Repeat these steps after you have installed a new CICS version.

    For information on NCIZNEP, see NCIZNEP Functionality in the TP Monitor Interfaces documentation.

    If you are not using the most recent CICS version, the translate step may result in a non-zero return code (4 - 16, depending on your CICS version) because of CICS commands being used that are unknown to your CICS translator. This return code can be ignored as long as the subsequent assembly step will end with a return code of 0 by using conditional assemblies to bypass potential CICS translator messages.

Step 10: Build the Natural CICS Interface XFAINTU Exit

(Job I070, Step 2280)

This step must be performed only if you want to use Natural via the CICS 3270 Bridge.

  • Translate, assemble and catalog the Natural CICS Interface module NCIXFATU. Repeat these steps after you have installed a new CICS version.

    If you are not using the most recent CICS version, the translate step may result in a non-zero return code (4 - 16, depending on your CICS version) because of CICS commands being used that are unknown to your CICS translator. This return code can be ignored as long as the subsequent assembly step will end with a return code of 0 by using conditional assemblies to bypass potential CICS translator messages.

Step 11: Build the Natural CICS Interface Front-End Driver NCISFED

(Job I070, Step 2290)

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

A sample job is provided with the NCII070R member in the NATvrs.LIBJ library.

  • Make sure that the IBM Language Environment (LE) macro library is available in the SYSLIB chain in the assembler step.

  • Translate, assemble and catalog the Natural CICS Interface front-end driver NCISFED. Repeat these steps after you have installed a new CICS version.

    If you are not using the most recent CICS version, the translate step may result in a non-zero return code (4 - 16, depending on your CICS version) because of CICS commands being used that are unknown to your CICS translator. This return code can be ignored as long as the subsequent assembly step will end with a return code of 0 by using conditional assemblies to bypass potential CICS translator messages.

Step 12: Build the Natural Parameter Module

(Job I080, Step 2220)

Build the Natural parameter module for the Natural CICS Interface:

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

  2. Assemble and catalog the Natural parameter module.

Step 13: Link the Environment-Dependent Nucleus

(Job I080, Step 2230)

  • Link the environment-dependent nucleus for the Natural CICS Interface with the following modules:

    NCIPARM built in Step 4,
    NCISTART built in Step 5,
    NCIROOT built in Step 6, and
    the Natural parameter module built in Step 12.

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

    All components of the environment-dependent nucleus are reentrant. Therefore, you can link it with the shared virtual area (SVA) option to take advantage of the CICS (E)RDSA storage area.

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

Step 14: 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 is not reentrant. Therefore, it cannot be linked with the shared virtual area (SVA) option.

Step 15: Link the VSAM Roll-File Initialization Module

(Job I080, Step 2265)

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

  • Link the VSAM roll-file initialization module NCISCPRI into your CICS user library.

Step 16: 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 and 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 partition 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.

    The external CALLNAT interface module of the Natural CICS Interface is reentrant. Therefore, you can link it with the shared virtual area (SVA) option to take advantage of the CICS (E)RDSA storage area.

Step 17: 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 by using the NCIZNEPV module.

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

    The node error program of the Natural CICS Interface is reentrant. Therefore, you can link it with the shared virtual area (SVA) option to take advantage of the CICS (E)RDSA storage area.

Step 18: 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.

Step 19: 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.

A sample job is provided with the NCII080R member in the NATvrs.LIBJ library.

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

    The Natural RPC server front-end under CICS is reentrant. Therefore, you can link it with the shared virtual area (SVA) option to take advantage of the CICS (E)RDSA storage area.

Step 20: 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 DLBL statement. No other parameter input is required for NCISCPRI; all data required for file initialization is obtained by SHOWCB VSAM macro calls.

    When running the Natural CICS Interface, supply an end-of-data (/*) statement in the JCL for compatibility reasons, although no parameter input is required for NCISCPRI.

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 Resource Definitions

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

Note:
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

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 Natural CICS Interface module built in Step 13: Link the Environment-Dependent Nucleus.

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

    DATALOCATION(ANY)

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 NCISTART program are inherited since standard linkage conventions (BALR 14,15) are used.

    To access the environment-independent nucleus in the SVA, specify USESVACOPY(YES) for this program definition and SVA=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)

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 16: Link the Natural CICS Interface External CALLNAT Interface Module.

    We recommend that you set the following parameter values in the CICS program definition under CICS TS:

    DATALOCATION(ANY)

Node Error Program

This definition is optional.

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 19: Link the Natural RPC Server Front-End.

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

    DATALOCATION(ANY)

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

  • 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 Natural CICS Interface module built in Step 13: Link the Environment-Dependent Nucleus.

    We recommend that you set the following parameter value in the CICS transaction definitions under CICS TS:

    TASKDATALOC(ANY)

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

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 13: Link the Environment-Dependent Nucleus.

    nmsg is the name of the Natural CICS Interface message switching transaction ID as defined with the MSGTRAN parameter described in Parameters in Macro NCMPRM in the TP Monitor Interfaces documentation. The default name is NMSG.

    We recommend that you set the following parameter value in the CICS transaction definitions under CICS TS:

    TASKDATALOC(ANY)

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

Node Error Program

This definition is optional and applies to CICS TS only.

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 19: 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:

    DFHFCT TYPE=FILE,                                                      *
           FILE=prefixRn,                                                  *
           ACCMETH=VSAM,                                                   *
           RECFORM=(FIXED,BLOCKED),                                        *
           SERVREQ=(UPDATE,DELETE,ADD),                                    *
           FILSTAT=(ENABLED,OPENED),                                       *
           BUFND=5,STRNO=3

    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

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:

    DFHDCT TYPE=INDIRECT,                                                  *
           DESTID=message-destination,                                     *
           INDDEST=name

    where:

    message-destination is the name of the Natural CICS Interface error message destination as defined with the MSGDEST parameter described in NCMPRM Macro Parameters in the TP Monitor Interfaces documentation. The default name is NERR.

    name is the name of the corresponding indirect destination.

  • An extra file:

    DFHDCT TYPE=SDSCI,                                                     *
           DSCNAME=NATMSG,                                                 *
           RECFORM=VARUNB,                                                 *
           RECSIZE=nnn,                                                    *
           TYPEFLE=OUTPUT
      
    DFHDCT TYPE=EXTRA,                                                     *
           DSCNAME=NATMSG,                                                 *
           DESTID=message-destination,                                     *
           OPEN=INITIAL

    where message-destination is the name of the Natural CICS Interface error message destination as defined with the MSGDEST parameter described in NCMPRM Macro Parameters in the TP Monitor Interfaces documentation. The default name is NERR.

    You can, for example, change the RECFORM format from VARUNB (variable unblocked) to VARBLK (variable blocked). Natural and the Natural CICS Interface messages have a length of up to 120 bytes. Therefore, the record size (RECSIZE=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 DLBL statement must be added to the CICS startup JCL.

Natural CICS Interface Session Statistics

This definition is optional.

  • Add two entries in the DCT for the Natural CICS Interface session statistics:

    DFHDCT TYPE=SDSCI,                                                     *
           DSCNAME=NATLOG,                                                 *
           RECFORM=VARBLK,                                                 *
           BLKSIZE=4628,                                                   *
           RECSIZE=4624,                                                   *
           DEVICE=DISK
      
    DFHDCT TYPE=EXTRA,                                                     *
           TYPEFLE=OUTPUT,                                                 *
           DSCNAME=NATLOG,                                                 *
           DESTID=log-destination,                                         *
           OPEN=INITIAL

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

Natural CICS Interface Profile Parameter File

This definition is optional.

  • Add two entries in the DCT for the Natural CICS Interface profile parameter file:

    DFHDCT TYPE=SDSCI,                                                     *
           RECSIZE=80,           card image                                *
           BLKSIZE=nnn,                                                    *
           BUFNO=1,                                                        *
           DSCNAME=cmprmin,                                                *
           RECFORM=FIXBLK,                                                 *
           TYPEFLE=INPUT
    
    DFHDCT TYPE=EXTRA,                                                     *
           DESTID=parameter-destination,                                   *
           DSCNAME=cmprmin,                                                *
           OPEN=DEFERRED

    where:

    parameter-destination is the name of the Natural CICS Interface profile parameter input destination as defined with the PRMDEST parameter described in NCMPRM Macro Parameters in the TP Monitor Interfaces documentation. The default name is NPRM.

    nnn is a multiple of 80.

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

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.