DitsLoad - Loads and runs a task.

Function

Loads and runs a task.

Description

This routine is used to request that DITS load and run a new task. The calling routine specifies the task to be run and the machine on which it is to be run. This routine initiates a transation which uses the Imp Master task on the target machine to load the task. This means that the the imp master task must be running on the target machine. The imp master task is normally started with the dits_netstart command, see Dits documentation for details.

Reschedules resulting from initiating this transaction are

`DITS_REA_LOAD`	The task has been loaded successfully and has registered with the message system. {\tt DitsPathGet()} should now succeed. Note, the transaction has not completed.
`DITS_REA_LOADFAILED`	The load has failed and the transaction is complete.
`DITS_REA_EXIT`	The loaded task has exited. This message indicates the program has then exited for whatever reason. The transaction is now complete.

Is it possible to load programs which are not Dits programs. In this case, DITS_REA_LOADED will never be received.

Language

Call

void = DitsLoad (Node, Program, ArgString, Flags, TaskParams, transid, status)

Parameters

(">" input, "!" modified, "W" workspace, "<" output)

>	Node	char `*`	Specifies the machine on which the task is to run. This can be any string that can interpreted by the underlying networking system, for example a symbolic or numeric `IP` address. If this parameter is a `NULL` address, or points to a null string the current machine is used.
>	Program	char `*`	Specifies the program to be run in the new task. See below for a more detailed description of how a program may be specified.
>	ArgString	char `*`	Arguments to be passed to the loaded task, formatted into a single character string. See below for a more detailed discussion of task arguments.
>	Flags	long int `*`	A flag word controlling some options. In general these options are system-dependent, at least to some extent. The various options are listed below.
>	TaskParams	DitsTaskParamType `*`	Address of a structure containing additional values used to control the loading of the task. The use of the various fields in this structure is controlled by the setting of the bits in the Flags argument.
<	transid	DitsTransIdType `*`	Transaction id for the transaction started. If an address of zero is supplied, then don't create a transaction id. In this case, we will never be notified of load events.
`!`	status	Int `*`	Modified status.

TaskParams fields to be set prior to the call

Priority(int), Bytes(int), ProcName(char [32]), Decode(char[64])

Program syntax

Generally, what is specified as 'Program' will be a string indicating an executable file. In the case of systems such as VxWorks, where programs are pre-loaded subroutines, a separate mechanism is provided to associate strings that can be specified as 'Program' with the routines to be run. In such a case, any string can be associated with a subroutine. In larger systems such as VMS or UNIX, where the name has to indicate a file, questions of filename syntax arise. In all cases, 'Program' can specify an explicit file in the syntax accepted by the target machine, eg 'SYSDISK1:[KS.PROGS]FRED' for VMS ('.EXE' being assumed), or '/home/aaossc/ks/progs/fred' for UNIX (no extension assumed). In most cases, programmers will prefer to use some more flexible way of specifying the file. So under VMS one could use 'EXE_DIR:FRED' where EXE_DIR is a logical name pointing to the directory containing FRED.EXE. UNIX has no such built-in facility, but to provide the required flexibility the IMP system under UNIX will interpret the string 'exe_dir:fred' as meaning the program 'fred' in a directory equated to an environment variable (as defined for the IMP_Master task) called 'exe_dir'. Note that IMP passes such names to the underlying system without any changes to case. This means that the string like 'exe_dir:fred' could be understood by IMP systems running on all of VMS, UNIX and VxWorks. A string such as 'fred' will be taken under UNIX to refer to a file called 'fred' in the PATH as defined for the IMP_Master task. Under VMS, 'fred' will be taken to be either a file called 'fred.exe' in the default directory for the IMP_Master task. Alternatively, under VMS - again to provide increased flexibility - 'fred' can be defined as a symbol causing a program to be run, so long as this symbol is defined for the IMP_master task. If parameters are to be passed directly to a task run under VMS, it has to be run in this way.

In summary, it is possible to set up the IMP_master task on all systems so that a simple name, eg 'fred' can be used as the taskname, or so that a name apparently involving a symbolic reference to a directory eg 'exe_dir:fred' can be used. Alternatively, for systems that have file systems, a full system-specific file specification can be provided.

Argument strings

