Version 4.2.6 for Mainframes
 —  Database Management System Interfaces  —

Installing Natural SQL Gateway

This section describes how to install the Natural SQL Gateway (in the remainder of this section also referred to as NSB) in the various environments supported.

The installation procedures contain a number of options that depend on the TP monitor being used as well as on other site requirements.

This section covers the following topics:


Installing Natural SQL Gateway - General Information

This section covers the following topics:

Installation Jobs

The installation of Software AG products is performed by installation jobs. These jobs are either created manually or generated by System Maintenance Aid (SMA).

For each step of the installation procedure described later in the section Installing Natural SQL Gateway , the job number of a job performing the respective task is indicated. This job number refers to an installation job generated by SMA. If you are not using SMA, an example job of the same number is provided in the job library on the NSB installation tape; you must adapt this example job to your requirements. Note that the job numbers on the tape are preceded by a product code (for example, NSBI070).

Using System Maintenance Aid

For information on the use of Software AG's System Maintenance Aid for the installation process, refer to the System Maintenance Aid documentation.

Prerequisites

Special considerations for DB2 Systems

Top of page

Installation Tape

The installation tape contains the datasets listed in the table below. The sequence of the datasets is shown in the Report of Tape Creation which accompanies the installation tape.

Dataset Name Contents
NSBvrs.LOAD Load modules
NSBvrs.JOBS Example installation jobs
NSBvrs.OBJS Contains the object modules of the server. See Installing the Natural SQL Gateway Server under z/OS.

The installation tape for NSB also contains the following NDB datasets:

Dataset Name Contents
NDBvrs.SRCE Source modules
NDBvrs.LOAD Load modules
NDBvrs.INPL Utility programs in INPL format
NDBvrs.ERRN Error messages

The notation vrs in dataset names represents the version number of the product.

Important Note for Installations with NDB License

If you have already installed the latest NDB version, you must not copy the NDB datasets from the tape again.

Copying the Tape Contents to a z/OS Disk

If you are using SMA, refer to the System Maintenance Aid documentation (included in the current edition of the Natural documentation CD).

If you are not using SMA, follow the instructions below.

This section explains how to:

The JCL in this dataset is then used to copy all datasets from tape to disk.

If the datasets for more than one product are delivered on the tape, the dataset COPY.JOB contains the JCL to unload the datasets for all delivered products from the tape to your disk.

After that, you will have to perform the individual install procedure for each component.

Step 1 - Copy Dataset COPY.JOB from Tape to Disk

The dataset COPY.JOB (Label 2) contains the JCL to unload all other existing datasets from tape to disk. To unload COPY.JOB, use the following sample JCL:

//SAGTAPE JOB SAG,CLASS=1,MSGCLASS=X
//* ---------------------------------
//COPY EXEC PGM=IEBGENER
//SYSUT1 DD DSN=COPY.JOB,
// DISP=(OLD,PASS),
// UNIT=(CASS,,DEFER),
// VOL=(,RETAIN,SER=tape-volume),
// LABEL=(2,SL)
//SYSUT2 DD DSN=hilev.COPY.JOB,
// DISP=(NEW,CATLG,DELETE),
// UNIT=3390,VOL=SER=volume,
// SPACE=(TRK,(1,1),RLSE),
// DCB=*.SYSUT1
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
// 

where:

hilev is a valid high level qualifier
tape-volume is the tape volume name, for example: T12345
volume is the disk volume name

Step 2 - Modify COPY.JOB on Your Disk

Modify the COPY.JOB on your disk to conform to your local naming conventions and set the disk space parameters before submitting this job:

Step 3 - Submit COPY.JOB

Submit COPY.JOB to unload all other datasets from the tape to your disk.

Top of page

Natural SQL Gateway Installation Procedure

This section describes how to install Natural SQL Gateway in various environments and covers the the following topics:

NSB Common Installation Steps

The following steps describe the procedure for installing the components of Natural SQL Gateway that are common to all environments:

Step 1: Modify, Assemble and Link NSB Parameter Module NDBPARM

Job I055, Steps 1640 or 1660 or 1675

Step 2: Link-Edit NATGWDB2

Job I055, Step 1680

Link-edit the environment-independent NSB nucleus NATGWDB2. Verify that the INCLUDE cards refer to the corresponding DD names for the load libraries.

