Version 4.2.6 for Mainframes
 —  Parameter Reference  —

WORK - Work-File Assignments

This Natural profile parameter allows you to define the maximum number of work files to be used during the session. Within a session, up to 32 logical work files (numbered 1 to 32) can be used.

WORK corresponds to the NTWORK macro in the parameter module NATPARM. To provide different work file definitions, WORK or NTWORK can be specified multiple times.

Possible settings   See Keyword Subparameters below.
Default setting   See below. Depending on the access method and the environment, there may be different default settings.
Dynamic specification yes The parameter WORK can only be specified dynamically. In NATPARM, the macro NTWORK must be used.
Specification within session no  

The software components for accessing work files in different environments are called access methods. For the duration of a Natural session, each logical work file can be assigned to one access method only. The access method for a work file is determined by the keyword subparameter AM (see below).

In z/OS under TSO and in batch mode, work files need not be predefined in the JCL. Provided they are defined by subparameter AM=STD, they can be allocated dynamically during the session by a Natural program using the DEFINE WORK FILE statement or the application programming interface USR2021, which is located in library SYSEXT.

This document covers the following topics:

See also Print and Work File Handling with External Datasets in a Server Environment in the Operations documentation).


WORK Parameter Syntax

With the WORK parameter, you first specify one or more logical work file numbers, and then several keyword subparameters, which define the characteristics for these work files:

WORK=((work-file-numbers),keyword-subparameters,...)

work-file-numbers

The file numbers must be specified first and enclosed in parentheses. The numbers can be from 1 to 31. They can be specified in any sequence. Multiple numbers must be separated from one another by commas or blanks. To specify a range of numbers, you can use a hyphen (-).

keyword-subparameters

The various types of keyword subparameters are described below.

For work files with different characteristics, you specify different WORK parameters. If any previous definition (or default) for the same work file exists, only the values for the specified keyword subparameters are overwritten, all other values remain unchanged.

Examples:

WORK=((2,12,18),AM=STD,DEST='WORK**') 
WORK=((1,3,6-11,15),AM=COMP,OPEN=INITOBJ,CLOSE=CMD)

Top of page

NTWORK Macro Syntax

With an NTWORK macro, you first specify one or more logical work file numbers, and then several keyword subparameters, which define the characteristics for these work files:

NTWORK (work-file-numbers),keyword-subparameters,...

work-file-numbers

The file numbers must be specified first and enclosed in parentheses. The numbers can be from 1 to 31. They can be specified in any sequence. Multiple numbers must be separated from one another by commas. To specify a range of numbers, you can use a hyphen (-).

keyword-subparameters

The various types of keyword subparameters are described below.

For work files with different characteristics, you specify different NTWORK macros. If any previous definition (or default) for the same work file exists, only the values for the specified keyword subparameters are overwritten, all other values remain unchanged.

Examples:

NTWORK (2,12,18),AM=STD,DEST='WORK**' 
NTWORK (1,3,6-11,15),AM=COMP,OPEN=INITOBJ,CLOSE=CMD

Top of page

Keyword Subparameters for All Environments

The following keyword subparameters are available: AM | DEST | OPEN | CLOSE | LRECL | TRUNC | PAD | PADCHRO | PADCHRI

AM - Type of Access Method

AM=xxx specifies the type of access method to be used.

For an online session, all work files to be used have to be assigned to a specific access method.

For a batch session, any work files not assigned to a specific access method will be automatically detected and assigned by the standard batch access method (AM=STD), provided that they have been predefined in the JCL. See also FAMSTD - Overwriting of Print and Work File Access Method Assignments.

STD Standard sequential files (batch, TSO, TIAM, CMS OS simulation).
COMP Com-plete work files.
SMARTS SMARTS work files. Work file on a SMARTS Portable File System (PFS).
CICS CICS transient data or temporary storage.
CMS CMS Disk and SFS files.
PC Entire Connection.
USER Third-party vendor work-file interface.
OFF Unassigned. No automatic assignments if FAMSTD=OFF is set.
0 Unassigned. Automatic assignments if FAMSTD=OFF is set. This is the default value.

Note:
WORK=OFF is equivalent to: WORK=((1-32)),AM=OFF). It does not affect any of the other keyword subparameter specifications.

DEST - External Dataset Name

DEST=name specifies the external dataset name (1 - 8 characters).

This corresponds to the operand1 of the DEFINE WORK FILE statement (and can be overwritten by a DEFINE WORK FILE specification).

The meaning of this keyword subparameter depends on the access method.

