acl_execute_file_in_window_c

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

	This routine will execute an ACL script file in a window.

	title		window title (A value of NULL may be passed for
			this argument if no title is desired.)
	top_row		top row of window (use WMNGR_CENTER for centering
			or WINDOW_xxx_COORD macros in macro for special
			positioning)
	left_column	left column of window (use WMNGR_CENTER for centering
			or WINDOW_xxx_COORD macros in macro for special
			positioning)
	num_rows	number of rows
	num_columns	number of characters per row
	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)
	[gui_options]	GUI options
			(ACL_GUI_OPT_NONE -> no options selected (default),
			 ACL_GUI_OPT_PERSISTENT_WINDOW -> wait for user to
							  dismiss window)
	[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.)
			(default is NULL)
	[num_devices]	number of substitute devices
			(default is 0)
	[default_ftd]	default reading FTD for any devices in the code
			(default is FTD_ONESHOT)
	[subst_strings]	array of null terminated strings which will replace
			strings in the source code of the form "STRINGnnn"
			(default is NULL)
	[num_subst_str]	number of substitute strings supplied
			(default is 0)
	[options]	execution options
			(ACL_OPT_NONE -> no options selected, parse and
					 execute the code (default),
			 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,
			 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)
	[error_string]	returned error string (Allow at least 133 characters.)
			(A value of NULL can be passed for this argument
			 if this information is not needed.)
			(default is NULL)
	[log_file]	fully specified name of log file to generate
			(default is NULL)
	[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)
			(If an alternate output function is specified,
			 it can determine the window ID of the output window
			 by calling the routine acl_get_window_id.)
			(A value of NULL can be passed for this argument
			 if this functionality is not desired.)
			(default is NULL)
	[output_data]	address of data to be passed to "output_func"
			(default is NULL)
	[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)
	[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)
	[hostreq_func]	function to be called by any ACL "host_request"
			command which allows the script to pass a request
			to the calling program
			(called as follows:
			 status.i4.v = hostreq_func(request_string.i1a.r)
			(A value of NULL can be passed for this argument
			 if this functionality is not desired.)
			(default is NULL)
	[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.)
			(default is NULL)
	[pre_exec_data]	address of data to be passed to "pre_exec_func"
			(default is NULL)
	[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.)
			(default is NULL)
	[post_exec_data]address of data to be passed to "post_exec_func"
			(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 status values as follows:

	OK			success
	CBS_INVARG		invalid number of rows or columns passed
	CBS_WINDOW_TOO_BIG	window won't fit on the screen
	CBS_MEMFAIL		dynamic memory allocation failure

	This function requires the following include files:

	cnsparam_h, ul_acl_h:acl_h, macro_h, acnet_errors_h

	Related functions:

	intro_acl, acl_execute_in_window_c, acl_get_window_id,
	acl_file_execute_c, acl_compile_c, acl_execute_c,
	acl_file_read_c, acl_file_write_c, acl_read_symbol_c,
	acl_read_symbol_info_c, acl_read_symbol_names, acl_info_c,
	acl_set_symbol_c, acl_cancel_requests_c, window_restore_hint_c

	C/C++ usage:

	static const char	title[] = "Title";
	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	top_row = WMNGR_CENTER;
	int	left_column = WMNGR_CENTER;
	int	num_rows = NUM_ROWS;
	int	num_columns = NUM_COLUMNS;
	int	file_type = ACL_FLAT_FILE;
	int	num_devices = 0;
	int	num_subst_str = 0;
	int	num_procs = 0;
	unsigned int	gui_options = ACL_GUI_OPT_NONE;
	unsigned int	options = ACL_OPT_NONE;
	void	*output_data = (void *) NULL;
	void	*input_data = (void *) NULL;
	void	*pre_exec_data = (void *) NULL;
	void	*post_exec_data = (void *) NULL;
	ACL_PROC_DATA	*procs = (ACL_PROC_DATA *) NULL;
	int	output_func(void *output_data, char *output_string);
	int	input_func(int data_type, int max_length, void *value,
			   int *data_length, void *input_data);
	int	abort_func(void);
	int	hostreq_func(char *request_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);

	status = acl_execute_file_in_window_c(title,top_row,left_column,
					      num_rows,num_columns,
					      file_name,file_type,gui_options,
					      subst_devices,num_devices,
					      default_ftd,subst_strings,
					      num_subst_str,options,
					      error_string,log_file,
					      output_func,output_func_data,
					      input_func,input_func_data,
					      abort_func,hostreq_func,
					      pre_exec_func,pre_exec_data,
					      post_exec_func,post_exec_data,
					      procs,num_procs);