HPSTAC30.DOC

  NOTICE: Programs HPSTACK.LIB, HPSTACKS.LIB and documentation
          HPSTAC30.DOC are copyright (C) 1995-96 Ludvik Krulik, all
          rights reserved.

          If you distribute this software to others, you are required
          to distribute the entire unmodified package (ZIP file).
          Commercial use of this material is not allowed without prior
          permission from the author.


  WARRANTY:  Following libraries works ONLY on G/GX series HP48
             calculators. They contain unsupported code. Even though
             they have been extensively tested on various ROM
             revisions, USE AT YOUR OWN RISK.

             THIS SOFTWARE IS PROVIDED WITHOUT ANY WARRANTY. AUTHOR
             SHALL NOT BE LIABLE FOR ANY DAMAGES RESULTING FROM THE
             USE OF THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO, LOSS
             OF PROFIT, DATA OR USE OF THE SOFTWARE, OR INDIRECT,
             SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES OR OTHER
             SIMILAR CLAIMS.


             If you have any questions, suggestions or bug reports,
             e-mail me at Ludvik.Krulik@snet.fer.uni-lj.si





    1. Contents

       2. Overview
       3. Revision History
       4. Using HPSTACK library
         4.1 Running HPSTACK
         4.2 Display
         4.3 User keyboard
         4.4 Default Key Assignments
         4.5 Additional programs
           4.5.1 HIDE
           4.5.2 XARCHIVE
           4.5.3 QOFF
           4.5.4 CLDIR
           4.5.5 CST|
         4.6 Mapping of system menus
         4.7 Restoring system flags on warm start
       5. Credits
       6. Information about libraries





    2. Overview

       HPSTACK v3.0 = HP48 STACK shell:
       * Improved status line display. (I/O device, alarms, RAM
         cards...)
       * Entry mode sensitive user keyboard (CommandLine / Prg / Alg)
         even during input forms, etc.
       * Self activated on warm start.
       * Restores system flags on warm start.
       * Additional commands in MEMORY menu (HIDE, ->HDIR, XARCHIVE)
         and MODES/KEYS menu (ASNS).
       * Additional key bindings: extended PURGE, extended XRECV,
         XSEND.
       * Runs 'AUTOEXEC' on turn on.
       * Runs 'AUTOEXEC.BOOT' on warm start.
       * Link to HPAPPA library (1504), executes HPAPPA's appointment
         alarms.
       * Purge confirmation.
       * Lowercase menus and path display.
       * Beeps and runs quick off on turn off.
       * Included memory wise version - HPSTACKS.LIB



       HPSTACK consists of nine commands:
       - HPSTACK, stack shell itself,
       - SETUP, sets some options,
       - ASNS, assigns entry mode sensitive key definitions,
       - HIDE, hides variables in HOME and sub directories,
       - XARCHIVE, ARCHIVE via XModem protocol,
       - QOFF, quick turn on replacement for OFF command.
       - CLDIR, cleans directories of unwanted variables,
       - CST|, sets { HOME CST } as current menu,
       - ABOUT.





    3. Revision history

      - Version 3.0:
        * Renamed library from LKSHELL to HPSTACK.
        * Removed free memory display from status area. Displaying
          amount of free memory requires garbage collection before
          every update which slows down HP48 (especially GX)
          considerably.
        * Added display of flag -56 (Standard beep on) status.
        * Removed old alarm system and added link to HPAPPA
          library (1504).
        * Added mode sensitive user keys.
        * Removed some key bindings.
        * Added SETUP and removed SWITCH command.
        * Added restoring system flags on warm start.
        * Added lowercase support.
        * Added card status display.
        * Added interactive stack support.
        * Added HPSTACKS.LIB - memory wise version of HPSTACK library.

      - Version 3.0a:
        * RS+BS launch box didn't work correctly when in command line.





    4. Using HPSTACK library

    4.1 Running HPSTACK

      - First, choose between HPSTACK.LIB and HPSTACKS.LIB.
        HPSTACKS.LIB is memory wise version of HPSTACK.LIB and it
        lacks lowercase support (lowercase menus and path display).

      - Second, install library in port 0 or port 1.

      - After that you have a choice of how to run HPSTACK:
         * Mode 1:
           Enter HPSTACK library menu and press HPSTACK.

           In this way, HPSTACK is on top of original stack shell.
           When you warm start HP48 (ON+C), HPSTACK will disappear.


         * Mode 2:
           - Enter HPSTACK library menu and press SETUP.
           - Check "ACTIVATE HPSTACK ON RESET" field.
           - Press ENTER or OK.
           - Press ENTER or OK to de/activate HPSTACK.

           After warm start, ORIGINAL STACK SHELL WILL BE REPLACED
           ENTIRELY BY HPSTACK and will remain even after you
           warmstart HP48 subsequently.
           The only way to exit is to run SETUP again and uncheck
           "ACTIVATE HPSTACK ON RESET".

         ! Note: HPSTACK creates 'HPSTACKpar' in hidden directory.
                 DO NOT MODIFY 'HPSTACKpar' MANUALLY IN ANY WAY.

         ! Note: If you want to purge HPSTACK library, you will have
                 to deactivate it first.


                 
    4.2 Display

      - HPSTACK displays 4 line stack, lowercase menus and improved
        status area.

      - There is no 5/7 line stack (partly because I didn't feel the
        need for it, partly because I hate seeing command line switch
        between large and medium font when put on or taken from the
        stack).

      - Debugging environment is not implemented. In this case HP48
        will switch to original stack shell with it's default display
        and key assignments.

      - HPSTACK display of status area (from left to right):
        - angle mode: "RAD", "DEG", "GRD",
        - coordinates mode: "XYZ"(rectangular), "R<Z"(cylindrical),
                            "R<<"(spherical),
        - standard beep status: a small icon representing speaker with
                                or without sound,
        - I/O Device: a small icon representing wire or IR LED,
        - card status: card 1 inserted - roman 1,
                       card 1 write protected - inverted roman 1,
                       card 2 inserted - roman 2,
                       card 2 write protected - inverted roman 2,
        - alarms status: bell icon displayed means at least one alarm
                         is in alarm list,
        - user keys status: "1USR", "USER",
        - entry mode status: "PRG", "ALG",
        - current path in form: /subdir1/subdir2... with lowercase
          support,
        - date and clock in appropriate format.



    4.3 User keyboard

      Using user defined keyboard under HPSTACK is very similar to
      using original user keyboard. (See User's Guide, Customizing the
      Keyboard)

      First, entry mode table:
   =============================================================================
   | Algebraic | Program | Command Line | No Command Line || Entry Mode Number |
   |===========+=========+==============+=================++===================|
   |     -     |    -    |      -       |        +        ||       01          |
   |     -     |    -    |      +       |        -        ||       02          |
   |     -     |    -    |      +       |        +        ||       03          |
   |     -     |    +    |      -       |        -        ||       04          |
   |     -     |    +    |      -       |        +        ||       05          |
   |     -     |    +    |      +       |        -        ||       06          |
   |     -     |    +    |      +       |        +        ||       07          |
   |     +     |    -    |      -       |        -        ||       08          |
   |     +     |    -    |      -       |        +        ||       09          |
   |     +     |    -    |      +       |        -        ||       10          |
   |     +     |    -    |      +       |        +        ||       11          |
   |     +     |    +    |      -       |        -        ||       12          |
   |     +     |    +    |      -       |        +        ||       13          |
   |     +     |    +    |      +       |        -        ||       14          |
   |     +     |    +    |      +       |        +        ||       15          |
   =============================================================================
      If there are more + marks in one line, AT LEAST ONE entry mode,
      marked with +, has to be active to activate entry mode number.

      To assign built-in command or any object to a user key:
      1. Enter a list on stack containing:
         - built-in command or single object,
         - entry mode number,
         - E to execute object or D to treat it (the object/command,
           not key) by default (depending on entry mode)

           ! Note: Difference between E and D:
                   - { QOFF 15 E } executes QOFF when in PRG mode,
                   - { QOFF 15 D } inserts "QOFF " in your program
                                   when in PRG mode,

      2. Enter on stack key location number.
      3. Press ASNS (also found in KEYS menu, see 4.6 Mapping of
         system menus, below)

      Example1: Assign 3.14 to LeftShift+SPC (PI) in Algebraic
                Entry Mode.

                Solution:
                  * Put on stack:
                    2:        { 3.14 08 D }
                    1:                 94.2
                  * Press ASNS

      Example2: Assign LOCK command (from HPLOCK library, 1503) to
                LeftShift+ON (CONT) for EXECUTION (I guess you don't
                want "LOCK " inserted in your program) regardless of
                entry mode.

                Solution:
                  * Put on stack:
                    2:        { LOCK 15 E }
                    1:                 91.2
                  * Press ASNS

                If you assign LOCK in this way, you can lock your HP
                almost no matter where you are (some fields in input
                forms, command line...)

      Notes: * YOU CAN HAVE ONLY ONE ENTRY MODE SENSITIVE DEFINITION
               PER KEY SPECIFICATION.
             * After you have finished experimenting with user keys
               and want to make them permanent, do
               << RCLKEYS 0 DELKEYS STOKEYS >> to pack them together.
             * You have to understand that certain applications
               (built-in or external) don't allow processing of
               standard (user) key definitions. You won't have much
               use of user keys in such applications.

      

    4.4 Default Key Assignments

        ! Note: RS = Right Shift, LS = Left Shift

        - RS + ON beeps, runs QOFF to turn HP48 off. (see 4.5.3 below)
                  When you subsequently turn HP48 on, HPSTACK searches
                  for variable named 'AUTOEXEC' in current path and if
                  found, executes it. It's best to put 'AUTOEXEC' in
                  HOME directory. In this way it is accessible from
                  all sub directories.

        - RS + LeftArrow runs extended XRECV command.
                         Usage:
                         * Place variable name on stack and press RS +
                           LeftArrow. The object received via XModem
                           is stored in the given variable name.
                         * Place real number representing port on
                           stack and press RS + LeftArrow. The object
                           received via XModem is stored in the
                           specified port.
                         * In all other cases, pressing RS + LeftArrow
                           will place object, received via XModem, on
                           stack level one.

        - RS + RightArrow runs extended XSEND command.
                          Usage:
                          * Place variable name on stack and press RS
                            + RightArrow. Contents of the variable
                            will be sent via XModem.
                          * Place any other object on stack level one
                            and press RS + RightArrow. Contents of the
                            object will be sent via XModem.
                            NOTE: This key assignment overrides
                                  default SERVER command, attached to
                                  RS + RightArrow.

        -  LS + EEX runs extended PURGE - same as built-in PURGE, but
                    able to purge non empty directories. You will also
                    be asked to confirm purge if you checked "CONFIRM
                    PURGE" in SETUP.

        - If you have HPAPPA library (1504) installed,
          RS + 4 (TIME) runs two of HPAPPA programs. See HPAPPA docs
                        for more information.

        - RS + BackSpace brings up choose box for launching HPTODO,
                         HPAPPA, DBASE and HPCALENDAR libraries, if
                         you have any of them installed.
        
        ! Note: Above assignments are active if command line is not
                present.



    4.5 Additional programs

      4.5.1 HIDE

        Usage:
        - To hide variables: place list of visible variables on stack
          and run HIDE.
        - To unhide: place 0 on stack and run HIDE.

        Examples:
        - 1: { 'ABC' 'BCD' 'CDE' }           hides all variables except
                                             'ABC', 'BCD' and 'CDE'
        - 1:                     0           unhides all variables



      4.5.2 XARCHIVE

        Usage:
        - To run ARCHIVE via XModem protocol:
          * run XARCHIVE on your HP,
          * run XModem receive on your PC.
        - To restore HOME:
          * download archive of HOME to HP,
          * put it on stack,
          * run built-in command RESTORE.



      4.5.3 QOFF

        QOFF turns HP48 off. When you turn it on, HP48 doesn't check
        for new libraries etc., so it faster than standard OFF
        command. (depends on the number and size of libraries)
        IF YOU INSTALL NEW LIBRARY, YOU HAVE TO WARMSTART HP48 (ON+C)
        INSTEAD JUST TURN IT QOFF/ON.



      4.5.4 CLDIR

        Usage:
        - Place a list of all WANTED VARIABLES in variable called
          CLDIRpar.
        - Running CLDIR with CLDIRpar in current directory will purge
          all variables in current directory except those in CLDIRpar
          and CLDIRpar itself.



      4.5.5 CST|

        Usage:
        - Running CST| will set { HOME CST } as current menu.



    4.6 Mapping of system menus

        - LS+VAR will give you following menu:

          [XXXXX][ORDER][CRDIR][HIDE][->HDIR][XARCHIVE][RESTORE]...
                                   _    _
          ...[ARCHIVE][MEM][NEWOB][DIR][ARITH]

          where
          * [XXXX] is: - [MEMI ] if you have MEMINF program stored
                                 under 'MEMINF' name in HOME,
                       - [BYTES] otherwise.

          * [HIDE] and [XARCHIVE] run appropriate commands from
                                  HPSTACK library.
          * [->HDIR] puts you in hidden directory.

            ! Note: ->HDIR is not library command. You can not include
                    it in your UserRPL programs.

                   _
        - LS+CST, [KEYS] will give you following menu:

          [ASNS][   ][ASN][STOK][RCLK][DEL]

          where
          * [ASNS] runs appropriate command prom HPSTACK library.



    4.7 Restoring system flags on warm start

      * Setting up:
        - have system flags set according to your preferences,
        - run SETUP from HPSTACK menu,
        - check "RESTORE SYSTEM FLAGS ON RESET" field.

      * Removing:
        - go to hidden directory (press LS+VAR and [->HDIR]),
        - purge variable 'HPSTACKpar' (be sure not to purge something
          else).





    5. Credits

      - Richard Steventon and Andre Schoorl: lowercase menus and path
                                             display code.

      - Simone Rapisarda: code for hiding variables in HOME directory.

      - William C Wickes: XPURGE.

      - Thanks to the following people for suggestions and beta
        testing:

          Francois Vignon (100333.700@compuserve.com)
          Andrej Sila (asil@ltk6.fer.uni-lj.si)
          Erik Wever (ew@p20.wharfrat.fido.de)
          Makoto Miyamoto (Makoto.Miyamoto@rz.ruhr-uni-bochum.de)





    6. Information about libraries

       HPSTACK.LIB:
         - Version: 3.0
         - Library ID: 1502
         - Size: 7626.0 bytes
         - Checksum: #4179h

       HPSTACKS.LIB:
         - Version: 3.0
         - Library ID: 1502
         - Size: 4416.0 bytes
         - Checksum: #2FBBh