DEFINE WORK FILE

DEFINE WORK FILE work-file-number

operand1 [TYPE operand2]
TYPE operand2

[ATTRIBUTES  {operand3}...]

Note:
The elements shown in square brackets [...] are optional, however, at least one of them must be specified with this statement.

This document covers the following topics:

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statements: CLOSE WORK FILE | READ WORK FILE | WRITE WORK FILE

Belongs to Function Group: Control of Work Files / PC Files

Function

The statement DEFINE WORK FILE is used to assign a file name to a Natural work file number within a Natural application. This allows you to make or change work file assignments dynamically within a Natural session or overwrite work file assignments made at another level.

When this statement is executed and the specified work file is already open, the statement will implicitly close the work file.

All work files to be used during a session must be preassigned to an access method by means of keyword subparameter AM of profile parameter WORK or automatically by definition in the JCL.

Note:
For Unicode and code page support on mainframe platforms, see Work Files and Print Files in the Unicode and Code Page Support documentation.

Syntax Description

Operand Definition Table:

Operand Possible Structure Possible Formats Referencing Permitted Dynamic Definition
operand1 C S       A U                     yes no
operand2 C S       A U                     yes no
operand3 C S       A U                     yes no

Syntax Element Description:

Syntax Element Description
work-file-number
Work File Number:
Specifies the work file number.

The work file number is either:

  • a numeric constant in the value range 1:32 or

  • a numeric variable of type B/N/P/I defined with a CONST clause which assigns a value in range 1:32. Precision digits for type (N/P) are not allowed.

This is the number you use in a WRITE WORK FILE, READ WORK FILE or CLOSE WORK FILE statement.
operand1
Work File Name:
operand1 is the name of the work file.

As operand1 you can specify the name of the data set to be assigned to the work file number.

operand1 can be 1 to 253 characters long. You can specify either a logical or a physical data set name. The possible format depends on the operating system environment and the access method defined by keyword subparameter AM of profile parameter WORK. Some access methods do not support a work file name as operand1, for example, AM=COMP and AM=PC.

If operand1 is not specified, the value of operand1 is determined by taking the current name specified with the previously performed DEFINE WORK FILE statement for this work file number. If no previous DEFINE WORK FILE statement was performed, the name is taken from the Natural parameter module.

Note:
If operand1 is not specified, the behavior of Natural for Mainframes and Natural for Windows/Linux is different.

Information on operating-system- or TP-monitor-dependent work file naming conventions is included in the following sections:

TYPE operand2
TYPE Clause:

operand2 specifies the type of work file.

The value of operand2 is handled in a case insensitive way and must be enclosed in quotes or provided in an alphanumeric variable.

UNFORMATTED

A completely unformatted file. No formatting information is written (neither for fields nor for records).

UNFORMATTED treats a work file as a byte-stream with no record boundaries. Note that type UNFORMATTED will be rejected by Entire Connection.

Format: UNFORMATTED
FORMATTED

FORMATTED defines a regular record-oriented work file, which is subject to the same handling as in previous Natural versions.

ATTRIBUTES {operand3}...
ATTRIBUTES Clause:

This clause makes sense only in Natural for Open Systems; in Natural for Mainframes it is ignored.

Examples: 

DEFINE WORK FILE 17 #FILE TYPE 'UNFORMATTED'
#TYPE := 'FORMATTED' 
DEFINE WORK FILE 18 #FILE TYPE #TYPE

Work File Name under z/OS Batch, TSO and Server

The following topics are covered:

Work File Name - operand1

Under z/OS, for a work-file number that is defined with the access method AM=STD, operand1 can be:

Logical Data Set Names

Example:

DEFINE WORK FILE 21 'SYSOUT1'

The specified data set SYSOUT1 must have been allocated before the DEFINE WORK FILE statement is executed.

The allocation can be done via JCL, CLIST (TCO) or dynamic allocation (SVC 99). For dynamic allocation you can use the application programming interface USR2021N, which is located in library SYSEXT.

The data set name specified in the DEFINE WORK FILE statement overrides the name specified with keyword subparameter DEST of profile parameter WORK.

Optionally, the data set name may be prefixed by DDN= to indicate that it is a DD name. For example: 

DEFINE WORK FILE 22 'DDN=MYWORK'
Physical Data Set Names

Example:

DEFINE WORK FILE 23 'TEST.WORK.FILE'

The specified data set must exist in cataloged form. When the DEFINE WORK FILE statement is executed, the data set is allocated dynamically by SVC 99 with the current DD name and option DISP=SHR.

If the data set name is 8 characters or shorter and does not contain a period (.), it might be misinterpreted as a DD name. To avoid this, prefix the name with DSN=. For example: 

