Version 4.2.6 for Mainframes
 —  Operations  —

Natural in Batch Mode under z/VSE

This document contains special considerations that refer to Natural in batch mode under the operating system z/VSE.

The following topics are covered:

For considerations that refer to Natural in batch mode generally, see also:


NATVSE - Natural z/VSE Batch Mode Interface

The Natural z/VSE batch mode interface NATVSE consists of a number of service routines interfacing with the z/VSE operating system.

NATVSE is supplied as a source module and can be customized to meet your requirements; see also Installing Natural under z/VSE, where you can set the generation parameters. You can either assemble and link it to the Natural nucleus or you can run it separately, connecting with a shared nucleus.

NATVSE must run below the 16 MB line. Multiple sessions can be started in parallel within one batch region; see Subtasking Session Support for Batch Mode Environments.

Top of page

NTVSE Macro - Generation Parameters for Natural under z/VSE

The NTVSE macro contains several generation parameters (to be set in the NATVSE copy book) to change the NATVSE internal defaults.

These parameters are:

NAME | BUFSIZE | CANCEL | DSECTS | FILEID | FILMNGR | FILSCAN | FLUSH | IDUMP | LE370 | LIBRID | MAXABND | RCSIZE | RJEUSER | SEGMENT | THDSIZE | USERID | WAITIME

NAME - Name of Relocatable Module

NAME specifies the name of the relocatable module to be created by the given assembly. Possible values:

NAME=xxxxxx xxxxxx = name of the relocatable module to be created.

Maximum length: 8 characters.

NAME=NATVSE This is the default value.

BUFSIZE - Size of Natural I/O Buffer

BUFSIZE specifies the size of the Natural I/O buffer which is used for all input and output operations.

BUFSIZE=nnnn nnnn specifies the size of the Natural I/O buffer in KB.

Minimum value: 8 (KB).

BUFSIZE=8192 This is the default value.

CANCEL - Session Termination

CANCEL specifies how the Natural z/VSE interface is to proceed at session termination. Possible values:

CANCEL=YES

The job is cancelled by CANCEL or JDUMP macros, unless either Natural terminated normally or the session was terminated by the Natural TERMINATE statement.

This is the default value.

CANCEL=NO NATVSE always terminates with RETURN or EOJ macros with a set return code (the same effect is achieved when you set the Session Abend Flag UPSI XXXXX1XX).

Note:
CANCEL=YES is the default for compatibility reasons. However, it is recommended to specify CANCEL=NO, particularly to take advantage of VSE conditional job control facilities.

DSECTS - Listing of Operating System DSECTS

DSECTS specifies whether operating system DSECTS are to be listed. Possible values:

DSECTS=YES Listing of operating system DSECTS takes place.
DSECTS=NO

Operating system DSECTS are not to be listed.

This is the default value.

FILEID - Check of Label Information

FILEID specifies a string of up to 8 characters which is checked against the start of a DLBL or TLBL file ID. If it matches, this label information is ignored. Possible values:

FILEID=xxxxxxxx xxxxxxxx = any character string which must be enclosed in apostrophes if it contains special characters.
FILEID='IGNORE' This is the default value.

This is particularly helpful when DLBL or TLBL statements for CMWKFnn* and/or CMPRTnn* are supplied in the (partition) standard labels, but should not be used.

If, for example, a // DLBL CMPRT01,'...' statement is found, it is not possible to direct a WRITE(1) output to a printer SPOOL. To do so, use the JCS statement // DLBL CMPRT01,'IGNORE' and a suitable printer assignment of the relevant SYSnnn.

FILMNGR - Management of Print or Work File in Natural

FILMNGR specifies how a print or a work file is to be managed in Natural. Possible values:

FILMNGR=YES

The fact that there is label information for a print or a work file and the fact that LABEL=OFF/ON is specified for an unlabelled work file indicates to Natural that this file is available. In particular, this is relevant if the Natural print and work files are to be managed by a file management system.

This is the default value.

FILMNGR=NO The logical unit number of the Natural print or work file must be assigned to the appropriate device type.

FILSCAN - Scanning of Print or Work Files

FILSCAN specifies whether print or work files are to be scanned. Possible values:

FILSCAN=YES