Step 3: Create Natural Parameter Module

Job I060, Steps 0010, 0015

Assemble and link the Natural parameter module for batch mode.

Adapt your Natural parameter module NATPARM by adding parameters specific to Natural for SQL Gateway (see Natural Parameter Modification for Natural SQL Gateway) and reassemble NATPARM.

Step 4: Link Natural Nucleus

Job I060, Step 0020

Link the nucleus (Step 0020) for batch Natural.

Modify the JCL used to link your Natural environment-dependent nucleus by adding the following INCLUDE cards and the corresponding DD statements:

INCLUDE SMALIB(NDBPARM) NDB parameter module created in Step 1
INCLUDE SMALIB(NSBCNXTB) ConnecX SQL Engine (CXX) interface entry point table
INCLUDE RCIOBJ(xxxxxxx) Environment-dependent interface (see below)
INCLUDE NATLIB(NAT2LE) Interface module required to call C runtime functions in a CICS or Com-plete environment
INCLUDE NCIOLIB(NCI2TCP) Natural TCP/IP interface required in a CICS environment

Natural SQL Gateway basically consists of:

Job I060, Step 0105

Modify the JCL used to link your Natural shared nucleus by adding the following INCLUDE card:

INCLUDE SMALIB(NATGWDB2) Environment-independent NSB nucleus from Step 2

Notes for CICS Environments:

RCIOBJ denotes the RCI.OBJ library from the installation of ConnecX SQL Engine.

Interface Library Description Environment
API3GL RCIOBJ ConnecX Client TSO and batch
CXXCLNT RCIOBJ Natural SQL Gateway Client CICS and Com-plete.

If you want to use the Natural File Server, include SMALIB(NDBPARMF) or SMALIB(NDBPARME) instead of SMALIB(NDBPARM); see also Step 1 above.

Note:
If you want to use NSB in various environments (that is, with different TP monitors), you must repeat this step for each of these environments.

Instead of link-editing your Natural nucleus in the way described above, you have the following alternatives:

  1. If you do not use a Natural shared nucleus, all modules must be included in the link-edit of the Natural nucleus.

  2. Remove NATGWDB2 from the link-edit of the Natural shared nucleus and run it as a separate module with the mandatory entry name NATGWDB2. You can modify the name of the module created in Step 2. However, if you use a name different from NATGWDB2, this name must be specified as an alias name in an NTALIAS macro entry of the Natural parameter module. This way of link-editing only applies if the Natural Resolve CSTATIC Addresses feature (RCA) is used.

  3. Include all modules in the link-edit job of a separate Natural parameter module with the mandatory entry name CMPRMTB. The name of the resulting module is arbitrary. This way of link-editing only applies if an alternative parameter module (profile parameter PARM) is used. If link-editing is done in this way, you can install NSB without having to modify your Natural nucleus or driver.

Step 5: Load Natural SQL Gateway Objects into System File

Job I061, Step 1610

Before executing this step, change the CMWKF01 DD statement to point to the NDBvrs.INPL dataset.

In this step, the Natural SQL Gateway system programs, maps and DDMs are loaded into the Natural system file. The INPL job loads objects into the Natural system libraries SYSDDM, SYSTEM and SYSDB2 in the FNAT system file.

Step 6: Load Natural SQL Gateway Error Messages into System File

Job I061, Step 1620

Before executing this step, change the CMWKF02 DD statement to point to the NDBvrs.ERRN dataset.

This step executes a batch Natural job that runs an error load program by using the NDBvrs.ERRN dataset as input. The ERRLODUS job loads error messages into the library SYSERR in the FNAT system file.

Step7: Create Natural Parameter Module and Link the Nucleus

Job I080, Steps 2210, 2220, 2230 (CICS), Steps 2300, 2310, 2320 (Com-plete), Steps 0010, 0015, 0020 (TSO)

Assemble and link the Natural parameter module and link the nucleus.

Top of page

Natural SQL Gateway Installation Steps Specific to CICS

This section describes how to install Natural SQL Gateway in a CICS environment:

Using the File Server with VSAM

Step 1: Define VSAM Dataset for File Server

Job I008, Step 1610

