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 Master Dictionary - the dictionary file that defines an account. It contains items that point to the code executed by all the TCL commands, to SYSTEM accounts, and to other accounts by means of Q-pointers. The MD also includes all File Definition Items for the account and other items. 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:

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

2. A command definition item with the same name as the source item is created in the MD Master Dictionary - the dictionary file that defines an account. It contains items that point to the code executed by all the TCL commands, to SYSTEM accounts, and to other accounts by means of Q-pointers. The MD also includes all File Definition Items for the account and other items. of the current account, referencing the executable item that was found or created. This item can be copied to other accounts if required.

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 An Account or File Synonym Definition Item. Q-pointers allow users to address information in accounts other than the one they are currently logged onto or in files for which they otherwise are not allowed access. 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.

History

The DataBasic history feature provides a mechanism to log history data to allow reporting and analysis of the usage of DataBasic programs, subroutines and external user functions. You create a separate HISTORY data section in your source files, and this section is used by the system to log the history usage of the code whenever it is complied and catalogued.

When any local source item is compiled and catalogued, a history log item with the same DataBasic program name is automatically written to the HISTORY data section of the source file (if such a section exists). Any previous history item is overwritten. The log item comprises the attributes shown in the following table (compilation is logged in attributes 1-7, cataloguing is logged in attributes 8-14).

Attribute	Description
1	Date of successful compilation (internal format)
2	Time of successful compilation (internal format)
3	PLID of successful compilation
4	ID of user requesting compilation
5	Account of successful compilation
6	Location of source (filename - including the data section, if appropriate)
7	Source item ID
8	Date of successful catalog (internal format)
9	Time of successful catalog (internal format)
10	PLID of successful catalog
11	ID of user requesting catalog
12	Account of successful catalog
13	Location of executable object (filename)
14	Executable item ID

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.