CATALOG

Catalogs a compiled DataBasic program, so that it can be run by entering the program name at TCL and shared between accounts.

See Introduction to DataBasic for descriptions of the types of item used and created by this process.

Syntax

CATALOG file-specifier item-list {(options}

Syntax Elements

file-specifier Specifies the file containing the items to be cataloged.

item-list A space-separated list containing the item-ids of the items containing the programs to be cataloged. An asterisk (*) specifies all the items in the file. The list can be provided by an immediately-preceding list-generating command.

Options

I Catalogs the program under another account name. The system prompts you for the account name.

If an executable item was not created when the program was compiled, an item is created (or updated) in the global POINTER-FILE; the id of this item includes the name of the specified account. A command definition item is also created in the MD of the specified account. See Operation for details.

If you do not specify an account, the system uses the account you are in.

L Must be used with the I option – updates the local MD rather than the MD of the specified account. This means that the program cannot be executed from the account under which it is cataloged.

If you specify the L option without the I option, it is ignored.

O Overwrites any existing item in the MD file. Without this option, CATALOG will not proceed if an MD entry with the specified program name is found, but it is not a cataloged DataBasic program definition item referencing the program being cataloged.

R Forces regeneration of an executable (platform-specific) item in the dictionary of the file from a deliverable (platform-independent) item. See Introduction to DataBasic for descriptions of these different types of item.

If the MD item points to the global POINTER-FILE, an error message is displayed.

This option is provided for compatibility with Procs written for earlier versions of Reality. Its use should not normally be necessary.

X Does not update any MD. This means you cannot execute the cataloged program at TCL.

You must use the X option with the I option. If you specify the X option without the I option, it is ignored.

Operation

Cataloging a program is a two stage process:

If the executable (platform-specific) item does not already exist, one is created from the deliverable (platform-independent) item and saved in the global POINTER-FILE with the name account*C*name, where account is the name of the account under which the program was cataloged, and name is the name of the program (that is, the name of the deliverable item without the initial $ or £).
- If an executable item already exists in the global POINTER-FILE, it is replaced with a new one, created from the current deliverable item.
- If an executable item is found in the dictionary of the specified file, a new executable is not created.
See Introduction to DataBasic for descriptions of these different types of item.
A command definition item with the same name as the source item is created in the MD of the current account, referencing the executable item that was found or created. This item can be copied to other accounts if required.

Notes:

If you compile a deliverable item, each time you recompile, you must also recatalog to create a new executable item in the global POINTER-FILE.
If you compile an executable item, you only need to catalog your program once. The executable item referenced by the command definition item is overwritten when you recompile.

When the program has been cataloged, the following message is displayed:

[241] item-id Cataloged.

If the item already exists in the MD, but is not a DataBasic program definition item, the program is not cataloged and the following message is displayed:

[415] item-id Exists on file

The CATALOG.COMP environment option relaxes the conditions under which an MD entry can be overwritten. If set, any cataloged DataBasic program definition item can be replaced, even if it references a different program. However, unlike the O option, CATALOG.COMP prevents other types of MD entry being overwritten.

Why Catalog?

There are several reasons why you should catalog your DataBasic programs:

It provides a simple way of making your program available to other users of the database. Simply copy the MD item to each account that needs the program. Note, however, that if your executable item is in the file dictionary, you must also create a Q-pointer to the file containing the executable item.
The time needed to execute a program is reduced, because if only a deliverable version is available, it must first be converted to an executable, and also because cataloged programs are executed by using just the item-id of the program as a command.
It saves memory space by reducing the number of copies of the executable code that are required. The same copy of the executable code is used by every user who runs the program. This is of particular benefit if you have a large number of users.
You can create a synonym for the program by creating a copy of the MD program definition item with a different name. There is no need to copy and recompile the source program.
External subroutines must be cataloged.

Comments

To list the items in the POINTER-FILE, use the LISTPF command.

To display the time and date that a specified cataloged DataBasic program was compiled use the PRINT-CATALOG command.

Example 1

:CATALOG BP TEST1

Catalogs the program TEST1 in the file BP. The following message is displayed:

[241] 'TEST1' Cataloged.

Example 2

:CATALOG FILEA 1 2 3

Catalogs the three DataBasic programs with item-ids of 1, 2, and 3 in file FILEA. The following messages are displayed:

[241] '1' Cataloged.
[241] '2' Cataloged.
[241] '3' Cataloged.

Example 3

:CATALOG BP TEST2 (R

Uses the deliverable item for the program TEST2 in the file BP to regenerate the executable item and the command definition item TEST2 in the account's MD. Any existing items are overwritten or deleted. The following message is displayed:

[241] 'TEST' Cataloged.