Legato
Legato

GoFiler Legato Script Reference

 

Legato v 1.5b

Application v 5.24b

  

 

Chapter SixFile Functions (continued)

WriteBlock Function

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