%OP%BON
%OP%JUY
%OP%PL66
%OP%TM1
%OP%HM2
%OP%FM2
%OP%BM1
%OP%LM5
%OP%HE/%H2%Z88 Users' Club Software Library%H2%/
%OP%FO/%H2%Z134%H2%//@P@/
%OP%DEZ88FKEYS.BAS USER GUIDE
%CO:A,80,70%%C%%H2%"Z88FKEYS.BAS"   (Version 4.01)

%C%%H2%FUNCTION KEYS FOR YOUR Z88

%C%Written by George R. Ogden (Z88 Club Membership No.1078)

22nd May, 1991


%JR%%H2%IMPORTANT%H2% - Users of versions before 3.0 please note changes marked 
%C%"%H2%#%H2%"


%H1%%H2%1 INTRODUCTION

%JR%I wrote this BASIC program, my first serious attempt on my trusty 
%JL%Z88, because I wanted to be able to create a set of function keys 
%JR%which would emulate the function of the keys I normally press while 
%JL%using my office PC when "online" to mainframe host applications.   It 
%JR%started out as quite a simple effort but I soon realised, largely 
%JL%through seeing Michael (the club's *CLI expert) Hey's menu programs, 
%JR%that it could perform a much wider role.   So it grew, and grew, 
until it became what you see today.

%JL%If you're just a Z88 beginner, %H2%DON'T PANIC%H2%.   It's really quite easy 
%JR%to use and, as far as I can tell after a certain amount of trial & 
%JL%error and luck will have it, crash proof.   It will enable %H1%ANYONE%H1%, 
%JR%even an absolute novice, to create a sequence of *CLI instructions 
%JL%(see your Z88 user manual) and assign them to a specific key on the 
Z88.

%JR%If you're an expert Z88 user, then I hope you'll find it an easier 
%JL%method of creating & using *CLIs and running other BASIC programs.  I 
%JR%certainly do! Also, the fact that you don't need the BASIC Patch, can 
%JL%minimise the number of suspended applications and will no longer need 
%JR%to use up space for CLI files should help offset the size of the 
program, which is just under 14k.

%JL%Whichever, the program can really unleash the power of the Z88's *CLI 
%JR%capabilities, greatly reduce wear & tear on your Z88's keyboard, your 
%JL%fingers, avoid severe mental strain and astound your friends (well 
maybe just a bit).


%H1%%H2%2 OUTLINE

%JR%Basically, this program will allow you to create up to 148 function 
%JL%keys (the maximum number of keys the standard Z88 keyboard can 
%JR%generate as far as I can tell) and group them together to be 
displayed on 16 "Menus", each of up to 18 keys, to suit your needs.

%JL%Those of you good at mental arithmetic will have spotted the anomaly 
%JR%in the last paragraph.   16 menus times 18 keys equals 288 yet the 
%JL%number of potential function keys is only 148!   This is so that you 
%JR%can repeat the display of a key, or number of keys, on more than one 
%JL%menu.   The key will ALWAYS carry out the same function.   This is 
%JR%helpful for some functions which are common to more than one menu.   
%P0%
%JL%All the same, you can execute ANY function key whatever menu is 
%JR%displayed avoiding the need to select and display the appropriate 
menu.

%JL%The function of the %H2%<>T%H2% key is "FIXED" to print the current date in 
%JR%the file you were editing, a letter perhaps, before you pressed %H2%[]B%H2% 
%JL%to go back to the function key program - you can change this (see 
%JR%Hints&Tips) but this only leaves you with 147 programmable keys!  The 
%JL%reason for doing this is that, while it's a useful function, in order 
%JR%to obtain the date ONLY, a short BASIC procedure is required to 
%JL%extract the required string (otherwise the day, as a word, and the 
time would be included).


%H1%%H2%3 RUNNING Z88FKEYS

%JL%The program is standard Z88 BASIC therefore all you need to do is go 
%JR%into BASIC from the Applications window or by pressing %H2%[]B%H2%, type 
%JL%%H2%CHAIN"LIBRARY/Z134B"%H2% (unless you have <>REnamed it) and then press 
the %H2%ENTER%H2% key. 

%JR%Please note - you can run the program over Richard Russell's BASIC 
%JL%Patch, however, if you do, be sure that the *CLI command is no more 
%JR%than 253 characters in length as this is the changed limit of the 
%JL%input buffer (normally 255). If you exceed this it will cause your 
%JR%Z88 to Hard Reset - if not then and there almost certainly very soon 
afterwards!

%H2%#%H2% Two important things to note,

%JL%%H1%%H2%ONE%H2%%H1% - Function keys are stored as separate default file %H2%Z88FKEYS%H2% with 
%JL%an extension of %H2%.KYS%H2%.  This is created automatically when running the 
%JR%program for the first time.  Thereafter, use the %H2%SAVE%H2% option from 
%JL%Menu Maintenance to save any changes you make to functions or menus.  
%JR%This will allow you to create multiple %H2%.KYS%H2% files to suit any 
%JL%application.  All menus are automatically saved with the %H2%.KYS%H2% 
extension.

%JL%When starting up the program, the default file, %H2%Z88FKEYS.KYS%H2% is 
%JR%automatically restored however, you can stop this by pressing ESCape 
%JL%and then use the %H2%RESTORE%H2% option from Menu Maintenance to restore the 
%JR%%H2%.KYS%H2% file required.  Alternatively, you can go straight to define new 
function keys and menus.

%JL%Of course, don't forget to %H2%SAVE%H2% the menu details before %H2%<>KILL%H2%ing the 
application or before you %H2%RESTORE%H2% another %H2%.KYS%H2% file.

%JR%%H1%%H2%TWO%H2%%H1% - I have adopted Simon Phipps' excellent idea of using an entry in 
%JR%a %H2%CONFIG.SYS%H2% file in :RAM.0 to hold the directory path of the %H2%.KYS%H2% 
%JL%files so that there is a consistent path when restoring and, as 
%JR%important, saving a menu.  I would also highly recommend this 
%JL%approach to others writing Z88 applications - it could, for example, 
%JR%be used to hold both paths and the name of application specific 
configuration files or parameters.
%P0%
%JR%On running the program for the first time, if you don't already have 
%JL%a CONFIG.SYS file in :RAM.0 it will be created, alternatively, if you 
already have a CONFIG.SYS file it will be updated with the entry -

%H2%Functionkeys=:RAM.1/FKEYS/%H2%

%JR%Also, the program will run a CLI to create the default directory 
%H2%:RAM.1/FKEYS%H2%.  

%JR%You can change this later to a name of you own choosing but be sure 
%JL%that both the directory name and the CONFIG.SYS entry are consistent.  
%JR%Note that the final %H2%/%H2% %H1%is%H1% required to complete the path name correctly 
in CONFIG.SYS.


%H1%%H2%4 SELECTING A MENU

%JR%At the introduction screen, or while a menu is displayed, you can 
%JL%change to any of the 16 menus by pressing an %H2%ARROW%H2% key and, if 
%JR%required, along with a %H2%SHIFT%H2%, %H2%DIAMOND%H2% or %H2%SQUARE%H2% key.  Although, the 
%JL%first time you run the program there will be no keys assigned to it!   
%JR%So, you'll need to do two things before you can really use the 
%JL%program - first, create a function key or keys and, second, create a 
menu! (see below).


%H1%%H2%5 LIST OF AVAILABLE KEYS

%JR%By pressing %H2%[]INDEX%H2% (both at the same time) a list of the available 
%JL%function keys will be displayed.   After you've assigned a title to a 
%JR%key it is omitted from the list so you can easily find the remaining 
available keys.

%JR%Keys available include both upper and lower case alpha keys (see 
%JL%Hints&Tips) as are numbers, symbols like %H2%^%H2% or %H2%@%H2%, DIAMOND upper case 
%JR%letters - and some you may not have come across before such as SHIFT 
ENTER, SQUARE DELETE and DIAMOND SPACE!


%H1%%H2%6 EXECUTING A FUNCTION

%JL%It really couldn't be easier, from within a menu display, simply 
%JR%press the appropriate key!   The key description will appear at the 
%JL%bottom of the screen and away it'll go.   But of course, you'll have 
to create it first so read on.


%H1%%H2%7 THE HELP MODE

%JL%By pressing the %H2%[]HELP%H2% keys together, the HELP mode is toggled on and 
%JR%off.   When on, the execution of a function key is disabled and, 
%JL%instead, it is displayed on the bottom line of the screen so that you 
%JR%can remind yourself of its purpose if you forget.   I often have to 
%JL%resort to this for some of my less often used functions.  If the 
%JR%command is too long to be displayed in full it will show a %H2%++%H2% symbol 
%JL%at the end of the line.  If this is still insufficient use the edit 
%JR%key option to display the entire command and press ESC rather than 
re-type the key description and command again.
%H1%%H2%8 CREATING A FUNCTION KEY

%JR%To create a function key press %H2%[]MENU%H2%, both at the same time or 
%JR%you'll get the BASIC Menu screen which is just as helpful as the 
%JL%BASIC Help screen! (if so press any key and try again).   The %H2%MENU%H2% 
%H2%MAINTENANCE%H2% screen will appear.

There are five options to choose from, %H2%K, L, M, R%H2% and %H2%S%H2%. 

%JL%Either %H2%K%H2% or %H2%L%H2% can be used to create a *CLI and allocate it to a 
function key. 

%JR%The %H2%K%H2% option can be used if you already know the *CLI key sequence 
%JL%you want to allocate to a particular function key OR when you want to 
%JR%execute a BASIC program on pressing a function key.  See Hints&Tips 
for more information.

%JL%The %H2%L%H2% option can be used when you don't already know the *CLI you 
%JR%want to allocate to a function key and you want the program to 
%JL%"LEARN" the *CLI key sequence.   This is ideal for the novice and, I 
%JR%must admit, my preferred option as it takes the hassle out of it all 
AND gets it right first time!

Once either is selected simply respond to the prompts.

%JL%Later, if you wish to redefine a key then follow the same procedures.   
%JR%To delete a function key, select %H2%K%H2% and press the desired function 
%JL%key.  Then press %H2%ENTER%H2% at the prompts to blank out (null) the 
%JR%function key title and *CLI key sequence or the name of the BASIC 
program to be executed.


%H1%%H2%9 CREATING A MENU

%JL%Bring up the %H2%MENU MAINTENANCE%H2% screen by pressing %H2%[]MENU%H2% and select 
the %H2%M%H2% option.

%JR%You will then be prompted to press the menu selection key of the menu 
%JL%you wish to create.   This requires you to press an %H2%ARROW%H2% key and, if 
required, along with a %H2%SHIFT%H2%, %H2%DIAMOND%H2% or %H2%SQUARE%H2% key.

%JR%Having selected the menu you wish to create, you will then be asked 
%JL%to type the menu title required.   Once you've typed it press %H2%ENTER%H2% 
%JR%and the new menu title will be displayed at the top of the screen.   
If you've typed it incorrectly, you will get a chance to correct it!

%JL%The keys, up to 18, already allocated to that menu are then displayed 
%JR%on the left hand side of the screen.   Of course, if none have yet 
been allocated then the lines are blank!

%JL%You will then be prompted to press the function keys you wish to 
%JR%assign to the menu and, as they are pressed, they are displayed in 
%JL%bold on the right hand side of the screen.   A menu key allocation 
%JR%count is kept on the seventh line.   If you want to allocated less 
%JL%than 18 keys to a menu (0-17) simply don't press any key, wait about 
5 seconds for the prompt on timing out and then respond.


%H1%%H2%10 SAVING A MENU

%JR%Bring up the %H2%MENU MAINTENANCE%H2% screen by pressing %H2%[]MENU%H2% and select 
%JL%the %H2%S%H2% option.  Then type in the name wish to use %H2%%H1%WITHOUT%H1%%H2% quotes, the 
%JR%extension %H2%.KYS%H2% or the directory path, e.g.  %H2%Z88FKEYS%H2% for the default 
%JL%menu and press %H2%ENTER%H2%.  The path assigned by reading the CONFIG.SYS 
%JR%file is displayed below and the extension .KYS is added 
automatically.

%JL%The reason for not automatically saving a menu with the default name 
is to avoid overwriting it by mistake.


%H1%%H2%11 RESTORING A MENU

%JR%Bring up the %H2%MENU MAINTENANCE%H2% screen by pressing %H2%[]MENU%H2% and select 
%JL%the %H2%R%H2% option. Then type in the name wish to use %H2%%H1%WITHOUT%H1%%H2% quotes, the 
%JR%extension %H2%.KYS%H2% or the directory path, e.g. %H2%NEWMENU%H2% and press %H2%ENTER%H2%.  
%JL%The path assigned by reading the CONFIG.SYS file is displayed below 
and the extension .KYS is added automatically.

%JL%If you either leave the name blank and press ENTER or press ESCape 
the default menu %H2%Z88FKEYS%H2% is restored.


%H1%%H2%12 HINTS & TIPS%H1%%H2%

%JR%%H2%ONE%H2% - To maximise the amount of available memory on your Z88, use the 
%JL%function key program to automate the loading, saving and <>KILLing 
%JR%(if required) of applications and files in regular use.  This will 
%JL%minimise the number of suspended applications and thus the 
%JR%duplication of files stored in RAM.  I only ever have three 
%JL%applications running at any one time - Z88FKEYS (of course!), my 
diary and the application/file currently in use.

%JR%%H2%TWO%H2% - In addition to creating a rather large number of function keys, 
%JL%the execution of existing function keys can be "chained" into a new 
%JR%function key.  Therefore think about creating a number of simple 
%JL%functions which can be used both stand alone and as part of a more 
complex function.  A chained function would look something like this,

%H2%*#P|fl:ram.1/address.dat~E#BA#B|R#Bz#B^#B7%H2%

%JR%The above function key command would first go to Pipedream (%H2%#P%H2%), load 
%JL%(%H2%|fl%H2%) your address file (%H2%:ram.1/address.dat~E%H2%) then go back to the 
%JR%menu (%H2%#B%H2%) and execute the function key %H2%A%H2% command, then by returning 
%JL%to the menu with %H2%#B%H2% execute the function key %H2%<>R%H2% (represented by  
%JR%%H2%|R%H2%). Then, again return to the menu with %H2%#B%H2%, execute the function key 
%JL%%H2%z%H2% command, then %H2%^%H2% etc. finally finishing with executing function key 
%JR%%H2%7%H2% which may, or may not, return you to the menu and execute another 
%JL%string of commands!  This will allow you to create very complex 
%JR%function keys comprising a number of simpler functions. This will 
%JL%reduce the space, and more importantly, effort required by re-using 
%JR%standard functions rather than having the whole sequence repeated for 
%JL%each function key.  As Michael Hey has already said, there are no 
%JR%real limits to what can be achieved using the *CLI - just use your 
imagination. 

%JL%One %H2%IMPORTANT%H2% thing to note if chaining function keys - it is 
%JR%important that only one instantation of BASIC is active -  the 
%JL%Function Key program of course! - otherwise the *CLI gets lost.  
%JR%Alternatively, the all the single %H2%#B%H2%s can be changed to %H2%#B#B%H2%s - then 
of course you must always have two instantations of BASIC active!

%JL%%H2%THREE%H2% - BASIC programs run from the menu and within the same 
%JR%instantation of BASIC can be altered to include the following two 
%JL%lines.  If they are included, and the program re saved!, then, when 
%JR%running the program pressing the %H2%ESCAPE%H2% key automatically returns you 
to the menu:

%H2%1.%H2% At or very near the beginning - line number N followed by:
%H2%ON ERROR GOTO X%H2%
%L%%H2%2.%H2% At the very end - line number X followed by:
%H2%IF ERR=17 CHAIN":RAM.1/Z88FKEYS.BAS"%H2%

%JL%N being a line number (e.g.10) and X being last line number (e.g.50000) 

%JL%Note, there may already be an ON ERROR statement in the BASIC program 
in which case it may be possible to amend it as above.

%JR%%H2%FOUR%H2% - When running BASIC programs, rather than ESCaping from 
%JL%Z88FKEYS and reload it when ESCaping as above, you can save the 
%JR%reloading time by starting up a second instantation of BASIC.  
%JL%Z88FKEYS will automatically switch to the second instantation and 
%JR%chain in the program.  If you prefer this option then amend your 
%JL%BASIC program as above changing the %H2%CHAIN":RAM.1/Z88FKEYS.BAS"%H2% to 
%H2%*CLI#B:CLS:END%H2%

%JR%%H2%FIVE%H2% - After chaining a BASIC program you might want to continue the 
%JL%command to, say, load a data file.  In which case, rather than having 
%JR%to either type it in or go back to Z88FKEYS to execute another 
%JL%function key, consider not using RUN* and create a * function like 
%JR%this - %H2%*|[ CHAIN"PROG.BAS"~EDATAFILE.DAT~E%H2% (|[ = ESCape from Z88FKEYS 
%JL%into current instantation of BASIC) or alternatively use 
%JR%%H2%*#BCHAIN"PROG.BAS"~EDATAFILE.DAT~E%H2% (#B to switch to a second 
instantation of BASIC).  The %H2%~E%H2% represents the ENTER key.

%JL%%H2%SIX%H2% - For those who are concerned about assigning different functions 
%JR%to "A" and "a" and mistakenly executing the wrong one, try pressing 
%JL%the %H2%[]CAPS LOCK%H2% keys at the same time to reverse the function of the 
%JR%%H2%SHIFT%H2% keys. This has the effect of leaving the upper case letters as 
%JL%standard and the lower case letters accessed by pressing shift and 
%JR%the appropriate key in much the same way as you would execute a %H2%<>%H2% 
upper case letter.

%JL%Alternatively, if you are still unhappy about this possible mistake 
%JR%occurring, load the program rather than chaining it and type in the 
following BASIC line -

%H2%3050 IF L>96 AND L<123 L=L-32

%H2%**** Then SAVE"Z88FKEYS.BAS"

%JL%This will now ensure that, even if the lower case letter has been 
assigned a function, only the upper case letters can be executed.

%JR%%H2%SEVEN%H2% - To change the function key assigned to printing the date set 
in the program to %H2%<>T%H2% the following BASIC lines need to be altered.

2460 md$(%H1%%H2%20%H2%%H1%)="TodaysDate>Application":c$(%H1%%H2%20%H2%%H1%)="FIXED"
3800 IFL=%H2%%H1%20%H2%%H1% PROCd:OSCLI("*CLI...etc

%JL%In both lines change the three 20s (which is the ASCII value of %H2%<>T%H2%) 
%JR%to the ASCII value of the key you want.  %H2%<>A%H2% to %H2%<>Z%H2% being 1 to 26 and 
%JL%%H2%A%H2% to %H2%Z%H2% being 65 to 90.  If another key, at the BASIC prompt type the 
following -
%H2%10 X=INKEY(1000):IF X=0 X=INKEY(0):PRINT X%H2%
- press ENTER type RUN and press ENTER.

%JR%Then press the required key.  The ASCII value of the required key 
%JL%will be printed. If you get the result %H2%-1%H2% try again as the INKEY 
timed out. 

%JR%%H2%EIGHT%H2% - The %H2%.KYS%H2% can be edited in PipeDream if you wish.  Each key 
%JL%has a two line entry, the first line is the function key description 
%JR%the second the command. Therefore, to edit %H2%<>C%H2% for example the ASCII 
%JL%code of 3 should be doubled to find the function key description line 
%JR%number in the text file. eg line 6 line 7 being the associated 
%JL%command. The last 16 lines contain the menu title and the 18 
%JR%associated keys in ASCII codes. Simple isn't it?  Anyway, be sure 
that -

1. always load and save .KYS files as plain text.
2. do not add or delete any lines.
3. start and end file markers in lines 1 and 496 must not be changed.
4. set the cell width and margin to 255 with %H2%<>W%H2% and %H2%<>H%H2%
5. do not use %H2%<>R%H2% reformat paragraphs


%H2%FUTURE RELEASES

%JL%There are still a couple of things I want to improve and, given time, 
%JR%will try to do.  One is to speed up the Restore and Save processes by 
%JL%using machine code (any help with this would be much appreciated) 
%JR%and, second, allow the user an option to speed up execution of *CLIs 
%JL%by switching off all the screen swapping. One thing is certain any 
%JR%%H2%.KYS%H2% files created with this release will be compatible with future 
releases of Z88FKEYS.BAS.

Any ideas or help needed please write to me,

George R. Ogden  -  (telephone 024-029-354 evenings & weekends)
Rose Cottage, Bottom Road, Buckland Common, Near Tring, Herts. HP23