SQLphone - spfDate.DLL

spfDate.DLL

This DLL can be used by a SQLphone flowchart to validate and format dates and times entered by a caller.

Function Summary

This DLL contains the following functions:

GetDate1 - Check year, month and day values entered by a caller
GetDate2 - Check month and day values entered by a caller
GetTime1 - Check hour and minute values entered by a caller
FmtTime1 - Format date and time into a speakable string

Typical Usage

The following describes how the GetDate1 function can be used by a flowchart (the other functions can be used in a similar way):

Digit boxes ask the caller to enter year, month and day (not necessarily in that order)
and the entered values are stored in three separate memories.
A DLL box calls the GetDate1 function, passing the entered year, month and day.
If the date is invalid, the function returns an error description (eg. "invalid month")
and the caller is prompted to re-enter.
If the date is valid, the function returns "OK" with the date formatted as YYYY-MM-DD.
A Play box speaks the date back to the caller, and they are prompted to confirm or re-enter.
A SQL box uses the date, typically with an INSERT statement.

Function : GetDate1

This function can be used to validate a date, entered by the caller as year, month and day. If the entered date is valid, the function returns "OK" with the date formatted as "YYYY-MM-DD". If the entered date is invalid, the function returns an error description (eg. "invalid day of month").

The following figure shows how to setup a DLL Box to call this function:

The following table describes the input and output parameters for this function:

Parameter Type I/O Memory Argument Expected Values

return code void output none none

1 int input memory contains a year value entered by the caller 4 or 2 digits. If a 2 digit year is specified, it is assumed to be after 2000

2 int input memory contains a month number entered by the caller 1 to 12

3 int input memory contains a day of the month number entered by the caller 1 to 31. validated against number of days in the month, leap years are also checked

4 char * output memory contains the date formatted as YYYY-MM-DD date in format: YYYY-MM-DD

5 char * output memory contains result of date validation "OK" if date is valid, otherwise error description

Parameter	Type	I/O	Memory Argument	Expected Values
return code	void	output	none	none
1	int	input	memory contains a year value entered by the caller	4 or 2 digits. If a 2 digit year is specified, it is assumed to be after 2000
2	int	input	memory contains a month number entered by the caller	1 to 12
3	int	input	memory contains a day of the month number entered by the caller	1 to 31. validated against number of days in the month, leap years are also checked
4	char *	output	memory contains the date formatted as YYYY-MM-DD	date in format: YYYY-MM-DD
5	char *	output	memory contains result of date validation	"OK" if date is valid, otherwise error description

Function : GetDate2

This function is similar to GetDate1, except it does not require the caller to enter a year. With this function, callers can specify any date between today, and 365 days in the future. To specify dates prior to today's date, or dates more than 365 days in the future, use function GetDate1.

The following figure shows how to setup a DLL Box to call this function:

The following table describes the input and output parameters for this function:

Parameter Type I/O Memory Argument Expected Values

return code void output none none

1 int input memory contains a month number entered by the caller 1 to 12

2 int input memory contains a day of the month number entered by the caller 1 to 31. validated against number of days in the month, leap years are also checked

3 char * output memory contains the date formatted as YYYY-MM-DD date in format: YYYY-MM-DD

4 char * output memory contains result of date validation "OK" if date is valid, otherwise error description

Parameter	Type	I/O	Memory Argument	Expected Values
return code	void	output	none	none
1	int	input	memory contains a month number entered by the caller	1 to 12
2	int	input	memory contains a day of the month number entered by the caller	1 to 31. validated against number of days in the month, leap years are also checked
3	char *	output	memory contains the date formatted as YYYY-MM-DD	date in format: YYYY-MM-DD
4	char *	output	memory contains result of date validation	"OK" if date is valid, otherwise error description

Function : GetTime1

This function can be used to validate a time, entered by the caller in hours and minutes. If the entered time is valid, the function returns "OK" with the time formatted as "HH:MM". If the entered time is invalid, the function returns an error description (eg. "invalid hour").

The following figure shows how to setup a DLL Box to call this function:

The following table describes the input and output parameters for this function:

Parameter Type I/O Memory Argument Expected Values

return code void output none none