Specify the size and the name of the VSAM RRDS that is to be used as the file server (see also Installing the File Server in Natural File Server for DB2).

Step 2: Format File Server Dataset

Job I075, Step 1610

Specify the five input parameters required to format the file server dataset (see also Natural File Server for DB2).

Step 3: Modify, Assemble and Link CICS Tables

Shown below are sample additional CICS table entries needed for the file server and for the DB2 components of Natural:

FCT entry:

  CMFSERV DFHFCT TYPE=DATASET,                         X
                 ACCMETH=VSAM ,                        X
                 BUFND=5,                              X
                 BUFNI=4,                              X
                 DATASET=CMFSERV,                      X
                 DISP=SHR,                             X
                 DSNAME=SAGLIB.NCIDB2.SERVER,          X
                 FILSTAT=(ENABLED,CLOSED),             X
                 JID=NO,                               X
                 LOG=NO,                               X
                 LSRPOOL=NONE,  1-8 ONLY FOR XA; NONE  X
                 RECFORM=(FIXED,BLOCKED),              X
                 RSL=PUBLIC,                           X
                 SERVREQ=(ADD,UPDATE,DELETE,BROWSE),   X
                 STRNO=4

Step 4: Restart CICS

Restarting CICS is required, because of the additional FCT entry above.

Specify the five input parameters required to format the file server dataset (see also Installing the File Server in Natural File Server for DB2).

Specifcation of Natural SQL Server TCP/IP Address and Port Number

Modify the NDBPARM module by specification of the NSBAHOST parameter to denote the TCP/IP address and the NSBAPORT parmeter to denote the port number of the Natural SQL Gateway server.

Connect to the Desired JDBC Server

Invoke Natural with the appropriate DB2SIZE.

Ensure that SQL tables can be accessed. Before the first SQL call you must connect to the ConnecX SQL Engine JDBC server. For this, use a PROCESS SQL statement to specify the desired hostname, port number and CDD file, plus user ID and password.

Top of page

Natural SQL Gateway Installation Steps Specific to Com-plete

This section describes how to install Natural SQL Gateway in a Com-plete environment:

Specification of Natural SQL Server TCP/IP Address and Port Number

Modify the NDBPARM module by specification of the NSBAHOST parameter to denote the TCP/IP address and the NSBAPORT parmeter to denote the port number of the Natural SQL Gateway server.

Connect to the Desired JDBC Server

Invoke Natural with the appropriate DB2SIZE.

Ensure that SQL tables can be accessed. Before the first SQL call you must connect to the ConnecX SQL Engine JDBC server. For this, use a PROCESS SQL statement to specify the desired hostname, port number and CDD file, plus user ID and password.

Top of page

Natural SQL Gateway Installation Steps Specific to TSO

This section describes how to install Natural SQL Gateway in a TSO environment:

Using the File Server with VSAM

If you want to use the Natural file server (VSAM), perform the following steps:

Step 1: Modify NDBFSRV in NATTSO

Set the NDBFSRV parameter in the NATTSO macro to YES and reassemble and relink your Natural TSO interface NATTSO.

Step 2: Define VSAM Dataset for File Server

Job I008, Step 1620

Specify the size and the name of the VSAM RRDS that is to be used as the file server (see also Installing the File Server in Natural File Server).

Step 3: Format File Server Dataset

Job I075, Step 1620

Specify the five input parameters required to format the file server dataset (see also Installing the File Server in Natural File Server).

Sample JCL for Starting and Using Natural SQL Gateway

To test the TSO installation of Natural SQL Gateway, perform the following steps:

Step 1: Adapt TSO CLIST

Job I070, Step 2400

Change the library and program names in the TSO CLIST to meet site requirements. If you do not use the file server, remove the ALLOC and FREE statements for CMFSERV.

Step 2: Invoke Natural

Invoke Natural by executing the CLIST created in the previous step. Ensure that SQL tables can be accessed. Before the first SQL call you must connect to the ConnecX SQL Engine JDBC server. For this, use a PROCESS SQL statement to specify the desired hostname, port number and CDD file, plus user ID and password.

Top of page

Natural SQL Gateway Installation Verification

This section provides example batch jobs and online methods for verifying the installation of Natural SQL Gateway:

This section covers the following topics:

Test Natural SQL Gateway in Batch Mode - Job NSBBATCA

