Skip to main content

Time Stamp Specifications for Filenames

Provides reference information for time stamp specifications for filenames.

Details

While configuring business operations and business services that transmit data to and from files, you can often specify input and output filenames in a string that includes date and time format codes, such as %Y%m%d%H%M%s_%f.txt. At runtime, the format codes within this string resolve dynamically based on the current date and time.

InterSystems IRIS ® data platform supports the following rules for composing a time stamp specification string:

  • The string may contain literal characters and any of the format codes listed in the following table.

  • Characters that are not part of a format code appear in the resulting time stamp unchanged.

  • All format codes are optional.

  • Each format code consists of a % character, an optional # character, and a conversion character.

  • InterSystems IRIS converts the time to a specific time zone or locale if the %K or %L format codes appear at the beginning of the string.

Symbol Meaning Within a Filename Specification
%a Locale’s abbreviated weekday name (Sun, Mon, ..., Sat)
%A Locale’s full weekday name (Sunday, Monday, ..., Saturday)
%b Locale’s abbreviated month name (Jan, Feb, ..., Dec)
%B Locale’s full month name (January, February, ..., December)
%c

InterSystems IRIS date and time representation as provided by the local machine, except that in forming the time stamp, InterSystems IRIS replaces certain characters in the usual date and time format. It replaces spaces with underscores (_), slashes (/) with hyphens (-), and colons (:) with dots (.).

The result is something like:

MM-DD-YY_hh.mm.ss

The %c specifier can have parameters. %c(dformat,tformat,precision) formats the date and time according to your specifications, where:

  • dformat is a number indicating date format.

  • tformat is a number indicating time format.

  • precision is the number of decimal places used to represent subseconds.

See $ZDATETIME for a list of all possible dformat and tformat values.

%d Two digits indicating the day of the month (01-31)
%#d Day of the month without leading zeros (1-31)
%D Date; equivalent to %m/%d/%y
%#D Date; equivalent to %#m/%#d/%y
%f

Name indicating the source of the data. The source is usually the input filename (for File and FTP) or a concatenation of the IP address and port number (for data that arrived via TCP).

In substituting a value for the format code %f, InterSystems IRIS strips out any of the characters |,?,\,/,:,[,],<,>,&,,,;,NUL,BEL,TAB,CR,LF, replacing spaces with underscores (_), slashes (/) with hyphens (-), and colons (:) with dots (.).

%#f

Only use the part of the input filename up to but not including the last period. For example:

  • With Input filename “Summary.docx”, %#f is replaced with “Summary”.

  • With input filename “MyData.txt.dat”, %#f is replaced with “MyData.txt”.

%$f Only use the part of the input file name from the last period to the end of the filename (the file extension). For example, if the input filename is “MyData.txt.dat”, %$f is replaced with “.dat”.
%F As for %f, but with all alphabetic characters converted to uppercase.
%#F As for %#f, but with all alphabetic characters converted to uppercase.
%$F As for %$f, but with all alphabetic characters converted to uppercase.
%h Locale’s abbreviated month name. Equivalent to %b.
%H Two digits indicating the hour in 24-hour format (00-23)
%#H Hour in 24-hour format without leading zeros (0-23)
%I Two digits indicating the hour in 12–hour format (01-12)
%#I Hour in 12–hour format without leading zeros (1-12)
%j Three digits indicating the day of the year as a number (001-366)
%#j Day of the year as a number without leading zeros (1-366)
%K(n)

Use the %K(n) format code only at the beginning of the time stamp specification string. %K(n) produces no output, but specifies a base time zone to convert to before formatting the time stamp.

n is the time zone, and can be one of the following (case-insensitive):

  • Server — (Default) Time on the server where the executing code resides.

  • UTC — Universal Time Coordinated (UTC)

  • [+]n — Number of hours after (east of) UTC time. n may have a fractional value expressed as a decimal; for example, 4.5

  • -n — Number of hours before (west of) UTC time (n may be fractional)

  • [+]hhmm — Hours and minutes after (east of) UTC time, in the ISO 8601:2000 standard format

  • -hhmm — Hours and minutes after (west of) UTC time in ISO format

