  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Six — File Functions
This section discusses functions that deal with file access at various levels and the associated functions for manipulating filenames, paths, folders and volumes. Legato supports file access at a number of levels: simple, mapped text objects, edit object and pools. Many of these modes share common terms and have strengths and weaknesses. For example, simple file operations allow access to data on the most fundamental level by binary blocks and even bytes while mapped text objects allow for easy management of large text file images.
A is a file self-contained piece of information available to the operating system and any number of individual programs to store related data. Information inside the file could consist of essentially anything but whatever the file contains is likely related somehow. In many cases, the file extension helps identify its content. For example, .txt is a file containing simple text while an .mp3 file contains encoded audio information.
A computer file can be thought of much like a traditional file that one would find in an office file cabinet. A file folder or directory contains individual or bound pages which could be considered a file. The cabinet itself can be considered a volume or disk drive. Unlike a paper file folder, files on a computer can become very large from just a few bytes to billions of bytes (gb). Whichever program creates and uses an individual file is responsible for understanding its contents. Similar types of files are said to be of a common “format” and in most cases, have similar extensions. Standard file formats and extensions exist for a wide variety of data.
Files generally have a path, a name and an extension. The path tells the system where the data is located. For example, C:\Windows\ means the file is located within the Windows folder on the C disk drive. When a path has a drive, UNC (Universal Naming Convention) or scheme and domain, the path is said to be “fully qualified”. There is no ambiguity as to where it is located (even if the programmer does not know the physical location) and it can be reliably accessed. Paths can also be related to another path, for example, “..\..\Data\MyFiles” says whatever my base path location is, move two branches up (..\..) and down “Data” and “MyFiles”. In the end, the system will resolve the path to a fully qualified location. Depending on the system and programmer, a filename is a name with or without an extension. Some systems and programs limit the names of files to a certain number of characters and types of characters (for example the SEC EDGAR System will only accept references to files with ‘a-z’, ‘0-9’ and a single ‘_’ or ‘-’). The extension is the last bit of trailing text after a period. For example: ‘myfile.thing.txt’ is considered a ‘txt’ or text file, not a ‘.thing.txt’ file.
Each individual file in Windows will also have file attributes which set specific conditions or requirements to access or use a file. For example, a file can be designated ‘read-only’ or ‘hidden’. In addition, files can have security access rights allowing or denying access to the file or folder containing files depending on the login user or process user’s authority. In addition, when a file is ‘opened’ or ‘created’, the ability of other users or programs to simultaneously access the file is also declared. This is called ‘file sharing’. It is up to the script to determine the level of allowed sharing and to manage conflicts.
Files in any operating system are stored on hard drives, optical drives, and other storage devices. The specific way a file is stored and organized is referred to as a file system. For Windows, the native system Legato runs under, there are local disk drives, removable storage (i.e., USB drives), network or remote connections and read-only devices such as CD or DVD drives. In addition to Windows types, Legato also supports VFC (Virtual File Cloud) files.
Most functions accept or return filenames and path names as 8-bit strings. The strings allow for UTF (Unicode Text Format) encoding for easy handing of extended character usage. For the most part, the encoding is completely transparent. However, if literal values are employed, caution should be exercised for any characters with values above 0xC0, when are then expected to be a UTF character sequence, not an ISO-8859 or ANSI character.
Whether from a high or low-level, files must be either created or opened in order to access or write data. Certain functions within Legato will open/create, process and close the file all within one action. For example, StringToFile will create the file, write the data and then close the file. For other actions, the file must be opened or created, then the script can act on the contents and when complete, the file is closed. In such a case, the script will receive a file handle or a higher-level object handle that, in turn, contains a file handle.
To create a file, a script can use the CreateFile function, then write data (for example WriteBlock) and later close the file using either CloseFile or CloseHandle. An example analog to StringToFile:
string text;
handle hFile;
int rc;
hFile = CreateFile("x:\\MyFiles\\Output.txt");
if (IsError(hFile)) {
rc = GetLastError();
MessageBox('x', "Error creating %08X", rc);
exit;
}
text = "Here is some text\r\nLine 2";
rc = WriteBlock(hFile, text);
if (IsError(hFile)) {
rc = GetLastError();
MessageBox('x', "Error writing %08X", rc);
exit;
}
CloseHandle(hFile);
Not only must the path be correct for the file to be created, the process running the script must have the access rights to actually write to the specified location.
| 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.