chips

Starting ChIPS

From the CIAO command line, type:

unix% chips [-x|-b|-l|-n] <file>

Any or all of the following options which may be supplied when ChIPS is started:

• -x : launch chips shell in separate display terminal.
• -b : runs ChIPS in batch mode; see the "Running ChIPS in batch mode" section for details.
• -l : specifies which language to use, "slang" or "python".
• -n : prevents the ChIPS banner from being displayed on startup.
• <file>: a file of S-Lang or Pythong ChIPS commands to execute

The startup script loads the ChIPS module, as well as the CRATES module, which handles file input and output ("ahelp crates").

The language to use - S-Lang or Python - is determined by the hierarchy:

• language specified by the "-l" command-line option
• CHIPS_SCRIPT_LANG environment variable.
• CIAO_SCRIPT_LANG environment variable (see "ahelp ciaorc")
• "chips.shell" preference in the $HOME/.chips.rc file
• if none of the above are set, default to PYTHON

The "Starting ChIPS" thread has more details.

The ChIPS Resource File: .chips.rc

When ChIPS is started - either directly by the "chips" command or from another CIAO application such as Sherpa - it processes the $HOME/.chips.rc resource file. The resource file specifies attribute settings for the ChIPS commands and can be customized to the user's preferences; refer to "ahelp chipsrc" for details.

Getting Help

There are several ways to access the ChIPS help files.

From the CIAO command line

o) Syntax, description and examples for a specific command:

unix% ahelp <command>

List of all ChIPS help files by syntax:

unix% ahelp -c py.chips

or

unix% ahelp -c sl.chips

From Python or S-Lang

Within Python or S-Lang, ahelp or the native help system can be used.

o) Python:

chips> ahelp("<command>")

chips> !ahelp <command>

chips> help <command>

o) S-Lang:

chips> ahelp("<command>");

chips> !ahelp <command>

chips> help <command>

Loading the ChIPS Module

Loading Modules in Python

To import the ChIPS and CRATES modules in Python without using the "chips" startup script:

from pychips import *
from pychips.hlui import *
from pycrates import *

The pycrates module is only needed if you want to use any of its routines for reading files ("ahelp -c py.crates").

Loading Modules in S-Lang

To import the ChIPS and CRATES modules in S-Lang without using the "chips" startup script:

require("chips_hlui");
require("crates");

The crates module is only needed if you want to use any of its routines for reading files ("ahelp -c sl.crates").

Loading Advanced ChIPS Functions

In CIAO 4.1, a number of ChIPS functions were moved into a separate module of advanced commands. These functions are primarily those whose capability is available from a higher-level ChIPS command; for instance, set_line_color() was moved because its functionality is available from the set_line() function. More advanced undo/redo commands (e.g. using undo and redo buffers) and software error handling commands were moved to this module as well.

Users who wish to access the advanced commands simply have to load the additional module into ChIPS:

In Python

To import the advanced ChIPS module in Python:

from pychips.advanced import *

In S-Lang

To import the advanced ChIPS module in S-Lang:

require("chips_advanced");

Running ChIPS in batch mode

If ChIPS is invoked with the batch-mode option, e.g. "chips -b", the "window.display" preference will be set to false. To have the display on, include a set_preference call at the beginning of the script to set "window.display" to true. In addition, if a connect command is issued within the script, it will automatically disconnects from the chips server if it is attached to one.

ChIPS always requires the presence of a X server, even when used in a script or program which does not produce on-screen plots (e.g. the "window.display" preference has been set to "false"). When a ChIPS server is started, it tries to connect to the X-display indicated by the DISPLAY environment variable, which can result in one of three cases:

DISPLAY environment variable is valid

In this case the ChIPS server will use the indicated X display for its plots.

DISPLAY environment variable is invalid or unset

If the server can not connect to the X display - e.g. the DISPLAY variable is not set or is invalid - then it will try to start up a temporary, virtual, framebuffer using the Xvfb program. If this works then the ChIPS commands will work, including calls to print_window(), but there will be no on-screen display.

No DISPLAY and no Xvfb

If the Xvfb program does not exist on your system then the server will fail to start up and report the following:

chips ERROR: Failed to open DISPLAY or Xvfb session- exiting chipsServer

Starting Xvfb manually

If you know that your program is going to be run with no active X display then you can set up Xvfb manually, and use it, rather than let ChIPS fall through to using it as described above. A simple example follows:

unix% Xvfb :9 &
unix% setenv DISPLAY :9

after which any program using ChIPS will use the virtual frame buffer. This is particularly useful if you plan to run multiple programs or scripts that use ChIPS, since the server will not have to spend time setting up Xvfb itself.

Client-Server interaction

ChIPS is implemented as a client-server system, which allows multiple clients to connect to a single server, as highlighted below. However, by default, the system is set up to use a single client per server, and you can have many servers running at the same time, which means that the following is only needed for advanced applications.

Starting a server

When the ChIPS module is loaded into a Python or S-Lang session then the client code is loaded. If no server has been joined or created, then the first ChIPS call that requires a server - which is most commands - will automatically start up a new server instance. Alternatively, the connect() routine can be used to connect to an existing servre, or the create_server() routine will start up a new server.

Finding servers

The list_servers() and check_server_exists() commands are used to find out about existing servers. Applications that use ChIPS - such as Prism - may also provide information on the server they are using.

Changing servers

The disconnect() call will stop the connection between a client and server. Note that a ChIPS server will automatically exit when it has no more clients connected to it.

Using multiple clients

If multiple clients are connected to a server then there is the possibility of a race condition if commands from the different clients are sent at the same time. To avoid this a client can use the lock() command to ensure that it will be the only one talking to the server, since any access by other clients during a lock will hang. The lock is broken by the locking client either calling unlock() or closing down. Note that there is no way to tell if a server is locked without trying to access it and seeing if the request hangs.

CHANGES IN CIAO 4.1

Startup Options

There are four command-line options which may be specified when ChIPS is started: -x (new xterm), -b (batch mode), -l (select language), and -n (no banner); see the text for details.

Module changes

A new module has been added which contains "advanced" routines, as described above in the section "Loading Advanced ChIPS Functions".

Batch Mode Changes

If ChIPS is invoked with the batch-mode option, e.g. "chips -b", the "window.display" preference will be set to false. To have the display on, include a set_preference call at the beginning of the script to set "window.display" to true. In addition, if a connect command is issued within the script, it will automatically disconnects from the chips server if it is attached to one.