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.

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:

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.

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

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:

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.

Under z/VSE

Under z/VSE, no string number can be specified in the JCS. Therefore, the syntax has been enhanced to be able to specify a string number with the OPRB parameter, where nn can be in the range from 1 to 10. Thus , string represents:

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:

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

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.

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:

11:24:04           ***** NATURAL SYSDDM UTILITY *****                2006-05-25
                         - Catalog a VSAM file/DDM -

        DBID 254   FNR  12    DDM AUTOMOBILES-VS                   Def seq
      ---------------------------------------- 
     VSAM file information
     
     VSAM file name ............ AUTO
     VSAM View ...........(Y/N) N
     Logical related to FNR ....
     User defined prefix .......   

     VSAM file organization   
                               
     KSDS, ESDS, RRDS, VRDS (K,E,R,V) .. K   
                                      
     Compress file ........(Y/N) N 
     Zones X'0C' / X'0F' (C/F) F

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

VSAM File Information Options

//PERSON DD ...

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.

Example of Logical Related to FNR

X1234
X2345
X3456

 DDM1

 PREFIX = X

 FNR = 10

Z1234
Z1209
Z9000

DDM2

PREFIX = Z

FNR = 11

Key
1234
2345
3456

VSAM File Organization Options

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.

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:

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

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:

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:

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:

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:

The parameter parm4 can contain the following response codes:

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: