STRFTIME Prototype

[ return to article ]

The STRFTIME procedure returns a pointer to a formatted character string containing date and time information in words. The input is a TM structure and a format string. The table the follows the prototype indicates the formatting codes available to the strftime procedure. See the example at the end of this article.

The strftime procedure is perhaps the most useful, if not the most fun procedure of the time prototypes. It allows you to create a date and/or time value formatted in words. For example "Monday, February 15, 1999" can be returned using strftime.

Prototype

.....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++
     D size_t          S             10i 0
     D strFTime        PR            10i 0 Extproc('strftime')
     D  szTarget                    256A   options(*VARSIZE)
     D  nTargetLen                         like(size_t)     value
     D  szFormat                       *   options(*string) value
     D  struct_tm                          like(tm)


The first parameter is a character field. This parameter receives the formatted character string based-on the formatting codes specified in the 3rd parameter.

The second parameter identifies the length of the field passed as the first parameter. For example, if a field named dtFormat is a Char(30) field, and is passed as the first parameter, the second parameter would either have the number 30, or the built-in function %Len(dtFormat) which passes the length of the dtFormat field.

The third parameter is the format pattern that is used to create the character string returned on the first parameter. The value can be any character string value with embedded format codes. The format codes are translated into their corresponding values.  These format codes and their corresponding values are listed in the table that follows.

Format Code Description
%a Abbreviated weekday name: 'Tue", "Wed", etc.
%A Full weekday name: "Tuesday", "Wednesday", etc.
%b Abbreviated month name: "Jan", "Feb", etc.
%B Full month name: "January", "February", etc.
%c Date and time formatted for the local system.
%d Day of the month as a decimal (01 to 31)
%H Hour in 24-hour clock format (01 to 24)
%I Hour in 12-hour clock format (01 to 12)
%j day of the year as a decimal (001 to 366)
%m Month as a decimal number (01 to 12)
%M Minute as a decimal number (00 to 59)
%p AM or PM indicator for 12-hour clock.
%S Seconds as a decimal number (00 to 59)
%U Week as a decimal number: Sunday base (00 to 53)
%w Weekday as a decimal number with Sunday base (0 to 6)
%W Week as a decimal number with Monday base (00 to 53)
%x Date edited for local system.
%X Time edited for local system.
%y Year without century (2-digit year) (00 to 99)
%Y Year with century (4-digit year)
%Z Time zone code for the local system or nothing if no time zone indicated.
%% Embed a percent sign into the string.

 

Example:

.....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++
     D/COPY qcpysrc,time
     D myFormat        C                   Const('%A, %B %d, %Y')
     D myTime          S                   Like(time_T)
     D myString        S             50A
     D pMyTM           S               *
     D myTM            S                   Like(TM) based(pMyTM)
.....CSRn01..............OpCode(ex)Extended-factor2+++++++++++++++++++++++++++++
     C                   CallP      time( myTime )

     C                   Eval       pMyTM = localtime( myTime )
     C                   CallP      strFTime(myString : %Len( myString ) :
     C                                        myFormat : myTM)

This code, assuming it is run on February 15, 1999, would return a string to the MYSTRING variable containing the following:

Monday, February 15, 1999

The first Calculation specification retrieves the current system date/time into the MYTIME variable. The second line converts the MYTIME time_t value into a TM structure. The LOCALTIME procedure returns a pointer to the TM structure. The pointer is stored in the PMYTM field. Since MYTM is based on PMYTM, MYTM references the TM structure data returned by LOCALTIME.

The third line in this example evokes the STRFTIME procedure to format the MYTM data based on the format string stored in MYFORMAT. The formatted string is returned to the first parameter in the MYSTRING field.

[ top ]