1 int input memory contains an hour number entered by the caller 1 to 23

2 int input memory contains a minutes number entered by the caller 0 to 59

3 char * output memory contains the time formatted as HH:MM time in format: HH:MM

4 char * output memory contains result of time validation "OK" if time is valid, otherwise error description

Parameter	Type	I/O	Memory Argument	Expected Values
return code	void	output	none	none
1	int	input	memory contains an hour number entered by the caller	1 to 23
2	int	input	memory contains a minutes number entered by the caller	0 to 59
3	char *	output	memory contains the time formatted as HH:MM	time in format: HH:MM
4	char *	output	memory contains result of time validation	"OK" if time is valid, otherwise error description

Function : FmtTime1

This function can be used to format a date and time, using a custom format template. Typically, this function is used to format a date and time into text which can be spoken by a text-to-speech engine. If the entered date and time are valid, the function returns the date/time formatted using the format template. If the entered date or time are invalid, the function returns an error description (eg. "invalid day of month").

The following figure shows how to setup a DLL Box to call this function:

The 4th parameter should be big enough to store the formatted date and time. We recommend 128 characters, as shown in the following figure:

The following table describes the input and output parameters for this function:

Parameter Type I/O Memory Argument Expected Values

return code void output none none

1 char * input memory contains the date formatted as YYYY-MM-DD date in format: YYYY-MM-DD

2 char * input memory contains the time formatted as HH:MM time in format: HH:MM

3 char * input memory contains the format template, see table below eg. %A %d %B %Y at %H %M

4 char * output memory contains formatted date and time formatted date and time, or error description

Parameter	Type	I/O	Memory Argument	Expected Values
return code	void	output	none	none
1	char *	input	memory contains the date formatted as YYYY-MM-DD	date in format: YYYY-MM-DD
2	char *	input	memory contains the time formatted as HH:MM	time in format: HH:MM
3	char *	input	memory contains the format template, see table below	eg. %A %d %B %Y at %H %M
4	char *	output	memory contains formatted date and time	formatted date and time, or error description

The following table describes the codes which can be used by a format template. For C programmers: these are identical to the strftime format codes.

Code Description

%a Abbreviated weekday name

%A Full weekday name

%b Abbreviated month name

%B Full month name

%c Date and time representation appropriate for locale

%d Day of month as decimal number (01 31)

%H Hour in 24-hour format (00 23)

%I Hour in 12-hour format (01 12)

%j Day of year as decimal number (001 366)

%m Month as decimal number (01 12)

%M Minute as decimal number (00 59)

%p Current locale's A.M./P.M. indicator for 12-hour clock

%S Second as decimal number (00 59)

%U Week of year as decimal number, with Sunday as first day of week (00 51)

%w Weekday as decimal number (0 6; Sunday is 0)

%W Week of year as decimal number, with Monday as first day of week (00 51)

%x Date representation for current locale

%X Time representation for current locale

%y Year without century, as decimal number (00 99)

%Y Year with century, as decimal number

%z, %Z Time-zone name or abbreviation; no characters if time zone is unknown

%% Percent sign

Code	Description
%a	Abbreviated weekday name
%A	Full weekday name
%b	Abbreviated month name
%B	Full month name
%c	Date and time representation appropriate for locale
%d	Day of month as decimal number (01 31)
%H	Hour in 24-hour format (00 23)
%I	Hour in 12-hour format (01 12)
%j	Day of year as decimal number (001 366)
%m	Month as decimal number (01 12)
%M	Minute as decimal number (00 59)
%p	Current locale's A.M./P.M. indicator for 12-hour clock
%S	Second as decimal number (00 59)
%U	Week of year as decimal number, with Sunday as first day of week (00 51)
%w	Weekday as decimal number (0 6; Sunday is 0)
%W	Week of year as decimal number, with Monday as first day of week (00 51)
%x	Date representation for current locale
%X	Time representation for current locale
%y	Year without century, as decimal number (00 99)
%Y	Year with century, as decimal number
%z, %Z	Time-zone name or abbreviation; no characters if time zone is unknown
%%	Percent sign

Source Code

The C source code for this DLL is available free on request. Please contact us to request it.