PHANTOM

The PHANTOM command starts execution of a verb, sentence or paragraph as a background process.

Format

PHANTOM {options} command

where

options

are selected from the following items described in detail below:

ACCOUNT name

Requests that the phantom process runs in a specific account.

DATA	Passes the data queue of the parent process to the phantom.

GROUP

Specifies that the phantom process is to be grouped with its parent.

LOGGING name

Specifies a non-default name for the log file.

NO.LOG

No log file is to be produced.

NO.MSG

No start or termination message to be displayed in parent process.

POOL name

Makes the phantom process a member of the named connection pool.

USER n

Requests that the phantom runs as a specific user number.

command

is the command to be executed by the phantom process.

A new background process is started to execute the command which must be a valid verb, sentence or paragraph. The process from which the PHANTOM command was performed continues without waiting for command to be completed. A message is displayed indicating the user number associated with the phantom. The user number is also returned in @SYSTEM.RETURN.CODE. If the phantom process cannot be started, @SYSTEM.RETURN.CODE holds the negative error code.

When using the POOL option, the system will first look for an idle process in that pool that can be awakened. If no such process is found, a new phantom is started. The pool name may be followed by the keyword NEW.PROCESS to force creation of a new process even if an idle process exists. This allows an application to start a number of phantom processes that perform initialisation and then go into the idle pool waiting for work to do.

When the background process terminates a message is queued for display immediately before the next command prompt. This message is

Phantom n : Normal termination.

where n is the user number if the process completed successfully or

Phantom n : Abnormal termination.

if the process aborted.

The default behaviour of the phantom process is to create a record in the $COMO file named PHn_date_time exactly as though it had commenced with the command

COMO ON PHn_date_time

This record will contain all output from the phantom process that would be directed to the terminal in an interactive process. The logging file may be switched off or redirected as desired from within the phantom process.

Use of the NO.LOG keyword causes the phantom process to run with no log file. Alternatively, the LOGGING keyword may be used to specify the name of the log file record to be created. If name is a quoted string containing a space, the portion before then space must correspond to a VOC file definition record for a directory file and the portion after the space will be used as the record name within that file.

Except when the NO.LOG or LOGGING option is used, the PHANTOM command checks for the presence of a catalogued subroutine named PHLOGNAME. If found, it is called with two arguments; the first through which it return an alternative log location, the second passed in as the command to be executed by the phantom process. The return value must be a file name and record name, separated by a single space where the file name must correspond to an already existing directory file on the QM server. This feature allows automatic selection of alternative log file locations and provides the opportunity for compatibility with log file naming conventions used by other systems.

For example, the phantom log record strategy used by UniVerse can be achieved with a PHLOGNAME subroutine as below.

subroutine phlogname(result, command)

$catalogue

result = '&PH& ' : upcase(field(command, ' ', 1)):'_':time():'_':date()

return

end

In all cases, a QMBasic program can determine the log record location for an active phantom by use of the !PHLOG() subroutine.

The ACCOUNT option specifies the name of the account in which the phantom process is to start execution, defaulting to the current account if omitted. The user must not be barred from access to this account or forced into some other account by the application security controls.

The DATA keyword causes the DATA queue of the process in which the PHANTOM command is executed to be passed into the phantom process, clearing it in the parent process.

The GROUP keyword causes the phantom process to be grouped with its parent such that, if the parent process terminates, the phantom is automatically logged out.

The USER option allows the phantom process to be created as a specific user number within a range of numbers reserved by the PHANTOMS configuration parameter. An error will occur if there is already a phantom running as the specified user.

Any attempt to read data from the keyboard will cause the process to abort. DATA statements may be used in the phantom to supply input that would normally be read from the keyboard.

Phantom processes may not be started within a transaction.

All QM processes, including phantoms, execute the VOC LOGIN paragraph, if it exists. To exit from the LOGIN paragraph for a phantom process, insert a line

IF @TTY = 'phantom' THEN STOP

at the relevant point in the paragraph. See @TTY for more details.

Any secure encryption keys enabled in the parent process are inherited by the phantom process.

Example

PHANTOM BASIC BP INVOICE

This command starts a phantom process to compile the QMBasic program INVOICE in the BP file.