CBL_READ_FILE

Usage

CAll "CBL_READ_FILE" 
     USING HANDLE, OFFSET, COUNT, FLAGS, BUF
     RETURNING STATUS-CODE

Parameters

HANDLE (pic x(4) comp-x) This is the handle returned from CBL_OPEN_FILE.
OFFSET (pic x(8) comp-x)    This is the offset from which to read from the file, based at "0" to read from the first byte. Note that this is a 64-bit value, allowing access to files larger than 4GB. Note that if your OS or File System does not allow such files, setting this to a value larger than your OS or file system can support will cause undefined results.
COUNT (pic x(4) comp-x) This is the number of bytes to read. This should not be set to a value larger than the size of the buffer (described below), or you will get undefined results, including a potential MAV.
FLAGS (pic x comp-x) One special value is recognized. If this parameter is 128, the size of the file returned is the offset parameter, and the file is not read. The only other allowable value is 0.
BUF (pic x(n)) This is the buffer that will store the values read from the file. This buffer should be at least count bytes long.

Description

This routine is used for reading files and returns 0 on success and non-zero if an error occurred. The error is a special encoding of the digit 9 with the ANSI-74 error code, or the runtime system error number if no ANSI-74 error code pertains to the error. If RETURN-CODE is non-zero after calling this routine, you must process it as a file status, for example:

01  file-status-group.
    03  file-status     pic xx comp-x. 
    03  redefines file-status. 
        05  fs-byte-1  pic x. 
        05  fs-byte-2  pic x comp-x.
. . . 
call "CBL_READ_FILE" using parameters 
if return-code not = 0 
    move return-code to file-status 
. . .

At this point fs-byte-1 contains 9 and fs-byte-2 contains the ANSI-74 error code or a runtime system error number.

Note: This routine is written in C and is called via the "direct" method, so it is not possible for the runtime to validate parameters for accuracy. Passing unexpected parameters will result in undefined behavior and possibly even a MAV.