%JPERIOD

Return the Julian period value for a date

WTSupported in traditional Synergy on Windows

WNSupported in Synergy .NET on Windows

USupported on UNIX

VSupported on OpenVMS

period = %JPERIOD[(date)]

Return value

period

The Julian period value for the specified date. (n)

Arguments

date

(optional) The date for which you want to determine the Julian period date. The default is the current date. (a or n)

Discussion

%JPERIOD validates a date and (if the date is valid) returns a numeric value that uniquely identifies the passed date. This value is the Julian period value, or the number of days since December 31, 4715 BC. Consecutive dates have consecutive Julian period values. Dates prior to December 31, 4715 BC are not supported.

The dates Wednesday, September 2, 1752, and Thursday, September 14, 1752, have consecutive Julian period values, because the changeover from the Julian to the Gregorian calendar occurred at this time, and September 2 (Julian) was followed by September 14 (Gregorian). Leap years are fully accounted for according to the Gregorian calendar.

Synergy provides no conversions between Julian and Gregorian calendar dates.

If date is passed as a numeric value, the format must be YYYYMMDD. Some examples are

19991013 = October 13, 1999

18120101 = January 1, 1812

If date is passed as an alpha value, the format can be

[DD][-][MMM][-][YYYY][BC]

or

+|-n

The hyphen delimiters in the first format are optional, but they must be specified if leading components are omitted. Any omitted component defaults to the current value. For example,
“-JUN” refers to today’s date, but in June. If the year is present, it must be fully specified with the century value; it does not default to the current century. For example, “17-JUN-62” occurred when Nero was emperor in Rome.

The second format indicates plus or minus n days from the current date.

Sample alpha date formats include

“17JUN1962” = June 17, 1962

“25-DEC” = December 25 of this year

“01” = The first day of the current month in the current year

“--1999” = Today’s date in 1999

“--200BC” = Today’s date in the year 200 BC

+365 = The date that is 365 days after the current date

-30 = The date that is 30 days before the current date

%JPERIOD is useful for validating keyboard input in a flexible way, giving keyboard operators freedom in date input formats. If an invalid date is passed, an “Invalid date” error ($ERR_INVDATE) is generated.

%JPERIOD also makes it easier to calculate dates. For example, you can find the number of days elapsed between two dates by subtracting the Julian period value of the earlier date from that of the later date, or you can determine the date that is n days from a given date by adding n to the date’s Julian period value to get the Julian period value of the desired date.

%JPERIOD is not intended to provide a means of storing dates; it is merely a means of validating and comparing dates.

To convert back to alphabetic format, use %DATE. To convert back to numeric format, use %NDATE.

%JPERIOD can also be called as a subroutine.

Examples

The example below checks for expiration of a license period, calculates both elapsed time and future dates, and converts to and from Julian period values.

subroutine license_check 
record 
    jper1                       ,i4 
    jper2                       ,i4 
    remain                      ,i4                     ;Days remaining in license 
    license_dur                 ,i2,    14              ;License length in days 
    license_start               ,d8,    40317           ;License start date (March 17)
    todays_date                 ,a11                    ;Today's date 
    expire_date                 ,a11                    ;Expiration date 
proc 
    jper1 = %jperiod(license_start) 
    ;Returns the Julian period value for license start period 
    ; Use (hard-coded!) numeric date as an argument 
    jper1 = jper1 + license_dur 
    ;Calculate Julian period of the expiration date 
    expire_date = %date(jper1) 
    ;Find out date string of expiration date 
    todays_date = %date 
    ;Called with no arguments, returns today's date as an alpha string 
    jper2 = %jperiod(todays_date) 
    ;Returns the Julian period value for today 
    ;Use alphabetic date as an argument 
    remain = jper1 - jper2 
    ;How many remaining days has license left? 
    xcall warn("Warning: license expires on " + 
  &            expire_date + ", only " + 
  &            %string(remain) + " days left") 
    ;Use the things we've created to warn of impending DOOM! 
    xreturn 
endsubroutine