CATALOGUE, CATALOG

Top  Previous  Next

 

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.

 

 

Format

 

CATALOGUE {file.name {catalogue.name}} record.name {options}

 

where

 

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

 

catalogue.nameis 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.nameis 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.

 

optionsare any of the following:

 

LOCALThe program is to be catalogued in the VOC.

 

GLOBALThe program is to be catalogued for use by all accounts.

 

NO.QUERYSuppresses all confirmation prompts.

 

NOXREFCatalogues 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.

 

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.

 

 

Private Cataloguing

 

Without either the LOCAL or GLOBAL keyword, 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.

 

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.

 

 

Global Cataloguing

 

With the GLOBAL keyword, the program is copied to the global catalogue file in the QMSYS directory and is available from all accounts. Global cataloguing is also implied by adding one of the following prefix characters to the catalogue.name of the program:

 

 

*User subroutine prefix provided for compatibility with other systems
!User callable system supplied subroutines
_Internal undocumented subroutines
$System subroutines, only callable from internal mode programs

 

 

Local Cataloguing

 

With the LOCAL keyword, an entry is written to the VOC file allowing calls only from the account in which the program is catalogued. This is useful during testing or for functions that are not called frequently. The first call to programs catalogued in this way are slower than to private or globally catalogued programs. Once the program has been loaded into memory, speed will be identical.

 

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 pathname of the executable program.

 

 

See also:

BASIC, DELETE.CATALOGUE, MAP