VA FileMan V. 22.2 Programmer Manual Banner

 

Contents: Main Chapter See Also: Getting Started Manual Advanced User Manual

Database Server (DBS) API

DT^DILF(): Date Converter 

Reference Type Category ICR #
Supported Database Server (DBS) 2054
Description

The DT^DILF API converts a user-supplied value into VA FileMan's internal date format and (optionally) into the standard VA FileMan external, readable date format.

Format
DT^DILF([flags,]in_date,.result[,limit][,msg_root])
Input Parameters
FLAGS

(Optional) Flags to control processing of user input and the type of output returned. Generally, flags is the same as %DT input variable to ^%DT entry point, with the following exceptions:

  • A is not allowed.
  • The meaning of E is different (see below).

The possible values are:

E External, readable date returned in Zero-node of result.
F Future dates are assumed.
N Numeric-only input is not allowed.
P Past dates are assumed.
R Required time input.
S Seconds are returned.
T Time input is allowed but not required.
X EXact date (with month and day) is required.
in_date

(Required) Date input as entered by the user in any of the formats known to VA FileMan. Also, help based on the flags passed can be requested with a question mark (?).

.result

(Required) Local array that receives the internal value of the DATE/TIME and, if the E flag is sent, the readable value of the date. If input is not a valid date, -1 is returned.

limit

(Optional) A value equal to a DATE/TIME in VA FileMan internal format or NOW. The in_date parameter is accepted only if it is:

  • Greater than or equal to limit if it is positive.
  • Less than or equal to limit if it is negative.

This is equivalent to the %DT(0) variable in the ^%DT call.

msg_root

(Optional) Root into which the following arrays are put:

  • Error
  • Help
  • Message
Output

Output is returned in the local array passed by reference in the RESULT parameter, shown below:

RESULT

Date in internal VA FileMan format. If input is invalid or if help is requested with a question mark (?), -1 is returned.

RESULT(0)

If requested, date in external, readable format. When appropriate, error messages and help text are returned in the standard manner in ^TMP or in msg_root (if it is specified).

Examples
Example 1

Figure 184 is an example of one of the many kinds of user inputs that can be processed by this call. Use of the E flag ensures that the readable form of the data is returned in the 0-node as follows:

Figure 184: DT^DILF API—Example 1: Input and Output

    >D DT^DILF("E","T+10",.ANSWER) <Enter>

    >ZW ANSWER <Enter>
    ANSWER=2931219
    ANSWER(0)=DEC 19, 1993
Example 2

Figure 185 is an example of a request for help when time is allowed as input:

Figure 185: DT^DILF API—Example 2: Input and Output

    >D DT^DILF("T","?",.ANSWER,"","MYHELP") <Enter>

    >ZW ANSWER <Enter>
    ANSWER=-1

    >ZW MYHELP <Enter>
    MYHELP("DIHELP")=10
    MYHELP("DIHELP",1)=Examples of Valid Dates:
    MYHELP("DIHELP",2)=   JAN 20 1957 or JAN 57 or 1/20/57 or 012057
    MYHELP("DIHELP",3)=   T   (for TODAY), T+1 (for TOMORROW), T+2, T+7, etc.
    MYHELP("DIHELP",4)=T-1 (for YESTERDAY), T-3W (for 3 WEEKS AGO), etc.
    MYHELP("DIHELP",5)=If the year is omitted, the computer uses the CURRENT YEAR.
    MYHELP("DIHELP",6)=You may omit the precise day, as: JAN, 1957.
    MYHELP("DIHELP",7)=
    MYHELP("DIHELP",8)=If the date is omitted, the current date is assumed.
    MYHELP("DIHELP",9)=Follow the date with a time, such as JAN 20@10, T@10AM, 10:30,
      etc.
    MYHELP("DIHELP",10)=You may enter NOON, MIDNIGHT, or NOW to indicate the time.
Error Codes Returned

In addition to errors indicating that the input parameters are incorrect or missing, Table 61 lists the possible error codes returned with the DT^DILF API:

Table 61: DT^DILF API—Error Codes Returned

Code Description
330 Date/time is not acceptable.
Details and Features
Acceptable User Input

The DT^DILF API processes a wide range of formats for dates and times. "Example 2" shows the response to an in_date of ? summarizes the acceptable formats. Remember that the allowable values are controlled by the flags sent and by the limit parameter.

Internal Format

The primary use of the DT^DILF API is to transform the DATE/TIME passed in the in_date parameter into the format used by VA FileMan to store values in DATA TYPE fields with a value of DATE/TIME. That format is: 

   YYYDDMM.HHMMSS

Where YYY is the number of years since 1700.

When the E flag is sent to request that the readable form of the data be returned, the format is always: 

   MON dd,yyyy@ hh:mm:ss

 

Reviewed/Updated: May 2026