CP/M/CPM_CDROM.iso/enterprs/cpm/utils/f/keys-128.ark/KEY128-3.DOC

Text File | 1989-09-27 | 14.5 KB | 295 lines

                       SAVEKEY and LOADKEY
                      For the Commodore 128
                           Version 3.0

                          Gene Pizzetta
                        January 16, 1988


Commodore includs a very nice utility program, KEYFIG, with C128
CP/M.  It allows you to assign strings to your function keys (or
any other key) or to completely redefine your keyboard.  You
could easily create a Dvorak keyboard if you wanted.

The problem is that it's not so easy to change the key
assignments if you'd like to have one set of function keys set up
for NewWord or WordStar, another set for SuperCalc, a third for
dBase II, a fourth for COMAL, and a fifth (default) set for
general uses like taking disk directories.  You've got to call up
KEYFIG and change each key individually before loading your
application program, or you've got to have several boot disks--
one for each set of function key assignments.

No More!  SAVEKEY will save the current key assignments at any
time to a small 1K file so you never have to recreate that set of
assignments again.  LOADKEY will load any file of key assignments
into your CP/M BIOS within a couple of seconds after you enter a
two-word command at the CP/M prompt.


USAGE:

     SAVEKEY {{d:}<fn>}

     LOADKEY {{d:}<fn>}

SAVEKEY will save the currently active key assignments to disk
under the given filename (<fn>) on the given disk drive (d:).  If
you don't give a drive designation, the key file will be written
to the current (default) disk.  If you don't enter a filename on
the command line, it will be requested by the program.  It is not
necessary to enter a filetype (extension) and if you do it will
be ignored.  All key files are created with a .KEY extension.  If
a file with the same name exists on the destination drive,
SAVEKEY will ask if you want to overwrite it and, if you don't
answer "y", request a new filename.  Any other error will abort
the program and send a "failure" code to the BDOS.

LOADKEY will load the key assignments in the given file (<fn>) on
the designated drive (d:) into the CP/M system.  If a filename is
not given, it will be requested by the program.  Unlike SAVEKEY,
if a drive is not given, the current drive will not be assumed.
Instead, LOADKEY will check the drive search chain in the System
Control Block and follow that chain looking for the file.  The
default drive will be checked only if it is part of the search
chain.  If a drive is specified, only that drive will be checked.
Any filetype you enter will be ignored; the key table file must
have a .KEY filetype and must have been written by the SAVEKEY
program.  LOADKEY checks to make sure the key file is exactly 8
sectors long before moving it to the BIOS.  But be warned that
any 8-sector file with a .KEY filetype can be loaded by LOADKEY
and, if it is not a file written by SAVEKEY, it will crash your
system.  If no file by that name is found or if any other error
is encountered, LOADKEY will complain and return you to the CCP
after sending a "failure" code to the BDOS.


CREATING CUSTOM FUNCTION KEYS:  KEYFIG is very easy to use.  It
is self-prompting and includes its own help file, so I won't
waste time and space explaining it's operation here.  The
keyboard can be set up just the way you want it and the new
configuration can be saved to your boot disk so it comes up your
way everytime you boot the system.

Custom key configurations for applications programs shouldn't be
saved that way, though, because you don't want them in effect
except when you're using the program.  So, after setting up the
keys for a particular program, choose the option to save the key
assignments as "current definitions", exit KEYFIG, and save them
to a file with SAVEKEY.

The four function keys give you 12 possible key assignments as
the unshifted, shifted, and control values.  The caps-lock value
for your function keys should probably be the same as the
unshifted value for function keys or you won't have access to
them when you have toggled on caps-lock by pressing the Commodore
key.

Good candidates for assignment to function keys are application
program commands that are used often and require you to enter two
or more characters.  For WordStar, for instance, you might want
to assign such commands as ^P^B for boldface, ^K^B and ^K^K for
marking a block, and ^O^G for temporary indent.  Then you only
have to press one key for those functions.  You might even want
to make the shifted or control values of your left and right
cursor keys issue ^A and ^F to move forward and backward a word
at a time.  After you get the keys the way you want them, exit
KEYFIG (after saving the new assignments as the current
definitions), and type
     A>savekey ws
