Process


Section contents


Overview

Defined in

ce32base.oxh


Construction / destruction


NewProcess - Constructor

Usage

this& = NewProcess&:

Description

Creates a rectangle object and returns a handle which allows the object to be manipulated.

Return Value
this& An value which represents the created process
Error Handling

If the object could not be created then an error is generated which should be trapped by an ONERR handler.

Example
  LOCAL this&

  this& = NewProcess&:
  DeleteProcess:(this&) 

DeleteProcess - Destructor

Usage

DeleteProcess:(BYREF this&)

Description

Destroys the process object.

Arguments
this& A handle to a process object
Example
  LOCAL this&

  this& = NewProcess&:
  DeleteProcess:(this&) 

Methods provided


ProcessCommandLine

Usage

cmdline$ = ProcessCommandLine$:(this&)

Description

Use this function to fetch a copy of the data which is passed as an argument to the thread function of the new process's main thread when it is first scheduled to run.

This is the command line which is passed to the ProcessCreate%:() member function of this process object.

Arguments
this& A handle to a process object
Return value
cmdline$ The command line

ProcessCreate

Usage

result% = ProcessCreate%:(this&,filename$,command$)

Description

Use this function to start a new process.

The string command$ contains the full path name of the executable to be loaded; this can be in ROM or RAM. If the full path name has no file extension, an extension of .EXE is appended. The length of the resulting full path name must be less than or equal to KMaxfileName%. The length of the file name itself must always be less than or equal to KMaxOsName%.

Arguments
this& A handle to a process object
filename$ Full path name of the executable to be loaded
command$ Data to be passed to the main thread of the new process when it is first scheduled.
Return value
result%  

ProcessExitCategory

Usage

category$ = ProcessExitCategory$:(this&)

Description

Use this function to find the name of the category associated with the end of the process. The category name together with the reason number is a way of distinguishing between different causes of process termination.

If the process has panicked, the category name is the panic category name; for example, E32USER-CBase or KERN-EXEC. If the process has ended as a result of a call to Kill(), then the category name is Kill.

If the process has not ended, then the category name is empty, i.e. the length of the category name is zero.

Arguments
this& A handle to a process object
Return value
category$ The category associated with the end of the process.
See Also

ProcessExitReason, ProcessExitType, ProcessKill, ProcessPanic


ProcessExitReason

Usage

reason& = ProcessExitReason&:(this&)

Description

Use this function to find the specific reason associated with the end of this process. The reason number together with the category name is a way of distinguishing between different causes of process termination.

If the process has panicked, this value is the panic number. If the process has ended as a result of a call to ProcessKill:(), then the value is the one supplied by ProcessKill:().

If the process has not ended, then the returned value is zero.

Arguments
this& A handle to a process object
Return value
reason& The reason associated with the end of the process.
See Also

ProcessExitCategory, ProcessExitType, ProcessKill, ProcessPanic


ProcessExitType

Usage

type% = ProcessExitType%:(this&)

Description

Use this function to find out whether or not the process has ended and, if it has ended, how it ended.

This information allows the caller to distinguish between controlled termination and a panic.

Arguments
this& A handle to a process object
Return value
type% An exit type which describe how the process has ended.
See Also

ProcessExitCategory, ProcessExitReason, ProcessKill, ProcessPanic


ProcessFileName

Usage

name$ = ProcessFileName$:(this&)

Description

Use this function to fetch a copy of the full path name of the loaded executable on which this process is based.

This is the file name which is passed to the ProcessCreate:%() function of this process object.

Arguments
this& A handle to a process object
Return value
name$ Full path name of the file.
See Also

ProcessCommandLine


ProcessGetRamSizes

Usage

ProcessGetRamSizes:(this&,BYREF code&,BYREF constData&,BYREF initializedData&,BYREF uninitializedData&)

Description

Use this function to get the size of an executable's sections.

The function fetches the:

If the process's executable is running from ROM, then the size of both the binary code and the constant data are zero.

Arguments
this& A handle to a process object
BYREF code& On return from this function, contains the size of the executable's binary.
BYREF constData& On return from this function, contains the size of the executable's constant data section.
BYREF initializedData& On return from this function, contains the size of the executable's initialized data section.
BYREF uninitializedData& On return from this function, contains the size of the executable's uninitialized data section.

ProcessKill

Usage

ProcessKill:(this&,reason&)

Description

Use this function to end this process specifying the reason code reason&.