The argument string is a character string containing an argument string to be passed to the task to be run. In many cases this is expected to be null, the message system being used to communicate with the task. In some cases, however, particularly where a general purpose program (one that does not use IMP) is being run, the argument string can be used to pass arguments to it. The IMP system will pass the argument string on to the task in as unchanged a form as possible, but this will in practice vary with the system in use. Under VMS, the string can be passed to the program unchanged, so for example, 'Program' could be 'DELETE' and 'ArgString' could be '/NOCONFIRM SCRAP.DAT;*'. Under UNIX the string will be split into separate arguments (separated by spaces, allowing for strings in double or single quotes) and these passed to the task. So under UNIX 'Program' could be 'rm' and 'ArgString' could be '-i scrap.dat'. Note that IMP will not interpret characters such as '*', as a UNIX shell would. Systems such as VxWorks where the task that is run is a subroutine that has to be called directly will normally have the argument string passed as a single character string. If the string is to be interpreted as a set of numeric and/or character values, the DITS_ARG_SPLIT flag should be specified - see below.

Possible flag values

The following bit masks are defined in DitsInteraction.h, and have the following effects if used to set bits in the Flags argument:

DITS_M_ARG_SPLIT For VxWorks type tareget systems only. TaskParams.Decode should be a string similar to that used by printf(), containing %d, %f and %s codes to indicate how the argument string is to be interpreted in order for the arguments to be passed to the task.

DITS_M_REL_PRIO If specified, TaskParams.Priority will be an integer used to set the priority of the loaded task relative to the priority of the IMP_Master task. A positive number will give the loaded task a priority that is higher than that of the master task, a negative number will give a lower priority. (The master task may be limited in the priority it can assign to a loaded task, particularly if asked to run it at high priority. Normally, tasks are loaded at the same priority as the master task.

DITS_M_ABS_PRIO If specified, TaskParams.Priority will be an integer used to set the priority of the loaded task in an absolute way. To use this the caller will have to know the priority conventions used by the target system.

DITS_M_SYMBOL Used where the target system is a VMS system to cover any ambiguity in the interpretation of a 'Program' string as either the actual name of a program to be executed or a symbol that causes a program to be executed. If this is set, it forces the string to be interpreted as a symbol.

DITS_M_PROG Used where the target system is a VMS system to cover any ambiguity in the interpretation of a 'Program' string as either the actual name of a program to be executed or a symbol that causes a program to be executed. If this is set, it forces the string to be interpreted as a program name. (The difference is that a program name needs to be run using a spawned RUN command, or - if no arguments are to be passed to it, by a direct call the the VMS $CREPAR system routine.)

DITS_M_NAMES Used to control the inheritance of symbols (logical names and symbols under VMS, environment variables under UNIX) by the new task. If specified, this flag insists that symbols known to the IMP_Master task be inherited by the new task. If not set, it is at the discretion of the master task whether this is done.

DITS_M_SET_BYTES If specified TaskParams.Bytes is a byte count value used to specify the amount of memory to be used by the task. This is currently only supported by VxWorks, where it is used to specify the stack size for the task. If not specified, a default size will be used.

Other flags will be included as they prove to be needed.

TaskParam fields

The TaskParam structure supplies the following fields. Not all are needed in all cases, but ProcName should normally be set. The rest depend on the settings of the various Flags bits.

TaskParam.ProcName is a character string used to supply a name for the task to be created. Not all systems support giving names to individual processes, but those that do usually insist that one be supplied and that it be unique. Note that this is a 'system' name, used by the operating system, and is not the name under which the loaded task will register with the IMP system (assuming it does so).

TaskParam.Decode is an argument decoding specification string used only if the DITS_ARG_SPLIT flag is set in Flags. See the description of this flag for more details.

TaskParam.Priority is a priority specification used only if either the DITS_ABS_PRIO flag or the DITS_REL_PRIO flag is set in Flags. See the description of these flags for more details.

TaskParam.Bytes is a byte count value used to specify the amount of memory to be used by the task. At present this is only supported by VxWorks where it specifies the task size for the task.

Include files

DitsInteraction.h

External functions used

ImpRunTask	Imp	Run a task

External values used

DitsTask = Details of the current task.

Prior requirements

Should only be called from a Dits application routine or when the context is DITS_CTX_UFACE.

Support

Tony Farrell, AAO

Click here for the DRAMA home page and here for the AAO home page.

For more information, contact tony.farrell@mq.edu.au