WRITE-FILE

#### Search Results

Search

# WRITE-FILE

File | 204
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.

## Fields

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 |
`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.

## Relevant Error Codes

Code | Text
--- | ---
530 | Access denied by Security Facility.
541 | Member generation not found in directory.
542 | GENERATION not valid for this library.
553 | I-O error in directory.
556 | File is in use.
557 | File held by linkage editor.
558 | No space in directory.
559 | Stow error.
560 | Segment length greater than 253.
590 | End-of-data reached during `UPDATE-INPLACE`.
591 | Member not found for `UPDATE-INPLACE`.
592 | Record length error for variable `UPDATE-INPLACE`.
608 | ISITMGD failed with RC :1: and reason :2:.
678 | Member already exists.
870 | `RECORD` field not in search buffer.
871 | `MEMBER` not specified.
872 | Record format not supported.
873 | Record length missing.
874 | `RECORD-LENGTH` > `LRECL`.
875 | Position of data field > `RECORD-LENGTH`.
883 | Dataset is full.
889 | Permanent I/O error while writing dataset.
899 | Permanent I/O error while reading dataset.
901 | Dynamic allocation failed.
991 | Unknown product.
993 | Open error.
997 | File not PDS/Sequential.
998 | Member not found.

## Field Descriptions

Field Name | Type/Length
--- | ---
`BLKSIZE` | (B2)

Block size for dataset.

Required only for tape datasets that have no standard label.

Field Name | Type/Length
--- | ---
BLOCK-TTR | (B3)

Track value at which to start writing.

Field Name | Type/Length
--- | ---
BLOCK-TOKEN | (B4)

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
--- | ---
DISP | (A3)

Disposition of dataset or file. Possible values:

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

Field Name | Type/Length
--- | ---
`DSNAME` | (A54)

Fully qualified dataset name. Specify `&TEMP.name` here to select a temporary dataset as specified in the Entire System Server startup parameter module. These temporary datasets or files are freed when you log off.

Field Name | Type/Length
--- | ---
`FUNCTION` | (A8)

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` | 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
--- | ---
`GENERATION` | (N9)

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

Field Name | Type/Length
--- | ---
`IDENTIFIER` | (A8)

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
--- | ---
`KEY` | (A253)

ISAM/VSAM key.

Field Name | Type/Length
--- | ---
`LRECL` | (B2)

Logical record length. Default length is 80.

Required only for tape datasets that have no standard label.

Field Name | Type/Length
--- | ---
`MEMBER` | (A10)

Member name.

Field Name | Type/Length
--- | ---
`PASSWORD` | (A8)

Password for protected dataset or file.

Field Name | Type/Length
--- | ---
`PRODUCT` | (A1)

Access method used. Possible options:

Option | Explanation
--- | ---
L | CA-Librarian
P | CA-Panvalet

Field Name | Type/Length
--- | ---
`PRODUCT-OPTIONS` | (A80)

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

Field Name | Type/Length
--- | ---
`RECFM` | (A2)

Record format of the dataset.

Required only for tape datasets that have no standard label.

Field Name | Type/Length
--- | ---
`RECORD` | (A253)

Record to be written.

Field Name | Type/Length
--- | ---
`RECORD-LENGTH` | (N5)

Length of record (used only if record format is variable).

Field Name | Type/Length
--- | ---
`REPLACE` | (A3)

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
--- | ---
`SEGMENT-LENGTH` | (N3)

Length of segment.

Field Name | Type/Length
--- | ---
`SEGMENT-NUMBER` | (N5)

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
--- | ---
`STATS` | (A3)

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
--- | ---
`TAPE-UNLOAD` | (A3)

Unload `TAPE` during `CLOSE`:

`YES`: Unload tape.

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

Field Name | Type/Length
--- | ---
`UPDATE-INPLACE` | (A3)

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
--- | ---
`USER-DATA` | (A120)

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

Field Name | Type/Length
--- | ---
`USER-DATA-HEX` | (B120)

User data for the member in hexadecimal format.

Field Name | Type/Length
--- | ---
`USER-DATA-LENGTH` | (N3)

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

Field Name | Type/Length
--- | ---
`VOLSER` | (A6)

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

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

- Fields
- Relevant Error Codes
- Field Descriptions
- WRITE-FILE Programming Notes
- WRITE-FILE and RELEASE Unused Space
- Write ISPF Statistics