WRITE-FILE

File 204
Op-Sys z/OS, z/VSE, BS2000
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
CA-Librarian
LMS (BS2000)
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.

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.

ISPF statistical data is not generated neither for a new member nor for an existing member that is overwritten, even if it already had ISPF statistics.

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.