Description

This module contains all the standard function calls that can be made in the context of a compass-style script.

Functions

executeprocedure(exename, runfiledir, runfilename)

Utility, executes the executable against the run file.

Assuming that the runfile is dumped into the project directory. It starts a search for the executable with in this order:

1. local directory
2. project directory
3. METLIB directory

If we are unable to locate the executable, we simply run it without an explicit directory, and rely on the fact generally %MEDEXE% is on your path.

This function is equivalent to making the following call:

<path>\<exename> /f<runfilename>

Where the <path> was determined by the above rules.

Arguments:

exename : string

Name of the executable.

runfiledir : string

The directory to perform the execution within.

runfilename : string

Name of the run file to pass to the executable.

fromcommandline(argv, mainfn)

Utility to allow you to run compass-style procedures from the command line.

This function also goes ahead and attempts to read the command line arguments for various options. When executing the procedure from the command line use --help (-h) for a usage message.

You can also see the help message by inspecting cmpsys.COMMANDLINE_USAGE.

Arguments:

argv : list of strings

The sys.argv [1] variable's contents.

mainfn : function

A reference to your scripts gmain function

Returns:

0	Indicates the user simply quit the panel-application window.
1	Indicates that the user wanted to execute their procedure against the sub-routine

Side-effects:

If a -h or --help option is found in the command line arguments, the program will display an usage message to sys.stdout, and the script will terminate via a sys.exit(0) call.

If an unknown option is found in the command line arguments, the program will display an usage message to sys.stderr, and the script will terminate via a sys.exit(-1) call.

If an program error occurs, such as selecting an invalid project file with the command line option or anything else, then a sys.exit(-2) is generated.

getfilelistbytype(type)

Returns a list of files for a given type.

This examines the Project Control File (PCF) and the project directory to return a listing of files for a given type.

So for example, say the PCF had the following file 15s listed in it,

• test15.dat
• test15.blt
• test15.slt

But the project directory only had the test15.blt file located in it, then a call to this function would return,

["test15.blt"]

This is useful, since most of the time a user may have only copied a select list of files that are described within the PCF's file 15 list.

getmetlibdir()

Returns the location of the METLIB directory. The location is determined by the METLIB environment variable. If the environment variable is not defined, then an empty string ("") is returned.

getmode()

For internal usage only. Returns the current mode.

getpanel(panelname)

Retrieves a panel reference from the currently active procedure based on the title (or panelname) of that panel.

There are two major assumptions that are made when you call this function:

1. That the panel has already been constructed. The order of construction is not guaranteed, so its best not to call this function within the context of GPanel.makewidgets().
2. That there is an active procedure window open. When the procedure window closes, all resources are released, which implies that we can no longer access the panels.

This function could generate either a

• GWidgetError if no panel exists with that panelname.
• AttributeError if the application is not running.

getpcf()

Returns the current Pcf object used by the grail compass system.

getproject()

Returns a ProjectInfo reference for the currently active project.

getrunfilepath()

Returns the directory location for the run file.

gmain(message, data)

Standard compass gmain.

Note

That the grailmain function defined in the grail.gsys module will automatically select this function and all its configuration options, if and only if you are running within a compass application.

In other words, you do not need to insert any reference to this function within your script.

isgo()

Indicates if a procedure was a go (1) or not (0).

ismultirun()

Predicate indicates if we are in multi run mode or not.

ismultirunsetup()

Predicate indicates if we are in multi-run setup mode or not.

itemlistforfile(filename)

Returns a sorted list of items for the given filename assuming that filename is part of the current PCF. If the filename is not part of the filelist expect a PcfError to be generated.

runprocedure(procfilename, proctitle, panellayout[, startpanel, version, copyright, aboutphotoimage])

Starts the procedure's window and event loop.

Arguments:

procfilename: string

The name of the procedure, typically sys.argv[0] [1].

proctitle : string

Title of your procedure.

panellayout : GFolder

The layout structure for the panel application, using the grail.widgets.GFolder and grail.widgets.GItem.

startpanel : string

Optionally specify, currently by title, the name of the first panel you want to display. Default is not to display any first panel.

version : string

A string indicating the version (for the about window).

copyright

Copyright notice (for the about window).

aboutphotoimage

A Tkinter.PhotoImage [2] object (for use in the about window).

setmode(mode)

For internal use only. Sets the execution mode: standard, multi-run, or multi-run-setup. Valid arguments are: message.STANDARD, message.MULTIRUN, or message.MULTIRUN_SETUP.

setproject(path)

Sets the compass system's project and Project Control File (PCF) based on the info in the path.

startmxepert(mxpertstring)

Will take the mxpertstring and insert it into a batch file. The batch file will have a :mxend label, and will set minteract equal to "on" at the start, and equal to nothing at the end. For example, the following string,

REM this is a test.

will generate the following batch file,

set minteract=on
REM this is a test
:mxend
set minteract=

If your compass style script is being executed from the command line, then you will need to use this function in order to execute the contents of your mxpert string.

stdinipath()

Returns path to the grail procedures configuration file.

Location is determined by examining the User's ROOT_DIR. The grail procedures configuration filename is defined by this modules CMPSYS_USR_FILE constant.

Exception

exception CompassError

Defines the standard error from the compass package.

Data

CMPSYS_USR_FILE

Defines the name of the standard procedure INI file name.

COMMANDLINE_USAGE

Defines the command line usage. This message is displayed if,

1. A compass-style script is created.
2. The script uses fromcommandline().
3. The user types --help (-h) to display the usage message.