coproc(1F) (Form and Menu Language Interpreter) coproc(1F)
NAME
coproc: cocreate, cosend, cocheck, coreceive, codestroy - communicate
with a process
SYNOPSIS
cocreate [-r rpath] [-w wpath] [-i id] [-R refname] [-s sendstring]
[-e expectstring] command
cosend [-n] procid string
cocheck procid
coreceive procid
codestroy [-R refname] procid [string]
DESCRIPTION
These co-processing functions provide a flexible means of interaction
between FMLI and an independent process. They enable FMLI to be
responsive to asynchronous activity.
The cocreate function starts command as a co-process and initializes
communications by setting up pipes between FMLI and the standard input
and standard output of command. The argument command must be an exe-
cutable and its arguments (if any). This means that command expects
strings on its input (supplied by cosend) and sends information on its
output that can be handled in various ways by FMLI. The following
options can be used with cocreate.
-r rpath
If -r is specified, rpath is the pathname from which FMLI reads
information. This option is usually used to set up communication
with processes that naturally write to a certain path. If -r is
not specified, cocreate chooses a unique path in /var/tmp.
-w wpath
If -w is specified, wpath is the pathname to which cosend writes
information. This option is usually used so that one process can
talk to many different FMLI processes through the same pipe. If
-w is not specified, cocreate chooses a unique path in /var/tmp.
-i id
If -i is specified, id is an alternative name for the co-process
initialized by this cocreate. If -i is not specified, id defaults
to command. The argument id can later be used with the other co-
processing functions rather than command. This option facilitates
the creation of two or more co-processes generated from the same
command. (For example, cocreate -i ID1 program args and cocreate
-i ID2 program differentargs.)
Page 1 Reliant UNIX 5.44 Printed 11/98
coproc(1F) (Form and Menu Language Interpreter) coproc(1F)
-R refname
If -R is specified, refname is a local name for the co-process.
The cocreate function can be issued more than once; therefore, a
refname is useful when the same co-process is referenced a second
or subsequent time. If a co-process already exists when the -R
option is specified, a new one will not be created. The same
pipes are shared. refname can be used as an argument to the -R
option to codestroy when you want to end a particular connection
to a co-process and leave other connections undisturbed. (The
co-process is only killed after codestroy -R has been called as
many times as cocreate -R was called.)
-s sendstring
The -s option specifies sendstring as a string that will be
appended to all output sent to the co-process using cosend. This
option allows a co-process to know when input from FMLI has com-
pleted. The default sendstring is a newline if -s is not speci-
fied.
-e expectstring
The -e option specifies expectstring as a string that identifies
the end of all output returned by the co-process. expectstring
need only be the initial part of a line. There must be a newline
at the end of the co-process output. This option allows FMLI to
know when output from the co-process has completed. The default
expectstring is a newline if -e is not specified.
The cosend function sends string to the co-process identified by
procid through the pipe set up by cocreate (optionally wpath), where
procid can be either the command or id specified in cocreate. By
default, cosend blocks, waiting for a response from the co-process.
Also by default, FMLI does not send a sendstring and does not expect
an expectstring (except a newline). That is, it reads only one line
of output from the co-process. If -e expectstring was not defined
when the pipe was created, then the output of the co-process is any
single string followed by a newline: any other lines of output remain
on the pipe. If the -e option was specified when the pipe was created,
cosend reads lines from the pipe until it reads a line starting with
expectstring. All lines except the line starting with expectstring
become the output of cosend. The following option can be used with
cosend:
-n If the -n option is specified, cosend will not wait for a
response from the co-process. It simply returns, providing no
output. If the -n option is not used, a co-process that does not
answer will cause FMLI to permanently hang, waiting for input
from the co-process.
The cocheck function determines if input is available from the process
identified by procid, where procid can be either the command or id
specified in cocreate. It returns a Boolean value, which makes cocheck
useful in if statements and in other backquoted expressions in Boolean
Page 2 Reliant UNIX 5.44 Printed 11/98
coproc(1F) (Form and Menu Language Interpreter) coproc(1F)
descriptors. cocheck receives no input from the co-process; it simply
indicates if input is available from the co-process. You must use
coreceive to actually accept the input. The cocheck function can be
called from a reread descriptor to force a frame to update when new
data is available. This is useful when the default value of a field in
a form includes coreceive.
The coreceive function is used to read input from the co-process iden-
tified by procid, where procid can be either the command or id
specified in cocreate. It should only be used when it has been deter-
mined, using cocheck, that input is actually available. If the -e
option was used when the co-process was created, coreceive continues
to return lines of input until expectstring is read. At this point,
coreceive terminates. The output of coreceive is all the lines that
were read excluding the line starting with expectstring. If the -e
option was not used in the cocreate, each invocation of coreceive
returns exactly one line from the co-process. If no input is available
when coreceive is invoked, it terminates without producing output.
The codestroy function terminates the read/write pipes to proc-id,
where procid can be either the command or id specified in cocreate.
It generates a SIGPIPE signal to the (child) co-process. This kills
the co-process, unless the co-process ignores the SIGPIPE signal. If
the co-process ignores the SIGPIPE, it will not die, even after the
FMLI process terminates (the parent process id of the co-process is
1).
The optional argument string is sent to the co-process before the co-
process dies. If string is not supplied, a NULL string is passed, fol-
lowed by the normal sendstring (newline by default). That is,
codestroy will call cosend procid string. This implies that codestroy
writes any output generated by the co-process to stdout. For example,
if an interactive co-process is written to expect a quit string when
the communication is over, the close descriptor could be defined like
this:
close=`codestroy ID 'quit' | message`
and any output generated by the co-process when the string quit is
sent to it through codestroy (using cosend) would be redirected to the
message line.
The codestroy function should usually be given the -R option because
you may have more than one process with the same name. You do not want
to kill the wrong process. codestroy keeps track of the number of
refnames you have assigned to a process with cocreate, and when the
last instance is killed, it kills the process (id) for you. codestroy
is typically called as part of a close descriptor because close is
evaluated when a frame is closed. This is important because the co-
process will continue to run if codestroy is not issued.
Page 3 Reliant UNIX 5.44 Printed 11/98
coproc(1F) (Form and Menu Language Interpreter) coproc(1F)
When writing programs to use as co-processes, the following tips may
be useful. If the co-process program is written in C language, be sure
to flush output after writing to the pipe. (Currently, awk(1) and
sed(1) cannot be used in a co-process program because they do not
flush after lines of output.) Shell scripts are well-mannered, but
slow. C language is recommended. If possible, use the default
sendstring, rpath and wpath. In most cases, expectstring will have
to be specified. This, of course, depends on the co-process.
In the case where asynchronous communication from a co-process is
desired, a co-process program should use vsig to force strings into
the pipe and then signal FMLI that output from the co-process is
available. This causes the reread descriptor of all frames to be
evaluated immediately.
EXAMPLES
.
.
.
init=`cocreate -i BIGPROCESS initialize`
close=`codestroy BIGPROCESS`
.
.
.
reread=`cocheck BIGPROCESS`
name=`cosend -n BIGPROCESS field1`
.
.
.
name="Receive field"
inactive=TRUE
value=`coreceive BIGPROCESS`
NOTES
If cosend is used without the -n option, a co-process that does not
answer causes FMLI to permanently hang.
Avoid using non-alphabetic characters in input and output strings to a
co-process because they may not get transferred correctly.
SEE ALSO
awk(1), cat(1), sed(1), vsig(1F).
Page 4 Reliant UNIX 5.44 Printed 11/98