Natural File Server for Db2

#### Search Results

Search

# Natural File Server for Db2

In all supported TP-monitor environments (CICS, IMS TM, and TSO), Natural for Db2 provides an intermediate work file, referred to as the File Server, to prevent database selection results from being lost with each terminal I/O. Exception: Com-plete.

This section covers the following topics:

- Concept of the File Server

- Preparations for Using the File Server

- Logical Structure of the File Server

## Concept of the File Server

To avoid reissuing the selection statement used and repositioning the cursors, Natural writes the results of a database selection to an intermediate file. The saved selected rows, which may be required later, are then managed by Natural as if the facilities for conversational processing were available. This is achieved by automatically scrolling the intermediate file for subsequent screens, maintaining position in the work file rather than in Db2.

All rows of all open cursors are rolled out to the file server before the first terminal I/O operation. Subsequently, all data is retrieved from this file if Natural refers to one of the cursors which were previously rolled out (see the description of roll out in Logical Structure of File Server below).

If a row is to be updated or deleted, the row is first checked to see if it has been updated in the meantime by some other process. This is done by reselecting and fetching the row from the Db2 database, and then comparing it with the original version as retrieved from the file server. If the row is still unchanged, the update or delete operation can be executed. If not, a corresponding error message is returned. The reselection required when updating or deleting a row is possible in both dynamic mode and static mode.

Only the fields which are stored in the file server are checked for consistency against the record retrieved from Db2.

As the row must be uniquely identified, the Natural view must contain a field for which a unique row has been created. This field must be defined as a unique key in Db2. In a Natural data definition module (DDM), it will then be indicated as a unique key via the corresponding Natural-specific short name.

## Preparations for Using the File Server

The size of a row which can be written to the file server is limited to 32 KB or 32767 bytes. If a row is larger, a corresponding error message is returned.

The File Server can use either a VSAM RRDS file or the Software AG Editor buffer pool as storage medium to save selected rows of Db2 tables.

This section covers the following topics:

- File Server - VSAM

- File Server - Editor Buffer Pool

- File Server – Shared Memory Object

### File Server - VSAM

The file server is installed via a batch job, which defines and formats the intermediate file. Samples of this batch job are supplied on the installation medium as described in the relevant section.

#### Defining the Size of the File Server

The file server is created by defining an RRDS VSAM file using AMS (Access Method Services). Its physical size and its name must be specified.

#### Formatting the File Server

The file server is formatted by a batch job, which requires five input parameters specified by the user, and which formats the file server according to these parameters. The parameters specify:

1. The number of blocks to be formatted (logical size of the VSAM file); this value is taken from the first parameter of the `RECORD` subcommand of the AMS `DEFINE CLUSTER` command.

2. The number of users that can log on to Natural concurrently.

3. The number of formatted blocks to be defined as primary allocation per user.

4. The number of formatted blocks to be used as secondary allocation per user.

5. The maximum number of file server blocks to be allocated by each user. If this number is exceeded, a corresponding Natural error message is returned.

Immediately before the first access to the file server, a file server directory entry is allocated to the Natural session and the amount of blocks specified as primary allocation is allocated to the Natural session.

The primary allocation is used as intermediate storage for the result of a database selection and should be large enough to accommodate all rows of an ordinary database selection. Should more space in the file server be required for a large database selection, the file server modules allocate a secondary allocation equal to the amount that was specified for secondary allocation when the file server was formatted.

Thus, a secondary area is allocated only when your current primary allocation is not large enough to contain all of the data which must be written to the intermediate file. The number of secondary allocations allowed depends upon the maximum number of blocks you are allowed to allocate. This parameter is also specified when formatting the file server.

The number of blocks defined as the secondary allocation is allocated repeatedly, until either all selected data has been written to the file or the maximum number of blocks you are allowed to allocate is exceeded. If so, a corresponding Natural error message is returned. When the blocks received as a secondary allocation are no longer needed (that is, once the Natural loop associated with this allocation is closed), they are returned to the free blocks pool of the file server.

Your primary allocation of blocks, however, is always allocated to you, until the end of your Natural session.

#### Changes Required for a Multi-Volume File Server

