Subroutine:   SUBST

Purpose:      Specify keyword substitution for a task which will be
              spawned via a call to DEPUTY.

Category:     USER-INTERFACE 

File:         srvreq.c

Author:       J.P. Terlouw

Use:          CALL SUBST( STRING,     Input     character
                          IRC )       Output    integer

              STRING    Character string containing keyword pairs.
                        The first member of the pair is the keyword as
                        referenced by the spawned task; the second is
                        the keyword as referenced by the calling task.
                        Keywords in the string must not be separated by
                        any separator (i.e. the string must only contain
                        keywords).
              IRC       error return code
                         1      no error
                        -1      odd number of keywords in string
                        -2      syntax error in keyword
                        -3      insufficient room for string

Notes:        If more than one keyword substitution is needed, they
              can be specified in one call or in a sequence of calls
              (see example b.)
              The mechanism is quite general and can also  be used
              in tasks which have been spawned themselves.
              If necessary, substitutions will be chained.
              After the call to DEPUTY, the substitution specification
              is removed.

Examples:     a) Suppose TASK1 processes a set and produces an output
              set of which the setnumbers are obtained from the
              keywords SET= and SETOUT= respectively. Also suppose that
              TASK1 requires the service of TASK2 to obtain information
              about the output set and that TASK2 uses the keyword SET=
              to obtain the setnumber. TASK1 and TASK2 then could be
              coded as follows:

              PROGRAM TASK1
              .
              .
              N = USERINT(...,'SET=',...)
              N = USERINT(...,'SETOUT=',...)
              .
              .
              CALL SUBST('SET=SETOUT=',IRC1)
              CALL DEPUTY('TASK2',IRC2)
              .
              .
              END

              PROGRAM TASK2
              .
              .
              N = USERINT(...,'SET=',...)
              .
              .
              END

              The call to USRINP from TASK2 obtains the setnumber
              associated with SETOUT=.  If the keyword isn't present
              in the keyword list, this call will prompt with
              "TASK1,SETOUT=".

              b) More than one substitution is allowed:
              CALL SUBST('SET=SETOUT=BOX=AREA=',IRC)
              This is equivalent to the following sequence:
              CALL SUBST('SET=SETOUT=',IRC)
              CALL SUBST('BOX=AREA=',IRC)

Related docs: DEPUTY.DC2  WKEY.DC2

Updates:      Oct 12, 1981: JPT Original document.
              Feb 15, 1990: JPT, Portable version, rewritten in ANSI C.