  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Five — General Functions (continued)
A separate object and function set is provided for managing large strings that are over and above the regular language level string functions. While many of the functional tasks can be performed by direct string functions, the String Pool Object (SPO) provides a vehicle to deal with large bodies of text directly in memory. Further, unlike string variables, data is not constantly moved and copied to perform appends and other operations, thus decreasing processor requirements.
An example would be the creation of a body of text to be written to a file and sent to a server. The data could be built up by performing simple string adds and concatenates. However, such actions require a great deal of information to be internally moved and copied and acted upon repeatedly. With the SPO, an object is created and the information can be amended or read easily without an underlying script engine thrashing memory as a result of managing strings as separate entities.
Below is an example of a simple routine to accumulate some data using a fictional routine, ‘get_item()’, which then writes the data to a file (it is assumed myfile is a string containing a path and filename, and s1 and various handles have already been declared):
Using the a variable:
s1 = get_item();
while (GetLastError() == ERROR_NONE) {
buffer += s1 + "\r\n";
s1 = get_item();
}
VariableToFile(s1, myfile);
Writing directly to file:
hFile = CreateFile(myfile);
s1 = get_item();
while (GetLastError() == ERROR_NONE) {
WriteLine(hFile, s1);
s1 = get_item();
}
CloseHandle(hFile);
Using a SPO:
hPool = PoolCreate();
s1 = get_item();
while (GetLastError() == ERROR_NONE) {
PoolAppend(hPool, s1); PoolAppendNewLine(hPool);
s1 = get_item();
}
PoolWriteFile(hPool, myfile);
CloseHandle(hPool);
Each version of this process accomplishes the same thing: data is read using the ‘get_item()’ function until ‘get_item()’ sets an error code, the data is accumulated and then written to a file. Using a plain variable will slowly trash the internal variable pool, leaving a lot of garbage as the string s1 slowly grows. If we are reading a couple of megabytes of data, the inefficiency starts showing some stress on resources.
The second version avoids this by writing directly to the file. However, this can be slow, relying on the Windows file cache and functions.
The last version appends the data to the pool and does not trash the internal variable pool but rather nicely adds data and reallocates internally as needed without trashing. The final result is written in one function, making for a very efficient write.
For the most part, with today’s high speed processors, a script is not likely to see much of a measurable improvement in these methods until large volumes of data are processed and/or the process is repeated thousands of times.
Basically any time data in the tens or more megabyte size where the information is accumulated or trickles through, an SPO may be a good idea. Pools are excellent for appending data and are in fact internal to a number of script functions and objects.
Generally the first operation is to create a pool object using the PoolCreate function which will return a handle. When the script no longer needs the pool, the CloseHandle function will close the object or if it is declared as a local variable, the pool will be closed when the function that declared the handle exits.
Once a pool has been created, it can be loaded with data from a file or by adding data using a variety of pool append functions.
For reading, load the contents from a file using the PoolAppendFile function (or manually loading strings) and then the ReadLine function can be used to serially read lines of data from the pool.
For writing, append information repeatedly, then write the complete data to the destination using the PoolWriteFile function.
Finally, using a combination of append functions and the PoolPut function, separate segments can be added and later referenced by using an offset. Many of the append and the put functions return the offset to the start of the data added to the pool.
Object Management:
CloseHandle — Closes an object handle and releases any associated resources.
PoolCreate — Creates a String Pool Object (SPO) and optionally loads the pool with a string.
PoolGetPool — Returns the entire pool as a string. This requires the pool to be a contiguous string.
PoolGetPosition — Returns the end/current position of the pool.
PoolReset — Resets the content of an existing pool.
PoolSetNewLineMode — Sets the mode for the PoolAppendNewLine function (on pool creation, the default is 0x0D, default for function is 0x0D/0x0A, mode FALSE is 0x0D only).
PoolSetPosition — Sets the end/write position of the pool.
Adding Data:
AddMessage — Adds a formatted message to the default or a specified log, or other object.
PoolAppend — Appends a string at the current position and returns pool offset.
PoolAppendAsPCData — Appends a string at the current position while processing for PCDATA and returns pool offset.
PoolAppendAsXString — Appends a string at the current position while processing for XML and returns pool offset.
PoolAppendFile — Appends a file to a specified pool object.
PoolAppendFormattedString — Formats a string and then appends it to pool and returns pool offset.
PoolAppendNewLine — Appends one or more new lines.
PoolOverlay — Lays a string over the existing data with or without a terminator.
PoolPut — Places a string into the pool with an extra zero delimiter and returns pool offset.
Extracting Data:
PoolGetReadPosition — Returns the next read position for the pool.
PoolGetString — Returns all or part of a pool as a string from a specified offset position.
PoolWriteFile — Writes the pool content to a specified file.
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.
| 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.