To minimize channel contention or bottlenecks that can be caused by placing a large and heavily used file server on a single DASD volume, you can create a file server that spans several DASD volumes.

To create and format such a file server, two changes are needed in the job that is used to define the VSAM cluster:

1. Change `VOLUME ()` to `VOLUMES (vol1,vol2,...)`.

2. Divide the total number of records required for the file (as specified with the first format job parameter) by the number of volumes specified above. The result of the calculation is used for the `RECORDS` parameter of the `DEFINE CLUSTER` command.

This means that in the file server format job, the value of the first parameter is the result of multiplying two parameters taken from the `DEFINE CLUSTER` command: `RECORDS` and `VOLUMES`.

### File Server - Editor Buffer Pool

The Software AG Editor buffer pool is used as storage medium when `EBPFSRV=ON` is set in the `NTDB2` macro. In this case, the primary, secondary and maximum allocation amounts for the file server are specified by `EBPPRAL`, `EBPSEC`, `EBPMAX` parameters of the `NTDB2` macro. Before Natural for Db2 tries to write data from a Natural user session to the file server for the first time, a Software AG Editor buffer pool logical file is allocated with the Natural terminal identifier as user name and the number 2240 as session number.

The operation of the file server is in this case depending on the definition of the Software AG Editor buffer pool; see Editor Buffer Pool in the Natural Operations documentation.

The number of logical files for the buffer pool limits the number of users concurrently accessing the file server. The number of work file blocks limits the amount of data to be saved at a specific moment. (You also have to consider that there are other users than Natural for Db2 of the Software AG Editor.)

However, using the Software AG Editor buffer pool as storage medium for the file server enables Natural for Db2 to run in a Sysplex environment.

If you like to use the file server in a sysplex environment, it is recommended to use the Software AG Editor buffer pool as storage medium.

### File Server – Shared Memory Object

A z/OS shared memory object above the bar is used as the storage medium for the file server. In this case, the shared memory object has the same structure as the VSAM RRDS file mentioned in the previous section, but all data is maintained in virtual storage above the bar. A file server that uses a shared memory object is referred to as a Shared Memory Objects File Server (FSSM).

To use a Shared Memory Objects File Server

1. Define the shared memory object in the `ASMPARM` parameter file (see the Operations documentation) of a Natural Authorized Services Manager that contains the `NATFSSM` module.

   For the messages that can be returned by the Authorized Services Manager, see Messages from the Shared Memory Objects File Server under NDB in the Messages and Codes documentation.

2. Set the `SMFSRV=ON` as the keyword subparameter of the `DB2` profile parameter or `NTDB2` macro.

3. Specify the name of the shared memory object to be used with the `DDFSERV` keyword subparameter of `DB2` (`NTDB2`).

4. Start the Authorized Services Manager configured in Step 1.

When Natural for zIIP is enabled in your Natural environment, switching between SRB and TCB modes for accessing the file server is not required since no disk I/O has to be performed.

> Defining Size and Format of an FSSM

>   The size and format of the FSSM is defined in the `ASMPARM` data set of the Authorized Services Manager, similar to the way the VSAM file server is defined. Each definition has the following format:

>       FSSMxxxx=(name,number-of-blocks,number-of-users,primary-blocks,secondary-blocks,maximum-blocks,block-size)

>   Explanations:

>   `FSSMxxxx` | The initialization keyword required to define a file server. `FSSM` is a mandatory prefix that can be followed by 1 to 4 characters `xxxx`.
>   `name` | The logical name for the file server. The name can contain up to 8 characters and must match the name specified with the `DDFSERV` keyword subparameter of `DB2` (`NTDB2`) used in the Natural session.
>   `number-of-blocks` | The number of blocks used by the file server. Valid range: 3 - 2147483647. The number has to be a multiple of 8.
>   `number-of-users` | The number of users that can use the file server concurrently. Valid range: 1 - 32767
>   `primary-blocks` | The primary block allocation for each user. Valid range: 1 - 32767
>   `secondary-blocks` | The secondary block allocation for each user. Valid range: 1 - 32767
>   `maximum-blocks` | The maximum block allocation for each user. Valid range: 1 - 32767
>   `block-size` | The size of each block in the file server. Valid range: 1 - 32767

