The Command Environment
Although applications commonly use the graphical interface capabilities of QM via Visual Basic, AccuTerm or web browsers, developers normally work from the character mode interface command prompt using a terminal emulator or directly from the system console. Commands can also originate from within application programs.
Commands entered at the terminal or generated from within a QM application are processed by the command processor. This uses the vocabulary file (VOC) to determine the meaning of each word or symbol within the command.
The default command prompt is the colon character. Whenever this is displayed at the start of a line, QM is ready to accept a new command. The command prompt changes to a double colon if the default select list is active. This serves as a warning that the select list may impact execution of the next command. The prompt characters may be modified using the PTERM command.
By default, QM operates with "case inversion" - that is, characters entered in lowercase letters are displayed in uppercase and vice versa. The original multivalue systems date back to a time when many terminals did not have lowercase letters and hence the command language was written to work in uppercase. To make it easy to operate in situations where a user may be switching between a QM session and, for example, a Word document, QM normally applies case inversion so that the user does not need to keep hitting the caps lock key.
Actually, QM is largely case insensitive but this feature is retained for compatibility with other systems. It can be disabled by typing
PTERM CASE NOINVERT
and this would usually be done as an automated part of the login process for an end user of the application. Alternatively, the default state may be changed by use of the INVCASE configuration parameter.
A command consists of a number of tokens separated by spaces. Where a token includes spaces, it must be enclosed in quotes. QM allows use of single quotes, double quotes or backslashes interchangeably though recognition of backslashes as quotes in the command processor can be disabled with the BACKSLASH.NOT.QUOTE mode of the OPTION command.
The first token of a command normally corresponds to the name of an executable item within the VOC. This will be the name of a verb, sentence, paragraph, menu or Proc (terms that will be defined in the following sections). It is also possible to run a program from the system catalogue by typing its name as a command. Other valid actions at the command prompt are:
Command stack operations, prefixed by a dot character
Save the command without execution by appending a question mark
The command processor performs the VOC look-up for a command in three stages; firstly by looking for a record with a name matching the first token in the command exactly as entered. If this fails, it then tries again with the name mapped to uppercase. All system verbs have uppercase names and can therefore be entered in lowercase, uppercase or a mix. For compatibility with Pick databases, a third attempt is made with any hyphens in the uppercase version of the name replaced by dots. Thus a command such as CREATE.FILE can be entered as create.file or CREATE-FILE.
If the command is not found in the VOC, a check is made in the private and global catalogues. If the name exists here, the catalogued program is executed. The names of catalogued programs executed in this way must commence with a letter or an asterisk. When executing a catalogued program in this manner, the command processor will look for and handle the LPTR and NO.PAGE keywords in the same way as the RUN command, leaving them in place so that the executed program will also see them if it performs its own command line scan.
Finally, if the command has still not been located, the command processor looks in the private vocabulary, if this exists.
Many commands perform the first two phases of this look-up for the remaining tokens on the command line (file names, keywords, etc), however, commands that might have a detrimental effect if used in error (DELETE.FILE, for example) either insist on the file name being entered exactly as it appears in the VOC or prompt for confirmation if the name is not an exact match.
Command lines commencing with an asterisk followed by at least one space are treated as comments and are ignored except that inline prompts are still processed. Although comments are primarily of use within paragraphs, they can be entered directly at the keyboard when they will appear in any active como file.
Many QM commands return status values via the @SYSTEM.RETURN.CODE variable. In general, a positive or zero value indicates success. A negative value is an error code and the actual value is the negative of the codes listed in the ERR.H include record in SYSCOM.