CATALOG

The CATALOG command is provided as a front end program to convert object files generated by the BASIC command into main program executables and shared libraries/DLLs of subroutines.

CATALOG -Llib -obin -v -cExternalCLibs BP PROGRAM1 SUB1

Where options are:

Option	Explanation
v	verbose
Llib	alternative lib directory to use for shared libraries
obin	alternative bin directory to use for executables
cExternalLibs	external C library functions

Main program executables by default are copied in the home directory "bin" directory. Subroutine object files are collated into evenly sized shared libraries and then by default placed in the home directory "lib" directory.

In order to be able to rebuild a shared library the object file is retained in the "objdir" subdirectory of the "lib" directory. These object files are no longer required once all the shared libraries have been debugged and ready to release.

The CATALOG command invokes the jBASE jBuildSLib command with the subroutine object file to construct the shared libraries. The jBuildSLib command then links several object files together with relevant references to other required libraries and creates a shared library/DD.

It should be noted that every time a subroutine is cataloged, jBuildSLib is invoked to rebuild the shared library/DLL. However when the CATALOG command is issued with an active select list of program names, the rebuilding (i.e. jBuildSLib) is deferred until the list has been fully processed. This means that each shared object/DLL is only rebuilt once, as opposed to once for each subroutine. So when cataloging subroutines, it is much faster to work from an active select list. The same is true when decataloging subroutines.

To force the CATALOG command to place executables and shared libraries in alternative directories to the "bin" and "lib" directory in the current home directory, the following environment variables can be set.

To redirect main executables use:
export JBCDEV_BIN=/usr/global/bin (Unix)
set JBCDEV_BIN=C:\GLOBAL\BIN (Windows)

To redirect subroutine shared libraries use:
export JBCDEV_LIB=/usr/global/lib (Unix)
set JBCDEV_LIB=C:\GLOBAL\LIB (Windows)

To link with external C function libraries:
export JBCDEV_CLIB=/usr/global/clib (Unix)
set JBCDEV_CLIB=C:\GLOBAL\CLIB (Windows)

Programmers should be aware that by convention jBC program names have an extension of ".b" (and also ".B" on Windows). The jbc command expects programs specified as "name.b". The BASIC and CATALOG commands do not require programs to have a .b extension because they add one when necessary. This can be seen when the verbose option is used on BASIC and CATALOG. If a main program has a .b extension, it is dropped when the program is cataloged. For example, if the name of the program is CUSTMAINT.b, the resulting executable created by CATALOG is called CUSTMAINT. If a subroutine has a .b extension, then it's internal name should not have the extension:

valid	Invalid
`UPDATECUST.B`	`UPDATECUST.B`
`SUBROUTINE UPDATECUST(a,b,c)`	`SUBROUTINE UPDATECUST.B(a,b,c)`

In this instance the subroutine would be called as:

CALL UPDATECUST(x, y, z)

JLIBDEFINITION FILE

The jLibDefinition file is used by default to configure the size and naming convention for each shared library. If the "lib" directory already exists then the jLibDefinition file is read from the "lib" directory. If this is the first time the "lib" directory is created then the jLibDefinition file is read from the "config" subdirectory of the jBASE release directory.

The configuration options contained in the jLibDefinition file are as follows:

%n - Use sequence number from 0 upwards
%a - Use account name, truncated to 8 characters.
%f - Use source filename

libname	Naming convention to use for library
exportname	naming convention to use for export file
objectdir	naming convention to use for object directory
maxsize	maximum size of the shared objects based on object size; default is 1MB for Unix and 8MB for Windows
baseaddress	base address for the first DLL created in a library (Windows only)

e.g. a "libname" definition of lib%a%n.so would result in libraries named as follows:
libAccount0.so
libAccount1.so

WINDOWS CONSIDERATIONS

Use of the %a definition should be restricted to small account/user names only, as the performance of scanning directories can be severely downgraded when the library file names as greater than 8.3 in length.
Because of a virtual memory overhead per DLL, it is best to have as few DLLs as possible. The default size is 8MBytes. If it is set too high, the linker cannot build the DLL. As CATALOG bases the size of the DLL on the sum of the component objects files, this equates to a DLL that is approximately 5 Mbytes.
An attempt is made to make sure that the users DLLs do not need to be relocated as this process causes them to become private (i.e. not shared). This is done by setting a unique base address for each generated DLL. The "baseaddress" entry is used for this, the default is 0x30,000,000 (or 768MByte). The jBASE system DLLs are based at 0x20,000,000 (512MByte) so this value should not be used. NT System DLLs are at 0x70,000,000. The first user DLL (normally lib0.dll) will be based at this specified address, with each subsequent one incremented by "maxsize". This should avoid any overlap since the "maxsize" value is based on the size of the objects and not the DLL which is usually about 75% of this figure.

Compiling