NSBBATCA contains sample JCL to test Natural SQL Gateway in batch mode. Modify the sample JCL to meet site requirements.

Before the first SQL call you must call NSBDCON to explicitly connect to the ConnecX SQL Engine JDBC server. NSBDCON can be edited to specify the appropriate host name, port number and CDD registry name.

Online Verification Methods

The online verification can only be done in a TSO, Com-plete or CICS environment.

Natural SQL Gateway Sample Programs

The following table contains all Natural SQL Gateway (NSB) sample programs. They are all provided during the Natural SQL Gateway installation.

Program Name Purpose
NSBDCON Connect to ConnecX SQL Engine JDBC server.
NSBDCREA Create table NSB.DEMO.
NSBDISC Disconnect from ConnecX SQL Engine JDBC server.
NSBDROP Drop table NSB.DEMO.
NSBDFIND Read NSB.DEMO by FIND statement.
NSBDINS Load NSB.DEMO by INSERT statement.
NSBDPDEL Delete from NSB.DEMO by positioned DELETE.
NSBDPUPD Update NSB.DEMO by positioned UPDATE.
NSBDSDEL Delete from NSB.DEMO by searched UPDATE.
NSBDSEL Read NSB.DEMO by SELECT statement.
NSBDSET Show SET SCHEMA and SET CATALOG statements.
NSBDSTOR Load NSB.DEMO by STORE statement.
NSBDSUPD Update NSB.DEMO by searched UPDATE.

All programs use DDM NSB-DEMO, which uses the LFILE 102. Therefore the NATPARM has to map the LFILE 102 to a DBID which is mapped to the database type CNX by a NDBID definition in the NDBPARM module.

Before the demo programs can be executed the user has to connect to a ConnecX SQL Engine JDBC server. This could be done by a modified copy of the NSBDCON program.

The results of demo programs differ depending on the sequence of their execution.

If you receive the message NAT3700, enter the Natural system command SQLERR (described in SQLERR Command) to display the corresponding SQL return code.

Top of page

Natural Parameter Modification for Natural SQL Gateway

This section covers the following topics:

Natural Profile Parameter Settings

To set the Natural profile parameters

  1. Add the following Natural profile parameter to your NATPARM module:

    DB2SIZE=nn

    The DB2SIZE parameter can also be specified dynamically. It indicates the size of the DB2 buffer area, which must be set to at least 6 KB.

    The setting of DB2SIZE also depends on whether you use the file server or not. If the file server is not used, the setting can be calculated according to the following formula:

    ((1064 + n1 * 40 + n2 * 120) + 1023) / 1024 KB 

    If the file server is used, the setting can be calculated according to the following formula:

    ((1060 + n1 * 40 + n2 * 160 + n3 * 8) 1023) / 1024 KB

    The variables n1, n2 and n3 correspond to:

    n1 the number of statements for dynamic access as specified as the second parameter in Job I055, Step 1600;
    n2 the maximum number of nested database loops as specified with the MAXLOOP parameter in NDBPARM;
    n3 the maximum number of file server blocks to be allocated per user specified as the fifth parameter in Job I075, Step 1620 or the EBPMAX parameter of NDBPARM, if you decided to use the Software AG Editor buffer pool as file server.

    Important:
    Ensure that you have also added the Natural parameters required for the Software AG Editor; see the relevant installation description in the section Installing the Software AG Editor, in the Natural Installation documentation.

    As DB2SIZE applies to Natural for DB2 and Natural SQL Gateway, it must be set to the maximum value if you run more than one of these environments.

    Add an NTDB entry with database-type SQL specifying the list of logical database numbers that relate to SQL tables. All Natural DDMs that refer to an SQL table must be cataloged with a DBID from this list. DBIDs can be any number from 1 to 254; a maximum of 254 entries can be specified. For most user environments, one entry is sufficient.

    Important:
    Ensure that all SQL DDMs used when cataloging a given program have a valid SQL DBID. Also ensure that the DBIDs selected in the NTDB macro for SQL do not conflict with DBIDs selected for other database systems

    At execution time of a program catalogued with a DBID of database-type SQL, the SQL database-type specified for that DBID in the NDB parameter module via NDBID macro determines which kind of database interface is used to access the SQL database. If the associated type is CNX, the Natural SQL Gateway will be used.

    NTDB SQL,(200,249) 
  2. Add an LFILE entry for LFILE 102 specifying a logical database number (DBID), that relates to database type CNX. This is necessary for usage of ISQL or calls to NDBISQL using Natural SQL Gateway.

    NTLFILE 102,249,1 SQL system file for CNX