Arguments
this& A handle to a process object
reason& The reason to be associated with the ending of this process.

ProcessLoadedFromRam

Usage

bool% = ProcessLoadedFromRam%:(this&)

Description

Use this function to determine whether the executable for this process was loaded from RAM or was found in ROM.

Arguments
this& A handle to a process object
Return value
bool% Return KTrue%(-1) if the executable was loaded from RAM, otherwise it returns KFalse%(0)

ProcessOpenFind

Usage

result% = ProcessOpenFind:(this&,pattern$,count%)

Description

Use this function to open a handle to the process found using a pattern to be matched.

Arguments
this& A handle to a process object
pattern$  
count%  
Return value
result%  

ProcessOpenName

Usage

result% = ProcessOpenName:(this&,name$)

Description

Use this function to open a handle to an existing process which has the same name as that contained in the string name$

Arguments
this& A handle to a process object
name$ Name of the process to be opened.
Return value
result%  

ProcessOwner

Usage

result% = ProcessOwner:(this&,BYREF that&)

Description

Use this function to get a handle to the process which owns this process.

Arguments
this& A handle to a process object
BYREF owner& On successful return from this function, this is a fully constructed handle. to the owning process.

Note: This this handle must be destroyed by a call to DeleteProcess:() once the caller no longer required the value.

Return value
result%  
See Also

ProcessSetOwner


ProcessPanic

Usage

ProcessPanic:(this&,category$,reason&)

Description

Use this function to panic the process and all of its owned threads, specifying the panic category name in the string category$ and the panic number defined by reason.

Arguments
this& A handle to a process object
category$ A string containing the text which defines the category name for this panic.
reason& The panic number
Return value
result%  

ProcessPriority

Usage

priority% = ProcessPriority%:(this&)

Description

Use this function to fetch the priority of this process.

Arguments
this& A handle to a process object
Return value
priority% The process prority of this process
See Also

ProcessSetPriority


ProcessProtected

Usage

bool% = ProcessProtected%:(this&)

Description

Use this function to determine whether this process is protected.

The protected state prevents any other process from setting the priority, ending or panicking this process.

Arguments
this& A handle to a process object
Return value
bool% KTrue%(-1), if the process is protected; KFalse%(0), otherwise
See Also

ProcessSetProtected


ProcessRename

Usage

result% = ProcessRename%:(this&,name$)

Description

Use this function to assign a new name to this process, replacing any existing name.

When a process is created, its default name is the name portion of the filename from which the executable is loaded.

Any attempt to rename a process which is protected and is different from the process invoking this function, causes the rename operation to fail. A process can call ProcessRename%:() on itself whether it is protected or not.

The new name must be a valid name and it must also be such that the process's new fullname remains unique amongst processes.

Arguments
this& A handle to a process object
name$ New name of the process
Return value
result%  

ProcessResume

Usage

ProcessResume:(this&)

Description

Use this function to make the first thread (the main thread) in the process eligible for execution.

Arguments
this& A handle to a process object

ProcessSetOwner

Usage

ProcessSetOwner:(this&,process&)

Description

Use this function to make the process with handle aProcess, the owner of this process.

Arguments
this& A handle to a process object
process& A handle to the owner process object which is to own this process
See Also

ProcessOwner


ProcessSetPriority

Usage

ProcessSetPriority:(this&,priority&)

Description

Use this function to set the priority of this process

Arguments
this& A handle to a process object
priority& The process priority to be set
See Also

ProcessPriority


ProcessSetProtected

Usage

ProcessSetProtected:(this&,protected%)

Description

Use this function to set the process into a protected state.

The protected state prevents any other process from setting the priority, ending or panicking this process.

Arguments
this& A handle to a process object
protected% KTrue%(-1), if the process is to be protected; KFalse%(0), otherwise.
See Also

ProcessProtected


ProcessSetUIDType

Usage

ProcessSetUIDType:(this&,uid1&,uid2&,uid3&)

Description

Use this function to set the process type.

Arguments
this& A handle to a process object
uid1&  
uid2&  
uid3&  
See Also

ProcessUIDType


ProcessUIDType

Usage

ProcessUIDType:(this&,BYREF uid1&,BYREF uid2&,BYREF uid3&)

Description

<TBS>

Arguments
this& A handle to a process object
BYREF uid1&  
BYREF uid2&  
BYREF uid3&  
See Also

ProcessSetUIDType