DEFINE WORK FILE

#### Search Results

Search

# 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:

- Function

- Syntax Description

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

- Work File Name under CICS

- Work File Name under Com-plete/SMARTS

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: Work File Name under z/OS Batch, TSO and Server Work File Name under CICS Work File Name under Com-plete/SMARTS
`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

- Allocation and De-Allocation of Data Sets

- Work Files in Server Environments

### Work File Name - operand1

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

- a logical data set name (DD name, 1 to 8 characters);

- a physical data set name of a cataloged data set (1 to 44 characters) or a physical data set member name;

- a path name and member name of an HFS file (1 to 253 characters) in an MVS Linux Services environment;

- a JES spool file class;

- `NULLFILE`.

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.

### On this page

- Function
- Syntax Description
- Work File Name under z/OS Batch, TSO and Server
- Work File Name under CICS
- Work File Name under Com-plete/SMARTS