home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 1 / FishNMoreVol1.bin / more / programming / arpprog / newdocs / asyncrun < prev    next >
Text File  |  1988-02-22  |  10KB  |  331 lines
  1.  
  2.  
  3.  
  4.      ASyncRun(33.4)      ARP Programmers Manual    ASyncRun(33.4)
  5.  
  6.  
  7.  
  8.      NAME
  9.       ASyncRun -- Create an    asynchronous process.
  10.  
  11.      SYNOPSIS
  12.       CLI# = ASyncRun("command", "arguments", PCB)
  13.         d0              a0     a1      a2
  14.  
  15.      FUNCTION
  16.       ASyncRun creates a distinct, independent process using the
  17.       information you provide.  Many types of background processes
  18.       may be created, including 'cli' style    processes.  Hopefully,
  19.       this function    fixes the limitations of the AmigaDOS
  20.       Execute() call.  Note    that this function does    not wait for
  21.       the child process to complete.  If a non-negative integer is
  22.       returned to you, you can assume the process is already
  23.       attached to the system and running.  While you may wait for
  24.       the child to complete    if you choose to,  it is not necessary
  25.       since    all of the system level    resources such as files    and
  26.       memory will be released when the child terminates.  (This
  27.       does not apply to resources the child    allocates for itself,
  28.       of course, the child is responsible for releasing those.)
  29.  
  30.       If you do wish to wait for the child to terminate, you will
  31.       be sent a message from the dying task    which contains more
  32.       information than it has previously been possible to obtain.
  33.       The childs exit status, as well as the Result2 values    are
  34.       returned along with the official time    of death.  Note    that
  35.       you should only WaitPort() for such a    message    if the task
  36.       was successfully launched.  If the child process could not
  37.       be dispatched    for some reason, all resources that would have
  38.       been freed on    a normal termination of    the child will be
  39.       released, and    then an    error code will    be returned to you.
  40.  
  41.      INPUTS
  42.       command -- The command name.    If you do not supply a value
  43.           in the pcb_LoadedCode    variable this must be a    valid
  44.           pathname or resident program name.  If you provide
  45.           already loaded code, the name    does not need to refer
  46.           to an    actual program file or resident    code, of
  47.           course.
  48.  
  49.       arguments -- The commands you    wish to    pass to    this argument.
  50.           This may be null, but    it must    not exceed 256
  51.           characters in    length.     Note that IO redirection must
  52.           be performed by the caller.  Also note that some
  53.           programs appear to have bugs in dealing with 0
  54.           length or NULL command lines.     To safely pass    a NULL
  55.           command line,    you should pass    a string consisting of
  56.           a newline, and a null, i.e. "\n".  This is defined
  57.           as a macro in    arpbase.h.
  58.  
  59.       ProcessControlBlock -- Only pcb_StackSize and    pcb_Pri    must
  60.  
  61.  
  62.  
  63.      Page 1                         (printed 2/22/88)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      ASyncRun(33.4)      ARP Programmers Manual    ASyncRun(33.4)
  71.  
  72.  
  73.  
  74.           be initialized by you.  Clear    all other variables if
  75.           you do not wish to use them.    Note that there    are a
  76.           large    variety    of options supported here.
  77.  
  78.       pcb_StackSize    - The size of the stack    you wish to use    for
  79.           the process.    If not an even multiple    of four, it
  80.           will be rounded up for you.  If the code starts with
  81.           a ResidentProgramTag,    your stack request will    be
  82.           overridden by    the value in the tag.
  83.  
  84.       pcb_Pri -- The priority you wish to assign the child.
  85.  
  86.       pcb_TrapCode - If you    do not provide alternate trap code for
  87.           the process ASyncRun() assumes that you want the
  88.           trap code from your own tasks    Process    structure
  89.           copied to the    childs.     This is usually the correct
  90.           behavior, since DOS installs special trap code which
  91.           should be overridden only with great care.
  92.  
  93.       pcb_Input -- The default input file handles.    This will be
  94.           closed for you on process exit unless    you set    the
  95.           PRB_SAVEIO control bit (see PRB_SAVEIO).
  96.  
  97.       pcb_Output --    As above.  Note    that these may be the same
  98.           file handle, they need not be    distinct.
  99.  
  100.       pcb_LoadedCode -- Normally, this will    be the return value
  101.           from LoadSeg() or LoadPrg().    If you provide this,
  102.           ASyncRun() will not try to LoadSeg() "command", and
  103.           it will not unload your code on exit.     Note that the
  104.           meaning of this variable is affected by the PRB_CODE
  105.           bit.
  106.  
  107.       pcb_LastGasp -- If you wish to receive notification of the
  108.           child    processes death, leave the address of a
  109.           ZombieMsg here, otherwise, leave a NULL.  The
  110.           ZombieMsg *must* have    its ReplyPort initialized to
  111.           the message port you want the    ZombieMsg sent to.
  112.           You may initialize the zm_UserInfo variable to
  113.           whatever you wish.  ASyncRun() completely ignores
  114.           this variable.  Note that you    should only WaitPort()
  115.           for a    ZombieMsg if ASyncRun()    returns    positive.
  116.  
  117.       pcb_WBProcess    -- This    is only    used when you have the
  118.           PRB_NOCLI bit    set.  If PRB_NOCLI is set, and
  119.           ASyncRun() succesfully dispatches the    child, then
  120.           this variable    will contain the child processes
  121.           message port.
  122.  
  123.       pcb_Console -- This is a union of two    variables, always
  124.           optional.  For all flags but PRB_STDIO,
  125.           pcb_SplatFile    refers to the file to use when a child
  126.  
  127.  
  128.  
  129.      Page 2                         (printed 2/22/88)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      ASyncRun(33.4)      ARP Programmers Manual    ASyncRun(33.4)
  137.  
  138.  
  139.  
  140.           process attempts to DUP the current window with
  141.           Open("*", mode_mumble).  If you are always going to
  142.           be running from the CLI, then    you can    disregard this
  143.           if you wish, however,    if you are going to run    as a
  144.           Workbench process it is very important that this
  145.           refers to a valid console window, else the child
  146.           will hang on such an Open.  If PRB_STDIO is set,
  147.           this name refers to the name to use when opening a
  148.           console for default IO for the child.     You do    not
  149.           need to supply the name, if this is null, a default
  150.           name will be used.
  151.  
  152.       pcb_Flags -- This variable contains various control flags:
  153.  
  154.       PRB_SAVEIO:      This will cause the child process to leave
  155.               the pcb_Input/pcb_Output file    handles    open
  156.               when it dies,    so you may continue to use
  157.               them for IO.    You can    also pass NULL file
  158.               handles to the child using this flag,    since
  159.               it says, in effect, "Use my files, and then
  160.               return them".     Should    be used    with care,
  161.               since    mixing output from two processes is
  162.               confusing, mixing input can be fatally
  163.               confusing.
  164.  
  165.       PRB_CLOSESPLAT: The file provided as a
  166.               pcb_Console.pcb_SplatFile will only be
  167.               closed if this flag is set.  You should use
  168.               this flag if you explicitly opened a console
  169.               to be    used as    a SplatFile, and don't want to
  170.               hang around to close it.
  171.  
  172.       PRB_NOCLI:      By default, a    CLI style process is created.
  173.               This flag causes a CreateProc() Workbench
  174.               style    process    to be created instead.    If
  175.               this is used,    ASyncRun() will    return ZERO
  176.               (never a valid CLI number) on    success, and
  177.               place    the address of the childs pr_MsgPort
  178.               in pcb_WBProcess.
  179.  
  180.       PRB_INTERACTIVE:
  181.               This sets the    interactive flag in the
  182.               process structure to TRUE, and the
  183.               background flag to FALSE. The    default    is
  184.               Background = TRUE, Interactive = FALSE.
  185.               Should be used if you    intend to spawn    an
  186.               interactive process, but note    that this is
  187.               not enough to    guarantee interactivity, you
  188.               should select    appropriate file handles, or
  189.               use PRB_STDIO    along with this    flag.
  190.  
  191.       PRB_CODE:      Setting this flag informs ASyncRun() that
  192.  
  193.  
  194.  
  195.      Page 3                         (printed 2/22/88)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      ASyncRun(33.4)      ARP Programmers Manual    ASyncRun(33.4)
  203.  
  204.  
  205.  
  206.               the value in pcb_LoadedCode is an actual
  207.               CPTR to actual code, rather than a BPTR to a
  208.               seglist.  This allows    you to create
  209.               processes out    of pieces of a program,    as you
  210.               can now create tasks.     I recommend setting
  211.               PRB_NOCLI along with this flag, and using
  212.               the message ports for    communication.
  213.               AmigaDOS is not very comfortable with    this,
  214.               so care in testing and design    is essential.
  215.               Still, initial tests indicate    that this is a
  216.               viable option.
  217.  
  218.       PRB_STDIO:      Create a new console window, using the CON:
  219.               filename supplied in
  220.               pcb_Console.pcb_ConName.  If this is NULL,
  221.               use a    default    name.  You should use this
  222.               option if you    wish the child process to
  223.               respond correctly to break's from the
  224.               keyboard, and    handle input well.  Note that
  225.               using    this flag guarantees that the child
  226.               will be able to Open("*") if it needs    to.
  227.  
  228.      RESULT
  229.       If this function succeeds, a positive    value, corresponding
  230.       to the number    of the CLI created will    be returned.  If no
  231.       CLI is created, the value returned will be zero.  If there
  232.       is an    error, then the    return will be negative, and one of
  233.       the documented error returns in arpbase.[ih].
  234.  
  235.       If the Parent    is not a cli process, both pcb_Input and
  236.       pcb_Output are null, and no flags are    set, then ASyncRun()
  237.       will force the actions described under PRB_STDIO to occur.
  238.       If one only of pcb_Input/pcb_Output are null,    then
  239.       ASyncRun() will set the null filehandle to the following:
  240.  
  241.           If (pcb_Input    == NULL) stdin = NIL:
  242.           if (pcb_Output == NULL) stdout = CON:DefaultFile
  243.  
  244.       If the Parent    is a cli process the situation is a little
  245.       simpler. If pcb_Input    is NULL, then the NIL: device will be
  246.       used for the childs stdin (as    above).     If pcb_Output is
  247.       NULL,    then the current window    will be    duped by an Open("*",
  248.       mode_mumble) call.
  249.  
  250.       This function    provides many options, and may seem a little
  251.       bewildering in its variety.  By far the largest number of
  252.       programs will    be happy with the defaults chosen for them
  253.       when NULL pcb_Input/pcb_Output handles are passed, or    using
  254.       the PRB_STDIO    level of interactivity,    so start from there,
  255.       and branch out as you    need too.
  256.  
  257.      ADDITIONAL    CONSIDERATIONS
  258.  
  259.  
  260.  
  261.      Page 4                         (printed 2/22/88)
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.      ASyncRun(33.4)      ARP Programmers Manual    ASyncRun(33.4)
  269.  
  270.  
  271.  
  272.       This function    will temporarily utilize your processes
  273.       msgport, calling the pr_TaskWait function if one is
  274.       installed.
  275.  
  276.      BUGS
  277.       None known
  278.  
  279.      SEE ALSO
  280.       LoadPrg(), UnLoadPrg(), SyncRun(), AddResident()
  281.  
  282.      AUTHOR
  283.       SDB
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.      Page 5                         (printed 2/22/88)
  328.  
  329.  
  330.  
  331.