>   Examples:

>       FSSMPRM1=(CMFSERV,1000,500,50,10,100,31744)

>       FSSMPRM2=(CMFSERV2,1000,203,50,10,200,4080)

> Formatting of an FSSM

>   The FSSM is formatted implicitly when the first user starts a Natural session with `SMFSRV=ON` with the name of the shared memory object specified in `DDFSERV`.

>   If another user from another address space also uses the same shared memory object, Natural for Db2 implicitly establishes access to the shared memory object for this address space. Access to the shared memory object for an address space only fails when the address space terminates.

>   Immediately before the first access to the file server, a file server directory entry is allocated to the Natural session and the number of blocks specified as primary allocation is allocated to the Natural session.

>   The primary allocation is used as the intermediate storage for the result of a database selection and should be large enough to contain all rows of an ordinary database selection. Should the file server require more space, the file server modules perform a secondary allocation using the number of blocks specified for the secondary allocation when the file server was formatted.

>   Thus, a secondary area is allocated only when your current primary allocation is not large enough to contain all of the data which must be written to the intermediate file. The number of blocks allowed for the secondary allocations depends on the maximum number of blocks you are allowed to allocate.

>   The number of blocks defined for the secondary allocation is allocated repeatedly, until either all selected data has been written to the file, or until the maximum number of blocks you are allowed to allocate is exceeded. If so, a corresponding Natural error message is returned. When the blocks received as secondary allocation are no longer needed (that is, once the Natural loop associated with this allocation ends), they are returned to the free blocks pool of the file server. However, your primary allocation of blocks is always allocated to you until the end of your Natural session.

## Logical Structure of the File Server

Immediately before a Natural user session accesses the file server, a file server directory entry (VSAM) or a logical file (Software AG Editor buffer pool) is allocated to the Natural user session and the number of blocks specified as primary allocation is reserved until the end of the session.

Generally, the file server is only used when a terminal I/O occurs within an active `READ`, `FIND`, or `SELECT` loop, where database selection results would be lost. Before each terminal I/O operation, Natural checks for any open cursors. For each non-scrollable cursor found, all remaining rows are retrieved from Db2 and written to an intermediate file. For each scrollable cursor, all rows are retrieved from Db2 and written to an intermediate file. In the Natural for Db2 documentation, this process is referred to as cursor roll out.

For each cursor roll out (scrollable and non-scrollable), a logical file is opened to hold all the rows fetched from this cursor. The space for the intermediate file is managed within the space allocated to your session. The logical file is then positioned on the row that was `CURRENT OF CURSOR` when the terminal I/O occurred.

Subsequent requests for data are then satisfied by reading the rows directly from the intermediate file. The database is no longer involved, and Db2 is only used for update, delete or store operations.

Positioned `UPDATE` and/or Positioned `DELETE` statements against rolled-out scrollable cursors are performed against the Db2 base table and against the logical file on the file server.

Once the corresponding processing loop in the application has been closed, the file is no longer needed and the blocks it occupies are returned to your pool of free blocks. From here, the blocks are returned to the free blocks pool of the file server, so that you are left with your primary allocation only.

In the following example, the space allocated to the first selection is not released until all rows selected during the third selection have been retrieved. The same applies to the space allocated to the third selection.

The space allocated to the second selection, however, is released immediately after the last row of the corresponding selection result has been retrieved.

Therefore, the space allocated to the second selection can be used for the selection results of the third selection.

If the primary allocation area is not large enough, for example, if the third selection is nested within the second selection, the secondary allocation area is used.

When a session is terminated, all of a user's blocks are returned to the free blocks pool. If a session ends abnormally, Natural checks, where possible, whether a file server directory entry for the corresponding user exists. If so, all resources held by this user are released.

If Natural is unable to free the resources of an abnormally-ended user session, these resources are not released until the same user ID logs on from the same logical terminal again.

If the same user ID and/or logical terminal are not used again for Natural, the existing directory entry and the allocated space remain until the file server is formatted again. A new run of the formatting job deletes all existing data and recreates the directory.

### On this page

- Concept of the File Server
- Preparations for Using the File Server
- Logical Structure of the File Server