Technical Reference: Base Operating System and Extensions, Volume 1

getdate Subroutine

Syntax

#include <time.h>
 
struct tm *getdate (const char *string)
extern int getdate_err

The getdate subroutine converts user definable date and/or time specifications pointed to by string, into a struct tm. The structure declaration is in the time.h header file (see ctime subroutine).

User supplied templates are used to parse and interpret the input string. The templates are contained in text files created by the user and identified by the environment variable DATEMSK. The DATEMSK variable should be set to indicate the full pathname of the file that contains the templates. The first line in the template that matches the input specification is used for interpretation and conversation into the internal time format.

The templates should follow a format where complex field descriptors are proceeded by simplier ones. For example:

%M
%H:%M
%m/%d/%y
%m/%d/%y %H:%M:%S

The following field descriptors are supported:

%%	Same as %.
%a	Abbreviated weekday name.
%A	Full weekday name.
%b	Abbreviated month name.
%B	Full month name.
%c	Locale's appropriate date and time representation.
%C	Century number (00-99; leading zeros are permitted but not required)
%d	Day of month (01 - 31: the leading zero is optional.
%e	Same as %d.
%D	Date as %m/%d/%y.
%h	Abbreviated month name.
%H	Hour (00 - 23)
%I	Hour (01 - 12)
%m	Month number (01 - 12)
%M	Minute (00 - 59)
%n	Same as \n.
%p	Locale's equivalent of either AM or PM.
%r	Time as %I:%M:%S %p
%R	Time as %H: %M
%S	Seconds (00 - 61) Leap seconds are allowed but are not predictable through use of algorithms.
%t	Same as tab.
%T	Time as %H: %M:%S
%w	Weekday number (Sunday = 0 - 6)
%x	Locale's appropriate date representation.
%X	Locale's appropriate time representation.
%y	Year within century. Note: When the environment variable XPG_TIME_FMT=ON, %y is the year within the century. When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969 to 1999, inclusive); values in the range 00-68 refer to 2000 to 2068, inclusive.
%Y	Year as ccyy (such as 1986)
%Z	Time zone name or no characters if no time zone exists. If the time zone supplied by %Z is not the same as the time zone getdate subroutine expects, an invalid input specification error will result. The getdate subroutine calculates an expected time zone based on information supplied to the interface (such as hour, day, and month).

The match between the template and input specification performed by the getdate subroutine is case sensitive.

The month and weekday names can consist of any combination of upper and lower case letters. The used can request that the input date or time specification be in a specific language by setting the LC_TIME category (See the setlocale subroutine).

Leading zero's are not necessary for the descriptors that allow leading zero's. However, at most two digits are allowed for those descriptors, including leading zero's. Extra whitespace in either the template file or in string is ignored.

The field descriptors %c, %x, and %X will not be supported if they include unsupported field descriptors.

Example 1 is an example of a template. Example 2 contains valid input specifications for the template. Example 3 shows how local date and time specifications can be defined in the template.

The following rules apply for converting the input specification into the internal format:

If only the weekday is given, today is assumed if the given month is equal to the current day and next week if it is less.
If only the month is given, the current month is assumed if the given month is equal to the current month and next year if it is less and no year is given (the first day of month is assumed if no day is given).
If no hour, minute, and second are given, the current hour, minute and second are assumed.
If no date is given, today is assumed if the given hour is greater than the current hour and tomorrow is assumed if it is less.

See Example 4 for examples illustrating the use of the above rules.

Return Values

Upon successful completion, the getdate subroutine returns a pointer to struct tm; otherwise, it returns a null pointer and the external variable getdate_err is set to indicate the error.

Error Codes

Upon failure, a null pointer is returned and the variable getdate_err is set to indicate the error.

The following is a complete list of the getdate_err settings and their corresponding descriptions:

1	The DATEMSK environment variable is null or undefined.
2	The template file cannot be opened for reading.
3	Failed to get file status information.
4	The template file is not a regular file.
5	An error is encountered while reading the template file.
6	Memory allocation failed (not enough memory available.
7	There is no line in the template that matches the input.
8	Invalid input specification, Example: February 31 or a time is specified that can not be represented in a time_t (representing the time in seconds since 00:00:00 UTC, January 1, 1970).

Examples

The following example shows the possible contents of a template:

%m
%A %B %d, %Y, %H:%M:%S
%A
%B
%m/%d/%y %I %p
%d, %m, %Y %H:%M
at %A the %dst of %B in %Y
run job at %I %p, %B %dnd
&A den %d. %B %Y %H.%M Uhr

The following are examples of valid input specifications for the template in Example 1:

getdate ("10/1/87 4 PM")
getdate ("Friday")
getdate ("Friday September 18, 1987, 10:30:30")
getdate ("24,9,1986 10:30")
getdate ("at monday the 1st of december in 1986")
getdate ("run job at 3 PM. december 2nd")

If the LC_TIME category is set to a German locale that includes freitag as a weekday name and oktober as a month name, the following would be valid:

getdate ("freitag den 10. oktober 1986 10.30 Uhr")

The following examples shows how local date and time specification can be defined in the template.

Invocation Line in Template
getdate ("11/27/86") %m/%d/%y
getdate ("27.11.86"0 %d.%m.%y
getdate ("86-11-27") %y-%m-%d
getdate ("Friday 12:00:00") %A %H:%M:%S

The following examples help to illustrate the above rules assuming that the current date Mon Sep 22 12:19:47 EDT 1986 and the LC_TIME category is set to the default "C" locale.

Input	Line in Template	Date
Mon	%a	Mon Sep 22 12:19:47 EDT 1986
Sun	%a	Sun Sep 28 12:19:47 EDT 1986
Fri	%a	Fri Sep 26 12:19:47 EDT 1986
September	%B	Mon Sep1 12:19:47 EDT 1986
January	%B	Thu Jan 1 12:19:47 EDT 1986
December	%B	Mon Dec 1 12:19:47 EDT 1986
Sep Mon	%b %a	Mon Sep 1 12:19:47 EDT 1986
Jan Fri	%b %a	Fri Jan 2 12:19:47 EDT 1986
Dec Mon	%b %a	Mon Dec 1 12:19:47 EDT 1986
Jan Wed 1989	%b %a %Y	Wed Jan 4 12:19:47 EDT 1986
Fri 9	%a %H	Fri Sep 26 12:19:47 EDT 1986
Feb 10:30	%b %H: %S	Sun Feb 1 12:19:47 EDT 1986
10:30	%H: %M	Tue Sep 23 12:19:47 EDT 1986
13:30	%H: %M	Mon Sep 22 12:19:47 EDT 1986

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The ctime (ctime, localtime, gmtime, mktime, difftime, asctime, or tzset Subroutine), ctype (ctype, isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, isgraph, iscntrl, or isascii Subroutines), setlocale, strftime, and times (getrusage, getrusage64, times, or vtimes Subroutine) subroutines.