BuiltIn Functions › $DATE Function

$DATE Function

$DATE returns an alphanumeric value of either the specified date or the current date in the specified format. See the SET COMMAND SESSION OPTIONS and SET COMMAND DATEFOR commands in the Command Reference Guide. The defaults are those defined at runtime.

This function has the following format:

$DATE [(['date‑pattern'][,DATE=input‑date])]

$DATE alone returns the current date in the default date format, which you can set in session or site options.

'date‑pattern'

Displays the sequence of characters (maximum 30), in quotes, that represents the format in which components of the date (day, month, and year) are returned. The default pattern is the format displayed in the current site option fill‑in. The notations that you can specify for each date component are shown in the following table.

Any characters except uppercase alphabetics in the date pattern remain unchanged.

The site administrator for each site defines the actual text indicated by the keywords MONTH, LCMONTH, MON, LCMON, WEEKDAY, LCWEEKDAY, DAY, and LCDAY in the PMS table PMSTBL.

input‑date

Displays the date used as input to the function. The input‑date can specify a literal, the name of a field containing the date, or the current date (that is, the date at runtime). If no DATE= clause is specified, the default input‑date is the current date. The input‑date must be between 2000 B.C. and 9999 A.D.

You can enclose the entire input‑date in parentheses. The input‑date is specified as follows:

{$TODAY                                                   }
{date‑field                                               }
{'literal'                                                }
{alpha‑date [,TEMPLATE='alpha‑input‑pattern'] [,BASE=yyyy]}
{                                                         }
{num‑date [,TEMPLATE='num‑input‑pattern'] [,BASE=yyyy]    }
{MONTH=month, DAY=day, YEAR=year [,BASE=yyyy]             }

$TODAY

Specifies a numeric function that returns the CA Ideal internal integer date for the current date (that is, the date at runtime). Each time $TODAY is encountered, it calls the operating system.

date‑field

Specifies the name of a date field defined in working data or parameter data.

'literal'

Defines a six‑character alphanumeric literal in the form 'yymmdd' (or in the format specified in a TEMPLATE clause described in the TEMPLATE=topic). Trailing blanks are ignored.

The numbers represented can be from 000101 to 991231. In this range, yy can be from 00 to 99, mm can be from 00 to 12, and dd can be from 01 to 31. The maximum value for dd depends on the value of mm and yy. The day specified must exist.

alpha‑date

Specifies an alphanumeric field containing a value in the default format yymmdd, or in the format specified by the accompanying TEMPLATE clause. Trailing blanks are ignored.

TEMPLATE='alpha‑input‑pattern'

Defines the pattern of the date in the accompanying field or literal. The input pattern is built in much the same way as the output date pattern. Up to 30 characters represent components and notation of the date being read by the function. However, several keywords available in the output date‑pattern are not available here. The notations for specifying the format of each input date component are shown in the following table.

M and D must be followed by an asterisk (*) or blank or used at the end of the pattern. The site administrator for each site defines the actual text indicated by the keywords MONTH, LCMONTH, MON, and LCMON in the PMS table PMSTBLS. For more information, see the Working in the Environment Guide.

num‑date

A numeric field containing a numeric date. This value is converted to alphanumeric format and interpreted using the default format yymmdd or the format specified by the accompanying TEMPLATE clause.

TEMPLATE='num‑input‑pattern'

Defines the pattern of the date in the accompanying numeric field. Up to 30 characters represent the formats of the components of the date being read by the function. The input pattern is built in much the same way as the date pattern, but only the keywords in the following table are available.

BASE=yyyy

Specifies a four‑digit number as the base year from which the century of the input year is determined (the default is 1900). The input date must include the year in the format yy (for example Mar 3, 84). If you include this clause, the following algorithm defines the year's century:

If yy >= the last two digits of the base year
   use the first two digits of the base year as the century.
Else

• use the first two digits of the base year plus one as the century.
• Input‑date Clause: DATE='010286',TEMPLATE='MMDDYY',BASE=1950 ...

  Date Specified: January 2, 1986

• Input‑date Clause: DATE='010201',TEMPLATE='MMDDYY',BASE=1950 ...

  Date Specified: January 2, 2001

• Input‑date Clause: DATE='010250',TEMPLATE='MMDDYY',BASE=1950 ...
• Date Specified: January 2, 1950

  MONTH=month

  DAY=day

  YEAR=year-Specifies an input date when the month, day, and year are separate numeric literals or numeric fields. Each operand can be a number or field. For example:

  MONTH=12,DAY=7,YEAR=year‑field
  

  If you omit one or more, the input date is interpreted as explained in the first note below. If the year is a two‑digit value, you can specify a BASE= year for the century. If the year is a four‑digit value, the BASE= year is ignored. A three‑digit day (DDD) is not valid.

If the century is required for the output format or for $INTERNAL-DATE format, the input date must be supplied either by a 4 digit YEAR or 2 digit YY with a BASE year.

If you do not specify the month, day, or year of the input date, the component is interpreted as follows:

month=1 day=1 year=current

Only the parts of the six‑character input date that are actually required by the 'date‑pattern' are edited for validity. The remaining characters must be represented, but their values are not tested. For example, the following date functions include an input date with a month of 23:

$DATE('YY',DATE='852307') is valid. 
$DATE('MM',DATE='852307') is in error.

Examples

The following example converts a Gregorian International date to a Julian date. W_JUL_DAT and W_GREG_DAT are both type X fields.

SET W_JUL_DAT =$DATE('YYDDD',DATE=W_GREG_DAT, TEM ='YYMMDD')

Assume that it is January 10, 1993.

If you want a period after an abbreviation, you must include it as part of the literal. You must also enter spacing between components.