| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
This procedure converts a user-supplied value into VA FileMan's internal date format and (optionally) into the standard FileMan external, readable date format.
DT^DILF(FLAGS,IN_DATE,.RESULT,LIMIT,MSG_ROOT)
| 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 and 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 will be 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 FileMan. Also, help based on the FLAGS passed can be requested with a "?". |
|
| .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 FileMan internal format or NOW. IN_DATE is accepted only if it is greater than or equal to LIMIT if it is positive, or 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 error, help, and message arrays are put. |
|
Output is returned in the local array passed by reference in the RESULT parameter, shown below:
| RESULT |
Date in internal FileMan format. If input is invalid or if help is requested with a "?", -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). |
Example 1
Following 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:
>D DT^DILF("E","T+10",.ANSWER)
>ZW ANSWER
ANSWER=2931219
ANSWER(0)=DEC 19, 1993
This is an example of a request for help when time is allowed as input:
>D DT^DILF("T","?",.ANSWER,"","MYHELP")
>ZW ANSWER
ANSWER=-1
>ZW MYHELP
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.
In addition to errors indicating that the input parameters are incorrect or missing, the following error code may be returned:
| 330 | Date/time is not acceptable. |
| Acceptable User Input |
This call processes a wide range of formats for dates and times. "Example 2" above that 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 this call is to transform the date/time passed in the IN_DATE parameter into the format used by FileMan to store values in Date/Time data type fields. That format is "YYYDDMM.HHMMSS" where YYY is the number of years since 1700. |
| Readable Date |
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: March 10, 2007