  |
GoFiler Legato Script Reference
Legato v 1.5b Application v 5.24b
|
| Table of Contents | < < Previous | Next >> |
Chapter Three — Data Types and Operators (continued)
Various functions are provided to manage variables, binary variable content and arrays. Variables are stored internally in a variable pool. Each script will have a global variable pool and each function will have its own local variable pool. Local variable pools are always transient, meaning the content of the pool is emptied to free space as soon as the function exits.
Internally, each variable will have certain properties associated with it as well as the data it represents. If the data is dimensional, e.g. a list, table or cube, then the variable element can be accessed via an index. Array indices are always zero-based and can also have a key name associated.
An array axis can be referenced by a zero-based index or by a key name. Key names can be up to 64 characters and can contain any legal character except /0 (since it is a string terminator). Key names can be a convenient method of accessing and organizing data. Further, key names are employed by several SDK functions to return an array with a variety of properties in one function call.
A key name is unique to the variable name, scope and axis. Therefore, this:
a["cat"][0]
is different and unique to:
a[0]["cat"]
For the first dimension “cat” could be index 7 while in the second dimension, “cat” could be ‘0’. Once a key name is associated with an index position, it will remain that value unless acted upon by an array function to manage keys or the variable released in the case of a local variable.
Functions are provided to perform basic management of keys. By default, the first time a key name is used, it is added to the key list for a variable by axis.
Key names are automatically added to the variable’s properties when a value is written to an element using a key name. Referencing an unknown key name will NOT result in an error. Rather, the value returned will be empty, zero or NULL_HANDLE depending on the type as string, numeric or handle, respectively.†
There are numerous functions available to access and manage key names. For example, key names can be added prior to data being instantiated such that the columns of a table might be in a particular order for exporting.
From a high-level stand point, script variables represent a string of text, a number or perhaps a handle to an object. Fundamentally, the data is binary as one or bytes (8-bits). In some cases, it may be necessary or advantageous to access the data as plain binary information. Legato provides a number of functions to allow access to the low-level binary data.
Array data saved and loaded directly from a string is known as a cluster. Clusters contain the dimensional data, key names and actual data. Clusters are typeless, so a cluster made from an integer array can be loaded into a string and all the strings will be numbers. Likewise, running strings into integers will try to convert the data.
The following is an example of a cluster:
Axes: 2; Rows: 20; Columns: 5; Layers: 0;
{Row: zero;
Col A:"This is cell 0:0 as key: row \"zero\" col \"Col A\"",
Col B:"This is cell 0:1 as key: row \"zero\" col \"Col B\"",
Col C:"This is cell 0:2 as key: row \"zero\" col \"Col C\"",
Col D:"This is cell 0:3 as key: row \"zero\" col \"Col D\"",
Col E:"This is cell 0:4 as key: row \"zero\" col \"Col E\""}
{Row: one;
Col A:"This is cell 1:0 as key: row \"one\" col \"Col A\"",
Col B:"This is cell 1:1 as key: row \"one\" col \"Col B\"",
Col C:"This is cell 1:2 as key: row \"one\" col \"Col C\"",
Col D:"This is cell 1:3 as key: row \"one\" col \"Col D\"",
Col E:"This is cell 1:4 as key: row \"one\" col \"Col E\""}
...
Clusters can be read and written by other applications.
While under the hood, the Script Engine employs a data pool to handle the interaction between functions, user or SDK and internal operator processing. The data pool end is reset at the end of the every statement while the allocated space is not. This is quite deliberate since the working space will generally be reused over and over again. However, it does mean that an interchange of large data, such as loading a 100mb file into a string will expand the working string pool.
Two functions are available should a programmer need to manage the Working Pool: GetWorkingPoolSize and ReleaseWorkingPoolSpace.
Arrays and Array Management:
ArrayAddKeyName — Adds a key name to a specified axis.
ArrayAddKeyNames — Adds one or more key names to a specified axis.
ArrayClear — Clears an array, including key names for a specific axis, item or key.
ArrayFindKeyName — Finds a key name for a specified array and a specific axis.
ArrayGetAxisSize — Gets the number of elements allocated on an axis.
ArrayGetAxisDepth — Gets the number of elements used by the highest index referenced.
ArrayGetKeyName — Gets the name of a key at a specified index.
ArrayGetKeys — Gets an array of the key names for a specified axis.
ArrayHasKeyName — Checks an index position for the presence of a key name.
ArrayIsKeyName — Checks for the existence of a key name.
ArrayIsValidKeyName — Tests a string as a valid key name.
Clusters and Foreign Data
ArrayToCluster — Writes a dimensional variable as a cluster to a file or returns it as a string.
ClusterToArray — Reads a dimensional variable cluster from a file or string and stores it in a dimensional variable.
Pointer Functions:
GetVariablePointer — Returns the raw pointer to a variable.
GetVariableSize — Returns the size of a variable.
Strings:
IsNullString — Tests a string or array entry for being null or never used.
Working Pool:
GetWorkingPoolSize — Returns the size of a specified section of the internal working pool.
ReleaseWorkingPoolSpace — Releases allocated but unused internal working pool space.
Related In Other Sections:
StringToFile — Writes a string to a specified file.
VariableToFile — Writes the contents of the specified variable to a specified filename.
† The behavior was changed in version 1.4a. Prior versions would create key names for referenced items as well.
| 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.