FREADBACKWARD

NM and CM callable.

Reads a logical record backward from the current record pointer. Data is presented as if read forward. Used for tape files only. Can recover tape errors when handling I/O management and data recovery routines.

Syntax

        I16                      I16V    UDS  I16V

   transfercount:=FREADBACKWARD(filenum,buffer,length);

Functional Return

transfercount

16-bit signed integer

Returns the length of the data transferred to buffer:

If a negative value is passed in the length parameter, the transfercount is a positive value indicating the number of bytes transferred.
If a positive value is passed in the length parameter, the transfercount is a positive value indicating the number of half words transferred.




	NOTE: If the file is opened with the nowait I/O option enabled, `transfercount` is zero. The `IOWAIT` intrinsic can be used to determine the length of the data transferred.

Parameters

filenum

16-bit signed integer by value (required)

Passes the file number of the file to be read.

buffer

user-defined structure (required)

Returns the specified record. This structure must be large enough to hold all of the information to be returned.

length

16-bit signed integer by value (required)

Returns the length of the data to be transferred to buffer:

Value	Meaning
<0	Length in bytes
=0	No transfer occurs
>0	Length in half words

: If length is larger than the size of the logical record, and the multirecord aoption in FOPEN/HPFOPEN was not specified, transfer is limited to the length of the logical record. If the multirecord aoption in FOPEN/HPFOPEN is specified, transfer continues until either length is satisfied or end-of-data is encountered, and each transfer begins at the start of the next physical record (block). Any data remaining in the last physical record read is inaccessible.

Operation Notes

Three restrictions apply when using FREADBACKWARD:

Used only with a magnetic tape drive with read-reverse capability.
The magnetic tape drive must be located on an HP-IB system.
The magnetic tape NOBUF must be accessed.




	NOTE: Magnetic tape devices with read-reverse capability are not supported. A call to `FREADBACKWARD` results in an error (CCL (`1`)).

Not used for KSAM files.

Condition Codes

CCE (2): Request granted.
CCG (0): Request denied. The logical beginning-of-data was encountered. When reading a labeled magnetic tape file that spans more than one volume, CCG (0) is not returned when beginning-of-tape (BOT) is encountered. CCG (0) is returned at actual beginning of file, with a transmission log of 0 if an attempt is made to read past beginning-of-file.
CCL (1): Request denied. The information was not read because a tape error occurred, or a tape error was recovered and the FSETMODE option was enabled. Check the condition code in both normal I/O and nowait I/O.

Related Information

Intrinsics: None
Commands: None
Manuals: Accessing Files Programmer's Guide (32650-90017)