acl_file_execute_c

	status.i4.v = acl_file_execute_c(file_name.i1a.r, file_type.i4.v,
					 subst_devices.i1a.r, num_devices.i4.v,
					 default_ftd.i2.v, options.u4.v,
					 output_func.f.v, output_data.g.v,
					 pre_exec_func.f.v, pre_exec_data.g.v,
					 post_exec_func.f.v,
					 post_exec_data.g.v, error_string.i1a.r
					 [,abort_func.f.v]
					 [,subst_strings.i1pa.r]
					 [,num_subst_str.i4.v]
					 [,input_func.f.v] [,input_data.g.v]
					 [,log_file.i1a.r] [,procs.sa.r]
					 [,num_procs.i4.v])

	This routine executes Accelerator Command Language commands (ACL)
	from a file or database table.  If the database option is chosen,
	the table which contains the code must be ACL_DB_TABLE.

	file_name	null terminated file name
	file_type	type of file
			(ACL_FLAT_FILE -> ASCII text file,
			 ACL_DB_FILE -> "file_name" should be the database
					table name from ACL_DB_TABLE)
	subst_devices	array of substitute device names which replace
			device names in the source code of the form "G:DEVnnn"
			(dio_get_terse_name_length characters per entry)
			(If the option ACL_OPT_SUBST_ARRAY_DEVICES is
			 selected, there should be C_STYLE_LONG_DEVICE_NAME_LEN
			 characters per entry.)
			(A value of NULL can be passed for this argument
			 if no substitute device names are needed.)
	num_devices	number of substitute devices
	default_ftd	default reading FTD for any devices in the code
	options		execution options
			(ACL_OPT_NONE -> no options selected, parse and
					 execute the code,
			 ACL_OPT_PARSE_ONLY -> parse, but do not execute code,
			 ACL_OPT_DELETE_SYMBOLS -> delete all existing ACL
						   symbols before executing
						   the code,
			 ACL_OPT_COMPILED_CODE -> code has already been
						  compiled by a call to
						  acl_compile_c, just
						  execute it,
			 ACL_OPT_DONT_CLOSE -> leave database connection
					       open upon exit (close later
					       with db_close),
			 ACL_OPT_NO_STALE -> ignore stale data errors,
			 ACL_OPT_NO_SETS -> suppress settings (no errors),
			 ACL_OPT_DISABLE_SETTINGS -> disable settings,
			 ACL_OPT_SAVE_SOURCE -> save source code with
						compiled code,
			 ACL_OPT_CLEAR_STATUS -> clear global status symbols,
			 ACL_OPT_CANCEL_REQUESTS -> cancel data requests,
			 ACL_OPT_SUBST_ARRAY_DEVICES -> substitute device names
							can include array
							indices
							(C_STYLE_LONG_DEVICE_NAME_LEN
							 characters per entry),
			 ACL_OPT_VERBOSE_OUTPUT -> display verbose output,
			 ACL_OPT_DIAGNOSTIC_MODE -> enable diagnostic mode,
			 ACL_OPT_SIMPLE_ERROR_STRINGS -> want simple error
							 strings,
			 ACL_OPT_WANT_OUTPUT_STRINGS -> want output strings
							($_output_strings symbol),
			 ACL_OPT_SUPPRESS_NEWLINES -> suppress default new line
						      characters in the print
						      command and printf
						      function)
	output_func	callback function to be called each time a line
			of output is generated
			(called as follows:
			 suppress_line.i4.v = output_func(output_func_data.g.v,
							  output_string.i1a.r,
							  value.g.v,
							  value_type.i4.v,
							  value_length.i4.v,
							  output_type.i4.v,
							  destination.i1a.r)
			(A value of NULL can be passed for this argument
			 if this functionality is not desired.)
	output_data	address of data to be passed to "output_func"
	pre_exec_func	callback function to be called just before a
			given line of code will be executed
			(called as follows:
			 status.i4.v = pre_exec_func(pre_exec_data.g.v,
						     command_data.s.r)
			 ("command_data" is a structure of type
			  ACL_PRE_EXEC_DATA))
			(If a status value of CLIB_ABORT is returned by
			 this routine, the ACL script will be aborted.)
			(A value of NULL can be passed for this argument
			 if this functionality is not desired.)
	pre_exec_data	address of data to be passed to "pre_exec_func"
	post_exec_func	callback function to be called just after a
			given line of code has been executed
			(called as follows:
			 status.i4.v = post_exec_func(post_exec_data.g.v,
						      command_data.s.r)
			 ("command_data" is a structure of type
			  ACL_POST_EXEC_DATA))
			(If a status value of CLIB_ABORT is returned by
			 this routine, the ACL script will be aborted.)
			(A value of NULL can be passed for this argument
			 if this functionality is not desired.)
	post_exec_data	address of data to be passed to "post_exec_func"
	error_string	returned error string
			(Allow ACL_ERROR_STRING_LEN + 1 characters.)
			(A value of NULL can be passed for this argument
			 if this information is not needed.)
	[abort_func]	callback function to allow the caller to abort a
			script  (It will be called before each command and
			within each internal loop of a command.  If this
			function returns a value other than FALSE, the
			entire script will be aborted.)
			(default is NULL)
	[subst_strings]	array of null terminated strings which will replace
			strings in the source code of the form "STRINGnnn"
	[num_subst_str]	number of substitute strings supplied
	[input_func]	callback function to be called each time a user
			input is needed
			(called as follows:
			 status.i4.v = input_func(prompt_text.i1a.r,
						  data_type.i4.v,
						  max_length.i4.v,
						  value.g.v, data_length.i4.r,
						  input_func_data.g.v)
			(A value of NULL can be passed for this argument
			 if this functionality is not desired.)
			(default is NULL)
	[input_data]	address of data to be passed to "input_func"
			(default is NULL)
	[log_file]	fully specified name of log file to generate
			(default is NULL)
	[procs]		array of calling process procedure information
			(array of structures of type ACL_PROC_DATA)
			(default is NULL)
	[num_procs]	number of calling process procedures
			(default is 0)

	This function returns ACNET status values as follows:

	OK			success
	CLIB_MEMFAIL		failed in allocating dynamic memory
	CLIB_NOTOPN		failed to open file
	CLIB_SYNTAX		syntax error
	CLIB_INVSIZ		command line too long
	otherwise		other ACNET format error code

	This function requires the following include files:

	ul_acl_h:acl_h, acnet_errors_h

	Related functions:

	intro_acl, acl_execute_c, acl_file_read_c, acl_file_write_c,
	acl_file_exists_c, acl_db_file_exists_c, acl_compile_c, acl_free_c,
	acl_free_arg_info_c, acl_read_symbol_c, acl_read_symbol_as_string_c,
	acl_read_symbol_info_c, acl_read_symbol_dynamic_info_c,
	acl_read_symbol_names, acl_read_intrinsic_symbol_names,
	acl_parse_symbol_name, acl_script_argument_info_c,
	acl_script_has_symbol_list_c, acl_script_has_setting_c,
	acl_delete_symbol, acl_reinit_symbol, acl_info_c,
	acl_cancel_requests_c, acl_set_symbol_c, acl_default_data_source_c,
	acl_log_file_c, acl_default_script_path_c, db_close,
	acl_script_is_executing, acl_register_host_request_func,
	acl_unregister_host_request_func, acl_translate_command_string,
	acl_file_read_description_c, acl_file_read_author_c,
	acl_file_read_title_c, acl_execute_file_in_window_c,
	acl_execute_in_window_c, acl_search_db_files_c,
	acl_file_is_in_repository_c, acl_parse_script_argument_string_c,
	acl_expand_file_name_c, acl_get_user_execution_privilege,
	acl_get_user_db_edit_permission

	C/C++ usage:

	static const char	file_name[] = "acl_file.acl";
	char	error_string[ACL_ERROR_STRING_LEN+1];
	char	*subst_devices = (char *) NULL;
	char	*log_file = (char *) NULL;
	char	**subst_strings = (char **) NULL;
	short	default_ftd = FTD_ONESHOT;
	int	status;
	int	file_type = ACL_FLAT_FILE;
	int	num_devices = 0;
	int	num_subst_str = 0;
	int	num_procs = 0;
	unsigned int	options = ACL_OPT_NONE;
	void	*output_data = (void *) NULL;
	void	*pre_exec_data = (void *) NULL;
	void	*post_exec_data = (void *) NULL;
	void	*input_data = (void *) NULL;
	ACL_PROC_DATA	*procs = (ACL_PROC_DATA *) NULL;
	int	output_func(void *output_data, char *output_string);
	int	pre_exec_func(void *pre_exec_data,
			      ACL_PRE_EXEC_DATA *command_data);
	int	post_exec_func(void *post_exec_data,
			       ACL_POST_EXEC_DATA *command_data);
	int	abort_func(void);
	int	input_func(int data_type, int max_length, void *value,
			   int *data_length, void *input_data);

	status = acl_file_execute_c(file_name,file_type,subst_devices,
				    num_devices,default_ftd,options,output_func,
				    output_data,pre_exec_func,pre_exec_data,
				    post_exec_func,post_exec_data,error_string,
				    abort_func,subst_strings,num_subst_str);
				    input_func,input_data,log_file,procs,
				    num_procs);