NAME
ikp - icon processing system
SYNOPSIS
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.
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.
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 out-
put, 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
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
function 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.
Many of the lines in a library file will be of the form
9 keyword value
9 where keyword is some attribute and value is the value of
that attribute. Double quotes may be used to indicate a null
value or to include whitespace characters within the value,
e.g., "" (the null string) and "This is a string containing
whitespace." In general, declaring a value to be "" is
equivalent to omitting the declaration line entirely. All
blank lines and lines whose first non-whitespace character
is # are ignored. Tabs and blank spaces may be used at will
anywhere within a line to improve readability by indenting,
aligning, etc.
A library is fully described by the lines
9 library name {
...
}
9 i.e., by an identifying name together with a sequence of
module decriptions. The supplied name will be the string
inserted into the Process -> Create menu.
A module is fully described by the lines
9 module name {
program executable-name
helpfile helpfile-name
pathprefix executable-path-prefix
directory working-directory
host execution-host
input input-fd
...
output output-fd
...
diagnostic diagnostic-fd
...
item
item
...
}
9 i.e., by an identifying name together with several key/value
pairs and a sequence of item decriptions. The supplied name
will be the string inserted into the Process -> Create -> [
Library ] menu.
The program entry specifies the name of the executable com-
mand that will be invoked when the process is run. This is
the only key/value pair that must be explicitly set within a
module description to a non-null value. This value cannot
be changed by the user from the process edit panel.
The helpfile entry specifies the name of an ASCII text file
containing help information for the module. If this is a
non-null string, the process edit panel will contain a help
button which will cause the contents of the named file to be
displayed when it is selected.
The pathprefix entry specifies a path to be prefixed to the
program name. This can be useful if the user's search path
does not contain the command specified by the program entry,
or if the user wishes to run some alternate version of the
command.
The directory entry specifies the working directory in which
the command is to be executed.
9
From trcgp/usp Last change: Fri Dec 08 2000 11
descriptors which are to be mapped onto the process input,
output and diagnostic connectors. There may be any number of
these entries. When the process icon is displayed, each con-
nector is shown with the number of the file descriptor to
which it is mapped. Ideally, the help file should document
the nature of each such descriptor so that the user can
fully understand the purpose of all displayed connectors.
Item descriptions are used to control the specification of
command options. Each item description corresponds to a
panel item which is built into the process edit panel. When
the user interactively changes the value of the panel item,
the command-line argument list with which the command is
invoked is rebuilt to reflect the changes made by the user.
Setting a panel item to a certain value may cause other
items in the edit panel to be enabled (i.e., made visible
and sensitive to user input) or disabled. An item descrip-
tion may contain other item descriptions, generally those
which it is capable of enabling and/or disabling.
There are four types of item descriptions, choice, cycle,
toggle, text and slider, corresponding exactly to the Lamont
X Toolkit (LXT) panel item types. See the LXT documentation
for a description of these. Typically, the first three types
are used to set option flags and enable/disable other items,
the text type is used to allow user editing of text strings
such as filenames, and the slider type is used to allow
specification of an integer within a fixed domain.
ikp builds the command-line argument list to the declared
executable program in the following sequence: (i) zero the
character string used to hold the command, (ii) append any
pre-declared or user-edited executable path prefix (if any),
(iii) append the name of the executable program, and (iv)
for each enabled item in the order in which they have been
declared in the module description, append arguments
appropriate to the particular item. Step (iv) is performed
according to rules which are particular to each item type
and which are explained in full detail below. Note that if
an item is disabled, all of its subitems are considered to
be disabled.
Each item description is of the form
9 item type ID-number {
declaration
...
}
9
From trcgp/usp Last change: Fri Dec 08 2000 12
Items of any type may contain any of the following declara-
tions:
9 column m
row n
xoffset x
yoffset y
string item-label
option item-option-string
prevoptcontig
The column, row, xoffset and yoffset entries are used to
position the item in the process edit panel. The column and
row entries are translated into a pixel location in the
panel using a formula based upon the height and width of the
font being used. This location is then adjusted more finely
by applying the pixel offsets declared by the xoffset and
yoffset entries. The default value of 0 for all of these
entries will cause the item to be located just beneath the
module name, path prefix, working directory and execution
host items which always appear at the top of any library
process edit panel.
The string entry is used to set the LXPI_STRING attribute of
the panel item.
The option entry declares an item-option-string which will
be inserted into the command-line argument list if this item
is enabled at the time the list is built.
If the prevoptcontig declaration is present, the item-
option-string will be appended to the existing command-line
argument list with no intervening white space between the
item-option-string and any preceding argument (or between
the item-option-string and the command itself if there are
no preceding arguments).
Text items may contain any of the following declarations in
addition to the universal item declarations described above
(note that they may not contain any nested item descrip-
tions):
9 value value-string
store max-stored-value-length
display max-displayed-value-length
nonnull
integer
From trcgp/usp Last change: Fri Dec 08 2000 13
attributes of the item. The value-string may be interac-
tively changed by the user to any string whose length does
not exceed max-stored-value-length.
The nonnull, integer and real entries will cause an error to
be reported to the user at the time the net containing the
process is executed if the value-string of the item does not
satisfy the stated condition, i.e., if the value-string is
null, is not an integer, or is not a real number.
The encapsulate entry will cause the item's value-string to
be enclosed within a pair of special encapsulation charac-
ters when it is appended to the command-line argument list.
This forces the command which is ultimately run when the
enclosing net is executed to treat the value-string as a
single argument regardless of any blank spaces which it may
contain. This is particularly useful when the value-string
represents a file name, which on many systems may legally
contain a blank space. The encapsulate declaration should be
made for any text item whose value-string is used to con-
struct an argument that might meaningfully contain blank
space. The internal encapsulation character currently used
by ikp is the tab character, which means that tab characters
should not be present in any item-option-string, value-
string or selection-option-string (see below) declared
within a program library file. Any such character will be
replaced by ikp with a single blank space.
If the optvalcontig declaration is present, the item's
item-option-string and value-string will be appended to the
existing command-line argument list with no intervening
white space between the item-option-string and the value-
string.
ikp will append text item option flags and/or other argu-
ments to the command-line argument list in the following
way: (i) append a blank space unless a prevoptcontig
declaration is in effect for the item, (ii) append the
declared item-option-string (if any), (iii) append a blank
character unless an optvalcontig declaration is in effect
for the item or the value-string is empty, and (iv) append
the item's value-string (if any). If both the item-option-
string and the value-string are empty, nothing is appended
to the argument list.
From trcgp/usp Last change: Fri Dec 08 2000 14
item.
Slider items may also contain any of the following declara-
tions (note that they may not contain any nested item
descriptions):
9 value value
barlength barlength
optvalcontig
The value and barlength entries are used to set the
LXPSLIDER_VALUE and LXPSLIDER_BARLENGTH attributes of the
item. The value may be interactively changed by the user to
any integer between min-value and max-value.
If the optvalcontig declaration is present, the item's
item-option-string and value will be appended to the exist-
ing command-line argument list with no intervening white
space between the item-option-string and the value.
ikp will append slider item option flags and/or other argu-
ments to the command-line argument list in the following
way: (i) append a blank space unless a prevoptcontig
declaration is in effect for the item, (ii) append the
declared item-option-string (if any), (iii) append a blank
character unless an optvalcontig declaration is in effect
for the item, and (iv) append the item's value.
Choice, cycle and toggle items are all variants on the
enumerated item type. (See the Lamont X Toolkit documenta-
tion for further explanation.) Enumerated items may contain
any of the following declarations in addition to the univer-
sal item declarations described above:
9 format format-type
value value
selection
...
item
...
The format entry specifies a format-type which must be
either H or V. This declares the visual layout of the
item's selections to be either horizontal (the default) or
vertical.
9
From trcgp/usp Last change: Fri Dec 08 2000 15
9 selection ID-number {
declaration
...
}
9 where ID-number is an integer identification tag associated
with the selection. The first selection in an item must have
a tag of 0, and subsequently declared selections must have
consecutively increasing tag values. The ID-number is con-
sidered to be the value of the selection. If the value of a
choice or cycle item is n, then that selection with value n
is considered to be active, and all other selections are
considered to be inactive. If the value of a toggle item is
n, then a selection within that item is active if and only
if its value s satisfies the condition (n & (0x1 << s). Note
that a choice or cycle item must have exactly one active
selection, while a toggle item may have any number of active
selections.
A selection may contain any of the following declarations:
9 string selection-label
option selection-option-string
prevoptcontig
enable ID-number
...
disable ID-number
...
The string entry sets the LXPENUM_SELSTRING attribute of the
selection.
The option and prevoptcontig entries are used during the
construction of the command-line argument list, which is
done by ikp in the following way: (i) append a blank space,
unless a prevoptcontig declaration is in effect for the item
or the item-option-string is empty, (ii) append the declared
item-option-string (if any), and (iii) for each active
selection within the item, (iii-a) append a blank character,
unless a prevoptcontig declaration is in effect for the
selection or the selection-option-string is empty, and
(iii-b) append the selection's selection-option-string (if
any). If the item-option-string and all active selection-
option-strings are empty, nothing is appended to the argu-
ment list.
From trcgp/usp Last change: Fri Dec 08 2000 16
9
enabled again at a later time, all of its previously enabled
subitems will once again be enabled.
The following example and subsequent description are pro-
vided to further illustrate the techniques of constructing a
program library specification file.
9 #
# Seismic Processing software
#
library "Seismic Processing" {
module "Instrument Response" {
program ahinstr
helpfile /usr/lib/ikp/ahinstr.help
input 0
output 1
item choice 0 {
column 0
row 0
format H
string Mode
value 0
selection 0 {
string Insert
option -i
}
selection 1 {
string Remove
option -r
}
}
item choice 1 {
column 0
row 1.5
format H
string Filter
value 0
selection 0 {
string None
From trcgp/usp Last change: Fri Dec 08 2000 17
9
User Commands ikp(1)
string "Low pass"
option -l
enable 2
enable 3
}
item text 2 {
column 0
row 3
string Roll:
option ""
store 20
display 10
value ""
real
}
item text 3 {
column 20
row 3
string Zero:
option ""
store 20
display 10
value ""
real
}
}
item cycle 4 {
column 0
row 4.5
format H
string Taper
value 0
selection 0 {
string Disable
option ""
disable 5
}
selection 1 {
string Enable
option -f
From trcgp/usp Last change: Fri Dec 08 2000 18
User Commands ikp(1)
encapsulate
}
}
item slider 6 {
column 0
row 7.5
string Order:
range 0 10
value 0
}
}
}
The above example describes a library of seismic processing
software containing a single program whose purpose is to
modify instrument response. The actual executable is
ahinstr. It reads input from file descriptor 0 and writes
output to file descriptor 1. Help information related to
this program is stored in the ASCII text file
/usr/lib/ikplib/ahinstr.help.
Standard interactive shell usage syntax for this program is
9 ahinstr [ -i | -r ] [ -l roll zero | -h roll zero ] [ -f
file ] order
9 Note that the -i (insert response) and -r (remove response)
options are mutually exclusive, as are the -l and -h options
(low pass vs. high pass filter). Exactly one of the -i and
-r options must be specified. Usage of the -l or -h option
is not required, but if either option is used two additional
numeric arguments must also be specified. The optional -f
argument requires the specification of a single non-null
text string. The required order argument must be an integer
between 0 and 10.
Item 0, a choice item, allows the user to select between the
mutually exclusive operations of response insertion and
removal. The declared item value of 0 initializes selection
0 to be the active selection. If the user does not alter the
value of the item by clicking the mouse over selection 1,
ikp will insert selection 0's -i selection-option-string
From trcgp/usp Last change: Fri Dec 08 2000 19
User Commands ikp(1)
the roll and zero arguments, are disabled since these argu-
ments will not be used. If selection 1 is activated by the
user, the -h selection-option-string is inserted into the
argument list, and text items 2 and 3, which are now
required, are enabled. If selection 2 is activated by the
user, the -l selection-option-string is inserted into the
argument list, and text items 2 and 3, which are required,
are enabled. If enabled, text items 2 and 3 are each
required to have as their value-string a string which can be
transformed into a real number. If, for example, the user
edits one of these items to set its value-string to "hello",
ikp will not allow the net containing the process to be exe-
cuted.
Item 4, a cycle item, allows the user to optionally perform
a tapering operation using parameters which have been stored
in a file. If selection 0 is active (the declared initial
state of the item), no option is inserted into the argument
list (note the null selection-option-string which has been
specified), and text item 5, which is used to specify the
filename argument, is disabled since it will not be used. If
selection 1 is activated by the user, the -f selection-
option-string is inserted into the argument list, and text
item 5, which is now required, is enabled. If enabled, text
item 5 is forced to be a non-null string, and is encapsu-
lated so that a user can specify a file name containing
blank spaces if desired.
Item 6, a slider item, allows the user to choose any integer
between 0 and 10 for the required order argument.
INSTALLATION
An attempt is made to read a site program library file at
startup time. This file should be installed as
/usr/lib/ikp/sitelib.
Tee processes are implemented via the ikp_tee program, which
must be installed in a directory contained within the user's
executable search path in order to be accessible by ikp.
From trcgp/usp Last change: Fri Dec 08 2000 20
User Commands ikp(1)
ikp or ikpd will be run. (The same port number must be used
in every /etc/services file).
The ikpd remote execution service daemon must be invokable
by inetd(8) or already running with root privilege on each
machine on which a user wants to run a remote process. It is
usually started up indirectly via inetd by the presence of
an appropriate entry in the inetd.conf(5) file such as
ikp stream tcp nowait root /usr/etc/in.ikpd
in.ikpd
(In this example, ikpd has been renamed in.ikpd and
installed in /usr/etc.) It may also be invoked directly at
system boot time as a background process from /etc/rc. The
following lines, placed near the end of that script, are one
example of how this may be done.
#
# icon processor remote execution service daemon
#
if [ -f /usr/etc/ikpd ]; then
/usr/etc/ikpd 2>/dev/console
echo 'Starting ikpd ...' >/dev/console
fi
#
Note that the file system in which ikpd is installed must be
mounted at the time these commands are executed (/ and /usr
are generally safe choices - in the above example, ikpd has
been installed in /usr/etc.)
XDEFAULTS
ikp attempts to determine user preferences for the following
X11 resources (program defaults are shown in parentheses):
Background
Set the background color (White).
Foreground
Set the foreground color (Black).
Border
Set the border color (Black).
From trcgp/usp Last change: Fri Dec 08 2000 21
User Commands ikp(1)
BUGS
Because the inter-process communication links used by ikp
are based upon pipe(2) and socket(2) facilities, user pro-
grams which are run from ikp must be prepared to handle par-
tially successful read and write requests, e.g., an attempt
to read n bytes may yield less than n bytes due to pipe
buffer sizes, network transmission delays, etc. This is
especially critical with regard to remote process execution.
It will generally be safer to use buffered (rather than
unbuffered) I/O when writing such programs.
There should be a more flexible mechanism for individually
tailoring remote execution environments.
Diagnostic output from remote processes which is being
redirected to the controlling terminal of ikp is handled by
a buffering algorithm which may cause some output to be lost
if the buffer is overrun. This problem should be exhibited
only by programs which generate a continuous stream of diag-
nostic output.
SEE ALSO
ikp_tee(1), ikp_cat(1), ikpd(8)
AUTHOR
Roger Davis, October 1989.
COPYRIGHT
copyright 2001, Amoco Production Company
All Rights Reserved
an affiliate of BP America Inc.
From trcgp/usp Last change: Fri Dec 08 2000 22
Man(1) output converted with
man2html