%m Two digits indicating the month number (01-12)
%#m Month number without leading zeros (1-12)
%M Two digits indicating minutes (00-59)
%#M Minutes without leading zeros (0–59)
%N Three digits indicating the number of milliseconds (000-999)
%p Locale’s a.m. or p.m. indicator for a 12-hour clock (lowercase, with dots)
%#p Locale’s am or pm indicator for 12-hour clock (lowercase, without dots)
%P Locale’s A.M. or P.M. indicator for a 12-hour clock (uppercase, with dots)
%#P Locale’s AM or PM indicator for a 12-hour clock (uppercase, without dots)
%q or %q() HL7 format date and time; equivalent to %Y%m%d%H%M%S or %q(0)
%q(0) HL7 format date and time; equivalent to %Y%m%d%H%M%S or %q
%q(1) ODBC format date and time; equivalent to %Y-%m-%d %H:%M:%S.%N
%q(2) ISO 8601:2000 standard date format; equivalent to %Y-%m-%d
%q(3) InterSystems IRIS $HOROLOG format
%q(4) InterSystems IRIS $ZTIMESTAMP format
%q(5) Creates a GUID
%Q ODBC format date and time; equivalent to %Y-%m-%d %H:%M:%S.%N or %c(3,,3) or %q(1)
%Q(n) Equivalent to %q(n)
%r Time with seconds in 12-hour format using a.m. or p.m. notation; equivalent to %I:%M:%S %p
%#r Time with seconds in 12-hour format using am or pm notation without whitespace or dots; equivalent to %I:%M:%S%#p
%R Time in 24-hour notation; equivalent to %H:%M
%S Two digits indicating seconds (00-60) (60 for leap seconds)
%t Produces a <tab> character
%T Time with seconds in 24-hour notation; equivalent to %H:%M:%S
%u Day of the week as a number (1-7). Monday=1, Tuesday=2, ..., Sunday=7.
%#u Equivalent to %u
%U

Two digits (00–53) indicating the current week within a week-based year convention that does not conform to the ISO 8601:2000 standard.

The rules are as follows:

  • The week numbers are 00-53

  • Sunday is the first day in each week.

  • The first Sunday of January is the first day of week 1

  • Days in the new year before the first Sunday are in week 0.

%#U Number indicating the current week within a week-based year that follows the rules described for %U, except the output does not include leading zeros (0-53).
%w Day of the week (Sunday=0, Monday=1, ..., Saturday=6)
%#w Equivalent to %w
%W

Two digits (00–53) indicating the current week within a week-based year convention that does not conform to the ISO 8601:2000 standard.

The rules are as follows:

  • The week numbers are 00-53

  • Monday is the first day in each week

  • The first Monday of January is the first day of week 1

  • Days in the new year before the first Monday are in week 0.

%W is equivalent to %U(1).

%#W Number indicating the current week within a week-based year that follows the rules described for %W, except the output does not include leading zeros (0-53). %#W is equivalent to %#U(1).
%y Two digits indicating the year within a century (00-99). For example, the year 1983 produces the number 83 in the time stamp; 2019 produces 19.
%Y Four digits indicating the year (0000-9999)
%z Time zone as an offset from Universal Time Coordinated (UTC) in the ISO 8601:2000 standard format (+hhmm or -hhmm). For example, -0430 means 4 hours 30 minutes behind UTC (west of Greenwich). If InterSystems IRIS cannot determine the time zone, it ignores the %z code in the time stamp specification string.
%#z Time zone as an offset from Universal Time Coordinated (UTC) in hours with leading +/- and without leading zeros. Trailing decimals may appear. For example, -4.5 means 4 hours 30 minutes behind UTC (that is, west of Greenwich). If InterSystems IRIS cannot determine the time zone, it ignores the %#z code in the time stamp.
%+(nn)

