lext_init_active_image (ul_lextools)

	status.i4.v = lext_init_active_image(name.i1a.r, overlay.i4.v,
					     subst_device.i1a.r, mode.i4.v,
					     image_change_fn.f.v,
					     display_up_fn.f.v
					     [,num_limits.i4.v]
					     [,caller_limits.r4a.r])

	This routine initializes an active Lextools image.

	name		name of Lextools active file to initialize
			(LEXT_SA_NAMLEN characters)
	overlay		overlay flag
			(TRUE -> overlay present image,
			 FALSE -> delete present image (if any))
	subst_device	device name substitution string
			(dio_get_terse_name_length characters)
			(For letters in device names that should remain the
			 same, this string should contain an asterisk in the
			 corresponding location.) (A null pointer may be
			 passed if no device substitutions are needed.)
	mode		application mode
			(LEXT_ACTIVE_NORMAL -> normal program execution,
			 LEXT_ACTIVE_COPY_IMAGE -> copy image to a GIF file
						   once active objects have
						   updated and terminate)
	image_change_fn	function to be called each time a new image is
			initialized by clicking on a change image button
			(A value of NULL can be passed for this argument.)
			(called as follows:
			 image_change_fn(new_image_file.i1a.r)
			 ("new_image_file" is the name of the new active
			  image file))
	display_up_fn	function to be called when an image has completely
			displayed itself for the first time
			(A value of NULL can be passed for this argument.)
			(called as follows:
			 display_up_fn(status.i4.v)
			 ("status" is the image display status.))
	[num_limits]	number of caller supplied analog object limits
			(default is 0)
	[caller_limits]	array of caller-supplied analog object limits
			(default is NULL)

	This function returns ACNET status values as follows:

	OK			success
	CBS_MEMFAIL		dynamic memory allocation failure
	CBS_GENERR		error reading file directory
	SQL_xxx			error reading image file

	This function requires the following include files:

	ul_lextools_h:lextuti_h, acnet_errors_h

	Related functions:

	lext_remove_active_image, lext_draw_object_c, lext_modify_object_c,
	lext_erase_object, lext_sa_menu_c, lext_enable_device_monitoring,
	lext_disable_device_monitoring, lext_enable_image_control,
	lext_disable_image_control, lext_current_active_image, lximag, lxobj

	C/C++ usage:

	static const char	name[LEXT_SA_NAMLEN+] = "BLDGTEMP";
	char	*subst_device = (char *) NULL;
	int	status;
	int	overlay = FALSE;
	int	mode = LEXT_ACTIVE_NORMAL;
	int	num_limits = 0;
	float	*caller_limits = (float *) NULL;
	lext_image_change_function	image_change_fn;
	lext_display_up_function	display_up_fn;

	status = lext_init_active_image(name,overlay,subst_device,mode,
					image_change_fn,display_up_fn,
					num_limits,caller_limits);