Next: , Previous: Include directives, Up: Resource file


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 letter1. 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 store2, 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 variables3 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:

Operation Description

dvar++ Simple increment by one day.
dvar-- Simple decrement by one day.
dvar+=[+|-]n Addition of a constant numerical day factor [+|-]n.
dvar-=[+|-]n Subtraction of a constant numerical day factor [+|-]n.
dvar+=nwww Addition of n weekdays www.
dvar-=nwww Subtraction of n weekdays www.

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 file4, 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.


Footnotes

[1] Except the date variable e which is internally reserved for the Easter Sunday's date, so it cannot be assigned or operated therefore. And except the date variable t which is internally reserved for today's date, so it likewise cannot be assigned or operated.

[2] Or the name of another date variable, which is already defined.

[3] In the command line, environment variable GCAL or response file.

[4] They are only done locally.