|Powered by QM on a Rpi server|
KnowledgeBase 00058: Command Scripts
This article was originally published as a Tip of the Week.
QM supports a set of command scripts that run automatically on entry to the system and at other key points in execution of an application. This article looks at these scripts, including some features that are unique to QM.
Although described below as being paragraphs (PA-type VOC items), all except MASTER.LOGIN may actually be any executable VOC record type (menu, paragraph, Proc, sentence, verb).
The LOGIN Paragraph
QM looks for an executable VOC item named LOGIN on arrival in an account, both on initial entry to QM and after using LOGTO to switch accounts. If found, this script is run and typically takes the user directly into the application without them seeing a QM command prompt. The LOGIN paragraph is also frequently used to perform any security and initialisation tasks required before entry to the application.
For security reasons, a QM process runs with the break key disabled until completion of the LOGIN paragraph. If the application is entered from this script, this implies that the break key will be disabled for application users. In the rare situations where the break key should be enabled for application users, this can be done either by use of the BREAK ON command in the LOGIN paragraph or from within the application.
QM does not directly support the concept of per-user login scripts as found in some other multivalue products but it is easy to emulate this behaviour. For example, a line
<<@LOGNAME>>.LOGINin the LOGIN paragraph would execute a VOC item named XXX.LOGIN where XXX is the user's login name. This example can be improved by testing that the item exists and by forcing the username to uppercase
IF EXISTS VOC <<U,@LOGNAME>>.LOGIN THEN <<U,@LOGNAME>>.LOGIN
Note that the LOGIN paragraph runs for all QM processes; terminal users, phantoms, QMClient connections, etc. It may be necessary to insert conditional elements to limit execution by some process types, for example,
IF @TTY = 'phantom' THEN STOPThis last example references the @TTY variable directly without an inline prompt construct as only simple substitution of the variable content is required. The IF command is the only QM command in which @-variables can be referenced directly. All other commands would treat the @-variable name as literal text.
The MASTER.LOGIN Paragraph
The LOGIN paragraph described above is specific to the account in which it resides. Sometimes it is useful to have an initialisation script that will be executed for all QM processes, regardless of the account in which they run. This can be done by creating a MASTER.LOGIN paragraph in the QMSYS account.
The MASTER.LOGIN paragraph is run before the LOGIN paragraph. Note that it is executed only on initial entry to QM, not on switching accounts with LOGTO.
The ON.LOGTO Paragraph
QM provides an optional command script named ON.LOGTO that runs as part of the LOGTO command, prior to switching accounts. It allows an application to perform any termination tasks such as removal of temporary data files or deletion of application specific named common.
The ON.EXIT Paragraph
The ON.EXIT paragraph, if present, is executed on leaving QM. This includes termination initiated by the application and use of the LOGOUT command to kill another process.
The ON.ABORT Paragraph
The ON.ABORT paragraph allows an application to trap abort events that occur as as result of a fatal runtime error, execution of an ABORT statement, or selection of the A option at the break key action prompt. The primary purpose of the ON.ABORT paragraph is to allow the application to take some action for tidy termination rather than taking the user to a QM command prompt.
An abort event occurring while executing the ON.ABORT paragraph will terminate the QM process immediately.
00036: Inline Prompts