Performance Considerations for the DB2SIZE Parameter

During execution of an SQL statement, storage is allocated dynamically to build the SQLDA for passing the host variables to the CXX interface stub.

For performance reasons, it is first attempted to meet the storage requirements by free space in the Natural for DB2 buffer (DB2SIZE). If there is not enough space available in this buffer, the TP monitor or operating system is invoked.

To take advantage of this performance enhancement, you must specify your DB2SIZE larger than calculated according to the formula; see Natural Profile Parameter Settings.

Depending on the SQL execution mode and on the usage of the Natural file server, the additional storage requirements (in bytes) can be calculated as follows:

Dynamic Mode

With sending fields:

80 + n * 56

With sending fields including LOB columns:

80 + 2 * n * 56

where n is the number of sending fields in an SQL statement. The storage is freed immediately after the execution of the SQL statement.

With receiving fields (that is, with variables of the INTO list of a SELECT statement):

80 + n * 56 + 24 + n * 2

With receiving fields including LOB columns:

80 + 2 * n * 56 + 24 + n * 2

where n is the number of receiving fields in an SQL statement.

The storage remains allocated until the loop is terminated.

Storage Requirements for the Natural File Server

When using the file server, additional storage is required for each database loop that contains positioned UPDATE and/or DELETE statements.

For each of such loops, a buffer is allocated to save the contents of all receiving fields contained in the INTO list. Therefore, the size of this buffer corresponds to the total length of all receiving fields:

 20 + 4 + sum (length (vl), ..., length (vn))

where v1 ... vn refers to the variables contained in the INTO list.
The buffer remains allocated until the loop is terminated.

Sample Calculation for Dynamic Mode without Using the Natural File Server

If you use the default value 10 for both variables (n1 and n2), the calculated DB2SIZE will be 2208 bytes. However, if you specify a DB2SIZE of 20 KB instead, the available space for dynamically allocated storage will be 18272 bytes, which means enough space for up to either 325 sending fields or 313 receiving fields.

Since space for receiving fields remains allocated until a database loop is terminated, the number of fields that can be used inside such a loop is reduced accordingly: for example, if you retrieve 200 fields, you can update about 110 fields inside the loop.

Considerations for VARCHAR Fields

When using VARCHAR fields (that is, fields with either an accompanying L@ field in the Natural view or an explicit LINDICATOR clause), additional storage is allocated dynamically if the L@ or LINDICATOR field is not specified directly in front of the corresponding base field. Therefore, always specify these fields in front of their base fields.

Top of page

Parameter Module NDBPARM

The source module NDBPARM is used in several Natural add-on products. It contains parameter macros specific to an SQL environment:

These macros are described below.

Parameter Macro NDBPRM

The default values of the parameters contained in this macro can be modified to meet site-specific requirements (see the corresponding step of the Installation Procedure). The values of the parameters cannot be dynamically overwritten.

Complete List of Parameters Contained in NDBPRM

Below is a description of all parameters contained in the NDBPRM macro:

BTIGN | CONVERS | CONVRS2 | DDFSERV | DELIMID | EBPFSRV | EBPPRAL | EBPSEC | EBPMAX | ETIGN | FSERV | MAXLOOP | NNPSF | NSBAHOST | NSBAPORT | PSCIGN | REFRESH | RETRYPO | RWRDONL | STATDYN

List of Parameters Applicable to Natural SQL Gateway

The following parameters in the NDBPRM parameter macro are relevant to Natural SQL Gateway. All other parameters contained in the module are ignored.

DDFSERV | DELIMID | EBPFSRV | EBPPRAL | EBPSEC | EBPMAX | FSERV | MAXLOOP | NNPSF | NSBAHOST | NSBAPORT | PSCIGN | RWRDONL

BTIGN - Ignore BACKOUT TRANSACTION Error

Note:
This parameter does not apply to Natural SQL Gateway and is ignored.