The Natural z/VSE interface scans the z/VSE label area for all Natural print and work files for which no specific file access method has been defined via Natural session parameters, as this may cause overhead.

This is the default value.

FILSCAN=NO Access to all Natural print and work files must be specified explicitly via session parameters in order to be "available". This concentrates all file access efforts on the defined files.

FLUSH - Flush Card Input Files until EOF

FLUSH specifies how the Natural z/VSE interface is to proceed at session termination with the CMSYNIN/CMOBJIN card input files. Possible values:

FLUSH=YES

At session termination, the Natural z/VSE interface will read the SYSIN/SYSRDR/SYSIPT card input file until EOF, unless EOF had been encountered by Natural; this means that when driving the batch mode Natural session completely with STACK data, an extra "/*" has to be provided in the JCL for a CMSYNIN/CMOBJIN null file.

This is the default.

FLUSH=NO No extra SYSIN/SYSRDR/SYSIPT card input (null) file is required, if the batch mode Natural session is completely driven with STACK data; the SYSIN/SYSRDR/SYSIPT card input file is then left as is, thus potentially resulting in INVALID STATEMENT operator prompts or job cancellation due to INVALID STATEMENT, when the Natural CMSYNIN/CMOBJIN had not been retrieved completely.

IDUMP - Dump Creation Mode

IDUMP specifies the kind of dump the Natural z/VSE interface is to produce.

Possible values:

IDUMP=YES

The Natural z/VSE interface will create dumps using the IDUMP macro.

This is the default value.

IDUMP=NO The Natural z/VSE interface will create dumps using the SDUMP macro.

LE370 - Use of IBM Language Environment

LE370 specifies whether Natural is to run in the IBM Language Environment. Possible values:

LE370=YES The IBM Language Environment runtime environment is initialized on the initialization of the Natural session. You must specify "YES" if IBM Language Environment subroutine programs (dynamic or static) are to be called via Natural.
LE370=NO

The IBM Language Environment runtime environment is not initialized on the initialization of the Natural session.

This is the default value.

LIBRID - Check of DLBL File ID Information

LIBRID specifies a string of up to 8 characters which is checked against the start of a DLBL file ID. If it matches, the remaining portion of that file ID is scanned for information specifying a library member in a z/VSE library or library chain. Possible values:

LIBRID=xxxxxxxx xxxxxxxx = any character string of 8 characters length; must be enclosed in quotes if it contains any special characters.
LIBRID='LIBR:' This is the default value.

MAXABND - Maximum Number of Abends

MAXABND specifies the maximum number of abends which NATVSE tolerates (that is, NATVSE intercepts the abend and invokes the Natural abend handler) until it assumes an unrecoverable abend situation or abend loop and terminates the Natural session abnormally by itself. Possible values:

MAXABND=nnnn nnnn = maximum number of abends.
MAXABND=16 This is the default value.

RCSIZE - Default Roll Cache Size for a Server Environment

RCSIZE specifies the default roll cache size for a server environment for the case that the roll cache size is not passed with the Initialize Environment request. Possible values:

RCSIZE=nnnnnnnnn nnnnnnnnn = default roll cache size in KB.
RCSIZE=0 This is the default value.

RJEUSER - User ID for Submission via XPCC Macro Requests

RJEUSER defines which user ID is to be set for submission via XPCC macro requests. Possible values:

RJEUSER=YES or
RJEUSER=(YES,VSE)

RJEUSER=YES is the default value. The system variable *INIT-USER is used as the mandatory submission user ID.
RJEUSER=(YES,NAT) The system variable *USER is used as the mandatory submission user ID.
RJEUSER=NO The user ID R000 is used.

SEGMENT - Behavior at Output Spool File Close

SEGMENT specifies how the Natural z/VSE interface is to behave at CLOSE of an output SPOOL file (print or punch). Possible values:

SEGMENT=YES A file close is accompanied by a POWER segment close unless CLOSE=FIN is in effect for that file.
SEGMENT=NO The SPOOL file is closed without closing the POWER segment.

This is the default value.

THDSIZE - Default Thread Size for a Server Natural Environment

THDSIZE specifies the default thread size for a server Natural environment for the case, that the thread size is not passed with the Initialize Environment request. Possible values:

