Operation

#### Search Results

Search

# Operation

This section provides information on various operational aspects of Natural for VSAM:

- Invoking Natural for VSAM

- OPEN/CLOSE Processing

- Natural File Access

- Buffers for Memory Management

- Application Programming Interfaces

## Invoking Natural for VSAM

If the Natural interface to VSAM is available, it is initialized when you start a Natural session. It can be switched off by setting the `VSIZE` parameter to `0` (see also the relevant description in the section Natural for VSAM Parameters).

## OPEN/CLOSE Processing

In this section, VSAM files means both VSAM user files and VSAM Natural system files.

Database `OPEN`/`CLOSE` processing is controlled by the Natural parameter `OPRB`, which is described in Profile Parameters in the Natural Parameter Reference documentation.

Instead of using the `OPRB` parameter, you can also use the `NTOPRB` macro of the Natural parameter module, which is described in Parameter Modules in the Natural Parameter Reference documentation.

An `OPEN`/`CLOSE` error must be followed by the NAT3539 error message. In a TP environment, the NAT3516 error message can also occur during an active Natural session if the file is closed.

Note
For dynamic `OPEN` handling within a session, you can use the application programming interface USR2008N.

The section below covers the following topic:

- OPRB Parameter for VSAM Databases

### OPRB Parameter for VSAM Databases

The `OPRB` parameter is not applicable under CICS or Com-plete, because in these environments, the TP monitor controls the `OPEN`/`CLOSE` processing of VSAM files.

By default, that is, without the `OPRB` parameter being specified, VSAM files are opened for input/output so that they can be read and/or updated.

If you want all used VSAM files to be opened for input only, you specify the `OPRB` parameter using the following syntax:

`OPRB = (.ALL)`

With this syntax, you specify an `OPEN` request for all VSAM files to be addressed. All files are opened for input only; individual files, however, are only opened when they are actually addressed by a given program.

Note
If you want all VSAM system files to be opened for input, you have to set the Natural profile parameter `ROSY=ON`; see also the relevant section in the Natural Parameter Reference documentation.

If you want to open VSAM files for input (`I`) or output (`O`) per DBID, use the following syntax:

`OPRB = (DBID =` nnn, |  | `MODE =` |  | `I` |  | `[,` string `; ...]` |  | `[, ...]` | `)`
`O`
| string `; ...`

With `MODE`, you specify a global default handling for `DBID nnn`.

If you do not want to specify a default handling per DBID or if, for some VSAM files, you want an input/output handling other than the default one, you specify the `string` parameter in the appropriate way.

The DBID must be defined with the `NTDB` macro as a VSAM DBID, and `string` varies depending on the operating system (see below).

Important: If several strings are to be defined, a semicolon (;) must be specified as delimiter character. If not, the semicolon must be omitted.

#### Under z/OS

Under z/OS, you specify the string as follows:

|  |  |  |  |  |  | `,` |  |  |  | `,` |  |  | `[,R]`
`FNR =` nnn | `K` |  |
| `E` | `O` | `B`
`DD =` dd-name `, TYP =` | `R` | `I` | `A`
| `P` |  |

The specified VSAM files must be defined as DDMs. However, instead of specifying the file number of the Natural DDM that corresponds to the VSAM file to be addressed, the dd-name and type (`KSDS`, `ESDS`, `RRDS`, or `PATH`) of this file can be specified directly, which saves you from having to look into the DDM first.

Individual files can be opened for output (option O), input (option I), opened before they are actually accessed (option B), or when they are accessed for the first time (option A), opened as reusable file (option R).

For performance reasons, it is sometimes desirable to modify the VSAM `STRNO` (string number) parameter to provide more index and data buffers. By default, Natural uses string number 3 for input processing and string number 5 for output processing. Since `STRNO` is specified in the JCL, both values can be modified with the `AMP` parameter in the corresponding DD card.

#### Sample OPRB Specification

The following `OPRB` example opens the specified files for input, while files not specified are opened for output by default:

`OPRB=(DBID=254,MODE=I)`

or

`OPRB=(DBID=254,FNR=21,I,A;FNR=22,I,A)`

The VSAM DBID and FNR as specified in the DDM are required. Option `I` specifies the corresponding FNR to be opened for input; option `A` specifies the corresponding FNR to be opened only if the file is accessed by a Natural program.

The corresponding `NTOPRB` macro example would be:

`NTOPRB 254,'MODE=I'`

or

`NTOPRB 254,'FNR=21,I,A';'FNR=22,I,A'`

## Natural File Access

The Natural interface to VSAM supports VSAM entry-sequenced data sets (ESDS), key-sequenced data sets (KSDS), relative record data sets (RRDS), variable relative record data sets (VRDS), and paths for alternate indexes.

To enable Natural to access VSAM files, a Natural DDM is required for each VSAM file that is to be made accessible to Natural programs.

The section below covers the following topics:

- Natural Data Definition Modules (DDMs)

- SYSDDM Main Menu

- Catalog DDM

- Edit DDM

- Restrictions with DDM Generation as Compared to Adabas

### Natural Data Definition Modules (DDMs)

A data definition module (DDM) must be set up for each file. DDMs are created and maintained with Predict (see the Predict documentation for details) or with the Natural utility `SYSDDM`; they are stored in the Natural dictionary system file (`FDIC`).

With VSAM, in addition to logical Natural DDMs, also VSAM user DDMs can be created from one physical DDM.

If you do not have Predict installed, use the `SYSDDM` utility to create DDMs from VSAM files. The `SYSDDM` utility is described in the Natural Editors documentation; the parts of it relevant to VSAM are described in the following sections.

All DDMs used within a session are located in the Natural buffer pool. This increases performance and enables synchronization of DDM usage across multiple sessions.

### SYSDDM Main Menu

The following functions on the main menu of the `SYSDDM` utility are relevant to Natural for VSAM:

Function | Explanation
--- | ---
Catalog DDM | The DDM currently in the work area is cataloged, making it available for use within Natural applications. The DDM must have previously been placed in the work area by a `READ` command (see also Editor and System Commands in the SYSDDM Utility documentation), or have been entered by using the Edit DDM function described below. Below are further details about Catalog DDM.
Edit DDM | Reads a DDM from the system file `FDIC` and into the `SYSDDM` work area, where it can be edited.
List DDMs | Displays a single DDM source (DDM editor not invoked) or a list of DDMs. The display format and options are identical to those of the `LIST DDM` command (see also Editor and System Commands in the SYSDDM Utility documentation).
Copy DDM to Another FDIC File | One or all DDMs can be copied to a different Natural system file (`FDIC`) and/or to a different database. This is, for example, necessary during conversion of a Natural application from test to production status. In addition to the DDM name, DBID and FNR, with Natural for VSAM the file type `V` must be specified, as well as the DD/FCT name of the Natural system file `FDIC`, if the `FDIC` file is a VSAM file.
List DDMs with Additional Information | Displays a list of the DDMs stored in the specified `FDIC` system file. From the list, you can select individual DDMs for further processing. This function differs from the List DDMs function in that it displays additional items of information on the individual DDMs. The information displayed includes file name, DBID, file number, DDM length, security type (with Natural Security only), file type (that is, `LOG.DDM`, `PHY.FILE`, `LOG.FILE` or `USERDDM` for VSAM DDMs) and remarks as, for example, the VSAM file organization (KSDS, VRDS, RRDS, ESDS); see the section SYSDDM Utility in the Natural Editors documentation for details.
Delete DDM | Deletes a previously cataloged DDM from the Natural system file `FDIC`. The DDM remains in the work area. Important If a DDM is deleted with `SYSDDM`, the corresponding Natural Security file profile is automatically deleted.

The following parameters relevant to Natural for VSAM can be specified for the various functions:

Parameter | Explanation
--- | ---
`DDM Name` | The name of the DDM to be processed.
`FNR` | The file number of the DDM to be processed.
`DBID` | The database which contains the DDM to be processed.
`Replace` | If `Y` is entered, DDMs which are being copied or cataloged and which are already existent are replaced. If `N` is entered, such DDMs are not replaced.
`FDIC Type` | The type of the system file `FDIC`.
`DDM Type` | The type of the DDM. For VSAM, the type must be `V`.
`DBID Type` | The type of the DDM. For VSAM, the type is `V`.

### Catalog DDM

A DDM can be cataloged by either using function code `C` in the `SYSDDM` main menu or entering the `CATALOG` command in the Command line of the DDM maintenance editor.

