  |
GoFiler Legato Script Reference
Legato v 1.4j Application v 5.22b
|
| Table of Contents | < < Previous | Next >> |
Chapter Six — File Functions (continued)
Overview
The WriteBlock function writes the contents of a variable or a literal to a Basic File Object.
Syntax/Parameters
Syntax
int = WriteBlock ( handle hBasicFile, parameter name, [int size] );
Parameters
hBasicFile
A handle to a Basic File Object.
name
A variable or literal value. If name contains an object or array, it must be structured as contiguous memory.
size
An optional int containing the requested number of bytes to be written. If specified, it must be equal or less than the size of the name parameter. If omitted or 0, size will be set to the size of name.
Return Value
Returns an int as ERROR_NONE or a formatted error code on failure. If hBasicFile is invalid, the function will return ERROR_INVALID_HANDLE. Use the GetLastError function to retrieve error information. The GetLastErrorMessage function may contain information to supplement the error code.
Remarks
The WriteBlock function is designed as an advanced function to give developers maximum flexibility in terms of accessing files and writing information to them from variables. It allows binary data to be written directly from variables or parameters into a Basic File Object. As a consequence, the variable must be a contiguous block of memory. Therefore, objects that contain strings or other auto allocated data types cannot be used with this function.
Writing 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 size parameter or the variable size of the name parameter is reached. The writing operation is binary-safe and does not alter the data referenced by or contained in the name parameter.
Developers are cautioned that writing small amounts of data to a file is incredibly inefficient. For example, although writing data to a file one character at a time can be programmatically performed, it is exceptionally slow. Other methods, such as using the WriteLine function or using a Mapped Text Object, are preferred. However, in some cases, such as writing a complex binary file, the WriteBlock function provides the only means of writing the data.
Related Functions
Platform Support
Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL
Legato IDE, Legato Basic
| Table of Contents | < < Previous | Next >> |
© 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.