THDSIZE=nnnnnnnnn nnnnnnnnn = default thread size in KB.
THDSIZE=0 This is the default value.

USERID - Content of System Variable *INIT-USER

This parameter specifies the contents of the system variable *INIT-USER. Possible values:

USERID=YES The following logic applies: if a z/VSE user ID is specified in JCL (// ID USER=xxx), this user ID is taken; otherwise, if a POWER from-user is specified in JECL (* $$ JOB FROM=xxx), this user id is taken; otherwise, the VSE job name is taken for the Natural user ID.
USERID=NO The VSE job name is taken for the Natural user ID.

This is the default value.

WAITIME - Time Limit for Session Roll-Out

WAITIME specifies a time limit in milliseconds. It applies to the CMROLL call in a Natural server environment: if the time interval passed in the CMROLL call is not less than the WAITIME interval, the session is rolled-out and the its thread is released, while the session is waiting. Possible values:

WAITIME=nnnnn nnnnn = time limit in milliseconds.
WAITIME=1000 This is the default value.

Top of page

Natural Datasets Used under a z/VSE Batch Mode Session

The following datasets are required if certain functions are used during a Natural z/VSE batch mode session:

Dataset Explanation
CMEDIT Software AG Editor Work File
CMHCOPY Hardcopy Print Output
CMOBJIN Input for Natural INPUT Statements
CMPLOG Dynamic Profile Parameter Report Output
CMPRINT Primary Report Output
CMPRMIN Dynamic Profile Parameter Input
CMPRTnn Additional Reports 01-31
CMSYNIN Primary Command Input
CMTRACE External Trace Output
CMWKFnn Work Files 01-32

These datasets are described below.

CMEDIT - Software AG Editor Work File

The Software AG Editor work file VSAM dataset is required if a local or global Software AG editor buffer pool is to be used.

If not defined in the JCL, the name of the Editor work file specified by subparameter DSNAME of profile parameter EDBP or parameter macro NTEDBP is used by Natural to do the dynamic allocation for the Editor work file.

Alternatively, profile parameter EDPSIZE can be used to run with an auxiliary editor buffer pool, which does not require an editor work file. For more information about the installation of the Software AG editor, see Installing the Software AG Editor.

CMHCOPY - Optional Report Output for Hardcopy

The default name of the hardcopy print output dataset is CMHCOPY. It can be changed by one of the following:

The subparameters of the profile parameter PRINT for Print File 0 can be used to change the default values for the hardcopy dataset. The default dataset name CMHCOPY implies CLOSE=FIN for the hardcopy print dataset, that is, after the dataset has been opened for output, any subsequent change of the hardcopy print output dataset name will not be honored. If a different name is defined at open time, the hardcopy dataset will be closed according to subparameter CLOSE of profile parameter PRINT for Print File 0.

By default, the CMHCOPY file is assigned to SYSLST and is processed via the macro DTFPR.

If appropriate label information is supplied for the file name CMHCOPY, the print output may also be routed to disk or tape by using the z/VSE macro DTFSD or DTFMT with:

RECFORM=UNDEF,BLKSIZE=133 

When routed to a z/VSE library, the record format is fix, the record length is 80 and the default member type is PRINT.

CMOBJIN - Input for Natural INPUT Statements

CMOBJIN is used for data intended to be read by Natural INPUT statements. This type of data can alternatively be placed in the CMSYNIN input stream immediately following the relevant source program or the relevant RUN or EXEC command.

When the setting for the profile parameter OBJIN is N, Natural reads input from CMSYNIN. When OBJIN is set to Y, Natural reads input from CMOBJIN. When OBJIN is set to R, Natural determines which option has been selected for a particular session depending upon the presence or absence of a CMOBJIN label information.

By default, the CMOBJIN input file is assigned to SYSIPT. By using the profile parameter READER, it can be assigned to SYSRDR.

Alternatively, a sequential disk or labeled tape file may be used rather than a real/logical (POWER) reader file. In that case, you must supply appropriate label information for file name CMOBJIN.

Supported file formats are:

DTFSD/DTFMT: RECFORM=FIXUNB,RECSIZE=81
DTFSD/DTFMT: RECFORM=FIXUNB/FIXBLK,RECSIZE=80
LIBR:        RECFORM=FIX,RECSIZE=80 , default member type CARD

You must supply appropriate label information; for assignment, you have to use file names CMSYNIN and /or CMOBJIN.

CMPLOG - Optional Report Output for Dynamic Parameters

If profile parameter PLOG=ON is set and dataset CMPLOG is available, the evaluated dynamic profile parameters are written to this dataset during session initialization. If dataset CMPLOG is not available, the evaluated dynamic profile parameters are written to CMPRINT.

By default, the CMPLOG file is assigned to SYSLST and is processed with the macro DTFPR.

If appropriate label information is supplied for the file name CMPLOG, the print output may also be routed to disk or tape by using the z/VSE macros DTFSD or DTFMT with:

RECFORM=UNDEF,BLKSIZE=133 

When routed to a z/VSE library, the record format is fix, the record length is 80 and the default member type is PRINT.

CMPRINT - Primary Report Output

CMPRINT is used for the primary output report resulting from DISPLAY, PRINT and WRITE statements in a Natural program.

By default, the CMPRINT file is assigned to SYSLST and is processed via the macro DTFPR.

If appropriate label information is supplied for the file name CMPRINT, the print output may also be routed to disk or tape by using the z/VSE macro DTFSD or DTFMT with:

RECFORM=UNDEF,BLKSIZE=133 

When routed to a z/VSE library, the record format is fix, the record length is 80 and the default file type is PRINT.

CMPRMIN - Dynamic Parameter Dataset

CMPRMIN can be used as a dynamic parameter dataset to overcome the length restriction for the character string in the job control PARM keyword of the EXEC statement.

If available, this file is read during session initialization to get the dynamic profile parameters.

All input records from CMPRMIN are concatenated into one parameter string. Only the first 72 positions of each CMPRMIN record are significant. Trailing blanks at the end of each record are truncated; if the last non-blank character is a comma, all trailing blanks are truncated, else just one blank is left for delimiter; no commas are inserted.

Additional dynamic parameters can be supplied using the job control PARM keyword: if the PARM keyword contains a dynamic parameter string, these profile parameters are concatenated at the end of the parameter string which was built trom the input of CMPRMIN, i.e. these can be used to overwrite the parameters from CMPRMIN. If the PARM keyword is specified as SYSRDR or SYSIPT, Natural retrieves additional profile parameters from SYSRDR or SYSIPT respectively as a logical extension of the CMPRMIN dataset, i.e. the same rules apply.

CMPRMIN is a sequential disk or a labelled tape dataset. Supported file formats are:

DTFSD/DTFMT: RECFORM=FIXUNB,RECSIZE=81
DTFSD/DTFMT: RECFORM=FIXUNB/FIXBLK,RECSIZE=80
LIBR:        RECFORM=FIX,RECSIZE=80 , default member type CARD

CMPRTnn - Additional Reports

CMPRTnn is used for each additional report referenced by any Natural program compiled or executed during the session. "nn" must be a two-digit decimal number in the range 01-31 corresponding to the report number used in a DISPLAY, PRINT or WRITE statement.

Instead of CMPRTnn, another file name may be used by setting the DEST subparameter of profile parameter PRINT to an appropriate value, for example:

PRINT=((nn),...,DEST=PRNTFIL)

When supplying label information with file name CMPRTnn, the print output can be written to a disk or tape. Natural treats this print file like an unblocked fixed-length work file. When "printing" to disk or tape, the same logic as for work files applies (see below).

When mapped to a z/VSE library member, the record format is fix, the record length is 80 and the default file type for these files is PRINT.

CMSYNIN - Primary Input

CMSYNIN is used for the primary input file that contains Natural commands, Natural source programs, and (optionally) data to be read by INPUT statements during the execution of Natural programs.

By default, the CMSYININ input file is assigned to SYSRDR. By using the profile parameter READER, it may be assigned to SYSIPT.

Alternatively, a sequential disk or labeled tape file may be used rather than a real/logical (POWER) reader file. In that case, you must supply appropriate label information for file name CMSYNIN.

Supported file formats are:

DTFSD/DTFMT: RECFORM=FIXUNB,RECSIZE=81
DTFSD/DTFMT: RECFORM=FIXUNB/FIXBLK,RECSIZE=80
LIBR:        RECFORM=FIX,RECSIZE=80 , default member type CARD

CMTRACE - Optional Report Output for Natural Tracing

If profile parameter ETRACE is set to "ON" or the equivalent terminal command %TRE+ was issued, any Natural trace output during the session is written to the CMTRACE dataset. To define the Natural components that are to be traced, the profile parameter TRACE is required.

By default, the CMTRACE file is assigned to SYSLST and is processed via the macro DTFPR.

If appropriate label information is supplied for the file name CMTRACE, the print output may also be routed to disk or tape by using the z/VSE macro DTFSD or DTFMT with:

RECFORM=UNDEF,BLKSIZE=133 

When routed to a z/VSE library, the record format is fix, the record length is 80 and the default member type is PRINT.

CMWKFnn - Work Files 01-32

CMWKFnn is used for each Natural work file referenced by any Natural program compiled or executed during the session. nn must be a two-digit decimal number in the range 01 - 32 corresponding to the number used in a READ WORK FILEor WRITE WORK FILE statement.

Instead of CMWKFnn, another file name may be used by setting the DEST subparameter of profile parameter WORK to an appropriate value.

If the Natural z/VSE generation parameter FILMNGR=YES is specified and there is label information for a work file or if OFF or NOTM is specified for the LABEL subparameter of profile parameter WORK for an unlabeled work file, Natural knows the file is available. Otherwise, the Natural work-file logical-unit number must be assigned to the correct device type.

When mapped to a z/VSE library member, the record format is fix, the record length is 80 and the default member type for these files is WORK.

If a Natural printer or work file is assigned IGN, all I/O requests for these files are treated as dummy and no Natural error is generated. However, if there is no assignment or the printer/work file is assigned UA, any attempt to use this file is treated as an error.

Top of page

NATVSE Print and Work File Support for z/VSE Library Members

NATVSE supports access to z/VSE library members for input and/or output for all Natural datasets. When a z/VSE library member is accessed, only "card image format" is supported, that is, a record length of 80 bytes.

The access to a z/VSE library member is triggered via the file ID of an associated DLBL statement. A special string (see LIBRID in NTVSE Generation Parameters) at the start of the file ID field in the DLBL statement signals that the Natural dataset actually is a z/VSE library member which is specified in the remainder of the file ID field.

The following specifications are possible:

C=chain Specifies a library concatenation chain defined in JCL.
S=library.sublib Specifies a specific sublibrary in a specific library.
M=mbrname.mbrtype Specifies a library member name and its type.

The following rules apply:

Example:

// LIBDEF PROC,SEARCH=(...) 
// LIBDEF SOURCE,SEARCH=(...)
// DLBL CMWKF01,'LIBR:M=FILE1.TEST S=SAGLIB.USRLIB'      
// DLBL CMWKF02,'LIBR:       S=SAGLIB.USRLIB'                  ->   M=CMWKF02.WORK
// DLBL CMWKF03,'LIBR: M=TEST   C=PROC'                        ->   M=TEST.WORK
// DLBL CMPRT04,'LIBR:M=*.LISTING,S=SAGLIB.USRLIB'             ->   M=CMPRT04.LISTING
// DLBL CMPRT05,'LIBR:'                                        ->   M=CMPRT05.PRINT,C=SOURCE
// DLBL CMPRT06,'LIBR:M=WORK'                                  ->   M=WORK.PRINT,C=SOURCE
// DLBL CMWKF07,'LIBR:      M=*.DATA'                          ->   M=CMWKF07.DATA,C=SOURCE
// DLBL CMPRMIN,'LIBR:M=*.*'                                   ->   M=CMPRMIN.CARD,C=SOURCE

Notes:

  1. When a chain is specified or defaulted for an output file, the output is written into the first sublibrary specified in the chain.
  2. If a member with the same name and type already exists in a target sublibrary of a Natural output file, this member is replaced unconditionally.
  3. The file ID field of a DLBL statement is just 44 characters in length, which is not enough to specify all (sub)parameters in their full length. Therefore it is recommended to take advantage of the defaults. Regarding the member name, there is also the option to specify the file name via the DEST subparameter of the Natural profile parameter PRINT or WORK.

Top of page

NATVSE Dynamic Work File Allocation (DYNALLOC) Support

Natural under z/VSE offers functionality to define work files dynamically, that is, these files need not be predefined in JCL. This means that Natural under z/VSE adds labels into the partition's temporary labels area for work files defined using a DEFINE WORK FILE statement.

In this respect Natural under z/VSE does not modify existing label information. All file labels dynamically added by a Natural session are deleted at session termination.

The following topics are covered below:

Prerequisites

A disk file manager is required, as it is not feasable to have fix file extent information within Natural application programs, particularly when these programs are executed in parallel in the same partition or in several partitions. This is not a restriction, as at least VSAM/SAM is available under z/VSE.

For dynamic allocation support by Natural under z/VSE, the following keyword subparameters of Natural profile parameter WORK have been made sensitive:

DEFINE WORK FILE Keyword Parameters

The following keyword parameters are available for dynamic work files under VSE:

Keyword Parameter Purpose
CAT=catalog Triggers the usage for VSAM/SAM for the dynamic work file, where catalog is the 1 to 7 characters VSAM catalog file name. As this parameter is mandatory, if you want to use VSAM/SAM, you have to specify a VSAM job catalog explicitely (CAT=IJSYSUC).
VOL=volser If specified a // EXTENT information is generated with that 1 to 5 characters volume serial number; its content depends on the preceeding DLBL information, see below.
DSN=fileid Is the DSN to set the file ID (optional).

Rules for Using the DEFINE WORK FILE Keyword Parameters

Potential CAT or VOL parameters have to come first in the DEFINE WORK FILE string, as the end of the parameter value can easily be found; the DSN= parameter must be specified as the last keyword parameter.

In other words, if CAT or VOL parameters are specified, and the DSN keyword parameter is not specified, all data in the DEFINE WORK FILE parameter string behind the last keyword parameter is considered as file ID to be set.

For VSAM/SAM, NATVSE dynamically adds the following label information:

// DLBL xxyyyyz,'file-id',0,VSAM,CAT=catalog, +
   RECORDS=n1,RECSIZE=n2,DISP=(dsp1,dsp2)
// EXTENT ,volser                                                                        optional

where:

xx is the partition's SYSLOG ID, for example BG, F4, etc.
yyyy yyyy is the edited z/VSE two-byte hexadecimal task number (to allow Natural subtasks in the same partition).
z is the Natural work file number: "1" through "9" for files 1 to 9, "A" through "W" for files 10 to 32.
n1 is the value specified by the keyword subparameter BLOCKS of profile parameter WORK.
n2 is the value specified by the keyword subparameter BLKSIZE of profile parameter WORK.
dsp1, dsp2 is the value specified by the keyword subparameter DISP of profile parameter WORK.
catalog is the VSAM catalog which has to be set using a DEFINE WORK FILE statement.
volser is the volume serial number on which the file is allocated.

Note that the EXTENT card is only generated when volser has been set in a DEFINE WORK FILE statement in the Natural application.

For other disk file management systems, for example CA-DYNAM/D, NATVSE adds dynamically the following label information:

// DLBL xxyyyyz,'file-id',0
// EXTENTsysnnn,volser,,,1,n1                                     optional

where:

xx is the partition's SYSLOG ID, for example BG, F4, etc.
yyyy is the edited z/VSE two-byte hexadecimal task number (to allow Natural subtasks in the same partition).
z is the Natural work file number: 1 through 9 for files 1 to 9, A through W for files 10 to 32.
n1 is the value specified by the keyword subparameter BLOCKS of profile parameter WORK.
sysnnn is the value specified by the keyword subparameter SYSNR of profile parameter WORK.
volser is the volume serial number on which the file is allocated.

Note that the EXTENT card is only generated when volser has been set in a DEFINE WORK FILE statement in the Natural application. If n1 is zero, extent information (start track/block and number of tracks/blocks) is omitted.

For Natural as a server the file name setup has the format:

xyyyyyz

where:

xyyyyy is the server session number in hexadecimal format (edited) with the very first character forced alphabetic by translation of 0 through F into A to P.
z is the Natural work file number, as for normal Natural under z/VSE batch operation.

Files to be dynamically allocated must have a Natural file name of '*' set in keyword subparameter DEST='*' of profile parameter WORK or a statement definition of DEFINE WORK FILE '*' to enable Natural under z/VSE to create new file names as described above.

The file identification to be used also has to be set using a DEFINE WORK FILE statement.

The regular z/VSE restrictions for file IDs apply.

In a Natural multitasking or server environment, it is recommended to provide some unique information in the file ID to prevent "equal file" conditions.

Samples

Natural parameters:

WORK=((1-6),AM=1,DEST='*',BLOCKS=100),WORK=((2), DISP=(OLD,DELETE)),WORK=((6),BLOCKS=0)

Natural work file definition within application:

DEFINE WORK 1 'CAT=IJSYSUC,VSAM.SAM.FILE'
DEFINE WORK 2 'CAT=IJSYSCT,DSN=ANOTHER FILE'
DEFINE WORK 3 'CAT=IJSYSUC,VOL=DOSRES,ONE MORE FILE'
DEFINE WORK 4 '==.CATALOGED.FILE' 
DEFINE WORK 5 'VOL=POOL01,DSN=FILE WITH EXTENT INFO' 
DEFINE WORK 6 'VOL=DOSRES,ANY FILE' 

z/VSE labels generated:

// DLBL xxyyyy1,'VSAM.SAM.FILE',0,VSAM,CAT=IJSYSUC, +
   RECORDS=100,RECSIZE=4628,DISP=(NEW,KEEP)
// DLBL xxyyyy2,'ANOTHER FILE',0,VSAM,CAT=IJSYSCT,  + 
   RECORDS=100,RECSIZE=4628,DISP=(OLD,DELETE)
// DLBL xxyyyy3,'ONE NORE FILE',0,VSAM,CAT=IJSYSUC, + 
   RECORDS=100,RECSIZE=4628,DISP=(NEW,KEEP)
// EXTENT ,DOSRES
// DLBL xxyyyy4,'==.CATALOGED.FILE',0
// DLBL xxyyyy5,'FILE WITH EXTENT INFO',0
// EXTENT SYS005,POOL01,,,1,100
// DLBL xxyyyy6,'ANY FILE',0 
// EXTENT SYS006,DOSRES 

Top of page

Debugging Facilities for Natural under z/VSE

The Natural z/VSE batch mode interface contains some debugging facilities which can help you to track down problems.

These facilities are controlled by the UPSI settings in the JCL.

Additionally, the UPSI settings may also be specified as a Natural session parameter (UPSI=1XXXXXXX, for example). This is useful if UPSI settings in JCL have produced side effects in the sense that they have a different meaning for other programs such as for front-end Natural or for programs called by Natural.

There may be the following UPSI settings:

UPSI Setting Meaning
UPSI 1XXXXXXX Dump Flag
UPSI X1XXXXXX Trace Flag
UPSI XXX1XXXX Storage Freeze Flag
UPSI XXXXX1XX Session Abend Flag
UPSI XXXXXX1X Abend Exit Flag
UPSI XXXXXXX1 Formatted Dump-Only Flag

These settings are described below. In addition, a sample job is given to show you how to obtain documentation for debugging.

UPSI 1XXXXXXX - Dump Flag

When Natural encounters a problem, the corresponding job usually cancels without a dump, unless an abend actually occurred. When this UPSI flag is set, a dump is always created at the end of the job when an error occurs, that is, when the Natural session termination message is other than NAT9995.

UPSI X1XXXXXX - Trace Flag

When this flag is set, snapshots are taken of the register save area at some strategic points in Natural.

Note:
Depending on the product sample output, setting this flag can lead to large output.

On entry of all NATVSE service routines, the name of this routine and the general registers 0 to 15 (GRG) are displayed.

Note:
You can identify the caller from Register 14.

On exit of all NATVSE service routines, the name of this routine, the current general registers (GRG) and Registers 0 to 15 of the currently assigned save area (CSA) are displayed.

Notes:

  1. The contents of the CSA are returned to the caller of the service routine, except the Register 15 return code which is taken from the general registers.
  2. The contents of the HSA are returned to the caller, which means that this save area contains the return code in Register 15 if a return code was set at all.

Whenever the GRG registers are set, the debugging trace program tries to determine the name of the calling routine and the offset of the call from the beginning of the routine.

The SYSnnn number for the debugging trace print output is SYS040, as long as this SYSnnn number is assigned to a printer device; otherwise SYSLST is used. This is of particular interest if debugging trace output and other Natural print output are to be separated; to do so, assign SYS040 appropriately and supply a POWER * $$ LST statement for this logical print unit.

UPSI XXX1XXXX - Storage Freeze Flag

On normal or abnormal session termination, Natural, by default, releases all its resources including storage. Despite the setting of UPSI 1, a dump may be useless, because all relevant storage has already been released during Natural termination. When this flag is set, no GETVIS storage acquired earlier is ever released within this job; this applies to all external subroutine programs called by Natural including the Natural nucleus (if not linked to NATVSE) and RCA=ON subproducts.

Warning:
This flag should be handled carefully, because more partition GETVIS storage is used, but jobs may still cancel due to failed GETVIS requests if the operating system storage requests cannot be satisfied.

UPSI XXXXX1XX - Session Abend Flag

By default, a Natural session is cancelled if crucial errors have occurred (NAT9nnn termination messages except NAT9995 and NAT9987). When this flag is set, Natural does not cancel, but terminates "normally" just passing the Natural return code to the job control.

UPSI XXXXXX1X - Abend Exit Flag

This flag may be helpful in the case of recurrent abends.

In batch mode, Natural usually has a check abend exit for active programs (STXIT PC) to recover from program checks (NAT095n error messages). When DU=ON is specified, this exit creates a snap dump and passes control to Natural for a clean session termination.

When this flag is set, the Natural session runs without any abend exit for active programs, which means that all program checks are handled directly by the operating system.

If this flag is set, the dump flag, the storage freeze flag, the session abend flag and the formatted dump-only flag are ignored.

UPSI XXXXXXX1 - Formatted Dump-Only Flag

With DU=ON, the NATVSE abend exit routine creates a snap dump of the Natural session when a program check abend occurs (and the UPSI XXXXXX1X flag is not set).

Since in many cases the dynamic Natural session areas are relevant for debugging only, the dump of the static session areas can be suppressed by setting this UPSI flag.

Obtaining Documentation for Debugging

If a problem has to be analyzed, any information which might be relevant is important, in particular, the executed JCS and the corresponding console log.

The following sample job is intended to show you how to obtain comprehensive documentation:

// JOB sampljob
// OPTION LOG,PARTDUMP to see JCL on printer
/* Library Definitions: labels and LIBDEFs
...
/* ADARUN Parameter Input Definition
// ASSGN SYS000,SYSRDR
/* Natural Work File Definitions
// DLBL CMWKFnn,'...',... disk work file
// EXTENT SYSnnn,volser,,,nn,mm
// ASSGN SYSnnn,DISK,VOL=volser,SHR
// TLBL CMWKFnn,'...',... labelled tape work file
// ASSGN SYSnnn,cuu assignment to tape unit
/* Natural Print File Definitions
// ASSGN SYSnnn,cuu assignment to print UR unit
// DLBL CMPRTnn,'...',... print file on disk
// EXTENT SYSnnn,volser,,,nn,mm
// ASSGN SYSnnn,DISK,VOL=volser,SHR
// TLBL CMPRTnn,'...',... print file on labelled tape 
// ASSGN SYSnnn,cuu assignment to tape unit
/* Debugging Options
// ASSGN SYS040,SYSLST debugging trace unit
// UPSI 1xxx00xx flags as discussed above
// EXEC Natural,SIZE=...
... dynamic parameters
/* end of dynamic parameters
... ADARUN parameters
/* end of ADARUN parameters
... Natural input
/* end of Natural input
// EXEC LISTLOG print console messages
/& end of job

Top of page

NATVSE Attention Interrupts

The Natural z/VSE batch mode interface (NATVSE) supports attention interrupts via the console command MSG xx, where xx is the z/VSE partition ID a console operator can force on a NAT1016 attention interrupt event.

This special functionality is controlled by the Natural profile parameter ATTN.

Top of page