This parameter is relevant in CICS and IMS TM environments only.

BTIGN ignores the error which results from a BACKOUT TRANSACTION statement that was issued too late for backing out the current transaction, because an implicit Syncpoint has previously been issued by the TP monitor.

Possible Values:

Value Explanation
ON The error after a late BACKOUT TRANSACTION is ignored. This is the default value.
OFF The error after a late BACKOUT TRANSACTION is not ignored.

CONVERS - Conversational Mode under CICS

This parameter is used to allow conversational mode in CICS environments where no Natural file server is used.

Possible Values:

Value Explanation
ON Conversational mode is allowed. This is the default value.
OFF Conversational mode is not allowed.

If this parameter is set to OFF and no Natural file server is used, you cannot continue database loops across terminal I/Os; if so, the DB2 SQL codes -501, 504, 507, 514, or 518 may occur.

CONVRS2 - Allow Conversational Mode 2 under CICS

This parameter is used to allow conversational mode 2 in CICS environments.

Possible Values:

Value Explanation
ON Conversational mode 2 is allowed.
OFF Conversational mode 2 is not allowed. This is the default value.

This parameter is used to control conversational mode 2 in CICS environments. Conversational mode 2 means that update transactions are spawned across terminal I/Os until either an explicit COMMIT or explicit ROLLBACK has been issued (Caution: DB2 and CICS resources are kept across terminal I/Os!). This means CONVRS2=ON has the same effect as the Natural parameter PSEUDO=OFF, except that the conversational mode is entered after an DB2 update statement (UPDATE, DELETE, INSERT) and left again after a COMMIT or ROLLBACK, while PSEUDO=OFF causes conversational mode for the total Natural session.

See also CALLNAT subprogram NDBCONV, which allows setting or resetting conversational mode 2 dynamically.

DDFSERV - Alternate DD Name for Natural File Server

This parameter specifies a DD name for the Natural file server module other than CMFSERV.

Possible Values:

Value Explanation
DD-name Any valid DD name. There is no default value.

DELIMID - Escape Character for Delimited Identifiers

This parameter determines the escape character to be used for generating delimited SQL identifiers for the column names and table names in SQL statements. A delimited identifier is a sequence of one or more characters enclosed in escape characters. You must specify a delimited identifier if you use SQL-reserved words for column names and table names, as demonstrated in the Example of DELIMID below.

Possible Values:

Value Explanation
" Double quotation mark
' Single quotation mark
None No value: Delimited identifiers are not enabled. This is the default value.

