WRITE-FILE

#### Search Results

Search

# WRITE-FILE

File | 204
Op-Sys | z/OS, z/VSE, BS2000 Note Support for z/VSE is deprecated. Support for BS2000 is also deprecated, except in conjunction with the ESM adapter. Features that are z/VSE and BS2000 specific will be removed from future releases.
Statement | `PROCESS`
Task | This view makes it possible to write data to an operating system file. Support of library systems such as CA-Panvalet, CA-Librarian, LMS is provided. See also WRITE-FILE Programming Notes at the bottom of this view description.

## Common Fields for all Operating Systems

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`ERROR-CODE` | N3 |  |  |
`ERROR-TEXT` | A58 |  |  |
`NODE` | N5 |  | D |
`NODE-NAME` | A16 |  | D |
`SYSTEM-MESSAGE-CODE` | A10 |  |  |
`DISP` | A3 |  | D |
`DSNAME` | A54 |  | D | Required.
`FUNCTION` | A8 |  | D |
`IDENTIFIER` | A8 |  | D | Required for multiple parallel `WRITE-FILE` calls.
`RECORD` | A253 |  | D |
`RECORD-LENGTH` | N5 |  | D |
`SEGMENT-LENGTH` | N3 |  | D |
`SEGMENT-NUMBER` | N5 |  | D |
`UPDATE-INPLACE` | A3 |  | D |

## Additional Fields Supported for z/OS

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`BLKSIZE` | B2 |  | D | Required for tape datasets with no standard label.
`BLOCK-TTR` | B3 |  | D |
`BLOCK-TOKEN` | B4 |  | D |
`GENERATION` | N9 |  | D |
`KEY` | A253 |  | D |
`LRECL` | B2 |  | D | Required for tape datasets with no standard label.
`MEMBER` | A10 |  | D |
`PRODUCT-OPTIONS` | A80 |  | D | When `PRODUCT=L`.
`PASSWORD` | A8 |  | D |
`PRODUCT` | A1 |  | D |
`RECFM` | A2 |  | D | Required for tape datasets with no standard label.
`REPLACE` | A3 |  | D |
`STATS` | A3 |  | D |
`TAPE-UNLOAD` | A3 |  | D |
`USER-DATA` | A120 |  | D | When `FUNCTION=CLOSE`.
`USER-DATA-HEX` | B120 |  | D | When `FUNCTION=CLOSE`
`USER-DATA-LENGTH` | N3 |  | D | When `FUNCTION=CLOSE`.
`VOLSER` | A6 |  | D | Required only if dataset is not cataloged.

## Additional Fields Supported for z/VSE

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`BLKSIZE` | B2 |  | D |
`INLINE-DATA` | A3 |  | D |
`LRECL` | B2 |  | D | Required if `RECFM=F`.
`LIBRARY` | A8 |  | D |
`MEMBER` | A10 |  | D |
`MEMBER-TYPE` | A8 |  | D |
`MSHP` | A3 |  | D |
`RECFM` | A2 |  | D | Default is `F`.
`REPLACE` | A3 |  | D |
`SUB-LIBRARY` | A8 |  | D |
`VOLSER` | A6 |  | D | Required.
`VSAM-CATALOG` | A8 |  | D |

## Additional Fields Supported for BS2000

Dictionary Field Name | F/L | Mu | DE | Remarks
--- | --- | --- | --- | ---
`SYSTEM-CODE` | B2 |  |  |
`DUPLICATE-KEY` | A3 |  | D | ISAM only.
`ELEMENT` | A64 |  | D |
`ELEMENT-PASSWORD` | A8 |  | D |
`ELEMENT-RECORD-TYPE` | N3 |  | D |
`ELEMENT-TYPE` | A8 |  | D |
`ELEMENT-USER-DATE` | A14 |  | D |
`ELEMENT-USER-TIME` | A8 |  | D |
`ELEMENT-VERSION` | A24 |  | D |
`EXPIRATION-DATE` | A5 |  | D |
`EXPIRATION-DATX` | D |  | D |
`KEY` | A253 |  | D |
`LMS-RESET-FLAG` | A3 |  |  |
`PAD` | N2 |  | D | ISAM only.
`PASSWORD` | A8 |  | D |
`PRODUCT` | A1 |  | D |
`RECORD-NUMBER` | N9 |  | D |
`TAPE-UNLOAD` | A3 |  | D |

