Home > Class Reference > ENSLIB namespace > %Library.File


stream class %Library.File extends %Library.AbstractStream

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 Caché 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.

Property Inventory

Method Inventory


property CanonicalName as %String (MAXLEN = 5000) [ Calculated ];
Read only property that returns the canonical filename if the file is open and "" if the file is not open. On VMS this will include the file version number
Property methods: CanonicalNameDisplayToLogical(), CanonicalNameGet(), CanonicalNameIsValid(), CanonicalNameLogicalToDisplay(), CanonicalNameLogicalToOdbc(), CanonicalNameNormalize()
property DateCreated as %Date [ Calculated ];
The creation date for this file (rounded to the second).
Property methods: DateCreatedDisplayToLogical(), DateCreatedGet(), DateCreatedIsValid(), DateCreatedLogicalToDisplay(), DateCreatedLogicalToOdbc(), DateCreatedNormalize(), DateCreatedOdbcToLogical()
property DateModified as %Date [ Calculated ];
The last modified date for this file (rounded to the second).
Property methods: DateModifiedDisplayToLogical(), DateModifiedGet(), DateModifiedIsValid(), DateModifiedLogicalToDisplay(), DateModifiedLogicalToOdbc(), DateModifiedNormalize(), DateModifiedOdbcToLogical()
property IsOpen as %Boolean [ InitialExpression = 0 ];
True (1) if this file is currently open, false (0) otherwise.
Property methods: IsOpenDisplayToLogical(), IsOpenGet(), IsOpenIsValid(), IsOpenLogicalToDisplay(), IsOpenNormalize(), IsOpenSet()
property Name as %String (MAXLEN = 5000);
The name of this file.
Property methods: NameDisplayToLogical(), NameGet(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()


classmethod Attributes(filename As %String) as %String
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

On OpenVMS, this is the file protection presented as four 4-bit fields, accessed by the following hexadecimal masks:

  • 000F: system privileges
  • 00F0: owner privileges
  • 0F00: group privileges
  • F000: world privileges
where each of these subfields has bit values with the following meanings:
  • 1: no read access
  • 2: no write access
  • 4: no execute access
  • 8: no delete access

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
VMS specific function, returns the canonical form of the filename, on VMS this will include the version number. If the file can not be opened then it will return ""
method CanonicalNameGet() as %String
method Clear() as %Status
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.

method Close()