AmigaDOS Data Structures

Process Data Structures

These values are created as part of an AmigaDOS process; there is a complete set for each process.

A process is an Exec task with a number of extra data structures appended. The process structure consists of:

• Exec task structure
• Exec message port
• AmigaDOS process value

The process identifier AmigaDOS uses internally is a pointer to the Exec message port (pr_MessagePort) from which the Exec task may be obtained.

AmigaDOS process values are as follows:

Type	Name	Description
BPTR	pr_SegList	Array of seg lists used by this process
LONG	pr_StackSize	Size of process stack in bytes
APTR	pr_GlobVec	Global vector for this process (BCPL)
LONG	pr_TaskNum	CLI task number of zero if not a CLI
BPTR	pr_StackBase	Ptr to high memory end of process stack
LONG	pr_Result2	Value of secondary result from last call
BPTR	pr_CurrentDir	Lock associated with current directory
BPTR	pr_CIS	Current CLI Input Stream
BPTR	pr_COS	Current CLI Output Stream
APTR	pr_ConsoleTask	Console handler process for current window
APTR	pr_FileSystemTask	File handler process for current drive
BPTR	pr_CLI	Pointer to CLI
APTR	pr_ReturnAdd	Pointer to previous stack frame
APTR	pr_PktWait	Function to be called when awaiting msg
APTR	pr_WindowPtr	Window for error printing
BPTR	pr_HomeDir	Home directory of executing program
LONG	pr_Flags	Flags telling DOS about process
LONG	(*pr_ExitCode)(LONG returncode, LONG pr_ExitData)	Code to call on exit of program or NULL
LONG	pr_ExitData	Passed as an argument to pr_ExitCode
UBYTE*	pr_Arguments	Arguments passed to the process at start
struct MinList	pr_LocalVars	Local environment variables
ULONG	pr_ShellPrivate	For the use of the current Shell
BPTR	pr_CES	Error stream - if NULL, use pr_COS

To identify the segments that a particular process uses, you must use pr_SegList. pr_SegList is an array of longwords with its size in Seg_List[0]. Other elements are either zero or a BPTR to a SegList. CreateProc() and CreateNewProc() create this array with the first two elements of the array pointing to resident code and the third element, being the SegList, passed an argument. When a process terminates, FreeMem() is used to return the space for the pr_SegList.

The pr_StackSize field indicates the size of the process stack, as supplied by the user when calling CreateProc() or CreateNewProc(). Note that the process stack is not the same as the command stack a CLI uses when it calls a program. The CLI obtains its command stack just before it runs a program and you may alter the size of this stack with the STACK command. When you create a process, AmigaDOS obtains the process stack and stores the size in pr_StackSize. The pointer to the space for the process control block and the stack is also stored in the MemEntry field of the task structure. When the process terminates this space is returned via a call to FreeVec(). You can also chain any memory you obtain into this list structure so that it, too, gets put back when the task terminates. But be careful, this method won't work for a program run from the CLI since memory is not freed until the process goes away.

If a call to CreateProc() or CreateNewProc() creates the process, GlobVec is a pointer to the Shared Global Vector. However, some internal handler processes use a private global vector.

The value of pr_TaskNum is normally zero; a CLI process stores the small integer that identifies the invocation of the CLI here.

The pointer pr_StackBase points to the high-memory end of the process stack. This is the end of the stack when using languages such as C or assembler; it is the base of the stack for languages such as BCPL. Note that pr_StackBase may not be the same as the one your application uses (eg. if your program is started from the CLI).

The pr_Result2 and pr_CurrentDir fields are handled by the AmigaDOS functions IoErr() and CurrentDir(), respectively. pr_CIS and pr_COS are the values Input() and Output() return and refer to the filehandles you should use when running a program under the CLI. Never access pr_CIS and pr_COS directly. Instead use the AmigaDOS functions provided for this purpose.

The pr_ConsoleTask field refers to the console handler for the current window. The pr_FileSystemTask field refers to the file handler for the boot device. You use these values when attempting to open the * device or file by a relative path name when pr_CurrentDir is null.

The pr_CLI pointer is nonzero only for CLI processes. In this case it refers to a further structure the CLI uses with the following format:

Type	Name	Description
LONG	cli_Result2	Value of IOErr from last command
BSTR	cli_SetName	Name of current directory
BPTR	cli_CommandDir	BPTR to CLI path
LONG	cli_ReturnCode	Return code from last command
BSTR	cli_CommandName	Name of current command
LONG	cli_FailLevel	Fail level (set by FAILAT)
BSTR	cli_Prompt	Current prompt (set by PROMPT)
BPTR	cli_StandardInput	Default (terminal) CLI input
BPTR	cli_CurrentInput	Current CLI input
BSTR	cli_CommandFile	Name of EXECUTE command file
LONG	cli_Interactive	Boolean; TRUE if prompts required
LONG	cli_Background	Boolean; TRUE if CLI created by RUN
BPTR	cli_CurrentOutput	Current CLI output
LONG	cli_DefaultStack	Stack size to be obtained in longwords
BPTR	cli_StandardOutput	Default (terminal) CLI output
BPTR	cli_Module	SegList of currently loaded command

The exit() function uses the value of pr_ReturnAddr which points to just above the return address on the currently active stack. If a program exits by performing an RTS on an empty stack, the control passes to the code address pushed onto the stack by CreateProc() or by the CLI. If a program terminates with a call to Exit(), then AmigaDOS uses this pointer to extract the same return address. Note that the AmigaDOS function Exit() is inappropriate for most programs which should use the exit() function provided by the compiler manufacturer instead.

The value of pr_PktWait is normally zero. If it is nonzero, then AmigaDOS calls pr_PktWait whenever a process is about to go to sleep to await a signal indicating that a message has arrived. In the same way as GetMsg(), the function should return a message when one is available. Usually you use this function to filter out any private messages arriving at the standard process message port that are not intended for AmigaDOS.

The value of pr_WindowPtr is used when AmigaDOS detects an error that normally requires the user to take some action. Examples of these errors are attempting to write to a write-protected disk, or when the disk is full. If the value of pr_WindowPtr is -1, then the error is returned to the calling program as an error code from the AmigaDOS call of Open(), Write(), or whatever. If the value is zero, then AmigaDOS places a request box on the Workbench screen informing the user of the error and providing the opportunity to retry the operation or to cancel it. If the user selects to cancel, then AmigaDOS returns the error code to the calling program. If the user selects retry, or insert[s] a disk, then AmigaDOS attempts the operation once more. Under V2.0 and later versions of AmigaDOS, if a pr_WindowPtr is zero then AmigaDOS will put requesters on the default public screen.

If you put a positive value into the pr_Window field, then AmigaDOS takes this to be a pointer to a window structure. Normally you would place the Window structure of the window you are currently using here. In this case, AmigaDOS displays the error message within the window you have specified, rather than using the Workbench screen. You can always leave the pr_WindowPtr field as zero, but if you are using another screen, then the messages AmigaDOS displays appear on the Workbench screen, possibly obscured by your own screen.

The initial value of pr_WindowPtr is inherited from the process that created the current one. If you decide to alter pr_WindowPtr from within a program that runs under the CLI, then you must save the original value and restore it when you finish; otherwise, the CLI process contains a pr_WindowPtr that refers to a window that is no longer present.

The rest of the fields in the process structure are brand new and appear only in V2.0 and later versions of AmigaDOS. The pr_HomeDir field is the directory from which the program associated with this process was loaded. This field is referenced when the PROGDIR: feature of V2.0 is used. The pr_Flags field is a private field containing flags for AmigaDOS.

The field named (*pr_ExitCode)() is a LONG pointing to the cleanup code to be called after the program exits. It takes as a parameter the return code of the program and may return a modified return code when the process terminates. The pr_ExitData is provided as a convenience and allows you to pass additional information to your pr_ExitCode automatically.

Another new field is pr_Arguments. This is a null terminated string of the register level arguments passed to the process when the program was started. You can modify this field using the SetArguments() function but if you do, you must restore it to its original value before exiting.

pr_LocalVars is used to implement process local variables. Do not access these directly. Use the new calls GetVar(), SetVar(), and DeleteVar() instead.

The pr_ShellPrivate field is for the private use of the Shell associated with this process. Never access it.

The value in pr_CES points to an error stream to use for this process separate from pr_CIS and pr_COS. This field is not fully implemented in AmigaDOS at the time of this writing.