AM=STD

DEST is the logical dataset name (DDNAME, LINK name, DTF name).

If the destination is to be for multiple files, two asterisks (**) have to be specified for the file number. These will be replaced by the corresponding logical file number for each work file. A DEST value including two asterisks must be enclosed in apostrophes when using it as a dynamic parameter.

The default value is DEST='CMWKF**' for IBM and DEST='W**' for SIEMENS environments.

Under z/VSE, only 7-character names are supported.

AM=CICS

There is no default value for work files under CICS. Here, the DEST subparameter is mandatory; that is, CICS work files defined without a valid DEST specification are ignored.

The Natural CICS interface also supports a variable (see TERMVAR parameter in the NCIPARM generation macro; &TID is the default) as part of the DEST value which, when being specified, is replaced by the actual CICS terminal ID; see also Natural Print and Work Files under CICS in the TP Monitor Interfaces documentation).

AM=CMS For usage of DEST under CMS, refer to Natural under VM/CMS in the Operations documentation).
AM=COMP DEST defines the name of the Com-plete SD-file. The length is restricted to a maximum of 8 characters. If the file is defined with TYPE=TID, the DEST value is appended by the Com-plete stack level. The length is restricted to a maximum of 7 characters accordingly. SD-file names starting with '&&' are treated as temporary files which are deleted automatically after Natural termination.

OPEN - Time of File Opening

OPEN=xxx determines when the file is to be opened:

Value The file is opened
INIT for output at session initialization.
OBF according to the default OPEN value for the different environments (Batch, CICS, Com-plete, TSO).
OBJ when the execution of the first object which accesses the file starts. This is the default value.
INITOBF for output at session initialization. Any subsequent re-opening of the file sets the default OPEN value for the different environments (Batch, CICS, Com-plete, TSO).
OBJ1 when the execution of the first object on level 1 which accesses the file starts. Otherwise, it is opened when it is first accessed.
ACC when it is first accessed by a statement.
INITOBJ for output at session initialization. Any subsequent re-opening of the file will be performed when the execution of the first object which accesses the file starts.
INITOBJ1 when the execution of the first object on level 1 which accesses the file starts. Otherwise, it is opened when it is first accessed.
INITACC for output at session initialization. Any subsequent re-opening of the file will be performed when it is first accessed by a statement.

CLOSE - Time of File Closure

CLOSE=xxx determines when the file is to be closed:

Value The file is closed
OBJ either when processing of the object in which it was first accessed is finished, or when command mode, NEXT mode or MAINMENU is reached.
CMD when command mode, NEXT mode or MAINMENU is reached. This is the default value.
FIN at session end. With CLOSE=FIN, a DEFINE WORK FILE statement causes an error if the work file was opened already. A CLOSE WORK FILE statement for the work file is ignored. When the end-of-file condition occurs during the READ WORK FILE statement, Natural closes the work file immediately.
USER

This value specifies that a work file is closed only if the file is open and one of the following conditions is true:

  • a CLOSE WORK FILE statement is issued,

  • a DEFINE WORK FILE statement is issued,

  • at session termination.

LRECL - Default and Maximum Record Length of Dataset

LRECL=nnn determines the record length (in bytes) of the dataset.

Possible values: 0 or 5 - 32767
Default value: 0

This subparameter is used particularly to check for truncation and padding. For more information on AM=STD, see the keyword subparameter LRECL in the section WORK Keyword Subparameters for AM=STD in All Environments below.

TRUNC - Truncation of Output Records

TRUNC=xxx determines whether the output records are truncated or not:

ON Output records that are longer than the record length (LRECL) of the dataset will be truncated.
OFF Error NAT1512 will be issued if an output record is longer than the dataset record length. This is the default value.

PAD - Padding of Output Records

PAD=xxx determines whether the output records are padded or not (applies only to datasets of fixed record length):

ON Output records that are shorter than the record length (LRECL) of the dataset will be padded with padding characters defined by keyword subparameter PADCHRO. This is the default value.
OFF Error NAT1510 will be issued if an output record is shorter than the dataset record length.

PADCHRO - Padding Character of Output Records

This subparameter defines the character which is used for padding of output records if PAD=ON is defined for the work file.

Possible values:

'x'

x'xx'

(one character x within single quotes)

(one hex character xx)

Default value: x'00'  

PADCHRI - Padding Character of Input Records

This subparameter defines the character which is used for padding of input records.

Possible values:

'x'

x'xx'

(one character x within single quotes)

