PHANTOM

PHANTOM

Top  Previous  Next

 

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

 

 

Format

 

PHANTOM {options} command

 

where

 

optionsare selected from the following items described in detail below:
ACCOUNT nameRequests that the phantom process runs in a specific account.
DATAPasses  the data queue of the parent process to the phantom.
GROUPSpecifies that the phantom process is to be grouped with its parent.
LOGGING nameSpecifies a non-default name for the log file.
NO.LOGNo log file is to be produced.
NO.MSGNo start or termination message to be displayed in parent process.
POOL nameMakes the phantom process a member of the named connection pool.
USER nRequests that the phantom runs as a specific user number.

 

commandis 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.

 

 

See also:

CHILD(), LIST.PHANTOMS, !PHLOG(), STATUS