The %File class represents a disk file. It contains a
number of class methods that provide a number of file system
services.
For example,
If ##class(%File).Exists("file.txt") Write "It exists",!
You can also create an instance of a %File object that
represents a particular file. %File makes a number of file
attributes accessible as properties as well as providing a
%AbstractStream interface on the file.
For example,
Set file=##class(%File).%New("file.txt")
Write file.Size
Do file.Open("WSN")
Do file.WriteLine("This is a line of text")
Note that this class is a fairly simple wrapper around the ObjectScript file commands. For simply reading/writing to a file it is suggested that
you look at the %Stream.FileCharacter and
%Stream.FileBinary classes. These open the file using the
correct mode automatically in order to read or write to the file and so
are simpler to use.
The creation date for this file (rounded to the second). Only Windows
maintains the created date; other operating systems return the date
of the last file "status" change.
Return the attributes of the file.
The format of the returned value depends on the underlying operating system.
Microsoft Windows® returns a value as a combination of bits whose meaning is:
1: 0x00001 - Read-only
2: 0x00002 - Hidden
4: 0x00004 - System
8: 0x00008 - Unused
16: 0x00010 - Directory
32: 0x00020 - Archive
64: 0x00040 - Device
128: 0x00080 - Normal
256: 0x00100 - Temporary
512: 0x00200- Sparse File
1024: 0x00400 - Reparse Point
2048: 0x00800 - Compressed
4096: 0x01000 - Offline
8192: 0x02000 - Content Not Indexed
16384: 0x04000 - Encrypted
32768: 0x08000 - Unused
65536: 0x10000 - Virtual
In UNIX®, the returned value represents the mode map:
1: 0x0001 - execute permission for others
2: 0x0002 - write permission for others
4: 0x0004 - read permission for others
7: 0x0007 - mask for others permissions
8: 0x0008 - execute permission for group
16: 0x0010 - write permission for group
32: 0x0020 - read permission for group
56: 0x0038 - mask for group permissions
64: 0x0040 - execute permission for owner
128: 0x0080 - write permission for owner
256: 0x0100 - read permission for owner
448: 0x01C0 - mask for file owner permissions
512: 0x0200 - sticky bit
1024: 0x0400 - set groupid
2048: 0x0800 - set userid
4096: 0x1000 - fifo
8192: 0x2000 - character device
16384: 0x4000 - directory
24576: 0x6000 - block device
32768: 0x8000 - regular file
40960: 0xA000 - symbolic link
49152: 0xC000 - socket
61440: 0xF000 - mask for file type
Note: Individual Operating System vendor differences may exist.
The relevant man/help pages or other associated documentation
should be consulted for a definitive description of the file attributes
on a given system.
classmethod CanonicalFilename(filename As %String) as %String
Returns the canonical form of the filename. If the file can not be opened then it will return ""
Inherited description: Clear the contents of this Stream from permanent storage. This will remove the permanent stream storage and
any temporary stream and initialise the stream to its initial state that it starts in, including removing all
the stream attributes.
Returns a %Status value indicating success or failure.
Handle delete of cases where filename contains a wildcard.
Note: this does not delete subdirectories in the given directory; only files are removed.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
classmethod ComputeFullDBDir(filename As %String) as %String
Return the canonical form of the directory name filename.
When filename is a non-full path directory, it will prefix
the filename with Manager Path instead of current directory.
Pass in an array of paths you want to turn into a filename for the server platform, for example:
Set dirs($i(dirs))=$system.Util.DataDirectory()
Set dirs($i(dirs))="httpd"
Set dirs($i(dirs))="logs"
Set filename=##class(%File).Construct(dirs...)
If you want the name returned to be a directory terminated with a '/' or '\' then
pass in a null dirs entry as the last piece. You can also call
Deconstruct() with the returned filename to turn this back into
an array like dirs. If you pass in a blank array it will return the
default directory.
Copy a host directory from pSource to pTarget.
Parameter pOverlay
Parameter pDeleteBeforeCopy may be used to specify that any file that already exists in the target directory should be deleted before
being overwritten with the source file. The default is 0 or false.
This method returns true if it succeeds and false otherwise.
Note: (1) If the target directory exists and pOverlay is false (default), then the operation fails. Also, if any of the target files exist
and pDeleteBeforeCopy is false (default), then the operation may fail usually due to operating system characteristics.
(2) The total number of files or directories created/copied during the operation can be gotten by passing a byref value in pCreated.
Copy a host file from to host file to.
Parameter pDeleteBeforeCopy may be used to specify that if the target file already exists then it should be deleted before being overwritten
with the source file. The default is 0 or false.
This method returns true if it succeeds and false otherwise.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
Creates a directory with name name. Returns true if it succeeds and false otherwise.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
Create this directory and all the parent directories if they do not exist. This differs from
CreateDirectory() as that method only creates one new directory where as
this will create the entire chain of directories. Returns true if it succeeds and false otherwise.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
Given a directory name and the name of a new directory create this directory inside
the given directory. Return true if it succeeds and false otherwise.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
classmethod Deconstruct(filename As %String, ByRef dirs As %String)
Pass in a full valid filename for the server platform and it will decompose it into the dirs array
with each integer subscript being a part of the path, this array can then be passed into
Construct() to reconstruct the filename again. So on a Unix server you need to pass this a valid Unix filename
and on a Windows server this should be passed a Windows filename.
Deletes the file filename. Returns true if it succeeds and false otherwise.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
classmethod DirectoryExists(filename As %String) as %Boolean
Tests if filename is a directory.
returns 1 if it is a directory, otherwise, returns 0.
classmethod DriveListClose(QHandle As %Binary) as %Status
classmethod DriveListExecute(ByRef QHandle As %Binary, fullyqualified As %Boolean = 0) as %Status
classmethod DriveListFetch(ByRef QHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) as %Status
Returns true (1) if filename exists.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
Given a full directory and filename this will return just the directory portion of this name.
This is useful as the parsing of filenames on Unix/Windows is different.
Return the amount of total space and free space in either Bytes,MB,GB on a drive or directory
Name = Valid Drive or directory specification
Flag = 0 - Return bytes
Flag = 1 - Return MB (Default)
Flag = 2 - Return GB
MB and GB returned are rounded to 2 decimal places.
Any error status returned is O/S level error. Note that on Windows
only drives have a measurement for free space and directories can not so
the FreeSpace is only returned for drives.
Return the date created of file filename in $H format,
if the operating system supports it. Windows is the only current
platform that tracks the created date. Other systems return the date
of the last file "status" change.
By default this is local time. If you pass utc as true it returns it in UTC time.
The value is rounded to second precision.
Return the date last modified of file filename in $H format.
By default this is local time. If you pass utc as true it returns it in UTC time.
The value is rounded to second precision.
classmethod GetFileSHA256Hash(filename As %String) as %String
Given a full directory and filename this will return just the filename portion of this name.
This is useful as the parsing of filenames on Unix/Windows is different.
Returns the normalized form of the directory name filename.
If you pass directory then it will normalize this filename relative to the provided directory,
if no directory is supplied then it is relative to the current default directory.
addnull use is deprecated
classmethod NormalizeFilename(filename As %String, directory As %String = "") as %String
Returns the normalized form of the filename.
If you pass directory then it will normalize this filename relative to the provided directory,
if no directory is supplied then it is relative to the current default directory. If the
directory does not exist then this method will return the empty string. Otherwise, this method
returns the normalized full path name of the specified file.
classmethod NormalizeFilenameWithSpaces(pathname As %String) as %String
Normalize filenames containing spaces for the host platform.
Parameter
pathname : A filename or pathname.
Description
The NormalizeFilenameWithSpaces class method handles spaces in pathnames as appropriate
to the host platform.
If a pathname contains spaces NormalizeFilenameWithSpaces returns the pathname
enclosed in double quotes ("path name").
If a pathname does not contain spaces, the method returns it
unchanged. NormalizeFilenameWithSpaces performs no other pathname validation.
NormalizefilenameWithSpaces is commonly used with the $ZF() functions.
Note that this method does not perform the normalization actions of NormalizeFilename().
mode is a string containing one or more file modes including:
R
Read
W
Write
S
Stream mode
N
Create a new file (overwrite existing file)
Note that if the mode contains ':' characters this is a delimiter.
For example if the mode="RN:/SHARED" then it will open the file with the equivalent
of the COS command 'Open name:("RN":/SHARED):0'. The first piece before the
':' is quoted and the subsequent pieces are not.
A complete discussion of the available options for mode can
be found in the online documentation in the book,
I/O Devices Guide, specifically the chapter on Sequential File I/O.
classmethod ParentDirectoryName(directory As %String) as %String
Given a directory name, return the name of its parent directory.
If the directory is already the root (e.g., "/" on Unix, "c:\" on Windows), return the root.
classmethod ParseDirectoryClose(ByRef QHandle As %Binary) as %Status
classmethod ParseDirectoryExecute(ByRef QHandle As %Binary, directory As %String) as %Status
classmethod ParseDirectoryFetch(ByRef QHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) as %Status
Removes directory name. Returns true if it succeeds and false otherwise.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
classmethod RemoveDirectoryTree(pTarget As %String) as %Integer
Recursively remove directory pTarget. Returns true if it succeeds and false otherwise.
Rename file oldname to newname. Returns true if it succeeds and false otherwise.
The rename subfunction is only intended for changing the name of a regular file, not directories or other types of files.
In particular, renaming a file across filesystems results in copying and deleting the original file,
but this will not work for a directory. Renaming a directory within a file system does work.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
Return binary form of SHA1 hash on the file if type is 0 (the default).
If you want the string version then pass in type as 1. Note that if you already
have the file open in this process calling this function will close this file.
Set the OS specific attributes of the file.
See the Attribute method in this class for file attribute values.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
classmethod SetOwnerGroup(filename, OwnerGroup) as %Status
Set the Owner and Group of a file or directory.
This uses the unix "chown" command to perform the operation, and is valid only on Unix platforms.
Make this file/directory read only (if we can).
If leaveexisting is true then it will add read permissions to the
file/directory without changing the existing permissions, by default
it will remove all other permissions other than read only flags. The leaveexisting
has no effect on Windows so you do not need to pass this argument on this platform.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
Make this file/directory writable (if we can). The writeonly
defaults to true in which case this makes the file write only, if you just
want to add writable to the existing permissions without modifying the
other permissions pass writeonly=0. The writeonly
has no effect on Windows so you do not need to pass this argument on this platform.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
Given a directory name and the name of a sub directory create the name for the
subdirectory inside the given directory. Return the new directory name.
This is useful as the parsing of filenames on Unix/Windows is different.
Return a temporary filename in the OS provided temp directory or the directory
specified by dir.
If you specify ext the temp filename will have this extension.
Pass return by reference to obtain the low level return value in case of an error.
It will be the negative value of the operating system return code,
or 0 if there is no error.
In case of an error, the method returns an empty string.
Truncate an existing file or create a new empty file.
Pass return by reference to obtain the low level return value in case of errors
which is the negative value of the operating system return code.
This query was originally created to return Windows drive letters, hence its name.
Later it was extended to work on Unix.
Windows: return a list of available drives
Unix: return a list of mounted file systems
On Windows, if fullyqualified is true then the drive letters include the
trailing '\' character. The default is false; this is backward compatible and returns
'c:' on Windows. This does not affect the behavior on Unix.
query FileSet(directory As %String(MAXLEN=""), wildcards As %String, sortby As %String = "", includedirs As %Boolean = 0, delimiter As %String = ";")
Return the list of files in directory matching the pattern wildcards.
The sortby can be one of:
Name - the name of the file (the default)
Type - file type
DateCreated - the date the file was created (rounded to second)
DateModified - the date the file was last modified (rounded to second)
Size - the file size
The includedirs if true (default is 0) will force the list
of all directories to be returned before any files, the directories will ignore the pattern you supplied so it returns them all.
If it is false it will
return any files that match the pattern you give it, this may include directories if they match the pattern as well.
So true forces any directory to be included, but false does not exclude directories.
You may also specify the delimiter that is used to separate the wildcards
from each other, this defaults to ";".
query ParseDirectory(directory As %String(MAXLEN=""))