time Formats

Specifying the format of a time field that is passed as a parameter to a conversion.

Four conversions, string_from_time, ustring_from_time, time_from_string, and ustring_from_time, take as a parameter of the conversion a time format or a time uformat. These formats are described below. The default format of the time contained in the string is hh:mm:ss.

time Uformat

The time uformat date format provides support for international components in time fields. It's syntax is:


 String % macroString % macroString % macroString

where %macro is a time formatting macro such as %hh for a two-digit hour. See time Format below for a description of the time format macros. Only the String components of time uformat can include multi-byte Unicode characters.

time Format

The string_from_time and time_from_string conversions take a format as a parameter of the conversion. The default format of the time in the string is hh:mm:ss. However, you can specify an optional format string defining the time format of the string field. The format string must contain a specification for hours, minutes, and seconds.

The possible components of the time_format string are given in the following table:

Table 1. Time format tags
Tag	Variable width availability	Description	Value range	Options
%h	import	Hour (24), variable width	0...23	s
%hh		Hour (24), fixed width	0...23	s
%H	import	Hour (12), variable width	1...12	s
%HH		Hour (12), fixed width	01...12	s
%n	import	Minutes, variable width	0...59	s
%nn		Minutes, fixed width	0...59	s
%s	import	Seconds, variable width	0...59	s
%ss		Seconds, fixed width	0...59	s
%s.`N`	import	Seconds + fraction (`N` = 0...6)	–	s, c, C
%ss.`N`		Seconds + fraction (`N` = 0...6)	–	s, c, C
%SSS	with v option	Milliseconds	0...999	s, v
%SSSSSS	with v option	Microseconds	0...999999	s, v
%aa	German	am/pm marker, locale specific	am, pm	u, w

By default, the format of the time contained in the string is %hh:%nn:%ss. However, you can specify a format string defining the format of the string field.

You must prefix each component of the format string with the percent symbol. Separate the string's components with any character except the percent sign (%).

Where indicated the tags can represent variable-fields on import, export, or both. Variable-width date elements can omit leading zeroes without causing errors.

The following options can be used in the format string where indicated:

s: Specify this option to allow leading spaces in time formats. The s option is specified in the form:; %(tag,s); Where tag is the format string. For example:; %(n,s); indicates a minute field in which values can contain leading spaces or zeroes and be one or two characters wide. If you specified the following date format property:; %(h,s):$(n,s):$(s,s); Then the following times would all be valid:; 20: 6:58; 20:06:58; 20:6:58

v: Use this option in conjunction with the %SSS or %SSSSSS tags to represent milliseconds or microseconds in variable-width format. So the time property:; %(SSS,v); represents values in the range 0 to 999. (If you omit the v option then the range of values would be 000 to 999.)

u: Use this option to render the am/pm text in uppercase on output.

w: Use this option to render the am/pm text in lowercase on output.

c: Specify this option to use a comma as the decimal separator in the %ss.N tag.

C: Specify this option to use a period as the decimal separator in the %ss.N tag.

The c and C options override the default setting of the locale.

The locale for determining the setting of the am/pm string and the default decimal separator can be controlled through the locale tag. This has the format:

%(L,'locale')

Where locale specifies the locale to be set using the language_COUNTRY.variant naming convention supported by ICU. The default locale for am/pm string and separators markers is English unless overridden by a %L tag or the APT_IMPEXP_LOCALE environment variable (the tag takes precedence over the environment variable if both are set).

Use the locale tag in conjunction with your time format, for example:

%L('es')%HH:%nn %aa

Specifies the Spanish locale.

The format string is subject to the restrictions laid out in the following table. A format string can contain at most one tag from each row. In addition some rows are mutually incompatible, as indicated in the 'incompatible with' column. When some tags are used the format string requires that other tags are present too, as indicated in the 'requires' column.

Table 2. Format tag restrictions
Element	Numeric format tags	Text format tags	Requires	Incompatible with
hour	%hh, %h, %HH, %H	-	-	-
am/pm marker	-	%aa	hour (%HH)	hour (%hh)
minute	%nn, %n	-	-	-
second	%ss, %s	-	-	-
fraction of a second	%ss.N, %s.N, %SSS, %SSSSSS	-	-	-

You can include literal text in your date format. Any Unicode character other than null, backslash, or the percent sign can be used (although it is better to avoid control codes and other non-graphic characters). The following table lists special tags and escape sequences:

Tag	Escape sequence
%%	literal percent sign
\%	literal percent sign
\n	newline
\t	horizontal tab
\\	single backslash

Converting Time Fields to Integers Example

The following figure shows the conversion of time field to two 8-bit integers, where:

The hours_from_time conversion specification extracts the hours portion of a time field and writes it to an 8-bit integer
The minutes_from_time conversion specification extracts the minutes portion of a time field and writes it to an 8-bit integer.

The following osh code converts the hours portion of tField to the int8 hoursField and the minutes portion to the int8 minField:


modify 'hoursField = hours_from_time(tField);
minField = minutes_from_time(tField);'