CP/M

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

/ CP/M / CPM_CDROM.iso / jsage / zsus / z3help / m.lbr / MENU.HLP < prev next >

Wrap

Text File | 1991-11-18 | 29.6 KB | 921 lines

; The ZCPR3 MENU Shell -- ZCPR3 Utilities -- 1 - MENU 2 - MENUCK -- Using MENU -- -- Programming MENU -- U - Using MENU P - Programming *.MNU Files S - Summary of User Cmds C - *.MNU Internal Commands E - MENU Error Messages M - Programming Cmd Summary Z - MENU and ZCPR3 :1 Command MENU 3.9 Syntax MENU <-- run MENU.MNU or MENU ufn <-- run menu contained in file Function MENU is the ZCPR3 menu front-end processor. It is a ZCPR3 Shell which reads a *.MNU file and processes commands from it. Options None Comments MENU is a true ZCPR3 Shell. It is described in this HELP file. Selected Error Messages "No Command Line" means that the ZCPR3 System does not support an external Command Line Buffer. MENU must have this to run. "No Shell Stack" means that the ZCPR3 System does not support a Shell Stack. MENU must have this to run. "Shell Stack Full" means that the Shell Stack is full and MENU cannot push itself onto the stack. "Shell Stack Entry Size" means that the Shell Stack elements are too short for MENU to store its parameters. "TPA Full" means that there is not enough room in the TPA to load the *.MNU file. Examples of Use See this HELP file MENU is the ZCPR3 Menu-Oriented Command Preprocessor. It acts as a front-end to ZCPR3, providing a menu-oriented user interface to ZCPR3. Its function can be represented by the following diagram: ------ ------ ------ ------ |M | |Z | |B | |P | User | E | | C | | D | | g | Menu ---->| N |--->| P |--->| O |--->| m | Command | U| | R| | S| | s| | | | 2| | | | | ------ ------ ------ ------ The "User Menu Command" is a single character that the user strikes which instructs MENU to perform a function. Once MENU begins processing this function, it builds a command line for ZCPR3, optionally asking the user for further input (such as a file name), and then passes the command line to ZCPR3 via the Command Line Buffer. ZCPR3 then runs the command line returns to MENU. MENU builds command lines based on simple input from the user. The user need never know what the actual command line is. The command line itself is always of the form: <command> <optional user input> As an example, a command built by MENU to run XDIR with user input for a file name specification, could look like the following: XDIR <user input> When MENU is executed, it builds the list of files to be displayed, and then looks for the desired menu file. It begins its search in the current directory, and continues along the system path until either it has found the menu file, or all directories in the path have been searched without success. If the menu file is found, it will be read into memory, and the first menu displayed. If it was not found, an error message will be generated. If no menu file is specified, then MENU will default to MENU.MNU. If the user has supplied a file ID with both the menu file name and type, MENU will use this file. If only the file name is specified, the default file type of MNU is assumed. The MENU.MNU file can contain up to 255 menus to be processed by MENU. The MENU will begin processing at the first menu in MENU.MNU. MENU itself is a COM file, like any other program under ZCPR3. Unlike most other programs, however, it generates command lines to be executed by ZCPR3 and stores its return command in the Shell Stack. In this way a loop is set up: -->--+->- MENU ->- ZCPR3 ->-+ ^ v | | +-<- Command Line -<---+ Only MENU itself or a ZCPR3 tool like SHCTRL can terminate this loop. If the MENU programmer wishes, he can set up the MENU.MNU file so that this loop will never be exited, or he can set up the file to allow anyone to exit at any time or just a special person who knows a password to exit when he wishes to. There is a lot of flexibility designed into the system, and it will be discussed later in the section on programming MENU.MNU files. A MENU.MNU file can be set up to execute any ZCPR3 command or sequence of commands. The MENU.MNU file can also be set up to not allow the user to leave MENU, to allow him to leave MENU at will, or to allow him to leave MENU only if he knows a password. This HELP file is divided into two basic parts. The info sections on "Using MENU" and "Summary of MENU Commands" are designed to be read by a person wanting to use MENU but not wanting to learn how MENU works or how to program it. These sections describe how to move from one menu to another, how to issue MENU commands, and how to leave MENU if the option is presented to him. The other sections of this HELP file describe the programming aspects of MENU and are intended to be used as an online reference for the MENU programmer. The MENU command programming summary is especially useful in that it provides a summary of the commands which the MENU programmer may issue to MENU within a *.MNU file. :U When MENU is first invoked, it will be installed as a Shell. If commands are pending, control will return to the ZCPR3 command processor for the next command in the line. When the command line is exhausted, ZCPR3 will realize that a shell has been installed and invoke MENU as a shell. If there are no pending commands, however, MENU will begin the menu command processing immediately. When MENU begins execution as a Shell, it will load the menu file, and then one of three things will happen: 1) A MENU will appear and be paged up to fill the screen; a command prompt will appear at the bottom of the menu 2) A MENU will appear and not be paged up to fill the screen; a command prompt will appear at the bottom of the menu 3) A command prompt will appear with no menu (this is called the Expert Mode) If at any time a Menu Display is garbled or the user desires to see the current Menu (as sometimes happens when you are in Expert Mode), just strike the RETURN key. The RETURN key refreshes the menu at all times. The prompt which appears at the bottom of your Menu display has the following general form: Command (CR=Menu,^C=Z3,*=1st Menu,<=Prev Menu,>=Next Menu) - There can be up to 255 menus in one MENU.MNU file. The MENU command prompt varies to reflect this. For instance, if only one Menu was present and the option to abort out of MENU to ZCPR3 was not available, then the Menu Command prompt would take its simplest form, looking like: Command (CR=Menu) - Strike the RETURN key at this time to refresh the Menu Display or strike the character of a Menu Option. These are the only choices, and striking a character which is not the RETURN key or a menu option results in the bell sounding. If the the option to exit to ZCPR3 was available and there is only one Menu in the MENU.MNU file, then the command line will look like this: Command (CR=Menu,^C=Z3) - The option of aborting to ZCPR3 by striking Control-C (hold down on the Control, or CTRL, key and strike the letter C) is now available. This will return to ZCPR3 and exit MENU. One brief note on option letters before going on. If one of your options is a letter in the range from A to Z, then case is not significant, and you can invoke the option A, say, by striking an upper- or lower-case A. If there is more than one menu in the *.MNU file, the command line options become slightly more complex, but they are still quite easy to follow. In the following examples, assume that the option to exit to ZCPR3 is off, so the "^C=Z3" option will NOT appear. From the first menu in the file, the command line will look like the following: Command (CR=Menu,>=Next Menu) - To advance to the next menu, strike the ">" or the "." character. On most keyboards, ">" is the shift of the ".", so MENU permits easy movement without having to worry about shifting the keyboard all the time. If at the last menu in the file, the command line will look like the following: Command (CR=Menu,*=1st Menu,<=Prev Menu) - This allows the user to strike the "*" character to jump back to the first menu in his *.MNU file. If "<" or "," is stuck ("<" is usually the shift of the ","), then the user will back up one menu to the previous menu in the file. If the user is somewhere in the middle of the MENU.MNU file, his command line will look like this: Command (CR=Menu,*=1st Menu,<=Prev Menu,>=Next Menu) - Again, "*" will go directly to the first menu, "<" or "," will go to the previous menu, and ">" or "." will go to the next menu. Striking the RETURN key will refresh the menu display. One last option the user has under MENU involves access to a System Menu. This menu is special in that there is only one way to get to it -- via the "$" command. The System Menu is intended to give priveleged users access to special commands that the rest of the users can't run. If a System Menu is available, MENU will respond to the "$" command with the prompt: Pass? The user is given one chance to type in the correct password to enter the System Menu. If he is wrong, the message "Password Error" will appear and he will be returned to the menu he came from. If he is correct, he will enter the System Menu. Physically, the System Menu is always the last menu in the file, and its command prompt is: Command (<CR>=Menu,*=1st Menu,<=Prev Menu) - If the user is at the menu just before the System Menu, the ">" will not function to allow him to enter it, even tho there technically is a "Next Menu". The ">" option in the command line will not appear. The only way to enter a System Menu is thru the "$" command. In summary, moving about within MENU is quite easy. "*" moves the user to the first menu, "<" to the previous menu, ">" to the next menu, and "$" to the System Menu. :S The full Menu Command Line looks like the following: Command (<CR>=Menu,^C=Z3,*=1st Menu,<=Prev Menu,>=Last Menu) - The Menu Commands are: Command Function <CR> Refresh Menu Display (RETURN Key) ^C Exit to ZCPR3 (Control-C) * Jump to the First Menu < or , Jump to the Previous Menu > or . Jump to the Next Menu $ Jump to the System Menu (Password Required) other Menu Option or Invalid Command; letters are automatically capitalized, so a=A :P Programming *.MNU Files The *.MNU file is simply a text file which may be created with any conventional CP/M editor, including WordStar. MENU ignores the Most Significant Bit of all bytes, so editors like WordStar, which occasionally set this bit, can be used. All *.MNU files have the same general structure. The first line is either a global option line or the beginning of a menu display. If a global option line, it begins with the character "-", and this character is immediately followed by global option characters. The global option line, then looks like this: -options After the global option line, if any, comes the first menu. Each menu is structured as follows: #options <Text of Menu Display> # menu commands The following are two sample Menu File structures: -options #options #options <Text> <Text> # # commands commands ## #options <Text> # commands ## There are four option characters. In using them, case is not significant. These option characters are: Option Function C Display Command Line to User D Display Menu to User P Page Out Menu Display X Allow User to Exit to ZCPR3 The C option displays the command line built by MENU to the user. This option is primarily intended for debugging purposes, to allow the programmer to see what commands are being built. It is instructive to the user, however, and may be employed for that purpose as well. The D option displays the menu to the user. If the display function is not turned on, we are in Expert Mode, and the commands are available without a menu display. RETURN, of course, can be used to invoke the display if necessary. The P option pages out the menu display. If the page function is engaged, then the MENU program outputs <CRLF> combinations until 24 lines have been printed on the screen. This is somewhat more attractive and eliminates old text from previous commands, allowing the user to concentrate on his current set of options. However, it is annoying if the user is accessing the system, say, at 300 baud via a dial up. It is for this reason that the MENU programmer has this option. Finally, the X option enables the facility which permits the user to type ^C and return to ZCPR3. When MENU first comes up, all options are turned off: C is OFF -- no command display to user D is OFF -- no menu display to user P is OFF -- no menu display paging X is OFF -- user cannot exit to CP/M The global options line, which, if present, is the first line of the file, turns on these options for the course of the session in general. That is, if a global options line like -DPx is used (case is insignificant), then menu display, paging, and exit to ZCPR3 will be available for all menus. The global options line affects all menus. The global options line turns on the indicated options for all menus in general. However, the same options may be presented on the first line of each menu immediately after the "#" character to temporarily complement the current option for only that menu. If an option is NOT included in the global options line, it is turned OFF for all menus in general. The defaults selected by using the global options line are overridden on a per-menu basis by the local menu options. Example: -dpx #x This menu is displayed and paged, but no exit to ZCPR3 is permitted # commands #dx This menu is not displayed and the user may not exit to ZCPR3. # commands #c This menu is displayed, paged, and the user may exit to ZCPR3. Additionally, the MENU-generated commands are printed to the user. # commands ## Any option that may appear on the global options line may also appear on the options line for a particular menu. The menu options line supports one additional option, viz. "$". This option declares the following menu to be a System Menu. In programming a *.MNU file, the MENU programmer MUST place the System Menu as the last menu in the file if it is going to have one. To do otherwise is flagged as an error. The following illustrates a *.MNU file containing a System Menu: -dp # This menu is displayed and paged, but the user may not exit to ZCPR3. # commands #$x This is a System Menu, and it is displayed, paged, and the user may exit to ZCPR3. ## If a menu is a System Menu, the "$" character must immediately follow the "#". In the case of the letter options in both the global and local cases, the order is not important ("dpx" means the same as "xpd"). The password used to enter a System Menu is hard-coded in. It may be altered by reassembly or use of DDT. Note that this password can be upper- and lower-case, and case is significant. :C *.MNU Commands This section describes the technique and options available for creating command lines in *.MNU files. The information herein is organized into the following subject areas: o Syntax of the command line o :nn Option o ! Option o "text" prompts and input o Variables ($C, $D, $U, $Fn, $Nn, $Tn, $$) o Highlighting (^A, ^B) Syntax The commands in a *.MNU file follow a simple structure. Each command occupies only one line, and blank lines in the command group are not permitted. The command line is structured as follows: l[o][command] where: l is the single character used to invoke the command note that it may be upper- or lower-case o is an opening option, which is one of: :nn -- go to Menu nn ! -- have MENU wait when the command is finished command is an optional ZCPR3 command; note that if the option is ":nn", then a command here makes no sense nn Opt The ":nn" option tells MENU to move to a different menu in the *.MNU file. The first menu is number 1. Example: -dpx # 1st Menu: A - Goto Menu 2 3 - Goto Menu 3 # a:2 3:3 # 2nd Menu Command: 3 - Goto Menu 3 # 3:3 #x 3rd Menu Command: 2 - Goto Menu 2 # 2:2 ## :nn Opt In the first menu, the user may strike: "a" or "A" to goto Menu 2 "3" to goto Menu 3 ">" or "." to goto the next menu (Menu 2) ^C to goto ZCPR3 In the second menu, the user may strike: "3" to goto Menu 3 "*" or "<" or "," to goto Menu 1 ">" or "." to goto Menu 3 ^C to goto ZCPR3 In the third menu, the user may strike: "2" or "<" or "," to goto Menu 2 "*" to goto Menu 1 ! Opt The "!" option causes MENU to pause and ask the user to "Strike Any Key" before continuing after the command line has been processed. In this way, if a command generates information to be read by the user before MENU clears his screen, the "!" option may be used to give the user all the time he wants to read this display. "prompt" Embedded within any command line may be a prompt for user input. This prompt takes the form of "prompt to user" When encountered, MENU will advance to the next line and print the text contained within the quotes. MENU will then wait for the user to input any text he desires followed by a RETURN. At this point, the text the user input is capitalized and placed into the command line at the point of the prompt. If the prompt appears at the end of a MENU command line, the trailing quote is not required. As many prompts as desired may appear within a MENU command line. Examples: "prompt" -dxp # A - Run XDIR without Pause or Input B - Run XDIR and Pause before Returning to MENU C - Run XDIR, Allow User Input, and Pause before Returning to MENU M - Run MCOPY, Allow User Input of Dest Dir, Allow User Input of Source Dir and File, and Pause before returning to MENU Z - Run Any ZCPR3 Command and Pause before Returning to MENU # m!mcopy "Destination Dir? "="Source DIR:AFN? " z!"Enter Command Line -- axdir b!xdir c!xdir "Enter Ambiguous File Name -- ## "prompt" Note the Space right before the "Prompt form in the C command. This space is significant to keep the command and user input from running together. This "run together" is desired for the Z command. Also note the dual prompt for the M command. With the M command, the following prompts will appear (and sample input): Destination Dir? BACKUP: Source DIR:AFN? *.TXT and the following command line is built: MCOPY BACKUP:=*.TXT Variables The command text which is specified in the MENU command line can contain embedded variables which MENU will expand when the command line is processed. These variables, which are denoted by a dollar sign ($) followed by one or two characters, are defined as follows: Variable Expands as -------- ---------- $C Current DIR ('Noname' if not defined) $D Current Disk $U Current User Area $Fn FILENAME.TYP for ZCPR3 System File n $Nn FILENAME for ZCPR3 System File n $Tn TYP for ZCPR3 System File n $$ Place a single $ in command line These variables can also be used in the menu display itself, and their values will be substituted when the display is generated. Example: Variables -dpx # Menu to Run M80 Assembler Current File: $F1 Directory: $D$U F - Define File E - Edit $F1 P - Page $F1 A - Assemble $F1 # fsetfile 1 "Filename? " eedit $f1 azex m80 $n1 ppage $f1 ## Variables Notes: 1. The ZCPR3 utility SETFILE is used to define the name of a ZCPR3 System File. There are four System Files available, and they can be referenced by $F1 to $F4, $N1 to $N4, and $T1 to $T4. 2. The A command shows the execution of ZEX. MENU is a true ZCPR3 Shell, and, as such, ZEX commands can be issued from it and will run on top of it. The prompt for the ZEX command lines will be "Menu>". 3. Assuming that "MYFILE.MAC" is assigned to the ZCPR3 System File 1 and the user is logged into disk B user 1, the following screen shows how the display and the resulting command lines will be expanded when execution occurs: Variables Display Menu to Run M80 Assembler Current File: MYFILE.MAC Directory: B1 F - Define File E - Edit MYFILE.MAC P - Page MYFILE.MAC A - Assemble MYFILE.MAC Command Lines Menu Command Expansion fsetfile 1 "Filename? " SETFILE 1 "Filename? " eedit $f1 EDIT MYFILE.MAC azex m80 $n1 ZEX M80 MYFILE ppage $f1 PAGE MYFILE.MAC Highlighting Just like the HELP utility can take advantage of the highlighting facility provided in the Z3TCAP, so can MENU. For those ZCPR3 Systems with a properly-installed TCAP, MENU will use the clear screen command to refresh the user's screen and highlighting can be enabled and disabled by embedding ^A (to turn on highlighting) and ^B (to turn off highlighting) into the *.MNU file. It is recommended that when highlighting is turned on, it should be turned off in the same line for consistency sake and appearance. Example: Highlighting # ^AThis is highlighted^B and this is not # will appear with "This is highlighted" in a highlighted mode like this: This is highlighted and this is not Closing Closing Notes As many commands as the printable ASCII character set (without lower-case letters and the MENU command characters) will allow are permitted by MENU. The text, however, for each menu must be able to fit on a screen with the command prompt at the bottom. This means that the text cannot exceed 22 lines. MENU fits in nicely to the ZCPR3 System of programs. The information section on "MENU's Relationship to the ZCPR3 System" explains how MENU and the other ZCPR3 programs work together. The following ASCII characters may NOT be used as commands since they are used elsewhere: <SPACE> # % , . < > * <DEL> <Any Char Less than Space> :M MENU Programming Command Summary Each MENU command occupies only one line, and blank lines in the command group are not permitted. The command line is structured as follows: l[o][command] where: l is the single character used to invoke the command note that it may be upper- or lower-case o is an opening option, which is one of: :nn -- go to Menu nn ! -- have MENU wait when the command is finished command is an optional ZCPR3 command; note that if the option is ":nn", then a command here makes no sense The MENU commands are: Command Function :nn Goto Menu nn, where the first menu is Menu 1 ! Wait after command line is executed before processing the menu "Prompt" Prompt the user for input and accept it The MENU variables are: Variable Expands to $C Current DIR ('Noname' if not defined) $D Current Disk $U Current User $Fn FILENAME.TYP for System File n $Nn FILENAME for System File n $Tn TYP for System File n $$ $ Note: System Files can be defined by the SETFILE command. The Highlighting Embedded Characters are: ^A Turn ON Highlighting ^B Turn OFF Highlighting Note: It is recommended that if highlighting is turned on, it should be turned off in the same line. The following ASCII characters may NOT be used as commands since they are used elsewhere: <SPACE> # % , . < > * <DEL> <Any Char Less than Space> :Z MENU's Relationship to the ZCPR3 System MENU, like most of the ZCPR3 utilities, interacts with the system as a whole and cannot be used with systems other than ZCPR3. In particular, MENU requires the ZCPR3 Multiple Command Line Buffer and Shell Stack facilities to be available to it and cannot run without them. MENU invokes command lines via the Command Line Buffer and returns to itself thru the Shell Stack. It also uses the ZCPR3 System Files for some of its variables and the Z3TCAP facility for its screen manipulation (highlighting). MENU is installed by Z3INS. Also, CD (Change Directory) and STARTUP (or, ST for CD) can come into play with MENU. When CD logs into to new directory, it looks for the file ST.COM and executes it if there is one. ST is simply STARTUP renamed, and STARTUP will load the Multiple Command Line Buffer with a command line and then terminate. From the point of view of MENU, the command loaded by ST could be MENU. The effect of this is to automatically enter MENU when the user employs CD to enter a given directory. Hence, by using CD, a user can enter a directory and suddenly find himself in a menu instead of at the ZCPR3 command level. This is good for applications where a directory is set aside for a specific purpose and only certain operations are to be performed in it, such as cataloging disks or handling accounts. Now that MENU is running for the directory, a MENU command could be another CD to another directory. Or it could simply be a DU: form. Example: #dp A - Enter ZCPR Directory B - Enter A0: # acd zcpr: ba0: # Here, if A is issued, then CD will move into ZCPR: and execute ST.COM if there is one there. If B is issued, the user is logged into A0:. MENU is the next command in both cases (command lines are "CD ZCPR;MENU" and "A0:;MENU"), so MENU automatically reinvokes and looks for MENU.MNU. If it finds it, we are in another MENU system, and, if it doesn't, we are back to ZCPR3 command level. Under the A option, if CD finds ST.COM, ST will execute its function and, unless this function pops the Shell Stack (SHPOP command), MENU will reinvoke after it is complete. Under the B option, we will run MENU next and simply exit if a MENU.MNU file is not found. :E MENU Error Messages In order to make MENU as small as possible, the error messages have been reduced to a minimum. MENU provides a minimum indication that something is wrong and aborts. The program MENUCK is designed to tell you more specifically what is wrong. MENUCK is a *.MNU Syntax Checker, and it looks for all sorts of error conditions that can occur in a *.MNU file. MENU provides the following minimal error messages: Message Meaning No Shell Stack Shell Stack Not Available No Command Line Command Line Buffer Not Avail Shell Stack Full Shell Stack is Full Shell Stack Entry Size Shell Stack Entries are too short for MENU cmd line File x.typ Not Found Menu File Not Found TPA Full Memory is Full <Bell> User Command is in Error Password Error Invalid Password Given Structure Error *.MNU File Structure Error :2 Command MENUCK 1.3 Syntax MENUCK dir:ufn <-- default file type is MNU Function MENUCK is used to check the syntax of a *.MNU file for the ZCPR3 Menu Shell, MENU. MENU is optimized for size and speed, and, in keeping it small, built-in diagnostics were reduced to the minimum. MENUCK is intended to be used to analyze *.MNU files and provide informative diagnostics on any syntactical errors with them. Options None Comments MENUCK checks to see if the size of the *.MNU file is too large for the TPA available to the MENU command. This is an additional check beyond the normal syntax check. MENUCK identifies the location of errors by line number. The first line in the file is line number 1. Selected Error Messages Self-Explanatory. Examples of Use MENUCK MYMENU -- perform check on MYMENU.MNU