GoFiler Legato Script Reference   Legato v 1.5d Application v 5.25a

Table of Contents	< < Previous	Next >>

 

Chapter Six — File Functions (continued)

ReadBlock Function

Overview

The ReadBlock function will read a specified or implied block of data from a Basic File Object at the current position.

Syntax/Parameters

Syntax

int = ReadBlock ( handle hBasicFile, parameter *data, [int bytes] );

Parameters

hBasicFile

A handle to a Basic File Object.

data

A variable of any type that will receive the data. It cannot be a literal or a calculated expression value and it must be in contiguous storage. See Section 3.7 Contiguous Data for more information. The parameter is treated as a pointer to the area of memory where the variable is held. Strings are an exception in that they must be zero-terminated (see the Remarks section below). By default, this parameter is treated as a reference and its contents will be altered.

bytes

An optional int containing the requested number of bytes to be read. If specified, it must be equal or less than the size of the data parameter. If data is a string type, the number of bytes read will always be reduced to allow for a terminator. The maximum number of bytes that can be read is 1GB or 0x3FFFFFFF. If the number of bytes is less than 1 or omitted, the default size of the data parameter will be used.

Return Value

Returns an int containing the number of bytes read or zero (0) code on failure. If hBasicFile is invalid, the function will return zero (0) with a lasy error of ERROR_FILE | ERROR_INVALID_HANDLE. Use the GetLastError function to retrieve error information. The GetLastErrorMessage function may contain information to supplement the error code.

Remarks

The ReadBlock function is designed as an advanced function to give developers maximum flexibility in terms of accessing files and loading information into variables. It allows binary data to be loaded directly into variables. As a consequence, the variable must be a contiguous block of memory. Therefore, objects that contains strings or other auto allocated data types cannot be used with this function.

The ReadBlock function differs from most other functions in that the provided data parameter is always a reference and its content will be altered by the function. With the exception of strings, the data is read verbatim and treated as binary information. Reading starts at the current file position within the Basic File Object (the SetFilePosition function can be used to alter the position) and will continue until the size specified by the bytes parameter, the variable size of the data parameter, or the file’s end is reached. If the size of the data parameter or the end of the file is reached, the number of bytes read may be less than the requested number in the bytes parameter. If there are no more bytes to read in the file from the current position, the function will return zero.

If the last read of the file is less than the requested amount, the GetLastError function will return ERROR_EOD. This does not mean that the read failed, only that it failed to fill the buffer.

Developers are cautioned that reading small amounts of data from a file is incredibly inefficient. For example, although streaming data from a file by reading a character one by one can be programmatically performed, it is exceptionally slow. Other methods, such as using the ReadLine function or using a Mapped Text Object, are preferred. However, in some cases, such as reading a complex binary file, the ReadBlock function provides the only means of reading the data.

String variables are not appropriate to use to receive data with the ReadBlock function but are allowed.

Examples

The following code converts a file to a hexadecimal dump file:

      char              buffer[0x1000];
      string            s1;
      int               bytes, total, rc;
      handle            hSRC, hDST;


      hSRC = OpenFile( .. filename .. ); 
      hDST = CreateFile( .. filename .. ); 

      bytes = ReadBlock(hSRC, buffer);
      while (bytes != 0) {
        s1 = HexBufferToBlock(buffer, bytes, total, 0x302);
        total += bytes;
        WriteLine(hDST, s1);      
        bytes = ReadBlock(hSRC, buffer);
        }

      CloseFile(hSRC);
      CloseFile(hDST);      

Related Functions

CreateFile — Creates a basic file with optional access mode and characteristics.

GetFilePosition — Gets the current position of a flat file for reading or writing.

OpenFile — Opens the specified file as a Basic File Object.

SetFilePosition — Sets the file’s next read or write position for a Basic File Object.

ReadLine — Reads the next line of data from a Basic File or Pool Object, or, reads a specified line from a Mapped Text or Edit Object.

WriteBlock — Writes a block to a Basic File Object at the current or specified position.

WriteLine — Writes a formatted line of text to a Basic File Object. Follows FormatString parameters.

Platform Support

Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL

Legato IDE, Legato Basic

 

Table of Contents	< < Previous	Next >>

GoFiler Legato Script Reference — Generated on 12/16/2024

© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.