class Ens.Util.File extends %Library.RegisteredObjectThis class provides utility methods related to File operations.
pSemaphoreSpec is of the form TargetPattern=SemaphorePattern with multiple ; separated e.g.
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 ('-').
- 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 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.
The timestamp string returned always reflects the current time, converted to the timezone specified using the %K format code.