to save the key configuration for WordStar on drive A as WS.KEY.
Whenever you want to use WordStar, just load the definitions and
call the program:
     A>loadkey ws
     A>ws sample.doc
You can even do it all in one line:
     A>loadkey ws!ws sample.doc
because CP/M Plus allows multiple commands in a single line,
separated by an exclamation point.

It would be a good idea to keep a copy of your default key
definitions on each applications program disk along with the
special key definitions so you can quickly change back to the
normal definitions when you exit the program.  I call my normal
key definition file CPM.KEY.  Whenever I exit WordStar or dBase,
I immediately issue the command:
     A>loadkey cpm

The logical color table for character and background colors is
saved to the file along with the key definitions.  Loading a new
color table has no immediate effect, however.  The change only
comes after a color change request is made via the correct escape
sequences, so this feature seems to have limited usefulness.


SETTING UP A DRIVE SEARCH CHAIN:  When you call a program by
typing its name at the CP/M prompt, the CCP searches only the
current default drive (or whatever drive you designate) for the
program.  You can, however, use the SETDEF command to set up a
search chain the the CCP will follow to try to find the program.

If you have more than one drive or a RAM expansion unit, you
should have a SETDEF command in your PROFILE.SUB so it will be
executed everytime you boot the system.  SETDEF is very easy to
use; just type "SETDEF" at the system prompt, followed by a
series of drive letters (up to four).

For instance, I have a RAM expansion unit and four other drives.
I always have some often-used utilities in the RAM expansion
(drive M), so I want the CCP to check there first.  My drive D is
a 1581, where I keep a disk containing another 700K or so of
handy utilities, like NULU, CRUNCH, UNARC, etc., so I want it to
check there second.  Drive A is where I run most of my
applications, so that drive should also be checked for a command.
Lastly, if the file is not found on any of those drives, I want
the CCP to look on drive B or C, if either is the current default
drive.  The following command will set up that search chain:
     A>setdef m:,d:,a:,*
The asterisk tells the CCP to check the default drive.  You don't
have to enter four drives.  If you only have one drive and a RAM
expansion, you would use:
     A>setdef m:,a:

If you have a RAM disk, you should probably also include a second
switch on the command line:
     A>setdef m:,d:,a:,* [temporary=m:]
That switch causes SUBMIT to create its temporary files on the
RAM disk and your SUBMIT batch jobs will execute like lightning.
(Without the above SETDEF switch, SUBMIT defaults to drive A.)

SETDEF doesn't change the CCP in any way.  I just puts the drive
search chain in a data structure called the System Control Block,
where the CCP (and LOADKEY) can find it.


PROGRAM NOTES:  Although Commodore's KEYFIG program allows
extremely flexible use of the keyboard, I never made use of the
function keys with applications programs because of the time it
took to change them and then change them back when I was through.
I dreamed of having a program to save definitions to disk so I
could change the function keys quickly.  After waiting for a year
and a half for one to appear, I decided I was going to have to
write it myself.  The result was SAVEKEY and LOADKEY versions 1.0
released February 25, 1987.

These two utilities are very small, so they load fast and work
fast.  SAVEKEY takes a little more time to open and write a file,
but LOADKEY can load itself and a keyboard definition in about
two seconds.  To keep them small there is minimal error trapping;
most errors during the disk read or write will abort the programs
with a BDOS error.  Still both programs make checks for illegal
characters in the filename and SAVEKEY checks for problems like a
full directory or full disk during the file write.

The BIOS MOVE and XMOVE routines are used to move the key table
between banks 0 and 1.  The routines are called more or less
directly by offsetting to the BIOS jump table.  I tried to make
these BIOS calls the "right" way by calling them indirectly
through BDOS function 50.  In fact, I tried repeatedly to get
that method to work through three versions now.  I couldn't.  I
don't know whether the problem is in the BDOS, in the BIOS, or in
my methods, so if anybody finds the solution I wish they would
let me know what it is.  In earlier versions I used direct
addressing into the BIOS, which worked with Commodore BIOS's, but
did not work with a modified public domain BIOS I ran across.
The offset method now used should work with any C128 BIOS, no
matter how extensively it is modified, as long as the key table
remains at 1000h in bank 0.