## Relevant Error Codes

Code | Text | z/OS | z/VSE | BS2000
--- | --- | --- | --- | ---
530 | Access denied by Security Facility. | X |  | X
531 | Password missing or incorrect. |  |  | X
541 | Member generation not found in directory. | X |  |
542 | GENERATION not valid for this library. | X |  |
551 | Member not specified. |  |  | X
553 | I-O error in directory. | X |  |
556 | File is in use. | X |  | X
557 | File held by linkage editor. | X |  |
558 | No space in directory. | X |  |
559 | Stow error. | X |  |
560 | Segment length greater than 253. | X | X | X
565 | Syntax error in dataset name. |  |  | X
590 | End-of-data reached during `UPDATE-INPLACE`. | X |  | X
591 | Member not found for `UPDATE-INPLACE`. | X |  |
592 | Record length error for variable `UPDATE-INPLACE`. | X |  | X
608 | ISITMGD failed with RC :1: and reason :2:. | X |  |
673 | Access error due to `FILETABLE=STATIC`. |  | X |
674 | VTOC error reading format-3 labels. |  | X |
675 | :1: not supported. |  | X |
676 | Not first volume of multi-volume file. |  | X |
678 | Member already exists. | X | X | X
692 | You are not permitted to access member. |  |  | X
697 | `LIBRARY/SUB-LIBRARY` not found. |  | X |
698 | Internal Librarian error. |  | X |
699 | Not enough main storage available. |  |  | X
700 | Invalid value specified (`DSORG/RECFM/TYPE`). |  |  | X
701 | `DSNAME` missing. |  |  | X
722 | Requested dataset not found. |  |  | X
733 | User ID does not exist. |  |  | X
737 | No more index space for inserting record. |  |  | X
798 | Task was not started under TSOS. |  |  | X
799 | Entire System Server internal error. |  |  | X
854 | Permanent I/O error. |  |  | X
856 | Operator unable to mount volume. |  |  | X
860 | Member is under MSHP control/bypass. |  | X |
861 | Member contains SYSIPT data. |  | X |
870 | `RECORD` field not in search buffer. | X | X | X
871 | `MEMBER` not specified. | X | X |
872 | Record format not supported. | X | X | X
873 | Record length missing. | X | X | X
874 | `RECORD-LENGTH` > `LRECL`. | X | X | X
875 | Position of data field > `RECORD-LENGTH`. | X | X | X
877 | VSAM (`SHOWCAT`) processing error |  | X |
881 | Error occurred while opening file. |  |  | X
882 | Error occurred while closing file. |  |  | X
883 | Dataset is full. | X | X | X
889 | Permanent I/O error while writing dataset. | X |  | X
899 | Permanent I/O error while reading dataset. | X |  | X
901 | Dynamic allocation failed. | X | X |
981 | Invalid value specified (`BLKCTRL/BLKSIZE/LRECL`). |  |  | X
982 | Error during use of ISAM key. |  |  | X
983 | `UPDATE-INPLACE` not supported by LMS. |  |  | X
985 | Access to tape file not allowed. |  |  | X
991 | Unknown product. | X |  | X
993 | Open error. | X |  | X
997 | File not PDS/Sequential. | X |  |
998 | Member not found. | X | X | X

## Field Descriptions

Field Name | Type/Length | Operating System
--- | --- | ---
`BLKSIZE` | (B2) | z/OS, z/VSE

Block size for dataset.

z/OS: | Required only for tape datasets that have no standard label.

Field Name | Type/Length | Operating System
--- | --- | ---
BLOCK-TTR | (B3) | z/OS

Track value at which to start writing.

Field Name | Type/Length | Operating System
--- | --- | ---
BLOCK-TOKEN | (B4) | z/OS

Token value at which to start writing.

For a large format sequential data set, the token is in the format `TTTR` where `TTT` is the relative track address and `R` the number of the block on that track.

Field Name | Type/Length | Operating System
--- | --- | ---
DISP | (A3) | z/OS, z/VSE, BS2000

Disposition of dataset or file. Possible values:

z/OS:

