A-Shell supports the same function key programming (aka translation) methods most popular under AMOS. For those unfamiliar with function key translations, here is a brief overview, followed by specific instructions on how to do it yourself. If applicable, see the following topic Standard IFX Translations.
Nearly all terminal keyboards, whether PC-based or not, include a number of special keys which send more than just a simple ASCII byte. When a key sends more than one byte (i.e. a "multibyte sequence"), it usually starts with one of a small group of bytes recognized as "lead-in" characters (ASCII 27 or Escape, and ASCII 1 or Ctrl+A, being the most common). Typical keys that send such multi-byte sequences are those across the top marked F1 thru F12 (or higher), plus a collection of keys over to the right with names like Page-Up, Page-Down, etc. In addition, using the Shift, Control, and/or Alt keys in conjunction with certain other keys may produce a multi-byte sequence, e.g. Shift+Tab.
The terminal driver (a module embedded within A-Shell that understands your terminal hardware) recognizes these multi-byte sequences by a combination of their lead-in characters and by the fact that the remaining bytes arrive too fast to have been manually typed. Since these multi-byte sequences typically vary greatly among hardware terminal types, they are difficult for applications to use directly. To overcome this difficulty, the terminal driver condenses the sequence into a single integer value, which then serves as an index into a translation table, which can be easily modified by the user or developer.
Function key translation tables are stored in files, which use one of two naming conventions. The first convention is for the name of the file to match the terminal driver name, with an extension that indicates the context in which the translations should be used. The most common of these is .ifx (for most input contexts) and .vux (for VUE). These are stored in DSK0:[7,0] (aka the LIB: ersatz directory.) For example, under A-Shell/Windows, the most common terminal driver name is PCTDVG, so the corresponding translation files are lib:pctdvg.ifx and lib:pctdvg.vux. Under Unix, the most common terminal drivers are AM62A, AM62C, AM65, AM75, WYSE50, and thus the corresponding translation files are lib:am62a.ifx, etc. These .ifx and .vux files are automatically loaded into memory as needed.
Under A-Shell/Windows, your terminal driver name is determined by the CONSOLE statement in miame.ini. Under A-Shell/Unix, it might be determined by a TRMDEF statement in miame.ini, or simply by setting your terminal emulator to a particular emulation and letting the operating system figure it out. Unix will set the TERM environment variable to indicate the terminal type, and then A-Shell will consult this variable to set the terminal driver. You can examine the TERM environment variable from the Unix shell prompt by typing the command: echo $TERM. You can reset it with the command: TERM=xxxxxx; export TERM (where xxxxx is the desired terminal type). From the A-Shell dot prompt, you can check your terminal driver setting with the command SET TERM. If it shows "GENERC", then your TERM environment variable setting was not recognized, and it is using a generic driver (which will not support function key translation.) Otherwise, it will indicate your terminal driver name, such as AM62A.
The second naming convention is for the filename to be anything you like, with an extension of PFK. For example, a user named Jack may create a set of his own special function key translations called jack.pfk. Or, perhaps a user or developer will set up some special function key translations for a particular application, such as invoicing, and call it invoic.pfk. These PFK translation files must be manually loaded into user memory (using the LOAD command) in order to be recognized, and once loaded, they override the previously mentioned type of translation file.
Under AMOS, these two naming conventions corresponded to different file formats, and required different commands to edit them (FIXTRN for the former and SET PFK for the latter.) Under A-Shell, they are actually the same format (matching the FIXTRN format used under AMOS) and are both maintained by the FIXTRN utility. See "Notes" for other differences between AMOS and A-Shell relating to the function keys.
To create or edit either style of function key translation table, use one of the following command forms:
FIXTRN
FIXTRN <extension>
FIXTRN <name>.PFK
The first form will create or edit lib:xxxxx.ifx (where xxxxx is your current terminal driver name.)
The second form will create or edit lib:xxxxx.<extension> where <extension> would normally be either ifx or vux (but could be something else if your application was going to specifically request usage of another extension.)
The last form will create or edit the specified PFK-style function key translation file, loading it from memory or from the current PPN if it exists.
From that point, the FIXTRN utility works the same way in all cases. It first prompts for a special key to be used as a delimiter, then prompts you to enter a function key, after which it displays the existing translation (if any) and allows you to enter a new one. You can repeat that process for as many special function keys as you like. At the end, it writes out the new translation table and offers to update it in memory as well.
Notes
There is no particular limit to the length of a translation. The output of the translation is buffered and fed into successive input requests until it is all used up, after which the next real input character (or next translation) will be used.
See FIXTRN.LIT and LOAD.LIT for further details.
If your application does not use all of the function keys, and you want to program the unused ones to act as typing shortcuts, the recommended procedure would be to copy the standard IFX file to another name, using a PFK extension (e.g. COPY MYFUNC.PFK=AM62A.IFX). Then use FIXTRN to modify the desired function key translations. Finally, load and lock the PFK module into user memory at the start of your A-Shell session (e.g. LOAD MYFUNC.PFK /LOCK). The alternative would be to simply modify the standard IFX file, but that runs the risk of it being overwritten during a subsequent update.
Unlike the case under AMOS, PFK translations do not deactivate all IFX translations. Instead, the PFK and IFX translation tables are additive, assuming both are loaded into memory. The PFK takes precedence, but if a key is not defined to the PFK, then the IFX translation will still be active. The idea here is to allow you to add your own function key translation customizations or extensions, but still be able to take advantage of any updates to the IFX tables for those keys which you have not customized.
