cocreate(1F)




NAME

     coproc, cocreate, cosend, cocheck,  coreceive,  codestroy  -
     communicate with a process


SYNOPSIS

     cocreate  [-r rpath]  [-w wpath]  [-i id]  [-R refname]   [-
     s send_string] [-e expect_string] command

     cosend [-n] proc_id string

     cocheck proc_id

     coreceive proc_id

     codestroy [-R refname] proc_id [string]


DESCRIPTION

     These co-processing functions provide a  flexible  means  of
     interaction between  FMLI and an independent process;  espe-
     cially, 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 executable 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 cosend function sends string to the  co-process  identi-
     fied  by proc_id via the pipe set up by cocreate (optionally
     wpath), where proc_id can be either the command or id speci-
     fied  in  cocreate. By default, cosend blocks, waiting for a
     response from the co-process. Also by  default,   FMLI  does
     not  send a send_string and does not expect an expect_string
     (except a newline). That is, it reads only one line of  out-
     put from the co-process. If -e expect_string 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 expect_string. All lines
     except  the line starting with expect_string become the out-
     put of cosend.

     The cocheck function determines if input is  available  from
     the  process  identified  by  proc_id,  where proc_id 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  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  core-
     ceive.

     The coreceive function is used to read input  from  the  co-
     process  identified  by proc_id, where proc_id can be either
     the command or id specified in cocreate. It should  only  be
     used  when it has been determined, using cocheck, that input
     is actually available. If the -e option was  used  when  the
     co-process  was  created,  coreceive will continue to return
     lines of input until expect_string is read. At  this  point,
     coreceive will terminate. The output of coreceive is all the
     lines that  were  read  excluding  the  line  starting  with
     expect_string  .  If  the  -e  option  was  not  used in the
     cocreate, each invocation of coreceive will  return  exactly
     one  line from the co-process. If no input is available when
     coreceive is invoked, it will simply terminate without  pro-
     ducing output.

     The codestroy function terminates the  read/write  pipes  to
     proc-id,  where  proc_id  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
     will be 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, followed by  the  normal  send_string
     (newline  by  default).  That is, codestroy will call cosend
     proc_id string: this implies that codestroy will  write  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;      close=`codestroy ID 'quit' | message`
     and  any  output generated by the co-process when the string
     quit is sent to it via codestroy  (using  cosend)  would  be
     redirected to the message line.

     The codestroy  function  should  usually  be  given  the  -R
     option,  since  you  may have more than one process with the
     same name, and you do not want to kill the wrong one. codes-
     troy 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 typ-
     ically 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.

     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
     send_string,  rpath and wpath. In most cases,  expect_string
     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  out-
     put from the co-process is available. This causes the reread
     descriptor of all frames to be evaluated immediately.


OPTIONS

     cocreate options are:

     -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 will choose 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 speci-
           fied, cocreate will choose a unique path in /var/tmp.

     -i id If -i is specified, id is an alternative name for  the
           co-processinitialized  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  is  typically  used,
           since  it  facilitates the creation of two or more co-
           processes generated from the same command. (For  exam-
           ple,  cocreate -i ID1 program args and cocreate -i ID2
           program different_args).

     -R refname
           If -R is specified, refname is a local  name  for  the
           co-process.  Since the cocreate function can be issued
           more than once, a refname is useful when the same  co-
           process  is  referenced  a  second or subsequent time.
           With the -R option, if the co-process already exists a
           new  one  will  not be created: the same pipes will be
           shared. Then, refname can be used as  an  argument  to
           the -R option to codestroy when you want to end a par-
           ticular 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 send_string
           The -s option specifies send_string 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  completed.  The default
           send_string is a newline if -s is not specified.

     -e expect_string
           The -e option specifies expect_string as a string that
           identifies  the  end of all output returned by the co-
           process. (Note: expect_string need only be the initial
           part of a line, and 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 expect_string is a newline if  -e  is  not
           specified.

     cosend options are:

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


EXAMPLES

     Example 1: Sample commands

        .
        .
        .
     init=`cocreate -i BIGPROCESS initialize`
     close=`codestroy BIGPROCESS`
        .
        .
        .
     reread=`cocheck BIGPROCESS`

     name=`cosend -n BIGPROCESS field1`
        .
        .
        .

     name="Receive field"
     inactive=TRUE
     value=`coreceive BIGPROCESS`


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|


SEE ALSO

     awk(1), cat(1), sed(1), vsig(1F), attributes(5)


NOTES

     If cosend is used without the -n option, a  co-process  that
     does not answer will cause  FMLI to permanently hang.

     The use of non-alphabetic characters  in  input  and  output
     strings  to  a co-process should be avoided because they may
     not get transferred correctly.


Man(1) output converted with man2html