I put the drive chain search in this version because I sometimes
forgot to put a drive specification in the command line and
watched LOADKEY bomb with a "file not found" message.  I have
four drives and sometimes I wasn't sure which drive the file was
on, anyway.  The search chain shows what would be possible for
many commercial programs with overlays, such as WordStar or dBase
II, if they had been written for CP/M Plus.  Nevertheless, we can
use this method for programs we write that require overlays or
other special files.  The SEARCH subroutine in the LOADKEY source
code is relatively short and easy to understand.  It receives the
address of the File Control Block in HL and, if it finds the
file, it returns with the file already open for reading and the
FCB updated to the correct drive.  If the file is not found
anywhere in the chain, it returns with the zero flag set.

The search pattern is modelled on the one followed by the CCP in
that the chain is not followed if a drive specification is given
for the file.  The only difference is that the CCP checks the
current user area and then checks user 0, while the SEARCH
subroutine only checks the current user area on each drive.  I
don't believe that many Commodore owners are using user areas, so
I didn't include that feature.  It would be easy to add, however,
so if I'm wrong please let me know.

ZCPR3 uses a similar but incompatible technique to search for
files.  I would be nice if a few of you would try converting some
of ZCPR's more useful utilities, such VFILER, to CP/M Plus.  The
source code is available from most Z-Nodes and from SIG/M.

In my public domain DISKNUM program, I used another technique
which allowed the program to determine which drive it was loaded
from.  Like the drive search chain, it's easy under CP/M Plus,
but not available under earlier versions of CP/M.


HISTORY:  Version 1 was released February 25, 1987.  I haven't
been notified of any bugs and I haven't discovered any myself.
However, if you have a file with a .KEY filetype that isn't a key
definition file saved with SAVEKEY and you tell LOADKEY to use
it, LOADKEY will promptly load it, or the first eight sectors of
it if it's a long file, and crash your system.

Version 2 was released May 23, 1987.  The most noticeable change
is that my name is no longer displayed in the screen sign-on
message.  I decided that was an ego trip I should no longer
inflict on the rest of you.  I also converted some of the opcodes
to Intel Z80 macros available in Z80.LIB.

The most important change in version 2 is for sophisticated batch
users.  If the .KEY file is not found, or any other error occurs,
a failure return code is sent to the BDOS for use during
conditional batch jobs.  For instance, if you have a .KEY file
you use with WordStar, you could issue the following command line:
     A>loadkey ws!:ws sample.doc
Notice the colon before the second command.  If LOADKEY does not
find WS.KEY on a drive in the drive chain, it issues a "File Not
Found" message, sends a failure code to the BDOS, and the CCP
does not execute the second command to load and run WordStar.
Without the colon WordStar would be loaded anyway.  This same
procedure will also work in SUBMIT files.

Version 3, released January 16, 1988, adds a good deal of error
trapping, including an attempt to verify the validity of the .KEY
file before it is moved to the BIOS, detection of illegal
characters and wildcards in the filename, full directory, etc.
LOADKEY also adds a SCB drive chain search if a drive
specification is not given for the key table file.


RE-ASSEMBLY:  Although I use SLRMAC for assembly language
programming, both these programs can be re-assembled with MAC if
you change the filetype from .MAC to .ASM.  In addition, you must
have Z80.LIB on the default drive or use the $Ld switch (where d
is the drive) to tell MAC where it can find Z80.LIB.  Z80.LIB is
included with the additional utilities from Commodore you got by
sending in that card in your manual.  If you didn't send the card
in, you won't have MAC and HEXCOM, so you won't be able to re-
assemble these programs anyway.


If you have any problems with either of these programs, or if you
have any suggestions for improvements, please let me know by
letter, telephone, or through one of the bulletin boards below.
Happy computing!

                                   Eugene L. Pizzetta
                                   481 Revere Street
                                   Revere, MA  02151

                                   Voice:  [phone]
                                   CompuServe:  72060,505
                                   Q-Link:  GeneP
                                   GEnie:  E.Pizzetta