WRITE—Write a block (BPAM and BSAM)

The WRITE macro adds or replaces a block in a sequential or partitioned data set. Control might be returned to the problem program before the block is written. The output operation must be tested for completion using the CHECK macro.

If the OPEN macro specifies UPDAT, both the READ and WRITE macros must refer to the same data event control block. See the list form of the READ or WRITE macro for a description of how to construct a data event control block. See the execute form of the READ or WRITE macro for a description of modifying an existing data event control block.

Data Conversion: You can request conversion by coding LABEL=(,AL) or (,AUL) in the DD statement, or by coding OPTCD=Q in the DCB macro or DCB subparameter of the DD statement. When conversion is requested, all records whose record format (RECFM parameter) is F, FB, D, DS, DB, DBS, or U are automatically converted from one character representation to another. Conversion is performed according to one of the following techniques:

Coded Character Set Identifier (CCSID) conversion
If CCSIDs are supplied from any source for ISO/ANSI V4 tapes, records are converted from the CCSID as seen by the problem program to the CCSID which represents the data on tape. You can also prevent conversion by supplying a special CCSID. CCSID may be supplied in the CCSID subparameter of a JOB, EXEC, or DD statement or the tape label.
Default Character Conversion
If you are using non-ISO/ANSI V4 tapes or if CCSIDs are not supplied by any source, data management converts the records from EBCDIC code to ASCII code using specific tables defined for this default character conversion.

Refer to z/OS DFSMS Using Data Sets, for a complete description of CCSID conversion and Default Character conversion.

If conversion from EBCDIC code to ASCII code is requested, issuing multiple WRITE macros for the same record causes an error because the first WRITE macro issued converts the output data in the output buffer into ASCII code. This problem also exists when converting from one CCSID to another.

A data event control block, shown in Status information following an input/output operation, is constructed as part of the macro expansion.

Processing PDSEs and Compressed Format Data Sets: If the PDSE member is open for update or a compressed format data set is open for output, and it resides ina storage class with "Guaranteed Synchronous Write" specified, issue a CHECK macro following a WRITE macro to guarantee that the data is synchronized to DASD. Otherwise, synchronization is not guaranteed until CLOSE, or the STOW macro or the SYNCDEV macro is issued. Synchronization occurs at CLOSE if BSAM or QSAM are used to process the PDSE member or compressed format data set. Specifying "Guaranteed Synchronous Write" in the storage class produces the same result as issuing the SYNCDEV macro.

When processing a compressed format data set and NOTE/POINT is specified in the DCB (MACRF=P), a WRITE issued for a block whose user RBN value exceeds 16 777 215 will result in an I/O error. This is due to the fact that the NOTE/POINT interface is limited by a 3 byte token.

z/OS UNIX files: The last write issued against a UNIX file before CLOSE denotes the end of the file. Any type of positioning (POINT, BSP, CLOSE TYPE=T REREAD) following a WRITE does not truncate the file.

Addressing mode: When you issue the WRITE macro in 24-bit mode, you provide only 24-bit addresses unless you code SF64 or SF64P. When you issue the WRITE macro in 31-bit addressing mode, all addresses must be valid 31-bit addresses unless documentation says otherwise or you code SF64 or SF64P. With SF64 or SF64P, the data area can reside above the 2 GB bar but you cannot issue WRITE in 64-bit mode.

BSAM and BPAM allow data areas to be located above the 16MB line. This includes allowing the caller to issue some other BSAM and BPAM macros in 31-bit addressing mode regardless of whether the data area is above or below the 16MB line. Most types of data sets support 31-bit mode. For more information, refer to Environmental considerations.

The standard form of WRITE must be issued from a program that resides below the 16MB line because the DECB must reside below the line.

To take advantage of providing data areas above the 16MB line for BSAM macros, the issuer of the WRITE macro must execute in 31-bit addressing mode.

Syntax: The standard form of the WRITE macro is written as follows (the list and execute forms are shown following the descriptions of the standard form):

[label]

WRITE

decb name
{,SF|SF64|SF64P}
,dcb address
,area address
[,{length|'S'}]

decb name—symbol

specifies the name that is assigned to the data event control block created as part of the macro expansion.

type—{SF|SF64|SF64P}

is coded as shown to specify the type of read operation:

SF: specifies normal, sequential, forward operation.
SF64: for BSAM, indicates sequential forward writing and that area address is an 8-byte address and can point to an area above the 2-GB bar. The 8-byte pointer in the macro expansion must reside below the 2-GB bar. When the area is in a register, it must be a 64-bit register.
The system supports this option only for extended format data sets. For other restrictions see z/OS DFSMS Using Data Sets.
SF64P: for BSAM, indicates sequential forward writing and that area address is a doubleword (8 bytes) containing the address of the area that can be above the 2-GB bar. The 8-byte pointer must reside below the 2-GB bar. With SF64 you code the name or address of the data area. With SF64P you code the name or address of a doubleword that points to the area.

dcb address—A-Type Address, or (2-12)

specifies the address of the data control block for the opened data set being allocated or processed. If the data set is being updated, the data control block address must be the same as the dcb address in the corresponding READ macro. When issued in 31-bit addressing mode, the input DCB address must be a clean 31-bit address. If the data area resides above the 16MB line, you must issue the WRITE in 31-bit mode.

area address—A-Type Address or (2-12)

specifies the address of the problem program area in which the block is placed if you do not code SF64P. Specifies an eight-byte pointer if you specify SF64P. If you specify SF64P, the specified doubleword contains an area pointer that can point above the 2 GB bar. The doubleword must reside below the 2 GB bar. If you specify the register form with SF64, it is a 64–bit register. Even if you specify SF64 or SF64P, your program must run in 24–bit or 31–bit mode. If a key is written (KEYLEN value is not zero), the key must precede the data in the same area. If the data area (or eight byte pointer with SF64P) resides above the 16 MB line, you must issue the WRITE in 31–bit mode.

length—symbol, decimal digit, absexp, (2-12) or 'S'

specifies the number of bytes to be written. The maximum value is BLKSIZE in the DCB (without LBI) or DCBE (with LBI) but on the WRITE macro the value also must be no more than 32760. This parameter is meaningful only for undefined-length records (RECFM=U) or for ASCII records (RECFM=D) when the DCB BUFOFF is not L. If you code 'S' to indicate the length of the block to be written, it means the length is in the data control block if you are not using LBI or in the DCBE if you are using LBI. If you are using LBI when writing format-U records or format-D records without BUFOFF=L , then you must code the 'S' value. Omit the length parameter for all record formats except format-U and format-D (when BUFOFF is not L).

If length is omitted for format-U or format-D (with BUFOFF that is not L) records, no error indication is given when the program is assembled, but the problem program must insert a length into the data event control block before the WRITE macro is issued.