Command line syntax: intlib {oneIntlibCommand}

INTLIB, the intmod librarian, is used to create and maintain intmod libraries. Putting several intmods into an intmod library eliminates the need for individual intmod files, reducing clutter in the file system.

Many INTLIB commands are similar to those of MODLIB, the objmod librarian.

“Open” intmod libraries are not open files; i.e., unlike objmod libraries opened for execution, 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. All MAINSAIL programs that use intmods may search for them in the same global intmod library list, and all program commands that open an intmod library add it to the global list. For example, opening an intmod library with the MAINEX subcommand OPENINTLIB opens it for the purposes of the compiler, opening an intmod library in the compiler opens it for the purposes of the debugger, etc. Intmod libraries remain open until explicitly closed.

Modifying an intmod library on the global open intmod library list has undefined effects.

As described in Chapter 14 of the MAINSAIL Language Manual, intmods are searched for by default in the order:

1. A file name, if the intmod directive specifies a file name (or a syntactically invalid MODULE name).

2. All open intmod libraries, most recently opened first.

3. The default file name for the MODULE.

4. The name specified, treated as a file name.

5. A remembered file name, if opening a supporting intmod.

There are no restrictions on the way MODULEs are organized in intmod libraries. An intmod library might consist of all MODULEs related to a given program, or it might consist of several unrelated “utility” MODULEs. An intmod library may also contain intmods for several different targets (this is not true of objmod libraries, which contain only objmods for the same target).

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

An intmod library can be opened in the following ways:

• With the MAINEX OPENINTLIB subcommand. The subcommand may be specified interactively or in a MAINSAIL bootstrap.

• With the compiler's OPENINTLIB or ININTLIB subcommand.

• With the debugger's OI subcommand.

• By using an INTLIB device prefix.

• Implicitly by the compiler or debugger, when looking for supporting intmods, if a remembered intmod file name contains an INTLIB device prefix.

• Performing an operation on it with INTLIB.

18.1. How INTLIB Opens Library Files

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

18.3. INTLIB 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 18–1.

• sysAbbrev is a system name abbreviation, as returned by $systemNameAbbreviation. Since intmods for more than one system may be stored in an intmod library, it may be important to distinguish between them. For example, if an intmod for a MODULE FOO is stored in a library for both Windows NT and SPARC UNIX, the two intmods can be distinguished as foo-mpnt and foo-uspa. It is not necessary to specify -sysAbbrev when all MODULEs operated on are for the same target system; a single TARGET command to specify the default target system suffices in this case.

• 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 INTLIB 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

18.3.1. <eol>, QUIT

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

18.3.2. ADD dLibName{,sysAbbrev} modList

Add the MODULEs specified by modList to the intmod library dLibName. modList is a list of MODULE specifications, separated by blanks. Valid MODULE specifications for this command are given in Table 18–3. 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 dLibBame contains no hole large enough to accommodate a MODULE in modList, the library is compacted.

If sysAbbrev is specified, it is an operating system abbreviation (as given by $systemNameAbbreviation; e.g., uspa, mpnt). The specified system becomes the default target system for the purposes of the current command. The initial default target is the host system. The target for individual MODULEs may be overridden by specifying a dash followed by a system abbreviation for individual MODULEs as shown in Table 18–3.

An error message is issued if the specified target for an ADD does not match the target for which the intmod was actually compiled.

