SCRIPT LANGUAGE REFERENCE MANUAL Copyright Warren Falls. 1986, 1987. I. TABLE OF CONTENTS Topics: Page Introduction 1 1. Basic Structure 2 2. Control Characters and Items 4 2A. Formatting alpha blank double number repeat unformatted/numeric unformatted/character unformatted/two_characters 6 2B. Action Control Flags clear no_clear bottom stop_on_err proceed_on_err silent verbose 7 query wait continue hold batch error 8 whole split isolate unformatted_screen assign 9 2C. Prompting ask askl asks string 10 2D. Program and System Management Control timeout prompt override maintain lock unlock slave free on off last kill_last cli 11 2E. Help ?/help ask? debug 12 2F. Interactive and Screen Control text clock block delay printer title top choice inquiry again/nagain 13 show_filename erase-screen reset_screen graphic date hardcopy_prompt output width 14 2G. Inter-script goto call return zero recalulate exit xstatus chain allow disallow halt_init_on_return 15 filename save_context sub_routine 16 2H. Privilege and Logic Control protect password privilege set and or if ifnot end loop 17 2I. VMS Logical and Symbolic Commands logical symbol dlogical dsymbol 18 2J. File and Event Flag Control (VMS only) open append write log close mailbox event_flag 19 3. Error Handling 20 4. Substituion 20 II. Topics: Page 5. User Input 21 6. Command Line Switches 22 7. Examples of Scripts and Styles 23 8. Summary of Control Items 24 9. Debug Output 25 10. Screen Attribute Control Macros 27 11. Terminal Support 28 12. Script Filename Conventions 28 13. Item Masking 28 14. VMS Symbol and Logical Usages 29 15. List Processing and Commands 29 16. VMS Installation 31 17. VMS Mailboxes and Event Flags 31 1. Introduction Script is a basic application and system management tool, much in the same way that a DCL proceedure in VMS is a tool. It is used to generate and run menus and is oriented toward CRT's but also can run on hardcopy terminals. It is an easy to use, friendly, fast, understandable interface to processes and applications. Script should be considered as a necesary extension of DCL (VMS) or Indirect (RSX). The major features of Script are: 1. Nested menus. 2. Intelligent screen and cursor control. 3. Programable, flexible help for options and queries. 4. Strong system management control of user enviroment. 5. Multiple format options. 6. Passwording, privilege checking and option access masking. 7. Programable, automatic slave printer control. 8. Idle terminal timeout. 9. Basic logic, query and command substitution capibilities. 10. Log file, and symbol and logical control. (VMS) 2. 1. 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. The separator between the Title and the Selection fields can also be followed by a Selection field format statement. Each line of the script can also be divided into three categories: (1) Output Text; (2) Action Items; and (3) Control Items. Example: ] Title Text %control $action %control ](option) Selection Text %control $action Selection Text %control $action %control $action Selection Text $action ] Prompt Text: Title and Initialization Field The first record of the file must be a lone "]". This record serves both as a flag to insure that the file is really a script text, and will prevent the script from accidentally being executed as a DCL command proceedure in VMS. 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. 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 presence of control or action items lines. Selection items may have multiple lines. Control flags will effect only the current selection that modified them. Control and Action items belong to the selection item that preceeds them. Prompt Field In the Prompt field, only text is allowed. 3. Syntax Considerations These are a few rules that should be followed when writing a menu script: 1. Starting the Selection and Action Field with a Control or Action item, or ending it with a text line are both illegal. 2. Any Control or Action item in the Prompt Field is also illegal. 3. There is a limit of 22 selections in the Selection and Action Field. 4. The "CLEAR" flag is cleared whenever any Action item or a Control item that produces output is executed; therefore it must be set after any of those items if you wish to have the screen cleared again during the selection, or to have it set as the default flag at the end of the initialzation process. 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 Script as a Screen Control Language Script can be used as a screen control language where only the initialization field is used. 4. 2. Control Characters and Items In addition to the "]", there are five more control characters. Like the "]", all but one of the control character's meaning is position dependent. There is a comment line control character, ";", which must preceed all other, including spaces and tabs. This allows menu scripts to contain comments. 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. Three control characters who have meaning only as the first character of a new line (like the "]") are the "%", "~", and the "$". The "%" is used to preceed a control item, the "~" is used to proceed an item list mask, and 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 . Items may contain both uppercase and lowercase characters. Summary of Control Characters: ] As first character, seperates fields ; As first character, comment line indicator ~ As first character, item mask symbol $ As first character, action item symbol % As first character, control item symbol \ Item delimitter 5. Valid control options following the field seperator, "]", between the Title and the Selection areas are: ALPHA BLANK CHARACTER UNFORMATTED DOUBLE NUMBER REPEAT TWO CHARACTERS UNFORMATTED UNFORMATTED NUMERIC These items control the formatting of the selection area and the kind of prompt that is generated for the user. Valid control items following a control item symbol, "%", are: AGAIN/NAGAIN ALLOW AND APPEND ASK ASKL ASKS ASK? ASSIGN BATCH BOTTOM BLOCK CALL CHAIN CHOICE CLEAR CLI CLOCK CLOSE CONTINUE DATE DEBUG DELAY DISALLOW DLOGICAL DSYMBOL END ERASE ERROR EVENT_FLAG EXIT FILENAME FREE GOTO GRAPHIC HARDCOPY_PROMPT HOLD IF IFNOT INQUIRY ISOLATE KILL_LAST LAST LOCK LOG LOGICAL LOOP MAILBOX MAINTAIN_FLAGS NO_CLEAR OFF OPEN ON OR OVERRIDE_FLAGS OUTPUT PASSWORD PRINTER PRIVILEGE PROCEED_ON_ERR PROMPT PROTECT QUERY RECALULATE RESET RETURN SAVE_CONTEXT SET SHOW_FILENAME SILENT SLAVE SPLIT STOP_ON_ERR STRING SUB_ROUTINE SYMBOL TEXT TIMEOUT TITLE TOP UNFORMAT_SCREEN UNLOCK VERBOSE WAIT WHOLE WIDTH WRITE XSTATUS ZERO ?/HELP These items fall into the following general categories: action control flags, prompt control, program and system management control, help control, interactive control, inter-script control and privilege control. All items can be called by the smallest unique character string, such as "TE" for "TEXT", and "G" for "GOTO". 6. 2A. Formatting These six control options select which of the formats that the interpreter will use in the generating of the Selection and Action Field. These control words are only valid immediately following the first field separtor. If any of the formatted options are proceeded by a "2", then the selections are generated in a double column format. If any unformatted option is requested by lowercase instead of uppercase, then there are no carriage return and or linefeeds added by script to the text. Also screen control macros are not automatically ended at the end of record. Screen control, therefore must be explicit, using the screen control macros. ]NUMBER (Default State) A formatting control item that will generate a numeric selection prompt for each succeeding items. ]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. ]REPEAT A formatting control item that takes the first character of the selection and repeats it as the selection prompt. ]BLANK A formatting control item that displays no characters as a selection prompt. ]UNFORMATTED_NUMERIC/unformatted_numeric A formatting control item that does not format selection items. Selections have automantic numeric matching response generated for them. ]CHARACTER_UNFORMATTED/character_unformatted A formatting control item that does not format selection items. Selections take the first character in the line and uses it as the matching response, that character is not used in the selection display. ]DOUBLE (VMS only) A formatting control item that takes the first two characters of the selection and uses them as the selection prompt, those characters are not further used in the output buffer. ]TWO_CHARACTERS_UNFORMATTED/two_characters_unformatted (VMS only) A formatting control item that does not format selection items. Selections take the first two characters in the line and uses them as the matching response, those character are not used in the selection display. 7. 2B. Action Control Flag This set of control items dictates what actions the interpreter will take when executing action statements. %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 selections 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.) %NO_CLEAR An action control item flag that will prevents the screen from being cleared. 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.) %BOTTOM An action control item, used with the "NO CLEAR". If the clear flag is reset, then the cursor will be set to the bottom of the screen, but the screen will not be cleared. The item must be reassertted for each use. %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.) %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.) %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.) %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.) 8. %QUERY 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.) %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.) %CONTINUE (Default State) 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.) %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 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.) %BATCH An action control item flag that causes the script interpreter to continue immediately after the requesting of an action item. The state of the "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.) %ERROR 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. 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.) 9. %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. %SPLIT A menu control item that causes the interpreter to split the screen on the execution of a selection. Valid only in the Title and Initalization field. %ISOLATE (VMS only) An action control item that cause the next action item to be spawned without passing logical_names or symbols. This cuts the spawn time in half but isolates the spawned process from much of the user's local enviroment. This flag is reset by each action request and must be reasserted when desired. %UNFORMATTED_SCREEN An initialization flag that prevents the screen from being cleared in between selections. %ASSIGN device/filespec An action control item that causes 'device/filespec' to be used on the next action item as its SYS$OUTPUT. The effect is reset by each action request. 10. 2C. Prompting Items These control items are used to interact with the user in obtaining action item substitution strings. (See Substitution section.) %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. %ASKL 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 addtional logic flag is set, other- wise, the flag is cleared. %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. %STRING (text) This control item will cause 'text' to be used as a substitution string. It is meant to be used with the ASKL and IF/IFNOT commands. 11. 2D. Program and System Management Control These control items effect how the script interpreter reacts after a selection is made and a set of system management tools. %TIMEOUT n A control item that enters an input timeout value for the selection and/or prompt items. The timeout length is equal to n times 10 seconds, where n is a number between 1 and 255, in RSX, and n times 1 second, where n is a number between 1 and 32000 in VMS. %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. %OVERRIDE_FLAGS (Default State) A menu control item that allows a 'child' script to start with all flags in the normal, default states. %MAINTAIN_FLAGS A menu control item that forces a 'child' script to adopt the flag states of its parent. %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. %UNLOCK (Default State) A control item that turns off the "LOCK" control function. %SLAVE A control item that slaves the terminal. (Disallows ^Y in VMS) %FREE A control item that un-slaves the terminal. (Allows ^Y in VMS) %OFF A control item that forces the terminal to be logged off when the script interpreter exits. %ON (Default) A control item that turns off the "OFF" control function. %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 %KILL_LAST Cancels the effects of the LAST command. %CLI cliname (Only valid in RSX, treated as a NOP in VMS) 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 item is only valid in the Title and Initialization Field. 12. 2E. Help Control This set of control items deals with what help is availible for each selection, and the prompting items, if any. %?/HELP 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. %?/HELP (filespec) A help control item that causes the interpreter to type 'filespec'. The screen will be held every 22 lines in non-hardcopy terminals. %?/HELP "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.) %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. %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. 13. 2F. Interactive and Screen Control These control items deal with all user input and output that do not deal with substitution or help. %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 ""). %CLOCK Outputs the current date and time to user. %BLOCK Outputs the text "Please enter to continue: " to the user and wait for input. %DELAY n A control item that causes the interpreter to stop for 'n' seconds, where 'n' is a number between 1 and 32000. %PRINTER option Will output one of five escape sequences, based on the option: turn the printer port on (ON), off (OFF), print the screen (SCREEN), turn the printer port only on (ENABLE), or turn off the printer only (DISABLE). Four additional options will control two more options. (ALL and PROMPT, which enables) and (NONE, which disables) will cause all output other than the menus themselves to be sent to the printer port. PROMPT will let the selection be printed also. (SLAVE, which enables) and (RELEASE, which disables) will enable the printer port only for the duration of an action ($) item. %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. %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. %CHOICE A prompting control item, valid only when not in split screen mode, that will clear the screen, homes the cursor, display 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. %INQUIRY Outputs text "Do you wish to halt this selection? ", to the user. A "YES" response will stop the processing of the selection. %AGAIN/%NAGAIN Outputs text "Do you wish to repeat this selection? ", to the user. A "YES" response will restart the processing of the selection. In the NAGAIN option, a timeout is treated as a "YES" response. Flags will be reset to their default state. Valid only in the Selection and Action field. 14. %OUTPUT filename Outputs filename to screen. %SHOW_SCRIPT_FILENAME Outputs the filename of the present menu script. %ERASE_SCREEN 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. %RESET_SCREEN Clears all screen scroll control, homes the cursor and clears the screen. Valid only in the Selection and Action field. %GRAPHIC command string The command string is executed immediately after every output of the menu screen, but prior to the acceptance of any input. The item is designed to work with the DECUS VTM or the modified VTN screen output formatting tasks. Valid only in the Title and Initialization field. (VTM/VTN are RSX products) %DATE (VMS only) Will cause the time and date to be placed at the top of the screen. This function is mutually exclusive of the "Graphic" function, and is in valid only on ANSI terminals. The time will be updated once a minute. Valid only in the Title and Initialization field. %HARDCOPY_PROMPT "prompt" Will use "prompt" in place of 'SCR>' on hardcopy menu returns. %WIDTH n Will cause the terminal width to change to 'n', if 'n' is 80 or 132 then an escape sequence to set the terminal in that mode is executed. 15. 2G. Inter-Script and Privilege Control These control items control what other scripts are presented and both script and selection password and privilege masks. %GOTO menuscript filespec A control item that closes execution of the present script and opens the file listed for interpretation and execution. %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 the Action field. %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. %ZERO A control item that closes execution of the present script and opens the initial script entered by the user and sets the script nesting level to 1. Valid only in the Selection and the Action field. %RECALULATE A control item that closes execution of the present script and reopens it. This allows redined symbols to be reflected by the script. VMS only. %EXIT A control item that closes execution of the present script and causes the process to exit. %XSTATUS n A control item that closes execution of the script and causes the process to exit with an exit status of the number "n". Valid only in the Selection and Action field, and only if the LOGOFF flag is not set. %CHAIN command_string A control item that closes execution of the script and causes the process to chain to "command_string". "Command_string" can contain local substitutions. %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. %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. %HALT_INITIALIZATION_ON_RETURN A menu control item that halts the execution of the initialization sequence on a "RETURN". Valid only in the Title and Initialization field. 16. %FILENAME (VMS only) A control item that causes the present script file filename to be placed in the symbol "SCR$FILE". %SAVE_CONTEXT (VMS only) A control item that causes the present nesting level and return filenames to be saved in the symbol "SCR$CONTEXT". %SUB_ROUTINE filespec Identical to the CALL item with the addition of saving the function context with the script name. Sub_routines can not be nested and is not valid in the Title and Initialization field. 17. 2H. Privilege and Logic Control %PROTECT A control item that allows only privileged users (OPER/SYS in VMS) from entering a menu when used in the Title and Initialization Field and from continuing a selection when used in the Selection and Action Field. %PASSWORD password name %PASSWORD "password" A control item that causes the password process to be invoked with the name given or to use the given parameter as the password. If the "password name" option is used, then Script will attempt to access a file defined by the logical 'SCR$PASSWORD'. The content of that file is maintained by the PASSWORD utility program. NOTE: the password option, at present, offers little security from ambitious users. 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. %PRIVILEGE password name (RSX) %PRIVILEGE (VMS) 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. In VMS, no process is invoked, the symbol "PRV$RESULT", is read instead and the 15 element mask is gain from it. Also the option mask symbol "SCR$MASK" is re-read. %SET n A control item that will set the privilege mask with the number n. The low- order, privilege user bit is not effected. The SET 1 and SET 0 commands sets or clears, an additional logic flag, not in the privilege mask. This flag can also be set by a SET LOGICAL command and cleared by a SET NOT_LOGICAL. %AND n A control item that will "AND" the privilege mask with the number n. The low- order, privilege user bit is not effected. The SET 1 and SET 0 commands sets or clears, an additional logic flag, not in the privilege mask. %OR n A control item that will "OR" the privilege mask with the number n. The low- order, privilege user bit is not effected. The SET 1 and SET 0 commands sets or clears, an additional logic flag, not in the privilege mask. %IF n {THEN %/$ item} ('THEN' FORM IS OPTIONAL) 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. IF 0 or IF L(OGICAL) command tests the additional logic flag. IF ERR command tests the execute status word, IF CRT tests whether the terminal is an ANSI Scope, and IF P(RIVILEGE) test privilege. %IFNOT n {THEN %/$ item} ('THEN' FORM IS OPTIONAL) Identical to the IF command except reverse logic. %END A control item that stops the execution of a selection. This item is used with the "IF" and "IFNOT" control items in selection flow control. %LOOP Will restart the processing of a selection. Flags will be reset to their default state. 18. 2I. VMS Logical and Symbolic Commands (VMS only) %LOGICAL (logical_name) string (VMS only) A control item that writes a process logical_name "(logical_name)" with "string". Accepts local substitutions. %SYMBOL (symbol) string (VMS only) A control item that writes global symbol "(symbol)" with "string". Accepts local substitutions. %DLOGICAL logical_name (VMS only) A control item that deletes "logical_name". %DSYMBOL symbol (VMS only) A control item that deletes "symbol". 19. 2J. File and Event Flag Control (VMS only) These control items can create, write and close a sequential file. This function is only implimented for VMS to allow creation of 'vectored' proceedures. Additonal mailboxes can be created, read, written, closed, and deleted. Also common cluster event flags can created, controled, and deleted to aid in inter-process synchronization. %OPEN filename (VMS only) A control item that creates an output file 'filename'. Accepts local substitutions. %APPEND filename (VMS only) A control item that opens for appending file 'filename'. If does not already exists, it creates it. Accepts local substitutions. %WRITE string (VMS only) A control item that writes 'string' to the output file. Accepts local substitutions. %LOG string (VMS only) A control item that writes the time and date, then 'string' to the output file. Accepts local substitutions. %CLOSE (VMS only) A control item that closes the output file. %MAILBOX (option) string (VMS only) A control item that has 11 options, the option keyword is held in 'option': LOCAL_MAILBOX MAILBOX Creates a local (to job) mailbox 'string'. GLOBAL_MAILBOX Creates a global (system-wide) mailbox 'string'. OPEN Opens mailbox 'string', only one mailbox at a time. READ Reads mailbox record into ##M (see Substitution). WRITE Writes mailbox with record 'string'. CLOSE Closes mailbox, no optional string needed. DELETE Deletes mailbox 'string' ERROR Copies ##M into action status word to be checked by IF/IFNOT ERR item. START Create and open mailbox 'MAILBOX', start the DCL sub-process '@SYS$SCRIPT:SCRIPT.MAIL_BOX' which will pass '$' action items via the mailbox to be executed (a much faster method than the SPAWN.) BACKGROUND Create and open mailbox 'MAILBOX', and will pass '$' action items via the mailbox to be executed (a much faster method than the SPAWN.) FINISH Close 'MAILBOX' which causes the subprocess to exit. All reads and writes are synchronous, in other words, they will wait until completed before proceeding. %EVENT_FLAG (option) flag/name (VMS only) A control item that has 5 options, the option keyword is held in 'option': ATTACH Attachs to common flag cluster 'name', (only 1 allowed). SET Sets flag 'flag' (1-32). CLEAR Clearss flag 'flag' (1-32). WAIT Waits for flag 'flag' (1-32) to set. DETACH Detaches common flag cluster 'name' The third cluster (numbers 64 to 95) is used, the flag number passed is the offset into that cluster. The attach command must be used before any other command. The cluster, if created by the attach command is a temporary cluster and is valid only for processes with the same UIC. 20. 3. Error Handling Script syntax errors are considered fatal, as are script file processing errors. If this error occurs on the first script, then the process will exit. On subsequent scripts, then the previous script is re-entered. Process errors are handled by control state flags. Selection errors are flagged, and the screen is then re-painted. 4. Substitution Script handles many kinds of substitutions; these can be divided into two categories, substitutions done at the initial processing of a script, and substitution done during the execution of the script. Initialization substitutions sources come from the command line, logicals (VMS), symbols (VMS), list-processing symbols or files (VMS), and the user device name. These may occur anywhere in the script file since they are operated upon before any processing of the script takes place. To force reprocessing of a script for updated substitution use the %RECALC command (see command for details) Command line substitution (see Command Line for syntax) replaces the sequence "\\n" where n is a number from 1 to 6. The numeric sequence based on the order of the substitutions on the command line. The sequence "\\0" is replaced by the lower two octals of the users' terminal number (RSX) or the first four characters of the user terminal device (VMS). This string is meant to help create discrete filenames for each version of SCRIPT running in a single account. Symbols and logicals will be substituted for if surrounded by "^". No error will occur if the symbol or logical is not found, but the text will be passed unaltered. List Processing uses the sequence "\\*". See the List Processing section for details. Dynamic substitution sources are ASK command inputs, system time/date and Mailbox reads. These are only processed in control (%) and action ($) items at the time of their execution. The sequence "##n", where n is a number from 1 to 4 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 order in which the string is aquired is related to the number in the sequence. The sequence "##0" is substituted by a 17 character time and date string (dd-mmm-yyyy hh:mm); "##T" by the 5 character time string (HH:MM); "##D" by the 11 character date string (dd-mmm-yyyy); "##t" by the 4 character time string (hhmm); and "##d" by the 11 character date string (dd_mmm_yyyy). The last two sequences to be used in filename creation (such as for log files). The sequence "##M" uses the last record read from the mailbox (see %MAILBOX). 21. 5. User 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 "!" (RSX) or a "$" (VMS) 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 of the string is a "@" then the string is treated as a filespec for a "GOTO" like action. If the first character of the string is a "?" then the remainder of the string is used as an argument to HELP. A lone "?" or a string of just "HELP" or "help" will call for an input syntax help screen. 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. The following control characters have meaning: ^Z, ^C, and ^Y are cancel input, exit if allowed; ^W repaints screen; ^T output name of present menu script. User Inputs Summary At the Cursor: Arrow Keys Moves the cursor up or down. Space Moves the cursor down. Tab Moves the cursor down. Zero <0> Moves the cursor down. Backspace Moves the cursor up. Carriage Return Selects option. Question Mark Requests help for option. At the Cursor or the Prompt: Request selection . Requests the top selection. Request help for selection . "HELP" or "help" Request help on Script input. $ Execute as a command. (VMS)* ! Exit with in symbol SCR$COMMAND. (VMS)* ! Execute as a command. (RSX)* @ Change menu script to .* PF1 Repaint screen. PF2 Same as , requests help for selection. PF3 Request return to first menu script.* PF4 Exit Script process.* <^C>, <^Y>, <^Z> Exit Script process.* Executes a RETURN function.* <^W> Repaint screen. <^T> Display filename of current menu script. * Subject to the state of the "Lock" flag, if not allowed, treated as a screen repaint. 22. 6. Command Line Switches In RSX there are no switches defined. In VMS the following switches are defined: /SCREEN_ONLY, /HARDCOPY, /DEBUG, /CONTEXT, /LOCK, /BUILD, /WSIPC, /MAILBOX, /BACKGROUND and /NO_EXECUTE. SCREEN prevents the execution of any proceedures and causes the program to exit after the first successful input with the symbols SCR$RETURN equal to the 'nth' number of the selection and SCR$HELP set to "YES" or "NO" depending on if help was or was not requested for that selection. HARDCOPY overrides the system parameter regarding whether the terminal is a CRT or a hardcopy device and forces it to be treated as a harcopy device. DEBUG forces set the debug flag to allow debugging of scripts without having to edit in the the DEBUG control function. CONTEXT causes the symbol "SCR$CONTEXT" to be read into the nesting level and return filenames. LOCK causes the lock flag (see the %LOCK function) to be set as the default and the SLAVE function (siable control_C/Y) to be executed. BUILD causes the script file specified to be 'compliled' and written back to a new file of the same name. A 'compiled' script has both positive and negative points. On the positive, it loads faster, initializes faster, uses less cpu time and is more secure in that it can not be editted. The negative side is that initial substitutions from command line or symbols/logicals can not be done dynamically, also support for terminal types is no longer dynamic. A script system can contain both types of scripts, 'compiled' and interpretted. MAILBOX switch causes Script to create and open mailbox 'MAILBOX', spawn a sub-process to execute the @SYS$SCRIPT:SCRIPT.MAIL_BOX, and pass '$' action items via the mailbox to be executed. (See VMS Mailboxes) BACKGROUND switch causes Script to create and open mailbox 'MAILBOX', and pass '$' action items via the mailbox to be executed. (See VMS Mailboxes) WSIPC switch causes script to attempt to simulate a DCL, line by line, upper- case only mode. (Known as ugly-mode by some.) NO_EXECUTE prevents the actual spawning of the commands. A great deal of functionality can be accomplished by the use of substitution into "empty" control and/or action item statements. Example: Title Text % \\1 % whatever The command line could appear as: SCRIPT "CLEAR\%VERBOSE\%WAIT\%TIME 4" filespec This line would set the clear flag, verbose flag, the wait mode of execution, and a timeout of 40 (RSX)/ 4 (VMS) seconds. If no switches were required then the below would be used: SCRIPT "" filespec 23. 7. Examples of Scripts A. ] File Services ] Return to the Main Menu %RETURN List of Current Directory %HOLD $PIP /BR Type a File %NO CLEAR %ASKS Please enter file: %HOLD %CLEAR $TYPE ##1 Copy a File %NO CLEAR %ASKS File(s) to copy from: %ASKS () Copy to: $COPY ##1 ##2 ] Please enter option: _______________________________________________________________________________ B. ] File Services ] Return to the Main Menu\%RET List of Current Directory\%H\$PIP /BR Type a File\%N\ASKS Please enter file: \%H\%CLE\$TYPE ##1 Copy a File\%N\ASKS Files to copy from: \%ASKS () Copy to: \$COPY ##1 ##2 ] Please enter option: _______________________________________________________________________________ Examples 'A' and 'B', both will generate the identical screens and results, but demonstrate different concepts in script generation. Example 'A' is a clearer functional statement of the script. On the otherhand, example 'B' accurately portrays how the screen will appear. 24. 8. Summary of Control Items Valid Title and Initialization Control Items (Least unique string capitolized) ALlow ANd n APpend filename ASK (insrt) text ASKL text ASKS (dflt) text ASKS text ASK? text ASK? (filespec) ASK? "text" ASSign filespec BAtch BLock BOttom Call filename CHain command CLEar CLI cliname CLOCk CLOSe DAte COntinue DEBug DELay n DIsallow DLogical logical DSymbol symbol ENd ERror EVent_flag (o) str EXit FIlename Free GOto filespec GRaphic command HAlt_init HARdcopy "prmpt" HOld IF n/err IFNot n/err INquiry ISolate Kill last LAst command LOCk LOG string LOGIcal (nm) str LOOp MAIL (opt) str MAINtain No_clear OFf ON OPen filename OR n OVerride OUtput filename PAssword #/name PRINter option PRIVilege #/name PROCeed_on_err PROMpt PROTect Query Return SAve_context SEt n SHow_filename SIlent SLave SPlit STOp_on_err STRing (text) SYmbol (sym) str TExt text TImeout n UNFormatted_scn UNLock Verbose WAit WHole WIdth n WRite string Valid Selection and Action Field Control Items (Least unique string capitolized) AGain/NAgain ANd n APpend filename ASK (insrt) text ASKL text ASKS (dflt) text ASKS text ASK? text ASK? (filespec) ASK? "text" ASSign filespec BAtch BLock BOttom CAll filespec CHAin command CHOoice CLEar CLOCk CLOSe COntinue DElay n DLogical logical DSymbol symbol ENd ERase EVent (opt) data EXit FIlesave FRee Goto filespec HElp text HElp (filespec) HElp "text" HOld IF n IFNot n INquiry ISolate LOCk LOG string LOGIcal (n) str LOOp Mailbox (o) str No_clear OFf ON OPen filename OR n PAssword #/name PRINter option PRIVilege #/name OUtput filename PROCeed_on_err PROTect Query RECaluate RESet RETurn SAve_context SEt n SHow_filename SIlent SLave STOp_on_err STRing (text) SUb_ro filespec SYmbol (s) stg TExt text/"text" TIMeout n TITle text TOp Verbose Wait WIdth n WRite string Xstatus n Zero ? text ? (filespec) ? "text" 25. 9. Debug Output (Debug switch is "/DEBUG" in VMS, in RSX it is the inclusion of "D" in the command.) 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: nnnn nnnn nnnn nnnn nnnn nnn FNC nn SEL nn LEN nn PRVMSK nnnnnnnnn BLKMSK nnnnnnnn SPSTAT nnnnnnnn parameter, if any for above function where the top line are the following flags: Clear Flag, which is set by the control item CLEAR and reset by NO CLEAR. Silent Flag, which is set by the control item SILENT and reset by VERBOSE. Screen Format Word, which is set by the first field separtor item; 1 = NUMBER 2 = ALPHA, 3 = BATCH, 4 = REPEAT, 5 = UNFORMATTED NUMERIC, 6 = UNFORMATTED CHARACTER, 7 = DOUBLE, 8 = UNFORMATTED DOUBLE. Action Item Control Word, which can have the following values: 1 = QUERY, 2 = WAIT, 3 = HOLD, 4 = BATCH, 5 = CONTINUE, and 6 = ERROR. Whole Flag, which is set by the control item WHOLE and reset by SPLIT. Logout Flag, which is set by the control item OFF and reset by ON. Lock Flag, which is set by the control item LOCK and reset by UNLOCK. Cursor Flag, which is set by default and reset by the PROMPT control item. Jet Flag, which is set by the ISOLATE control item. Print Flag, which is set by the PRINTER SLAVE and reset by the PRINTER RELEASE control items. Prnter Flag, which is set by the PRINTER ALL and is reset by the PRINTER NONE control item. Prntr Flag, which is set by the PRINTER PROMPT and is reset by the PRINTER NONE control item. Dumb Flag, set if the terminal is a CRT, but does not support ANSI sequences. Dumb and Scope are reset then the terminal is known as a hardcopy device. Scope Flag, set if the terminal is an ANSI CRT. Return Flag, set if executing initialization code as the result of a RETURN. Allow Flag, which is set by the control item ALLOW and reset by DISALLOW. 26. Stop_On_Err Flag, which is set by the control item STOP_ON_ERR and reset by PROCEED_ON_ERR. Override Flag, which is set by the control item OVERRIDE and reset by MAINTAIN. Double Flag, which is set if the double column option is selected. Logic Flag, which is the logical used by ASKL, IF, IFNOT, and SET items. Bottom Flag, which is set by the BOTTOM control item. Init Flag, which is set when executing the initialzation selection. Graphic Flag, which is set by the GRAPHIC (1) or the DATE (2) items. Level Control Word which shows the nesting level of the present script. The second line items are as follows: FNC = 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 56 CHAIN 57 SYMBOL 58 LOGICAL 59 ISOLATE 60 CLOSE 61 OPEN 62 WRITE 63 RECALULATE (57)64 SHOW_FN 65 BOTTOM 66 APPEND 67 PRINTER 68 PROTECT 69 OR 70 AND 71 CLOCK 72 LOOP 73 ASKL 74 ERROR 75 STRING 76 DLOGICAL 77 DSYMBOL 78 SAVE_CONTEXT 79 FILENAME 80 OUTPUT 81 LOG 82 SUB_ROUTINE 83 NAGAIN 84 MAILBOX 85 EVENT_FLAG 86 ASSIGN 87 WIDTH SEL = The number of the selection chosen between 1 and 99 with 0 being the initialization process. LEN = The length, if any, of the item/function's object string. PRVMSK = The state of the Privilege Mask word. BLKMSK = The state of the Blocking Mask. SPSTAT = The state fo the Spawn Return Status Word. 27. 10. Screen Attribute Control Macros There are a number of attributes that can be manipulated by a set of special commands. The syntax of these special commands is a "!" followed immediately by the control string or word which must be terminated by a space or tab. (The string can be shorten to its first character.) When encountered, the "!", the string and the space/tab are replaced by the appropriate escape sequence. Attributes are only valid on the line where they are found. The interpreter will append a sequence to return the attributes to normal, if needed at the end of the line. The attributes that can be controlled are: !nn,nn Moves cursor to location nn,nn. !Bold Bold Characters !Flash Flashing Characters !Underline Underline Characters !Reverse Reverse Video !Normal The above atrributes are cancelled !Wide Double Wide Characters !Tall Double Tall Characters * Top line of Double Tall Characters ** !tall Bottom line of Double Tall Characters ** !High Double Wide/Tall Characters * Top line of Double Wide/Tall ** !high Bottom line of Double Wide/Tall Characters ** !Ascii Normal/Ascii Character Set !Graphic Graphic Character Set !Special Special Graphic Character Set !Zero Homes the cursor *** !Line Erases line from cursor to end !Clear_line Clears entire line of the cursor !Delete_rest Clears screen from cursor down *** !Erase_scrren Clears whole screen *** !mnn,nn Set scrolling margins, top and bottom *** !O Set origin mode *** !o Resets origin mode *** !save_cursor Save the present cursor location !restore_cursor Restore the saved cursor location !< Move cursor left !> Move cursor right !down Move cursor down !up Move cursor up !backspace Do a !cr Do a !linefeed Do a !escape Do a !Xbackgrnd Cause the background of the screen to be white. !xbackgrnd Cause the background of the screen to be dark. !Mann Repeat multiple character 'a', nn times. * Not valid in the Option and Selection text field. ** Alternate meaning in an Action Item, useful only with the "TEXT" command. *** Availble only in in Action Items 28. 11. Terminal Support At present three general categories of terminals are supportted. ANSI CRT's, 'dumb' CRT's and hardcopy Devices. ANSI CRT Will support all features, which include: screen clearing, cursor selection, split screen options (such as CHOICE and SPLIT), and screen attribute macros. The screen is cleared (may not be the entire screen, depending upon the state of the split flag) and the menu is repainted after the execution of each item. DUMB CRT Supports screen clearing only. Item selection is force from the prompt field. The screen is cleared and the menu is repainted after the execution of each item. HARDCOPY DEVICE Support will output the menu, force the selection from the promtp field, and will only reprompt after the execution of an item with "SCR>". Another copy of the menu will be repainted if the user inputs a control W (^W). 12. Script Filename Conventions Script filenames have a default extention of ".SCR", if no other extention is given. Also if a script filename is prefixed by a "$" then the "$" is replaced by the the following: SYS$SCRIPT: (in VMS) or LB0:[1,3] (in RSX). Filenames in RSX have a total limit of 30 characters, including the replaced "$" and added extention, and 50 characters in VMS. 13. Item Masking Items in the Selection and Action field can be masked-out by the use of the "MASK" option. The syntax and rules for this option are as follows: 1. The mask option line must proceed the prompt text of a selection. 2. The selection must follow the normal rules of syntax. 3. The mask option uses the the value contained in the symbol SCR$MASK as the user's mask. 4. The number in the mask option is a bit offset in the range of 1 to 32. The mask number 0 is a privilege bit check (OPER/SYS). 5. The syntax for the mask option line is: ~comment_text number where the comment_text can not contain any spaces or tabs and number is a a decical number between 0 and 32. There should be no space between the '~' and the comment_text. 29. 14. VMS Symbol and Logical Use The following logicals are used by Script: SYS$SCRIPT: Replaces "$" on script filespecs. SCR$PASSWORD: Logical filespec for location of password data file. The following symbols are used as inputs by Script: SCR$MASK Mask to be used in Item Masking (see above). PRV$RESULT Privilege mask used by PRIVILEGE command. The following symbols are outputted by Script: SCR$RETURN The number of the selection chosen in DCL mode. SCR$HELP "YES"/"NO" flag in help was chosen in DCL mode. SCR$COMMAND Holds special escape "!" command line. SCR$FILE Output of FILENAME command, current script filespec SCR$CONTEXT1/4 Output of SAVE_CONTEXT command, key flags and script nesting information. 15. List Processing Script has the ability to process lists supplied either through a file or a symbol. The processing takes place within a repeated segment of script, each repetition using the next element of the list as its substitution parameter. Lists can not be nested, although a single script may have multiple lists. The syntax of the list commands are: %LIST_BEGIN @filename or symbol This command both starts the block of script commands that are to be repeated and gives the name of the file or symbol from which the list elements are to be accessed. The filename must start with a '@', and each record of the file is treated as one element of the list. The symbol contains elements seperated by a comma ','. %LIST_END This command ends the block of script commands start with the LIST_BEGIN command. The substitution syntax is "\\*". The substitution character set is replaced by the list element. Each time the block of script commands are replicated, the next element in the list is used. The script block syntax can be any valid set of script commands, and may contain more than one option. 30. Example of List Processing: Symbol 'VALID_QUE' contains "TAPEQ,LOCAL_PRINTER,BATCH1,BATCH2" Script text: "] Display Queue Menu ] Exit to Main Menu % RETURN % LIST_START VALID_QUE Show Queue \\* % HOLD % NO CLEAR $ sho que \\* % LIST_END ] Please Enter Option: " Would appear as: " Display Queue Menu 1 Exit to Main Menu 2 Show Queue TAPEQ 3 Show Queue LOCAL_PRINTER 4 Show Queue BATCH1 5 Show Queue BATCH2 Please Enter Option: " 31. 16. Installation and Notes (VMS) Script installs as a normal "foreign" command: sc*ript:==$ddan:[dir.dir]script.exe The logical SYS$SCRIPT should point to where the scripts for the user resides. Script can also be install in the system, and it is suggested that it is installed if there are enough global pages (66) and sections (2). The options to uses should be shared, header, and open. Script help file can be installed by: LIB/REPLACE/HELP SYS$HELP:HELPLIB.HLB [dir]SCRIPT.HLP 17. VMS Mailboxes and Event Flags These features allow Script to interface with other processes. This ability to communicate and synchronize with other programs, DCL or executables has a number of benefits and solves a major problems of Script. One of the benefits include faster execution of action items ($) since these commands do not have to be initiated by the SPAWN directive (which requires the creation of a new sub-process). Instead they are passed via the mailbox to an already existing sub-process to be executed. This proceedure is automated by either the /MAILBOX switch in the command line, or the "% MAILBOX (START)" command. Both of these use the supplied command file SCRIPT.MAIL_BOX. Another benefit is that since the sub-process does not exit, it maintains its context, so that commands like "$ SET DEF" or "$ ALLOCATE MTA0:" are effective while Script is executing. A similar function with Script running in a sub-process and the command file executing as the parent is started either by the "/BACKGROUND" switch or the "% MAILBOX (BACKGROUND)" command. The command file "SCRIPT.BACKGROUND" is an example of how this technique is used. Event flag handling and sychronization for DCL can be done with the included FLAG utility. See FLAG.DOC for command details.