Skip to main content


class Ens.Util.File extends %Library.RegisteredObject

This class provides utility methods related to File operations.

Method Inventory


classmethod CorrespondingSemaphoreExists(pTargetFile As %String, pSemaphoreSpec As %String, pDirectory As %String, ByRef pSemaphoreFile As %String, ByRef pStatus As %Status) as %Boolean
Identify if a semaphore file exists for a target file based on a series of target/semaphore specification
pSemaphoreSpec is of the form TargetPattern=SemaphorePattern with multiple ; separated e.g.
classmethod CreateTimestamp(pFilename As %String = "", pSpec As %String = "%f_%Q", pIsVMS As %Boolean = $$$isVMS, pDirectory As %String = "", pLocal As %Boolean = 1, pCharactersToRemove As %String = {"|?\/:[]<>&,;"_$C(0, 7, 9, 10, 13)}) as %String
Transform the given filename pFilename according the the timestamp and uniqueness construction specification string pSpec. The pSpec argument consists of literal characters and zero or more format codes. A format code is preceded by a percent sign (%); characters that are not part of a format code are output unchanged.
Timestamp format codes are documented in the method FormatDateTime() in class Ens.Util.Time
. In addition the following filename-related enhancements are supported:
  • In the final output string, spaces (' ') are replaced by underbars ('_'), slashes ('/') replaced by hyphens ('-') and colons (':') replaced by dots ('.'), except on VMS where both slashes ('/') and colons (':') are instead replaced by hyphens ('-') unless the pFilename argument is just %f and the empty string is specified for the pCharactersToRemove parameter.
  • The pFilename input argument is stripped of the characters (|,?,\,/,:,[,],<,>,&,,,;,NUL,BEL,TAB,CR,LF) before being inserted as replacement text for the %f and %F format codes. The sixth parameter pCharactersToRemove can be specified to use a different set of characters to strip.
  • The additional format code '+' is supported to guarantee filename uniqueness by incrementing a counter string. This additional code is supported in the following forms, where nn is an alphanumeric counter string of 0 or more characters:
    • %+(nn) - If pLocal is true, increment nn until the generated filename does not exist in the target directory specified by pDirectory
    • %#+(nn) - If pLocal is true, increment nn omitting leading non-significant 0/a characters
    • %!+(nn) - If pLocal is true, only use nn if the base filename already exists
    • %#!+(nn) or %!#+(nn) - If pLocal is true, omit nn if the filename without it does not exist already, otherwise use nn but omit leading non-significant 0/a characters within it
    • %$+(nn) - increment nn without testing for existence of the resulting filename; if pLocal is true then re-increment while the resulting filename exists
    • %#$+(nn) or %$#+(nn) - increment nn regardless without testing for existence, omitting leading non-significant 0/a characters

    • Thus the '#' character means to output only the rightmost significant (non-zero,non- a/A) alphanumeric characters, the '!' means to only use nn if needed to create a unique local filename, and '$' means to increment nn for each call regardless of the local filesystem. The '$' form can be used to generate a series of filenames on a local or remote filesystem. This form relies on a counter variable in $$$EnsStaticAppData("Ens.Util.File:CreateTimestamp").
      The counter string nn may also contain non-alphanumeric characters. If these are present they are output unchanged as literal characters. To ensure a unique filename, first the filename including string nn is checked for existence, and if that already exists the string is incremented in its rightmost alphanumeric character first. Digits are incremented in the range 0-9, and alphabetic characters are incremented in the ranges a-z and A-Z. If the entire range represented by nn is exhausted, additional digits/letters will be prepended as needed.
    For example, the string %F_%Q_%!#+(.a1) means the input filename is returned with a timestamp appended, and if a file like that already exists then .1 is further appended, and if that also exists already then .2 is appended, and so on, up to .9, then to .a1, then up to .z9, and beyond that to .az1 and so on. Only one '%+' format code is supported in a given format spec string.
    The timestamp string returned always reflects the current time, converted to the timezone specified using the %K format code.
classmethod FileLikePattern(pTargetFile As %String, pTargetPattern As %String, ByRef pStatus As %Status) as %Boolean
Compares a string with a pattern containing wildcards * and ?
classmethod GenerateSemaphoreFilename(pTargetFile As %String, pSemaphorePattern As %String, ByRef pStatus As %String) as %String
Generates a filename for a semaphore based on a target file name and a pattern that contain * wildcards
classmethod LinkFileStream(pFilename As %String, Output pStream As %FileBinaryStream) as %Status
Create a %FileBinaryStream from the specified file name
classmethod NormalizeDirectory(pFilename As %String) as %String
Return the normalized path string for pFilename.
classmethod SemaphoreFileExists(pTargetFile As %String, pDirectory As %String, pSemaphorePattern As %String, ByRef pSemaphoreFile As %String, ByRef pStatus) as %Boolean
Identifies if a semaphore for a given file exists based on given file name and semaphore pattern.
classmethod fixPath(pPath As %String) as %String
Append '/' to pPath if it is missing and we are not running on VMS.

Inherited Members

Inherited Methods


FeedbackOpens in a new tab