Class Documentation
Run |
1.0 |
ID_RUN |
Unspecified |
Command |
April 2004 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2004. All rights reserved. |
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.
FOREIGN | If 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. |
WAIT | If 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:
EDIT | Edit mode is used for running an application that can edit the data file. |
OPEN | Open 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. |
VIEW | View 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".
|
|