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.
Q If the file-specifier is a Q-pointer, then attribute 6 of the MD command definition item is the name of that Q-pointer.
Absent this option, attribute 6 is the value of the Q-pointer. This is usually preferred as it allows BVERIFY to access the source even if the original Q-pointer is deleted.
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.
Note
-
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.
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 cataloged.
When any local source item is compiled and cataloged, 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 |
Note
By default, nothing is logged; the user has to enable compile/catalogue history logging by adding the HISTORY data section.
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
Example 1
:CATALOG BP TEST1Catalogs the program TEST1 in the file BP. The following message is displayed:
[241] 'TEST1' Cataloged.
Example 2
:CATALOG FILEA 1 2 3Catalogs 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 (RUses 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.