VA FileMan V. 22.0 Programmer Manual Banner


 

Main Chapter Getting Started Manual Advanced User Manual

Classic VA FileMan API


^%DT

This routine accepts input and validates the input as being a correct date and time.

Input Variables
%DT

A string of alphabetic characters which alter how %DT responds. Briefly stated, the acceptable characters are:

A Ask for date input.
E Echo the answer.
F Future dates are assumed.
I For Internalization, assume that the day number precedes the month number in input.
M Only Month and year input is allowed.
N Pure Numeric input is not allowed.
P Past dates are assumed.
R Requires time input.
S Seconds should be returned.
T Time input is allowed but not required.
X EXact input is required.

For an explanation of each character, see "%DT Input Variables in Detail."

X

If %DT does not contain an A, then the variable X must be defined as equal to the value to be processed. See Date Fields in the "Editing Specific Field Types" chapter of the "VA FileMan Getting Started Manual" for acceptable values for X and for the interpretation of those values.

%DT("A")

(Optional) A prompt which will be displayed prior to the reading of the input. Without this variable, the prompt "DATE:" will be issued.

%DT("B")

The default answer to the "DATE:" prompt. It is your responsibility to ensure that %DT("B") contains a valid date/time. Allowable date input formats are explained in the "Editing Specific Field Types" chapter of the "VA FileMan Getting Started Manual."

%DT(0)

(Optional) Prevents the input date value from being accepted if it is chronologically before or after a particular date. Set %DT(0) equal to a VA FileMan-format date (e.g., %DT(0)=2690720) to allow input only of dates greater than or equal to that date. Set it negative (e.g., %DT(0)=-2831109.15) to allow only dates less than or equal to that date/time. Set it to NOW to allow dates from the current (input) time forward. Set it to -NOW to allow dates up to the current time.

NOTE: Be sure to kill this variable after returning from %DT.

Output Variables
Y

%DT always returns the variable Y, which can be one of two values:

Y=-1 The date/time was invalid.
Y=YYYMMDD.HHMMSS The value determined by %DT.
X

X is always returned. It contains either what was passed to %DT (in the case where %DT did not contain an A) or what the user entered.

DTOUT

This is only defined if %DT has timed-out waiting for input from the user.

%DT Input Variables in Detail
A

%DT Asks for input from the terminal. It continues to ask until it receives correct input, a null, or an up-arrow. If %DT does not contain the character A, the input to %DT is assumed to be in the variable X.

E

The External format of the input will be echoed back to the user after it has been entered. If the input was erroneous, two question marks and a "beep" will be issued.

F

If a year is not entered (example 1), or if a two-digit year is entered (example 2), a date in the Future is assumed.

EXCEPTION: If a two-digit year is entered and those two digits equal the current year, the current year is assumed even if the date is in the past (example 3).

Example Current Date User Input Date Returned Returned Without F
1) July 1, 2000 5/1 May 1, 2001 May 1, 2000
2) July 1, 2000 5/1/90 May 1, 2090 May 1, 1990
3) July 1, 2000 5/1/00 May 1, 2000 May 1, 2000

See "Y2K Changes" below for the behavior of %DT when neither the F nor P flag is used.

I For Internationalization, this flag makes %DT assume that in the input, the day number precedes the month number. For example, input of 05/11/2000 is assumed to be November 5, 2000 (instead of May 11, 2000). Also, with this flag, the month must be input as a number. For example, November must be input as 11, not NOV.
M

Only Month and year input is allowed. Input with a specific day or time is rejected (example 1). If only a month and two digits are entered, the two digits are interpreted as a year instead of a day (example 2).

If the M flag is used with theX flag, a month must be specified; otherwise, the input can be just a year (example 3).

M Flag
Example Date Input Date Returned Returned Without M
1) 7-05-2005 Invalid July 5, 2005
2) 7-05 July 2005 July 5, 2000*

*Assuming the current year is 2000 and the F and P flags aren't used.

M Flag (with X Flag)
Example Date Input Date Returned Returned Without X
3) 05 or 2005 Invalid 2005
N

Ordinarily, a user can enter a date in a purely Numeric form, i.e., MMDDYY. However, if %DT contains an N, then this type of input is not allowed.

P

If a year is not entered (example 1), or if a two-digit year is entered (example 2), a date in the Past is assumed.

EXCEPTION: If a two-digit year is entered and those two digits equal the current year, the current year is assumed even if the date is in the future (example 3).

Example Current Date User Input Date Returned Returned Without P
1) March 1, 1995 6/1 June 1, 1994 June 1, 1995
2) March 1, 1995 6/1/98 June 1, 1898 June 1, 1998
3) March 1, 1995 6/1/95 June 1, 1995 June 1, 1995

See "Y2K Changes" below for the behavior of %DT when neither the F nor P flag is used.

R

Time is Required. It must be input.

S

Seconds are to be returned.

T

Time is allowed in the input, but it is not necessary. See Date Fields in the "Editing Specific Field Types" chapter of the "VA FileMan Getting Started Manual" for details of how user-input times are interpreted.

X

EXact input is required. If X is used without M, date input must include a day and month. Without X, the input can be just month-year or only a year.

If X is used with M, date input must include a month. If M is used without X, then the input can be just a year.

Y2K Changes: New/Updated with VA FileMan V. 22.0
Behavior of %DT when neither the F nor P flag is used

If no year is entered, the current year is assumed (example 1).

If a two-digit year is entered, a year less than 20 years in the future and no more than 80 years in the past is assumed. For example, in the year 2000, two-digit years are assumed to be between 1920 through 2019.

NOTE: Only the year, not the current month and day, is taken into account in this calculation (examples 2 through 5 in the table below).

Example Current Date User Input Date Returned
1) Sep 15, 2000 3/15 Mar 15, 2000
2) Sep 15, 2000 1/1/20 Jan 01,1920
3) Sep 15, 2000 12/31/20 Dec 31, 1920
4) Sep 15, 2000 1/1/19 Jan 01, 2019
5) Sep 15, 2000 12/31/19 Dec 31, 2019

 


Reviewed/Updated: March 10, 2007