5.1.8 Date variables

Gcal respects global and/or local date variables which may be used either in the date part of a Gcal resource file line, or which may be part of a special text in the text part of a Gcal resource file line. This means, up to 24 user-defined date variables can be set and referenced during program execution. See Fixed date option --date-variable=argument, for more information how global date variables can be used.

A date variable name dvar consists of a single, case-insensitive letter⁶¹. In a definition, this name is trailed by the assignment operator character ‘=’, and the numerical values of month mm (or a short, three characters month name, e.g. ‘Jan’, ‘Feb’…) and day dd, this variable has to store⁶², e.g.:

a=1127
c=a

stores the 27th November into the local date variable a and into the local date variable c. You should always remember that date variables can only be referenced in a line if they are already defined, because Gcal processes a resource file line by line.

Only local date variables can store dynamical dates given in the mmwwwn, dvar[+|-]n[www] or *d|wn[www] format, e.g.:

a=03su2
b=JunMon9
c=b-3
d=c+4Sa
x=*d10
y=*d10fri
z=*w3Su

which means, date variable a stores the date of second Sunday in March and b stores date of last Monday in June. The date variable c stores the date which is three days before the date of the last Monday in June and this date is set in the date variable d to that date which is four Saturdays after the date of c. The date variable x stores the date of the 10th absolute day of the year (≡ 10th January). y stores the date of the 10th Friday of the year, and the assignment to z is the date of the Sunday which occurs in the 3rd week of the year.

Caution:
These kinds of assignments to date variables are only computed correctly in simple year bounds —which means during a current year— and not in fixed dates shown after the current year has changed, e.g. in fiscal years.

Date variables which are defined in a resource file are always local and only respected in this specific file, and that file which is included by it. This means for the included file, that all local variables of the caller are visible. The included file itself may define its own local variables in its own name-space, which are not exported to caller on return. All other definitions of date variables⁶³ are always global. If a resource file line contains a reference to a date variable which is not locally defined in that file, Gcal will try to use the global values held by this variable. If this fails because no global definition of this date variable is given, Gcal will not process this line. If the simple --debug respectively --debug=internal option is given, informational messages for each undefined date variable will be shown on the standard error channel (see Global option --debug=internal). If the --debug=abort option is given, the Gcal program will be aborted with an error code when the first undefined global date variable reference occurs. See Error Code 113, and Global option --debug=abort, for further information.

A local date variable can be deleted. This means, that this date variable is no longer valid in its local scope and be undefined therefore. So it is possible to use its potentially defined global value in succeeding lines if this date variable is referenced there. The following example of the resource file dvar-1.rc elucidates these facts:

$ cat dvar-1.rc
-| ; dvar-1.rc
-| ;
-| z=0202
-| 0@z The local assigned date to `z'
-| z=
-| 0@z The global assigned date to `z'
-| z=0404
-| 0@z The local assigned date to `z'

So Gcal creates the following output:

$ gcal %1777 -H no -x -v z=1212 -f ./dvar-1.rc -y
-|
-| Sun, Feb   2nd 1777: The local assigned date to `z'
-| Fri, Apr   4th 1777: The local assigned date to `z'
-| Fri, Dec  12th 1777: The global assigned date to `z'
$ gcal %1777 -H no -x -f ./dvar-1.rc -y
-|
-| Sun, Feb   2nd 1777: The local assigned date to `z'
-| Fri, Apr   4th 1777: The local assigned date to `z'

Only advanced users should apply the --export-date-variables option which causes that the actual incarnation of a local date variable —which was previously defined in a resource file and not in an included file— is being exported to further resource files instead of using its global value, in case that date variable is not locally defined in that further resource file. See Include directives, for more details.

But be aware, the use of this option could create unwanted results, because the order of processing the resource files is an important entity in managing the --export-date-variables option, so it is not recommended to use it. You, the user, must exactly know what you are doing when applying this option; you are expressively warned now!

Some basic operations can be performed on date variables. These are:

The scope of the operations which are done on a local date variable, is that resource or include file, where the local date variable is defined.

If operations on a global date variable are performed in a resource file or that file which is included by it, these operations are only valid in that specific file⁶⁴, not in further resource files processed. This means, the initial values of global date variables are always restored if the resource file changes.

Please finally note, that each date variable assignment/operation must be given separately on a single line in the resource file.