Inserts a counter and tests for filename uniqueness on a local file (not FTP) where nn is a string of alphanumerics and other characters. The alphanumeric characters in the string are incremented from the right-most character. Nonalphanumeric characters are included unchanged in the output file specification. Numeric characters are incremented from 0 to 9 and alphabetic characters are incremented from a to z or from A to Z.

For example, if the filename string specification is “%f_%+(1)” and the input file is “NewFile.txt”, then InterSystems IRIS first checks if “NewFile.txt_1” exists. If it exists, it checks “NewFile.txt_2” through “NewFile.txt_9” and then “NewFile.txt_10” and so on. It creates the file with the first filename that doesn’t yet exist.

If the filename string is “%f_%+(a.1), it first increments the 1 digit and then, after reaching 9, it increments the a; first testing the strings “NewFile.txt_a.1” through “NewFile.txt_a.9” and then “NewFile.txt_b.0” through “NewFile.txt_b.9” and then “NewFile.txt_c.0” and so on. After it reaches “NewFile.txt_z.9”, it prepends an 1 to the string. In this case, it tests “NewFile.txt_1a.0” next.

Typically, the counter is used in conjunction with a timestamp to reduce the possibility that filenames are duplicates even if they are created with the same timestamp. Combining a timestamp with a counter makes it extremely unlikely that filename collisions will occur.

You can use the %+ counter specification only once within a filename specification.

The counter format can be modified by inserting any of the following symbols between the percent sign and the plus sign:

  • Dollar sign ($)—Allows the counter to be used for remote FTP filenames. Always increment a static counter and use the resulting value. For local files, the uniqueness check is then made.

  • Exclamation point (!)—Only append the counter if the filename without the counter would not be unique.

  • Number sign (#)—Omit leading zeroes and omit leading a’s if they are not required to make a unique filename.

If the dollar sign ($) is not specified, the counter always restarts from the initial value specified in nn. If used with a timestamp, the counter is typically incremented a small number of times before a new timestamp value ensures uniqueness. If you are using the counter without a timestamp and expect it to be incremented many times, you should specify the dollar sign to avoid continually rechecking the filenames that you have already created.

Consider the format “%#F_%Q_%+(a0)%$f”. If the input filename is “NewFile.txt” and three files are created with the same timestamp, these files are named:

  • NEWFILE_2014-09-12_16.43.15.895_a0.txt

  • NEWFILE_2014-09-12_16.43.15.895_a1.txt

  • NEWFILE_2014-09-12_16.43.15.895_a2.txt

%% Literal % percent sign
%( Literal ( left parenthesis
%_ Reserved token (do not use). This sequence passes through unchanged.

The previous table describes all the format codes that you can use when specifying time stamps for use with an inbound or outbound file adapter. These codes conform to POSIX, IEEE, and ISO standards for time format codes. The following table lists the time stamp format codes that do not conform to these standards, or that conform to other standards.

Symbol Unique Meaning Within a Filename Specification
%# InterSystems IRIS® supports (and extends) certain Microsoft extended semantics, such as the %# prefix.
%c This indicates the InterSystems IRIS time stamp provided by the local machine.
%E InterSystems IRIS does not support the %E code.
%F InterSystems IRIS supports %F as an uppercase replacement string, not an ISO format date. InterSystems IRIS supports the ISO format date as %q(2) or %Q(2).
%K(n) The user defines the time zone by providing the %K(n) code at the beginning of the file specification string. The %K(n) code produces no output, but specifies a base time zone to convert to before formatting the time stamp.
%L(n) The user defines the locale by providing the %L(n) code at the beginning of the file specification string. The %L(n) code produces no output, but specifies a base locale to use with locale-dependent format codes.
%O InterSystems IRIS does not support the %O code.
%P InterSystems IRIS defines this code as uppercase AM or PM.
%q,%Q InterSystems IRIS defines some of these codes according to standards other than POSIX, IEEE, or ISO, such as HL7 or ODBC.
%( InterSystems IRIS defines this code as a literal ( character.
FeedbackOpens in a new tab