File name and file number are required for this function. With Natural for VSAM, a DBID assigned to VSAM must be specified. If no DBID is entered, it is assumed to be 0 and is generated dynamically at execution time based on the DBID of the Natural user system file (`FUSER`) in use (see also the description of the `UDB` parameter in the section Profile Parameters in the Natural Parameter Reference documentation).

If a DBID assigned to VSAM is specified (and `V` for VSAM in the field Type of this DDM), `SYSDDM` prompts you for additional information.

Note
The actual DBID assignments for VSAM is made with `NTDB` macros when assembling the Natural parameter module; see Installing Natural for VSAM in the Installation for z/OS documentation.

#### Additional Options for VSAM Files

If the DDM is to access a VSAM file, an additional screen, requiring the entry of additional VSAM options, is displayed:

    13:11:33              ***** NATURAL SYSDDM UTILITY *****             2021-06-14
                             - Catalog a VSAM file/DDM -
    DDM Name AUTOMOBILES-VS                    Def.Seq.        DBID   254 FNR     12

        VSAM file information

        VSAM file name ........... AUTO____
        VSAM View ................ N (Y/N)
        Logical related to FNR ... _____
        User defined prefix ...... ________________

        VSAM file organisation

        KSDS, ESDS, RRDS, VRDS ... K (K,E,R,V)
        Extended file ............ N (Y/N)

        Compress file ............ N (Y/N)
        Zones X'0C' / X'0F'....... F (C/F)

The additional options for VSAM files consist of two parts: VSAM File Information and VSAM File Organization.

#### VSAM File Information Options

Option | Explanation
--- | ---
VSAM file name | The DDNAME/FCT entry as defined to the TP monitor or when using batch mode, for example:
    //PERSON DD ...
where PERSON would be entered under VSAM file name.
VSAM View (DDM) |
Indicates whether this DDM represents a logical user DDM or a physical DDM.
`Y` | Indicates that the DDM represents a logical DDM, which means that it does not necessarily correspond to the physical layout of the VSAM file. A logical DDM must use the same file number as the physical DDM from which it is derived, and the corresponding physical DDM must exist at the time the user DDM is invoked during execution. The short names of the logical DDM must be identical to those defined in the physical DDM. The sequence of fields within the DDM can be different from the physical sequence. The primary-key field must not be deleted from the DDM. Since the logical DDM is a subset of the physical DDM, the corresponding subsets of the underlying VSAM file appear to the user as independent files with different record layouts. When processing a logical DDM, the user obtains records only from the corresponding subset and not from any other subset contained in the same physical VSAM file.
`N` | Indicates that the DDM represents a physical DDM. Only one DDM with a given file number can be used as the physical DDM for a VSAM file. This physical DDM is used internally by Natural to calculate field offsets.

Logical DDMs are used to define different record types in a physical VSAM file. At DDM generation, these record types are identified by specifying a prefix for the primary key.

If a logical DDM is read, only records whose key begins with the specified prefix are returned from the VSAM file. Records beginning with any other prefix are ignored. If not specified otherwise, the prefix corresponds to the logical file number.

A different prefix must be assigned to each logical DDM. Natural automatically links the prefix with the logical key. The field layout in the logical DDM need not be the same as in the physical DDM.

The following two options are used only if the DDM represents a logical file which is to be derived from a physical VSAM file.

Option | Explanation
--- | ---
Logical related to FNR | This option is used to enter the file number of the physical DDM from which the logical file or DDM is derived. A logical DDM corresponds to a record type which is controlled by a prefix. Several logical record types can be contained in a physical VSAM file. The record types are distinguished by a prefix which determines which records are to be processed. See the example below.
User defined prefix | The prefix value which is to be assigned for the logical file. The default prefix value is the logical file number (length 3).

#### Example of Logical Related to FNR

Physical Data Set |  |  |
Key |  |  |
    X1234
    X2345
    X3456
     DDM1
     PREFIX = X
     FNR = 10
    Z1234
    Z1209
    Z9000
    DDM2
    PREFIX = Z
    FNR = 11
Read DDM1 with key |  |  |
Display key |  |  |
results in: |  |  |
    Key
    1234
    2345
    3456

#### VSAM File Organization Options

