My Date Utility Programs

This library is a combined collection of code from various sources that I have just merged into usefull programs in the attempt to get any date information I need easily.

I had a lot of programs doing their own date routines, some needing julian dates, some gregorian; and finally I needed to know what day of the week a date was... (wikipedia has some examples of how to work that out) and I decided I was not replicating that between programs; so have merged everything into one library that returns everything about a date that I could use; and I am changing all my programs to use this library instead of doing it themselves.

This is not a macro library, its primary purpose is to provide/assemble useful programs to go into your linklist (or steplib) libraries and only two macros are actually needed in your assembler programs, one to create the data layout or dsect, the other used as an interface that based upon what parameters are passed to the macro will determine the correct program to link to to obtain the desired results.
These utility programs are designed to be called from other assembler programs, not to be run directly.

Note: this copy may not be in sync with the github version as while enhancements and bugfixes are applied to my git directories first whether I 'push' to github or copy the file here first depends upon what I am doing (ie: I may be doing a lot of changes in the massive git collection and if I need to do a tiny change to this library as part of that I may copy this file across to my webserver weeks before I am ready to push lots of changes to github; or I may push to github and forget to update this file on my webserver).

General Use

It is designed to be simple to use. All the key programs are easily accessable via a simple macro call to UDATEMAC to request the function to be preformed, the macro will determine what program is to be called based on the request. The only other thing you need is a data are (dsect or inline) mapped by UDATEVAR to address the returned valued by field name.

Functions available

The programs used by UDATEMAC provided in this library will return text displayable values describing a date and time for the following request types

• return the current date and time; calculated using either a TIME DEC or STCK method as you choose. If using the STCK method you can chose whether the timezone offset is added or UTC time is returned
• you can provide a supplied date and time to be used (in either TIME DEC or STCK format) to obtain information on past or future dates
• You can request the last IPL date and time information is returned

There are macros that may be used inline where calling a program may be overkill to

• test if a YYYY value is a leap year
• determine the day of week a date falls on

All the UDATEnnn programs currently in this library will all always return the following date information as character fields in a mapped DSECT for easy reference (see the UDATEVAR macro used to map the data area).

• The year (CCYY)
• The julian day (less the year bit already available above, so DDD)
• The current month and day (MMDD)
• The current time (HHMMSSht)
• The current day number (0=sunday thru 6=saturday)
• The day name, 'SUN' to 'SAT'.

The SCHEDnnn programs may require a different data area format, however the UDATEMAC will only (currently) invoke those if the CALCARD function is requested. Those SCHEDnnn programs were specifically created as utility programs for my job/command scheduler.
Current status is SCHED001 returns data in the expected structure, input format is not using that structure. SCHED002 is not yet compatible.
TODO: decide if I want the SCHEDnnn programs fully compatible requiring scheduler changes, or as they were created for the scheduler leave them as is with a leave alone warning. As SCHED002 returns a binary timestamp in Hsecs (so the scheduler knows what to put in a timer) rather than a data structure it will never really be compatible but the common macro could be updated to handle that.

The supplied dataset member TESTALL shows how to request each of the available standard UDATEnnn functions using the supplied macros. Additional test jobs are provided for macro-only and scheduler module testing; I may merge them into testall later.

Additional non-core Functionality added for scheduling

Obviously if there is a date library, the best way to show that it is usable is by writing a scheduler; stable eneough that it is the job scheduler I now use on my system :-).

• Added SCHED001 (scheduling utility) to obtain the standard data fields for a future date (ie: next sunday, next 13th, exact date in future etc).
  This can be considered a "core" program as I have forced it to fit into the UDATEMAC macro (bypassing version checking) for ease of use; but is was created as a scheduling function.
  One warning is that it will always return a valid date even if you provide a bad one, ie: if you provide December 33rd 2015 the data fields returned will correctly return January 2nd 2016
• Added SCHED002 (scheduling utility) to return the number of hsecs between the current time and a provided future time if the future time is within the next 24hr window
• Added MDSCHED1 (member SCHEDTST) which is a full function scheduler that can, based on time/day/date scheduling of course, submit JCL job members to be run and issue console commands from command members. Stable enough that I use this now.

Download Location

If interested download the current datetime library. The JCL will create two files, the main program library which is the JCL and ASM source to assemble the programs, and a TEST library containing jobs to test the programs are working plus a few possibly useful example programs.
The member $DOC explains usage.

This utility library will grow over time as I find more functions I need, for example I may one day handle 'TIME BIN' format, and maybe even take a passed text date and return STCK or TIME values; but I don't need them yet :-).

So keep an eye on this page.