The following are the availible topics: ATTRIBUTES CONTROL DEBUG INPUT STRUCTURE SUBSTITUTION SYNTAX SUMMARY (CONTROL ITEMS) Valid control items following a field seperator, "]": ALPHA BLANK NUMBER REPEAT Valid control items following a control item symbol, "%": ALLOW AGAIN ASK ASKS ASK? BATCH BLOCK CALL CHOICE CLEAR CLI CONTINUE DEBUG DELAY DISALLOW END ERASE EXIT FREE GOTO GRAPHIC HOLD IF IFNOT INQUIRY KILL LAST LAST LOCK MAINTAIN FLAGS NO CLEAR OFF ON OVERRIDE FLAGS PASSWORD PRIVILEGE PROCEED ON ERR PROMPT PROTECT QUERY RESET RETURN SET SILENT SLAVE SPLIT STOP ON ERR TEXT TIMEOUT TITLE TOP UNLOCK VERBOSE WAIT WHOLE XSTATUS ZERO ?/HELP All items can be called by the smallest unique character string, such as "TE" for "TEXT", and "G" for "GOTO". 2 STRUCTURE Basic Structure Menu scripts are divivded into three fields: (1) Title and Initialization; (2) Selection and Action; and (3) Prompt. Each field is separated from the others by a "]" as the first character on a new line. In the Title and Initialization field, text is included in the screen buffer. Action and control items are processed prior to outputting the initial screen. The final state of the control flags will be used as the defaults for the Selection and Action field. In the Selection and Action field, text is included in the screen buffer. Any line without control or action item is considered to be a selection text. Selection items are seperated from each other by the presents of control or action items lines. Selection items can have multiple lines. Control flags will effect only the current selection that modified them. In the Prompt field, only text is allowed. 2 SUMMARY Valid Title and Initialization Control Items (Least unique string capitolized) ALlow ASK (insert) text ASKS (default) text ASKS text ASK? text ASK? (filespec) ASK? "text" BAtch BLock CLEar CLI cliname COntinue DEBug DELay n DIsallow ENd EXit Free Graphic command HAlt init HOld IF n IFNot n INquiry Kill last LAst command LOck Maintain No clear OFf ON OVerride PAssword #/name PRIvilege #/name PROCeed on err PROMpt PROTect Query Return SEt n SIlent SLave SPlit STop on err TExt text/"text" TImeout n Unlock Verbose WAit WHole Valid Selection and Action Field Control Items (Least unique string capitolized) AGain ASK (insert) text ASKS (default) text ASKS text ASK? text ASK? (filespec) ASK? "text" BAtch BLock CAll filespec CHoice CLear COntinue Delay n ENd ERase EXit Free Goto filespec HElp text HElp (filespec) HElp "text" HOld IF n IFNot n INquiry No clear PAssword #/name PRIvilege #/name PROceed on err Query RESet RETurn SEt n SIlent SLave STop on err TExt text/"text" TItle text TOp Verbose Wait Xstatus n Zero ? text ? (filespec) ? "text" 2 SYNTAX Syntax Summary A. There are three fields. a Title, a Selection, and a Prompt area which are separated by a "]" as the first character in a line. B. All commands to be passed to the Operating System for execution must be preceeded by a "$". C. All control commands used by the interpreter must be preceeded by a "%". D. Both field separaters must be present, even if the Title or the Prompt fields have no content. E. There must be at least one selection text and control and/or command item in the Selection field 2 CONTROL Control Characters and Items There are five control characters. All but one of the control character's meaning is position dependent. The only character not position dependent is the "\". This character is used as a field delimitter and is treated essentially as an end-of-line or an end-of-record. The other control characters who has meaning only as the first character of a new line are: The "]" is used as a field separtor. (See HELP SCRIPT STRUCTURE) The ";" is used as a comment line indicator. The "%" is used to preceed a control item. The "$" is used to preceed an action item. All items that are not preceeded by a control character are used as menu text. Leading spaces and tabs are NOT counted as characters in the case of defining a Control Character as the first character on a line. Also spaces and tabs immediately following a Control Character are ignored. This allows the use of indentation for clarity in scripts. (An item is defined as a string of characters that is terminated by a delimitter or an end-of-line .) 2 NUMBER ]NUMBER (Default State) A formatting control item that will generate a numeric selection prompt for each succeeding items. Example: Delete a file equals " 1 Delete a file" List a directory equals " 2 List a directory" Type a file equals " 3 Type a file" (Also See ALPHA, REPEAT, and BLANK) 2 ALPHA ]ALPHA A formatting control item that takes the first character of the selection and uses it as the selection prompt, that character is not further used in the output buffer. Example: DDelete a file equals " D Delete a file" LDirectory of files equals " L Directory of files" (Also See NUMBER, REPEAT, and BLANK) 2 REPEAT ]REPEAT A formatting control item that takes the first character of the selection and repeats it as the selection prompt. Example: Delete a file equals " D Delete a file" List a directory equals " L List a directory" (Also See NUMBER, ALPHA, and BLANK) 2 BLANK ]BLANK A formatting control item that displays no character as a selection prompt. Example: Delete a file equals " Delete a file" List a directory equals " List a directory" (Also See NUMBER, ALPHA, and REPEAT) 2 CLEAR %CLEAR (Default State) An action control item flag that will cause the screen to be cleared prior to the execution of the first action item or control item that produces output to the screen. To re-clear the screen during the proccessing of a selection, the flag must be set again within the selection. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag if set at the end of processing.) (Also see NO CLEAR) 2 NO CLEAR %NO CLEAR An action control item flag that will prevents the screen from being cleared prior to the execution of any action or control item. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see CLEAR) 2 STOP ON ERR %STOP ON ERR (Default State) An action control item flag that prevents further execution of a selection if an action item returns an exit status of non-one (one being a success code). This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see PROCEED ON ERR) 2 PROCEED ON ERR %PROCEED ON ERR An action control item flag that allows further execution of a selection no matter what exit status is returned. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see STOP ON ERR) 2 SILENT %SILENT (Default State) An action control item flag that will cause the silent submission of an action item to be executed. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see VERBOSE) 2 VERBOSE %VERBOSE An action control item flag that will cause the action item to be executed to be displayed on the screen prior to its execution. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see SILENT) 2 QUERY %QUERY (Default State) An action control item flag that causes the script interpreter to wait for the completion of an action item before continuing. If an exit status of non-one is returned, and there are additional items in the selection then the screen is held and the user is asked whether to continue with the further execution of the selection. If there were no more items then the interpreter will treat the case as a WAIT. This selection will override the state of the "STOP/PROCEED ON ERR" flag. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see WAIT, CONTINUE, HOLD and BATCH) 2 WAIT %WAIT An action control item flag that causes the script interpreter to wait for the completion of an action item before continuing. If an exit status of non-one is returned, then the screen is held and the user is prompted to enter a to continue. Further execution of the selection is determined by the state of the "STOP/PROCEED ON ERR" flag. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see QUERY, CONTINUE, HOLD and BATCH) 2 CONTINUE %CONTINUE An action control item flag that causes the script interpreter to wait for the completion of an action item before continuing. The exit status is not examined. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see QUERY, WAIT, HOLD and BATCH) 2 HOLD %HOLD An action control item flag that causes the script interpreter to wait for the completion of an action item, hold the screen and prompt the user to enter a to continue. Further execution of the selection is determine by the state of the "STOP/PROCEED ON ERR" flag. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see QUERY, WAIT, CONTINUE and BATCH) 2 BATCH %BATCH An action control item flag that causes the script interpreter to continue immediately after the requesting of an action item. The the state of "STOP/PROCEED ON ERR" flag is ignored. This flag only effects the selection where it is encountered, subsequent selection revert to the default flag. (This is a valid initialization field control item which will then become the default flag.) (Also see QUERY, WAIT, HOLD and CONTINUE) 2 ASK %ASK (insert) text A prompting control item, that causes the text to be outputted and a "yes or no" response is expected where a lone is defaulted to a "no". If the response is "yes" or "Yes" then the "insert" text is used as the substitution. (Also see ASKS) 2 ASKS %ASKS (default) text A prompting control item, that causes the text to be outputted and a response expected. if the response is a lone , then the "default" text is used as the substitution. The "default" text can have no length. %ASKS text A prompting control item, that causes the text to outputted and a response is required. The response must have length and is used as the substitution. (Also see ASK) 2 PROTECT %PROTECT A control item that allows only privileged users from entering a menu. This item is only valid in the Title and Initailization Field. 2 CLI %CLI cliname An action control item that tells the script interpreter to which CLI to pass the command. The default state of interpreter is that of terminal. (This is a valid Initialization field control item which will then become the default option.) 2 TIMEOUT %TIMEOUT n A control item that enters an input timeout value for the selection and prompt items. The timeout length is equal to 10 seconds times n, where n is a number between 1 and 255. Valid only in the Title and Initialization field. 2 DELAY %DELAY n A control item that causes the interpreter to stop for 'n' seconds, where 'n' is a number between 1 and 999. 2 PROMPT %PROMPT A menu control item that causes the interpreter to prompt for user's selections without cursor pointer. Valid only in the Title and Initalization field. 2 WHOLE %WHOLE (Default State) A menu control item that causes the entire screen to used by the interpreter. Valid only in the Title and Initalization field. (Also see SPLIT) 2 SPLIT %SPLIT A menu control item that causes the interpreter to split the screen on the execution of the selection. Valid only in the Title and Initalization field. (Also see WHOLE) 2 OVERRIDE FLAGS %OVERRIDE FLAGS (Default State) A menu control item that allows a 'child' script to start with all flags in the normal, default states. (Also see MAINTAIN FLAG) 2 MAINTAIN FLAG %MAINTAIN FLAGS A menu control item that forces a 'child' script to adopt the flag states of its parent. (Also see OVERRIDE FLAG) 2 DISALLOW %DISALLOW A menu control item that prevents the execution of all following action items in the the Title and Initialization field on a menu "RETURN". Valid only in the Title and Initialization field. (Also see Allow) 2 ALLOW %ALLOW (Default State) A menu control item that allows the execution of all following action items in the the Title and Initialization field on a menu "RETURN". Valid only in the Title and Initialization field. (Also see DISALLOW) 2 HALT INIT %HALT INITIALIZATION ON RETURN A menu control item that halts the execution of the initialization sequnce on a "RETURN". Valid only in the Title and Initialization field. (Also see ALLOW AND DISALLOW) 2 SLAVE %SLAVE A control item that slaves the terminal. (Also see FREE) 2 FREE %FREE A control item that un-slaves the terminal. (Also see SLAVE) 2 LOCK %LOCK A control item that disables the user command submit (the input "!" option), the script goto (the input "@" option), the script reset (the input "PF3" option), and the script exit (the input "PF4" option) inputs. Valid only in the Title and Initialization field. (Also see UNLOCK) 2 UNLOCK %UNLOCK (Default State) A control item that turns off the "LOCK" control function. Valid only in the Title and Initialization field. (Also see LOCK) 2 OFF %OFF A control item that forces the terminal to be logged off when the script interpretor exits. Valid only in the Title and Initialization field. (Also see ON) 2 ON %ON (Default) A control item that turns off the "OFF" control function. Valid only in the Title and Initialization field. (Also see OFF) 2 ? %? text A help control item that causes the interpreter to request the Help Process with the text appended as a topic descriptor. The following control states are used for the Help request: (1) PROCEED ON ERR, (2) HOLD on RSX or WAIT on VMS, and (3) the CLEAR/NO CLEAR flag is examined. %? (filespec) A help control item that causes the interpreter to request the Type Process with the filespec appended. The following control states are used for the Type request: (1) PROCEED ON ERR, (2) HOLD, and (3) the CLEAR/NO CLEAR flag is examined. %? "text" A help control item that causes the interpreter to write the text to the user The following control states are used: (1) HOLD, and (2) NO CLEAR. (There is no process requested.) (Also see ASK?) 2 ASK? %ASK? text or (filespec) or "text" A help contorl item for the prompt item that must be coupled directly following the prompt item in the script. The source of the help is the same as the normal help control items; see the above three items. (Also see ?) 2 DEBUG %DEBUG A control item that will cause the interpreter to display the current state of all important flags between the execution of all items. It is also causes the interpreter to act as though the verbose flag was set. This item is only valid in the Title and Initialization Field. 2 TEXT %TEXT text/"text" Outputs the text to the user. Text strings can be surrounded double quotes. To pass a null string or a linefeed to the user, you must use the quotes as in (%TEXT ""). 2 TITLE %TITLE text A prompting control item, valid only when not in split screen mode, that clears the screen and output the text to the user on the top line of the screen. It then set the scrolling margins so that the top title line is preserved. Valid only in the Selection and Action Field. (Also see TOP and CHOICE) 2 TOP %TOP A prompting control item, valid only when not in split screen mode, that clears the screen, homes the cursor and sets the scrolling margins so that the next outputted text will be preserved. This is designed to work with the verbose mode, to allow the spawned command to be saved on the screen. Valid only in the Selection and Action field. (Also see TITLE and CHOICE) 2 CHOICE %CHOICE A prompting control item, valid only when not in split screen mode, that will clear the screen, homes the cursor, displays the text of the selection from the menu, (first line only), and sets the scrolling margins so that the text will be preserved. Valid only in the Selection and Action field. (Also see TOP and TITLE) 2 INQUIRY %INQUIRY Outputs text "Do you wish to halt this selection? ", to the user. A "YES" response will stop the processing of the selection. 2 AGAIN %AGAIN Outputs text "Do you wish to repeat this selection? ", to the user. A "YES" response will restart the processing of the selection. Flags will be reset to their default state. Valid only in the Selection and Action field. 2 BLOCK %BLOCK Outputs the text "Please enter to continue: " to the user and wait for input. 2 ERASE %ERASE If in split screen, then the cursor is returned to the line below the menu output, then the screen is cleared below it. If no in split screen, then it is treated as a screen reset. Valid only in the Selection and Action field. 2 RESET SCREEN %RESET SCREEN Clears all screen scroll control, homes the cursor and clears the screen. Valid only in the Selection and Action field. 2 GOTO %GOTO menuscript filespec A control item that closes execution of the present script and opens the file listed for interpretation and execution. Valid only in the Selection and Action field. 2 CALL %CALL menuscript filespec A control item that closes execution of the present script and opens the file listed for interpretation and execution. The present script filename is saved on a stack for later return. The Call does not save any further context than the filename and upon Return execution starts at the beginning except for Initilization Password processing. Valid only in the Selection and Action field. (Also see RETURN) 2 RETURN %RETURN A control item that closes execution of the present script and attempts to remove a filename from its stack. If there is no further names on the stack, then the return is treated as an Exit. (Also see CALL) 2 EXIT %EXIT A control item that closes execution of the present script and causes the process to exit. 2 XSTATUS %XSTATUS n A control item that closes execution of the script and causes the process to exit with the exit status word equal to the number "n". Valid only in the Selection and Action field and only when the LOGOFF flag is not set. (See SCRIPT OFF) 2 PASSWORD %PASSWORD password name A control item that causes the password process to be invoked with the name given. When this item occurs within the Title and Initialization field it controls entry into the entire menu screen, when this item occurs within a Selection and Action field, it controls the further processing of that selection. (Also see PRIVILEGE) 2 PRIVILEGE %PRIVILEGE password name A control item that causes the password process to be invoked with the name given. That process returns a 15 element mask that is used in determining the results of the "IF" item. (Also see PASSWORD, and IF and IFNOT) 2 SET %SET n A control item loads "n" into the privilege mask. The low order privilege user bit is not effected. SET 0 or SET 1 sets or clears an additional logic flag. (Also see PASSWORD, PRIVILEGE, and IF and IFNOT) 2 GRAPHIC %GRAPHIC command string A control item that submits the "command string" to be executed after each menu screen is outputted and before any input is accepted. Item is designed to allow the use of the DECUS VTM or VTN screen format output program. 2 LAST %LAST command string The command string is executed just prior to the process exiting. The string is NOT executed at script changes and has no effect on future scripts. Valid only in the Title and Initialization field (See SCRIPT KILL LAST) 2 KILL LAST %KILL LAST Cancels the effects of the LAST command. (See SCRIPT LAST) 2 IF %IF n A control item that matches the privilege mask with the number n (1 to 16) to determine whether the next item of the selection should be executed. If the match fails then a message is outputted, if in verbose mode, and the following item of the selection is skipped. The IF 0 command tests the additional logic flag. (Also see PRIVILEGE and SET) 2 IFNOT %IFNOT n A control item that matches the reverse of the privilege mask with the number n (1 to 16) to determine whether the next item of the selection should be executed. If the match fails then a message is outputted, if in verbose mode, and the following item of the selection is skipped. The IFNOT 0 command tests the additional logic flag. (Also see PRIVILEGE and SET) 2 END %END A control item that stops the execution of a selection. Used in conjuction the "IF" and "IFNOT" control items to control the flow of a selection. 2 ZERO %ZERO A control item that closes the execution of the present script and opens the initial script entered by the user. The nesting level is then set to 1. Valid only in the Selection and Action Field. 2 SUBSTITUTION Substitution Substitution is handled on two levels, the first is based on strings passed by the command line and replaces the sequence "\\n" where n is a number from 1 to 8. This sequence can occur anywhere in the script. The second level is local to each selection with the strings aquired by the ASK and ASKS items of that selection. These strings are cleared before each selection. The sequence that would be replaced is "##n" where n is a number from 1 to 4. In both cases the order in which the string is aquired is related to the number in the sequence. 2 INPUT Valid cursor control inputs are: (1) arrow keys, (2) tab and backspace, (3) space and "0". Selection with the cursor is done by a . Selection of help with the cursor is done with a "?". All other characters are accepted as the beginning of a string input selection. Strings terminated with a "" are processed as a selection request, Strings terminated with a "?" are processed as a help request. If the first character of the string is a "!" then the string is not treated as a request. The following string is submitted as an Action item with the following control states: (1) CLEAR, (2) PROCEED ON ERR, and (3) WAIT. If the first character is a "@" then the remainder of the string is used as a filespec for a "GOTO" action. If the first character is a "?" then the rest of the string is treated as an arguement to HELP. A lone "?" or "HELP"/"help" will get menu input help. Function key also have meaning: PF1 is a screen reset; PF2 is a help request; PF3 is a process reset that will return to the first script entered by the process; and PF4 is an Exit request. 2 DEBUG Debug Output When the interpreter is in debug mode, (either by the control item "DEBUG" or by the inclusion of a "D" in the command invocation (SCRIPTDEBUG etc.)) then prior to the execution of each control or action item, it will output the status of 16 important control flags and words. The output appears like this: CLR n SIL n FOR n SPN n WHO n LOG n LCK n CUR n CLI n ALL n STP n OVR n LEV n FNC n SEL n LEN n PRVMSK n where: CLR = The status of the CLEAR Flag, which is set by the control item "CLEAR" and reset by "NO CLEAR". SIL = The status of the SILENT Flag, which is set by the control item "SILENT" and reset by "VERBOSE". FOR = The status of the screen format word, which is set by the first field separtor item; 1 = "NUMBER", 2 = "ALPHA", 3 = "BATCH", and 4 = "REPEAT". SPN = The status of the action item control word, which can have the following values: 1 = QUERY, 2 = WAIT, 3 = HOLD, 4 = BATCH, and 5 = CONTINUE. WHO = The status of the WHOLE Flag, which is set by the control item "WHOLE" and reset by "SPLIT". LOG = The status of the LOGOUT Flag, which is set by the control item "OFF" and reset by "ON". LCK = The status of the LOCK Flag, which is set by the control item "LOCK" and reset by "UNLOCK". CUR = The status of the CURSOR Flag, which is set by default and reset by the "PROMPT" control item. CLI = The status of the CLIMOD Flag, which is set when a "CLI" control item is successfully executed. If this flag is set, it forces the interpreter to reset the terminal to its original CLI when it exits. ALL = The status of the ALLOW Flag, which is set by the control item "ALLOW" and reset by "DISALLOW". STP = The status of the STOP ON ERR Flag, which is set by the control item "STOP ON ERR" and reset by "PROCEED ON ERR". OVR = The status of the OVERRIDE Flag, which is set by the control item "OVERRIDE" and reset by "MAINTAIN". LEV = The status of the LEVEL control word which shows the nesting level of the present script. Levels are decended by the "CALL" control item and ascended by the "RETURN". FUNC = The control item/function about to be executed. See the table below for its meaning: 1 ACTION 2 HELP/? 3 GOTO 4 QUERY 5 WAIT 6 HOLD 7 CLEAR 8 NO CLEAR 9 STOP ON ERR 10 PROCD ON ERR 11 SILENT 12 VERBOSE 13 CALL 14 RETURN 15 ASK 16 ASKS 17 BATCH 18 TEXT 19 INQUIRY 20 EXIT 21 PASSWORD 22 WHOLE 23 SPLIT 24 CLI 25 AGAIN 26 CONTINUE 27 BLOCK 28 PROMPT 29 DISALLOW 30 ALLOW 31 SLAVE 32 FREE 33 TIMEOUT 34 PRIVILEGE 35 IF 36 ASK? 37 TITLE 38 TOP 39 CHOICE 40 LOCK 41 UNLOCK 42 ON 43 OFF 44 ERASE 45 RESET 46 MAINTAIN 47 OVERRIDE 48 DELAY 49 IFNOT 50 XSTATUS 51 ZERO 52 END 53 SET 54 HALT INIT 55 KILL LAST SEL = The number of the selection chosen between 1 and 22 with 0 being the initialization process. Alpha input is converted to a numeric equal to its equivilent if the "NUMBER" screen format had been chosen. LEN = The length, if any, of the item/function's object string, such as filename for the "GOTO" item or the number of the "TIMEOUT". Items such as "HOLD" or "CLEAR" have no object strings. PRVMSK = The state of the Privilege Mask word, which is really a sixteen element bit mask. The high order fifteen bits are returned by the "PRIVILEGE" item, and the lowest order bit (the 1 bit) is set or cleared by whether the user is privileged (1) or not (0). When evaluating the results, remember, that the output is prior to the acting on the function in the "FNC n" field, therefore, whatever flags/control words are modified by that function/item will not have taken place. 2 ATTRIBUTES Screen Attribute Control Macros There are a number of attributes that can be manipulated by a set of special commands. These controls are valid in a text field that is to be displayed on the menu, not in the text field of any control item. The syntax of these special commands is a "!" followed immediately by the control word which must be terminated by a space or tab. (The word can be shorten to its first character.) When encountered, the "!", the string and the space or tab are replaced by the appropriate escape sequence. Attributes are only valid on the line where they are found. The attributes that can be controlled are: !Bold Bold Characters !Flash Flashing Characters !Underline Underline Characters !Reverse Reverse Vidoe !Normal Cancels above attributes !Wide Double Wide Characters !Tall Doulbe Tall Characters (Valid only in Title field) !Height Double Wide and Tall Characters (Valid only in Title field) !Ascii Normal/Ascii Character Set !Graphic Graphic Character Set !Special Special Graphic Character Set