Class Documentation

Name:Run
Version:1.0
ID:ID_RUN
Status:Unspecified
Category:Command
Date:April 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2004. All rights reserved.
Short:  The execute class runs native binary programs.



Description

The Run class allows you to launch binary files that are stored in the file system. Executable files must be native to the system that Athene is running on. For example, if you are running Athene on a Linux system, the Run class will allow you to run X11 programs and popular applications such as Netscape.

The Run class is not restricted to launching executable files. For instance, you can launch picture, text and custom file types. The exact behaviour that occurs when launching a data file is dependent on the settings found in the user's "user:config/associations.cfg" file, which holds the launch settings for each registered class and file type. In most cases a script will be run which can handle the file data.

Typical usage of the Run class in a DML script is demonstrated in the following examples:

   <run src="netscape"/>
   <run mode="view" src="pictures:screenshot.png"/>

If you need to send arguments to an executable file, use the Args field as in this example:

   <run src="myprogram" args="arg1 arg2 arg3"/>

Like all commands, you may make a run object static if you want it to be activated in response to system events.

Actions

The Run class supports the following actions:

Activate  Activates a Run object.
ClosingTag  If the object is non-static, this action will start the execution process and then the object will self-destruct.

Structure

The Run object consists of the following public fields:

Args  Set this field to send the executable program a range of arguments.
Flags  Defines special options to use when running programs.
Location  Defines the location/name of the executable program.
Mode  The type of launch mode to use when launching data files.
ReturnCode  The code returned from the running process is stored here.
Static  Set to TRUE to make the object static.
TimeOut  Defines the maximum amount of time to wait for a process to return.
Type  The class or filetype association to use for running the target file.
Field:Args
Short:Set this field to send the executable program a range of arguments.
Type:STRING
Status:Read/Write

If the executable program accepts arguments, then you may send them to the program by setting this field.


Field:Flags
Short:Defines special options to use when running programs.
Type:LONG
Status:Read/Init

Optional flags that affect the behaviour of the Run class may be specified in this field.

FlagDescription
FOREIGNIf the program that you are running is not native to Athene or Pandora then you must set the FOREIGN flag so that the system does not attempt to treat it as a native program.
RESETDIR  Normally when a program is launched, it will start in the same directory as your own process. If you would rather that the program starts in the same directory as its executable, set the RESETDIR flag.
WAITIf this option is set then your task will be stop and wait for the other program to finish when launched. This can be very useful when running batch scripts. See the TimeOut field if you wish to limit the amount of time that you are prepared to wait.

Field:Location
Synonyms:Src
Short:Defines the location/name of the executable program.
Type:STRING
Status:Read/Write

It is compulsory that this field is set to the location of the executable program that you wish to run. Directory assigns are fully supported, so you may use this file-system feature in specifying the location.

If you are running Athene on a Unix system then you should know that the PATH variable is supported, so you do not need to fully-qualify the location if it is in the path.


Field:Mode
Short:The type of launch mode to use when launching data files.
Type:LONG
Status:Read/Write

The Mode field determines the type of action that will be performed when running a data file. The default mode is 'Open', which will open the data file in the preferred user mode (in most cases a viewing application will be loaded for this purpose). Other mode types that are available to you are listed in the following table:

ValueDescription
EDITEdit mode is used for running an application that can edit the data file.
OPENOpen mode will open the file in a way that is appropriate for the data in question (for instance, opening an audio file will play the audio data).
PRINT  Print mode is used to instantly print a data file to the default printer. Printing can only be used on data files that have some form of visual representation.
VIEWView mode is used to view the file data in the user display. This mode can only be used on data files that have some form of visual representation.

Field:ReturnCode
Short:The code returned from the running process is stored here.
Type:LONG
Status:Read/Init

If you need to know the return code of a process after it has finished running, you can read the ReturnCode field. You will need to specify the WAIT flag as an option, as the return code can only be retrieved if you wait for the process to finish.

If the return code value is unobtainable, this field returns a default value of 0. You can change the default return code by writing this field prior to initialisation.


Field:Static
Short:Set to TRUE to make the object static.
Type:BOOLEAN
Status:Read/Init

By default, a run object will activate itself and then self-destruct when a closing tag is received. If you would rather that the object stays in the system, set this field to TRUE. If you do this, the only way to get the run object to perform is to call the Activate() action.


Field:TimeOut
Short:Defines the maximum amount of time to wait for a process to return.
Type:FLOAT
Status:Read/Set

The Run class gives you the option to wait on a process until it returns. By default the code will wait indefinitely, but you can prevent this by setting the TimeOut field to the number of seconds that you are prepared to wait for the process to return. If the TimeOut is reached, the ReturnCode field will be set to ERR_TimeOut. The process will be allowed to continue running in the background if it does not complete within the timeout period.

The timeout value is measured in seconds and is cast as floating point so that you can achieve sub-second precision. By setting the TimeOut to any value other than zero, you will automatically enable the WAIT flag option.


Field:Type
Short:The class or filetype association to use for running the target file.
Type:STRING [32]
Status:Get/Set

By default the Run class will examine target files to determine their type before launching the program that handles that data type. This is not always a viable method of execution however - trying to run a browser for a file location such as http://localhost/ for instance will fail. You may also have good reasons for running a program associated with a particular filetype but don't want to actually load any file into the program on startup.

To manage either instance you will need to set the Type field to the name of the class or file association that handles the file type (for a list of preconfigured file associations please check the system:config/software/associations.cfg file). In the aforementioned browser example, the correct Type setting would be "HTML".