intro_acl_usage


	The Accelerator Command Language (ACL) is a simple scripting
	language for reading and setting ACNET devices.  It can also be
	used for simple general purpose programming.


	Using ACL from the command line:


	To use ACL from the command line, you simply type in "acl" and
	hit return.  You will then see a prompt of "ACL>".  At this
	prompt you can type in any valid ACL command or list of commands
	separated by semicolons.  You can execute an existing ACL script
	file by simply typing an "@" character followed by the name of
	the file and any arguments that the file might need separated
	by spaces.  If the script is contained in a text file and the
	extension of the file is ".acl", you do not have to explicitly
	enter it.  If you are executing an ACL script kept in the ACL
	script database, you should add a suffix of ".db".  Also, in
	this case, if the name of the script contains spaces, the entire
	name except the extension should be enclosed in quotes.

	Example of executing a script contained in a text file:

	ACL> @my_script argument_1 argument_2

	Example of executing a script contained in a text file
	with a different extension:

	ACL> @my_script.txt argument_1 argument_2

	Example of executing a script contained in a database file:

	ACL> @'my database script'.db argument_1 argument_2

	It is important to note that on the command line when you press
	return after entering a command, that is considered to be the
	execution of a script.  Any environment related commands such
	as "output", "data_source", or "data_event" will have no effect
	on subsequent commands that are entered.  An exception is the
	"keep_open" qualifier for the output command.  If that qualifier
	is specified, the corresponding output will be used for the
	remainder of that ACL session.

	The command line environment has some special commands that
	are unique to it.  Here is a brief listing of them.

	source [on|off] : turn source code display on or off
	verbose [on|off] : turn verbose output on or off
	suppress_settings [on|off] : turn setting suppression on or off
	show symbols : display all active symbol names
	show symbol {symbol name} : display the value of a symbol
	set symbol{/qualifier} {symbol} {value} : set the value of a symbol
	(Qualifiers for the set symbol command include:
	 error -> value will be interpreted as an ACNET error string
	 error_int -> value will be interpreted as an ACNET error code (integer)
	 device -> value will be interpreted an an ACNET device name
	 device_index -> value will be interpreted as an ACNET device index
	 string -> value will be interpreted as a string
	 logical -> value will be interpreted as a logical
	 integer -> value will be interpreted as an integer
	 float -> value will be interpreted as a floating point value)


	Using ACL from a parameter page or a parameter window:


	To use ACL in this environment, you must start the line with the
	string "ACL>".  There are two optional special characters that can
	follow this.  The first is a plus ('+') sign which indicates that
	the ACL output window should remain open until the user manually
	closes it.  The other special character is a greater than ('>')
	sign which indicates that the ACL command should be spawned off
	as a batch job.  As in the command line environment, an existing
	ACL script can be executed by preceding its name with an '@'
	character.  In this case however, only scripts contained in the
	ACL script database can be executed.  You do not have to add the
	".db" extension to the file name, but you still have to enclose
	the file name in quotes if it contains spaces.  The scripts must
	be created and modified using the application program D136.  If
	you have never used this program before, you must contact Brian
	Hendricks (hendricks@fnal.gov) to be authorized to edit scripts.
	To execute an ACL command in this environment, you must click on
	the line containing the command.  You will then be presented with
	a decision window.  If you click on the "OK" button the ACL
	command will be executed.

	Example of executing a script whose name contains spaces:

	ACL> @'my spacey script' argument_1 argument_2

	Example of spawning off a script execution:

	ACL>> @my_spawned_script argument_1 argument_2

	Example of executing a script and retaining the output window
	for the user to view:

	ACL>+ @my_output_script argument_1 argument_2

	There is a command in both the index page as well as the parameter
	page itself named 'Find ACL Command' to search for occurrences of
	a particular ACL command in all of the parameter pages.


	Using ACL from the simple IDE contained in the Pgm_Tools menu:


	To use the ACL interface contained in the Pgm_Tools menu, you click
	on "Pgm_Tools" in a console application and click on the entry
	named "ACL Edit/Run".  Once you've done this an empty window will
	be displayed that you can enter ACL code in.  The window acts as
	a simple text editor which supports some of the numeric keypad
	editing functions from EDT.  There are other special features such
	as command signature help.  This is enabled if the text to the left
	of the cursor is an ACL command name and you press control-e.  This
	will display possible arguments for this type of command.  Pressing
	control-h anywhere within the window will give you help on the editor
	itself.  You can also click on the field named "Action" and perform
	other operations such as reading in an existing script from either a
	text file or the script database.  If you choose either of these
	actions, any text entered in the window will be replaced by the script
	text.  You can then edit the text further if you wish.  You can
	execute the code presently in the editor window by clicking under
	"Action" followed by "Execute Script".  This will cause two windows
	to be displayed.  The top window displays the source lines as they
	are executed while the bottom window displays any output that the
	script generates.  Clicking on either of these windows will cause
	them both to close, and the editor window will once again be displayed.
	This interface also supports the writing of scripts to text files
	in the directory /usr/local/cbs_files/cns_write/acl.

	There are many other options in the "Action" menu of this interface.
	You can display detailed help about individual ACL commands.  You
	can display, read, and set ACL symbols.  You can suppress settings
	as well as stale errors.  You can request verbose output from all
	commands executed as well as many other things.


	Using ACL from the Sequencer:


	ACL scripts can be executed in the Sequencer by utilizing the
	"ACL" command.  This executes scripts which are text files located
	in the directory /usr/local/cbs_files/sequencer/acl.  These scripts
	can be created/modified using the MECCA project sequencer_acl.
	Use the standard MECCA commands to do this.  Scripts can either be
	executed inline or they can be spawned off as a batch file to
	execute in parallel.  Sequencer scripts are limited to a maximum
	of ten substitute devices and five substitute strings.


	Using ACL in a Lex SA:


	ACL scripts can be executed in Lex SA displays through the use
	of script objects.  These scripts must be contained in the script
	database just like the parameter page and parameter window
	environment.  There can be both a display script as well as an
	action script which is activated by clicking on the graphical
	object.  Lex SA scripts are limited to a single substitute string.


	Using ACL in a web browser:


	ACL commands and scripts can be executed in a web browser environment
	using the following command.

	http://www-ad.fnal.gov/cgi-bin/acl.pl?acl={your ACL code goes here}

	If there are any spaces in your command, they must be replaced
	by plus signs.

	ACL commands executed in a browser environment are by necessity
	very limited.  You can basically perform only reading type
	operations.


	Using ACL in EDM:


	ACL commands and scripts can be executed in EDM by using the
	shell command widget.  Simply enter your ACL command in the
	"Shell Command" field as "acl @{your file name}".  The ACL
	file should be committed in the MECCA project that you are
	working on like hins_edm or nml_edm.


	Using ACL from the ACL daemon:


	ACL commands and scripts can be executed remotely using the
	ACL daemon.  This daemon accepts ACNET requests to execute
	ACL scripts and will return any requested data to the caller
	after the script completes.

	Any requested return data should be for values of ACL symbols
	that are set by the script.  The value of multiple symbols
	can be requested.  All values will be returned as strings
	regardless of their data type.  If the script fails, the
	returned data will be a single string which describes the
	error which caused the script failure.

	Any flat file scripts executed by the daemon should be kept
	in the MECCA project utility_acl.  The normal database scripts
	used by the parameter page, parameter window, and Lex SA can
	be used as well.

	ACNET requests to this daemon use the protocol defined in the
	user library ul_acld_protocol.


	Controlling ACL Output


	In the case of the parameter page, the parameter window,
	the ACL IDE,and the Sequencer, ACL output format can be
	controlled by the use of the ACL host_request command.
	This command works by passing an ASCII string to the process
	which is hosting the ACL script.  In the case of output,
	these commands can control the screen output formating.
	If the host application does not understand a request,
	it simply ignores it.  The ACL script is unaware of whether
	or not the request has been honored.

	Requests honored by the parameter page, parameter window, and ACL IDE:

	window_height={size}	 -> set the height of the ACL output window
				    (default, large, or number of rows)
	window_width={size}	 -> set the width of the ACL output window
				    (default, large, or number of rows)
	suppress_scrollbar	 -> disable the scrollbar and scroll status
				    display for the ACL output window
	text_color={color}	 -> set the ACL output text color
	text_align={alignment}	 -> set the ACL output text alignment
				    (default, center, or right)
	scroll_text={yes|no}	 -> enable or disable scrolling of ACL output
	clear screen		 -> erases the ACL output window
	text_row={row}		 -> sets the output text row for nonscrolling
				    output
	text_column={column}	 -> sets the output text column for nonscrolling
				    output
	clear_text_field={len}	 -> erases a field in the ACL output window
	text_row_increment={inc} -> sets the output text row automatic increment
				    for nonscrolling output
	text_column_increment={} -> sets the output text column automatic
				    increment for nonscrolling output
	suppress_completion_message -> disable the script completion message

	Requests honored by the Sequencer:

	text_color={color}	 -> set the ACL output text color
	text_align={alignment}	 -> set the ACL output text alignment
				    (default, center, or right)
	scroll_text={yes|no}	 -> enable or disable scrolling of ACL output
	clear screen		 -> erases the ACL output window
	text_row={row}		 -> sets the output text row for nonscrolling
				    output
	text_column={column}	 -> sets the output text column for nonscrolling
				    output
	clear_text_field={len}	 -> erases a field in the ACL output window
	text_row_increment={inc} -> sets the output text row automatic increment
				    for nonscrolling output
	text_column_increment={} -> sets the output text column automatic
				    increment for nonscrolling output

-------------------------------------------------------------------------------

	Related functions:

	intro_acl, acl_compile_c, acl_execute_c, acl_file_execute_c,
	acl_file_read_c, acl_file_write_c, acl_free_c, acl_read_symbol_c,
	acl_read_symbol_info_c, acl_read_symbol_names, acl_set_symbol_c,
	acl_delete_symbol, acl_info_c, acl_cancel_requests_c, acl_get_devices_c,
	acl_close, acl_command_text, acl_log_file_c, acl_default_data_source_c,
	acl_default_script_path_c, spawn_acl_script_c, device_listing_c