File and Directory Functions

The following file and directory functions return information regarding their status.

To access a file in the internal File Storage, specify an absolute file path using the //ICAMFS/ universal file descriptor (e.g., “//ICAMFS/O9001”). Files in the internal File Storage area are read-only.

The $FACCESS Function

Get file access information Returns: Logical

The $FACCESS function returns $TRUE if the specified file or directory path is accessible. If the optional mode argument is omitted, the function tests for both read and write access. To check a specific access type, supply a mode value from the table below.

$FACCESS returns $FALSE if the path is invalid, does not exist, or the file does not support the requested access rights.

The following mode values are supported. Note that Windows file systems cannot differentiate the “run” access type:

0:

File exists?

1:

File can be run?

2:

File can be written?

3:

File can be written or run?

4:

File can be read?

5:

File can be read or run?

6:

File can be written or read? (default)

7:

File can be written, read or run?

The $FBASNAM Function

Return file name portion of path string Returns: String

The $FBASNAM function extracts the file name from a path string, optionally stripping a trailing suffix. For example, given the path C:\temp\test.cld, the base name is test.cld.

If a suffix is specified, the function finds the last occurrence of that string within the file name and removes it along with everything that follows. For example, specifying "." as the suffix would return test from the path above. Note that suffix matching is case-sensitive.

The $FCTIME Function

Convert numeric time value to date and time string Returns: String

The $FCTIME function converts a numeric time-val — representing the number of seconds elapsed since the operating system's “epoch” — into a human-readable date and time string. It is particularly useful for formatting time values returned by the $FSTAT function.

The return value uses the following format, with a single space separating the date and time portions:

dd-mm-yyyy hh:mm:ss

The $FDIRNAM Function

Return directory portion of path string Returns: String

The $FDIRNAM function extracts the directory portion from a path string. If the path contains no directory information, an empty string is returned.

The $FEOF Function

Test for end-of-file Returns: Logical

The $FEOF function returns $TRUE if the specified unit is positioned at the end-of-file mark, and $FALSE otherwise. Use this function to check the end-of-file status of a text file unit before attempting to read from it. If the specified unit has not been opened with the OPEN command, an error is reported.

The $FGETCWD Function

Get current working directory Returns: String

The $FGETCWD function returns the current working directory as a string. This is typically the directory from which CERUN was run.

The $FSETCWD Function

Set current working directory Returns: String

The $FSETCWD function changes the current working directory to the specified path and returns the new working directory as a string. If path does not include a directory component, the current working directory is unchanged and its path is returned.

The $FSTAT Function

Get file status information Returns: Numeric

The $FSTAT function returns statistics about the file or directory specified by path, with the type argument selecting which statistic to return. The type string is case-insensitive and may be abbreviated, though “m” resolves to modification time rather than file mode.

The following values are supported for type:

size:

File size in bytes

atime:

Time of last file access

ctime:

Time of last file status change (typically creation time)

mtime:

Time of last file modification

mode:

File mode (operating system specific)

owner:

Numeric ID of owner

group:

Numeric ID of file group

Date values are returned as the number of seconds since the operating system's “epoch”. Use the $FCTIME function to convert these to a human-readable string.

File mode information is operating system specific; use the $FACCESS function to determine file access rights instead. Ownership information is unavailable on Windows file systems and returns zero.

The $FTMPFILE Function

Create temporary file Returns: String

The $FTMPFILE function creates a uniquely named temporary file in the system's default temporary directory and returns its full path. The file is automatically deleted when CERUN processing completes.

If the optional filename argument is specified, the temporary file is created as a copy of that file. To copy a file from internal File Storage, specify its path using the //ICAMFS/ universal file descriptor (e.g., “//ICAMFS/O9001”).