Command Scripts

The QM VOC file normally contains one or more items that represent scripts of commands to be executed automatically at certain events. Although these are usually paragraphs, all except for the MASTER.LOGIN item may actually be any executable type of VOC record (verbs, menus, Procs, etc). None of these items need exist. They provide the means to perform a fixed sequence of commands at the events described below.

LOGIN

The LOGIN paragraph is executed on entry to QM and also when the LOGTO command is used to switch to a new account.  The break key is inhibited until first execution of this paragraph has been completed. This paragraph is executed for interactive (terminal) users, phantom processes and QMClient connections. The @TTY variable can be tested to determine the user type and, as in this example, used to control flow through the paragraph. The LOGIN paragraph is typically used to set QM option flags, perform security checks, set up printers, set terminal characteristics and enter the application. The last step ensures that an application user does not see a QM command prompt.

Example

PA

DATE.FORMAT ON

IF @TTY IN 'phantom', 'vbsrvr' THEN STOP

PTERM CASE NOINVERT

BELL OFF

OPTION NO.USER.ABORTS

BREAK ON

RUN BP MAIN

ON.LOGTO

The ON.LOGTO paragraph is executed on use of the LOGTO command before switching to the new account. This paragraph might be used, for example, to clear down application specific data such as named common blocks.

Example

PA

DELETE.COMMON ALL

ON.EXIT

The ON.EXIT paragraph is executed on leaving QM by use of the QUIT command or any of its synonyms. The break key is inhibited during execution of this paragraph. An abort occurring in this paragraph will terminate the QM session immediately.

Example

PA

SELECT TEMP WITH UNO = <<@USERNO>>

IF @SELECTED THEN DELETE TEMP NO.QUERY

ON.ABORT

The primary role of the ON.ABORT paragraph is to prevent the user reaching a command prompt if the application fails. It may be useful to include logging of the cause of the abort.

The ON.ABORT paragraph is executed when QM aborts a program due to an internally detected error, a QMBasic program executes an ABORT statement or when the Abort response is chosen after use of the break key. The @ABORT.CODE and @ABORT.MESSAGE variables may be useful in determining the cause of the error. Aborts occurring in commands started using the QMBasic EXECUTE statement with the TRAPPING ABORTS option do not execute the ON.ABORT paragraph.

A further abort occurring whilst executing the ON.ABORT paragraph will cause a message to be displayed without re-entering the paragraph. If execution of the application is to be resumed, the ON.ABORT paragraph should execute a CLEAR.ABORT statement to inform the command processor that the abort condition has been handled and normal execution is to resume.

Example

PA

RUN BP LOG.ABORT

QUIT

MASTER.LOGIN (QMSYS account)

This item, if present, must be a paragraph and is executed on initial entry to QM in any account before the LOGIN paragraph but not when the LOGTO command is used to switch to a new account. This paragraph is executed with the break key inhibited for terminal users and phantom processes. It is also executed for QMClient connections.

Example

PA

DATE.FORMAT ON

OPTION NO.USER.ABORTS

OPTION DUMP.ON.ERROR