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.  Special
	permission is required to edit files in this directory.  Please,
	contact Brian Hendricks (hendricks@fnal.gov) for access to this
	directory.  Scripts can either be executed in line 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.

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

	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