




			SCRIPT LANGUAGE REFERENCE MANUAL

			 Copyright Warren Falls. 1986.



									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			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					13
	show_filename   erase-screen   reset_screen   graphic   date
	hardcopy_prompt   output					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 Control (VMS only)
	open   append   write   log   close				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
									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 <CR>.  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		ALLOW		AND		APPEND		ASK
ASKL		ASKS		ASK?		BATCH		BOTTOM
BLOCK		CALL		CHAIN		CHOICE		CLEAR
CLI		CLOCK		CLOSE		CONTINUE	DATE
DEBUG		DELAY		DISALLOW	DLOGICAL	DSYMBOL
END		ERASE		ERROR		EXIT		FILENAME
FREE		GOTO		GRAPHIC		HARDCOPY_PROMPT HOLD
IF		IFNOT		INQUIRY		ISOLATE		KILL_LAST
LAST		LOCK		LOG		LOGICAL		LOOP
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		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 <CR> 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 <CR> 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 <CR> 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.
									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 <CR> 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 <CR> 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 <CR>, 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 <CR> 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
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.
									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.  Valid only in the Title and Initialization field.

	%HARDCOPY_PROMPT "prompt"
Will use "prompt" in place of 'SCR>' on hardcopy menu returns.
									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.  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 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.


	%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.
									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

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 6.  Additionally to these six possible strings, the sequence "\\0" is
replaced by the lower two octals of the users' terminal number.  This string
can then be used to create discrete filenames for each version of SCRIPT 
running.  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.
VMS only:  DCL symbols  or logicals will be substituted for if surrounded by
"^" before any other types of substitutions are attempted.
									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 <CR>.  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
"<CR>" are processed as a selection request, Strings terminated with a
"?<CR>" 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 <sp>		Moves the cursor down.
	Tab <tab>		Moves the cursor down.
	Zero <0>		Moves the cursor down.
	Backspace <bs>		Moves the cursor up.
	Carriage Return <cr>	Selects option.
	Question Mark <?>	Requests help for option.

    At the Cursor or the Prompt:

	<string><cr>		Request selection <string>.
	<cr>			Requests the top selection.
	<string?><cr>		Request help for selection <string>.
	"HELP" or "help"<cr>	Request help on Script input.
	$<string><cr>		Execute <string> as a command. (VMS)*
	!<string><cr>		Exit with <string> in symbol SCR$COMMAND. (VMS)*
	!<string><cr>		Execute <string> as a command. (RSX)*
	@<string><cr>		Change menu script to <string>.*
	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.*
	<lf>			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, 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.

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. (VMS or RSX)

Example:
	Title Text
%	\\1
%	whatever

The command line could appear as:

		SCR "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:

		SCR "" 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 ##0

Copy a File
	%NO CLEAR
	%ASKS File(s) to copy from:  
	%ASKS () Copy to:  
	  $COPY ##0 ##1
]

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 ##0

Copy a File\%N\ASKS Files to copy from:  \%ASKS () Copy to:  \$COPY ##0 ##1
]

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		APend filename		ASK (insrt) text
ASKL text	   ASKS (dflt) text	ASKS text		ASK? text
ASK? (filespec)	   ASK? "text"		BAtch			BLock
BOttom		   Call filename	CHain command		CLEar
CLI cliname	   CLOCk		CLOSe			DAte`
COntinue	   DEBug		DELay n			DIsallow
DLogical logical   DSymbol symbol	ENd			ERror
EXit		   FIlename		Free			GOto filespec
GRaphic command	   HAlt_init		HARdcopy_prom "prompt"	HOld
IF n/err	   IFNot n/err		INquiry			ISolate
Kill last	   LAst command		LOCk			LOG string
LOGIcal (nm) str   LOOp			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_screen	UNLock			Verbose
WAit		   WHole		WRite string

Valid Selection and Action Field Control Items (Least unique string capitolized)

AGain		   ANd n		APend filename		ASK (insrt) text
ASKL text	   ASKS (dflt) text	ASKS text		ASK? text
ASK? (filespec)	   ASK? "text"		BAtch			BLock
BOttom		   CAll filespec	CHAin command		CHOoice
CLEar		   CLOCk		CLOSe			COntinue
DElay n		   DLogical logical	DSymbol symbol		ENd
ERase		   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		   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			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.
									26.

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.

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


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 <BS>
!cr		Do a <CR>
!linefeed	Do a <LF>
!escape		Do a <ESCAPE>
!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 Selectiona 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.  The space between
	    the '~' and the comment_text is optional.
									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 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.

The following symbols are used by Script:

	SCR$MASK		Mask to be used in Item Masking (see above).
	PRV$RESULT		Privilege mask used by PRIVILEGE command.



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:  "