18.3.3. COPY sLibName{,sysAbbrev} dLibName{,sysAbbrev}{ 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 sysAbbrev is specified for either library, it is the default system abbreviation for the current command (if it is specified for both and the two targets differ, an error message is issued). If modList contains system specifications for individual MODULEs, they override the default. An error message is issued if a MODULE name is used without a system abbreviation and no MODULE exists for the default target system.

If sysAbbrev is specified for either library, but no modList is given, only MODULEs for the specified target are copied from sLibName to dLibName. If no sysAbbrev and no modList are given, then all MODULEs (for all systems) are copied from sLibName to dLibName.

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.

18.3.4. CREATE libName

Create an intmod library named libName. The library is initially empty.

18.3.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 an INTLIB command, e.g.:

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

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

18.3.6. DELETE sLibName{,sysAbbrev} modList

Delete the MODULEs specified in modList from the intmod library libName. modList is a list of MODULE names separated by blanks. If sysAbbrev is specified, the MODULEs in modList are deleted for the specified system; otherwise, they are deleted for the current default target. A system abbreviation in modList overrides the default target.

18.3.7. DIRECTORY libName{,sysAbbrev}{=fileName}{ modList}

List information about the MODULEs contained in the intmod library libName. libName may be the character * if the intmods reside in individual intmod files instead of in an intmod 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, the default intmod file name is formed. If fileName is specified (the given STRING is not a possible MODULE name), the given file name is used.

If modList is omitted, all MODULEs in the intmod library are listed if sysAbbrev is omitted; if sysAbbrev is present, only MODULEs for the specified target are listed.

The information listed includes the MODULE's directory name, the MODULE name (if it differs from the directory name), the MODULE's target system, the number of pages it occupies (where a page is considered by INTLIB to be 512 characters), the date and time at which it was compiled, the version for which it was compiled, and the options with which it was compiled. Example 18–4 is a sample session with MAINSAIL showing execution of the INTLIB directory command and the resulting listing.

The meanings of the abbreviations shown in the options column of the directory listing, separated by spaces, are shown in Table 18–5. For example, C D L indicates that the MODULE was compiled with checking 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.

The DIRECTORY command may be able to display the contents of intmod libraries for versions older than the current version; however, XIDAK does not specify how long the INTLIB DIRECTORY command will maintain compatibility with previous versions.

18.3.8. EXTRACT sLibName{,sysAbbrev}{ modList}

Extract (copy to individual intmod files) the specified MODULE(s) from the intmod library libName. sysAbbrev, if specified, is the default target system abbreviation for the command; otherwise, the current default target is used. modList is a list of MODULE specifications, separated by blanks. Valid MODULE specifications for this command are given in Table 18–6. Different types of MODULE specifications can be mixed within modList.

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

18.3.9. LOG

The informational messages written by INTLIB when operating on libraries are enabled.

18.3.10. MOVE sLibName{,sysAbbrev} dLibName{,sysAbbrev} modList

The arguments to MOVE have the same format and effect as the arguments to COPY, except that MODULEs copied from sLibName are also deleted from dLibName.

18.3.11. NOLOG

The informational messages written by INTLIB when operating on libraries are suppressed.

18.3.12. QDIRECTORY libName{,sysAbbrev}{=fileName}{ modList}

The arguments to QDIRECTORY have the same format and effect as the arguments to DIRECTORY, except that less information is given about each MODULE.

18.3.13. READ fileName

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

18.3.14. TARGET{ sysAbbrev}

TARGET specifies the default target system for subsequent commands. sysAbbrev is a system abbreviation, as given by $systemNameAbbreviation. If the target system is omitted, the default target is set to the host system. The default target is initially the host system.

18.3.15. UPDATE/NOUPDATE

Default: UPDATE

Operations modifying large libraries (i.e., adding or deleting intmods) take longer than operations on small libraries. After each INTLIB command, the updated directory list for every modified library is written to the corresponding library file, and all library files open by INTLIB 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 INTLIB through calls to $executeIntlibCommands. The UPDATE and NOUPDATE commands may be used to handle such situations.

The default is UPDATE. Once the NOUPDATE command is given, all library files 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 INTLIB's FINAL PROCEDURE, so all libraries are updated when MAINSAIL exits).

The commands:

NOUPDATE
COPY srcLib dstLib mod₁
COPY srcLib dstLib mod₂
...
COPY srcLib dstLib mod_n
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.

18.4. INTLIB as a Device Prefix

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

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

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

intlib(proj-xxx.ilb)>foo

The target system of an intmod file may be specified either by following the library name with a comma and the target system abbreviation or by following the MODULE name with a dash and the target system abbreviation; e.g.:

intlib(proj-xxx.ilb,upa)>foo

or:

intlib(proj-xxx.ilb)>foo-upa

If the target is not specified, the host system is assumed.

If the library is omitted in an INTLIB file specification, i.e., if the syntax:

"INTLIB" & $devModBrkStr & modName

is used, all open intmod libraries are searched for modName.

When an INTLIB file f is opened, f.name is modified to include the library name and target if these were not specified in the call to open.

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

18.5. INTLIB Program Interface

INTLIB can be controlled from a user program by calling the PROCEDURE $executeIntlibCommands, declared as shown in Figure 18–7.

cmds is a STRING that contains exactly what would be typed by a user giving commands to INTLIB. 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 INTLIB 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 "INTLIB:".