WRITE-FILE

File	204
Op-Sys	z/OS, z/VSE, BS2000/OSD
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	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	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
`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	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/OSD

Dictionary Field Name	F/L	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/OSD
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/OSD

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/OSD:

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/OSD

Fully qualified dataset name. For BS2000/OSD, 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/OSD).

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

For ISAM only:

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

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

Name of the LMS element to be written.

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

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

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

Record type (LMS only).

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

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/OSD

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/OSD

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

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

Version of LMS element to be written.

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

The file's new expiration date in format YYDDD.

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

Expiration date in Natural format.

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

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/OSD

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/OSD

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/OSD

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

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

Password for protected dataset or file.

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

Access method used. Possible options:

Option	Explanation
L	CA-Librarian
M	LMS (BS2000/OSD)
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/OSD

Record to be written.

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

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

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

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/OSD

Length of segment.

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

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
`SUB-LIBRARY`	(A8)	z/VSE

Name of sublibrary.

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

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/OSD

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.