Chapter 6 Wrapped Class Reference

6.5 External Processes

The External Processes (XT) wrapped classes are designed to allow the user of ADL to have access to other computational processes outside of AM2. This function can even allow AM2 to spawn other applications and send them input and output. Documentation for the following classes appear in this section:

Note that the class inheritance tree diagram for the External Commands (XT) wrapped classes is flat, meaning that that these classes do not have superclasses, thus no inheritance diagram is provided here.

6.5.1 XTcommand

This class implements the execution of an external command in a fashion similar to the UNIX "system" routine.

Superclasses

Section 6.1.2, "Activity Manager - Abstract" page 116

Section 6.1.3, "Attribute Manager - Abstract" page 118

Methods

upon Create: list cmd

Executes the command specified in the argument cmd. This constructor blocks on the execution of the external command. The list cmd must be a list of strings with at least one element. The first string on the list represents the command name, and the following elements, if present, represent command line arguments. The interpretation of the command list is platform dependent and is normally left to the standard platform execution environment. Under UNIX, this would be the user's shell.

upon CreateNoBlock: list cmd

Executes the command specified in the argument cmd asynchronously. Under UNIX, this corresponds to executing the command "in the background". This constructor does not block on the execution of the external command. The argument must be formatted as in the Create method.

on Abort

Kills an external command initiated with the 'CreateNoBlock constructor. This method executes in a platform dependent manner, and it does not guarantee smooth termination or cleanup of the external command. The spawned external command should normally be terminated through their own interface.

on Done: return boolean

Returns TRUE if the external command has terminated and FALSE otherwise.

on GetStatus: return integer

The returned value is a status variable indicating the success or failure of the external command. The value 0 indicates successful execution on all platforms; non-zero values are platform dependent error codes. If an UNSET value is returned, then the external command has not terminated, i.e., in the cases in which the 'Done message would return FALSE.

Attributes

None

Activities

None

Example

1 /* Demonstrates the use of XTcommand to run external programs */

2 anonymous: XFtop

3 {

4 XFbutton but1

5 { x=20; y=100; width=400; height=40;

6 label="Create Non Blocking External Process";

7 };

8 XFbutton but2

9 { x=20; y=200; width=400; height=40;

10 label="Create Blocking External Process";

11 };

12 upon Construct

13 { width=440; height=350;

14 but1.Pressed = {'but1Pressed, self};

15 but2.Pressed = {'but2Pressed, self};

16 }

17 on but1Pressed

18 { /*This creates a Telnet Session on Windows*/

19 new {'CreateNoBlock, {"telnet"}} => XTcommand;

20 }

21 on but2Pressed

22 { /*This creates a Telnet Session on Windows*/

23 new {'Create, {"telnet"}} => XTcommand;

24 }

25 }top;

6.5.2 XTprocFilter (only on UNIX)

This class implements the execution of an external command that functions as a co-process to the ADL script creating the XTprocFilter. That is, it both reads a stream generated by the calling ADL script and generates an output stream read by the script.

Superclasses

None

Methods

upon Create: list cmd

Executes the command specified by cmd in such a way that the input to and output from the command is tied to a read-write IOpipe whose handle is stored in the member hPipe.

on Abort

Kills the external command. This should not be the standard method of terminating the external process. Normal termination should be triggered by closing the IOpipe pointed to by hPipe.

on GetStatus: return integer

The returned value is a status variable indicating the success or failure of the external command. The value 0 indicates successful execution on all platforms; positive non-zero values are platform dependent error codes. 'GetStatus returns UNSET if one of the IOpipes to or from the external process is still open. This return value except in the UNSET case is identical to the value returned by 'Close => hPipe once the pipe has closed.

Attributes

None

Activities
XTprocFilter Activities
ActivityKeysDescription
hPipehandlehandle to the IOpipe object opened when the XTprocFilter was created

Example

None

6.5.3 XTprocSink (only on UNIX)

This class implements the execution of an external command that reads a stream generated by the calling ADL script. It thus resembles the UNIX popen routine in "w"rite mode.

Superclasses

None

Methods

upon Create: list cmd

Executes the command specified by cmd in such a way that the input to the command is tied to a writable IOpipe whose handle is stored in the member hTo.

on Abort

Kills the external command. This should not be the standard method of terminating the external process. Normal termination should be triggered by closing the IOpipe pointed to by hTo.

on GetStatus: return integer

The returned value is a status variable indicating the success or failure of the external command. The value 0 indicates successful execution on all platforms; non-zero values are platform dependent error codes. 'GetStatus returns UNSET if the IOpipe to the external process is still open. This return value except in the UNSET case is identical to that returned by 'Close => hTo if the pipe has already been closed.

Attributes

None

Activities
XTprocSink Attributes
ActivityKeysDescription
hTohandlehandle to the IOpipe object opened when the XTprocSink was created

Example

1 // Decode a rot-13 message using tr, a standard UNIX utility

2 XTprocSink { 'Create, { "tr", "a-zA-Z", "n-za-mN-ZA-M" } }

3 => myOutFilter;

4 integer status;

5 myOutFilter.hTo << "Zrffntr va n obggyr" << Endl;

6 status = 'Close => myOutFilter.hTo;

6.5.4 XTprocSource (only on UNIX)

This class implements the execution of an external command that generates an output stream read by the calling ADL script. It thus resembles the UNIX popen routine in "r"ead mode.

Superclasses

None

Methods

upon Create: list cmd

Executes the command specified by cmd in such a way that the output from the command is tied to a readable IOpipe whose handle is stored in the member hFrom.

on Abort

Kills the external command. This should not be the standard method of terminating the external process. Normal termination should be triggered by the external process itself and should be sensed by detecting an EOF on the pipe associated with hFrom.

on GetStatus: return integer

The returned value is a status variable indicating the success or failure of the external command. The value 0 indicates successful execution on all platforms; non-zero values are platform dependent error codes. 'GetStatus returns UNSET if the IOpipe from the external process is still open. This return value except in the UNSET case is identical to the value returned by 'Close => hFrom once the pipe has closed.

Attributes

None

Activities
XTprocSource Attributes
ActivityKeysDescription
hFromhandlehandle to the IOpipe object opened when the XTprocSource was created

Example

None

6.5.1 - XTcommand
Superclasses
Methods
Attributes
Activities
Example
6.5.2 - XTprocFilter (only on UNIX)
Superclasses
Methods
Attributes
Activities
Example
6.5.3 - XTprocSink (only on UNIX)
Superclasses
Methods
Attributes
Activities
Example
6.5.4 - XTprocSource (only on UNIX)
Superclasses
Methods
Attributes
Activities
Example
AM2 Documentation - 19 NOV 1996

Generated with Harlequin WebMaker