(one hex character xx)

Default value: x'40' (blank)

Top of page

Keyword Subparameters for AM=STD in All Environments

The following keyword subparameters are available: RECFM | BLKSIZE | LRECL

RECFM - Default Record Format of Dataset

RECFM=xxxx determines the default record format of the dataset.

The following formats are supported:

F Fixed
V Variable
U Undefined
B Blocked
S Spanned
A ASA
M Machine control characters

The following values and also combinations of values are possible:

Possible value: F, FA, FM, FB, FBA, FBM, V, VA, VM, VB, VBA, VBM, VBS, VBSA, VBSM, U, UA, UM
Default value: RECFM=VB (variable blocked).

The RECFM specification only applies if no record format is predefined in the JCL or (z/OS only) in the dataset DCB.

BLKSIZE - Default Block Size of Dataset

BLKSIZE=nnnnn determines the default block size (in bytes) of the dataset.

Possible values: 0 or 8 - 32767
Default value: 4628

The BLKSIZE specification only applies if no block size is predefined in the JCL or (z/OS only) in the dataset DCB.

LRECL - Default and Maximum Record Length of Dataset

LRECL=nnn determines the record length (in bytes) of the dataset.

Possible values: 0 or 5 - 32767
Default value: 0

This subparameter is used particularly to check for truncation and padding.

The LRECL specification only applies if no record length is predefined in the JCL or (z/OS only) in the dataset DCB.

Top of page

Keyword Subparameters for AM=STD in z/OS Environments

The following keyword subparameters are available: REREAD | FREE | BUFNO | DISP | VMAX

REREAD - Closing of Tape File Datasets

REREAD=xxx sets the REREAD option for the closing of the tape file:

ON The REREAD option is set for the CLOSE SVC. This causes the volume to be repositioned to reprocess the dataset. This is the default value.
OFF The REREAD option is not set for the CLOSE SVC.

FREE - Dataset De-allocation at File Closure

FREE=xxx determines whether the dataset is de-allocated when the file is closed:

ON The FREE option is set for the CLOSE SVC, which means that the dataset is de-allocated when it is closed (and not at step termination).
OFF The FREE option is not set for the CLOSE SVC. This is the default value.

BUFNO - Default Number of z/OS I/O Buffers of Dataset

BUFNO=nnn defines the default number of z/OS I/O buffers of the dataset.

Possible values 0 - 255
Default value 0

In this case, z/OS allocates five I/O buffers per default.

The number of I/O buffers can improve the performance of work file access dramatically. Note that the storage for I/O buffers is allocated below the 16 MB line.

The BUFNO specification applies only if the BUFNO parameter is not specified in the JCL for the dataset.

DISP - Open Work File for Modification

DISP=xxx determines that the work file is opened for modification.

This corresponds to the JCL DD statement subparameter DISP=MOD.

MOD New records are added at the end of the file.
NOMOD The work file is rewritten from the start. This is the default value.

VMAX - Control LRECL for Variable Record Format

VMAX=xxx controls the LRECL setting for an output file with variable record format (RECFM=V).

ON Providing a nonzero BLKSIZE value exists for the file, VMAX=ON sets LRECL=BLKSIZE-4 for variable record format, regardless of the LRECL setting in the DCB or the LRECL subparameter.
NAT LRECL is set to the length +4 of the largest record in the application program if this value is less than LRECL in the DCB for the dataset.
OFF LRECL from the DCB for the dataset is used. This is the default value.

Top of page

Keyword Subparameters for AM=STD in z/VSE Environments

The following keyword subparameters are available: SYSNR | LABEL | REWIND | BLOCKS | DISP

SYSNR - Logical VSE SYS Number

SYSNR=nn determines the logical VSE SYS number.

Possible values: 1 - 99
Default value: By default, the SYS number is identical to the work file number.

LABEL - Tape Label Processing

LABEL=xxx d determines the tape label processing:

ON The tape is in standard label format. This is the default value.
OFF The tape is unlabeled with front tape mark.
NOTM The tape is unlabeled without front tape mark.

REWIND - Action at File Closure

REWIND=xxx determines the action to be taken when a tape file is closed:

ON The tape is rewound when the file is closed. This is the default value.
OFF The tape is not rewound when the file is closed.
UNLOAD The tape is unloaded when the file is closed.

BLOCKS - Number of Storage Blocks

BLOCKS=nnnn specifies the number of file blocks or file tracks to be allocated for a dynamic NATVSE work file.

