DAX
                                ===

DAte entry eXternal. This is a date entry tool to be used in programs that
require user input of a date. Enter or edit a given date and return result
as a long word to the calling program.

This program is freeware and the source code ©pjwitte 2oo2..2oi7+. You may
modify it and re-distribute it under normal rules of Open Source Software.



Usage users
===========

Note: The applet is limited by the QDOS/SMSQ date range limitations. It can
only correctly handle dates between 1961 Jan 01 00:00:00 and
2097 Feb 06 06:28:15. Some programs may experience problems with dates
later than 2029 Jan 19 03:14:07.

Program Window:
---------------
Press and hold the mouse button on the titlebar to move the window
Click the X-it button to quit without sermony
DO on a menu field to return the selected date and exit the applet
HIT an item to select or edit it (The date string (top) can  be edited)
HIT an arrow to scroll a setting (Year, Hour, Minute, Second)
DO  an arrow to scroll in larger increments
DO the Weekday header (M T W T F S S) to set today's date and time

Keyboard shortcuts:
-------------------
Use cursor keys to move to the title bar and press SPACE to get to the
 old fashioned move sprite operation

D - move to date field
M - move to month field
Y - move to year field
H - move to hour field
I - move to minute field
S - move to second field
ENTER - to return the new date
ESC   - to return the original date

Editing the date string:
------------------------
HIT the date string to manually edit the date
Once you enter the date string editor you can either enter date and
time directly from the keyboard or use the up and down keys to increment
or decrement the different parts of the date string. Terminate editing
with DO or ENTER. Another DO, ENTER or ESC is required to exit the
applet in the usual manner.


Usage programmer
================

From a programmer's POV, DAX is called up as an external program. The
calling program must wait for the utility to complete before continuing.
It is a good idea to have some circuity running to take care of the event
that the job is killed off or buried, or becomes hidden under the calling
program's window. See Examples below.
                      ========

Command Line
------------

The applet can be instructed via the command line [default value]:

        /X      = x-postion at startup          [-1]
        /Y      = y-postion at startup          [-1]
        /D      = start date highlighted (hex)  [current]
        /P      = palette 0..3, address (hex)   [0]
        /R      = return address (hex)
        /S      = sound on/off 1/0              [1]
        /T      = title text up to 18 char      [Date]

Each command key is preceded by a slash / and followed by its parameters.
Parameters with enclosed spaces may be quoted. The reasons for using hex
are that it is a convenient way to accurately pass long integers (such as
memory addresse and dates) as strings. Use HEX$(number, 32) to convert long
integers to fixed length strings.

The /R (Return address) parameter, if present, must point to a minimum 4
byte memory space where the result will be returned as a date code. If the
parameter is not present the result is returned as a standard date string
in the Stuffer Buffer, where it may be got with ALT + SPACE or,
programatically, with HOT_GETSTUFF$.

Examples:

         /X-1 /Y-1 /D 693AF0C7 /T From date /S0 /P1 /R00101894

         /X60 /Y 40 /T"Set date" /P005D6214

Parameters may be used in any order, and defaults will be used where
parameters are omitted. (Unsupported parameters will probably be ignored.)

Evoke with EX_M or FEW or equivalent. This ensures that the applet doesnt
poke its result into an unreserved memory location in the event the
calling job is unexpectedly removed:

        id = FEX_M(<progname>); <parameter command line>
        IF id > 0: PRINT HOT_GETSTUFF$: ELSE ERT -15


Examples
========

        (See Harness_bas)


Testing
=======

To test, unzip to a ram disk. unzip will create the necessary sub
directories. Make sure the following toolkits are pre-loaded:

        QLib_run or equivalent
        ptrmen_cde or equivalent (must be loaded by job #0, eg in boot)

On none-SMSQ/E systems, like QDOS or Minerva, make sure the Pointer
Environment, ie ptr_gen and wman, are loaded too.

LOAD and RUN the Harness_bas SBASIC program stub from a console window.
Once you have set a suitable date (DO a selected field) the program
will exit. If you provided a return buffer, the date code can be fetched
from there with a PEEK_L(buffer). This code can be converted to the
standard date string using the DATE$ command. If no buffer was provided,
the date is returned as a string in the Stuffer Buffer.

Note: To run the SBASIC code, the toolkit DAX_cde needs to be loaded, in
addition to the other toolkits mentioned. To compile it with Qliberator,
the DAX toolkit must be available: Alter the first line of the program
to suit. The other toolkits mentioned must be pre-loaded.

It may be possible to compile it with Turbo. This will require suitable
Turbo directives to be added.


Manifest
========

This applet may be part of another program, in which case not all
components listed here need to be present. This manifest only applies
where this program is supplied on its own, eg for development purposes:

        Dax_txt         this file
        Dax_obj         the Dax executable program
        Dax_bas         the SBASIC source code
        Harness_bas     a simple program to demonstrate usage

        rxt_
         Dax_cde        the Dax toolkit and menu definition

        men_
         Date_men       main date menu (also compiled into toolkit)
         ..             assorted sprites

        thm_
         black_thb      sample palette


Acknowledgements
================

DAX was written for and under Marcel Kilgus'es excellent QPC2 emulator,
running SMSQ/E 3.27 (by Tony Tebby and others), using JMS'es QD text
editor. It was compiled with Liberation Software's QL compatible Q_Liberator
compiler. The menus were designed and realised with the aid of Albin
Hessler's superb Easy Pointer toolkit and utlities (updated and much
enhanced by Marcel Kilgus). The free DAX_cde toolkit was created by me,
the source code for which may be viewed by polite request, but does not
form part of the overall Open Source part of this project.

Please let me know if you discover any bugs or if you have suggestions for
improvements.

If you find this utility worthwhile and useful let me know! This is
essential if you wish me to continue developing and making available
software for QL systems.

----------------
P Witte, December 11th 2016

               Conditions of use and DISCLAIMER as per Knoware.no