Starting ChIPS

From the CIAO command line, type:

unix% chips

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

The script determines whether to use S-Lang or Python based on the "chips.shell" preference in the $HOME/.chips.rc file or the CHIPS_SCRIPT_LANG environment variable. The "Starting ChIPS" thread has more details, including how to set these values.

Loading Modules in Python

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

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").

Getting Help

There are several ways to access the ChIPS help files.

From the CIAO command line

o) Python syntax, description and examples for a specific command:

unix% ahelp py.chips <command>

List of all ChIPS Python help files:

unix% ahelp -c py.chips

o) S-Lang syntax, description and examples for a specific command:

unix% ahelp sl.chips <command>

List of all ChIPS S-Lang help files:

unix% ahelp -c sl.chips

Users can create an alias for ahelp to default to one syntax. To always access Python syntax, for instance:

unix% alias pyhelp "ahelp py.chips"
unix% pyhelp add_curve

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 py.chips <command>

chips> help <command>

o) S-Lang:

chips> ahelp("<command>");

chips> !ahelp sl.chips <command>

chips> help <command>

Running ChIPS in batch mode

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 muany 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.