NOTE—Provide relative position (BPAM and BSAM—tape and DASD only)

The NOTE macro returns the position of the last (or next if TYPE=ABS is specified) block read from or written into a data set. All input and output operations using the same data control block must be tested for completion before the NOTE macro is issued.

The NOTE macro with the REL parameter, which is the default, works with any magnetic tape drive. However, NOTE with the ABS parameter works only on cartridge tapes, such as the 3480, 3490 and 3590.

The capability of using the NOTE macro is automatically provided when a PDSE or partitioned data set is used (DSORG=PO). But you must specify MACRF=P in the DCB macro to use NOTE or POINT when using BSAM for a sequential data set, a large format data set, or a member of a partitioned data set or PDSE.

The NOTE macro can be issued in 24- or 31-bit addressing mode. When issued in 31-bit addressing mode, all addresses must be valid 31-bit addresses.

Spooled Data Sets: The NOTE (and POINT) macros cannot be used with spooled data sets.

Subsystem data sets: The NOTE macro can be used for subsystem data sets if the subsystem supports it. If the subsystem does not support it, the results are unpredictable.

UNIX files: The NOTE macro can be issued for UNIX files, except for FIFO or character special files or with PATHOPTS=OAPPEND.

If you set BLOCKTOKENSIZE=LARGE (DCBELARGE=1) and MACRF and DSORG in the DCB indicate BSAM and the NOTE and POINT macros then the OPEN macro will allow the opening of large format data sets. BLOCKTOKENSIZE=LARGE signifies that you aware of the changes in the DSCB, DEB, and TTR conversion routines and that the NOTE and POINT macros must use the TTTR interface in place of the TTR0 interface regardless of what kind of DASD the data set resides on.

The format of the NOTE macro is:

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

specifies the address of the data control block opened for the partitioned or sequential data set being processed. For TYPE=REL requests, when issued in 31-bit addressing mode, the input DCB address must be a clean 31-bit address.

TYPE={ABS|REL}

indicates if the device that the data set resides on supports the physical block identifier (ABS) or relative addresses (REL). The ABS option of the POINT macro generally is much faster than the REL option, especially when positioning over many blocks.

ABS

specifies that, after NOTE executes successfully (contents of register 15 is 0), register 0 contains the physical block identifier for the next data block that will be transferred between virtual storage and the control unit buffer, and register 1 contains the physical block identifier of the next data block that will be transferred between the control unit buffer and the tape drive.

You can subtract register 1 from register 0. On certain cartridge tape drives the physical block identifier is a 32-bit unsigned integer. In these cases the result is the number of data blocks left in the control unit buffer. On other drives the block identifier contains unsigned integers of unequal length. The number of bits varies between models. Consult the hardware manual. A negative result means the buffer is in read mode, and a positive remainder means the buffer is in either write or read-backward mode. A zero remainder means that no data is buffered.

REL

causes the system to return the relative position of the last block read from or written into a data set. This means that if the data set later is copied and the number of blocks on each volume is changed or the data set is reblocked, then the value returned by NOTE for a particular block may differ. The position of the current volume is returned in register 1 as follows:

Magnetic Tape: The block number is in binary, right-adjusted in register 1 with high-order bits set to zero. Do not use a NOTE macro for tapes without standard labels when:

• The data set is opened for RDBACK (specified in the OPEN macro), or
• The DISP parameter of the DD statement for the data set specifies DISP=MOD and the OPEN option was OUTPUT or OUTIN, or
• The OPEN option was EXTEND or OUTINX, or
• The CLOSE macro is issued with TYPE=T and the LEAVE option, or
• The CLOSE macro is issued with TYPE=T and the DISP option and the DD statement or dynamic allocation equivalent has DISP=(xxx,PASS).

Direct Access Storage Devices: The value that the NOTE macro returns depends on the type of data set and on whether you coded BLOCKTOKENSIZE=LARGE on the DCBE macro that the DCB points to. If your program turns on the DCBELARGE bit in the DCBE, it has the same effect as coding BLOCKTOKENSIZE=LARGE.

If you do not code BLOCKTOKENSIZE=LARGE, then the value returned in register 1 is in the three high order bytes and the low order byte contains X'00'. If you code BLOCKTOKENSIZE=LARGE, then the value returned in register 1 is in all four bytes. BLOCKTOKENSIZE=LARGE has no effect on the FIND and BLDL macros or on the content of DCBRELAD and DCBERELA, which identify the location of the beginning of the member. They always use a three-byte member token.

If your program runs on a system before z/OS® 1.7, then the system ignores any setting of BLOCKTOKENSIZE=LARGE.

TTRz Basic format, large format. or PDS:

TTRz

Returned if you do not code BLOCKTOKENSIZE=LARGE.

TTTR

Returned if you code BLOCKTOKENSIZE=LARGE. You must code this if the data set is large format unless less then 65536 tracks are allocated to it on the volume and your program opened the data set with the INPUT option. If the data set is a PDS or basic format data set, then the high order byte always will contain X'00' because those data sets cannot contain more than X'FFFF' tracks.

Note: The TT or TTT bytes contain the relative track address of the block, where the first track in the data set is 0.

R

Specifies the number of the block on the track, where the first block is X'01'.

Z

Contains X'00'.

• PDSE or UNIX file with BPAM: The three or four byte token does not represent the physical location of the data set or member. Without BLOCKTOKENSIZE=LARGE, the maximum number of records in a member is 15,728,639. With BLOCKTOKENSIZE=LARGE, the maximum number of records in a member is 4,277,145,599.
• UNIX file with BSAM: The NOTE macro can be issued for UNIX files, except for FIFO or character special files or with PATHOPTS=OAPPEND. If you do not code BLOCKTOKENSIZE=LARGE, then (1) NOTE does not support a UNIX file that contains more than 16 mega-records minus two (X'1000000'-2 or 16,777,214) and (2) a NOTE macro after 16 mega-records minus two returns an invalid value (X'FFFFFF'). If you code BLOCKTOKENSIZE=LARGE, then you do not have this limit.
• Extended format data set or compressed format data set: The three or four byte value is a token that does not represent the physical location of the data set or member. If you do not code BLOCKTOKENSIZE=LARGE, then your program can address up to 16,777,215 blocks. If you code BLOCKTOKENSIZE=LARGE, then your program can address up to 4,294,967,295 blocks.

If the data set later is copied to a DASD that has a different track length, the value returned by NOTE for a particular block may differ.

When direct access storage devices are being used, the amount of remaining space on the track is returned in register 0 if a NOTE macro follows a WRITE macro. If a NOTE macro follows a READ or POINT macro, the track capacity of the direct access storage device is returned in register 0. For PDSEs, extended format data sets, and UNIX files, the NOTE macro does not calculate the amount of space remaining on the track or the track capacity, and returns a value of X'7FFF'.

Recommendation: Your programs should not become device-dependent. Your program is device-dependent if it examines what NOTE returns in register 1 or performs arithmetic on it. Your program can pass the four bytes to the POINT macro without examining them.