R. E. Cook
Home 
Contact Us 

Dr. Cook
Resume 

RunningShoes Library for WinRunner 
RunningShoes 

Custom WinRunner Functions 
and Utilities,
to Your Specs
Custom 

A Random Collection of WinRunner Solutions
Solutions 

Creating DLLs for WinRunner 
"DLLs Demystified" 
(Mercury Interactive's Worldwide Users Conference 2000)

R. E. Cook Consulting

 


Tutorial: RunningShoes Date Formatting


One of the really powerful features of RunningShoes is the ability to generate virtually any required date format. It's such a powerful formatting tool that for several years we've been offering $100 to anyone who can stump the library with a format we can't generate, and no one has managed yet. 

The date formatting works with each of the date systems in RunningShoes: WinRunner date values, Julian dates, individual date components, and the current system time can all be formatted using the same logical process. Define a format string using the basic rules we'll cover below, and the formatting functions generate any date in the format desired. 

As always, the library must be initialized, so begin this script with the standard initialization line:

## Load the DLL and declare the functions.
call_close "RunningShoesInit"();

In an earlier tutorial, we saw a couple of basic formatting steps with a brief explanation. Let's review that here to get us started. As you go through these steps, put formatted_date in the watch list to track the results:

## Get the current system time.
date_value = get_time();

## Format current date.
format = "D MMMM YYYY";
formatted_date = WrDateFormat(format, date_value);

As seen in that earlier tutorial, the above format string says we want a date that contains the one- or two-digit day ("D"), followed by the name of the month ("MMMM"), followed by the four-digit year ("YYYY"). 

Formatting Days

You can work with as many or as few date components as you like when formatting dates. But for simplicity, let's look at formatting just the day, working with standard WinRunner date values:  

## Set date value (Sunday 5 June 2005)
date_value = WrFromDate(2005, 6, 5);

## Format a one- or two-digit day 
format = "D";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "5"

A single format indicator says 1 or 2 digits, as needed. If you want to force 2 digits (with a leading zero when needed), use 2 indicators together. Do not separate the 2 format indicators:

## Force a two-digit day 
format = "DD";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "05"

A numeric day will give the day of the month. You can also request the day of the week, either the full name or a three-letter abbreviation. Use three indicators to request the abbreviation, and four to request the full name.

## Abbreviate the day 
format = "DDD";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "Sun"

## Full day name
format = "DDDD";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "Sunday"

A fifth way to format the day is to use the ordinal number, e.g., the 7th of November. To include the ordinal day in the output, use the format indicator "O" in the format string (that's the letter O for ordinal):

## Format the ordinal day ("5th")
format = "O";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "7th"

In sum, you can format the day to yield:
A one- or two-digit number, as needed ("5", "31")
Two digits for all numbers ("05", "31") 
A three-letter abbreviation ("Sun")
The full name ("Sunday")
The ordinal day of the month ("5th")

Formatting Months

Here you'll see that formatting the month is almost identical to the day formatting that you saw above. The month format indicator is the letter "M", and we use it exactly as we used the "D" for the day. The only difference is we don't have an ordinal month:

## Format a one- or two-digit month 
format = "M";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "6"

## Force a two-digit month 
format = "MM";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "05"

## Abbreviate the month 
format = "MMM";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "Jun"

## Full month name
format = "MMMM";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "June"

Formatting the Year

The year behaves slightly differently, since we don't use alphabetic names for years. Common formats include 2- or 4- digit years ("05" or "2005"), which are generated using 2 or 4 year indicators, "YY" or "YYYY", respectively. 

When we work with historical dates (before the year 1000) or far future dates (after year 9999), it is appropriate to include all digits in the year, as in 7, 492, or 15398. To specify using the actual number of digits, use three year indicators, "YYY". Note that three indicators covers any length, from a single digit on up to as many as needed. The output year will have the same number of digits as the input year. Given the limited range of WinRunner date values, years other than 2 or 4 digits aren't relevant, so we'll save them until we work with the other date systems in RunningShoes.

In certain contexts the year is written in Roman numerals. You can easily format years as Roman numerals in RunningShoes, but it requires one extra step and is not available directly in the format string. (Roman numeral years normally include only the year, not the month or day, so there is little reason to make them available in the date format string.)

## Two-digit years 
format = "YY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "05"

## Four-digit years 
format = "YYYY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "2005"

For those websites that are counting the days to the next Super Bowl, or for those of you working with publishing software, or some other context that still uses Roman numerals, or just out of plain old curiosity, here's how – just convert the standard Arabic year to Roman:

## Roman numeral years 
year = 1994;
formatted_date = RomanFromArabic(year);
# formatted_date: "MCMXCIV" 

Combining Date Fields

The above discussion was limited to single date fields just to clarify the various options for each field. Usually you'll include more than one field; a completely specified date includes year, month and day, and you'll see later that you can include time fields as well. You can combine the format indicators in any pattern needed for your required format. Now that you've seen how the individual date fields can be formatted, combining them in a single format string is a simple step.

When combining date fields in the format string, remember that all non-reserved characters in the format string will appear in the output formatted date. This allows you to insert spaces or punctuation in the date, as needed. 

The only constraint on combining format indicators is that the output string is limited to 511 characters. If the output would be longer than 511 characters, the output string is truncated at the last field that will still fit within the limit.

Numeric Dates

One of the most common date formats is numeric year, month and day, each separated by a slash. Since the slash is not a reserved format indicator, it is passed through to the output string without being interpreted. Let's start with the basic form and build on that: 

## Set date value (Sunday 5 June 2005)
date_value = WrFromDate(2005, 6, 5);

## US standard 
format = "M/D/YY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "6/5/05"

## Almost everywhere else (non-US)
format = "D/M/YY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "5/6/05"

Of course, since Y2K, many contexts now require 4-digit years. A simple change in the format string handles that, using four year indicators ("YYYY") instead of two:

## Non-US
format = "D/M/YYYY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "5/6/05"

## US 
format = "M/D/YYYY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "6/5/05"

Another minor variation is standard for online credit-card purchases, requiring two digits for the card expiration month. In that case, use two month indicators ("MM") to force a leading zero when needed:

## 2-digit month, 4-digit year:
format = "MM/YYYY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "06/2005"

Of course, there are many other variations on these numeric dates. Financial databases often use the "YYYYMMDD" format. To generate dates in that format, use that format as the format string:

## 2-digit month, 4-digit year:
format = "YYYYMMDD";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "20050605"

Play around with the format strings and you'll quickly uncover the ease and power of date formatting with RunningShoes.

Alphanumeric Dates

Dates mixing names and numerals are just as straightforward as numeric dates. You can use names or three-letter abbreviations for the month and for the day of the week. Some common formats: 

## Set date value (7 November 2005)
date_value = WrFromDate(2005, 11, 7);

## "7 November, 2005" (note the comma appears in output)
format = "D MMMM, YYYY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "7 November, 2005"

In its US equivalent:

## "November 7, 2005" (note the comma appears in output)
format = "MMMM D, YYYY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "November 7, 2005"

One format that works both in the US and elsewhere is the day number, month abbreviation, and year, written as "7 Nov 05":

## day number, month abbreviation, year
format = "D MMM YY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "7 Nov 05"

By now you can easily convert that to a form using 2-digit days and 4-digit years:

## day number, month abbreviation, year
format = "DD MMM YYYY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "07 Nov 2005"

Days of the Week

By now, you can probably include days of the week without any help. You know that the day format indicator is the "D"; you also know that you request a three-letter abbreviation with three format indicators, and the full name with four.

## "Monday, November 7, 2005"
format = "DDDD, MMMM D, YYYY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "Monday, November 7, 2005"

And most of us probably remember 1/1/00 did not bring about the end of life as we know it, but what day of the week was it?

## Set date value 
date_value = WrFromDate(2000, 1, 1);

## Abbreviate the day of the week 
format = "DDD D MMM YYYY";
formatted_date = WrDateFormat(format, date_value);
# formatted_date: "Sat 1 Jan 2000"

Brief Quiz

Rather than insulting your intelligence by walking through more variations, we'll leave you to try creating the format strings for these formats on your own:

"06-Aug-96"

"January 1"

"2 February 1998"

"December, 1999"

"Oct. 14, 2004"

Challenge yourself building a string in this format, which contains pitfalls for the unwary: "Today is Monday, the 7th day of November, 2005."

Try those yourself before you view the solutions.

 

Now that you're through with the library, call the script that unloads the DLL:

call_close "RunningShoesEnd"();


Created 7 November 2005 



Top of  This Page | R. E. Cook Home Page

Copyright R. E. Cook Consulting, 2000 - 2011.
All rights reserved.

The site is designed to look best when viewed with Internet Explorer 5.0 - 8.0. Results with other browsers will probably deviate from what is intended.

NOTE: This website refers to registered trademarks and service marks that are owned by other companies, including Mercury Interactive, WinRunner, TestDirector, TSL, Microsoft, Windows.