A library is a specially constructed file consisting of one or more programming routines. Generally, these routines provide services that you may need repeatedly or services that are related and so have been gathered for ease of use and storage. You use the routines in a library by joining the library file with your source program. Usually this occurs at link-time; but with assembly language programs, it can also occur at assembly-time.

The RT--11 operating system provides several library files; SYSMAC and SYSLIB for example. These libraries supply the monitor services, input and output routines, conversion routines, and other programming services that user programs may need. You can create other library files yourself. Thus you can construct libraries that contain routines specific to your programming needs or to the combined needs of those using your RT--11 system.

Use the on-line index utility, INDEX, and see the on-line help utility, HELP, for more information on topics described in this chapter. (Kinds of Library Files )

The two kinds of library files are macro libraries and object libraries. (Macro Libraries)

Macro libraries, such as SYSMAC.SML, are used by MACRO--11 source programs at assembly-time and consist entirely of macros. A macro is described in (int_macro_chap) as a recurring sequence of coding instructions, which, when defined in a .MACRO statement, can then be called and used anywhere in your program. A macro library is a collection of macro definitions gathered into a single file. To use the macros in a macro library, you name those macros you plan to use in a .MCALL statement. When the assembler encounters the .MCALL statement during processing, it searches the appropriate macro library (SYSMAC.SML is default) for the definitions. It takes the definitions from the library and inserts them in a macro symbol table where they are available for use during assembly. (Object Libraries)

Object libraries, such as SYSLIB, are used by assembled MACRO--11 source programs and/or by compiled FORTRAN source programs at link-time. These libraries consist of object modules that contain global routines; such routines have been defined with global entry points and then named as global symbols in the source program. During the link operation, the linker searches the object libraries to determine if they provide definitions for any undefined globals. If the linker finds definitions, it takes those object modules containing the definition from the library and includes them in the link.

The global symbol table lists each global in a given object library. You can print this list on the terminal or the printer and thus keep track of an object library's current contents. (Creating and Maintaining a Library File)

You create a library file by dcombining several macro routines or several object modules into a single larger file using the LIBRARY command.

To build a macro library, first use the editor to create an ASCII text file that contains all the macro definitions. Then, process this file by using the LIBRARY command in combination with its /MACRO option. To update a macro library (that is, to add or delete macro definitions), edit the ASCII text file and, then, reprocess the file with the LIBRARY command.

To build an object library, use the editor to create an ASCII text file. The file contains the routines and functions written as complete program segments in either the MACRO--11 assembly language or a FORTRAN programming language. Then process the file, producing an object module. Next, use the LIBRARY command in combination with its /CREATE option. Once the library file is created, update it (add and delete routines) by means of other options to the LIBRARY command.

In the following exercises, you create an object library that contains three input object modules. The routines in two of these modules can be used by both MACRO--11 and FORTRAN programs; the routine in the third module can be used by only FORTRAN programs.

To build the library file, first use the editor to create the three ASCII text files. Then convert the ASCII text files to object format. Finally, process the object files with the LIBRARY command. Once you create the library files, use LIBRARY command operations and options to add and delete modules and globals and to obtain a listing of the library file contents. (Creating Object Library Input Files)

The first step in building an object library is to prepare the source code of the routines and functions that you choose to include in the library. Use the editor to create the following three text files, calling them FIRST.MAC, SECOND.MAC, and THIRD.FOR, respectively. FORTRAN users should create all three files; MACRO--11 users (who do not use FORTRAN) should create only the first two files.

(FIRST.MAC\bold) .TITLE COMB .MCALL .PRINT ; I = LEN(A) .GLOBL LEN LEN: TST (R5)+ ;SKIP # OF ARGS MOV @R5,R0 ;GET STRING POINTER 1$: TSTB (R0)+ ;FIND END OF STRING BNE 1$ ;LOOP UNTIL NULL BYTE DEC R0 ;BACK UP SUB @R5,R0 ;CALC # OF CHARS IN STRING RETURN ; CALL PRINT(ISTRING) .GLOBL PRINT PRINT: MOV 2(R5),R0 ;ADDR OF ISTRNG .PRINT ;.PRINT RETURN ;AND RETURN .END

(SECOND.MAC\bold) .TITLE ITTOUR ; I=ITTOUR(ICHAR) ; I=0 CHARACTER HAS BEEN OUTPUT ; =1 RING BUFFER IS FULL .MCALL .TTOUTR .GLOBL ITTOUR ITTOUR: MOVB @2(R5),R0 ;GET CHARACTER .TTOUTR ;.TTOUTR BIC R0,R0 ;CLEAR ERROR FLAG ADC R0 RETURN ;RETURN .END

(THIRD.FOR\bold) C CALL PUTSTR(LUN,AREA,CC) SUBROUTINE PUTSTR(LUN,AREA,CC) LOGICAL*1 AREA(250),CC DO 10 I=1,250 IF(AREA(I).EQ.0) GO TO 20 10 CONTINUE 20 LEN=I-1 IF(CC.NE.0) GO TO 30 WRITE(LUN,99)(AREA(I),I=1,LEN) RETURN 30 WRITE(LUN,99)CC,(AREA(I),I=1,LEN) 99 FORMAT(250A1) END

