A MAINSAIL program is a collection of MODULEs. The MODULEs are not linked into a single unit as is common for most programming languages. Instead, MAINSAIL dynamically brings MODULEs into memory as needed and takes care of intermodule communication in a machine-independent manner.

MODLIB, the objmod librarian, is used to create and maintain objmod (object MODULE) libraries. MODULE libraries provide a means of logically organizing MAINSAIL object MODULEs. Some advantages of MODULE libraries over individual object MODULE files are listed below:

• When a system consists of several MODULEs, putting them into a MODULE library eliminates the need for individual object MODULE files, thus reducing clutter in the file system.

• An objmod library is opened once (for execution access) during execution. Each MODULE that does not reside in an object MODULE library is individually opened during execution when it is first accessed. This is generally a time-consuming operation.

• Sometimes it is necessary to remove MODULEs from memory in order to make room for another MODULE. A MODULE that does not reside in memory must first be written to a “swap” file before its space is used. A MODULE that resides in an open library need not be written to the swap file.

As described in Chapter 14 of the MAINSAIL Language Manual, MODULE libraries open for execution access are searched when MAINSAIL needs to allocate a MODULE for which a control section does not already exist in memory. They are searched in order of most recently opened to least recently opened so that if two MODULEs with the same name exist in two libraries, the MODULE in the most recently opened library is found and used.

There are two ways in which an objmod library can be “open”: for execution access and for read/write access. The PROCEDURE openLibrary and the MAINEX subcommand OPENLIBRARY open objmod libraries for execution access. Some MAINEX and compiler subcommands are used to open libraries for read/write access; such libraries are used in objmod searches, e.g., by the compiler, and are also cached for MODLIB operations. The list of objlibs open for execution is distinct from the list open for read/write access; both are global to the entire MAINSAIL session.

There are no restrictions on the way in which MODULEs are organized in objmod libraries. A MODULE library might consist of all MODULEs related to a given program, or it might consist of several unrelated “utility” MODULEs. However, all objmods in an objmod library must be for the same target system (unlike intmod libraries).

MAINSAIL does not impose a limit on the number of MODULE libraries that may be open during execution, although the underlying operating system may have a limit on the number of open files.

A MODULE library can be opened for execution access in any of the following ways:

1. With the system PROCEDURE openLibrary (see Section 43.6 of the MAINSAIL Language Manual).

2. With the MAINEX OPENEXELIB or OPENLIBRARY subcommand (see Section 21.2.29). This subcommand may be specified interactively or in a MAINSAIL bootstrap.