Option | Explanation
--- | ---
KSDS, ESDS, RRDS, VRDS |
The type of VSAM file:
`K` | KSDS file (default)
`E` | ESDS file
`R` | RRDS file
`V` | VRDS file
Extended file |
Specifies whether the extended VSAM file (so the larger ISN) will be used or not.
`N` | Indicates that the file is not extended. `N` is the default value.
`Y` | Indicates that the file is extended.
Compress file |
Specifies whether the file is to be compressed or not.
`N` | Indicates that the file is not to be compressed. The file is written in the maximum length (that is, the length of all fields within this file) as defined in `SYSDDM` or Predict. `N` is the default value.
`Y` | Indicates that the file is to be written in variable record length. During compression, the record is scanned backwards for default values, which are blank for alphanumeric fields, low values for binary fields, low values with a zone for packed fields and `X'F0'` for numeric fields. Compression stops as soon as the first non-default value is detected or the first descriptor is found. The new computed length is used to write the record to the file; this applies to KSDS and ESDS files only. Compression of trailing null values in VSAM records minimizes the space required for VSAM records. The application programming interface `USR0100N` in the library `SYSEXT` is provided to be able to maintain the logical record length by a Natural program.
Zones X'0C' / X'0F' | In Adabas all positive packed values have `X'0F'` as a zone. This value could be different in VSAM.
`F` | Indicates that all packed data are written to the VSAM file with the zone `X'0F'`. This is the default.
`C` | Indicates that all packed values are written to the VSAM file with the zone `X'0C'`.

### Edit DDM

To edit the DDM currently loaded in the work area, you can use the DDM editor of the `SYSDDM` utility. If no DDM has been read into the work area, an empty screen is displayed, allowing the manual entry of a DDM definition.

Instead of entering a complete DDM manually, you can read an existing DDM definition into the work area, by entering `EDIT ddm-name` in the DDM editor Command line. This DDM can be modified and cataloged under a different name.

Note
When you modify a DDM, all objects which reference this DDM have to be cataloged again.

#### DDM Editor

Example:

    11:26:09                  ***** EDIT DDM (VSAM) *****                2007-02-25
    DDM Name EMPLOYEES-VS                      Def.Seq.        DBID   254 FNR     1
    Command
    I T L DB Name                             F Leng  S D Remark
    - - - -- -------------- top ------------- - ----- - - ------------------------
        1 AA PERSONNEL-ID                     A 8.0     P
      *      CNNNNNNN
      *      C=COUNTRY
      G 1 AB FULL-NAME
        2 AC FIRST-NAME                       A 20.0  N
        2 AD MIDDLE-NAME                      A 20.0  N
        2 AE NAME                             A 20.0    A
        1 AF MAR-STAT                         A 1.0   F
      *      M=MARRIED
      *      S=SINGLE
      *      D=DIVORCED
      *      W=WIDOWED
        1 AG SEX                              A 1.0   F
        1 AH BIRTH                            N 6.0
      G 1 A1 FULL-ADDRESS
      M 2 AI ADDRESS-LINE                     A 20.0  N
        2 AJ CITY                             A 20.0  N

If you enter the `HELP` command or a question mark (?) in the Command line, the editor help information is displayed.

The header information of the DDM editor is:

DDM Name | The name used to reference the DDM in a Natural program. The name must be unique within the specified Natural system file.
Def. Seq. | The default sequence by which the file is read when it is accessed with a `READ LOGICAL` statement in a Natural program.
DBID | The database in which the file to be accessed with the DDM is contained. With Natural for VSAM, a DBID assigned to VSAM must be specified. If `0` is specified, the default DBID for the Natural user system file (`FUSER`) as defined in the Natural parameter module is used. Note The actual DBID assignments for VSAM are made with `NTDB` macros when assembling the Natural parameter module; see Installing Natural for VSAM in the Installation for z/OS documentation.
FNR | The number of the file being referenced. The specified file number is used internally by Natural for VSAM.

The DDM itself comprises the following field definition attributes which can be entered or modified:

