NAME
ikp - icon processing system
SYNOPSIS (graphical startup script)
IKP [ -Luser net ]
SYNOPSIS (batch)
ikp [ -d display ] [ -b ] [ -B ] [ netfile ] [ -n ] [ -l
libfile ] [ -v level ]
DESCRIPTION
ikp is a graphical X11 interface which allows a user to
create and execute an arbitrarily connected process network
built from standalone programs. The program may also be exe-
cuted outside of the X11 window system by running it in
batch mode using a net configuration file which has been
previously created in interactive mode.
Each standalone program, or process, is represented by a
bitmap icon displayed in an X11 window. Each process may
have any number of input and/or output connectors represent-
ing data streams which are to be read from or written to by
the process. A connector is displayed as a small opening at
the border of the process icon together with an arrow indi-
cating the direction of data flow. Certain output connec-
tors, known as diagnostic connectors, are displayed with a
dashed arrow, and are generally used to output diagnostic
error messages.
A group of processes may be linked together into a net by
graphically connecting pairs of input and output connectors.
Connectors may be bound directly to disk files as well as to
other connectors. A net is deemed to be completely connected
when all of its input and non-diagnostic output connectors
have been either linked to other connectors in the same net
or bound to disk files. The connection of diagnostic outputs
is optional.
When a net has been completely connected, it may be exe-
cuted, meaning that all processes in the net will be run as
child processes of ikp with their inputs and outputs con-
nected to each other via pipes and sockets. Output from
unconnected diagnostic connectors is redirected to the con-
trolling terminal of ikp, i.e., the window from which ikp
was invoked. Individual processes within a net may be exe-
cuted on remote machines as well as on the local worksta-
tion, enabling the user to more effectively distribute the
computational load across a network.
In addition to supporting a small number of builtin process
types representing the most commonly used input/output con-
figurations, ikp maintains an internal database of both
site-wide and user-specific program libraries, which are
simply descriptions of external standalone programs. This
database, which contains a full description of the command
syntax of each program in the library, allows ikp to present
a more intuitive interface to the user and provide easy
access to available software with which the user may be com-
pletely unfamiliar. Support for on-line help regarding
individual programs is provided. The major seismic process-
ing library currently available is USP along with one migra-
tion before stack (MBS) library.
All of USP is available under ikp from tapes to reformatting
to final poststack processing. The processing modules are
listed under the general functional listings maintained in
the USP manual and in the X-windows functionality browser
xuspman. Some programs because of their general or multiple
usage can be found in several categories.
ikp could typically be used for such tasks as signal pro-
cessing, seismic waveform manipulation, or any other pro-
cedure which requires that a number of standalone modules be
interconnected to transform a group of input data sets into
a group of output data sets. Unlike most command inter-
preters such as sh or csh, which only permit a linear con-
nection of standalone programs via the stdin and stdout
streams, processes within ikp can be connected in any arbi-
trarily complex topology, including feedback loops, via
arbitrary data streams. This makes complex seismic process-
ing flows with a minimum of intermediate disk files a prac-
tical reality.
OPTIONS
-d display
Utilize the named X11 display. The default display is
the first screen of the host on which ikp is invoked.
-b Operate in batch mode, reading the net configuration
file specified on the command line and executing the
process network described therein. The program will
exit as soon as the process network runs to completion
or any child process stops or exits abnormally.
-B This option is identical to the -b option described
above, except that all child process stop and exit con-
ditions are ignored.
netfile
Read in the process network described by the net confi-
guration file netfile at initialization.
-n Do not use the default site program library file
/usr/lib/ikp/sitelib. This file is normally read at
initialization.
-l libfile
Read the named program library file at initialization.
Any number of such library files may be specified as
long as each one is preceded by the -l flag.
-v level
Specify a verbosity level for the printing of diagnos-
tic messages to stderr. The default value of 0
suppresses all such output, while higher values produce
a progressively greater volume of chatter. Specifying
any positive value will, for example, display the full
command lines of library processes whenever they are
constructed, a useful feature for the debugging of
user-created program library files.
USAGE
When invoked in its usual interactive mode, ikp is driven by
an X11 windowing interface. After initialization has com-
pleted, a large empty scrollable window is displayed within
which the user may construct any number of nets. Access to
all of the software's functionality is available via a pop-
up menu which is displayed by depressing the right mouse
button. This menu contains a number of submenus which are
displayed by dragging the mouse to the rightmost edge of the
main menu. The following paragraphs describe the purpose of
all menu options.
Net -> Select. ikp is capable of manipulating any number of
nets, and maintains a notion of a current net for certain
purposes. A particular net can be made the current net
either by selecting this option and then clicking the mouse
over any process icon in the net, or by performing any edit-
ing operation on any process within the net.
Net -> Run. Execute the current net. While a process within
the net is executing, its icon is displayed with a stippled
light grey pattern. If an executing process becomes tem-
porarily stopped for any reason, its icon will change to a
stippled dark grey pattern. When a process completes, its
icon will return to its original state. If a process is
killed or stopped by a signal, or returns an exit status
other than 0, its icon will be momentarily displayed in
reverse video and the user will be prompted to take an
appropriate course of action, e.g., ignore the event and
proceed, attempt to restart the process if stopped, or abort
all other processes in the net which are still running. Only
one net may be run at a time, and a running net may not be
edited in any manner whatsoever. (Operations on other nets
may be performed while a net is running.)
Net -> Read. Read a net configuration file and build a new
net from its contents. The upper left corner of the smallest
bounding rectangle containing the entire new net will be
placed at the location selected by the next mouse click.
After the position is selected, the user is prompted for the
name of the net configuration file to be read.
Net -> Write. Save the net containing the process icon
selected by the next mouse click into a net configuration
file. The user is prompted for the name of the file to be
written. If the saved process network is functionally com-
plete, it can be executed in batch mode at a later time by
invoking ikp with the appropriate command-line option.
Net -> Copy. Copy the existing net selected by the next
mouse click into a new net located at the position selected
by a second mouse click. All user-specifiable values main-
tained within the edit panels of the existing net will be
duplicated in the new net.
Net -> Stop. Temporarily suspend net execution by sending
each running process within the net a SIGSTOP signal.
Net -> Restart. Resume net execution by sending each
suspended process within the net a SIGCONT signal.
Net -> Abort. Terminate net execution by sending each run-
ning or suspended process within the net a SIGKILL signal.
Net -> Destroy. Destroy the entire net containing the pro-
cess icon selected by the next mouse click.
Process -> Create. Create a new process and display its icon
at the location selected by the next mouse click. When a
process is created it is logically placed in a net by
itself. As its connectors are linked to the connectors of
other processes, its net is merged with the nets of said
processes. A process is created with a fixed type of source,
sink, filter, tee, custom or library.
Process -> Create -> Source. A source process has a single
output connector which is mapped to its standard output and
a single diagnostic connector which is mapped to its stan-
dard error.
Process -> Create -> Sink. A sink process has a single input
connector which is mapped to its standard input and a single
diagnostic connector which is mapped to its standard error.
Process -> Create -> Filter. A filter process has a single
input connector which is mapped to its standard input, a
single output connector which is mapped to its standard
output, and a single diagnostic connector which is mapped to
its standard error.
Process -> Create -> Tee. A tee process copies all data read
from its single input connector onto each of its two output
connectors.
Process -> Create -> Custom. A custom process has a user-
specified number of input, output and diagnostic connectors.
After the user clicks the mouse over the location at which
the process icon is to appear, the user is prompted for the
number of connectors. When the process icon is displayed,
each connector is shown with the number of the file descrip-
tor to which it is mapped. Custom processes are frequently
used to invoke ikp_cat(1), which concatenates an arbitrary
number of input streams onto a single output stream.
Process -> Create -> [ Library ] -> [ Module ]. A library
process is completely detailed by a module description in
either the site program library file or some user-specified
program library file. This description tells ikp what com-
mand is to be run, what the available command-line options
are, which file descriptors are to be used for input and
output connectors, etc. For each library known to ikp, a
menu item is present within the Process -> Create menu which
accesses a pullright menu containing menu items correspond-
ing to each module description contained in the library.
Selecting an item from this pullright menu will create a
library process with the characteristics of the correspond-
ing module. The library process type is intended as a method
of providing easy access to software external to ikp without
requiring detailed knowledge of that software's command syn-
tax.
Process -> Edit. Clicking the mouse over a process icon
after selecting this option causes the process to be opened
for editing. A panel window is displayed which allows vari-
ous attributes of the process to be interactively set by the
user. The nature of these attributes is dependent upon the
type of the process.
A command string, remote execution host, remote user, work-
ing directory and icon label may be specified for source,
sink, filter and custom processes. The command string should
contain the name of the program to be executed by the pro-
cess together with any command-line arguments which that
program may accept. Note that this string is similar but
not identical to the string which you would type at a com-
mand interpreter such as sh or csh to execute the program,
the difference being that ikp does not attribute any special
meaning to such characters as <, >, *, $, etc. The only
metacharacters recognized by ikp within a process command
string are the single quote character ' , which may be used
in pairs to enclose argument strings containing blank
spaces, and the backslash character \ , which may be used to
escape both the single quote and itself. (In other words,
the behavior of these two special characters in this context
is similar to their behavior under csh.) The icon label is
displayed in the center of the process icon. If no icon
label is specified, the last pathname component of the pro-
gram name will be displayed in the icon.
A remote execution host and remote user may be specified for
a tee process. Remote execution of a tee may be useful in
minimizing network traffic when the tee is being used to
connect remotely executing processes. The buffering mode to
be used by the tee may also be selected. The default memory
buffering is almost always preferable, but special cir-
cumstances may require the use of file buffering (see
ikp_tee(1)).
Library process edit panels allow the specification of a
remote execution host, remote user, working directory, icon
label and command path prefix. The name of the program to be
executed is fixed, but its command-line arguments may be
specified by making appropriate selections from whatever
other panel items are present (these will vary depending
upon the particular module description used to create the
process.) A help button may be present to provide easy
access to help information if such is available. If no icon
label is specified, the program name will be displayed in
the icon. The command path prefix can be used to specify the
execution of some alternate version of the program, or to
specify an absolute pathname for an executable which is not
located in a directory contained within the user's search
path.
If the working directory of a process is not specified, the
process will be run in the directory in which ikp was
invoked. (This applies to both local and remote processes.)
Remote execution involves a number of issues such as machine
architecture and user environment. These questions are dis-
cussed in detail in a later section of this document.
Process -> Copy. Copy the existing process selected by the
next mouse click into a new process located at the position
selected by a second mouse click. All user-specifiable
values maintained within the edit panel of the existing pro-
cess will be duplicated in the new process.
Process -> Move. The display location of a process icon may
be altered by clicking the mouse over its icon after select-
ing this option. The icon may then be dragged by the mouse.
Click the right mouse button to fix the location and return
to the main menu.
Process -> Load. Read a process library file and append
appropriate pullright menus to the existing Process ->
Create menu to enable the creation of library processes
corresponding to module descriptions contained within the
file. The user is prompted for the name of the file to be
read. (The format of this file is described below.)
Process -> Stop. Temporarily suspend execution of the run-
ning process selected by the next mouse click by sending it
a SIGSTOP signal.
Process -> Restart. Resume execution of the suspended pro-
cess selected by the next mouse click by sending it a
SIGCONT signal.
Process -> Abort. Terminate execution of the running process
selected by the next mouse click by sending it a SIGKILL
signal.
Process -> Destroy. Destroy the process selected by the next
mouse click.
Connector -> Link. Link the two connectors selected by the
next two mouse clicks. Note that an input connector may only
be linked to an output connector and vice-versa. There is no
explicit prohibition against linking two connectors of the
same process.
Connector -> File. Bind the connector selected by the next
mouse click directly to a disk file. A popup window will
appear in which the user may enter the name of the file. If
the selected connector is an output connector, the user may
also specify whether the file, if preexisting, should be
rewritten from the beginning or extended from its current
end-of-file by toggling a truncate/append switch. A file
which is bound to a connector of a remote process will be
opened and accessed by the process on the remote machine -
if you want a remote process to access a local file, the
connector of the remote process should be linked to a local
process which uses a command such as cat(1) to read the file
and transmit it to the remote process.
Connector -> Ground. Ground the connector selected by the
next mouse click directly to /dev/null, the system's virtual
trashcan. This option is useful for discarding unwanted
output from a process.
Connector -> Unlink. Break the link, file binding or ground
to the connector selected by the next mouse click. Removing
a connector link may cause a net to be divided into two dis-
joint nets.
Connector -> Edit. Change the file decriptor and/or filename
and truncate/append mode mapped to the connector selected by
the next mouse click. A file descriptor edit may be per-
formed only on the connector of a custom process. A
filename or truncate/append mode edit may be performed only
on a connector which has been either bound to a disk file or
grounded.
Connector -> Move. The display location of a connector may
be altered by clicking the mouse over it after selecting
this option. The connector may then be dragged by the mouse
to any point on the perimeter of its process icon. Click the
right mouse button to fix the location and return to the
main menu.
Directory. Change to a new working directory.
Redisplay. Redisplay the contents of the network window.
Exit. Exit the program.
ACCELERATOR FUNCTIONS
While the entire functionality of ikp is accessible through
its menu system, some accelerators exist to more quickly
invoke a small number of the most commonly used functions.
Clicking the left mouse button over a process is equivalent
to invoking the Process -> Edit menu option on the selected
process.
Clicking the left mouse button over a connector is
equivalent to invoking the Connector -> Edit menu option on
the selected connector.
Clicking the middle mouse button over a connector is
equivalent to invoking the Connector -> Link menu option on
the selected connector.
Clicking the middle mouse button over a connector while
simultaneously depressing the keyboard Shift key is
equivalent to invoking the Connector -> File menu option on
the selected connector.
Clicking the middle mouse button over a connector while
simultaneously depressing the keyboard Control key is
equivalent to invoking the Connector -> Unlink menu option
on the selected connector.
REMOTE EXECUTION (what you will need)
Before you do anything using the remote execution features
of ikp you will have to get your system administrator to
install the ikp daemon on all machines that you intend to
run on. The details on installation follow:
The system administrator must add the line
ikp 5070/tcp
to the NIS server (yellow pages) /etc/services file. He
must then
cd /var/yp
make services
One all machines to be used by ikp (including servers) the
line
ikp stream tcp nowait root /explprod/phase2/usp/bin/in.ikpd
must be added to the local /etc/inetd.conf file.
A sure-fire way to reset everything is to reboot the servers
and the local machines.
The user must have a .rhosts file in which all machines to
be used by ikp must be listed by name along with his user
id, i.e. the .rhosts file must contain lines like
usapsw08 zwww10
for all the machines to be used (including the users own
local machine!). The .rhosts file must be in the users home
directory and must be readable by user, group, and world (-
rw-r--r--). The user should make a printout directory in
his home directory to capture printout files generated by
remote process. When building a net that contains remote
processes the user when filling in the menu panels should
fill in the "Directory:" entry with the full path to the
printout directory, e.g. /home/usasrv7a/zwww10/Printouts
The user should now be ready to build and run nets on remote
machines.
REMOTE EXECUTION (operational details)
Any individual process within a net can be made to execute
on a remote machine by specifying that machine's name in the
remote host field of the process edit panel. It is also pos-
sible to cause the remote process to be run under an arbi-
trary user name by similarly specifying the remote user
name. (An empty user field will cause the process to run
under the local user name.) There are three issues relating
to remote execution that must be kept in mind: (i) remote
host availability, (ii) user authentication and permissions,
and (iii) remote execution environment.
A process may be remotely executed only on a host which has
access to the ikpd(8) remote execution service daemon. This
program is normally started up by inetd(8). Its sole func-
tion is to service remote process execution requests from
users who are running ikp on another machine on the network.
The ikpd service daemon running on the remote machine on
which process execution is being requested performs a user
authentication check before granting execution privileges.
This authentication check is similar to that performed by
rlogin(1) and rsh(1), i.e., (i) a lookup of your user name
in the remote password database is performed on the remote
machine to determine if you have login privileges, and (ii)
the .rhosts file in your home directory on the remote
machine is scanned for the hostname of the machine from
which you are requesting remote execution (in other words,
the machine on which you are running ikp). If either of
these steps fail, remote execution privilege is denied. If
you have requested remote execution under a remote user name
which is different from your local user name, (i) a lookup
of the remote user name in the remote password database is
performed on the remote machine to determine login
privileges, and (ii) the the remote user's .rhosts file is
checked to ensure that access from your local user name and
local host has been specifically granted by scanning for a
line whose first token is the hostname of the machine from
which you are requesting remote execution, and whose second
token is your local user name.
If the remote authentication check succeeds, ikp (and the
cooperating remote ikpd) will attempt to construct a remote
execution environment for you before actually running your
remote process. This execution environment is a list of
environment variable names, together with their values,
which will be inherited by the remote program which you want
to run. You can generate a complete list of all your local
environment variables by using the printenv(1) command in
any shell window. One environment variable, the PATH vari-
able, is absolutely critical to the successful use of ikp's
remote execution facilities, as it is used to locate the
actual executable program file which you are attempting to
run (unless you have specified an absolute pathname as the
command name of a source, sink, filter or custom process, or
as the command path prefix for a library process). ikp can-
not simply use your local PATH variable on the remote
machine because (i) executable programs may be stored in
different locations on different machines, and (ii) the
location of the program may be dependent upon the architec-
ture of the remote machine, which may be different from the
architecture of the local machine.
The remote execution environment is constructed as follows:
(i) your entire local environment is copied to the remote
machine, (ii) the remote machine architecture is determined,
e.g., sun3, sun4, etc., and is used to set (or replace) the
value of the ARCH environment variable, (iii) any instance
of the string IKPRARCH which occurs in any environment vari-
able value is replaced by the new value of the ARCH environ-
ment variable, (iv) the name of your home directory (or that
of the remote user name you have specified, if any) on the
remote machine is determined, and is used to set (or
replace) the value of the HOME environment variable, (v) any
instance of the string IKPRHOME which occurs in any environ-
ment variable value is replaced by the new value of the HOME
environment variable, and (vi) if the environment variable
IKPRPATH exists, its value will be used to set (or replace)
the value of the PATH variable.
It is therefore possible to dynamically adjust your PATH
variable to appropriate values for different remote machines
by including a line in your .cshrc file such as the follow-
ing:
setenv IKPRPATH
.:IKPRHOME/IKPRARCH:/usr/local/IKPRARCH:/usr/ucb:/bin:/usr/bin
Then, if you request remote process execution on a machine
of architecture type sun4 where your home directory is
/home/elvis, your ARCH, HOME and PATH environment variables
will be set as follows before the remote process is exe-
cuted:
ARCH=sun4
HOME=/home/elvis
PATH=.:/home/elvis/sun4:/usr/local/sun4:/usr/ucb:/bin:/usr/bin
PROGRAM LIBRARY FILE FORMAT
ikp can be informed of numerous characteristics of an exter-
nal program by reading in a program library file which con-
tains a description of the program. A library is defined as
a collection of modules, and a module is defined as a
description of a program and its command syntax.
For a complete description of how to put together your own
ikp menu entries see the full manual page for ikp. Further
information is available by contacting Joe Wade,
TRCVM(ZJMW36), zjmw36@trc.amoco.com or Paul Gutowski,
TRCVM(ZPRG03), zprg03@trc.amoco.com
SEE ALSO
"Parallel Processing Seismic Data" by Paul Gutowski, Joe
Wade, and Bryan Helvey, available on request by contacting
Joe or Paul.
COPYRIGHT
copyright 2001, Amoco Production Company
All Rights Reserved
an affiliate of BP America Inc.
Man(1) output converted with
man2html