CATALOGUE

The CATALOGUE command (which may be entered with the American spelling for compatibility with other products) adds a compiled QMBasic program to the global or private catalogue file or as a locally catalogued entry in the VOC.

file.name

is the name of the directory file holding the program. If omitted, this defaults to BP, the .OUT suffix being added automatically.

catalogue.name

is the name by which the program or subroutine is to be catalogued. If omitted, the record.name is used. The catalogue name is translated to uppercase though calls from QMBasic programs are case insensitive. Except as described below, catalogue names must start with a letter. Subsequent characters may be letters, digits, periods, percent signs, dollar signs, hyphens or underscores.

For compatibility with other database systems, the catalogue.name may also commence with a digit though such catalogued items can only be used as user defined conversion codes and not as call names in programs.

record.name

is the name of the record within the specified file. The record.name may be specified as an asterisk to catalogue all programs in file.name. If record.name is omitted and the default select list is active, this list will be used to determine the programs to be catalogued.

PRIVATE

The program is to be placed in the private catalogue for use only by this account.

GLOBAL {c}

The program is to be catalogued for use by all accounts. The optional c component of this command is the prefix character to be used if the catalogue.name does not already include a prefix.

NO.PAGE

Suppresses page end prompts when output exceeds page length (e.g. use of select list).

NOXREF

Catalogues the program without any symbol and line cross-reference information. This results in lower disk and memory usage but prevents full diagnostic messages in case of run time errors.

RELATIVE

Used with LOCAL, this causes the pathname stored in the VOC item to be a relative pathname so long as the program file is a subdirectory of the account.

FULL.PATH

Used with LOCAL, this causes the pathname stored in the VOC item to be a full pathname.

The CATALOGUE command makes a program or subroutine available for access via the QMBasic CALL statement. Catalogued programs can also be executed as command simply by entering their name at the command prompt or within a stored sentence or paragraph.

If none of the LOCAL, PRIVATE or GLOBAL catalogue mode options is present, the default action is to use the private catalogue. The CATALOGUE.LOCAL setting of the OPTION command changes this default to be the local catalogue. Where the name of the item to be catalogued starts with one of the reserved prefix characters described below, it is always placed in the global catalogue.

Compiling a program signals an event to all QM processes to reload the object code. See the QMBasic CALL statement for full details.

The program is copied to the private catalogue in the account from which the command is executed and is available only to users of that account. Recompiling the program requires that the program is recatalogued so that the new version is copied to the catalogue directory. A failed compilation, where no object code has been produced, will not impact users of the previously catalogued version.

The private catalogue is normally a subdirectory, cat, under the account directory but can be moved by creating an X-type VOC entry named $PRIVATE.CATALOGUE in which field 2 contains the pathname of the alternative private catalogue directory. This only takes effect when QM is re-entered or on use of the LOGTO command. This feature is particularly useful where two or more accounts are to share a common private catalogue. The US spelling, $PRIVATE.CATALOG, may be used instead. If both are present, the British spelling takes priority.

The program is copied to the global catalogue file in the QMSYS directory and is available from all accounts. For compatibility with other products, global cataloguing is also implied by adding one of the following prefix characters to the catalogue.name of the program:

Use of a prefix character has the disadvantage that the prefix must also be included in calls to the subroutine as it becomes part of the subroutine name.

Recompiling the program requires that the program is recatalogued so that the new version is copied to the catalogue directory. A failed compilation, where no object code has been produced, will not impact users of the previously catalogued version.

A record is written to the VOC file as a pointer to the object code allowing calls only from the account in which the program is catalogued.

The VOC entry for a locally catalogued program is of type V (verb) and has a dispatch field of CS. The third field holds the full pathname of the executable program. When QM is installed on a USB memory device, the pathname will be transformed internally to a format that allows for the drive letter to be different when the stick is loaded in future. Use of the RELATIVE option to the CATALOGUE command stores a relative pathname so long as the program is in a subdirectory of the account directory. Use of the FULL.PATH option stores the full pathname. If neither option is present, the pathname is saved in the form determined by the setting of the LOCAL.CAT.RELATIVE mode of the OPTION command.

If a locally catalogued program that has a security subroutine defined in its VOC entry is recatalogued, the security subroutine name is carried forward to the new VOC entry.

Recompiling the program does not require the program to be recatalogued as the VOC pointer will still be in place. A failed compilation, where no object code has been produced, may cause other processes to fail. Use of the KEEP.OLD.OBJECT mode of the OPTION command will retain the old object code at a compilation error.

CATALOGUE, CATALOG