Attribute | Explanation
--- | ---
I | Line indicator. This field is used by the DDM editor to mark lines.
`E` | Lines containing an error detected during execution of the CHECK command.
`S` | Lines containing a scanned value.
`X`/`Y` | Lines selected for copy/move operation.
T | Field Type:
`G` | Group header.
`M` | Multiple-value field.
`P` | Periodic group header.
`*` | Comment line.
blank | Elementary field.
L | Level number assigned to the field. Valid level numbers are 1 - 7. Level numbers have to be specified in consecutive ascending order.
DB | For VSAM files, the two-character code which is used in VSAM.
Name | A 3- to 32-character external field name. This is the field name used in Natural programs to reference the field.
F | Field format. For valid formats, refer to User-Defined Variables, Format and Length of User-Defined Variables (in the Natural Programming Guide).
Leng | Standard field length. This length can be overridden in a Natural program. For numeric fields (format N), the length is specified as `nn.m`, where `nn` represents the number of digits before the decimal point and `m` represents the number of digits after the decimal point.
S | This attribute is not applicable to Natural for VSAM.
D | Descriptor Option.
`A` | Indicates that the field is an alternate index for a VSAM file.
`P` | Indicates that the field is a primary key.
`S` | Indicates that the field is a primary subdescriptor or superdescriptor; that is, a primary key for a VSAM file.
`X` | Indicates that the field is an alternate subdescriptor or superdescriptor; that is, an alternate index for a VSAM file.
Remark | A comment which applies to a field and/or the DDM.

Most of the editor and line commands available with the Natural program editor also apply to the Natural DDM editor. Special commands, such as `PROFILE`, `RENUMBER`, `SET`, `SHIFT`, etc. and some line commands are not available. Refer to the section SYSDDM Utility in the Natural Editors documentation and to the section Program Editor in the Natural Editors documentation for more details on editor commands.

#### Extended Editing at Field Level

The DDM editor can also be used to enter or modify DDM definitions at field level.

Extended editing mode is used to specify field headers and edit masks to be applied when the field is used in a `DISPLAY` or `INPUT` statement, as well as further specifications for VSAM DDM definitions. All the other information specific to the field (field type, length, name, format, remarks) can also be modified at this point.

The extended editing mode is invoked by entering the line command `.E` in the first positions of the line containing the field.

A range of field definitions can be selected for editing by entering `.Ennn` where `nnn` is the number of fields to be selected.

The field level editing mode is terminated when you press ENTER with or without having made any modifications.

The Extended Field Editing screen displays special attributes of the field definition if the edited DDM is a VSAM DDM:

     11:25:26                 ***** EDIT DDM (VSAM) *****                 2007-02-25
                               - Extended Field Editing -
     DDM Name AUTOMOBILES-VS                    Def.Seq.        DBID   254 FNR    12

     I T L DB Name                             F Leng  S D Remark
     - - - -- -------------- top ------------- - ----- - - ------------------------
         1 GA OWNER-PERSONNEL-NUMBER           N 8.0     A SECONDARY KEY
     ------------------------------------------------------------------------------

     Field Header .......... OWNER/NUMBER______________________________________
     Field Edit Mask ....... __________________________________________________

     Alternate Index Name .. AUTOY___

     Maximum Occurrence ....   1

     Upgrade Flag .......... _ (X)
     Unique Key Flag ....... _ (X)
     Null Flag ............. _ (X)

     Field GA redefines field __ with offset   0

The following attributes can be specified:

Attribute | Explanation
--- | ---
Alternate Index Name | If the field references a VSAM alternate index or a path (denoted by an `A` in column D), the index or path name must be entered here.
Maximum Occurrence | The number of occurrences for a multiple-value field or a periodic group (denoted by an `M` or `P` in column T).
The following flags only apply to alternate indexes and not to paths:
Upgrade Flag | Since Natural does not use VSAM paths, upgrading can be performed either by Natural or by VSAM when using a KSDS or ESDS file with alternate indices defined. A blank value indicates that upgrading the alternate index is to be done by VSAM, which is the default. If VSAM is to perform the upgrading, define the VSAM file using IDCAMS with `UPGRADE`. If you enter an `X`, upgrading of the alternate index is performed by Natural. If so, the AIX must be defined with the `NONUPGRADE` option. Note For LSR handling, it is recommended that you specify this option. Under CICS, the FCT entry must also contain the `VARIABLE` option.
Sort Flag | If this option is marked with an `X`, the alternate index is to be read in ascending or descending value order. This option only takes effect if the Upgrade Flag option is specified, too.
Unique Key Flag | If this option is marked with an `X`, Natural ensures that the values of the alternate index field are unique. An attempt to update with a non-unique value results in an error message. The default value is a blank. This option only takes effect if the Upgrade Flag option is also specified.
Null Flag | A value of `S` indicates that null values for the alternate index field are suppressed. The default value is a blank. This option only takes effect if the Upgrade Flag option is also specified.

