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.
When you code BLOCKTOKENSIZE=LARGE on the DCBE with
BSAM or BPAM then:
The format of the NOTE macro is:
[label]
|
NOTE
|
dcb address
[,TYPE={ABS|REL}]
|
- 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.
An example of an unmovable data set is one that has all of these
attributes:
- The system determined the block size because it was omitted. IBM® recommends omitting it. See
the BLKSIZE parameter description for DCB—Construct a data control block (BSAM).
- The data set resides on DASD. A program such as DFSMShsm may copy
the data set to a different type of DASD or to tape. This may cause
the system to determine a different block size that is optimized for
the new device type.
- A program has stored the results of a NOTE macro inside the data
set or in some other data set. This value typically depends on the
block size.