DEFINE WORK FILE 22 'DSN=WORKXYZ'

If the data set is a PDS member, you specify the PDS member name (1 to 8 characters) in parentheses after the data set name (1 to 44 characters). For example: 

DEFINE WORK FILE 4 'TEST.WORK.PDS(TEST1)'

If the specified member does not exist, a new member of that name will be created.

HFS Files

Example:

DEFINE WORK FILE 14 '/u/nat/rec/test.txt'

The specified path name must exist. When the DEFINE WORK FILE statement is executed, the HFS file is allocated dynamically. If the specified member does not exist, a new member of that name will be created.

For the dynamic allocation of the data set, the following z/OS path options are used: 

PATHOPTS=(OCREAT,OTRUNC,ORDWR)
PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)
FILEDATA=TEXT

When an HFS file is closed, it is automatically de-allocated by z/OS (regardless of the setting of keyword subparameter FREE of profile parameter WORK).

To read an HFS file, you have to use the application programming interface USR2021N (dynamic data set allocation) instead of the DEFINE WORK FILE statement, because of the OTRUNC option. This option resets the HFS file at the first read access, which results in an empty file.

JES Spool File Class

To create a JES spool data set, you specify SYSOUT=x (where x is the desired spool file class). For the default spool file class, you specify SYSOUT=*.

Examples:

DEFINE WORK FILE 10 'SYSOUT=A'
DEFINE WORK FILE 12 'SYSOUT=*'

To specify additional parameters for the dynamic allocation, use the application programming interface USR2021N (dynamic data set allocation) in the library SYSEXT instead of the DEFINE WORK FILE statement.

NULLFILE

To indicate a dummy data set.

Allocation and De-Allocation of Data Sets

When the DEFINE WORK FILE statement is executed and a physical data set name, HFS file, spool file class or dummy data set has been specified, the corresponding data set is allocated automatically. If the logical file is already open, it will be closed automatically, except when the keyword subparameter CLOSE=FIN of profile parameter WORK has been specified, in which case an error will be issued. Moreover, an existing data set allocated with the same current DD name is automatically de-allocated before the new data set is allocated. To avoid unnecessary overhead by unsuccessful premature opening of work files not yet allocated at the start of the program, work files should be defined with keyword subparameter OPEN=ACC (open at first access) of profile parameter WORK.

In the case of an HFS file, or a work file defined with keyword subparameter FREE=ON of profile parameter WORK, the work file is automatically de-allocated as soon as it has been closed.

As an alternative for the dynamic allocation and de-allocation of data sets, the application programming interface USR2021N (dynamic data set allocation) in the library SYSEXT is provided. This API also allows you to specify additional parameters for dynamic allocation.

Work Files in Server Environments

In server environments, errors may occur if multiple Natural sessions attempt to allocate or open a data set with the same DD name. To avoid this, you either specify the work file with keyword subparameter DEST=* of profile parameter WORK, or you specify DEFINE WORK FILE '*' in your program before the actual DEFINE WORK FILE statement. Natural then generates a unique DD name at the physical data set allocation when the first DEFINE WORK FILE statement for that work file is executed.

All work files whose DD names begin with CM are shared by all sessions in a server environment. A shared work file opened for output by the first session is physically closed when the server is terminated. A shared work file opened for input is physically closed when the last session closes it, that is, when it receives an end-of-file condition. When a work file is read concurrently, one file record is supplied to one READ WORK FILE statement only.

Work File Name under CICS

For a work-file number defined with access method AM=CICS, operand1 can be a transient data or temporary storage queue name (1 to 8 characters), depending on keyword subparameter TYPE of profile parameter WORK for the work file. For TYPE=TD, only the first 4 characters of operand1 are honored and the transient data destination must be predefined to CICS.

For further information on work files, see Natural Print and Work Files under CICS in the TP Monitor Interfaces documentation.

Work File Name under Com-plete/SMARTS

Under Com-plete with access method AM=SMARTS, PFS files are available. Any work file name can be assigned, even if it has not been defined to Natural. For example: 

DEFINE WORK (14) '/nat/path/workfile'
DEFINE WORK (14) 'workfile'

It depends on the MOUNT_FS parameter of SMARTS whether the file is located on a SMARTS portable file system or on the native file system. The first element of the path (/nat/) determines the target file system.

If the string does not start with a slash (/), the path of the file is taken from the environment variable $NAT_WORK_ROOT.

The specified path name must exist. When the DEFINE WORK FILE statement is executed, the file is allocated dynamically. If the specified member does not exist, a new member of that name will be created.