3. With the MAINDEBUG OL command (see Section 4.31 of the MAINDEBUG User's Guide).

24.1. How MAINSAIL Opens Library Files

Unlike libraries open for execute access, objmod libraries open for read/write access are not open files; i.e., they do not consume an operating system file handle. The files are opened when information is added to them or extracted from them and then immediately closed; however, they are considered to be “open” libraries because the MAINSAIL runtime system maintains a global list of libraries open for read/write access. Objmod libraries for read/write access remain open until explicitly closed.

24.2. MODLIB on Old Libraries

• display directories

• show legal notices

• call $moduleInfo

Other operations (e.g., extraction, copying, or addition of MODULEs) are allowed only on object MODULEs whose format matches the format used by the current version of MAINSAIL.

24.3. Library Size

MODLIB automatically extends the size of a library file to accommodate new MODULEs. However, a library file never shrinks; if many deletions are done without corresponding adds that reuse the space freed by the deletions, it may be desirable to use the COPY command to compact the library into a new file.

24.4. MODLIB Commands

• modList is a list of MODULE specifications separated by blanks. A MODULE may be specified differently depending on the command, as summarized in Table 24–1.

• libName is a library file name. sLibName is a source library name (the name of a library from which MODULEs are removed or copied) and dLibName is a destination library name (the name of a library to which MODULEs are added).

• Anything enclosed in curly brackets ({ and }) is optional.

A very long MODLIB command may be broken across several lines by terminating each line with a backslash (\). Thus, the command lines:

add foo.lib\
 abc\
 def\
 ghi

are equivalent to the single command line:

add foo.lib abc def ghi

24.4.1. <eol>, QUIT

To exit, type <eol> or QUIT when you are finished using the MODULE librarian.

24.4.2. ADD dLibName modList

Add the MODULEs specified by modList to the MODULE library dLibName. modList is a list of MODULE specifications, separated by blanks. Valid MODULE specifications for this command are given in Table 24–3. Different types of MODULE specifications can be mixed within modList.

If dLibName does not exist, it is created. If free pages constitute more than a certain fraction of dLibName and dLibName contains no hole large enough to accommodate a MODULE in modList, the library is compacted.

24.4.3. COPY sLibName dLibName{ modList}

Copy the MODULEs specified by modList in sLibName to dLibName. If modList is absent, copy all MODULEs in sLibName. If dLibName does not exist, it is created.

If dLibName does not exist before the COPY command, then it contains no holes after the command is completed. Thus, the COPY command may be used to compact a library with unused space.

24.4.4. CREATE libName

Create a MODULE library named libName. The MODULE library is initially empty.

24.4.5. DEFINE libName s

libName is defined as an alias for the library named s. libName can later be used anywhere a library file name would be used as part of a MODLIB command, e.g.:

DEFINE foo /fs3/usr/fxi/fxi74200.40/src/src/fgc.olb
ADD foo mod1 mod2 mod3
ADD foo mod4 mod5 mod6
DIRECTORY foo

The motivation for this command should be clear from the above example.

24.4.6. DELETE sLibName modList

Delete the MODULEs specified in modList from the MODULE library libName. modList is a list of MODULE names separated by blanks.

24.4.7. DIRECTORY libName{=fileName}{ modList}

List information about the MODULEs contained in the MODULE library libName. libName may be the character * if the MODULEs reside in individual object MODULE files instead of in a MODULE library. fileName is the name of the file to which the list is to be written. If fileName is omitted, the list is written to logFile. modList is a list of MODULE names to be included in the directory list, separated by blanks. Valid MODULE specifications for DIRECTORY are moduleName and fileName. If the MODULE resides in a library, only moduleName is permitted. If the MODULE does not reside in a library (* was specified for the library name), then if moduleName is specified, a file name is formed in the operating-system-dependent default fashion. If fileName is specified (the given STRING is not a possible MODULE name), the given file name is used. The object MODULE in the named file is examined.

If modList is omitted, all MODULEs in the MODULE library are listed.

The information listed includes the MODULE's directory name, the MODULE name, the number of pages it occupies, the date and time when it was compiled, the version for which it was compiled, and the options with which it was compiled. Example 24–4 is a sample session with MAINSAIL showing execution of the MODLIB directory command and the resulting listing.

The meanings of the letters shown in the options column of the directory listing are shown in Table 24–5. For example, CDL indicates that the MODULE was compiled with checking initially set, debuggable, and with a legal notice. Cmp, Cms, Cps, or Cmps is used to display multiple counting options. Tmp is displayed to indicate both MODTIME and PROCTIME options.

If you specify the argument ? to the DIRECTORY command, MODLIB displays the list of compiler option abbreviations it uses in the DIRECTORY command output (e.g., C for CHECK, AC for ACHECK, etc.).

24.4.9. EXTRACT sLibName{ modList}

Extract (copy to individual objmod files) the specified MODULE(s) from the MODULE library libName. modList is a list of MODULE specifications, separated by blanks. Valid MODULE specifications for this command are given in Table 24–6. Different types of MODULE specification can be mixed within modList.

If modList is omitted, all MODULEs are extracted from the library and written to their default files.

24.4.10. LEGALNOTICE libName{ modList}

The library and MODULEs examined are selected in accordance with libName and modList in the same way as by the DIRECTORY command. The legal notices of the examined MODULEs are written to logFile.

24.4.11. LOG/NOLOG

Default: LOG

LOG enables the informational messages written by MODLIB when operating on libraries. NOLOG cancels LOG.

24.4.12. MOVE sLibName dLibName modList

Move MODULE(s) from sLibName to dLibName. modList is a list of MODULE names to be moved, separated by blanks. The specified MODULEs are copied to dLibName and deleted from sLibName. Valid MODULE specifications for this command are given in Table 24–7. MODULE specifications can be mixed within modList.

If dLibName does not exist, it is created.

Give a quick list (MODULE names only) of the MODULEs contained in the MODULE library libName. The parameters to QDIRECTORY have the same meaning as the corresponding parameters to DIRECTORY.

24.4.14. READ fileName

READ causes MODLIB commands to be read from the named file. The READ command can be used to do nested readings to an arbitrary depth.

24.4.15. TARGET{ targetSystem}

The TARGET command specifies the operating system for which subsequently opened libraries are formatted. The TARGET command does not affect the target of libraries that have already been opened. The specified target is in effect until the end of the MODLIB session or until another TARGET command is given. The initial target is the same as the host system.

If the target system is omitted, the target is set to the host system.

targetSystem is the system abbreviation for the target system. TARGET ? causes a list of valid target abbreviations to be displayed.

If MODLIB assumes the wrong target when a library is opened, undefined errors result. Therefore, you must be careful to specify the correct target.

24.4.16. UPDATE/NOUPDATE

Default: UPDATE

Operations modifying large libraries (i.e., adding or deleting MODULEs) take longer than operations on small libraries. After each MODLIB command, the updated directory list for every modified library is written to the corresponding library file, and all library files open by MODLIB are closed. This helps keep the library files in a consistent state should a system crash or other abort occur between commands, and keeps the number of open files to a minimum. As the directory gets large, it takes longer and longer to store and read it each time.

Since the storing of the directory occurs only after each command, the single command COPY srcLib dstLib is a much faster way to copy all MODULEs from srcLib to dstLib than a separate command for each MODULE. If not all MODULEs are to be copied, then the command:

COPY srcLib dstLib mod₁ mod₂ ... mod_n

is faster than n separate commands since just one library update occurs (after all the MODULEs mod_i have been copied).

However, there are times when it is more convenient to use a separate command for each MODULE, e.g., in a script generated by a program, or when the commands are being sent to MODLIB through calls to $executeModlibCommands. The UPDATE and NOUPDATE commands may be used to handle such situations.

The default is UPDATE. Once the NOUPDATE command is given, all libraries referenced are kept open, and directories are not written to each altered library after each command. The UPDATE command turns off this effect of NOUPDATE, and also immediately closes all libraries and updates the directories of all altered libraries. An altered library is updated when it is closed, even if NOUPDATE is in effect (all libraries are closed by MODLIB's FINAL PROCEDURE, so all libraries are updated when MAINSAIL exits).

The commands:

NOUPDATE
COPY srcLib dstLib mod1
COPY srcLib dstLib mod2
...
COPY srcLib dstLib modn
UPDATE

execute faster than the same commands without the surrounding NOUPDATE and UPDATE commands. The speed-up may be significant when many MODULEs are involved.

If the system should crash, or if the MAINSAIL execution is aborted, between NOUPDATE and UPDATE, the libraries opened for output access may be in an unrecoverable state.

24.5. MODLIB as a Device Prefix

"MODLIB(" & libName & ")" & $devModBrkStr & modName

The case of the letters in MODLIB and modName is not important.

For example, on systems where $devModBrk is the character >, a MODULE FOO in a library proj-xxx.olb would be specified by:

modlib(proj-xxx.olb)>foo

If no library is specified, e.g., if the syntax:

"MODLIB" & $devModBrkStr & modName

is used, all open objmod libraries are searched for modName. When a MODLIB file f is opened, f.name is modified to include the library name in the file name if it was not included in the call to open.

MODLIB files cannot be opened for output access; i.e., they must be opened read-only.

24.6. MODLIB Program Interface

MODLIB can be controlled from a user program by calling the PROCEDURE $executeModlibCommands, declared as shown in Figure 24–8.

cmds is a STRING that contains exactly what would be typed by a user giving commands to MODLIB. In addition, f can indicate a file from which commands are read once cmds becomes empty. If f is omitted, cmdFile is used. To force MODLIB to return rather than read from f when cmds becomes empty, specify the QUIT command as the last command in cmds.

A return value of FALSE indicates that an error occurred during processing of a command. errMsg is called to report the error; the invoking program can intercept the error using the MAINSAIL exception mechanism. In this case, $exceptionStringArg1 starts with the substring MODLIB:.