WRITE - unit-oriented block I/O.

Alternative Entry Name: RAW.WR

Usage:

B:
   status = write( [unit,] buffer [, sector [, nwds] ] );

C:
   int write( [FILE *unit,] void *buffer,
            [int sector[, int nwds]]);

Where:

unit: indicates the unit number on which I/O will be performed. The unit must be open. If "unit" is not specified, it defaults to the current write unit.
buffer: points to the first word of a buffer from which WRITE takes the data it writes. "buffer" must be big enough to hold "nwds".
sector: is the starting sector address in the file which is being written. A sector is 64 words long and the first sector of the file has an address of zero. If "sector" is omitted a default value of zero is assumed. For sequential files and tapes, "sector" is ignored unless you specified the "zi" option when you opened the file with OPEN. For linked files, the write operation advances the file pointer by the number of llinks accessed. "sector" must be supplied for random files. For tape files, "sector" should be zero. If "sector" is 04000000000, the next sequential sector is used on either random or sequential files.
nwds: is the number of words to write. This is discussed below. If "nwds" is not specified, the default is 320 words.
status: is the number of words written, if the I/O operation is successful. If an I/O error occurs, and the unit was opened with the "e" action to prevent the error ending the program, then "status" receives the negative of the major I/O status.

Description:

WRITE performs binary I/O on random or sequential disk files or tapes which have been opened by a call to OPEN.

If WRITE gets an eof status on a file, it attempts to grow the file enough to hold the data, provided that the write operation was exactly at the end of the file. If the grow is successful, the remainder of the write will be reissued. If the grow fails, WRITE will not make a second attempt at growing the file.

Buffer Sizes:

For a random disk file, "nwds" may be any non-zero value. However, if it is not a multiple of 64 when writing, the hardware will fill the remainder of the last sector with zeroes. The file pointer will be advanced (words+63)/64 sectors (where "words" is the number of words transfered, normally "nwds").

For a sequential disk file, "nwds" would normally be a non-zero multiple of 320. It must be less than or equal to 20160 (63 llinks). The file pointer will be advanced by (words+319)/320 llinks (where "words" is the number of words written, normally "nwds"). If "nwds" is not a multiple of 320 when writing, the hardware will fill the last sector with zeroes, and the remaining sectors of the last llink will be left untouched.

For a tape, "nwds" must be a non-zero value.

Notes:

If a write encounters an EOF, and the file grow is unsuccessful, an EOF error will be raised.

When "status" is negative indicating an error was raised, and the file was opened with the "e" option, the A-register will contain the number of words transfered before the error. B users can retrieve this with a call to .NULL; C users can define the functions as returning a two-word struct.