Using the child task

If the child task has a visible session window associated with it, you can enter commands and APL expressions in it in the normal way. Alternatively, the parent APL task can use it as follows:

Checking the status of the child task:

The status read-only property indicates the execution state of the task. It returns one of the following codes:

¯1 The task is not running (i.e. it has not been opened, or has terminated)

0 The task is busy executing an APL expression or command

1 The task is in desk-calculator mode, awaiting input

2 The task is awaiting ⍞ input

3 The task is awaiting ⎕ input

4 The task is awaiting ⎕CC input

Causing the child task to execute an expression or command

The Execute method allows the parent to cause the child task to execute an APL expression or system command. It takes as an argument a character string which the command to be executed (or passed as input to ⍞ or ⎕).

The child task should be awaiting input (you can tell whether this is the case by reading the status property, or by using the onReady callback). If it is not, the command will be placed in a buffer and will be executed when the child task next asks for input. However, there is no queue of commands held; any existing command already in the buffer will be over-written if the child task has not yet executed it. The Execute method returns immediately; it does not wait for the command to complete.

In this example, the child task is initially ready for input. It then executes the )LOAD command, and is busy for a short time (status property is 0). The status property then changes back to 1 when it is ready for further input:

      ChildTask.status
1
      ChildTask.Execute ')LOAD 10 SAMPLEEXCEL'
      ChildTask.status
0
      ChildTask.status
1

Note that in a real multi-tasking APLX application you would typically use 'signal' events to allow the parent and child tasks to communicate with each other and synchronize their operations - this is described below. The Execute method would typically be used only when starting up the child task.

Reading back the child task's session window contents

The text property of the APL object contains the text in the task's session window (assuming it is not a background task). For example, after executing the )LOAD above you might have:

      CONTENTS←ChildTask.text

      CONTENTS
CLEAR WS
      )LOAD 10 SAMPLEEXCEL
SAVED  2002-09-12 16.43.21
APLX for Windows and Excel Sample - 18th July 2002
--------------------------------------------------
This workspace contains some functions to demonstrate how to use APLX to
access Excel spreadsheets via the Microsoft Excel OLE server.

... etc

It is a text vector, usually with embedded carriage return (⎕R) characters. The text property returns the logical contents of the session window, even if the session window is not visible (however it is always an empty vector for a background task, which does not have a session window). You can also write to this property to change the text in the session window of a child task.

Uniquely identifying a child task

Every task has a unique identifier. You can read the task identifier of a child task using the read-only taskid property. It is a scalar integer, and can be used in event handling to identify the task:

      ChildTask.taskid
53429272

The taskid property will be zero if the task is not running.

The child task can read its own task identifier using the taskid property of its System object.

Interrupting a child task under program control

If a child task is executing (status property is 0), the Interrupt method can be called to interrupt it. It is equivalent to a keyboard interrupt (break).

Terminating a child task under program control

A child task may terminate for various reasons. For example, you might use the Execute method to cause it to execute an )OFF command, or it may run an APL function which ends by executing an )OFF. If it has a session window, you can end the task in the same ways as you would a top-level task, using the File menu or by closing the session window.

Alternatively, a parent task can terminate the child by using the Close method:

      ChildTask.Close

This closes any windows belonging to the task, releases the workspace memory, and ends the task. The status property reverts to ¯1. If you wish you can then use the Open method to start it afresh, or the Delete method to destroy the task object altogether (or erase the last reference to it in the workspace).

If a parent task terminates, all its child tasks are automatically terminated as well.