Black Box 4

home *** CD-ROM | disk | FTP | other *** search

/ Black Box 4 / BlackBox.cdr / editors / hypsh40b.arj / HYPDEVEL.LZH / HSREF.HYP / hsref.HXP

Wrap

Text File | 1991-04-24 | 155KB | 4,539 lines

.INDEX .HEADER ~M ~TwF~TKile ~PMFile~Kf~E ~M ~TwC~TKontents ~PMContents~Kc~E ~M ~TwG~TKoto ~PMGoto~Kg~E ~M ~TwS~TKearch ~PMSearch~Ks~E ~M ~TwO~TKther ~PMOther~Ko~E ~M ~TwH~TKelp ~PMHelp~Kh~E ║~A ~PF-~E║~A ~PB~E║~A ~Pb@B~E║~A ~PF+~E║~A ~PA@C3$$1~E║ ┌──────────────────────────────────────────────────────────────────────────────┐ │~DF $1 - $2 ~h/~C72√ Match~Z~C79 ~DT│ └──────────────────────────────────────────────────────────────────────────────┘~i5 .REMARK Reference hyperfile for HyperShell Copyright (c) 1990,1991 N.G.Taylor Version 4 amendment level 6 . .PRINT MARGIN 5 . .PRINT TITLE HyperShell Reference Guide . .CHECK +fa Check both menu types . .MENU File Type file |T?File name List HSREF |O91;THSREF.HYP;O90 ──── » ────|ZUc Command |D?Command line DOS shell |D ──── « ────|ZUh About a|NHyperShell Quit F10 q|Q . .MENU Search Title search |A@S?Search string Search Text F6|A@X?Search string Pick and search|SPicksrch ─────── » ─────|ZUo Add to search |O*64;MSearch Refine search |O*63;MSearch ─────── « ─────|ZUg Matched flag ± |ZL/ ───────────────| Next matching |F+1 List matching l|A@C1 Unmatched list |A@C2 . .MENU Contents Contents list F2|A@C ─────── » ──────|ZUg From current |A@C3$1 Starting with |A@C0?Starting with ────── « ───────|ZUf List sections |A@C4Section By category |MCategories . .MENU Categories Action codes |A@C4Action Conditions |A@C4Condition Function codes |A@C4Function Modifier codes |A@C4Modifier Reference flags |A@C4Flag Dynamic menus |A@C4Menuspec . .MENU Goto Next frame n|F+ Matching frame m|F+1 Previous frame p|F- Home frame |b1 ─────── » ─────── |ZUs Backtrack one b|B Unwind backtrack F4|b@B Revisit frame |A@b ─────── « ─────── |ZUc Select noted ref F5|A@R . .MENU Other Action F8|A?What action Calculator |SCalculator ───── » ────|ZUh Example |FExample script Print frame |Dhp -p -o hsref $1 ───── « ────|ZUs Set colours |Scolours Last error |Sperror . .MENU Help Selecting |NSelecting Key mappings |NKey mappings Funct. keys |NFkeys Menu bar |NMenu bar ────── » ────|ZUf Information i|NInfo Notation |NNotation Colour key |NKey ────── « ────|ZUo Paged lists |MPaged Help . .MENU Paged Help Control Keys |NPaged control keys Paged lists |NPaged lists Selecting |NSelecting . .CHECK -fax . .MENU Item Action ref |A Menu Choice |C Title |D Frame ref |F Menu heading|H Note heading|J Note text |K Menu ref |M Note ref |N Menu seln |O Pop message |P Invisible |Q Request |R Script ref |S Frame text |T . .MENU Error text 1 - Operation cancelled 2 - No selection from menu 3 - End of file 4 - Cant open file 5 - File not open 6 - File open 7 - File changed 8 - At start of backtrack 9 - Divide by 0 10 - Value not expected 11 - Value expected 12 - Undefined opcode 13 - Unmatched parenthesis 14 - Syntax error 15 - Script not available 16 - Menu not available 17 - Note not available 18 - Frame not available 19 - Key not defined 20 - Invalid key code 21 - Local ref can't be noted 22 - Not at reference 23 - Key not mapped 24 - No action or disabled 25 - Invalid action code 26 - No command 27 - Env var not present 28 - Invalid dynamic menu 29 - Line too wide for screen 30 - String too long 31 - Too many lines in frame 32 - Max script reached 33 - Maximum menu size reached . .NOTE HyperShell -------------- HyperShell Version 4 ------------- Copyright (c) Text Technology 1988,1989,1990,1991 Design, Implementation and Documentation by Nick Taylor . .NOTE Paged lists Type contents of file Search titles or texts Detailed directory list Contents list Backtrack list Noted references list . .NOTE Paged control keys F1 or ? - This help F2 or # - Page number (*T) F3 or PgUp - Previous page F4 or Home - Start of list/file F5 - Find next (*T) F6 or / - Search file (*T) F8 or End - End of file (*T) F9 - Quit (*T Suspend list) F10 - Quit (*T Quit list) Return - Select (*T Suspend) (*T - Type file control keys) . .NOTE Info - $9 - Frame: $1 Title: $2 File : $3 Date : $4 Time : $5 ~ABacktrack ~O2 ~PO2A;NInfo~E with $6 entries ~AAutoref ~O4 ~PO4A;NInfo~E Error status $? ~C32~AClear~PYah;NInfo~E . .NOTE Menu bar The menus on the menu bar can be selected using their initial letters. With a menu on display, the options can be selected with the initial letter of the option. . .NOTE Key mappings The following key mappings are always provided:- q Quit HyperShell n Next frame p Previous frame b Backtrack one step m Next matching frame . .NOTE Key A ~Mmenu~PNKey~E gives a menu. A ~Nnote~PNKey~E displays a note. A ~Freference~PNKey~E allows a new frame to be selected. An ~Aaction~PNKey~E does some other action. An ~Iinput field~PNKey~E permits some value to be entered. . .NOTE Notepad The notepad allows you to store a reference that you may want to use later. The INS key adds the reference pointed at to the notepad, or the current frame if not pointing at any. The DEL key deletes a reference. The NOTEPAD option on the main menu allows you to select from the notepad and delete unwanted references. . .NOTE Selecting Use the cursor keys or the TAB and SHIFT/TAB keys to move to a reference Press RETURN to select the reference. Press ESCAPE for the control menu, or to cancel a menu, note or list. When using a mouse, move mouse to position cursor to select a reference, Press LEFT mouse button to select. Press RIGHT mouse button for the control menu or to cancel a menu, note, or list. See Also:- ~NFunction keys~PNFkeys~E . .NOTE notation {param} indicates an optional parameter {param1|param2} indicates alternative options . .NOTE Colour choice Select $\ground colour ~F~BW~TKBlack~PK~E~BK ~F~TBBlue~PB~E ~F~TGGreen~PG~E ~F~TCCyan~PC~E ~F~TRRed~PR~E ~F~TMMagenta~PM~E ~F~TYBrown~PY~E ~F~TWWhite~PW~E ~F~BW~TkGrey~Pk~E~BK ~F~TbBlue~Pb~E ~F~TgGreen~Pg~E ~F~TcCyan~Pc~E ~F~TrRed~Pr~E ~F~TmMagenta~Pm~E ~F~TyYellow~Py~E ~F~TwWhite~Pw~E Choose bright for blink on backgrounds . .NOTE Fkeys F1 Help F2 Full Contents F3 Backtrack F4 Select back F5 Notepad F6 Search text F7 Type file F8 Do action F9 DOS Shell F10 Quit Program See also: ~NKey mappings~E . .CHECK +fa . .SCRIPT Colours Y?Press escape to abort at any time. (Return to continue) pChoose Item to change colour of V[@MItem V{@NColour choice(Fore) V]@NColour choice(Back) O$[${$] y . .SCRIPT Calculator Ve?Enter expression (x = last result $x) Vx=$e pExpr $e = $x . .CHECK +fax . .SCRIPT perror p@MError text($?)|Error %s . .SCRIPT Picksrch pPick a word with the mouse P;Ve&P;abq A@X$e . .SCRIPT SETUP O# O16 O*11 -- OUwK -- OVrk -- OTWB KF1MHelp KM1HELP KH4SMENBAR KH3Paged Help K#nF+ K#pF- K#bB K#mF+1 K#qQ K#iNinfo K#aNHyperShell K#lA@C1 Vsfirst VZ$d? VrY?Press escape to abort at any time. (Return to continue) . .SCRIPT MENBAR ZX1;ZY1 . .PRINT Section 1. . .PRINT THIS ~F------------ HyperShell Version 4 ------------~E ~DDReference guide~DT ~FCopyright (c) Text Technology 1988,1989,1990,1991~E ~NDesign, Implementation and Documentation by Nick Taylor~E ~FAll rights reserved~E Text Technology 66 Kennedy Avenue Macclesfield Cheshire ENGLAND SK10 3DE . .PRINT PAGE . .FRAME HyperShell Reference .TITLE Section - Introduction This hyperfile is a reference guide for use by HyperShell authors. It describes the format of the HyperShell hyperfiles and describes the specification of references, actions, functions etc. within them ~i0 [1] ~FFile Contents~K1~E The structure of the file [2] ~FReferences~K2~E Reference and formatting flags [3] ~FActions~K3~E Command strings [4] ~FAction modifiers~PFAction modifier functions~K4~E Functions returning parameters [5] ~FVariables~K5~E Information storage [6] ~FConditions~K6~E Condition codes [7] ~FRestrictions~K7~E Limits and reserved characters [8] ~FCodes~K8~E Codes and settings [9] ~FGeneral~K9~E Miscellaneous ~i5 . .PRINT SECTION 2. . .PRINT TITLE Reference Guide - Hyperfile structure . .PRINT PAGE . .FRAME File contents .TITLE Section - Hyperfile structure ╔══════════╗ ╔══════════╗ ┌── ╔═════════════════╗ ║ H ║ ║ ~F.INDEX~PFIndex~E ║ ╔══════════╗ │ ║ ~F.REMARK~PFRemarks~E ║ ║ ║ ║══════════║ ║ ~F.HEADER~PFHeader~E ║ │ ║ ~F.SCRIPT SETUP~PFSetup Script~E ║ ║ Y ║ ║ ~FGLOBAL~PFGlobal Items~E ║ ║ ~F.FOOTER~PFFooter~E ║ │ ║ ~F.NOTE name~PFNotes~E ║ ║ ║ ║ ITEMS ║ ╚══════════╝ │ ║ ~F.MENU name~PFMenus~E ║ ║ P ║ ║ - ~DM OR ~DT - ║ ╔══════════╗ ──┘ ║ ~F.SCRIPT name~PFScripts~E ║ ║ ║ ║ ║ ║ OTHER ║ ║ ~F.PRINT command~PFPrint~E ║ ║ E ║ ║ ~F.SHARE~PFShare~E ║ ║ ITEMS ║ ║ ~F.CHECK flags~PFCheck~E ║ ║ ║ ╚══════════╝ ╚══════════╝ ───── ╚═════════════════╝ ║ R ║ ╔══════════╗ ─────── ╔════════╗ ╔═════════════════╗ ║ ║ ║ ║ ─────┐ ║ FRAME ║ ║ ~F.FRAME~PFFrames~E ~Fname~PFFrame Name~E ║ ║ F ║ ║ FRAME ║ │ ║ SPEC. ║ ║ ~F.TITLE text~PFTitle~E ║ ║ ║ ║ ║ │ ║ ║ ╠═════════════════╣ ║ I ║ ║ ~FSPECS~PFFrames~E ║ │ ║ ║ ║ ~F.REMARK~PFRemarks~E ║ ║ ║ ║ ║ │ ║ ~FLOCAL~PFLocal Items~E ║ ║ ~F.NOTE name~PFNotes~E ║ ║ L ║ ║ ║ │ ║ ║ ║ ~F.MENU name~PFMenus~E ║ ║ ║ ║ ║ │ ║ ITEMS ║ ║ ~F.SCRIPT name~PFScripts~E ║ ║ E ║ ║ ║ │ ║ ║ ║ ~F.PRINT command~PFPrint~E ║ ╚══════════╝ ╚══════════╝ └─ ╚════════╝ ╚═════════════════╝ . .FRAME Remarks .TITLE So you know why you did it .REMARK text lines A remark section can appear anywhere in the hyperfile, between other sections. It is followed by lines of text containing information for the hyperfile author only, and will not be displayed during a HyperShell session. Remark sections can be placed before other sections to describe the function of those sections. The section, like all sections, is terminated by the next section identifier (any line starting with '.'). . .FRAME Check .TITLE To control the checker component .CHECK {-options}{+options} The Check specification is a single line 'section' signalling the settings of flags for use by the HyperShell Checker utility (HC). For details of the parameters, see the chapter on the HyperShell Checker in the operation guide. This section is ignored by HyperShell, although it does signify a new section, and therefore terminates a previous section. . .FRAME Print .TITLE To control the HP printout .PRINT command The Print section is used to control the HyperShell Printer utility (HP). The following commands are supported by HP. .PRINT TITLE take next line as title string (can be used to change the title throughout the hyperfile .PRINT PAGE force new page .PRINT SECTION prefix define new section prefix and reset frame serial number .PRINT THIS print subsequent lines up to next line starting with '.', recognizing format and highlight flags .PRINT OFF disable printing .PRINT ON enable printing This section is ignored by HyperShell, although it does signify a new section, and therefore terminates a previous section. . .FRAME Share .TITLE sharing globals with another hyperfile .SHARE Indicates that the hyperfile will use the global items from a master hyperfile (the first hyperfile loaded i.e. the one named on the command line). All global notes, menus and scripts (including the SETUP script) are shared, as well as HEADER and FOOTER sections. No global items may be specified within the secondary hyperfile. If an ~FINDEX~E is needed for the hyperfile, this may be specified. Also .REMARK, .PRINT and .CHECK directives may be used. The secondary hyperfile can have local items specified with the frames. This is used for splitting large hyperfiles, where a main entry point can always be used. It is necessary to ensure that any frame references in global items to frames in the secondary hyperfile are fully qualified (i.e. they specify the frame name and hyperfile in the form 'frame^file'). ~G The ~FPreload hyperfile~E action can be used to load the secondary hyperfiles in the SETUP script of the master file. Contents lists will only cover the current hyperfile, but a search action of the form 'A@s' will present a list of all frames in all loaded hyperfiles. . .FRAME Header .TITLE Fixed information at the top of the frame .HEADER (text with ~Freferences~E and ~Fformatting~E) The header section provides the text that will appear at the top of the frame display. By convention it contains the name and title of the frame being displayed, and may also contain date, time, hyperfile name etc. The header section is optional. If omitted, a default title is displayed showing the frame name and title. A 'null' header consisting of a .HEADER line followed by another '.' line may be used if each frame is to have a different form, and does not need the default title. The header display can be suppressed for certain frames by starting the frame ~Ftitle~E with a ')' character. . .FRAME Footer .TITLE Fixed information at the bottom .FOOTER (text with ~Freferences~E and ~Fformatting~E) The footer section is optional, and provides the text that will appear at the bottom of the frame display. It is usual to position it at a fixed line location (Using ~FLine positioning~E) so that it appears in the same place for each frame. The footer usually contains references that are present for all frames in the file, such as a help ~Fnote~PFNotes~E display, a function key map, a backtrack count display etc. Alternative and conditional footer texts can be set up using the conditional hidden line flag (~~hn), and these can be triggered for each frame using the local setting flag (~~Jn) which sets the frame local flags e.g. .FOOTER ~~h8Footer text one ~~h8text one continued~~G ~~h9~~G Default footer text more default footer yet more default footer . The frame text can then code ~~J8 for footer text one, ~~J9 for no footer and default footer text if no ~~J specified. If no default required, then only conditional lines are included. The ~~J8 can be included at the end of the first text line in the frame, or of course can be set up by actions. If a footer is specified in this manner, then the maximum depth MUST be set up in the SETUP script using the ZF action. For the above, this would be ZF3. Also the footer display can be suppressed for a frame by starting the frame ~Ftitle~E with a ')' character. . .FRAME Global Items .TITLE Accessible from all frames Global items are accessible from any frame in the hyperfile. Global items are specified at the start of the hyperfile, before any frame specifications. ~FReferences~E to global items and actions invoking global items generally start with a capital letter, whereas those to ~Flocal items~E start with a lowercase letter. . .FRAME Local Items .TITLE Accessible from one frame only Local items are only accessible from the frame which specifies them. Local Items are specified after a frame for which they are to be local. They may only be accessed when that frame is on display, or when a paged list has been displayed from that frame. ~FReferences~E to local items generally start with a lowercase letter. If the local item specified in a reference or action does not exist, a global item with the same name is used, if it exists. . .FRAME Setup Script .TITLE To configure the hyperfile .SCRIPT SETUP (limited ~Factions~E) The setup ~Fglobal script~PFScripts~E is acted upon when the hyperfile is loaded, and when the hyperfile is re-entered after displaying frames from another hyperfile. It is used to ~Fset key mapping~Es and to set control options. An initial note display or certain other actions may also be performed at this stage, but remember that the script is used on reentry as well as at load time, so may well be executed many times when the user switches between hyperfiles. It is imperative not to do a frame display, or any action which would ultimately cause a frame display. The setup script is optional. . .FRAME Index .TITLE For large hyperfiles .INDEX The .INDEX line may be present anywhere before the first frame specification. It signals that an index file is usually present for the frame. An index file is useful when the hyperfile is above a certain size, as it saves HyperShell from having to read all the way through the hyperfile to build its internal index. Opening and reading the index file has its overheads, however, so its not always helpful to have the index file in use. An index is generally of use when a hyperfile has above 30 frames of reasonable size. The index file is maintained automatically, and is kept in the same directory as the hyperfile. It has the same name as the hyperfile, but with an extension of .HIX. If you modify the hyperfile, HyperShell will detect this and rebuild the index for you. If you delete the index, a new one will also be built. If the .INDEX line is not present, HyperShell does not try to use index files. . .FRAME Frames .TITLE The unit of display for HyperShell Frame specifications are started by a .FRAME keyword. The frame specification will terminate with the next .FRAME keyword or the end of the file. There must be at least one frame specification in a hyperfile. The frame specification includes the frame name and optional title, along with the text which is to be displayed for the frame. ~FLocal items~E may follow the frame text. ┌───────────────────────────────────────────────────────────────┐ │ .FRAME ~Fframe name~E~C70│ │ .TITLE ~Ftitle text~PFtitle~E~C70│ │ (~Fframe text~PFtext~E with ~Freferences~E and ~Fformatting~E)~C70│ │ .MENU ~Fmenu name~PFmenus~E \~C70│ │ (options) \~C70│ │ .NOTE ~Fnote name~PFnotes~E \ Can be a number~C70│ │ (text with references and formatting) / of these~C70│ │ .SCRIPT ~Fscript name~PFscripts~E /~C70│ │ (actions) /~C70│ │ ~F.END~PFend~E~C70│ └───────────────────────────────────────────────────────────────┘ . .FRAME Frame Name .TITLE The key to the frame .FRAME frame name The frame name provides the key to the frame. It is very important to choose the frame name carefully. The frame name will be used to cross reference the frame from text in other frames, and it is most useful if the form of name used in open text is chosen for the frame name. It is not essential to do this, however, as other words or phrases can be cross referenced to the frame using ~Fparameter~PFParameter section~Es in the ~Fframe reference~Es, hidden from display, that refer to the real frame name. In general, duplicate frame names should be avoided, as references cannot then uniquely identify the frame. The first such name is selected normally, although see ~FFrame selection~E for details of how duplicate frames can be selected. Also the frame stepping and backtracking operations can handle duplicate frames. Note that the HyperShell editor and checker do not support duplicate frame names. The frame name is limited to 35 characters. . .FRAME Title .TITLE A description of the frame .TITLE title text This line is optional. However, note that the frame title is normally displayed in the frame display ~Fheader~E. It is also displayed in any ~Fpaged displays~E containing frame lists, and is used by the ~Fsearch selection~E to locate frames about particular topics. It is therefore reasonably important, and well worth providing. The frame title is limited to 40 characters. If the title for a frame starts with a ')' character, the header and footer are not displayed for that frame, and the text can use the bottom line, which is usually kept clear. This may be used for full screen displays such as those captured from other programs and translated through the editor components. . .FRAME Text .TITLE The contents of the frame The frame text comes after the frame name (and title) lines. It contains the text specific to the frame. This will be displayed between the ~Fheader~E and ~Ffooter~E sections. The text may contain embedded ~Freferences~E to other ~Fframes~E, ~Fnotes~E, ~Fmenus~E and other ~Factions~E. Frame references can either be explicitly marked or may be automatically highlighted using the ~Fautoreference~E facility. It is recommended that frame text does not take up more than the number of lines left after the header and footer have been allowed for. If this does occur, a message is displayed indicating that further text may be displayed by pressing the PgDn key. Also it is possible to return to the first screen of a frame by pressing the Home key. A formatting trigger is provided which will force a '~Fscreen break~E' after the line in which it occurred. The frame text is displayed to a width of 80 characters, extra characters being ignored. ~G Graphic and other characters from the 256 character set may be used to draw boxes etc. A double line box may or an area of different colour may also be drawn automatically using the area drawing flags ~~a and ~~b. Automatic indenting of text can be performed by the use of the ~Findent flag~E ~~i. . .FRAME Notes .TITLE Popup windows of text .NOTE note name (text with ~Freferences~E and ~Fformatting~E) . Notes are small popup windows of text which supply general information or information additional to the ~Fframe text~PFText~E. They may contain ~Fformatting~E and ~Freference triggers~PFReferences~E. The note name can be up to 35 characters. Notes have a size limit of 22 lines of 76 characters. ~FGlobal~PFGlobal Items~E notes are used for general information in support of the main material and for help displays. ~FLocal~PFLocal Items~E notes are used for information in support of the frame to which it is local. Selections from a note cause the note to be cleared before continuing. . .FRAME Menus .TITLE Popup selections .MENU menu name (options) . Menus are popup items which show a list of options for selection. Each option is supplied on a separate line, and consists of the choice text, and optionally the associated action for the choice. For a menu invoked using the ~FM action~PFPopup menu display~E the options are treated as frame names, if the action string is not supplied. An action string is separated from the choice text by the '|' character. If action type indicator symbols (see ~FOptions~E) are to be used, it is good practice to line up the action separator, so that the symbols line up on the right of the menu display. The menu name should not exceed 20 characters. There is no limit to how many items can appear in a menu, but only 20 options are displayed at a time, scrolling being performed by the selection of the scrolling option on the top and/or bottom. ~G ~X1Example: The following menu has the actions described afterwards:- .MENU various starting help |Nhelp next frame |F+ exit program|Q . The first option, when selected, displays the frame 'starting' in the current hyperfile. The second option displays a global popup note called 'help'. The third option moves to the next frame. The fourth option quits the HyperShell program. ~G A menu may also be used as a lookup table, and referenced via the lookup modifier (e.g. Mmenuname[key]). In this case it is necessary to place the action separator directly after the option text, and to always supply the action string. If a menu is to be used with a direct index specifier (e.g. Mmenuname(3)), the action string is not normally required. Menus can have options which are conditional. These are indicated by lines starting with a '?' or a '\' character, followed by a single character ~Fcondition code~PFconditions~E. For the '?' variant, the menu option is included in the menu if the condition is TRUE, otherwise it is excluded. For the '\' variant, the line is only included if the condition is FALSE. Thus the following menu displays different options depending on the setting of the error status. .MENU errors ?sClear error status |Y ?sShow error status |P$? \sRun program |D123 . . .FRAME Scripts .TITLE Sequences of actions .SCRIPT script name (limited ~Factions~E) . Scripts are sequences of actions, used where a simple action string or a multiple action string are not sufficient. A script can be used to display a sequence of notes, to input a number of variables to construct a command line, or for many other more complex purposes. Scripts are limited to 200 lines, and each line may contain a number of actions up to a maximum length of 128 characters. A script is terminated when:- 1. It reaches the end, or a 'q' action 2. A further script is called 3. ESC is pressed to cancel a menu or other display 4. A new frame is displayed (unless using 'f' action) ~G A number of control actions exist to allow looping and conditional branching, and ~Fexpression evaluation~E permits simple integer arithmetic to be performed on ~Fvariables~E. The ~FJump within script~E and ~FLabel in script~E actions may be used to perform control flow. ~FSubroutines~PFCall subroutine~E can exist within scripts to perform common sequences of actions. Lines starting with a '-' sign are treated as comment lines, and are not loaded with the script. Also completely blank lines are ignored. It is helpful to have comments to explain how the script works, for when you need to change the script. Lines in the script can be indented with spaces or tabs, and these are ignored when the script is loaded. Indentation can show the structure of a script. A script can contain a line of the form +scriptname in which case script 'scriptname' is appended to the script. Only one script can be appended, although that can itself append another script. The total number of lines is limited to 200. Subroutines can then exist in a separate script which can be appended to script wishing to use them. If this is done, the first line of the script can be a 'q' action, in case the first script runs off the end by accident. A local script of the given name is firstly looked for, and then a global script, if a local script is not found. Scripts cannot be 'nested'. When a script calls another script the original script is cleared first, effectively 'chaining' from one to another. An ~Fexample script~E is provided to show how the control flow actions can be used. Also see ~FLabel in script~E for details of how problems with scripts can be dealt with. . .FRAME End .TITLE The end of the frame specification The .END keyword indicates the end of the frame specification. It is present for historical reasons, and serves no purpose other than to indicate to the author where a frame finishes. This may therefore be omitted, as the next frame specification serves the same purpose. . .PRINT SECTION 3. . .PRINT TITLE Reference Guide - References . .PRINT PAGE . .FRAME References .TITLE Section - link references and control flags In the frame text, in the text of a popup note and in the text of a file displayed using the 'Type file' action, control sequences can exist to indicate references to other items, which are highlighted in the text, and to perform text formatting actions. Reference control sequences have the general form:- ~~?text string~~E OR ~~?text string~~Paction string~~E Where ? is the reference type identifier, and text string is the text to be displayed, highlighted in a manner applicable to its type, in the frame text display. action string is an optional action string which will be performed instead of the implicit action for the reference if the reference is selected. The text string and action string elements are limited to 39 characters (although a longer text string may be used where an action string is supplied). . .FRAME Frame reference .TITLE Flags ~~F and ~~f ~~Fframe name~~E ~~Freference~~PFframe name~~E The frame reference is introduced by the ~~F or ~~f sequence. The ~~F reference adds the reference to the backtrack list, when selected. The ~~f reference replaces the top entry on the backtrack list. Thus ~~F is used for browsing or cross references, and ~~f is used for deliberate frame sequencing or hierarchical references. The ~~f type of reference is highlighted in a different manner to tell the user that selection of the reference will not allow backtracking. A ~Fparameter section~E (~~P) may be added to supply an explicit action string to be performed on selection. ~~Fdeleting~~PFDelete~~E - reference to frame 'Delete' . .FRAME Note reference .TITLE Flags ~~N and ~~n ~~Nnote name~~E ~~Nreference~~PNnote name~~E The note reference is introduced by the ~~N or ~~n sequence. The ~~N reference is a global note, whose specification occurs at the start of the hyperfile, before the first frame specification. The ~~n reference is a local note, whose specification lies within the current frame specification, after the frame text and before the next frame. A parameter section (~~P) may be added to supply an explicit action string to be performed on selection. ~~NHelp~~E - reference to global note 'Help' . .FRAME File note reference .TITLE Flag ~~t ~~tfile name~~E ~~treference~~Ptfile name~~E The file note reference is introduced by the ~~t sequence. This causes a file with a name equal to the reference (and with default extension '.NTE') to be displayed as a popup note. See the 't' action for further details. A parameter section (~~P) may be added to supply an explicit action string to be performed on selection. ~~tmemo~~E - reference to file MEMO.NTE . .FRAME Menu reference .TITLE Flags ~~M and ~~m ~~Mmenu name~~E ~~Mreference~~PMmenu name~~E The menu reference is introduced by the ~~M or ~~m sequence. The ~~M reference is a global menu, whose specification occurs at the start of the hyperfile, before the first frame specification. The ~~m reference is a local menu, whose specification lies within the current frame specification, after the frame text and before the next frame. A parameter section (~~P) may be added to supply an explicit action string to be performed on selection. ~~msizes~~E - reference to local note 'sizes' . .FRAME Script reference .TITLE Flags ~~S and ~~s ~~Sscript name~~E ~~Sreference~~PSscript name~~E The script reference is introduced by the ~~S or ~~s sequence. The ~~S reference is a global script, whose specification occurs at the start of the hyperfile, before the first frame specification. The ~~s reference is a local script, whose specification lies within the current frame specification, after the frame text and before the next frame. A parameter section (~~P) may be added to supply an explicit action string to be performed on selection. ~~Scalculate~~E - reference to global script 'calculate' . .FRAME Action reference .TITLE Flag ~~A ~~Areference~~Paction string~~E The action reference is introduced by the ~~A sequence. This form of reference contains an action which is not a frame, note, menu or script reference. It covers the miscellaneous actions whose multiplicity precludes the use of specific highlighting schemes. The action reference usually contains the parameter section (~~P sequence), as it has no implicit action. If the reference text can be used as an action, then the parameter may be omitted. ~~Agreen~~PPindicates safety~~E - reference to popup message . .FRAME Input field .TITLE Flag ~~I ~~Iinput area~~Paction pattern~~E The input field is not exactly a reference, but is used to input data to be used by the application. Its most general use is to input variable values. The input field always has reference text and a parameter section, which specifies a pattern within which the input value is substituted prior to execution. The reference text part of the input field delimits the field, and provides the text which is to be edited to form the input to the field. If the input field is being used to set a variable, the reference text usually contains an expansion token for the variable, so that when the frame is displayed, the current value is displayed in the field and can be edited. The field should contain a width specification after any reference text, which will determine the width of the input field. If new input is always required, the field should be blank, just a width being supplied in the reference text. ~G The parameter section usually consists of a variable assignment and sometimes some other action. The parameter string provides a pattern, within which the input value is substituted. The string can contain up to three occurences of the string '%s', each of which will be replaced by the value when it is input. An example of a line containing an input field is as follows:- Name : ~~I$$n~~W15~~PVn%s;scheckname~~E This, when selected, allows the current value of variable 'n' to be edited (up to 15 characters in length), which is the assigned back to variable 'n' and checked using local script 'checkname'. When displayed, this will look like (assuming variable n contains 'Fred Jones'):- Name : ~DIFred Jones ~DT The input field may also be specified in a note, although the note display will terminate after entry of the input field. . .FRAME Parameter section .TITLE Flag ~~P The parameter section, introduced by the ~~P sequence, permits any action to be associated with a reference. It is usual, and helpful, to use the same type of action as that suggested by the initial introductory sequence, as it is that which has already determined the highlighting scheme for the reference. If a miscellaneous action for which there is no set colour scheme is to be performed, the ~Faction reference~E should be used. . .FRAME Key mapping .TITLE Flag ~~K The key mapping sequence, introduced by ~~K, permits a key on the keyboard to be mapped to the reference, such that when it is pressed, the reference is selected. This is useful for 'menu' frames. A key mapped using the 'K' action takes precedence over this form of key mapping. The reference:- ~~FNext frame~~Pf+~~K ~~E will have 'Next frame' highlighted as a frame reference, and will move to the next frame when selected directly or when the space bar is depressed. . .FRAME Immediate reference .TITLE Flag ~~Q One reference on a frame or note display may be flagged as an 'immediate' reference, which will be selected automatically after the frame or note text has been displayed. This is done by including the sequence ~~Q after the complete reference sequence for the reference to be selected. This may be used for many purposes, but the most common would be to select the first input field on a form frame, and therefore put the frame into a data input mode automatically on entry. The immediate reference flag may also be used with an 'invisible' reference. This has a zero length reference string and does not therefore permit manual selection. This could be placed in the header or footer to, for instance, write a log file of frames visited. It can also be used to pop up a note or a menu on moving to a frame. It may even invoke a script which could perform a long sequence of actions. ~~A~~PNhello~~E~~Q . .FRAME Formatting .TITLE Format control flags The formatting sequences permit the frame, and note, displays to be controlled in a number of ways. Absolute cursor positioning and colour control are the main uses for this feature. Formatting sequences can be placed within the reference text, provided that a parameter section is provided for that reference. This facility can be used to highlight a letter in the reference, if that letter key is mapped to the reference. . .FRAME Option display .TITLE Flag ~~O The option display is an extended form of variable display. It allows the state of various runtime options to be displayed as either 'ON' or 'OFF'. The runtime options are as follows, showing the option code, the command line flag and the option description with the default state which is toggled by the flag. ~~O2 displays ON or OFF depending on backtrack status It is possible to access options in the extended option set using the following characters:- O*0':' O*1';' O*2'<' O*3'=' O*4'>' O*5'?' O*6'@' O*7'A' O*8'B' O*9'C' The special form ~~O# displays a three character field containing current page number of a multi screen frame. This can be used with ~Flocal flag~PFlocal flags~E '<' to show a conditional footer with the page number. . .FRAME Line positioning .TITLE Flag ~~L ~~Lnn The line positioning command, introduced by the ~~L sequence, positions the text writing cursor at the default indent of the specified line, unless that line is before or at the current line, or beyond the bottom of the display or footer margin. The full form of the sequence is either ~~Ln or ~~Lnn, where n/nn is the line number, starting from 1. Thus:- ~~L3 positions at line 3, column 1 ~~L20 positions at line 20, column 1 . .FRAME Column positioning .TITLE Flag ~~C ~~Cnn The column positioning command, introduced by the ~~C sequence, positions the text writing cursor at the specified column, by outputting spaces, unless that column is before or at the current position, or beyond the edge of the display. The full form of the sequence is either ~~Cn or ~~Cnn, where n/nn is the column number, starting from 1. Thus:- ~~C9 positions at column 9 ~~C74 positions at column 74 . .FRAME Width positioning .TITLE Flag ~~W ~~Wnn The ~~W sequence, of the form ~~Wn or ~~Wnn, outputs spaces to the display upto the specified number of column positions from the start of the last reference, or the start of the line if no references yet displayed. This is normally used to specify the width of an ~Finput field~E. It may, however, be used for other purposes. ~~W12 positions 12 columns from start of reference . .FRAME Force column position .TITLE Flag ~~X ~~Xnn The force column position flag, introduced by the ~~X sequence, positions the text writing cursor at the specified column of the current line, regardless of the current position. The full form of the sequence is either ~~Xn or ~~Xnn, where n/nn is the column number, starting from 1. Thus ~~X34 positions at column 34. This flag is usually used in the ~FInsert text~E action. The position set by the ~~X flag can be used to start a width range, so that the ~~W flag may be used to clear part of a line. CAUTION: this flag should be used with care . .FRAME Force line position .TITLE Flag ~~Y ~~Ynn The force line position flag, introduced by the ~~Y sequence, positions the text writing cursor at the current column of the specified line, regardless of the current line position. The full form of the sequence is either ~~Yn or ~~Ynn, where n/nn is the line number, starting from 1. Thus ~~Y10 positions at line 10. This flag is usually used in the ~FInsert text~E action. CAUTION: this flag should be used with care . .FRAME Screen break .TITLE Flag ~~G In the frame text, a 'new page' (or second screen) of text may be forced after the current line by the inclusion of the screen break trigger. The form of this sequence is ~~G, and this may occur at any point in the line, although it is probably easiest to maintain if placed at the end of the line. . . . . line at end of screen 1 ~~G Line at start of screen 2 . . . . . .FRAME Line break .TITLE Flag ~~g In frame or note text, a new line can be started by embedding this flag in the text. This is used where ~Fnamed variables~E hold text to be displayed which occupies more than one line. This line~~gNext line . .FRAME Concatenate text .TITLE Flag ~~c ~~c The ~~c flag may be placed at the end of a line, if the next line is to be concatenated. This flag has special applications and should not be used in open frame or note text. It is usually used with the 'i' action to retain the text position after writing to the screen. CAUTION: This flag should be used with care . .FRAME Hidden lines .TITLE Flag ~~H ~~Hc Lines in the text can be excluded from a frame or other display by putting a ~~H sequence at the start of the line. If the ~~H flag appears after the first column, it marks the start of a hidden area which finishes at the end of the line or at a ~~Z flag. The ~~H flag can be used for embedding maintenance comments in frame text, which will not be displayed. ~X1See also: ~FConditional hidden lines~E . .FRAME Conditional hidden lines .TITLE Flags ~~h and ~~j ~~hc - display text if condition c is TRUE ~~jc - display text if condition c is FALSE These sequences provide a conditional hidden text capability. The 'c' character is one of the general HyperShell ~Fconditions~E. When the condition is FALSE, the ~~hc sequence acts as ~~H to hide a complete line or part of a line terminated by ~~Z. When the condition is TRUE, the sequence has no effect, permitting the text to be displayed. The ~~jc sequence has the opposite effect, whereby if the condition is TRUE the text is hidden, else it is displayed. The conditional hidden text flags are generally used for information which is ~Fexpanded 'in line'~PFlocal flag toggle~E with the main text. The frame ~Flocal flags~E 0 to 9 are usually used for this purpose. ~X1See also: ~FHidden lines~E . .FRAME Print suppress lines .TITLE Flag ~~p ~~p Lines in the text which are only required for online display can be excluded from printout when using the HP program by putting a ~~p sequence at the start of the line. If the ~~p flag appears after the first column, the rest of the line is not printed. . .FRAME Flag setting .TITLE Flag ~~J ~~Jn The local flags 0 to 9 can be set using the ~~J flag. The sequence sets the local flag 'n' IMMEDIATELY it is encountered. This is used for setting the local flags to influence the frame display or operation in some way, mainly for conditional text in the footer section of the display, where the conditional hidden line flag is used. ~~J3 - sets frame local flag 3 ~X1See Also: ~FHidden lines~E . .FRAME End of hidden range .TITLE Flag ~~Z The ~~Z flag is used to terminate the range of a hidden or conditionally hidden piece of text in a frame or note. start of line ~~h2Hidden text~~Z ~X1See Also: ~FHidden lines~E . .FRAME Text/Background colours .TITLE Flags ~~T and ~~B ~~Tc ~~Bc These sequences set the text colour or background colour to the colour with code 'c'. The text can have one of 16 different 'colours' and the background can have one of 8. It is helpful to choose these so that they have a good contrast. And yes, if you make them both the same, the text is invisible. ~~Tr - set text bright red ~~BM - set background magenta ~X1See also: ~FColour codes~E . .FRAME Display colour schemes .TITLE Flag ~~D ~~Ds The ~~D sequence selects colour highlighting scheme 's'. There are 26 colour schemes, mapped to the letters A to Z. The scheme letter is specified directly after the ~~D. The colour scheme sequence works slightly differently to the text/background settings in that it is held over a reference display. The schemes are configurable using the option setting action 'O'. ~~DM - use menu reference colour scheme ~X1See also: ~FColour schemes~E . .FRAME Indent flag .TITLE Flag ~~i ~~in The indent flag can be used to cause an indent to be added automatically to the text in a frame display. The parameter 'n' is a digit from 0 to 9 indicating the indent to be applied. A value of 0 causes no indent. ~~i5 - indent the text by 5 places The flag is usually placed at the end of the header to cause the frame body text to be indented, and possibly at the start of the footer to reset the indent before the footer. Indivual lines can be reset to column 1 by prefixing them with the sequence '~~X1'. Ranges of lines can have the indent changed before the start and after the end. . .FRAME Box start .TITLE Flag ~~a ~~a This flag indicates the TOP LEFT position of a graphic box. ~X1See also: ~FBox draw~E . .FRAME Box draw .TITLE Flag ~~b ~~bt This flag indicates the BOTTOM RIGHT of a box area, and causes the area to be drawn from the top left position indicated by a ~FBox start~E flag. The 't' parameter indicates the type of area, as follows:- ~~b0 -- just return to position of ~~a flag ~~b1 -- draw a double edged box ~~b2 -- define a window and clear it ~~b3 -- draw a box, then define a window within it ~~b4 -- define window as full screen (used by itself) ~~b6 -- clear the area without defining a window ~~b7 -- draw box and clear inside without defining window Most of these specify window areas and are for use with the 'i' action. Only the ~~b1 version should be used in frame displays generally. CAUTION: This flag should be used with care ~G Example boxes ~~a ~a This is in a box -- This is in a box ~~b1 ~b1 ~~a ~a ~~DJ~~b3 ~DJ~b3 ~a Text in a box window~b4 ~Y18 ~DTThis feature can also be used for 'subwindows' or panelled windows, along with the ~FTake copy of screen~E and ~FShow saved screen~E actions. ~X1See also: ~FBox start~E . .FRAME Wait in display .TITLE Flag ~~w ~~ws The ~~w flag causes a delay of 's' seconds before proceeding with the display. This is used for effect. 1~w12~w13 ~X1See also: ~FTeletype mode~E . .FRAME Teletype mode .TITLE Flag ~~d ~~d The ~~d flag causes text to be slowly displayed as though by an old fashioned teletype. The flag acts as a toggle, and is valid for the current line only. It is used for special effects, and is useful to focus attention on the text. Type this ~dslowly at first~d and then fast ~X1See also: ~FWait in display~E . .FRAME Flag character display .TITLE To actually display a ~~ The ~~ character can be displayed in a frame, note or paged list by coding it as two ~~ signs:- ~~~~ . .PRINT SECTION 4. . .PRINT TITLE Reference Guide - Actions . .PRINT PAGE . .FRAME Actions .TITLE Section - HyperShell control commands Actions are the commands which control HyperShell. Action specifications, including ~Fmultiple actions~E can be supplied at a number of different places:- 1. The reference action in the text. 2. A menu action. 3. A script action. Not all forms of action specification are relevant in all places. It is normally obvious where a particular type of action modifier string is not applicable, or where a particular action is not sensible. In particular, control flow actions are only relevant in scripts (although a popup note or menu may cause a branch within a currently executing script). . .FRAME Multiple actions .TITLE A string of actions Multiple action strings can exist in any action specification. The actions are separated by ';' characters. Multiple actions are permitted wherever an action specification is expected. ZX40;ZY12 - Positions the cursor in the middle of the screen. The following rules apply to multiple action strings:- 1. The condition of a ~Fconditional action~E affects remaining actions. 2. A conditional ~Fjump within script~E does not clear remaining actions. 3. The remaining actions are cleared if an error occurs in an action, or an input is cancelled. 4. If a further multiple action is encountered, for instance as the result of an action modifier or menu selection, the remaining actions are cleared in the original. . .FRAME Action codes .TITLE Command letters Action specifications start with a single letter action code, or a double letter ~Fextended action code~PFExtended action codes~E (starting with Z). An action may also have parameters supplied directly after the code. The parameters may be supplied directly as literal strings or indirectly via one of a number of ~Faction modifiers~PFAction Modifier functions~E. . .FRAME Perform action .TITLE Action 'A' ~X1Format: Aactionspec The 'A' action is provided to enable action modifiers returning full action specifications to be serviced. For example the extended directory listing modifier 'l' and the notepad listing modifier 'R' both return action strings, and would be handled as follows:- A@l*.* A@R Also the form 'A?Enter action' can be used to permit the user to enter an action specification for execution. . .FRAME Conditional action .TITLE Action 'a' ~X1Format: acxxxxxxx{;actionstring}{;actionstring}... The 'a' action is used to execute an action or set of actions conditionally on the setting of the condition 'c' specified. This action provides a means of specifying conditional actions without having to use scripts. The condition letters are described in the ~Fconditions~E section. adpvariable not defined - displays message if variable not set ~X1See also: ~FUnless condition~E . .FRAME Backtrack one step .TITLE Action 'B' ~X1Format: B HyperShell retains a list of frames that the user has displayed. This list acts like a 'stack' which has a frame reference 'pushed' when a new frame is displayed. The 'B' action 'pops' the frame references from this stack one at a time, displaying the frame referenced. ~X1See also: ~FMultiple backtrack~E . .FRAME Multiple backtrack .TITLE Action 'b' ~X1Format: b{depth} The 'b' action permits a number of frames to be discarded from the backtrack list, retaining the depth specified as a numeric parameter, where 0 represent the first frame visited in the file. After this it displays the frame referenced at that point. This action is usually used with the 'B' dynamic menu, to permit the point in the list to be selected. If a frame from the backtrack is to be revisited without winding back, the 'b' dynamic menu should be used with the A action. b@B Select level and unwind b3 Unwind to level of 3 ~X1See also: ~FSelect backtrack~E . .FRAME Change drive / directory .TITLE Action 'C' ~X1Format: C{Wd:}{pathname} The 'C' action allows the working directory to be changed, and optionally allows the working drive to be altered. For example:- CB:\HYPER CSUBDIR C..\HYPER2 The original drive:directory is held in system variable 8, and the current drive:directory is held in system variable 7. Thus the action 'P$$7' would display the current working drive:directory, and the action 'C$$8' changes back to the original directory. . .FRAME Call script file .TITLE Action 'c' ~X1Format: cscriptfile The 'c' action permits a file containing a script to be executed. The 'scriptfile' parameter may have its extension omitted, in which case .HSF is assumed. Script files are treated as normal ~Fscripts~E, and obey the same rules. A file script cannot be appended to a script, but can append normal scripts itself. Script files can be used as small 'programs'. ~FParameters~E can be supplied on a script action. creload - runs the script file RELOAD.HSF ~X1See also ~FExecute script~E . .FRAME DOS command execution .TITLE Action 'D' and 'd' ~X1Format: D{ }{Command line} d{ }{Command line} This action starts the DOS command processor to run a command or to permit command line interaction. If a parameter is supplied, it is issued as a command line to DOS. The command can be a DOS built-in command, a batch file, or an external program. The command can have parameters. If the action is specified without parameters, it runs the command line interpreter to allow the user to interact with DOS. When the user has finished, the EXIT command is used to return to HyperShell. The uppercase form of the action indicates that when the command has finished, a key press is required before redisplaying the current HyperShell frame again. The lowercase form indicates that when the command has finished, HyperShell will immediately redisplay the current frame. The system variable '^' is set to the exit code of the DOS command processor (this is always 0!). If the command line contains a space character as the first character, the screen is not cleared before invocation or refreshed afterwards, allowing 'silent' commands, or commands with redirected output to be executed without disturbing the display. If the command does output to the screen, the display will be disturbed, but can be refreshed using the 'y' action. It is preferable to ensure that the command will never output to the screen. ~FOption~PFOptions~E O6 can be set so that the HyperShell program is saved to disk whilst a command runs (this is only possible with the HS.EXE program). Examples:- D - escape to command line allowing return DDIR/W *.HYP - Do wide directory listing of hyperfiles d DEL DATA.DAT - Silently delete a file ~X1See also: ~FExecute program~E . .FRAME Command chaining .TITLE Action 'E' ~X1Format: ECommand line The 'E' action executes another program, overwriting HyperShell in memory. Only programs (files with .EXE or .COM as an extension) can be executed using this action. If subsequent return to HyperShell is required, either the 'D' action or the 'X' action should be used, although these will mean that the program has less room in which to execute, as HyperShell occupies around 120k of memory. Edbase - chains the dbase program ~X1See also: ~FDOS command execution~E, ~FExecute program~E . .FRAME Expand, or split, variable .TITLE Action 'e' ~X1Format: evsabc... The 'e' action allows a variable to be split into fields, and assigned to a number of other variables. Parameter 'v' is the name of the source variable, 's' is a character used to separate the fields in the source variable, and abc... are the target variables to receive the fields. If the character 's' is ommitted, the fields are assumed to be separated by spaces. There is a list of ~Freserved characters~E which cannot be used as separators. ex:abcd - splits 'x' on ':' into a,b,c and d If 'x' contained 'one:two:three:four' then 'a' would become 'one', 'b' would become 'two' etc. ~G The opposite effect to the expand action is to pack the values of a number of variables in a variable, with a separator between them. This can easily be accomplished by the form:- Vv$$as$$bs$$c Where the values of v,s,a,b,c are as above. This mechanism can be used to pack a set of variables for storage whilst the variable names are used for some other purpose. Of course the variable can be expanded into a set of variables other than the original. . .FRAME Frame selection .TITLE Action 'F' and 'f' ~X1Format: Fframename{^hyperfile} fframename{^hyperfile} The 'F' and 'f' actions select a new frame to display. The parameter specifies the frame name of the frame to be displayed. If just a frame name is supplied, the frame is assumed to be in the local hyperfile. If the hyperfile parameter is used, this indicates that the frame belongs to the specified hyperfile. The home frame of a hyperfile can be selected with the form:- F^hyperfilename The home frame of the current hyperfile is selected with the form F ~G The lowercase form of the action modifies the backtrack processing so that the frame replaces the last frame reference on the backtrack list, rather than being added to the list. This is used to step through related frames when it is clear that the user is reading them through, and where it is not necessary to stack the frames on the backtrack list. Also, whilst the uppercase form causes a currently executing script to be cleared, the lowercase form does not. The example shows an action which will step to the next frame in the hyperfile, without retaining the previous frame reference. f+ The '+' modifier is only applicable to the 'F' or 'f' action. An extended form of the '+' modifier allows selection of the next matching or unmatched frame:- F+1 - next matching frame F+2 - next unmatched frame If you have chosen to have duplicate frame names in your hyperfile, the special form:- F+frame name can be used. This looks for the frame from the current frame onwards. It can therefore be used in the action string of a reference in a frame to look for the next occurrence of the frame name after that frame - for when the hyperfile is split into sections, or can be used to step through all frames of a particular name by using 'Fframe name' for the first and 'F+frame name' for the rest. The '-' modifier is used to step to the previous frame in the hyperfile, and to 'wrap' to the last frame from the first. F- . .FRAME Graphic screen display .TITLE Action 'G' and 'g' ~X1Format: Gfilename g{filename} The 'G' and 'g' actions display a graphic or text screen from a file in BLOAD format. The 'g' variant does not reset the screen mode after display, so that graphic screens can be displayed one after the other with no lack of continuity. The 'g' action with no parameter resets the display mode to the default text mode, which otherwise takes place the next time the frame display is refreshed. The formats of display supported are listed in the component operation guide. BLOAD images, tagged BLOAD images and .PCX images of various forms are supported. ~G The file type is auto-sensed. The correct adaptor type is assumed to exist and is not tested, apart from text mode screens, where the correct screen address is used for the adaptor type. After display the mouse may be used to select a zone on the screen, or a character may be pressed to choose an option if no mouse is available. The character and zone mappings are defined in a special form of MENU, and selected using the ~Fzone selection~E method. . .FRAME Notepad maintenance .TITLE Action 'H' and 'h' ~X1Format: H{string} h{string} The notepad, as well as being maintained by the INS and DEL keys, may also have data added and removed by the 'H' and 'h' actions. The items on the notepad would normally be action specifications, although it is possible to store other data on the list for selection for other purposes. These actions cause the notepad scan pointer (used by !R) to be reset. The 'H' action by default requests a comment string which is associated with the reference when it is listed. This can be suppressed using the ~FO*8 option~PFextended options~E flag. HFframe two - adds frame reference for 'frame two' hNHelp - removes all note references for 'Help' . .FRAME Select next input field .TITLE Action 'I' ~X1Format: I Ix The 'I' action is specific to frames containing input fields. This action is used in an input field action string to select the next input field after input is complete on that input field. If a parameter is supplied as in the second format above, the CURRENT input field is reselected. This is used where an input field is validated in a script, and has to be re-entered if in error. ~X1See also: ~FInput field~E . .FRAME Insert text .TITLE Action 'i' ~X1Format: istring The 'i' action is used to insert text in the current frame display. The string can contain formatting flags, but must not contain any reference flags. It is usual to start with ~~X and ~~Y flags to position the text cursor for writing the string. This action can be used to update information on the screen without redisplaying the whole frame text. Y&H;i~~Y1~~X60$$5~~L25 will update the time displayed at line 1 column 60 and re-park the text cursor. This action should be used with care, as it is easy to corrupt the screen display if used incorrectly. . .FRAME Jump within script .TITLE Action 'J' and 'j' ~X1Format: Jlabel jclabel The uppercase form 'J' is an unconditional branch, and transfers control to the script ~Flabel~PFLabel in script~E denoted by the parameter. Jstart Branches to the line containing 'Lstart' in the script. If the label does not exist in the script, the jump does not take place, and processing continues with the next line in the script. The lowercase form 'j' is a conditional jump, and is followed by a letter denoting the condition upon which a jump will occur, followed by the label to which a branch will be made if the condition is set. See ~Fconditions~E. . .FRAME Set key mapping .TITLE Action 'K' ~X1Format: Kksactionstring The 'K' action maps a keyboard key to an action string. This action is then available from a frame display (not from paged displays). When the key is pressed, the action is performed. Function keys and printable ascii characters may be mapped (subject to them not conflicting with HyperShell metacharacters). The key to be mapped is specified by the following notations:- K#xstring Character x KFnstring Function key n KSnstring Shift/function key n KCnstring Ctrl/function key n KAnstring Alt/function key n Function key 10 is indicated by n = 0. ~G ~X1Example: K#hNHelp - map 'h' key to global note 'Help' KF1F^HOME - Map F1 key to move to HOME hyperfile Unshifted function keys equate to the main control menu actions, and mapping them changes the actions for the main menu. This can be used to disable certain control menu options. The option text for the main menu can be set using the special form:- KMnstring - set menu option text n to string ~G The K action is also used for mapping strings and actions to certain ~Fheadings and control keys~PFControl key mapping~E, using the form KHnmapping or KGnmapping ~X1Example: KH4Q - map ESCape to action 'Q' to quit HyperShell The complete set of key and heading mappings can be reset at any time by the special option action O# This is useful for inclusion at the start of the SETUP script in a hyperfile, to avoid confusing key mappings being inherited when a hyperfile is referenced from another. ~X1See also: ~FDo mapped key~E . .FRAME Do mapped key .TITLE Action 'k' ~X1Format: kks The 'k' action takes a key specification as for action K and performs the action mapped to the key specified. This action is used where an action is both mapped to a key and tied to a reference or a menu selection. kF1 - do action mapped to Function key 1 k#h - do action mapped to 'h' key ~X1See also: ~FSet key mapping~E . .FRAME Label in script .TITLE Action 'L' ~X1Format: Llabelname The 'L' action does not do any processing, but indicates a line in a script to which jump actions can branch. The 'labelname' is the name used as the target of a ~Fjump statement~PFjump within script~E. Lrepeat - label 'repeat' One of the traditional problems with programming is the endless loop. To help diagnose this sort of problem, a trace can be performed by setting ~Foption flag 7~PFoptions~E. If this is set, the script stops at each label it executes, showing the label name. O71 If tracing is not enabled, pressing the ESCape key will stop and display the label. Any key will resume the script, or pressing ESCape again will stop the script. . .FRAME Load named variable .TITLE Action 'l' ~X1Format: lvnamed The 'l' action is used to load a named variable with a string value. ~FNamed variables~E can be used instead of the single letter variables to hold information for expansion in text or in an action. Parameter v is a single letter variable and 'named' is the name of the named variable. The contents of the variable v are loaded into the variable 'named'. Note that the name can be supplied by an action modifier or by the expansion of a variable token, including that of the same or another named variable. ltTime of day - loads variable 't' to variable 'Time of day' ~X1See also: ~FNamed variables~E, ~FSet variable~E, ~FSet Named Variable~E . .FRAME Popup menu display .TITLE Action 'M' and 'm' ~X1Format: Mmenuname mmenuname This action performs the action resulting from selection by the user from the named menu. The uppercase form is used for global menus and the lowercase form for local menus, where a local menu is firstly looked for, with a global menu being looked for if a local menu is not found. A menu action, and a menu action modifier, may have special parameters added to select from the menu by means other than interaction. mtype ~X1See also: ~FMenu parameters~E . .FRAME Popup note display .TITLE Action 'N' and 'n' ~X1Format: Nnotename{params} nnotename{params} The action 'N' pops up the named note, and waits for a key/button press before clearing the note. The uppercase form applies to global notes and the lowercase form applies to local notes, where a note local to the frame is firstly looked for and a global note accessed if the local note cannot be found. Notes can contain ~Freferences~E just as frames do, and these will be actioned if selected. Nexample note ~FParameters~E can be supplied on a note action. . .FRAME Option setting .TITLE Action 'O' ~X1Format: O{*}os The action 'O' is used to set HyperShell control options and colour schemes. The variants are as follows:- Ons - Set option 'n' to 's' O*ns - Set extended option 'n' to 's' OXfb - Set colour scheme 'X' to foreground 'f' on background 'b' O*Xx - Set application option 'X' to 'x' ~FOptions~E and ~Fextended options~E control the operation of HyperShell. Parameter n is the option number and s is the setting. Some options can have a value of 0 (for OFF) or 1 (for ON). Such an option can be 'toggled', that is set off if on and on if off, by specifying an alphabetic value. E.g. to toggle warnings:- O8T ~G ~FColour schemes~E are the highlighting schemes used for various purposes in HyperShell. They are set to a two character colour setting consisting of the foreground and background ~Fcolours~PFcolour codes~E. Note that the brighter 8 colours are used for the background scheme if blinking is required. ONyG - set note references to bright yellow on dark green ~FApplication options~E are character settings used to control a HyperShell application, and can act as ~Fcondition codes~PFconditions~E These are set using the form O*Xx Where X is the application option name of 'A' thru 'Z', and 'x' is the character value assigned to that option. The option is reset using the form 'O*X'. . .FRAME Printer output .TITLE Action 'o' ~X1Format: ostring The 'o' action prints the supplied 'string' to a route specified by the printer option. The valid values, along with their routes, are as follows:- 0 - Display on bottom line 1 - Print to printer 2 - Send to standard output 3 - Send to standard 'AUX' (e.g. RS232) 4 - Send to 'output file' (that opened by action 'w') If an invalid route is specified, output goes to the bottom line. The printer is enabled by using '-p' on the command line, or by issuing the action 'O51' to set option 5 to 1. Other routes are set using 'O5n' where n is one of the above. The 'o' action adds a carriage return and a line feed character to each line supplied. ~G oLine of text - output line of text to output route To output a control code to the printer, such as a form feed, the string function &Cnn can be used:- o&C12 CAUTION: It is wise to warn the reader to have the printer ready . .FRAME Popup message .TITLE Action 'P' ~X1Format: Pmessage The 'P' action pops up a flashing 'message' at the current mouse cursor position, and awaits a key or mouse button depression before 'popping down'. PHello there! If a null string is passed as a parameter, an asterisk will flash in the bottom right hand corner of the screen. This can be used as a pause to await a key depression from the user before continuing with a series of actions. . .FRAME Display message .TITLE Action 'p' ~X1Format: pmessage The 'p' action displays a 'message' at the bottom of the screen, and continues without waiting for any inputs. pThis is a long message to stay on the screen If no parameter is supplied to p, it clears any message currently on display. . .FRAME Quit HyperShell .TITLE Action 'Q' ~X1Format: Q{exit status} This action is used to exit the HyperShell program. If a parameter string is given, its numeric value is used as the exit status for the HyperShell program. This means you can use hypershell in batch files to control the flow, just as with the 'ask', 'choose' etc. type of programs which set the exit status to be tested with the 'IF ERRORLEVEL' statement. It is also possible that you may wish to return information to a program that has invoked HyperShell directly. Q1 - exit with status 1 . .FRAME Quit script .TITLE Action 'q' ~X1Format: q This action cancels any current script being executed. It can be used to abort a script if an error situation occurs. . .FRAME Formatted read .TITLE Action 'R' ~X1Format: Rsabc.. The 'R' action allows a line to be read from the input file (opened via the 'r' action), split into fields separated by the character 's', and assigned to a number of variables (abc etc). If the character 's' is ommitted, the fields are assumed to be separated by spaces. Separators can be any non-alphanumeric character which can be supplied at this point in the action string. When the end of the file is reached, no assignments are performed and the error status is set. R:gja - reads the next line from the file and splits it on ':' characters into variables g, j and a. ~X1See also: ~FOpen/close input file~E . .FRAME Open/close input file .TITLE Action 'r' ~X1Format: r{filename} This action is used for opening or closing an input file dedicated to applications use. If a parameter is supplied, it contains the name of a file to open for input. If no parameter is supplied, the input file is closed. The file opened via this action can be read by the action modifier '!' or by the action 'R'. Note that on opening an input file, any already open input file will be put in suspension until the file is closed, at which time the original file will again be available for reading. There can only be two suspended input files. rDATABASE.DAT - open DATABASE.DAT for reading ~X1See also:- ~FFormatted read~E . .FRAME Execute script .TITLE Action 'S' and 's' ~X1Format: Sscriptname The 'S' action executes a named script. If a script is currently being executed, it is cleared prior to running the specified script. The 's' action looks for a script local to the frame, and if not found looks for a global script. SShow price - run script 'Show price' ~FScripts~E can be appended to add ~Fsubroutines~PFcall subroutine~E. If a script calls another script, the first script is cancelled. ~FParameters~E can be supplied on a script action. ~X1See also:- ~Fscripts~E, ~FParameters~E . .FRAME Display text file .TITLE Action 'T' ~X1Format: T{filename}{#page}{/search string} The 'T' action presents a paged display of the named text file. If no filename is supplied, reentry to a file display that has been interrupted is assumed. The paged display highlights any references embedded in the text file, unless the ~Fverbatim~PFOptions~E option is set. If the ~F8 bit filter~PFOptions~E is set, the top bit is cleared on all characters displayed (This is used for certain word processor files). If a search string is specified, the string is located and the page containing the string is displayed, with the line containing the string highlighted. If a page number is specified, the display locates at the page number, and is a search string is also specified any line containing the search string is highlighted. Tmanual.txt - display file 'manual.txt' Tcatalog.dat/chair - display file and search for 'chair' Tcatalog.dat#8 - display file at page 8 Tcatalog.dat#8/chair - display at page 8 and highlight 'chair' A number of function and control keys are supported:- F1 or ? Help F2 or # Request page number and go to page F3 or Pg Up Go to previous page F4 or Home Go to start of file F5 Search for next occurrence F6 or / Request search string and perform search F7 Redisplay current page F8 or End Go to end of file F9 or RETURN Suspend typing, allowing subsequent return F10 Close file and exit typing Ctrl-Right Scroll Right to view text off screen Ctrl-Left Scroll screen to left ESCAPE Exit typing and cancel script Pg Dn or other unmapped key Go to next page ~G The RETURN key, if over a highlighted reference, selects the reference, otherwise it returns to the current frame display, and permits subsequent return to viewing of the file by use of the 'T' action with no parameter. A further T action, supplying a parameter, will close the file on display and start a new one. References selected from the text will be acted on. Certain references will have a 'T' action appended so that viewing of the file will resume after the action has been performed. The F6 or '/' key will prompt for a search string, and search forward through the file for that string, stopping at the page containing the string and highlighting any lines containing the string. A ~Fpattern match~E search can be specified by starting the search string with the '^' character. Further occurrences of the string can be located by pressing F5. The F2 or '#' key will prompt for a page number, and will then locate and display the page. . .FRAME File popup note .TITLE Action 't' ~X1Format: tfilename The 't' action displays the contents of a file as a popup note, the filename having an explicit extension or a default implicit extension of '.NTE'. The file notes can contain the same as normal ~Fnotes~E, and can contain references which can be selected. The file note is used for a number of purposes, and usually indicates that the note is less permanent than one included in the hyperfile. It could, for instance, be a scratchpad note created by the HyperShell user. If a text line in a note file starts with the '.' character, that line and the remaining lines are not displayed. tprices - pops up note file PRICES.NTE ~FParameters~E can be supplied on a file note action. . .FRAME Set variable .TITLE Action 'V' ~X1Format: Vxstring The 'V' action allows a variable 'x' to be set to a 'string'. There are 52 applications variables named 'a' to 'z' and 'A' to 'Z'. There are a few system variables that may be set using this command also, although the numeric ones cannot be changed. ~FVariables~E can hold any string value, and can also hold numeric data as a numeric string. Variables can be expanded into the frame text display, a note display, or into an action string, by specifying the variable substitution token '$$x' where x is the variable name. VnJohn Smith - set variable 'n' to 'John Smith' The 'named' variables described under the 'l' action may not be set using this action. ~X1See also: ~FTest variable~E . .FRAME Test variable .TITLE Action 'v' ~X1Format: vxstring The 'v' action compares the variable 'x' against the 'string', setting condition codes to reflect the result of the comparison. A lexical comparison is performed, unless the comparand string starts with a numeric digit or a minus sign, in which case an integer numeric comparison is made. A substring search of both operands within each other. The resulting ~Fcondition codes~PFconditions~E can be used in the 'j', 'a' and 'z' actions, and other places. vnSmith;jcSMITHS - jumps to SMITHS if 'n' contains 'Smith' Pattern matching is performed during a variable comparison if variable '~~' is set. If the supplied pattern starts with a '^' character, the variable is compared against the supplied pattern using a ~FPattern Match~E process, otherwise a case sensitive comparison is performed. If the comparison succeeds, condition code 'm' is set, else condition code 'f' is set. If variable '~~' is NOT set, the condition code 'f' will be set in ALL CASES (even when condition code 'e' is set). To test a named variable, it first has to be loaded into a single letter variable using the form:- Vx$$(named) This may then be used in the test:- vxtest value ~X1See also: ~FSet variable~E . .FRAME Write record to file .TITLE Action 'W' ~X1Format: Wstring The 'W' action writes the parameter string to the output file opened via the 'w' action. WRhododendron - writes 'Rhododendron' to file A line can be formatted to contain the values of variables by simply specifying the variable expansion tokens at the required place in the line. Thus to write a line with variables a,b,c in it separated by colons, we specify:- W$$a:$$b:$$c . .FRAME Open/close output file .TITLE Action 'w' ~X1Format: w{filename} w{filename+} This action is used for opening or closing an output file for hyperfile applications to use. If a parameter is supplied, it contains the name of a file to open for output. If no parameter is supplied, the output file is closed. If a suffix of '+' is added, an existing file is opened for extension. The file opened via this action can be written to using the 'W' action. If the file cannot be opened, an error status is set. wprices.dat - opens file PRICES.DAT for writing On opening an output file, any already open output file will be put in suspension until the file is closed, at which time the original file will again be available for writing. There can only be two suspended output files. . .FRAME Execute program .TITLE Action 'X' and 'x' ~X1Format: Xcommand line xcommand line The 'X' action executes the program and parameters supplied in the parameter string, and returns to HyperShell when the program terminates. The uppercase form waits for a key press before redisplaying the current frame, the lowercase form returns immediately to the display. The system variable '^' is set to the numeric exit code of the program. Xpayroll week 1 - runs program 'payroll' with parameters Care should be exercised when specifying the program invocation, as certain errors will 'crash' the computer and require a reboot. If in doubt, use the 'D' action, which is safer. The X actions are more efficient in speed and memory utilisation, however, and the exit code of the executed program is always available. . .FRAME Clear status .TITLE Action 'Y' ~X1Format: Y The 'Y' action does nothing, apart from reset the error status to 0. It is also used to 'throw away' the results of an action modifier. If the special system variable (`) is used, the Y action should be used to reset the error status so that the error action mapped to the variable is performed on an error. . .FRAME Refresh frame display .TITLE Action 'y' ~X1Format: y{c} The 'y' action refreshes the current frame display. If a parameter 'c' is supplied, and the frame occupies more than one screenful, the action has the following effects:- y - display first page of frame y# - redisplay current page of frame y- - display previous page of frame y+ - (or any other character than '-' or '#') display next page of frame or first page if at end . .FRAME Unless condition .TITLE Action 'z' ~X1Format: zcaction The 'z' action works in the same way as the ~Fconditional action~E does, but the action is only performed if the condition is FALSE. vn23;zlJGREQ - jumps to GREQ if 'n' not less than 23 . .FRAME Extended action codes .TITLE Action codes 'Z' The 'Z' code introduces an 'extended' action code. This is one where a second character denotes the action to be performed. As action modifier codes are required in the second or third character position, only the third character position is available with these action codes. This does have advantages in some cases. . .FRAME Specified autoreference .TITLE Action code 'ZA' ~X1Format: ZArreference:action ZArreference The 'ZA' action sets up an autoreference specification. The 'r' parameter is the reference type, and can be one of the reference flags A,F,f,M,m,N,n,S,s,t. action is the action string to be mapped to the reference. If the action part is ommitted, as in the second format above, the action string defaults to just 'rreference'. When the autoreference is applied, instances of string 'reference' are replaced by the string:- ~~rreference~~Paction~~E - for first format ~~rreference~~E - for second format To perform autoreferencing, the options 4 and *4 should be set appropriately (4 should be 2 or 3, *4 should be 0 or 1). This form of autoreferencing can be used for glossary references to global notes, or for ~Falternative hypertext~E referencing. Examples: ZANTSR - sets autoreference for note 'TSR' This sets note reference flags on all occurences of the string 'TSR' in the text. ZAAQuit:Q - sets up an action autoreference This maps the 'Q' action to all occurrences of the word 'Quit' in the text. . .FRAME Sound Bell .TITLE Action code 'ZB' ~X1Format: ZB The 'ZB' code causes the audible warning device to be deployed. This usually emits a 'beep' sound. ~p ~APress this if you haven't heard one before~PZB~E . .FRAME Blink enable .TITLE Action code 'Zb' ~X1Format: Zb1 Zb0 The 'Zb' action changes the way the text screen handles the 'blink' attribute. The settings are as follows:- Zb1 - Blink characters with high bit set (lowercase colours) Zb0 - High intensity background for characters with high bit This action may be used on various display adaptors to change the appearance of the text, and allow high intensity background colours to be set. ~X1CAUTION: THE ADAPTOR IS LEFT IN THE CURRENT STATE ON PROGRAM EXIT . .FRAME Do control menu .TITLE Action code 'ZC' ~X1Format: ZC The 'ZC' code causes the HyperShell control menu to be presented for selection. It is by default mapped to the ESC key. . .FRAME Exit subroutine .TITLE Action code 'ZE' ~X1Format: ZE The 'ZE' action returns from a subroutine called in a ~Fscript~PFscripts~E by the ~FCall subroutine~E action. If no subroutine is in effect, no return is made. . .FRAME Set footer depth .TITLE Action code 'ZF' ~X1Format: ZFnn The 'ZF' action sets the depth reserved for the ~Ffooter~E section for when conditional lines are included in the footer. The depth should accommodate the footer text with the most lines. This action is used in the SETUP script, if required. It is not necessary where the footer is of fixed content, as it will be determined automatically when the header is loaded. ZF4 - set footer depth to 4 . .FRAME Get mouse coordinates .TITLE Action code 'ZG' The 'ZG' action causes the mouse coordinates to be read into the variables used by the ~Fzone selection~E operation normally after a graphics display. These variables can be accessed using the functions &X and &Y, or a zone selection could be performed based on the new values. . .FRAME Special graphic selection .TITLE Action code 'Zg' ~X1Format: Zg Zgx The 'Zg' action will cause the mouse to be used for selection from the screen currently on display. If a parameter is supplied as in the second format, the screen is assumed to have a high vertical resolution (greater than 200) when calculating the mouse coordinates. This is used where some external program is used to display the graphic screen, or possibly when a further selection is needed from a screen displayed using the 'g' ~Fgraphic screen display~E. . .FRAME Hold line for return .TITLE Action code 'ZH' ~X1Format: ZH The 'ZH' action causes the current line number to be held in the subroutine call stack, permitting a return to be made to the current line using the ~FExit subroutine~E action. This is used as an alternative method for loop constructs:- -- open file rfilename.ext -- read file ZH;Y;R,abc jsEOF P$a $b $c -- loop back to read ZE LEOF r q . .FRAME Quick conditional .TITLE Action code 'ZI' ~X1Format: ZIexpr;action . . . The 'ZI' action, pronounced 'if', allows a single line conditional statement to be coded. The 'expr' represents a numeric expression as used in the ~FExpression Evaluation~E action modifier, but without the introductory '=' sign. If the expression evaluates to TRUE (having a value other than 0), then the remaining actions of the multiple action are performed, otherwise they are ignored. Condition codes are not affected by this action, unless the combined string compare and condition truth test (quotes) is used. With the extended ~Fexpression evaluation~E capabilities, this makes multiple conditions easy to specify. For example to test if variable 'x' is in the range 10 to 15 inclusive, and print a message if not, the following multiple action is coded. ZI(x < 10) ! (x > 15);pValue outside permitted range . .FRAME Call subroutine .TITLE Action code 'ZJ' ~X1Format: ZJlabel The 'ZJ' action acts like the ~FJump within script~E action, only the current position in the script is retained so that it can be returned to using the ~FExit subroutine~E action. If the label does not exist, no branch is made, but the position is marked so that a return can be made. Subroutines can nest up to 10 deep. . . . ZJDouble - branches to subroutine 'Double' . . . - return to here when subroutine exits LDouble - start of subroutine 'Double' . . . ZE - exit from subroutine . .FRAME Local flag toggle .TITLE Action code 'ZL' ~X1Format: ZLn{s} The 'ZL' action toggles the frame local flag 'n', and causes the display to be refreshed, unless the refresh suppression character 's' is specified. The flag 'n' has a value of '0' to '9' or one of the special local flags '/' or ':'. This is used for ~Ainline text expansion~PZL3~E using a reference of the form:- ~~Ainline text expansion~~PZL3~~E ~h3 Inline text expansion is used to provide additional information ~h3 hidden within the text until a reference is selected. This is ~h3 useful where an expert would not want to read mundane details ~h3 which a novice would require. The local flag is usually used ~h3 for this, although a ~Fglobal flag~PFglobal options~E can be used where an overall ~h3 expansion of text for a novice is required. . .FRAME Local flag indicator .TITLE Action code 'Zl' ~X1Format: Zlc{i} The 'Zl' action is used to select which of the ~Flocal flags~E will cause an indicator to be displayed in the ~Fcontents list~E. The 'c' parameter is the local flag code to be used. The optional 'i' parameter is a single character indicator which is displayed next to the key map box in the contents list. ~X1Example: Zl: This causes the default indicator '√' to be shown in the contents for frames which have been visited. . .FRAME Set 43 or 50 line mode .TITLE Action code 'ZM' ~X1Format: ZLM{nn} The 'ZM' action sets the video mode for the adaptor. ZM3 80 column by 25 line mode (default) ZM64 80 column by 43 or 50 line mode This should only be used with EGA and VGA adaptors. In the 43/50 line mode, depending on the mouse driver and adaptor, different degrees of control are available over the mouse cursor. You may find that it is not possible to properly use the extra lines. Using the -m flag on the command line may allow you to move the cursor below line 25 using keyboard control. All paged lists and the typed file display make use of the extra lines. Frame text also makes use of it, provided the footer has not truncated it at an earlier line. The number of lines is returned by function call &R25. .FRAME Preload hyperfile .TITLE Action code 'ZP' ~X1Format: ZPhyperfile The 'ZP' action causes a hyperfile to be loaded without any frame being displayed from it. This is useful to load a set of hyperfiles during the SETUP script, to permit searches to be made across them. ZPextra - preloads EXTRA.HYP . .FRAME Recall saved screen .TITLE Action code 'ZR' ~X1Format: ZR The 'ZR' action displays the screen that was saved at startup, if the '-s' flag was specified on the command line. If this flag was not specified, nothing happens. The frame is redisplayed when any key is pressed. . .FRAME Reset to full screen .TITLE Action code 'Zr' ~X1Format: Zr The 'Zr' action is used to reinstate the full screen mapping after a window has been defined within the screen using the ~Fbox draw~E reference flag, usually through a 'i' action. . .FRAME Set environment variable .TITLE Action code 'ZS' ~X1Format: ZSenvironment string assignment The 'ZS' action causes an environment variable to be set, which can be used elsewhere in HyperShell using the ~Fenvironment variable~E modifier, or passed to a program invoked from HyperShell, such as dBASE III, which can access the variable to obtain parametric information. ZSNAME=FRED JONES - equivalent to SET NAME=FRED JONES on the DOS command line. . .FRAME Take copy of screen .TITLE Action code 'ZT' ~X1Format: ZT The 'ZT' action takes a copy of the current screen display. The whole screen is saved to the screen save area (and overwrites that set up by the -s flag, if one was specified). The saved screen is displayed using the ~FShow saved screen~E action. This may be used before a ~Fsubwindow~PFBox draw~E is drawn, to allow the subwindow to be 'popped down' after use. ~X1CAUTION: These actions can be used for other purposes, but care must be taken not to confuse the user with false reference mappings. . .FRAME Show saved screen .TITLE Action code 'Zt' ~X1Format: Zt The 'Zt' action shows the screen display saved by a previous ~FTake copy of screen~E action. If no saved screen is available, nothing happens. The whole screen is overlaid by the saved screen save area (or the one that set up by the -s flag, if one was specified). A number of subwindows can be drawn, and cleared again afterwards using the Show saved screen action. ~X1CAUTION: These actions can be used for other purposes, but care must be taken not to confuse the user with false reference mappings. . .FRAME Unget key code .TITLE Action code 'ZU' ~X1Format: ZUc The 'ZU' action is used to place a character in the key input so that the action mapped to that character will be performed as though the key had been pressed. This can be used for frame display inputs, note display inputs, popup request inputs and graphic display inputs. It cannot be used for timeout inputs or text string inputs. It is usually used with a timeout input supplying the character:- ZU&G300;ab{timeout action} . .FRAME Set Named Variable .TITLE Action code 'ZV' ~X1Format: ZVnamed=value The 'ZV' action is used to set a named variable to a string value. ~FNamed variables~E can be used instead of the single letter variables to hold information for expansion in text or in an action. 'named' is the name of the named variable. Note that the name can be supplied in part or in full by the expansion of a variable token, allowing a form of 'subscripting' for arrays of values. ~X1Example: ZVdate=$$4 - set variable 'date' to current date ~X1See also: ~FNamed variables~E, ~FSet variable~E, ~FLoad named variable~E . .FRAME Set mouse column .TITLE Action code 'ZX' ~X1Format: ZXnn The 'ZX' action sets the 'x' position of the mouse cursor, namely the column number, from 1 to 80. The 'y' position, or line number, stays the same. ZX3 - set mouse cursor at column 3 . .FRAME Set mouse line .TITLE Action code 'ZY' ~X1Format: ZYnn The 'ZY' action sets the 'y' position of the mouse cursor, namely the line number, from 1 to 25. The 'x' position, or column number, stays the same. ZY15 - set mouse cursor at line 15 . .FRAME Parameters .TITLE passing data into scripts and notes The actions t,N,n,c,S,s and the @t,@N,@n modifiers can have a parameter string added in parentheses afterwards as follows:- Sscript(parameters) The string in parentheses is assigned to variable $$\, and can be used as such in the note or script. In a script, it can be split up on a separator using action 'e'. If the script is called with:- Shelp(contents,12,file.txt) Then this may be split into variables in a script using the action e\,abc... where a,b,c etc. are the variables to split the string into. For the above, this would set a = contents, b = 12, c = file.txt The variables can then be used within the script as parameters. . .FRAME Pattern Match .TITLE Extended string comparison and searching The Pattern Match operation, used for comparisons and searching, compares a string against a pattern. The pattern contains literal characters and various pattern specifying 'metacharacters'. These metacharacters are as follows:- < at start - match start of string > at end - match end of string ? match any character _ match one or more space or TAB characters (alt1/alt2) match alt1 or alt2 (if only one, it is optional) [abc] match 'a', 'b' or 'c' [^abc] match any character but 'a','b' or 'c' [x-y] match any character in range x to y e.g. [a-zA-Z] would match any letter { start of word } end of word x# zero or more of the character or subexpression x x+ one or more of the character or subexpression x * any string (equivalent to ?#) \x character 'x' (allows metacharacters to be used literally) Examples:- [a-zA-Z]# an alphabetic substring [0-9]# a numeric substring (perhaps) optional substring 'perhaps' (cat/dog)(s) 'cat' or 'cats' or 'dog' or 'dogs' ((pine)apple/grape(fruit)) 'apple','pineapple','grape', or 'grapefruit' <.FRAME a string starting '.FRAME' . .FRAME Menu parameters .TITLE Special forms of menu selection A number of different selection methods can be used to select items from menus, other by presenting the menu to the user for selection. ~X1[1] ~FArray selection~K1~E - to use a menu as an array ~X1[2] ~FLookup selection~K2~E - to use a menu as a lookup table ~X1[3] ~FZone selection~K3~E - to use a menu for graphic zone actions . .FRAME Array selection .TITLE Using a menu as an array Special forms of menu action specification are used to permit selection of a menu option from global, local and file menus, specified as actions or dynamic menus. The following form is used to select a menu choice by index:- Mmenuname(nn) Where nn is a number representing the option number in the menu to select. If the number is outside the range of the menu, no action is performed (or is returned for an action modifier), and the error status is set. P@Merror message(4) - Pops up line 4 of menu 'error message' . .FRAME Lookup selection .TITLE Menus as lookup tables A menu can also be used as a lookup table. The menu is then accessed by a specification of the form:- Mmenuname[key] In this case, the lines in the menu section have to be set up in the following form:- key|action Where key is the key to look up, and action is the action to perform if a match is found. The '|' character has to immediately follow the key string for this to work. If the key is not found in the menu, no action is performed and the error status is set. If the key is found, the action part is returned as the menu result. The last line of a lookup table menu can be of the form:- *|default action This action is performed if the key is not found in the other options. . .FRAME Zone selection .TITLE Mapping an action to a selection zone The form Mmenuname[@] is used for zone selection menus used with graphic displays. The menu options in this case are set up using the graphics preparation facilties described in the operation guide. They can also be set up manually, and have the following form:- kXYxy|returnval where k is the key mapping and XY and xy are the top left and bottom right corners of the selection zone. Returnval is the value returned by menu, as usual. XxYy are single characters equal to ASCII 32 + the column/row number (similar to those used in ANSI escape sequences on terminals). If a RETURN key or left mouse button is pressed, the zone coordinates are searched. If any other key is pressed, the key mappings are searched. A default entry can be placed at the end of the menu using an option of the form:-~G *....|default action Because the menu is searched in sequence from to to bottom, selection zones can overlap, as the selection priority is determined by the sequence. The zone 'on top' or 'in front' should come before the one behind. The graphics preparation facilities build the list from the start, so highest priority zones should be specified first. Of course, the list can be edited afterwards if the zones are in the wrong order. . .PRINT SECTION 5. . .PRINT TITLE Reference Guide - Action modifiers . .PRINT PAGE . .FRAME Action Modifier functions .TITLE Section - Functions to modify actions The action may have its parameter string supplied indirectly via an action modifier, or the first character supplied directly and the rest supplied indirectly. The action modifier argument string may contain variable tokens, which are expanded prior to evaluation. The result of the action modifier can optionally be further formatted via ~Fpattern strings~E. The resulting parameter string then has any ~Fvariable token specifiers~PFexpansion of variables~E expanded prior to being applied to the action. Action modifiers are as follows:- ~X1[1] ~FPrompt Function~K1~E Ask for string ~X1[2] ~FRead and Lookup functions~K2~E From file ~X1[3] ~FEnvironment variable~K3~E As SET by DOS ~X1[4] ~FExpression evaluation~K4~E Arithmetic ~X1[5] ~FString functions~K5~E Miscellaneous ~X1[6] ~FDynamic menu functions~K6~E Menus and selections . .FRAME Prompt function .TITLE Modifier code ? ~X1Format: ?prompt string ?prompt string/default The prompt modifier allows a string to be requested from the user. 'prompt string' is a string which is used as a prompt to the user. The input response will form the resulting parameter. If the first character of the prompt is a ':', the input response is not echoed to the user, allowing passwords and other confidential material to be input. Vn?Enter your name - loads input string to variable 'n' A string can be provided for editing by appending a string to the prompt modifier. When this is done, the cursor is placed at the end of the string ready for editing. This can be used to provide defaults or to modify the previous value of a variable:- Vc?Delete disk/Y Vj?Enter name/$$j . .FRAME Read and Lookup functions .TITLE Modifier codes !, !F, !L ~X1Format: !{F|L|B}{key} These functions perform read and search operations on the input file (opened by an 'r' action). The modifier for a file read is !F{key} Where {key} is an optional key string, which is compared against the start of each record read until a match is found. The comparison is case insensitive. If '!' or '!F' appears on its own, it returns the next line read from the input file. Any search starts immediately after the last record read. The modifier !L{key} Causes the file to be rewound prior to the search taking place. The EOF status is set if the end of file is reached. ~G !Bkey Provides a very fast search of a text file sorted in ascending order. The file can be sorted using the DOS SORT command. The fast search CANNOT be used on compressed files. . .FRAME Directory functions .TITLE Directory functions ~X1Format: !Dwildcard !D These functions allow the file names of files selected using the wildcard pattern to be accessed. The wildcard specification is used first to select the first file matching the wildcard. The specification without the wildcard is then used to step through the matching filenames. The EOF status is set when there are no more files matching the specification. The directory functions do not affect the currently open files, and it is possible to open, read and close each file in turn. ~X1Example: !D*.HYP - get first hyperfile name !D - get next filename . .FRAME Noted references .TITLE Modifier code !R and !C ~X1Format: !{R|C}{key} The noted references, set up using the INS key or the 'H' action, can be obtained using the modifier:- !R{key} The {key}, if present, causes the references to be scanned for the next one starting with the key string. For example:- !RF returns the next frame reference. Any search or step is taken from after the last reference obtained. The scan pointer is reset whenever a reference is added or removed from the list, and can be rewound with a dummy 'remove' action:- h The EOF status is set when the end of the references is reached. The comment associated with the last reference obtained by the !R modifier can be obtained using the modifier:- !C . .FRAME Environment Variable .TITLE Modifier code % ~X1Format: %variablename An environment variable modifier returns the value of a DOS environment variable. This variable is set using the SET command under DOS, or using the ~FSet environment variable~E action in HyperShell. Vf%FORMAT - load value of 'FORMAT' into variable 'f' The e.v. was set using a DOS command of the form:- SET FORMAT=DDMMYY . .FRAME Expression evaluation .TITLE Modifier code = ~X1Format: =expression An expression evaluation modifier returns the result of an expression. An expression can consist of simple integer arithmetic operations, boolean expressions, or a combination of both. An integer expression can involve the simple arithmetic operators +,-,*,/,% and can use parentheses to direct order of evaluation. The % operator returns the remainder of a division. The expression can involve integer values and alphabetic variable names (used directly without the $$ token). 32-bit signed integers are used in the evaluation of the expression. e.g. to calculate a value and assign it to the variable 'c':- Vc=(22*r*2)/7 ~G The arithmetic bit operations ! & and ^ represent OR AND and EXCLUSIVE OR. For example:- 2 ! 3 -> 3 2 ^ 3 -> 1 2 & 3 -> 2 Boolean expressions can be made up from the following operators, each returning a 1 if true or a 0 if false. = or == equality of comparands ~~= inequality of comparands < > <= >= left operand less than, greater than, less than or equal, greater than or equal #c truth of ~Fcondition~PFConditions~E 'c' "xstring"c combined variable comparison and condition truth ~G Boolean conditions can be combined using the bit operators to form compound conditions:- (a == 3) ! (a == 4) evaluates true if a = 3 or 4 The condition flags are set after an expression evaluation as though the result had been compared against zero. For an arithmetic evaluation a negative result is tested using the condition flag 'l'. The combined variable string comparison and condition truth boolean is effectively a string comparison, with the added power of the extra substring and ~Fpattern match~E condition codes. The 'xstring' forms the parameter for an implicit ~FTest variable~A action, with 'x' being a variable and 'string' being a comparand. The condition codes are set accordingly, and the boolean returns the truth of the specified condition code 'c'. ~G For a boolean expression, the 'n' condition code is set for a TRUE result and a 'e' condition code for a FALSE result (this may seem counter intuitive at first). The ~FQuick conditional~E expression testing action can be used for convenient testing of boolean expressions. The triadic conditional choice expression is of the form:- expr?true expr:false expr e.g. a<3?45:78 - if variable a less than 3 return 45 else return 78 Each expression may be of the full expression form. Nested triadics are therefore possible, but should be enclosed in parentheses. . .FRAME String Functions .TITLE Modifier code & ~X1Format: &FParg There are a number of functions which return a string or a number. In the general form shown above, 'F' is the function code, 'P' is an optional parameter and 'arg' is the argument string to apply the function against. ~X1[1] ~FList of string functions~PA@C4Function~K1~E . .FRAME ASCII value of character .TITLE Function code A The 'A' function returns the ASCII value of the first character of the remaining string, and is the same as the BASIC ASC() function. &AA returns '65', as this is the ASCII decimal code for 'A' . .FRAME Scale number .TITLE Function code B The 'B' function is used to format numeric variables for display with decimal places. It takes the next character as the number of decimal places to display. &Bpvalue returns 'value' with 'p' decimal places. &B212345 - returns 123.45 &B312 - returns 0.012 . .FRAME Character of code .TITLE Function code C The 'C' function returns the character equivalent to the ASCII value provided by the remaining string, which is expected to be numeric, and is the same as the BASIC CHR$$() function. &C66 returns 'B', as this is the character with ASCII code 66 . .FRAME External function .TITLE Function code c The 'c' function passes its argument to a Resident Extension, if there is one installed, and returns the result string. For example, using the hrxfp floating point extension &c10/4 returns 2.5 . .FRAME Display adaptor code .TITLE Function code D The 'D' function returns a single digit representing the type of display adaptor currently in use. Codes returned are:- 0 CGA adaptor 1 Monochrome or Hercules adaptor 2 EGA adaptor 3 VGA adaptor This ~sbutton~E displays the current monitor type . .SCRIPT button VT&D VT=T+1 P@mAdaptor($T) . .MENU Adaptor CGA Monochrome EGA VGA . .FRAME Extended key mapping .TITLE Function code E This function works as for the ~FM function~PFString mapped to key~E. The extended mapping function &Eks should be used for function key mappings, as 'ks' is specified as for action K. &EF8 returns the action string mapped to function key 8 . .FRAME Substring from .TITLE Function code F The 'F' function takes the next character as a search argument, and returns the substring from, and including, the located character, or the full string if this is not found. &Fdabcdefg returns 'defg', as this is the part of 'abcdefg' starting with 'd' . .FRAME Get key with timeout .TITLE Function code G The 'G' function takes the supplied numeric string as a timeout period in hundredths of a second. It then awaits a key depression and either returns the character pressed, or a null string if the timeout occurs. The character can be fed back as key input using the ~FUnget key code~E action, for use in selections from frame displays etc. Vn&G300 - this waits 3 seconds for a key press and loads it into 'n', or times out. . .FRAME Time of day .TITLE Function code H The 'H' function returns the time of day as hundredths of a second. This can be used to time long periods of activity. Short periods can be timed using the ~FDelta time~E function. &H returns time of day. . .FRAME Index of character .TITLE Function code I The 'I' function takes the next character as a search argument, and returns the index of this character within the remaining string, or zero if it is not found. This is similar to the BASIC INSTR() function, but only deals with a single character search argument. &Icabcdef returns '3', as 'c' is the third letter in 'abcdef' . .FRAME Input from screen .TITLE Function code i ~X1Format: &i{default} The 'i' function permits a string to be input at the current text cursor location, with an optional default value supplied. This function is intended for direct screen I/O in conjunction with the 'i' action, and possibly with windows defined using the ~~b2 and ~~b3 flags. For example, to put a prompt on the screen and then input a string, allowing a default, the following actions are used. i~~X10~~Y3Enter name: ~~c Vn&iFred CAUTION: This function should be used with care . .FRAME Delta time .TITLE Function code J The 'J' function returns the time since the last call to function 'J', function 'G', function 'H' or the last frame display in hundredths of a second. It can be used to time certain events, such as the time taken to select from a menu or a frame. . .FRAME Prompted key input .TITLE Function code K The 'K' function takes the remaining string as a popup message, awaits a key depression, and returns the character for the key pressed. This is similar to the BASIC INKEY$$() function. &KPress Y or N could return 'Y' or 'N' (or any character typed in response) . .FRAME Length of string .TITLE Function code L The 'L' function returns the length of the remaining text string in the action, and is the same as the BASIC LEN() function. &Labc returns '3', as there are three letters in 'abc' . .FRAME String mapped to key .TITLE Function code M The 'M' function takes the next character as a key character, and returns the string mapped to that character (using the 'K' action), or a null string if nothing is mapped. &Mh could return 'NHelp', if the mapping action 'K#hNHelp' was in effect . .FRAME Indexed character .TITLE Function code N The 'N' function takes the next character as a numeric argument specifying an index into the string. The character indexed in the string is returned as the result of the function. &N4abcdef returns 'd', as this is the 4th letter of 'abcdef' . .FRAME Application option setting .TITLE Function code O The 'O' function takes application flag specification following and returns the character mapped to that flag. &OA would return the character setting of flag 'A' (set via action O*A) . .FRAME Pick word .TITLE Function code P The 'P' function returns the word or number over which the mouse cursor is positioned. This can be used for direct selection or prompted selection of words. If any character follows the &P, the word is echoed at wherever the text cursor is positioned. K#nN&P When the 'n' key is pressed with the mouse positioned on a word, this pops up a global note, if there is one, about the word. pSelect word to search for P A@S&P This prompts for the selection, issues a null popup message to await mouse selection with any key, then searches for the selected word in the frame titles. . .FRAME Typed file details .TITLE Function code p Format: &pn The 'p' function returns details about the current or previous file which was typed using the ~FDisplay text file~E action. The parameter 'n' may have the following values:- 0 - returns 1 if file still available, else 0 1 - returns current page number ? 2 - returns current maximum page number ? 3 - returns end of file page number or 999 if not reached ? See Also: ~FTyped file name~E . .FRAME Pick reference .TITLE Function code Q The 'Q' function returns the action string for the reference over which the mouse cursor is positioned, or a null string if not over a reference. This can be used for processing the action in other ways than executing it, when selected using a key other than the Return key. &Q - returns the reference action . .FRAME Run option .TITLE Function code R The 'R' function returns the numeric value of one of the run ~FOptions~E or ~FExtended Options~E. It takes a numeric parameter equal to the option number (plus 10 for extended options). &R17 - returns the tab stop width. &R4 - returns the autoreference setting Also for codes 20 onwards:- 20 returns 1 if -s was specified on the command line 21 returns 0 if -m was specified and 1 if not. 22 returns the number of input files open using 'r' 23 returns the number of output files open using 'w' 24 returns 1 if U.K. date format, 0 if U.S. date format 25 returns the number of frames listed in the last search operation or contents list . .FRAME Substring indexed .TITLE Function code S The 'S' function takes the next character as a numeric argument specifying an index into the string. The substring indexed in the string is returned as the result of the function. This is similar to a variant of the BASIC MID$$() function. &S4abcdef returns 'def', as this is the substring starting at the 4th character of 'abcdef'. . .FRAME Frame title string .TITLE Function code T The 'T' function takes the remaining string as a frame name, and returns the title string for that frame. &TFrame title string would return 'Function code T' . .FRAME Typed file name .TITLE Function code t Format: &t The 't' function returns the filename of the current or previous file which was typed using the ~FDisplay text file~E action. See Also: ~FTyped file details~E . .FRAME Substring upto .TITLE Function code U The 'U' function takes the next character as a search argument, and returns the substring up to, but not including, the located character, or a null string if this is not found. &Udabcdefg returns 'abc', as this is the substring of 'abcdefg' up to, but not including, the letter 'd'. . .FRAME Configuration string value .TITLE Function code V The 'V' function takes the numeric argument as a ~Fconfiguration~E string index and returns the string configured to that value &V56 would return the date format string . .FRAME Variable address .TITLE Function code v ~X1Format: &vx The 'v' function returns a string representing the segment and offset address of the variable 'x', in a form usable by an external program, so that the variable may be accessed. The form of the string is two hexadecimal numbers separated by a colon, as follows:- SSSS:OOOO This string can be assigned to a variable and used in a command line of an invoked program. This can then access and modify the variable if it decodes the address first. If a variable is to receive data, it must be large enough for that data, otherwise information will be overwritten, with unpredictable results. CAUTION: This function should be used with extreme care . .FRAME Whole string .TITLE Function code W The 'W' function returns the whole supplied string. This is used to permit action modifier characters to be included in the initial few characters of action strings. P&W?Hello would popup the string '?Hello' whereas P?Hello would prompt for a string with 'Hello' and then pop it up . .FRAME Graphic X coordinate .TITLE Function code X The 'X' function returns the column number of the mouse cursor when a button was pressed during the last graphic display. . .FRAME Graphic Y coordinate .TITLE Function code Y The 'Y' function returns the line number of the mouse cursor when a button was pressed during the last graphic display. . .FRAME Graphic key press .TITLE Function code Z The 'Z' function returns the key pressed during the last graphic display. . .FRAME Convert string .TITLE Function code # ~X1Format: &#vconv The function '#' performs string conversion on the variable 'v' according to the conversion string 'conv'. The conversion string is taken as a string of directives to show the conversion required. Directives can be as follows:- l - convert to lowercase u - convert to uppercase s - strip superfluous spaces tv - translate according to variable v rv - remove characters in variable v each directive can be made conditional by preceding it with:- ic where c is any condition code letter e.g. i3rr removes characters specified in variable 'r' if frame-local flag 3 is set directives and conditional directives can be combined in a single string:- e.g. ls - convert to lowercase and remove spaces So, to convert variable x to lowercase and remove spaces:- Vx&#xls The conversion string can be supplied from a variable simply by using a variable token. e.g. to use the '~~' variable, the action is:- Vx&#x$$~~ . .FRAME Dynamic menu functions .TITLE Modifier code @ ~X1Format: @menuspec The dynamic menu specification covers a range of menus and paged selections. The selected choice from the dynamic menu becomes the resulting string. These menus are not necessarily 'dynamic', but the term does apply to some of them, and is used collectively for all of them. ~X1[1] ~FList of dynamic menus~PA@C4Menuspec~K1~E . .FRAME Select backtrack .TITLE Menuspec B and b The '@B' dynamic menu presents a paged list from which a frame can be selected, and returns the backtrack level number. This is usually used with the 'b' action to unwind to a frame:- b@B The following action will unwind fully to the entry frame b1 The '@b' dynamic menu presents a paged list from which a frame can be selected, and returns the frame reference. This is usually used with the 'A' action to revisit a frame without unwinding the backtrack list:- A@b . .FRAME Contents list .TITLE Menuspec C The contents list menu '@C' presents a paged list of frames in the current hyperfile, optionally refined using the variants shown below. The contents list returns a frame selection action, and is usually used with the 'A' action:- A@C @C0 Is the same as @C, and lists all frames in the hyperfile @C1 Lists those frames matched in the last search @C2 Lists those frames not matched in the last search @C0, @C1 and @C2 can also have a string appended which is used to refine the list to those frame names starting with the supplied string. @C3string Lists all frames starting from the first frame name starting with 'string' @C4string Lists all frames with titles starting with 'string' @C5string Lists all frames starting from the first frame with a title starting with 'string' A@C3$$1 - lists all frames starting at the current frame . .FRAME Formatted list .TITLE Menuspec G ~X1Format: @Gfilename{#page}{/search} This is a variant of the ~FDisplay text file~E action, and is used for producing formatted listings of files with special character separated fields, for instance comma separated fields. The line to be displayed is firstly split into a number of variables, then a format line with embedded variable tokens is expanded and displayed. The parameter specification, and the operation of the list is as for the ~FDisplay text file~E action. Any comparisons for searches are done done against the original line. The ~AG mappings~PFGeneral mapping~E need to be set up before using the @G list. KG5 variable split specification KG6 selection expression KG7 line format template, with variable tokens and two %c tokens for key mapping ~G The G5 mapping should be a variable split specification, as for the ~FFormatted read~E action, and will cause each line to be split into the specified variables before display. eg. KG5,abcd - split line on commas into variables a, b, c and d The G6 mapping is a 'selection expression'. This is an expression as used in the ZI action. The variables set up by G5 can be tested to provide a selection of records to be displayed. If the expression is true, the formatted line is displayed, otherwise the record is ignored. Note that it is set to 1 by default as this is true for all records, so this key mapping need not be explicitly set. This expression is particularly effective with numeric fields, and can be used with combination string comparisons for more power. eg. KG6(a > 0) & (a < 11) display only those records with field 'a' between 1 and 10. ~G The G7 mapping is a prototype line which is used to format the variables and to provide an optional key mapping if reference flags are added. Two %c tokens can be included, which will receive the key map characters as used in other paged displays. Note double dollars are used in the mapping line to delay expansion until the display stage. Examples:- KG7$$$$a~~C20$$$$b~~C40$$$$c~~C60$$d - Simple tabulated list of variables a, b, c, d KG7[%c] ~~A$$$$a~~PSprocess($$$$a)~~K%c~~E ~~C40$$$$b~~C50$$$$c~~C60$$$$d - Key mapped list with variable 'a' set as a reference to a script called using the value of 'a' as a parameter. . .FRAME Directory listing .TITLE Menuspec D, d and E ~X1Format: @Dwildcardspec The '@D' menu pops up a menu of files matching the wildcardspec, and returns the filename selected. No extension is displayed in the menu, and no extension is returned. The '@d' works as for the '@D' menu, only the file extension is included in the menu, and is returned on selection. The '@E' works as for the '@D' menu, only the menu presented only includes subdirectories. The menu return can be used in any action, or dynamic menu, requiring a file specification as a parameter. T@d*.TXT - gives a menu of files with extension .TXT then displays the file selected C@E*.* - change to selected directory . .FRAME Popup menu .TITLE Menuspec M,m and F ~X1Format: @Mmenuname @Ffilename The popup menus simply present the menu named, and return the option selected. The '@F' menu uses the contents of a file as the menu. The filename specified has a default extension of '.MNU'. Vp@Fprice - uses PRICE.MNU as a menu . .FRAME Extended directory .TITLE Menuspec L and l ~X1Format: @Lwildcardspec @lwildcardspec The extended directory display '@L' presents a paged list showing details of the files matching the wildcardspec, in a similar fashion to the DOS DIR command. It returns a filename, and should be used with an action requiring a filename parameter. G@L*.PIC - lists all files with an extension .PIC The extended directory display with actions added '@l' provides its own action strings for typing a text file or changing to a directory, and should be used with the 'A' action. . .FRAME Popup note .TITLE Menuspec N,n and t ~X1Format: @Nnotename @tfilename The popup note displays return the action string resulting from selection of a reference within the note display. These do not have to be used as actions, and a note can be used as a fancy form of menu which can return any string for any purpose. . .FRAME Notepad selection .TITLE Menuspec R ~X1Format: @R The notepad display '@R' is used to display a paged list showing the noted references and their associated comments, and returns the selected reference action, it is usually used with the 'A' action:- A@R . .FRAME Search selection .TITLE Menuspec S,s,X and x ~X1Format: @Ssearch string The search operations available are as follows:- Sstring Search for string in titles of current file sstring Search for string in titles of open files Xstring Search for string in titles and texts of current file xstring Search for string in titles and texts of open files The title searches look for the search string in the frame name and the title. A search string starting with the '^' character indicates that a ~Fpattern match~E search is to be performed, and that the remaining string forms the pattern. The search menus normally return a frame selection action, but may also return other reference actions. They should be used with the 'A' action:- A@S?Enter search string The list of matches produced can be used for immediate selection, or can be left to complete and subsequent selection made from a restricted contents list:- A@C1 The search can be restricted to refine a previous search or to add to a search. This is achieved by setting the search refinement option O*6 as follows:- O*60 Search all frames O*61 Search frames matched in last search This refines the search (effectively an AND) O*62 Search frames not matched in last search This adds to the matched frames (OR condition) O*63 These work as for 1 and 2, but reset the option O*64 to 0 after the next search operation. When an additive search is done, only the new matches are shown in the search listing. A subsequent restricted contents list as above will show all the matching frames. If the option O*6 has 5 added to its value, the search listing only shows the first page of lines matched, does not list the frames for selection, and returns immediately the search is complete or the user presses a key to abort the search. The value of 5 is subtracted from the option value at the start of the search, and the remaining value is used as indicated above. This feature is provided to allow combinations of searches to be performed without user intervention, such as looking for frames containing 'string a AND string b' or 'string a OR string b'. Combinations of title search and text search should start with the title search, as this will reduce the amount of text searching required. The last search can be a normal stopping search so that selection can be made from the listing. . .FRAME Pattern strings .TITLE Action suffix | The pattern string may be optionally specified after an action modifier to format the return string into a form expected by the action. Pattern strings consist of the string expected as a parameter, with all occurences of the chosen string represented by the string '%s'. Up to three occurrences of the chosen string may be expanded in the pattern string. An example is a command to copy a file selected from a directory display to the root directory of drive C:- d@d*.*|COPY %s C:\%s This facility can be used for more complex formatting, if the variants on the '%s' format token are used:- %{-}{nn){.mm}s | | | | | maximum length (truncated at right end) | minimum length (right aligned, space fill) left align (else right align) For example:- %s full string as supplied %8s string to minimum length of 8, right aligned %-8s ditto, left aligned %.23s string to maximum length of 23 For example, to shorten a variable, x, to 5 characters, and enclose it in square brackets (function &W is used here):- V&W$$x|x[%.5s] This facility is useful where you are formatting lines for printout, to make things line up in columns. . .FRAME Paged displays .TITLE Lists presented page by page Paged displays provide a full screen display offering one line per option, and offering multiple pages of options if necessary. F1 or ? - Help menu F2 or # - Go to page number (*T) F3 or PgUp - Previous page F4 or Home - Start of list/file F5 - Find next match (*T) F6 or / - Search file (*T) F7 - Redisplay page (*T) F8 or End - End of file (*T) F9 - Quit (*T Suspend list) F10 - Quit (*T Quit list) Return - Select reference (*T Suspend if not on reference) INS/DEL - Add / Remove reference from notepad (*T - Type file control keys) . .PRINT SECTION 6. . .PRINT TITLE Reference Guide - Variables . .PRINT PAGE . .FRAME Variables .TITLE Section - containers for data HyperShell permits strings to be assigned to 'variables'. These are token characters which hold character or numeric data strings and can be expanded anywhere in the displayed text, and can also be used to parameterise the control strings of the various ~Factions~E that may be performed. There are three main types of variable:- ~X1[1] ~FSystem variables~K1~E - used for HyperShell details ~X1[2] ~FApplication variables~K2~E - used by applications ~X1[3] ~FNamed variables~K3~E - extra applications storage . .FRAME System variables .TITLE Variables about HyperShell itself There are a number of system variables, some of which may be set by hyperfile applications, and some which can only be expanded. The HyperShell system variables have the names '0' to '9' and some special characters, and have the following string values:- 0 full pathname of HyperShell program used 1 current frame name 2 current frame title 3 current file name 4 current date 5 current time 6 backtrack list current depth 7 current directory 8 original directory 9 HyperShell name and version ? error code of last error that occurred < file name returned from last paged directory display > filename extension returned from last long directory : list of extensions to be excluded from TYPE action @ Available memory _ File prompt (becomes null string when viewing file) ^ Exit status from X,x,D,d action program execution \ Parameter supplied in parentheses to note or script ` Error action - action taken on error status set ~~ Variable specifying string conversions for comparisons , Pseudo variable - represents ';' in action mappings ! Pseudo variable - represents '!' in action mappings The ':' variable is a string representing those file extensions for which the extended directory display providing actions (dynamic menu 'l') will not set a 'Type file' action. It is set to the following string by default:- .EXE.COM.OBJ.SYS.DBF.LIB. Additional extensions can be added by resetting the variable. Note that extensions should have a '.' to each side. . .FRAME Application variables .TITLE Variables with single character names Application variables are strings that may be stored under a single letter name, either upper or lower case. Thus there can be 52 application variables. Variables can be set within a hyperfile and may be 'expanded' within the frame text or in an action string. Application variables are provided to allow a hyperfile to modify its behaviour depending on circumstances. For instance, variables may be used to input parameters one at a time in order to build up a command line for execution under DOS, or to build an action specification. Popup menus are useful for setting variables to one of a fixed set of values. In addition, an unlimited set of ~FNamed variables~E are available, which provide for longer term storage of data, and for sets of data in pseudo-arrays. . .FRAME Expansion of variables .TITLE Variable token specification The variable expansion token for system and applications variables takes the form '$$x' where x is the variable name. This is expanded to the string value of the variable. The variable may be expanded in the frame text, in a note text, or in an action string, where it may form any part of an action string apart from the action code itself (although the 'A' action can be used to permit the expansion of a variable to an action code). The variable expansion token is simply the flag character $$ followed by the variable name character. e.g. :- $$a If the '$$' symbol is required in the text, two '$$' symbols together will be taken to mean one, which will not be expanded when the text is displayed, or when an action string is expanded prior to execution. This may be used when an action string in a reference in frame text needs to contain a variable expansion token itself, but this must not be expanded until the action is performed. . .FRAME Named variables .TITLE Variables for longterm use There are another set of variables which can be specified. These are set and expanded in a different manner to single character ~Fvariables~E. They are set using the ~FLoad named variable~E action or the ~FSet Named Variable~E action. Named variables are expanded using the form:- $$(name) Where 'name' is the name of the variable. The name can be specified by a string containing single character variable expansion tokens, ~X1Example: $$($$n) or $$(item $$n) or $$($$n$$m) etc. Where n is a single letter variable containing the name of the named variable. This feature can be used for pseudo-arrays with a limited form of 'subscripting', or indirection. ~G It is possible to include a single character variable expansion token within the named variable value string. This will be expanded when the named variable is expanded. ~X1Example: ZVtime=Time: $$$$5 This will expand to the current time in the form 'Time: hh:mm:ss' when specified in text as $$(time). . .PRINT SECTION 7. . .PRINT TITLE Reference Guide - Conditions . .PRINT PAGE . .FRAME Conditions .TITLE Section - Condition codes and flags HyperShell provides a general system of condition codes which can be used to control various aspects of display and execution. The condition code token is a single character, which is specified in ~Fconditional action~Es, ~FHidden lines~Es and also in ~Fmenus~E. The condition code has a number of potential values:- ~X1[1] ~FResult of test~K1~E - for variable tests ~X1[2] ~FError status~K2~E - for action errors ~X1[3] ~FReturn value~K3~E - for action modifier returns ~X1[4] ~FLocal flags~K4~E - for frame related control ~X1[5] ~FGlobal options~K5~E - for application options . .FRAME Result of test .TITLE Condition set by test The traditional use of a condition code is to determine the result of a test or comparison. The first set of codes are used for this purpose, and are set up by the ~Ftest variable~E action 'v'. The test conditions available are as follows (note the lowercase form is used) e variable equals string * ! n variable not equal to string ! g variable greater than string * ! l variable less than string * ! d variable is defined u variable is undefined c variable contains string w variable is contained within string m variable matches a pattern ~~ f variable fails a pattern match ~~ ~G Note that the conditions marked with an asterisk indicate lexical comparisons unless the comparand string starts with a numeric digit or a minus sign '-', in which case an arithmetic (integer) comparison is made. The condition codes marked with an exclamation point are also set by use of the ~Fexpression evaluation~E function '=', indicating how the result compares against zero. e.g. 'g' is set if the result is positive. The condition codes marked with a ~~ are only set if a pattern match is performed, due to the variable '~~' being set. Code 'f' is otherwise always set. . .FRAME Error status .TITLE Condition set by error The next set of codes are used to indicate whether the error status is set, as follows:- s the error status is set o the error status is O.K. (clear) The error status can be cleared to 'O.K.' by the action 'Y', and will otherwise retain its setting, even if successful actions are performed. . .FRAME Return value .TITLE Condition set by action modifier This set of condition codes are used to determine whether a string is returned from ~Faction modifier functions~E, or whether a null string was returned or the function cancelled. r a string was returned b a blank string was returned or the function was cancelled These are very useful for a number of purposes, for example to determine whether a selection has been made from a menu or a string has been input to a request, or that a timeout has occurred from a ~Fget key with timeout~E function. . .FRAME Special codes .TITLE Condition codes for the IDE A special set of condition codes are provided with the integrated development environment (IDE), to allow a hyperfile to determine which program is running and whether an item is being edited or viewed. i Integrated environment being used v Item is being viewed, not edited . .FRAME Local flags .TITLE Condition codes local to frame This set of condition codes are flags which are local to each frame. These are usually used to flag a matching frame after a ~Fsearch selection~E, or to control ~FHidden lines~E in frames and notes. They are set using the ~FLocal flag toggle~E. 0 to 9 frame local flag. : visited frame flag (set after frame visited) / matching frame flag (set by searches) < frame more than one screen this is set after display of first screen of frame text, but is available in the footer and on subsequent screens and visits to the frame. . .FRAME Global options .TITLE Condition code for global control The fourth set of condition codes represent a set of general control flags which may be used to control a hypertext application - the ~Fapplication options~E. These flags are set using the ~Foption setting~E action O*X and are as follows:- A to Z application options These flags are character flags which evaluate TRUE if they are set to other than a null character. . .PRINT SECTION 8. . .PRINT TITLE Reference Guide - Restrictions . .PRINT PAGE . .FRAME Restrictions .TITLE Section - limits and reserved chars This section contains:- ~X1[1] ~FSize limits~K1~E ~X1[2] ~FNumber Limits~K2~E ~X1[3] ~FReserved characters~K3~E . .FRAME Size limits .TITLE Maximum lengths Line size, including flag characters, expanded variables etc. is limited to 255 characters. Frame name may be up to 35 characters. Title length may be up to 40 characters. Reference text length may be up to 39 characters. Action strings may be up to 40 characters, or 79 in scripts. Frame text can be up to 80 characters wide. Frame text can be any number of lines deep although the recommended limit is 24 - (header lines + footer lines). Note, Script and menu names must be less than 35 characters. Note text can be up to 76 characters wide and 22 lines deep, extra text being truncated. . .FRAME Number limits .TITLE Maximum counts There can be up to 100 references per displayed screen, INCLUDING headers and footers, and any note popped up containing references. A menu can now be any length, but will be displayed in groups of 20 options. A very large menu will exhibit a delay when showing later options. A script can contain up to 200 lines. . .FRAME Reserved characters .TITLE Control characters The following characters cannot appear within the second (or third if the second is not one of them) position of an action specification, apart from for their stated purpose. @ Dynamic menu & String function ! Read record = Expression evaluation % Environment variable ? Prompted input Also, for frame selection action specification + Next frame - Previous frame To include the above characters in the parameter to an action, the ~Fwhole string~E function &W can be used to 'guard' any special characters. The following characters cannot appear in the body of an action specification, apart from for their stated purpose. $$ Variable expansion token (code $$$$ for $$) | Action modifier pattern specification ^ (Within frame names) Hyperfile separator ; Multiple action separator (set up variable using &C to hold ';' character) The following characters cannot appear within frame text, apart from for their stated purpose. ~~ Reference and formatting directive flag (code ~~~~ for ~~) $$ Variable expansion token (code $$$$ for $$) . (At beginning of line) Section flag The '(' character cannot be used in a note or script name. . .PRINT SECTION 9. . .PRINT TITLE Reference Guide - Codes . .PRINT PAGE . .FRAME Codes .TITLE Section - Codes and mappings This section contains information about codes and setting. ~X1[1] ~FOptions~K1~E ~X1[2] ~FExtended options~K2~E ~X1[3] ~FColour codes~K3~E ~X1[4] ~FColour schemes~K4~E ~X1[5] ~FApplication options~K5~E ~X1[6] ~FControl key mapping~K6~E ~X1[7] ~FError codes~K7~E . .FRAME Options .TITLE HyperShell control Option Def Value Meaning 0 (0) - 1 = Use restart file for notepad 2 = Use restart file for notepad, variables and frame name 1 (1) - +1 = Symbols on menus +2 = Suppress function keys on menus +4 = Immediate (hot) menus on top line 2 (1) - 1 = Record backtrack 3 (1) - +1 = Add hyperfile name as notepad extension +2 = Suppress INS and DEL key notepad action 4 (0) - +1 = Autoreference frame names +2 = Application specified autoreference +4 = Autoreference global note names ~G Option Def Value Meaning 5 (0) - 1 = 'o' output to printer 2 = to standard text output 3 = to AUX device 4 = to output file (opened by 'w') 6 (0) - +1 = Display remaining space on exit +2 = Swap HS.EXE (~DFNB. only HS~DT) to disk on d and D actions 7 (0) - 1 = Trace script labels 8 (1) - 1 = Give warnings of unavailable items 9 (0) - 1 = 'T' listing gives verbatim list 2 = also strips 8th bit, for Wordstar files . .FRAME Extended options .TITLE HyperShell control Option Def Value Meaning *0 (1) - 1 = ESC key during popups, paged displays cancels script *1 (0) - 1 = Shadow edges on popups (uses G colour scheme) *2 (0) - 0 = No blinking 1 = Blink mouse cursor 2 = Blink mouse cursor and references using TAB/BackTAB *3 (0) - +1 = Suppress mouse cursor +2 = Use cursor left/right to select references (as TAB) *4 (1) - 0 = Restrict autoreference to typed files 1 = Include frame texts in autoref scope ~G Option Def Value Meaning *5 (0) - 0 = Accept characters less than 128 only 1 = less than 176 2 = less than 199 *6 (0) - 0 = Search all 1 = Search matched frames 3 = reset after 2 = Search unmatched frames 4 = reset after +5 - do 'non stop' search (+5 cleared after) *7 (8) - n = Tabstop width *8 (1) - 1 = Request comment on noted references *9 (0) - 0 = case sensitive key mapping 1 = case insensitive key mapping . .FRAME Application options .TITLE Application hyperfile control The application control options A to Z can be:- Set to a character using ~FOption setting~E action O*X O*Fj - set option 'F' to 'j' (condition will be true) O*F - reset option 'F' (so condition is FALSE) Used as a ~Fcondition code~PFGlobal options~E - A to Z aFPIt is set - popup message if option 'F' is set Supplied using the ~FApplication option setting~E function &OX Vx&OF - set variable x to character value of option 'F' . .FRAME Control key mapping .TITLE Control keys and headings Certain control keys and headings are configurable using the ~FSet key mapping~E action 'K', as follows:- Mapping Default Used for KH1 SELECT FILE (for directory popup menu) KH2 MHELP (for ? key in frame display) KH3 HELP (name of menu for ? in paged display) KH4 ZC (ESCAPE mapping) \ KH5 y (HOME mapping) \ KH6 ZR (END mapping) for frame display KH7 y- (PGUP mapping) / KH8 y+ (PGDN mapping) / KH9 B (BACKSPACE mapping) / KH0 HYPERSHELL (Control menu heading) . .FRAME General mapping .TITLE Control strings The general mappings are a further set of control mappings. These are configurable using the ~FSet key mapping~E action 'K', as follows:- Mapping Default Used for KG1 "" ENTER / LEFT button action when not over ref KG2 "" ENTER / LEFT button action in ~FDisplay text file~E KG3 "" ESCape / RIGHT button action in ~FDisplay text file~E KG4 "" End of title for ~FDisplay text file~E and @G KG5 "" Variable split specification for ~FFormatted list~E KG6 "1" Selection expression for ~FFormatted list~E KG7 "" Line format template for ~FFormatted list~E KG8 "" ~FString input translation~E ('from' characters) KG9 "" ~FString input translation~E ('to' characters) KG0 "" - Reserved - . .FRAME String input translation .TITLE Mapping keys to special characters The string input translation capability allows string input characters to have a translation mapping applied against them. String input is used in a number of places:- 1. For input of strings on the prompt line at the bottom. 2. For entry into input fields. The translation converts specified character codes to other specified character codes. This can be used for a number of purposes, including:- 1. Stopping the input of certain characters by translating them to a character which is rejected, such as TAB (ASCII 9). 2. Mapping certain ALT shifted keys to accented characters for language learning applications. (Note: option setting O*51 or O*52 must be used to allow input of extended character set). ~G ~FGeneral mapping~E strings KG8 and KG9 provide the 'from' and 'to' tables of characters. Whenever a character in the 'from' string is input, it is translated to the corresponding character in the 'to' string. Thus, to map the keys '%&*' to produce '!=^' characters, the following settings are used:- KG8%&* KG9!=^ The two mapping strings must be the same length or results will be unpredictable. The mappings do not have any effect on single keystroke inputs, such as function keys, menu selections, reference key mappings etc. . .FRAME Colour codes .TITLE codes Colour codes are as follows (monochrome in [brackets]):- K Black [Inverse] B Blue [Underline] G Green C Cyan R Red M Magenta Y Yellow (brown) W White (light grey) [Bright] k Dark grey (Foreground only) b Light blue (Foreground only) g Light green (Foreground only) c Light Cyan (Foreground only) r Light red (Foreground only) m Light magenta (Foreground only) y Light yellow (Foreground only) w Bright white (Foreground only) . .FRAME Colour schemes .TITLE Global highlighting schemes The available schemes are as follows, showing the scheme letter, the default setting (foreground, background) and the normal usage. ('User' schemes are not used by HyperShell):- Scheme colour mono Description A wB BK Action reference B Wk(bl) Wk(bl) Blink C KC KW Menu choice D KW KW Default title E yK wK Frame reference - replace backtrack F wK wK Frame reference - add to backtrack G KK KK Ghost - used for shadows on popups H KY kW Menu heading I yY KW Input field J KG KW Note heading and border K yG KW Note L RK BK Low intensity M KW kW Menu reference N gK bK Note reference O yB WK Menu selection P yr(bl) Kw(bl) Popup message Q Kk(bl) Kk(bl) XOR for reference (with TAB/BackTAB) R KW Kw Request / message S yG BW Script reference T WK WK Frame text U YK BK (User 1) V MK bK (User 2) W GK WK (User 3) X RK kK (User 4) Y BK BW (User 5) Z rK KW (User 6) . .FRAME Error codes .TITLE Status codes for error conditions The following error codes are set in variable '?'. The variable is only reset on command (~Fby the 'Y' action~PFClear Status~E). An action can be specified in ~Fsystem variable~PFsystem variables~E (`), which will be performed when the status changes from UNSET to SET (once SET, it should be RESET using 'Y' before the action will take place again). 0 Success - (after status cleared) 1 Operation cancelled 2 No choice from menu 3 End of file when reading 4 Cannot open file 5 File is not open 6 File is already open 7 File has changed 8 At start of backtrack 9 Divide by 0 in expression 10 Value not expected in expression 11 Value expected in expression 12 Undefined opcode in expression 13 Unmatched parenthesis in expression 14 Syntax error in expression 15 Script not available 16 Menu not available 17 Note not available 18 Frame not available 19 Key not defined 20 Invalid key code 21 Local reference - cannot be noted 22 Not at reference when key pressed 23 Key not mapped 24 No action or action disabled 25 Invalid action code 26 No command present 27 Environment variable not defined 28 Invalid dynamic menu 29 Line too wide for screen 30 String too long 31 Too many lines in frame 32 Maximum script size reached 33 Maximum menu size reached . .PRINT SECTION 10. . .PRINT TITLE Reference Guide - Miscellaneous . .PRINT PAGE . .FRAME General .TITLE Section - Miscellaneous information This section contains information on:- ~X1[1] ~FConfiguration~K1~E ~X1[2] ~FAutoreference~K2~E ~X1[3] ~FAlternative Hypertext~K3~E ~X1[4] ~FExample script~K4~E . .FRAME Configuration .TITLE Changing the look and feel The option flags, extended options and key mappings permit a lot of configuration to be done to individual hyperfiles. The colour schemes permit the various highlighting to be fully configured. Custom frame headers and footers can be used to create a professional appearance to your application. All the prompts, headings, format strings, error messages and other strings can also be configured using a special file called HYPSHELL.CFG. This provides mappings between configuration string numbers and the strings to be used. If the file is not supplied, default strings are used. Foreign languages can be readily supported using this. Full details are provided in the authoring guide. . .FRAME Autoreference .TITLE Inserting references dynamically The autoreference facility adds references dynamically as the text is displayed. A number of kinds of autoreference are provided. 1. Frame name autoreference flags any occurrence of frame names in the text. 2. Application autoreferencing allows specified search strings to be mapped to specified actions. 3. Global note name autoreference flags occurrences of global note names in the text. Both kinds of autoreference can be applied to just text displayed using the ~Fdisplay text file~E action, or to frame text displays as well as text files. . .FRAME Alternative hypertext .TITLE Other forms of hypertext The HyperShell single hyperfile format described in this file is normally used for hypertext systems. HyperShell does, however, provide a number of features which support an alternative to this format. The 'T' and 't' actions, described above, permit normal text files to be displayed, and these files can contain simple embedded references to other files, for display in a paged fashion using 'T' or as a popup note using 't'. The authoring guide gives a description of how this can be done. If HyperShell is given the name of one of these simple text files, rather than that of a normal hyperfile, it displays the file as a single frame, possibly with multiple pages. Thus, it is not even necessary to have a controlling hyperfile. Although it would not be usual to do so, such a file could contain HEADER, FOOTER and global items, provided these were supplied AFTER the main text in the file. . .FRAME Example script .TITLE to show how script works The following script, when called with a parameter e.g. Slines(read.me) counts the lines in the file whose name is supplied as a parameter and displays the total on the bottom line. The script is normally coded with a number of actions on each line, but it is coded here with one action per line so that comments can be added (these cannot appear on the actual script). Note that it is good practice to start a new line after a jump or conditional jump. Labels must appear at the start of a line. If there is an error opening the file, an error message will have been displayed already, so we just quit. The error status from the read is assumed to be an end of file indication. Note that you must remember to close the file when you have finished with it, otherwise it remains open until you quit HyperShell.~G ~C6.SCRIPT lines - select action for details ~Fv\~PFTest variable~E - is there a ~Fparameter~PFparameters~E ~FjeERROR~PFjump within script~E - no - go to error display ----\ ~FVx0~PFSet variable~E - set count variable to zero | ~FY~PFclear status~E - clear error status | ~Fr$$\~PFOpen/close input file~E - open file | ~Fasq~PFConditional action~E - quit if error | ~FLREAD~PFLabel in script~E - Label for read <-------------\ ~FY~PFclear status~E - clear error status | | Vy~F!~PFRead and lookup functions~E - read record into variable y | | j~FsEOF~PFconditions~E - if end of file goto display --- | \ Vx~F=x+1~PFexpression evaluation~E - increment count variable | | | ~FJREAD~PFjump within script~E - loop back to read -------------/ | ~FLERROR~PFlabel in script~E - error display label <-------/ | ~FPNo parameter supplied~PFpopup message~E - display error message | ~Fq~PFquit script~E - quit script ----------------\ | ~FLEOF~PFlabel in script~E - End of file label <------------/ ~Fr~PFopen/close input file~E - close file | ~FpThere were $$x lines read~PFdisplay message~E - display count | ~C6. - quit script at end v . .END End of HSREF.HYP .