ASyncRun(33.4) ARP Programmers Manual ASyncRun(33.4) NAME ASyncRun -- Create an asynchronous process. SYNOPSIS CLI# = ASyncRun("command", "arguments", PCB) d0 a0 a1 a2 FUNCTION ASyncRun creates a distinct, independent process using the information you provide. Many types of background processes may be created, including 'cli' style processes. Hopefully, this function fixes the limitations of the AmigaDOS Execute() call. Note that this function does not wait for the child process to complete. If a non-negative integer is returned to you, you can assume the process is already attached to the system and running. While you may wait for the child to complete if you choose to, it is not necessary since all of the system level resources such as files and memory will be released when the child terminates. (This does not apply to resources the child allocates for itself, of course, the child is responsible for releasing those.) If you do wish to wait for the child to terminate, you will be sent a message from the dying task which contains more information than it has previously been possible to obtain. The childs exit status, as well as the Result2 values are returned along with the official time of death. Note that you should only WaitPort() for such a message if the task was successfully launched. If the child process could not be dispatched for some reason, all resources that would have been freed on a normal termination of the child will be released, and then an error code will be returned to you. INPUTS command -- The command name. If you do not supply a value in the pcb_LoadedCode variable this must be a valid pathname or resident program name. If you provide already loaded code, the name does not need to refer to an actual program file or resident code, of course. arguments -- The commands you wish to pass to this argument. This may be null, but it must not exceed 256 characters in length. Note that IO redirection must be performed by the caller. Also note that some programs appear to have bugs in dealing with 0 length or NULL command lines. To safely pass a NULL command line, you should pass a string consisting of a newline, and a null, i.e. "\n". This is defined as a macro in arpbase.h. ProcessControlBlock -- Only pcb_StackSize and pcb_Pri must Page 1 (printed 2/22/88) ASyncRun(33.4) ARP Programmers Manual ASyncRun(33.4) be initialized by you. Clear all other variables if you do not wish to use them. Note that there are a large variety of options supported here. pcb_StackSize - The size of the stack you wish to use for the process. If not an even multiple of four, it will be rounded up for you. If the code starts with a ResidentProgramTag, your stack request will be overridden by the value in the tag. pcb_Pri -- The priority you wish to assign the child. pcb_TrapCode - If you do not provide alternate trap code for the process ASyncRun() assumes that you want the trap code from your own tasks Process structure copied to the childs. This is usually the correct behavior, since DOS installs special trap code which should be overridden only with great care. pcb_Input -- The default input file handles. This will be closed for you on process exit unless you set the PRB_SAVEIO control bit (see PRB_SAVEIO). pcb_Output -- As above. Note that these may be the same file handle, they need not be distinct. pcb_LoadedCode -- Normally, this will be the return value from LoadSeg() or LoadPrg(). If you provide this, ASyncRun() will not try to LoadSeg() "command", and it will not unload your code on exit. Note that the meaning of this variable is affected by the PRB_CODE bit. pcb_LastGasp -- If you wish to receive notification of the child processes death, leave the address of a ZombieMsg here, otherwise, leave a NULL. The ZombieMsg *must* have its ReplyPort initialized to the message port you want the ZombieMsg sent to. You may initialize the zm_UserInfo variable to whatever you wish. ASyncRun() completely ignores this variable. Note that you should only WaitPort() for a ZombieMsg if ASyncRun() returns positive. pcb_WBProcess -- This is only used when you have the PRB_NOCLI bit set. If PRB_NOCLI is set, and ASyncRun() succesfully dispatches the child, then this variable will contain the child processes message port. pcb_Console -- This is a union of two variables, always optional. For all flags but PRB_STDIO, pcb_SplatFile refers to the file to use when a child Page 2 (printed 2/22/88) ASyncRun(33.4) ARP Programmers Manual ASyncRun(33.4) process attempts to DUP the current window with Open("*", mode_mumble). If you are always going to be running from the CLI, then you can disregard this if you wish, however, if you are going to run as a Workbench process it is very important that this refers to a valid console window, else the child will hang on such an Open. If PRB_STDIO is set, this name refers to the name to use when opening a console for default IO for the child. You do not need to supply the name, if this is null, a default name will be used. pcb_Flags -- This variable contains various control flags: PRB_SAVEIO: This will cause the child process to leave the pcb_Input/pcb_Output file handles open when it dies, so you may continue to use them for IO. You can also pass NULL file handles to the child using this flag, since it says, in effect, "Use my files, and then return them". Should be used with care, since mixing output from two processes is confusing, mixing input can be fatally confusing. PRB_CLOSESPLAT: The file provided as a pcb_Console.pcb_SplatFile will only be closed if this flag is set. You should use this flag if you explicitly opened a console to be used as a SplatFile, and don't want to hang around to close it. PRB_NOCLI: By default, a CLI style process is created. This flag causes a CreateProc() Workbench style process to be created instead. If this is used, ASyncRun() will return ZERO (never a valid CLI number) on success, and place the address of the childs pr_MsgPort in pcb_WBProcess. PRB_INTERACTIVE: This sets the interactive flag in the process structure to TRUE, and the background flag to FALSE. The default is Background = TRUE, Interactive = FALSE. Should be used if you intend to spawn an interactive process, but note that this is not enough to guarantee interactivity, you should select appropriate file handles, or use PRB_STDIO along with this flag. PRB_CODE: Setting this flag informs ASyncRun() that Page 3 (printed 2/22/88) ASyncRun(33.4) ARP Programmers Manual ASyncRun(33.4) the value in pcb_LoadedCode is an actual CPTR to actual code, rather than a BPTR to a seglist. This allows you to create processes out of pieces of a program, as you can now create tasks. I recommend setting PRB_NOCLI along with this flag, and using the message ports for communication. AmigaDOS is not very comfortable with this, so care in testing and design is essential. Still, initial tests indicate that this is a viable option. PRB_STDIO: Create a new console window, using the CON: filename supplied in pcb_Console.pcb_ConName. If this is NULL, use a default name. You should use this option if you wish the child process to respond correctly to break's from the keyboard, and handle input well. Note that using this flag guarantees that the child will be able to Open("*") if it needs to. RESULT If this function succeeds, a positive value, corresponding to the number of the CLI created will be returned. If no CLI is created, the value returned will be zero. If there is an error, then the return will be negative, and one of the documented error returns in arpbase.[ih]. If the Parent is not a cli process, both pcb_Input and pcb_Output are null, and no flags are set, then ASyncRun() will force the actions described under PRB_STDIO to occur. If one only of pcb_Input/pcb_Output are null, then ASyncRun() will set the null filehandle to the following: If (pcb_Input == NULL) stdin = NIL: if (pcb_Output == NULL) stdout = CON:DefaultFile If the Parent is a cli process the situation is a little simpler. If pcb_Input is NULL, then the NIL: device will be used for the childs stdin (as above). If pcb_Output is NULL, then the current window will be duped by an Open("*", mode_mumble) call. This function provides many options, and may seem a little bewildering in its variety. By far the largest number of programs will be happy with the defaults chosen for them when NULL pcb_Input/pcb_Output handles are passed, or using the PRB_STDIO level of interactivity, so start from there, and branch out as you need too. ADDITIONAL CONSIDERATIONS Page 4 (printed 2/22/88) ASyncRun(33.4) ARP Programmers Manual ASyncRun(33.4) This function will temporarily utilize your processes msgport, calling the pr_TaskWait function if one is installed. BUGS None known SEE ALSO LoadPrg(), UnLoadPrg(), SyncRun(), AddResident() AUTHOR SDB Page 5 (printed 2/22/88)