The VOC File

The VOC File

Top  Previous  Next


The VOC file is central to everything that QM does. This file is the vocabulary of words and symbols that may appear in commands and holds many other things as well. The initial VOC file is a copy of NEWVOC from the QMSYS directory. By modifying the VOC it is possible to change the names of commands to meet particular needs of an application or user. It would be possible, for example, to include French translations of all the command names. More often, changes are made simply to use wording that is more appropriate to the manner in which the product is used.


Records in the VOC are of differing types, the type of the record being determined by the first one or two characters of field 1 of the record. The remainder of field 1 after the identifying characters may contain any value and is typically used to comment the role of the VOC entry.


The VOC record types are


DData item
Defines a field within a data file. D type entries may appear in the VOC but are more commonly found in dictionaries.


Defines a file, relating its application level name for use within QM to its operating system pathname.


Many commands have keywords which affect the behaviour of the command or introduce optional clauses in the command syntax.


A menu record defines a menu that can be displayed by executing the VOC entry.


A paragraph is a sequence of commands that can be executed by entering the name of the VOC entry.


A phrase is a short form for a sequence of items to be substituted into query processor commands.


A PROC is the predecessor of paragraphs. QM supports PQN style PROCs for use when migrating applications. It is recommended that new developments should use paragraphs or QMBasic programs instead.


QRemote File
A remote file pointer refers to a file in another QM account, perhaps on a different server.


An R type VOC entry points to a record in another file which is constructed in the same way as an executable (M, PA, R, S or V type) VOC entry.


A sentence is a single command.


A verb is the portion of a command which identifies the part of QM which will process it.


X type records may be used to store miscellaneous information in the VOC.



VOC record types Y and Z will never be defined as part of the standard QM product and are available for whatever purpose a developer may find useful. Other type codes not listed above may be defined in future releases.


Users may add handlers for other VOC record types that are to be usable as commands. This is done by creating a VOC record named $VOC.PARSER:

Field 1        X

Field 2        A multivalued list of VOC record type codes.

Field 3        A corresponding multivalued list of catalogued handler subroutine names.


The handler is a QMBasic subroutine taking two arguments; the verb name and the VOC record. It is necessary to use LOGTO or exit and re-enter QM after adding or modifying the $VOC.PARSER record.



The VOC includes an F-type entry referencing itself so that commands that access the VOC do not have to treat it as a special case. Users must not modify this VOC entry as any change is likely to cause QM to malfunction because internal components reference the VOC by pathname.


The VOC also includes a Q-type entry named MD as a synonym for VOC for compatibility with other systems.



Making the VOC Case Insensitive


The CREATE.ACCOUNT command has an option to create the account with a case insensitive VOC file. Converting the VOC of an existing account is a little more complex as the reconfiguration of the VOC file requires that no QM process has it open at the time. The easiest way to achieve this is to set up an F-type VOC entry from some other account, referencing the pathname of the VOC that is to be modified. Although a Q-pointer may seem more logical, the CONFIGURE.FILE command requires that the file is accessed via an F-type item.

Once the F-type item is in place and all users of the account have logged out or moved to another account, use CONFIGURE.FILE with the NO.CASE option to reconfigure the required VOC file.


It is strongly recommended that the original VOC file is backed up before making this modification.



The Private VOC


The vocabulary file is shared by all users of the account to which it belongs. To allow users to store private commands (verbs, sentences, paragraphs, menus, Procs), QM also supports use of a private vocabulary file that is separate for each operating system level user name. This is a multi-file named PVOC with subfiles names that are the uppercase version of the user's login name. The private vocabulary is checked only after failing to find the item in the VOC and the catalogue. It is only used to locate command names, not other VOC record types such as phrases, keywords or files.


The private vocabulary file may be created and modified directly by of CREATE.FILE, ED, SED, etc. Alternatively, the "dot commands" of the command stack editor include options in .D, .L, .R and .S to access the private vocabulary. First use of .SP in this mode will create the private vocabulary file if it does not already exist.


Unlike the VOC file, which the command processor opens by pathname, the private vocabulary is opened using the normal indirection via a VOC F-type record. It is therefore possible to set up the VOC record such that groups of users share a common private vocabulary or so that one user sees the same private vocabulary from multiple accounts.


The optional LOGIN, ON.EXIT, ON.LOGTO and ON.ABORT command scripts must reside in the VOC file, not the private VOC.