Note
For all DDMs cataloged with Natural which contain alternate indexes and any specifications for the above flags, all flags are nullified during runtime as soon as path processing is activated for these DDMs.

The last two fields on the screen are used to define sub-/superdescriptors for a VSAM file. For example, to define the field `S1` as superdescriptor beginning in field `BA` and ending in field `BB`, the following would be entered:

    S1 redefines BA with offset 0

The field `S1` must have been defined to VSAM as a primary or secondary key.

VSAM superdescriptors can only be constructed from fields which are contiguous. To define the field `S2` as a superdescriptor which begins in the 11th position of field `BA` and ends with the first two positions of field `BB`, the following would be entered:

    S2 redefines BA with offset 10

In addition, the length of `S2` would have to be set to `7`. As mentioned above, `S2` must have been defined as a primary or alternate index to VSAM.

### Restrictions with DDM Generation as Compared to Adabas

- No keys can be defined within periodic groups.

- Descriptors that contain multiple-value fields are not allowed with VSAM.

- Natural DDMs for VSAM cannot contain multiple-value fields or periodic groups within periodic groups.

- The same field cannot be defined more than once in the same DDM. A data definition as in the following example would lead to unpredictable results when used with VSAM:

#### Example:

    ...
    G 01 AB FULL-NAME
            02 AC FIRST-NAMEA 20.0  N
            02 AD MIDDLE-I                  A  1.0 N   /* duplicate short name
            02 AE NAME                      A 20.0
            01 AD MIDDLE-NAME               A 20.0 N   /* duplicate short name
    ...

Natural would treat the field `MIDDLE-I` not as a redefinition of `MIDDLE-NAME` but as a separate field.

## Buffers for Memory Management

The `VSIZE` parameter is suballocated into ten different areas whose sizes are determined by the assembly of the Natural parameter module. The different VSAM areas are split into fixed and variable buffer types. If there is insufficient space in the `VSIZE` buffer for all Natural parameter module areas, you receive error message NAT3592 during initialization. At runtime, error message NAT3513 can occur for fixed buffer types. In this case, you must adapt the corresponding the Natural parameter module value. Variable buffers are increased during runtime, NAT3513 does not occur. Some buffer sizes depend on the use of VSAM system files. The relevant buffers are FCT, FWA, TSA and UPD.

The `VSIZE` parameter is suballocated as follows:

- FCT - File Control Table

- FWA - File Work Area

- OPV - Open Table

- SFT - System File Table

- SWT - Switch Table

- TAF - Table of Accessed Files

- ROLL - Table of Session Status Information

- DFB - Table of Decoded Format Buffers

- TSA - Table of Sequential Access

- UPD - Table of Update Records

- VCA - Natural Control Area for VSAM

### FCT - File Control Table

FCT contains file-specific information and is a fixed buffer type.

FCT also contains the complete VSAM access control block (ACB), information on existing user exits, and information on the application programming interface `USR0100N`.

The size of the table is determined by using the following formula and then rounding up to a double-word boundary:

( 72 + ACB-length ) ( TAFE * 2 ) + 80

Without VSAM system files, the default setting is:

( 72 + 76 ) ( 10 * 2 ) + 80 = 3040

With VSAM system files, the default setting is:

( 72 + 76 ) ( 26 * 2 ) + 80 = 7776

FCT and SWT (see below) share a common buffer area.

### FWA - File Work Area

FWA contains information on a VSAM request and is a fixed buffer type.

FWA also contains information on the VSAM request parameter list (RPL).

The size of the table is determined by using the following formula and then rounding up to a double-word boundary.

( 40 + RPL-length ) ( TAFE * 2 ) + 80

Without VSAM system files the default setting is:

( 40 + 76 ) ( 10 * 2 ) + 80 = 2400

With VSAM system files the default setting is:

( 40 + (76*4) ) ( 26 * 2 ) + 80 = 17968

FWA and OPV (see below) share a common buffer area.

### OPV - Open Table

OPV contains information on an `OPRB` string and is a fixed buffer type.

The size of the table is determined by using the following formula and then rounding up to a double-word boundary:

24 * ( TAFE * 2 ) + 48

The default setting is :

24 * ( 10 * 2 ) + 48 = 528

OPV and FWA share a common buffer area.

### SFT - System File Table

This table is only active if VSAM system files are defined. The buffer type is fixed.

This area contains the description of the VSAM system files `FNAT`, `FUSER`, `FDIC`, `FSEC` and `FSPOOL` as well as the system file used by Natural ISPF, if available.

The size of the area is 8192 for `SFILE=ON`. The default setting is 0.

### SWT - Switch Table

SWT contains information necessary for the application programming interface `USR1047N` for dynamic DD/DLBL modification. SWT is allocated only if the value specified for the parameter `DDSWITE` in `NTVSAM` is greater than 0.

The SWT buffer type is fixed.

The size of the table is determined by using the following formula and then rounding up to a double-word boundary:

24 * DDSWITE + 48

The default setting is 0.

SWT and FCT (see above) share a common buffer area.

### TAF - Table of Accessed Files

This area describes the record layout for each file accessed by Natural; it is created by reading the physical or logical DDM for the file. Each TAF entry consists of a header entry and an entry for each field in the DDM. The header entry describes the type of file, file name, primary key, etc. The field entries describe the format, offset, and length of every field in the file. The layouts for the header and field entries are described in the macros NVMTAF and NVMFLD respectively.

The TAF buffer type is fixed.

The size of the table is determined by using the following formula and then rounding up to a double-word boundary:

( ( ( 32 * TAFN ) + 112 ) * TAFE ) + 80

The default setting is:

( ( ( 32 * 50 ) + 112 ) * 10 ) + 80 = 17200

### ROLL - Table of Session Status Information

This table is used to keep track of the position within a file for every active `FIND` or `READ` statement; it is identified by the CID. This allows Natural to release all VSAM resources during a ROLLOUT operation and then reposition itself correctly after a ROLLIN operation.

The ROLL buffer type is fixed.

The size of this area is determined by the subparameter `ROLLSIZ` of macro `NTVSAM` in the Natural parameter module, rounded up to a double-word boundary:

TAXSIZE + 80

The default setting is:

550 + 80 = 632

### DFB - Table of Decoded Format Buffers

The table is suballocated into two areas, one for global format IDs (GFIDs) and one for command IDs (CIDs).

For any given I/O request, this area describes which fields from the VSAM record area are returned to the Natural record buffer. Each DFB (decoded format buffer) entry consists of one header, identified by the CID or the GFID of the I/O request, plus an entry for each field to be returned to Natural. Each field entry in the DFB contains the format, offset, and length of the field as derived from the associated TAF entry for the file. The layouts of the header and field entries are described in the macros `NVMDFB` and `NVMDFF` respectively.

The DFB buffer type is fixed. If the no-space-condition occurs for GFID-oriented entries, the oldest entries are deleted.

The size of the TDFB area is determined by using the following formula and then rounding up to a double-word boundary:

( 16 * DFBN * 2 + 36 ) * DFBE * 2 + 128

The default setting is:

( 16 * 50 * 2 + 36 ) * 10 * 2 + 128 = 32848

### TSA - Table of Sequential Access

The TSA is used to keep important pointers and information on each `READ` or `FIND` statement. There is one TSA entry for each active `READ` and `FIND` statement, and each entry is identified by the CID. The layout of the TSA is described in the macro `NVMTSA`.

The TSA buffer type is variable.

The size of the area is determined by using the following formula and then rounding up to a double-word boundary:

(104 + KEYLGH) * TSAE + 80

Where TSAE = TSA entry.

The default setting is:

(104 + 32) * 10 + 80 = 1440

### UPD - Table of Update Records

This area contains an entry for every `READ` or `FIND` loop that contains an `UPDATE` or `DELETE` statement. These entries are released when an `END TRANSACTION` or `BACKOUT TRANSACTION` statement is executed. Each entry contains control information about the record and the values of all the fields that might be updated within the loop. The layout of each UPD entry is described in the macro `NVMUPD`.

The UPD buffer type is variable.

The size of the UPD area is determined by the subparameter `UPDL` of macro `NTVSAM` in the Natural parameter module, rounded up to a double-word boundary.

The default setting is 8272 without VSAM system files and 32848 with VSAM system files.

### VCA - Natural Control Area for VSAM

VCA is a fixed length area which contains pointers, addresses, flags, and work areas that are important to a Natural environment for VSAM. The layout for this area is described in the macro `NVMCA`. Within a Natural environment for VSAM, R3 always points to this area.

The size of this area is 6744 bytes.

## Application Programming Interfaces

Natural for VSAM provides the following application programming interfaces (APIs) in the Natural system library `SYSEXT`:

API | Function
--- | ---
`USR0100N` | Controls the VSAM variable record length (LRECL).
`USR1047N` | Supports dynamic switching of DD/DLBL names defined in a DDM.
`USR2008N` | Supports dynamic `OPEN` calls for VSAM data sets.

A short description of the APIs is provided in the following section; for more detailed information, log on to the system library `SYSEXT` and display the text object (`USRxxxxT`) that corresponds to the required API.

The section below contains information on the following APIs:

- USR0100N

- USR1047N

- USR2008N

### USR0100N

The API `USR0100N` controls the record length of variable VSAM files.

The API is invoked as follows (a sample program called `USR0100P` is provided in the library `SYSEXT`):

    CALLNAT 'USR0100N' parm1 parm2 parm3 parm4 parm5

The parameters are described in the following table:

Parameter | Format/Length | Explanation
--- | --- | ---
`parm1` | A1 | Specifies either of the following function codes:
G | For retrieval statements; the current record length is determined for `parm5`.
P | For update/store statements; the length specified in `parm5` becomes the current record length.
`parm2` | A8 | Specifies the DD/DLBL name for the current file (optional); if specified, `parm5` is only valid for this file.
`parm3` | N5 | Specifies the DBID taken from the DDM (optional); is used instead of the DD/DLBL name and only in conjunction with `parm4`.
`parm4` | N5 | Specifies the FNR taken from the DDM (optional).
`parm5` | N5 | Specifies or returns the record length depending on the setting of `parm1`.

Note
If neither `parm2` nor `parm3` and `parm4` are specified, `parm5` is valid for all files.

### USR1047N

The application programming interface `USR1047N` enables dynamic modification of DD/DLBL names within a Natural program if the `DDSWITE` subparameter is specified in the `NTVSAM` macro. It can be used if data are spread over several VSAM files which have different DD/DLBL names, but the same record structure.

The API is invoked as follows (a sample program called `USR1047P` is provided in the library `SYSEXT`):

    CALLNAT 'USR1047N' parm1 parm2 parm3 parm4

The various parameters are described in the following table:

Parameter | Format/Length | Explanation
--- | --- | ---
`parm1` | A1 | Specifies either of the following function codes:
`S` | For switching of DD names with the next following database calls.
`R` | For resetting of DD names; the switch table entry of function `S` has been deleted (see SWT - Switch Table).
`parm2` | A8 | Specifies the old DD name taken from the DDM.
`parm3` | A8 | Specifies the new DD name for the next database calls.
`parm4` | P4 | Return code of Natural for VSAM.

The parameter `parm4` can contain the following response codes:

Code | Explanation
--- | ---
`0` | Normal return.
`4` | The switch table (SWT) is too small; increase the `DDSWITE` subparameter in macro `NTVSAM`.
`8` | The switch table entry has not been found; program error.
`12` | Invalid function code.
`16` | The switch table is not allocated; that is, the `DDSWITE` parameter is set to `0`.

### USR2008N

This application programming interface (API) is not applicable under Com-plete and CICS.

`USR2008N` supports dynamic `OPEN` calls during a Natural session if `OPSUPP=ON` is specified in the `NTVSAM` macro.

The API is invoked as follows (a sample program called `USR2008P` is provided in the library `SYSEXT`):

    CALLNAT 'USR2008N' parm1 parm2 parm3 parm4 parm5 parm6

The parameters are described in the following table:

Parameter | Format/Length | Explanation
--- | --- | ---
`parm1` | N5 | Specifies the DBID taken from the `NTDB` macro definition; see NTDB Macro in the section Natural for VSAM Parameters.
`parm2` | A1 | Specifies the global `OPEN MODE`; see OPEN/CLOSE Processing.
`parm3` | A4 | Specifies the data management type, for example, VSAM.
`parm4` | A40/16 | Specifies the valid `OPRB` syntax and/or DDM long name instead of the `DD=` or `FNR=` definitions.
`parm5` | P4 | Returns the Natural for VSAM error number.
`parm6` | A50 | Returns the Natural for VSAM error text.

### On this page

- Invoking Natural for VSAM
- OPEN/CLOSE Processing
- Natural File Access
- Buffers for Memory Management
- Application Programming Interfaces