CEEFTDS—Format time and date into character string

CEEFTDS, analogous to the C function strftime(), converts the internal time and date to character strings according to the specifications passed to it by the TD_STRUCT. These specifications work in conjunction with the format conversions set in the current locale. The current locale's LC_TIME category affects the behavior of this service, including the actual values for the format specifiers. CEEFTDS is sensitive to the locales set by setlocale() or CEESETL, not to the Language Environment settings from COUNTRY or CEE3CTY.

Syntax

>>-CEEFTDS--(--omitted_parm--,--time_and_date--,--maxsize--,---->

>--format--,--stringout--,--fc--)------------------------------><

omitted_parm

This parameter is reserved for future expansion and must be omitted. For information about how to code an omitted parm, see Invoking callable services.

time_and_date (input)

Points to the time structure that is to be converted. The structure has the following format:

td_sec

A 4-byte integer that describes the number of seconds in the range of 0 through 59.

td_min

A 4-byte integer that describes the number of minutes in the range of 0 through 59.

td_hour

A 4-byte integer that describes the number of hours in the range of 0 through 23.

td_mday

A 4-byte integer that describes the day of the month in the range of 1 through 31.

td_mon

A 4-byte integer that describes the month of the year in the range of 0 through 12.

td_year

A 4-byte integer that describes the year of an era.

td_wday

A 4-byte integer that describes the day of the week in the range of 0 through 6.

td_yday

A 4-byte integer that describes the day of the year in the range of 0 through 365.

td_isdst

A 4-byte integer that is a flag for daylight savings time.

maxsize (input)

A 4-byte integer that specifies the maximum length (including the string terminator) of the string that can be placed in stringout.

format (input)

A halfword length-prefixed character string (VSTRING) of 256 bytes that contains the conversion specifications. The format parameter is a character string containing two types of objects: plain characters that are placed in the output string and conversion specifications that convert information from time_and_date into readable form in the output string. Each conversion specification is a sequence of this form:

%[-][width][.precision]type

%

A percent sign (%) introduces a conversion specification. This character is required.

width (optional)

An optional decimal digit string that specifies a minimum field width. A converted value that has fewer characters than the field width is padded with spaces to the left. If the decimal digit string is preceded by a minus sign, padding with spaces occurs to the right of the converted value.

If no width is given, for numeric fields the appropriate default width is used with the field padded on the left with zeros, as required. For strings, the output field is made exactly wide enough to contain the string.

precision (optional)

An optional value that specifies the maximum number of characters to be printed for the conversion specification. The precision value is a decimal digit string preceded by a period. If the value to be output is longer than the precision, it is truncated on the right.

type

Specifies the type of conversion to be performed. The characters and their meanings are:

%a

The abbreviated weekday name (for example, Sun) defined by the abday statement in the current locale.

%A

The full weekday name (for example, Sunday) defined by the day statement in the current locale.

%b

The abbreviated month name (for example, Jan) defined by the abmon statement in the current locale.

%B

The full month name (for example, January) defined by the month statement in the current locale.

%c

The date and time format defined by the d_t_fmt statement in the current locale.

%d

The day of the month as a decimal number (01 to 31).

%D

The date in %m/%d/%y format (for example, 01/31/91).

%e

The day of the month as a decimal number (1 to 31). The %e field descriptor uses a two-digit field. If the day of the month is not a two-digit number, the leading digit is filled with a space character.

%E

The combined alternative era year and name, respectively, in %o %N format in the current locale.

%F

The ISO 8601:2000 standard date format, equivalent to %Y-%m-%d.

%g

The last 2 digits of the week-based year as a decimal number [00,99].

%G

The week-based year as a 4-digit decimal number.

%h

The abbreviated month name (for example, Jan) defined by the abmon statement in the current locale. This field descriptor is a synonym for the %b field descriptor.

%H

The 24-hour clock hour as a decimal number (00 to 23).

%I

The 12-hour clock hour as a decimal number (01 to 12).

%j

The day of the year as a decimal number (001 to 366).

%m

The month of the year as a decimal number (01 to 12).

%M

The minutes of the hour as a decimal number (00 to 59).

%n

Specifies a new-line character.

%N

The alternative era name in the current locale.

%o

The alternative era year in the current locale.

%p

The AM or PM string defined by the am_pm statement in the current locale.

%r

The 12-hour clock time with AM/PM notation as defined by the t_fmt_ampm statement (%I:%M:%S [AM|PM]) in the current locale.

%S

The seconds of the minute as a decimal number (00 to 60).

%t

Specifies a tab character.

%T

Represents 24-hour clock time in the format %H:%M:%S (for example, 16:55:15).

%U

The week of the year as a decimal number (00 to 53). Sunday, or its equivalent as defined by the day statement, is considered the first day of the week for calculating the value of this field descriptor.

%w

The day of the week as a decimal number (0 to 6). Sunday, or its equivalent as defined by the .day statement, is considered as 0 for calculating the value of this field descriptor.

%W

The week of the year as a decimal number (00 to 53). Monday, or its equivalent as defined by the day statement, is considered the first day of the week for calculating the value of this field descriptor.

%x

The date format defined by the d_fmt statement in the current locale.

%X

The time format defined by the t_fmt statement in the current locale.

%y

The year of the century (00 to 99).

%Y

The year as a decimal number (for example, 1989).

%z

The offset from UTC in ISO8601:2000 standard format ( +hhmm or -hhmm ). For example, "-0430" means 4 hours 30 minutes behind UTC (west of Greenwich).

%Z

The time-zone name, if one can be determined (for example, EST); no characters are displayed if a time zone cannot be determined.

%%

Specifies a percent sign (%) character.

stringout (output)

A halfword length-prefixed character string (VSTRING) of 256 bytes that contains the formatted time and date output of the CEEFTDS service.

fc (output/optional)

A 12-byte feedback code, optional in some languages, that indicates the result of this service. If you choose to omit this parameter, refer to Invoking callable services for the appropriate syntax to indicate that the feedback code was omitted.

The following symbolic conditions can result from this service:

Code	Severity	Message number	Message text
CEE000	0	—	The service completed successfully.
CEE3T1	3	4001	General Failure: Service could not be completed.
CEE3VM	3	4086	Input Error: The number of characters to be formatted must be greater than zero.

Usage notes

• PL/I MTF consideration—CEEFTDS is not supported in PL/I MTF applications.
• This callable service uses the C/C++ runtime library. The C/C++ library must be installed and accessible even when this service is called from a non-C program.

For more information

• For more information about the setlocale() function, see COUNTRY, CEE3CTY—Set default country, and CEE3LNG—Set national language.
• For more information about the CEESETL callable service, see CEESETL—Set locale operating environment.