Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎

KEY

Keyword Abbreviation Token (hex) Version(s) Classification
KEY K{Shift+E} DF 4.7 Command and Statement
PAINT P{Shift+A} DF 3.5, 7.0 Command and Statement
KEY K{Shift+E} F9 3.5, 7.0 Command, Preposition* and Statement
* See GETKEY for use as a preposition.
 
  Syntax   
KEY [ { keyNumber , definition } | ON | OFF ]
 
Parameters Type Legal Value(s) Default Value Note(s)
keyNumber Unsigned Byte 1 ~ 8* * 20 for the CBM-II series
definition String  0 ~ 255* characters   * assuming enough free memory 
 
 
  Purpose  
State management.  List or redefine the string assigned to function key(s).

 
  Remarks  
KEY allows you to change the string generated when a user presses a function key (F-Key), or view (some) of the current F-Key assignments.
 
Without any parameters, KEY will print (most) of the function key definitions to the current output device (usually the text screen).  The number of keys that can be redefined, and the way memory use is calculated varies by machine.  Control codes 13, 27, 34, and 141 will will not printed literally but instead by shown as CHR$(code); these correspond with Return, Escape, Quote ("), and Shift+Return.  Most control codes, however, will display in reverse-font (see the ASCII-X and/or PETSCII tables).
 
On the C128, the HELP and RUN keys are handled by the KERNAL as function keys but BASIC does not list them or allow them to be changed.  However the KERNAL allows them to be changed; they are stored in RAM and their definitions count toward memory use.  On the TED series, the HELP key is just another function key that will be listed and can be changed.  On both the TED and CBM-II series, the RUN key (Shift + STOP) definition is hard-coded in ROM and is neither listed by nor changable with KEY; because it is not in RAM the length of the RUN key's definition is not relevant to memory use.  On the CBM-II series, only the first 10 key definitions will be listed, although KEY allows you to change any keyNumber from 1 to 20 (function keys 11 to 20 are the Shift'ed version of function keys 1 to 10).
 
KEY will change the string generated by a function key when given a keyNumber and definition.  If the definition is omitted, or either parameter is an invalid expression, SYNTAX ERROR occurs.  If keyNumber is not numeric, TYPE MISMATCH ERROR occurs; STR$ may be used to convert a numeric value.  If definition is not a string expression, TYPE MISMATCH ERROR occurs; VAL may be used to convert a string value.  A floating-point keyNumber will be converted with INT.  If the resulting keyNumber is not a valid F-Key number (is not a Legal Value), ILLEGAL QUANTITY ERROR occurs.  If deleting the current (old) definition does not leave enough free memory for the given (new) definition then OUT OF MEMORY ERROR occurs.  If an error occurs, no changes are made to the existing F-Key's string.
 
In version 7.0, using either the ON or OFF preposition will generate UNIMPLEMENTED COMMAND ERROR.  This seems to be from the unreleased Commodore LCD (version 3.6).  Other pre-7.0 versions of BASIC will instead generate SYNTAX ERROR.
 
Unfortunately BASIC provides no way to get the length of any key definition nor tell you the amount of available "function key memory".  So without PEEKing at secret variables, there is no way to know if a KEY command will succeed or fail.  Even if you do PEEK into the system, you have to do some work to calculate the amount of available memory for a new definiton.  You would need to know the total amount of memory available on a particular machine and then subtract the length of all the other (all except the desired keyNumber) string lengths.  Also, there is no way for a program to "see" the current string definitions (without PEEK'ing again)... unless maybe you redirect output to a disk file, use KEY to list the definitions, and then parse the file.  Due to all these issues, KEY is not easy to use in a program unless you make assumptions.
 
Sorry if all that is confusing.  Here is a table that tries to summarize things:
Machine Max keyNumber # Listed Keys Max bytes for
all definitions
HELP redefinable
with KEY?
RUN definition
uses KEY memory?
C128 8 (10 in RAM) 8 246 No Yes
CBM-II Series 20 10 511 (no HELP key)  No
TED Series 8 8 128 Yes No 
 
Examples (Plus/4):
KEY 1, "GRAPHIC" : REM change definiton

READY.
KEY : REM list definitons
KEY 1,"GRAPHIC"
KEY 2,"DLOAD"+CHR$(34)
KEY 3,"DIRECTORY"+CHR$(13)
KEY 4,"SCNCLR"+CHR$(13)
KEY 5,"DSAVE"+CHR$(34)
KEY 6,"RUN"+CHR$(13)
KEY 7,"LIST"+CHR$(13)
KEY 8,"HELP"+CHR$(13)

READY.
Note the definitions ending with +CHR$(13) will execute when the corresponding key is pressed (13 is the code for carriage return). Those with +CHR$(34) will end with a double-qoute (") ready for the user to type a filename.
 
  Compare With  
 
  Contrast With  
  See Also  
CHR$, ON, OFF 

© H2Obsession, 2014
Comments