_file (Read/Write Files)

Description

_file is a JavaScript object which has a number of functions related to file handling. One of these functions is _file.fopen. This function opens a file for either reading or writing. It creates a new JavaScript object which is returned as the value of the function call. That object, in turn, has functions associated with it to read from and write to the file.

Semi-automatic File Path/Name Resolution

DocOrigin likes to discourage the use of hard-coded file paths. Consequently, we urge you to use the $X folder mappings as described in $X String Substitutions. Script functions with file or folder name parameters will automatically resolve those $X folder mapping references. That takes care of a large number of cases automatically.

However, if your file name parameter also uses the various % placeholders as described in File Naming Conventions, those % placeholders will not be automatically resolved. The user is expected to have control over their file names and should use _file.resolveName or _resolve if required when passing such templated file names to a script function.

Functions

_file.copy(fromFile, toFile)
Copy a file.
(As of 3.2.001.02) toFile can be just the destination directory, and not include the file name. fromFile cannot include wildcards. You copy one file at a time.
(As of 3.3.002.01 on Windows) The “to” parameter can handle the “prt::” prefix as well. The return value is the result code of the copy operation.
_file.date(fileName)Return the 'last modification date' of a file. The returned format is "yyyy/mm/dd hh:mm:ss". This can be used directly in a new Date(...) construct.
_file.delete(fileName)Delete a file.
(As of 3.0.005.07) The file name can contain wildcards. No error is issued if no such file exists.
_file.errno()Returns the last error code from a previous file operation.
_file.exists(fileName)(As of 3.0.005.07) Determine if the named file exists or not.
(As of 3.2.001.02) Supports file name wildcards (like "$E/*.prm").
_file.findClose()Terminate a wildcard file search.
_file.findNext(fileSpec[, directories])Begin or continue a wildcard file search. Returns "" at end-of-list.
_file.gets()Read a single line from the console.

Note that this is gets, not fgets. Do not confuse this with fp.fgets which reads from a file.
_file.fopen(fileName, fmode[, "BOM"])Open a file. Returns a file pointer object (fp). For write mode purposes you can force the writing of a BOM by supplying the optional third parameter with a value of BOM.
_file.fromBase64(base64, fileName)(As of 3.2.001.01) Decode a base64 string into a file. Use this for binary data with NULLs. Returns a Boolean value representing the operation's success/failure.

_file.getFileNamePart(fileName, part)Return a selected portion of a file name. Valid part names are: Full, Drive, Path, DrivePath, Name, Ext, NameExt, and NoExt. Note that DrivePath and NoExt require build 3.0.001.10 or greater. If the fileName does not have a full path, the full path will be computed based on current circumstances.

var f = "C:/DocOrigin/DO/Samples/empty.xml";
s = _file.getFileNamePart(f, "Full");      // "C:/DocOrigin/DO/Samples/empty.xml"
s = _file.getFileNamePart(f, "Drive");     // "C:"
s = _file.getFileNamePart(f, "Path");      // "/DocOrigin/DO/Samples"
s = _file.getFileNamePart(f, "DrivePath"); // "C:/DocOrigin/DO/Samples"
s = _file.getFileNamePart(f, "Name");      // "empty"
s = _file.getFileNamePart(f, "Ext");       // ".xml"
s = _file.getFileNamePart(f, "NameExt");   // "empty.xml"
s = _file.getFileNamePart(f, "NoExt");     // "C:/DocOrigin/DO/Samples/empty"

_file.getOpenFileName([folder], [title], [fileTypes], [defaultFile])Display the File>Open dialog. Returns the user-chosen file name. If the user clicks Cancel, null is returned.
_file.getSaveFileName([folder], [title], [fileTypes], [defaultFile])Display the File>Save dialog. Returns the user-chosen file name.
_file.getOpenFolderName([initFolder], [title])(As of 3.2.001.02) (Windows only) Display the Folder Open dialog. Returns the user-chosen folder name. If the user clicks Cancel, null is returned.
_file.isDir(dirPath)
(As of 3.0.005.07) Determine if the provided path is a directory or not.
_file.mkdir(dirPath)
Create a file directory.
(As of version 3.0.003.19) This will also handle multi-level paths such as "C:/A/B/C". Return codes: 0 (Ok), 1 (path was already there), -1 (a failure).
_file.readFile(fileName[, convertLineEndings])
Read the contents of fileName. Returns the file contents as a JavaScript string. If the file does not exist, null is returned.
(As of 3.2.001.01) convertLineEndings (defaults to true) requests line ending conversion from Windows to Unix (\r\n to \n). Note that not doing line-ending conversions may result in faster processing but newlines and linefeeds are left in the returned string.
_file.readIniFile(fileName)
Read an INI file. Returns a JavaScript object with all the data from the INI file.
_file.readPdfData(fileName)
(As of 3.0.003.13) Open a DocOrigin generated PDF and extract the embedded data. See the -{prt}option "-PDFembedData Yes". Returns a text string of the embedded-in-the-PDF XML data used to produce the document.
_file.readPrmFile(fileName)
Read a DocOrigin PRM file. The returned value will be a JavaScript object with name/value properties corresponding to the PRM file entries. If the file does not exist or is not properly formatted, null is returned.
_file.remove(fileName)
Synonym for the _file.delete function.
_file.rename(fromFile, toFile)
Rename a file. Returns 0 if successful. Note that you cannot change the path of the file, only its name.
_file.resolveName(template)
Do variable substitution into a template intended to be used as a file name. See _resolve for details. In this "file name template" context, [] references to fields which don't exist will be deleted.
_file.rmdir(directoryName)
Delete the specified directory (which must be empty).
_file.tempname(dir)
Create an empty temporary file and return its name as a string. Note that dir is ignored. On Windows, it uses the TMP environment variable. Under Unix, it uses the TMPDIR environment variable if it is set, otherwise, it uses /tmp. The folder pointed to by %TMP% or
$TMPDIR must exist. In either case, it uses an AtwTempFiles folder under the nominated temp folder; that subfolder is created automatically. Doing an _file.resolveName("$T/xxxx_%u.ext") may be a preferred option in that it gives you more control over the name of the file including its file extension. Use %u to ensure it has a unique name.
_file.toBase64(fileName)
(As of 3.1.002.10) Convert the contents of a file to a base64-encoded string.
_file.unzip(zipPath, destPath[, overwrite])
(As of 3.1.002.06) Extract files from a zip archive.
_file.writeFile(fileName, string [, "-BOM"] [, mode])
Writes string to the designated file. This function opens fileName for write (overwriting if necessary); writes the string, and closes the file. The output is always written in UTF8 format. Normally a BOM is written.
(As of 3.0.005.07) You can suppress that by supplying the optional third parameter with the value -BOM.
(As of 3.2.001.02) the mode parameter was introduced. Use the value a to initiate append mode (creates the file if it does not exist). The _file.writeFile function returns a Boolean true if successful and false if something went wrong.
_file.zip(zipPath, filePath[, addMode])
(As of 3.1.002.06) Add a file to the zip archive.

Description

Functions

See Also