File Functions¶
Naming a file system¶
Every function on this page works against the IMan server's own disk. Each will also take the Id of a File System setup as an optional first argument, and resolve the path against that S3 bucket, Blob container or OneDrive drive instead:
ReadTextFile("C:\IMan\Inbound\SO-10432.xml", False) ' the IMan server
ReadTextFile("aws", "inbound/SO-10432.xml", False) ' the bucket the "aws" setup names
The rest of the expression is the same whatever kind of storage the setup uses.
The function counts the arguments to tell whether you named a file system. Once
you name one, pass every other argument the function takes, including any that are
otherwise optional.
Base64EncodeFile
needs its throwonerror in this form and in no other. If you leave an argument out,
the function treats the call as a local one and reads the Id as the path.
ReadTextFile("aws", "inbound/SO-10432.xml") fails with "Type mismatch: The argument
[throwOnError] to function [ReadTextFile] could not be converted to [Boolean]".
Read that message as a missing argument. The two writers have nothing to convert, so
they do not fail: WriteTextFile("aws", "outbound/SO-10432.txt") writes a file called
aws on the IMan server.
Give it the Id, not the Description. Use the Id column on the
File Systems grid
(at most 12 characters), not the description that drop-downs elsewhere show you.
An Id that matches no setup raises "File System [Id] does not exist" from every
function, whatever its throwonerror argument says and however it treats a bad path.
An unknown Id is a mistake in the expression, not a missing file. FileExists does not
return False for it, and BuildPath, FileName and FilePath do not return it as a
result.
The path is relative to the location the setup points at. The bucket, container or drive comes from the setup, so the expression holds only the part of the path below it. Use that store's own separator. All three cloud types use forward slashes, and IMan converts any backslash you write into one.
You can reach an FTP or SSH server the same way, although FTP servers are not on
the File Systems screen. Prefix the Id of an
FTP Server setup with
ftp:, for example ftp:SUPPLIER for a server whose Id is SUPPLIER. The Id default
and an empty string both mean the IMan server itself, the same as leaving the argument
out.
BuildPath¶
Description
Appends a name to an existing path. The new path takes the form path\name.
Syntax
Arguments
- filesystem
- Optional. The Id of a File System setup. The function resolves the path against that setup rather than the IMan server's own disk. See Naming a file system.
- path
- A string holding a file path.
- name
- A string holding a subpath or a file name.
Example
' Joins a directory and a file name, inserting the
' separator.
BuildPath("C:\IMan\Outbound", %OrderNo & ".csv")
' Returns "C:\IMan\Outbound\SO-10432.csv"
' Through a File System setup, named first. The container
' comes from the setup, so the path is relative to it --
' and the separator is the one that store uses.
BuildPath("AZUREBLOB", "outbound", %OrderNo & ".csv")
' Returns "outbound/SO-10432.csv"
FileExists¶
Description
Returns True if the file named by the file argument exists, and False if not.
Syntax
Arguments
- filesystem
- Optional. The Id of a File System setup. The function resolves the path against that setup rather than the IMan server's own disk. See Naming a file system.
- file
- The full path of the file.
Example
' Returns False on any error with the file, including
' a bad path, rather than raising.
FileExists("C:\IMan\Inbound\" & %OrderNo & ".xml") ' Returns True or False
' The guarded read this is normally half of:
Dim f
f = BuildPath("C:\IMan\Inbound", %OrderNo & ".xml")
IIf(FileExists(f), ReadTextFile(f, False), "")
' The same guard against the bucket the "aws" setup
' names. ReadTextFile still needs its throwOnError
' argument, or the Id is read as the path.
Dim k
k = BuildPath("aws", "inbound", %OrderNo & ".xml")
IIf(FileExists("aws", k), ReadTextFile("aws", k, False), "")
FileName¶
Description
Returns the file name from a path.
Syntax
Arguments
- filesystem
- Optional. The Id of a File System setup. The function resolves the path against that setup rather than the IMan server's own disk. See Naming a file system.
- filepath
- The full path of the file.
Example
' The file portion of a path, extension included.
FileName("C:\IMan\Outbound\SO-10432.csv") ' Returns "SO-10432.csv"
' Naming a File System splits the path by that store's
' rules rather than the IMan server's -- here an object
' key in a Blob container.
FileName("AZUREBLOB", "outbound/2026/SO-10432.csv") ' Returns "SO-10432.csv"
FilePath¶
Description
Returns the path from a file path.
Syntax
Arguments
- filesystem
- Optional. The Id of a File System setup. The function resolves the path against that setup rather than the IMan server's own disk. See Naming a file system.
- filepath
- The full path of the file.
ReadTextFile¶
Description
Reads the contents of a text file.
Syntax
Arguments
- filesystem
- Optional. The Id of a File System setup. The function resolves the path against that setup rather than the IMan server's own disk. See Naming a file system.
- filepath
- The full path of the file.
- throwonerror
- When False, the function returns an empty string in place of raising an error if it cannot open or read the file. You cannot leave it out when you name a file system, because a call with two arguments always reads from the IMan server.
Example
' Reads the whole file as UTF-8. The last argument is
' throwOnError: False returns an empty string for a
' missing or unreadable file and the integration
' continues; True fails the record.
ReadTextFile("C:\IMan\Inbound\" & %OrderNo & ".xml", False)
' Through a File System setup, named first -- here the
' AWS S3 bucket the "aws" setup points at. The bucket
' comes from the setup, so the path is the object key
' within it.
ReadTextFile("aws", "inbound/" & %OrderNo & ".xml", True)
' And from an SFTP server, by prefixing the Id of an FTP
' Server setup with "ftp:".
ReadTextFile("ftp:SUPPLIER", "/outbound/" & %OrderNo & ".xml", True)
WriteBinaryValue¶
Description
Writes the value of a binary field to the specified path. If the file exists, the function overwrites it.
Syntax
Arguments
- filesystem
- Optional. The Id of a File System setup. The function resolves the path against that setup rather than the IMan server's own disk. See Naming a file system.
- filepath
- The path to write the field's contents to.
- fieldId
- The binary field's name. If the field is not of the Binary type, the function raises an error.
Example
' Writes a BINARY field's value to a file -- use it to
' land an attachment that arrived inside the dataset. If
' the field is not set, nothing is written and no error
' is raised.
WriteBinaryValue("C:\IMan\Outbound\" & %OrderNo & ".pdf", "DocumentImage")
' Through a File System setup, named first -- here the
' OneDrive for Business drive the "ONEDRIVE" setup names.
WriteBinaryValue("ONEDRIVE", "Invoices/" & %OrderNo & ".pdf", "DocumentImage")
WriteTextFile¶
Description
Writes to a text file. If the file exists, the function overwrites it.
Syntax
Arguments
- filesystem
- Optional. The Id of a File System setup. The function resolves the path against that setup rather than the IMan server's own disk. See Naming a file system.
- filepath
- The full path of the file.
- data
- The data to write to the file.
Example
' Writes text, overwriting the file if it exists. No
' byte-order mark is written, which matters to ERP
' importers that treat one as data.
WriteTextFile("C:\IMan\Outbound\" & %OrderNo & ".txt", %OrderNo & "," & %CustomerCode)
' The same line written into the Blob container the
' "AZUREBLOB" setup names, under an "outbound" prefix.
WriteTextFile("AZUREBLOB", "outbound/" & %OrderNo & ".txt", %OrderNo & "," & %CustomerCode)