To enable generation of delimited identifiers, DELIMID must be set to double quotation mark (") or single quotation mark (').

The escape character specified for DELIMID and the SQL STRING DELIMITER are mutually exclusive. This implies that the mark (double or single quotation) used to enclose alphanumeric strings in SQL statements must be different from the value specified for DELIMID. If you enable delimited identifiers, ensure that the value specified for DELIMID also complies with the SQL STRING DELIMITER value of your DB2 installation.

See also the RWRDONL parameter to determine which delimited identifiers are generated in the SQL string.

Note:
For Natural SQL Gateway users:

If generation of delimited identifiers is enabled, switch on the ConnecX CDD option Use Quoted Delimiter.

Example of DELIMID:

In the following example, a double quotation mark (") has been specified as the escape character for the delimited identifier:

Natural statement:

SELECT FUNCTION INTO #FUNCTION FROM XYZ-T1000

Generated SQL string:

SELECT "FUNCTION" FROM XYZ.T1000

EBPFSRV - Editor Buffer Pool for Natural File Server

This parameter is used to determine whether the Natural file server uses the Software AG Editor buffer pool as the storage medium.

Possible Values:

Value Explanation
ON The Software AG buffer pool is to be used as the storage medium for the Natural file server.

ON must be set if the file server is to be used in a Parallel Sysplex environment. In this case, your Natural session must use the auxiliary editor buffer pool (see also Support of a z/OS Parallel Sysplex Environment in the Installation documentation).

OFF A VSAM file is to be used as the storage medium for the Natural file server. This is the default value.

EBPPRAL - Editor Buffer Pool Primary Allocation

This parameter specifies the number of blocks to be allocated primarily to each user of the Natural file server, if the Software AG Editor buffer pool is used as the storage medium.

Possible Values:

Value Explanation
0 - 32676 Number of blocks to be allocated primarily.
20 This is the default value.

If the EBPFSRV parameter is set to OFF, EBPPRAL is not used at runtime.

EBPSEC - Editor Buffer Pool Secondary Allocation

This parameter specifies the number of blocks to be allocated secondarily to each user of the Natural file server if the Software AG Editor buffer pool is used as the storage medium. The secondary allocation is used to allocate buffer pool blocks to the user if the primary allocation amount is already exhausted.

Possible Values:

Value Explanation
0 - 32676 Number of blocks to be allocated secondarily.
10 This is the default value.

If the EBPFSRV parameter is set to OFF, EBPSEC is not used at runtime.

EBPMAX - Editor Buffer Pool Maximum Allocation

This parameter specifies the maximum number of blocks to be allocated to each user of the Natural file server if the Software AG Editor buffer pool is used as the storage medium. This parameter serves as upper limit for the allocation of buffer pool blocks to a single user.

Possible Values:

Value Explanation
0 - 32676 Maximum number of blocks to be allocated.
100 This is the default value.

If the EBPFSRV parameter is set to OFF, EBPMAX is not used at runtime.

ETIGN - Ignore END TRANSACTION Error

Note:
This parameter does not apply to Natural SQL Gateway and is ignored.

This parameter is relevant in IMS TM MPP and message-oriented BMP environments only.

It is used to handle END TRANSACTION statements in a message-driven IMS region (MPP or message-oriented BMP).

In such a region, an END TRANSACTION cannot be executed by the Natural/IMS interface and is therefore ignored without any notification. In such situations, the ETIGN parameter can be used to issue an error message instead.

Possible Values:

Value Explanation
ON The END TRANSACTION error is ignored and processing is continued. This is the default value.
OFF The END TRANSACTION error is not ignored.

FSERV - Activate Natural File Server

This parameter determines whether the Natural file server is to be used and whether it can be disabled in the case of an initialization error.

Possible Values:

Value Explanation
ON Natural file server is to be used.
OFF Natural file server is not to be used. This is the default value.
DIS Natural file server is to be used but is to be disabled if it cannot be initialized.

If FSERV is set to ON and the file server is not operational, the initialization of the Natural SQL Gateway is terminated with a corresponding Natural error message. The Natural SQL Gatewayis disabled and any SQL call is rejected with a corresponding error message.

MAXLOOP - Maximum Number of Nested Program Loops

This parameter specifies the maximum possible number of nested database loops accessing SQL databases.

Possible Values:

Value Explanation
1 - 99 Maximum possible number of nested database loops.
10 This is the default value.

NNPSF - Set Natural Numerics' Positive Sign to F

This parameter changes the sign character of positive Natural variables which have format N, if they are filled from the SQL database system. Usually these variables have the C as positive sign character. If the parameter NNPSF is set to ON, F is used as positive sign character.

Possible Values:

Value Explanation
ON Positive numbers put into Natural numeric variables by the SQL database system get the sign F.
OFF Positive numbers put into Natural numeric variables by the SQL database system remain unchanged. This is the default value.

NSBAHOST - Set Natural SQL Gateway Server Hostname

This parameter specifies the Natural SQL Gateway server TCP/IP hostname used to communicate from TP-monitor environments like CICS hosting Natural to ConnecX JDBC server talking to SQL databases.

Possible Values:

Value Explanation
hostname This hostname designates the TCP/IP address of the Natural SQL Gateway server who communicates with the CXX JDBC server.
’’(Empty string) This is the default value, meaning no Natural SQL Gateway server hostname is specified.

Example:

NSBAHOST=IBM2.HQ.SAG

NSBAPORT – Set Natural SQL Gateway Server TCP/IP Port Number

This parameter specifies the TCP/IP port number the Natural SQL Gateway server is listening to.

Possible Values:

Value Explanation
integer Specifies the port number the Natural SQL Gateway server listens to.
0 This is the default value, meaning no Natural SQL Gateway server port number is specified.

Example:

NSBAPORT=4713

PSCIGN - Treat Positive Sqlcodes as Sqlcode 0

This parameter influences the treatment of positive sqlcodes returned from the SQL database system. If the parameter PSCIGN is set to OFF, a NAT3700 error message is issued. If the parameter PSCIGN is set to ON, positive sqlcodes are treated as if they were zero, that is, no NAT3700 error message is issued.

Possible Values:

Value Explanation
ON Positive sqlcodes are treated as zero.
OFF Positive sqlcodes cause a NAT3700 error message. This is the default value.

REFRESH - Refresh Setting of DB2 Server and Package Set

Note:
This parameter does not apply to Natural SQL Gateway and is ignored.

This parameter is used to automatically set the DB2 server and package set to the values that applied when the last transaction was executed. Server and package set are refreshed by using the CONNECT TO server-name and SET CURRENT PACKAGESET = 'package-name' SQL statements of DB2.

Possible Values:

Value Explanation
ON An automatic refresh is performed every time before a database transaction starts and if a server or package set has been specified.
OFF No automatic refresh is performed. This is the default value.

RETRYPO - Number of Positioning Retries

Note:
This parameter does not apply to Natural SQL Gateway and is ignored.

This parameter delimits the number of retries done by Natural for DB2 (NDB) in order to reposition a dynamic scrollable cursor in a pseudo-conversational environment (IMS MPP or CICS).

Possible Values:

Value Explanation
0 - 2147483648 Number of retries done by Natural for DB2.
10 This is the default value.

This parameter applies only for dynamic scrollable cursors.

In pseudo-conversational environments, cursors are closed at terminal I/O. For dynamic scrollable cursors the current absolute position number and the current key column values are saved. After terminal I/O the dynamic scrollable cursor is opened again and positioned absolutely to the position of the saved absolute position. The contents of the key columns are compared with the saved values. If they match, processing continues with the next requested database operation.

If the contents of the key columns do not match the saved values, the next rows are fetched and compared with the saved values until either the values match or no row is found or the RETRYPO count is exhausted. In the latter cases the cursor is repositioned to the saved position and the prior rows are fetched and compared until either the values match or no row is found or the RETRYPO count is exhausted. In the latter cases a NAT3703 error message is issued. If a row is fetched whose key columns matches the saved values, processing continues with the next database instruction.

RETRYPO delimits the retries in each direction (next or prior).

If RETRYPO is zero no repositioning takes place.

RWRDONL - Generate Delimited Identifiers for Reserved Words Only

This parameter determines which identifiers are generated as delimited identifier in an SQL string. RWRDONL only takes effect if the setting of the DELIMID parameter allows delimited identifiers.

Possible Values:

Value Explanation
ON Only identifiers that are reserved words are generated as delimited identifiers. The list of reserved words is contained in the NDBPARM macro. This list has been merged from the lists of reserved words for DB2 for z/OS, DB2 for VSE/VM, DB2 for LINUX, OS/2, Windows and UNIX, and ISO/ANSI SQL99.

This is the default value.

OFF All identifiers are generated as delimited identifiers.

STATDYN - Allow Static to Dynamic Switch

Note:
This parameter does not apply to Natural SQL Gateway and is ignored.

This parameter is used to allow dynamic execution of statically generated SQL statements if the static execution returns an error.

Possible Values:

Value Explanation
NEVER Dynamic execution is never allowed. This is the default value.
ALWAYS Dynamic execution is always allowed after an error.
SPECIAL Dynamic execution is allowed after special errors only.

These special errors are:

  • NAT3706: Load module not found

  • SQL -805: DBRM (database request module) does not exist in plan

  • SQL -818: Mismatch of timestamps

Parameter Macro NDBID

The parameter macro NDBID determines the database type of an SQL DBID.

The NDBID macro is specified as follows:

  1. Default Database Definition

    The default database type is specified as follows. It applies to all database IDs not explicitly specified by NDBID.

    NDBID=database-type
  2. Single Database Definition

    A single database ID and its type is specified as follows:

    NDBID=database-type,database-id 
  3. Multiple Database Definition

    Multiple database IDs of the same database type can be specified together, enclosed in parentheses:

    NDBID=(database-type,database-id1,database-id2,...) 

database-type

Possible Values Explanation
DB2 Databases are accessed via Natural for DB2 (NDB). This is the default value.
CNX Databases are accessed via Natural SQL Gateway (NSB).

database-id

Possible Values
1-254

Top of page