The routines in these files represent the services generally provided in a library file.

FIRST.MAC contains two global routines, LEN and PRINT. The LEN routine returns the number of characters in a string. PRINT outputs an ASCII string terminated with a zero byte to the terminal (it is the FORTRAN equivalent of the system macro .PRINT, used in the demonstration program in (int_macro_chap). SECOND.MAC contains one global routine, ITTOUR, which transfers a character to the console terminal. THIRD.FOR also contains one global routine, PUTSTR. This routine can be used by only FORTRAN programs and writes a variable-length character string on a specified FORTRAN logical unit.

Once you create these text files, the next step is to convert them from ASCII format to object format. Assemble or compile the text files as appropriate, first assembling FIRST.MAC and obtaining an object module (a listing is not necessary). FORTRAN users who are not familiar with the assembly process can type the MACRO commands as shown. (.)(MACRO FIRST (RET))

The command creates an object module called FIRST.OBJ on the default data (DK) volume. If errors occur, the assembler prints a message on the terminal, indicating the number of errors encountered during assembly. No errors should occur.

In the same way, assemble SECOND.MAC. Again, no errors should occur. (.)(MACRO SECOND (RET))

If any errors occur during the assembly operations, you have typed the source files incorrectly. Find and correct the typing errors and reassemble.

If you are a FORTRAN IV or FORTRAN--77 user, continue by compiling THIRD.FOR. The following command calls the correct FORTRAN compiler because of the SET FORTRA F4 or SET FORTRA F77 command you issued in (int_fort_chap): (.)(FORTRAN THIRD (RET))

If any errors occur during the compile operation, you have typed the source file incorrectly. Find and correct the typing errors and recompile.

Once you have produced the object modules, you are ready to build the object library file. (Building the Object Library)

Use the LIBRARY command in combination with its /CREATE option to construct a library file. You must indicate in the command the name of the library file and the names of the input object modules. Call the library file LIBRA and specify as input the two object modules, FIRST and SECOND. The LIBRARY command assumes that the input modules have the .OBJ file type (unless you indicate otherwise) and automatically assigns .OBJ to the library file. (.)(LIBRARY/CREATE LIBRA FIRST,SECOND (RET))

Once the library creation operation is complete, obtain a listing of the library file's contents, using the LIBRARY command with its /LIST option. The printer is the assumed output device for the list file, although you may indicate a different output device by adding a 2-letter device mnemonic to the /LIST option that follows.

To print a listing: (.)(LIBRARY/LIST LIBRA (RET))

To display a listing: (.)(LIBRARY/LIST:TT: LIBRA (RET))

The listing produced shows the library file's current contents. This library has three entry points: LEN and PRINT in the first module and ITTOUR in the second module. RT-11 LIBRARIAN V05.03 TUE 25-OCT-88 10:38:31 DK:LIBRA.OBJ TUE 25-OCT-88 10:38:13 MODULE GLOBALS GLOBALS GLOBALS LEN PRINT ITTOUR (Updating the Object Library)

Once you have created an object library, you use various LIBRARY command operations to update and maintain the library by adding and deleting modules and globals.

If you created the THIRD.OBJ object module, you can add it to the library file by using the /INSERT option. If you did not create this module, read through this section anyway; the command steps apply to any object module you wish to insert. (.)(LIBRARY/INSERT LIBRA THIRD (RET))

This operation inserts the object module contained in the file THIRD.OBJ, including all its globals, into the library file LIBRA. Obtain a listing of the library contents, using the /LIST option, to verify that the new globals have been added. The listing should look like this: RT-11 LIBRARIAN V05.03 TUE 25-OCT-88 10:42:31 DK:LIBRA.OBJ TUE 25-OCT-88 10:42:07 MODULE GLOBALS GLOBALS GLOBALS LEN PRINT ITTOUR PUTSTR

This listing shows the complete library file containing the globals from all three modules.

You can remove individual globals by using the /REMOVE option. For example, to remove the global ITTOUR, type: (.)(LIBRARY/REMOVE LIBRA (RET)) (Global?)( ITTOUR(RET)) (Global?)((RET))

The library file's contents now look like this: RT-11 LIBRARIAN V05.03 TUE 25-OCT-88 10:44:06 DK:LIBRA.OBJ TUE 25-OCT-88 10:43:51 MODULE GLOBALS GLOBALS GLOBALS LEN PRINT PUTSTR

These are some of the library maintenance operations that you can perform by using the LIBRARY command. Other library operations are available and are explained in the (SUG_BOOK). (Summary of Commands for Maintaining Library Files)

The following commands are described and illustrated in this chapter. If the meaning of any command is not clear, review the example in this chapter that illustrates the command. (LIBRARY/MACRO) () (SIMPLE) Creates a macro library. (LIBRARY/CREATE) () (SIMPLE) Creates an object library. (LIBRARY/INSERT) () (SIMPLE) Inserts object modules into the object library. (LIBRARY/LIST[:filespec]) () (SIMPLE) Lists the current contents of an object library on the printer; [:filespec] is an optional output file and/or device. (LIBRARY/REMOVE) () (SIMPLE) Remove globals from the object library.