Value | Explanation
--- | ---
`MOD` | Add records to the end of the sequential dataset.
`OLD` | Overwrite existing dataset.

BS2000:

Value | Explanation
--- | ---
`MOD` | Add records to the end of the sequential file.
`NEW` | Create new file.
`STR` | Only for ISAM files: replace or add records identified by value in `KEY`.

z/VSE ((VSAM (SAM ESDS) only):

Value | Explanation
--- | ---
`MOD` | Add records at the end of the dataset or file.
`NEW` | Overwrite existing file contents.
`OLD` | Same as `MOD`.

Field Name | Type/Length | Operating System
--- | --- | ---
`DSNAME` | (A54) | z/OS, z/VSE, BS2000

Fully qualified dataset name. For BS2000, fully qualified file name. Specify `&TEMP.name` here to select a temporary dataset or file as specified in the Entire System Server startup parameter module. These temporary datasets or files are freed when you log off (not supported in BS2000).

Field Name | Type/Length | Operating System
--- | --- | ---
`DUPLICATE-KEY` | (A3) | BS2000

For ISAM only:

Value | Explanation
--- | ---
`NO` | Default. No duplicate keys allowed.
`YES` | Duplicate keys allowed.

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT` | (A64) | BS2000

Name of the LMS element to be written.

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-PASSWORD` | (A8) | BS2000

Password for protected LMS element (LMS V2 or above).

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-RECORD-TYPE` | (N3) | BS2000

Record type (LMS only).

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-TYPE` | (A8) | BS2000

Type of LMS element to be written.

Types `C` and `L` are currently not supported.

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-USER-DATE` | (A14) | BS2000

Is written as element information into LMS library. Format: `YYYY-MM-DDaaaa`, where aaaa can be any 4-character string.

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-USER-TIME` | (A8) | BS2000

Is written as element information into LMS library. Format: `HH`:`MM`:SS.

Field Name | Type/Length | Operating System
--- | --- | ---
`ELEMENT-VERSION` | (A24) | BS2000

Version of LMS element to be written.

Field Name | Type/Length | Operating System
--- | --- | ---
`EXPIRATION-DATE` | (A5) | BS2000

The file's new expiration date in format `YYDDD`.

Field Name | Type/Length | Operating System
--- | --- | ---
`EXPIRATION-DATX` | (D) | BS2000

Expiration date in Natural format.

Field Name | Type/Length | Operating System
--- | --- | ---
`FUNCTION` | (A8) | z/OS, z/VSE, BS2000

Function to be performed. Possible options:

Option | Explanation
--- | ---
blank | Default. Write a record.
`CLOSE` | All records have been written. Specify this function for the last `WRITE-FILE` request.
`OPEN` | (z/OS) Open a new file. This `OPEN` can be omitted for simple `WRITE-FILE` loops, but is recommended for complex, nested `WRITE-FILE` programs (for example, writing in parallel to several files).

Field Name | Type/Length | Operating System
--- | --- | ---
`GENERATION` | (N9) | z/OS

Generation number of member (only valid for PDSE version 2 with MAXGENS > 0).

Field Name | Type/Length | Operating System
--- | --- | ---
`IDENTIFIER` | (A8) | z/OS, z/VSE, BS2000

Required if multiple `WRITE-FILE` calls are executing in parallel. All requests for the same file must have the same identifier.

Field Name | Type/Length | Operating System
--- | --- | ---
`INLINE-DATA` | (A3) | z/VSE

For cataloged procedures: (see `LIBR,DATA=YES`). Possible values:

Value | Explanation
--- | ---
`NO` | Default. Input contains no SYSIPT data.
`OFF` | SYSIPT flag for existing member switched off before member is saved.
`YES` | Input contains SYSIPT data.

Field Name | Type/Length | Operating System
--- | --- | ---
`KEY` | (A253) | z/OS, BS2000

ISAM/VSAM key.

Field Name | Type/Length | Operating System
--- | --- | ---
`LIBRARY` | (A8) | z/VSE

Name of library.

Field Name | Type/Length | Operating System
--- | --- | ---
`LMS-RESET-FLAG` | (A3) | BS20000/OSD

If `YES` is specified in this field with `FUNCTION=CLOSE`, all previous writes for this LMS element are reset.

Field Name | Type/Length | Operating System
--- | --- | ---
`LRECL` | (B2) | z/OS, z/VSE

Logical record length. Default length is 80.

z/OS: Required only for tape datasets that have no standard label.

z/VSE: Required if `RECFM=F`.

Field Name | Type/Length | Operating System
--- | --- | ---
`MEMBER` | (A10) | z/OS, z/VSE

Member name.

Field Name | Type/Length | Operating System
--- | --- | ---
`MEMBER-TYPE` | (A8) | z/VSE

Member type.

Field Name | Type/Length | Operating System
--- | --- | ---
`MSHP` | (A3) | z/VSE

Indicate MSHP bypass required when saving members. Possible values:

Value | Explanation
--- | ---
`NO` | No MSHP bypass required.
`YES` | MSHP bypass to be performed.

Field Name | Type/Length | Operating System
--- | --- | ---
PAD | (N2) | BS2000

Only for ISAM: padding factor (default is 15).

Field Name | Type/Length | Operating System
--- | --- | ---
`PASSWORD` | (A8) | z/OS, BS2000

Password for protected dataset or file.

Field Name | Type/Length | Operating System
--- | --- | ---
`PRODUCT` | (A1) | z/OS, BS2000

Access method used. Possible options:

Option | Explanation
--- | ---
L | CA-Librarian
M | LMS (BS2000)
P | CA-Panvalet

Field Name | Type/Length | Operating System
--- | --- | ---
`PRODUCT-OPTIONS` | (A80) | z/OS

Options for CA-Librarian access method (when `PRODUCT=L`).

Field Name | Type/Length | Operating System
--- | --- | ---
`RECFM` | (A2) | z/OS, z/VSE

Record format of the dataset.

z/OS: Required only for tape datasets that have no standard label.

z/VSE: Default is `F`.

Field Name | Type/Length | Operating System
--- | --- | ---
`RECORD` | (A253) | z/OS, z/VSE, BS2000

Record to be written.

Field Name | Type/Length | Operating System
--- | --- | ---
`RECORD-LENGTH` | (N5) | z/OS, z/VSE, BS2000

Length of record (used only if record format is variable). Can be omitted in BS2000.

Field Name | Type/Length | Operating System
--- | --- | ---
`RECORD-NUMBER` | (N9) | BS2000

Number of record to be written.

Field Name | Type/Length | Operating System
--- | --- | ---
`REPLACE` | (A3) | z/OS, z/VSE

Possible options:

Option | Explanation
--- | ---
`NO` | Add module. If it already exists, issue error code.
`REP` | Replace module. If it does not already exist, issue error code.
`YES` | Default. Add module, replace module of the same name, if it exists.

Field Name | Type/Length | Operating System
--- | --- | ---
`SEGMENT-LENGTH` | (N3) | z/OS, z/VSE, BS2000

Length of segment.

Field Name | Type/Length | Operating System
--- | --- | ---
`SEGMENT-NUMBER` | (N5) | z/OS, z/VSE, BS2000

Number of segment. If `SEGMENT-NUMBER=`1, a new logical record is started. If `SEGMENT-NUMBER` > 1, the segment is a continuation.

Field Name | Type/Length | Operating System
--- | --- | ---
`STATS` | (A3) | z/OS

Generate or update ISPF statistical data, see also Write ISPF Statistics. If `STATS=YES`,

- ISPF statistical data is generated if

  - the member is new, that is `WRITE-FILE` is creating the member,

    or

  - the member already existed, but no ISPF statistical data has yet been generated for example when the member was created by a previous version of `WRITE-FILE`.

- ISPF statistic data already generated for an old member is updated.

If `STATS=DEL`, ISPF statistical data of an existing PDS member is deleted. `STATS=DEL` is valid only for PDS members and these will be always be accessed as if `UPDATE-IN-PLACE` is set to `YES`.

The default is `STATS=NO`. In this case `WRITE-FILE` behaves like in a previous version where the function did not provide writing of ISPF statistics. No ISPF statistics is generated or updated.

Field Name | Type/Length | Operating System
--- | --- | ---
`SUB-LIBRARY` | (A8) | z/VSE

Name of sublibrary.

Field Name | Type/Length | Operating System
--- | --- | ---
`TAPE-UNLOAD` | (A3) | z/OS, BS2000

Unload `TAPE` during `CLOSE`:

`YES`: Unload tape.

`NO`: Tape is rewound and positioned to beginning of tape (default).

Field Name | Type/Length | Operating System
--- | --- | ---
`UPDATE-INPLACE` | (A3) | z/OS, z/VSE, BS2000

Valid only for PDS members. It is ignored for PDSE members; these will be always be accessed as if `UPDATE-IN-PLACE` was set to `NO`. Possible options:

Option | Explanation
--- | ---
`YES` | Perform UPDATE-INPLACE function.

Field Name | Type/Length | Operating System
--- | --- | ---
`USER-DATA` | (A120) | z/OS

User data for PDS member, for example, save date, size. Relevant when FUNCTION=CLOSE.

Field Name | Type/Length | Operating System
--- | --- | ---
`USER-DATA-HEX` | (B120) | z/OS

User data for the member in hexadecimal format.

Field Name | Type/Length | Operating System
--- | --- | ---
`USER-DATA-LENGTH` | (N3) | z/OS

Length of data for PDS member. Relevant when `FUNCTION=CLOSE`.

Field Name | Type/Length | Operating System
--- | --- | ---
`VOLSER` | (A6) | z/OS, z/VSE

Volume serial number (required if dataset is not cataloged).

Field Name | Type/Length | Operating System
--- | --- | ---
`VSAM-CATALOG` | (A8) | z/VSE

Name of the VSAM catalog where the library is kept.

## WRITE-FILE Programming Notes

`WRITE-FILE` is an `UPDATE` view, i.e., data is transmitted from the Natural program (client side) to ESY (server side).

The Entire System Server view `WRITE-FILE` returns codes and messages that describe whether the requested operation has been executed successfully or not. The `DEFINE DATA` section of the Natural program should only contain the fields shown below:

    1 WRITE-FILE VIEW OF WRITE-FILE
      2 ERROR-CODE
      2 ERROR-TEXT
      2 SYSTEM-MESSAGE-CODE
      2 SYSTEM-CODE

These fields in `DEFINE DATA` are the fields returned from the `WRITE-FILE` view in Entire System Server to the calling Natural program. It is not necessary to define any other fields in the DDM; accessing any fields other than those above may lead to unpredictable results.

## WRITE-FILE and RELEASE Unused Space

    PROCESS FILE-ALLOCATE using DSNAME = xxx, RLSE=YES
    ...
    PROCESS WRITE-FILE using DSNAME = xxx, record = yyy
    PROCESS WRITE-FILE using DSNMAE = xxx, function=close

After the last `PROCESS` statement, unused space will be released; only one `FILE-ALLOCATION` and `WRITE-FILE` relationship with `RLSE` is possible at any one time.

## Write ISPF Statistics

Writing PDS members in TSO / ISPF or NSPF produces statistics entries. Most common is an order of entries on who edited the member at which time:

    MEMBER            VV.MM  CREATED  MODIFIED TIME  SIZE   INIT   TID   ID
    ----------------------+--------+---------+------+-----+-------+-------+
    AFP1              01.05  19950131  19970403 16:19   23    17        user1
    ASMAOPT           01.10  20190613  20190613 13:15    1     1        user2

whereas the columns are explained as follows:

VV | main version
MM | subversion
CREATED | date of creation
MODIFIED | date of modification
TIME | time of modification
SIZE | current record count
INIT | initial record count, when member was created
ID | ID of the user responsible for the latest change

These statistic entries can also be written using `WRITE-FILE` view outside NSPF or ISPF in an application.

ISPF statistics is described in https://www.ibm.com/support/knowledgecenter under z/OS version> ISPFz/OS> ISPF Messages and Codes> Diagnostic Tools and Information> Diagnostic information, for example in https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.f54mc00/ispmc28.htm.

### On this page

- Common Fields for all Operating Systems
- Additional Fields Supported for z/OS
- Additional Fields Supported for z/VSE
- Additional Fields Supported for BS2000
- Relevant Error Codes
- Field Descriptions
- WRITE-FILE Programming Notes
- WRITE-FILE and RELEASE Unused Space
- Write ISPF Statistics