Possible values: 1 - 9999
Default value: 20

See NATVSE Dynamic Work File Allocation (DYNALLOC) Support in the Operations documentation.

DISP - Work File Disposition for VSAM/SAM

DISP=(xxx,xxx) specifies the disposition of a dynamic NATVSE work file controlled by VSAM/SAM.

Possible value pairs are:

(NEW,KEEP) File is to be reset at OPEN and to be kept at CLOSE. This is the default value.
(NEW,DELETE) File is to be reset at OPEN and to be made inaccessible at CLOSE.
(OLD,DELETE) File is not to be reset at OPEN and to be made inaccessible at CLOSE.
(OLD,KEEP) File is not to be reset at OPEN and to be kept at CLOSE.

See NATVSE Dynamic Work File Allocation (DYNALLOC) Support in the Operations documentation.

Top of page

Keyword Subparameters for AM=STD in BS2000/OSD Environments

The following keyword subparameter is available: DISP

DISP - File Open Mode

DISP=xxx determines the open mode of the file:

EXT The open mode is set to EXTEND.
NOEXT The open mode is set to the default value OUTPUT. This is the default value.

Top of page

Keyword Subparameters for AM=CICS

The following keyword subparameters are available: TYPE | DISP

TYPE - Type of CICS Storage Medium

TYPE=xxxx specifies the type of CICS storage medium to be used:

MAIN Temporary main storage.
AUX Temporary auxiliary storage.
TD Transient data.

The default value used depends on the DEST keyword subparameter setting. If the DEST subparameter value matches a valid CICS transient data queue, the TYPE subparameter defaults to TD, otherwise MAIN will be taken as the default value.

DISP - CICS Temporary Storage Queue Disposition

DISP=(xxx,xxx) specifies the CICS temporary storage queue disposition.

Possible value pairs are:

(NEW,KEEP) The storage queue is deleted when the file is opened. This is the default value.
(NEW,DELETE) The storage queue is deleted when the file is opened and when it is closed.
(OLD,DELETE) The storage queue is deleted when the file is closed.
(OLD,KEEP) The storage queue is not deleted.

Note:
The DISP specification does not apply to CICS extra-partition transient data queues.

Top of page

Keyword Subparameters for AM=COMP

The following keyword subparameters are available: TYPE | BLOCKS | BLKSIZE

TYPE - Type of Storage Access

TYPE=xxx specifies the type of storage access to be used:

SHR Shared access, that is, the work file is accessible by all users.
TID The work file is only available to the current Com-plete terminal ID.
DYN The work file is only available to the current terminal stack level.

BLOCKS - Number of Storage Blocks

BLOCKS=nnnn specifies the number of storage blocks to be allocated.

Possible values: 1 - 9999
Default value: 20

BLKSIZE - Size of Storage Blocks

BLKSIZE=nnnn determines the default block size (in bytes) of the dataset.

Possible values: 0, or 8 - 32767
Default value: 4628

Top of page

Keyword Subparameters for AM=SMARTS

The following keyword subparameters are available: DEST | TYPE | DISP

DEST - Work File Name

DEST=name specifies the workfile name (1-8 characters).

Since the DEST clause is restricted to an 8 character maximum, it is useless to define a file with absolute PFS path specification.

The name specified in the DEST clause is relative to the workfile root directory. The work file root directory is specified with the environment variable NAT_WORK_ROOT.

To specify a file with absolute path definition, the DEFINE WORK FILE statement must be used.

TYPE - Type of Storage Access

TYPE=xxx specifies the type of storage access to be used. Possible values are:

BIN Each line is written to the work file without terminating end-of-line character. This is the default value.
TXT Each line is written to the work file with a terminating end-of-line character (x'15').

DISP - File Open Mode

DISP=(Disp1,Disp2,Disp3) specifies the mode of the work file. Possible values are:

Disp1=xxx Specifies whether an existing file should be deleted or new data should be appended to the file.
NEW An existing file will be deleted if the file is opened for writing. This is the default value.
OLD or MOD New data written are appended at the end of the file.
Disp2=xxx Specifies whether a file should be kept or removed after access.
KEEP Permanent file that will be kept after close. This is the default value.
DELETE Temporary file that will be removed after close.
Disp3=xxx Specifies whether a user has exclusive access to the file or not.
SHR Shared access, that is, the work file is accessible by all users. This is the default value.
OWN Exclusive access, the work file is accessible to the current Comp-lete user ID. Files with exclusive access are located in an additional directory which has the name of the current user ID.

Top of page