CtrlNamedBackground

CtrlNamedBackground taskName , keyword = value [, keyword = value ...]

The CtrlNamedBackground operation creates and controls named background tasks.

We recommend that you see Background Tasks for an orientation before working with background tasks.

Parameters


taskName	taskName is the name of the background task or _all_ to control all named background tasks. You can use any valid standard Igor object name as the background task name.
burst [= b ]	Enable burst catch up mode (off by default, b =0). When on (b =1), the task is called at the maximum rate if a delay misses normal run times.
dialogsOK [=d ]	Use dialogsOK=1 to allow the background task to run when a dialog window is active. By default, dialogsOK=0 is in effect. See Background Tasks and Dialogs for details. Setting dialogsOK to 1 can cause a crash if the background task does things the dialog does not expect. See Background Tasks and Dialogs for details.
kill [= k ]	Stops and releases task memory for reuse (k =1; default) or continues (k =0).
noEvents=mode	Controls Igor's event processing while a background task function is executing. The noEvents keyword was added in Igor Pro 8.04.
	If your background task function uses a large fraction of available processor time, you may find that it is difficult to type on the command line or anywhere else. That is because Igor normally discards events that arrive while a user-defined function is running, causing events to be lost. This is the default mode of operation and corresponds to noEvents=0.
	Using noEvents=1 causes Igor to postpone event handling until after the background task function returns which improves the reliability of the user interface. A consequence of using noEvents=1 is that you cannot abort a rogue background task function using User Abort Key Combinations.
	The noEvents keyword applies to all background tasks, including the unnamed background task. You should use _all_ for the taskName parameter.
	mode defaults to 0 when Igor starts. The mode set using noEvents remains in effect until Igor quits.
period=deltaTicks	Sets the minimum number of ticks (deltaTicks ) that must pass between background task invocations. deltaTicks is truncated to an integer and clipped to a value greater than zero. See Background Task Period for details.
proc=funcName	Specifies name of a background user function (see Details below).
start [=startTicks ]	Starts when the tick count reaches startTicks. A task starts immediately without startTicks.
status	Returns background task information in the S_info string variable.
stop [= s ]	Stops the background task (s =1; default) or continues (s =0).

Details

The user function you specify via the proc keyword must have the following format:

Function myFunc(s)
	STRUCT WMBackgroundStruct &s
	...

The members of the WMBackgroundStruct are:

Member	Description
char name[MAX_OBJ_NAME+1]	Background task name.
uint32 curRunTicks	Tick count when task was called.
int32 started	TRUE when `CtrlNamedBackground start` is issued. You may clear or set to desired value.
uint32 nextRunTicks	Precomputed value for next run but user functions may change this.

You may also specify a user function that takes a user-defined STRUCT as long as the first elements of the structure match the WMBackgroundStruct or, preferably, if the first element is an instance of WMBackgroundStruct. Use the started field to determine when to initialize the additional fields. Your structure may not include any String, WAVE, NVAR, DFREF or other fields that reference memory that is not part of the structure itself.

If you specify a user-defined structure that matches the first fields rather than containing an instance of WMBackgroundStruct, then your function will fail if, in the future, the size of the built-in structure changes. The value of MAX_OBJ_NAME is 255 but this may also change. It was changed from 31 to 255 in Igor Pro 8.00.

Your function should return zero unless it wants to stop in which case it should return 1.

You can call CtrlNamedBackground within your background function. You can even switch to a different function if desired.

Use the status keyword to obtain background task information via the S_info variable, which has the format:

NAME:name;PROC:fname;RUN:r;PERIOD:p;NEXT:n;QUIT:q;FUNCERR:e;

When parsing S_info, do not rely on the number of key-value pairs or their order. RUN, QUIT, and FUNCERR values are 1 or 0, NEXT is the tick count for the next firing of the task. QUIT is set to 1 when your function returns a nonzero value and FUNCERR is set to 1 if your function could not be used for some reason.