This field provides direct access to the actions of a task, and is intended for use with the active task object returned from CurrentTask(). Hooking into the action table allows the running executable to 'blend-in' with Parasol's object oriented design.

The Actions field points to a lookup table of ActionEntry items. Hooking into an action involves writing its AC index in the table with a pointer to the action routine. For example:

if (!AccessObject(CurrentTask(), 5000, &task)) {
   task->getPtr(FID_Actions, &actions);
   actions[AC::Seek] = PROGRAM_Seek;
   ReleaseObject(task);
}

This field allows command line arguments to be set using a single string, whereby each value is separated by whitespace. The string will be disassembled and the arguments will be available to read from the Parameters field.

If an argument needs to include whitespace, use double-quotes to encapsulate the value.

The ErrorCallback field can be set with a function reference that will be called when an active process sends data via STDERR. The callback must follow the prototype Function(*Task, APTR Data, LONG Size)

The information read from STDERR will be returned in the Data pointer and the byte-length of the data will be indicated by the Size. The data pointer is temporary and will be invalid once the callback function has returned.

The ExitCallback field can be set with a function reference that will be called when the executed process is terminated. The callback must follow the prototype Function(*Task).

Please keep in mind that if the Task is freed when the process is still executing, the ExitCallback routine will not be called on termination because the Task object no longer exists for the control of the process.

The InputCallback field is available to the active task object only (i.e. the current process). The referenced function will be called when process receives data from STDIN. The callback must follow the prototype Function(*Task, APTR Data, LONG Size, ERR Status)

The information read from STDOUT will be returned in the Data pointer and the byte-length of the data will be indicated by the Size. The data buffer is temporary and will be invalid once the callback function has returned.

A status of ERR::Finished is sent if the stdinput handle has been closed.

Use the LaunchPath field to specify the folder that a launched executable will start in when the task object is activated. This will override all other path options, such as the RESET_PATH flag.

When a task object is activated, the Location field will be checked for a valid filename. If the path is valid, the executable code will be loaded from this source. The source must be in an executable format recognised by the native platform.

Leading spaces will be ignored by the string parser. The Location string can be enclosed with quotes, in which case only the quoted portion of the string will be used as the source path.

This field specifies the name of the task or program that has been initialised. It is up to the developer of the program to set the Name which will appear in this field. If there is no name for the task then the system may assign a randomly generated name.

The OutputCallback field can be set with a function reference that will be called when an active process sends data via STDOUT. The callback must follow the prototype Function(*Task, APTR Data, LONG Size)

The information read from STDOUT will be returned in the Data pointer and the byte-length of the data will be indicated by the Size. The Data pointer is temporary and will be invalid once the callback function has returned.

Command line arguments for a program can be defined here as a vector list, whereby each argument is an independent string. To illustrate, the following command-line string:

1> YourProgram PREFS MyPrefs -file "documents:readme.txt"

Would be represented as follows:

pf::vector<std::string> Args = {
   "PREFS",
   "MyPrefs",
   "-file",
   "documents:readme.txt"
};

The Path specifies the 'working folder' that determines where files are loaded from when an absolute path is not otherwise specified for file access. Initially the working folder is usually set to the folder of the parent process, such as that of a terminal shell.

The working folder can be changed at any time by updating the Path with a new folder location. If changing to the new folder fails for any reason, the working folder will remain unchanged and the path value will not be updated.

Set the Priority field to change the priority of the process associated with the task. The default value for all processes is zero. High positive values will give the process more CPU time while negative values will yield CPU time to other active processes.

Note that depending on the platform, there may be limits as to whether one process can change the priority level of a foreign process. Other factors such as the scheduler used by the host system should be considered in the effect of prioritisation.

If a task object launches an executable file via Activate(), the ProcessID will be set to the 'pid' that was assigned to the new process by the host system. At all other times the ProcessID is set to zero.

The ProcessPath is set to the path of the executable file that is associated with the task (not including the executable file name). This value is managed internally and cannot be altered.

In Microsoft Windows it is not always possible to determine the origins of an executable, in which case the ProcessPath is set to the working folder in use at the time the process was launched.

Once a process has completed execution then its return code can be read from this field. If process is still running, the error code ERR::TaskStillExists will be returned.

This field can be set in conjunction with the WAIT flag to define the time limit when waiting for a launched process to return. The time out is defined in seconds.