A text library contains library modules of source text. To include a library module from a text library in a program, use an INCLUDE statement.

Library modules within a text library are like ordinary text files, but they differ in the following ways:

• They contain a unique name, called the library module name, that is used to access them.
• Several library modules can be contained within the same library file.

Library modules in text libraries can contain any kind of text; this section only discusses their use when Compaq Fortran language source is used.

You should be aware of the difference between library modules that reside in text libraries and the Compaq Fortran post-compiled module files (.F90$MOD file type) that support use association (see Section 2.2.3).

Use the LIBRARY command (OpenVMS Librarian Utility) to create text libraries and insert, replace, delete, copy, or list library modules in text libraries. Text libraries have a default file type of TLB.

Figure 2-2 shows the creation of a text library and its use in compiling Compaq Fortran programs.

Figure 2-2 Creating and Using a Text Library

For More Information:

• On using the logical name FORT$LIBRARY to define a default library, see Section 2.2.4.
• On specifying the name of the library using the /LIBRARY qualifier on the FORTRAN command line, see Section 2.3.24.
• On specifying the directory location of the library using the /INCLUDE qualifier, see Section 2.3.22.
• On specifying the directory location of the library using the /ASSUME=SOURCE_INCLUDE qualifier, see Section 2.3.6.
• On using Fortran modules, see Section 2.2.3.
• On using INCLUDE or USE statements, see the Compaq Fortran Language Reference Manual.

Table 2-3 summarizes the commands that create libraries and provide maintenance functions. For a complete list of the qualifiers for the LIBRARY command and a description of other DIGITAL Command Language (DCL) commands listed in Table 2-3, see the Guide to Using OpenVMS Command Procedures or type HELP LIBRARY.

Table 2-3 Commands to Control Library Files

Function	Command Syntax1
Create a library.	LIBRARY/TEXT/CREATE library-name file-spec,...
Add one or more library modules to a library.	LIBRARY/TEXT/INSERT library-name file-spec,...
Replace one or more library modules in a library.	LIBRARY/TEXT/REPLACE library-name file-spec,... 2
Specify the names of library modules to be added to a library.	LIBRARY/TEXT/INSERT library-name file-spec/MODULE= module-name
Delete one or more library modules from a library.	LIBRARY/TEXT/DELETE=(module-name,...) library-name
Copy a library module from a library into another file.	LIBRARY/TEXT/EXTRACT=module-name/OUTPUT= file-spec library-name
List the library modules in a library.	LIBRARY/TEXT/LIST=file-spec library-name

When the LIBRARY command adds a library module to a library, by default it uses the file name of the input file as the name of the library module. In the example in Figure 2-2, the LIBRARY command adds the contents of the files APPLIC.SYM and DECLARE.FOR to the library and names the library modules APPLIC and DECLARE.

Alternatively, you can name a module in a library with the /MODULE qualifier. For example:

$ LIBRARY/TEXT/INSERT FORFILES DECLARE.FOR /MODULE=EXTERNAL_DECLARATIONS

The preceding command inserts the contents of the file DECLARE.FOR into the library FORFILES under the name EXTERNAL_DECLARATIONS. This library module can be included in a Compaq Fortran source file during compilation with the following statement:

INCLUDE 'FORFILES(EXTERNAL_DECLARATIONS)'

For More Information:

• On the INCLUDE statement, see the Compaq Fortran Language Reference Manual and Section 2.2.4.1.
• On controlling the directories and libraries searched with FORTRAN command qualifiers and the FORT$INCLUDE logical name, see Section 2.2.4.1.

The following sections discuss the compiler limits and error messages.

2.5.1 Compiler Limits

Table 2-4 lists the limits to the size and complexity of a single Compaq Fortran program unit and to individual statements contained in it.

The amount of data storage, the size of arrays, and the total size of executable programs are limited only by the amount of process virtual address space available, as determined by process quotas and system parameters.

Table 2-4 Compiler Limits

Language Element	Limit
Actual number of arguments per CALL or function reference	No limit
Arguments in a function reference in a specification expression	No limit
Array dimensions	7
Array elements per dimension	9,223,372,036,854,775,807 or process limit
Constants; character and Hollerith	2000 characters
Constants; characters read in list-directed I/O	2048 characters
Continuation lines	511
DO and block IF statement nesting (combined)	128
DO loop index variable	9,223,372,036,854,775,807 or process limit
Format group nesting	8
Fortran source line length	132 characters
INCLUDE file nesting	20 levels
Labels in computed or assigned GOTO list	500
Lexical tokens per statement	3000
Parentheses nesting in expressions	40
Structure nesting	20
Symbolic-name length	63 characters

For More Information:

On relevant process quotas and system parameters, see Section 1.1.

2.5.2 Compiler Diagnostic Messages and Error Conditions

The Compaq Fortran compiler identifies syntax errors and violations of language rules in the source program.

If the compiler locates any errors, it writes messages to your default output device; so, if you enter the FORTRAN command interactively, the messages are displayed on your terminal. If the FORTRAN command is executed in a batch job, the messages appear in the log file for the batch job.

A sample message from the compiler as it would appear on a terminal screen follows:

40 FORMAT (I3,) ................^ %F90-W-ERROR, An extra comma appears in the format list. at line number 13 in file DISK$:[USER]SAMP_MESS.FOR;4

This sample message consists of the following lines:

• The source file line that caused the message
• A pointer (...^ on a terminal or ...1 in a listing file) to the part of the source line causing the error
• The actual message (facility, severity, mnemonic, and text)
• The line number and name of source file

The message line has the following format:

%F90-s-ident, message-text

The facility, F90, follows the percent sign (%). The severity of the message (I for informational, W for warning, E for error, or F for fatal) replaces s. A mnemonic for that message replaces ident. The explanatory text of the message replaces message-text.

Diagnostic messages usually provide enough information for you to determine the cause of an error and correct it. If you compile using the /OPTIMIZE qualifier (the default) and have difficulty determining the cause of an error (possibly because of the optimizations), consider compiling using a lower optimization level or /NOOPTIMIZE.

If the compiler creates a listing file, it also writes the messages to the listing. The pointer (...1) and messages follow the statement that caused the error.

2.6 Compiler Output Listing Format

A compiler output listing produced by a FORTRAN command with the /LIST qualifier consists of the following sections:

• A source code section
• A machine code section---optional
• A storage map section (cross-reference)---optional
• A compilation summary

Section 2.6.1 through Section 2.6.4 describe the compiler listing sections in detail.

For More Information:

• On the /LIST qualifier, see Section 2.3.25)
• On the /MACHINE_CODE qualifier, see Section 2.3.26.
• On the /SHOW qualifier, see Section 2.3.40.

The source code section of a compiler output listing displays the source program as it appears in the input file, with the addition of sequential line numbers generated by the compiler. Example 2-1 shows a sample of a source code section of a free-form compiler output listing.

Example 2-1 Sample Listing of Source Code

RELAX2 Source Listing 10-MAY-1999 13:09:20 Compaq Fortran V7.x-xxxx Page 1 10-MAY-1999 08:20:00 $DISK:[USER]LIST_SAMPLE.F90;3 1 SUBROUTINE RELAX2(EPS) 2 INTEGER, PARAMETER :: M=40 3 INTEGER, PARAMETER :: N=60 4 5 COMMON X (M,N) 6 7 LOGICAL DONE 8 10 DONE = .TRUE. 9 10 DO J=1,N-1 11 DO I=1,M-1 12 XNEW = (X(I-1,J)+X(I+1,J)+X(I,J-1)+X(I,J+1))/4 13 IF (ABS(XNEW-X(I,J)) > EPS) DONE = .FALSE. 14 X(I,J) = XNEW 15 END DO 16 END DO 17 18 IF (.NOT. DONE) GO TO 10 19 RETURN 20 END SUBROUTINE

Compiler-generated line numbers appear in the left margin and are used with the %LINE prefix in debugger commands. These compiler-generated line numbers are displayed by compiler-generated messages and certain run-time error messages. (For more information on messages, see Appendix B.)

2.6.2 Machine Code Section

The machine code section of a compiler output listing provides a symbolic representation of the compiler-generated object code. The representation of the generated code and data is similar to that of a MACRO assembly listing.

The machine code section is optional. To receive a listing file with a machine code section, you must specify the following:

$ FORTRAN/LIST/MACHINE_CODE

Example 2-2 shows a sample of part of a machine code section of a compiler output listing.

Example 2-2 Sample Listing of Machine Code (Partial Listing)

RELAX2 Machine Code Listing 10-MAY-1999 Compaq Fortran V7.x-xxx Page 3 RELAX2$BLK 10-MAY-1999 $DISK:[USER]LIST_SAMPLE.F90;3 .PSECT $CODE$, OCTA, PIC, CON, REL, LCL, SHR, - EXE, NORD, NOWRT 0000 RELAX2:: ; 000001 80100000 0000 LDF F0, (R16) ; F0, (R16) ; 000013 A41B0010 0004 LDQ R0, 16(R27) ; R0, 16(R27) ; 000012 803B0018 0008 LDF F1, 24(R27) ; F1, 24(R27) 2FFE0000 000C UNOP 0010 .10: ; 000008 203FFFFF 0010 MOV -1, DONE ; -1, R1 47E77411 0014 MOV 59, var$0002 ; 59, R17 ; 000010 47E03412 0018 MOV 160, R18 2FFE0000 001C UNOP 0020 lab$0004: 40120413 0020 ADDQ R0, R18, R19 ; 000012 47E4F414 0024 MOV 39, var$0003 ; 39, R20 ; 000011 2273FF5C 0028 LDA R19, -164(R19) ; 000012 2FFE0000 002C UNOP 0030 lab$0008: ; 000011 A3F3FFA4 0030 LDL R31, -92(R19) ; 000012 81730000 0034 LDF F11, (R19) 81530008 0038 LDF F10, 8(R19) 8193FF64 003C LDF F12, -156(R19) 81B300A4 0040 LDF F13, 164(R19) 81D30004 0044 LDF F14, 4(R19) ; 000013 A3F30048 0048 LDL R31, 72(R19) ; 000012 556A100B 004C ADDF F11, F10, F11 47FF0416 0050 CLR R22 ; 000013 556C100B 0054 ADDF F11, F12, F11 ; 000012 A3F300E4 0058 LDL R31, 228(R19) 556D100B 005C ADDF F11, F13, F11 5561104B 0060 MULF F11, F1, XNEW ; F11, F1, F11 556E102E 0064 SUBF XNEW, F14, F14 ; F11, F14, F14 ; 000013 5FEE040E 0068 FABS F14, F14 55C014EE 006C CMPGLE F14, F0, F14 D5C00001 0070 FBNE F14, L$1 C3E00001 0074 BR L$3 0078 L$1: 47E10416 0078 MOV DONE, R22 ; R1, R22 007C L$3: . . . Routine Size: 432 bytes, Routine Base: $CODE$ + 0000 .PSECT $LINK$, OCTA, NOPIC, CON, REL, LCL,- NOSHR, NOEXE, RD, NOWRT 0000 ; Null-Frame invocation descriptor Entry point: RELAX2 Registers used: R0-R1, R16-R25, R27-R28, F0-F1, F10-F29 00000000 0010 .ADDRESS $BLANK 00003F80 0018 .LONG X^3F80 ; .F_FLOATING 0.2500000

The following list provides a detailed explanation of how generated code and data are represented in machine code listings.

• Machine instructions are represented by MACRO mnemonics and syntax. To enable you to identify the machine code that is generated from a particular line of source code, the compiler-generated line numbers that appear in the source code listing are also used in the machine code listing. These numbers appear in the right margin, preceding the machine code generated from individual lines of source code.
• The first line contains a .TITLE assembler directive, indicating the program unit from which the machine code was generated.
  • For a main program, the title is as declared in a PROGRAM statement. If you did not specify a PROGRAM statement, the main program is titled filename$MAIN, where filename is the name of the source file.
  • For a subprogram, the title is the name of the subroutine or function.
  • For a BLOCK DATA subprogram, the title is either the name declared in the BLOCK DATA statement or filename$DATA (by default).
• The lines following .TITLE provide information such as the contents of storage initialized for FORMAT statements, DATA statements, constants, and subprogram argument call lists.
• General registers (0 through 31) are represented by R0 through R31 and floating-point registers are represented by F0 through F31. The relative PC for each instruction or data item is listed at the left margin, in hexadecimal.
• Variables and arrays defined in the source program are shown as they were defined in the program. Offsets from variables and arrays are shown in decimal. (Optimization frequently places variables in registers, so some names may be missing.)
• Compaq Fortran source labels referenced in the source program are shown with a period prefix (.). For example, if the source program refers to label 300, the label appears in the machine code listing as .300. Labels that appear in the source program, but are not referenced or are deleted during compiler optimization, are ignored. They do not appear in the machine code listing unless you specified /NOOPTIMIZE.
• The compiler may generate labels for its own use. These labels appear as L$n or lab$000n, where the value of n is unique for each such label in a program unit.
• Integer constants are shown as signed integer values; real and complex constants are shown as unsigned hexadecimal values preceded by ^X.
• Addresses are represented by the program section name plus the hexadecimal offset within that program section. Changes from one program section to another are indicated by PSECT lines.

The storage map section of the compiler output listing is printed after each program unit, or library module. It is not generated when a fatal compilation error is encountered.

The storage map section summarizes information in the following categories:

• Program sections: The program section summary describes each program section (PSECT) generated by the compiler. The descriptions include:
  • PSECT number (used by most of the other summaries)
  • Name
  • Size in bytes
  • Attributes
  
  PSECT usage and attributes are described in Section 13.1.
• Total memory allocated: Following the program sections, the compiler prints the total memory allocated for all program sections compiled in the following form:

  Total Space Allocated nnn

• Entry points: The entry point summary lists all entry points and their addresses. If the program unit is a function, the declared data type of the entry point is also included.
• Variables: The variable summary lists all simple variables, with the data type and address of each. If the variable is removed as a result of optimization, a double asterisk (**) appears in place of the address.
• Records: The record summary lists all record variables and derived types. It shows the address, the structure that defines the fields of the individual records or types, and the total size of each record or type.
• Arrays: The array summary is similar to the variable summary. In addition to data type and address, the array summary gives the total size and dimensions of the array. If the array is an adjustable array or assumed-size array, its size is shown as a double asterisk (**), and each adjustable dimension bound is shown as a single asterisk (*).
• Record Arrays: The record array summary is similar to the record summary. The record array summary gives the dimensions of the record or derived-type array in addition to address, defining structure, and total size. If the record or derived-type array is an adjustable array or assumed-size array, its size is shown as a double asterisk (**), and each adjustable dimension bound is shown as a single asterisk (*).
• Labels: The label summary lists all user-defined statement labels. FORMAT statement labels are suffixed with an apostrophe ('). If the label address field contains a double asterisk (**), the label was not used or referred to by the compiled code.
• Functions and subroutines: The functions and subroutines summary lists all external routine references made by the source program. This summary does not include references to routines that are dummy arguments, because the actual function or subroutine name is supplied by the calling program.

A heading for an information category is printed in the listing only when entries are generated for that category.

Example 2-3 shows an example of a storage map section.

Example 2-3 Sample Storage Map Section

RELAX2 Source Listing 10-MAY-1999 09:31:21 Compaq Fortran V7.2-nnnn Page 2 10-MAY-1999 09:30:35 $DISK:[USER]LIST_SAMPLE.F90;3 PROGRAM SECTIONS Name Bytes Attributes 1 $CODE$ 432 PIC CON REL LCL SHR EXE NORD NOWRT OCTA 2 $LINK$ 28 NOPIC CON REL LCL NOSHR NOEXE RD NOWRT OCTA 3 $BLANK 9600 NOPIC OVR REL GBL NOSHR NOEXE RD WRT OCTA Total Space Allocated 10060 ENTRY POINTS Address Name 1-00000000 RELAX2 VARIABLES Address Type Name Address Type Name Address Type Name Address Type Name Address Type Name ** L*4 DONE ** R*4 EPS ** I*4 I ** I*4 J ** R*4 XNEW ARRAYS Address Type Name Bytes Dimensions 3-00000000 R*4 X 9600 (40, 60) LABELS Address Label 1-00000010 10

As shown in Example 2-3, a section size is specified as a number of bytes, expressed in decimal. A data address is specified as an offset from the start of a program section, expressed in hexadecimal.

2.6.4 Compilation Summary Section

The final entries on the compiler output listing are the compiler qualifiers and compiler statistics.

The body of the compilation summary contains information about OPTIONS statement qualifiers (if any), FORTRAN command line qualifiers, and compilation statistics.

"Compiler Statistics" shows the machine resources used by the compiler.

Example 2-4 shows a sample compilation summary.

Example 2-4 Sample Compilation Summary

COMMAND QUALIFIERS /ALIGNMENT=(COMMONS=(NONATURAL,PACKED,NOSTANDARD,NOMULTILANGUAGE),RECORDS=NATURAL) /ARCHITECTURE=GENERIC /ASSUME=(ACCURACY_SENSITIVE,ALTPARAM,NOBUFFERED_IO,NOBYTERECL,NODUMMY_ALIASES, NOFP_CONSTANT,NOINT_CONSTANT,NOMINUS0,NOUNDERSCORE,NOSOURCE_INCLUDE) /NOAUTOMATIC /NOBY_REF_CALL /CHECK=(NOBOUNDS,FORMAT,NOFP_EXCEPTIONS,OUTPUT_CONVERSION,NOOVERFLOW,POWER,NOUNDERFLOW) /CONVERT=NATIVE /DEBUG=(NOSYMBOLS,TRACEBACK) /NODEFINE /DOUBLE_SIZE=64 /NOD_LINES /ERROR_LIMIT=30 /NOEXTEND_SOURCE /F77 /FLOAT=G_FLOAT /GRANULARITY=QUADWORD /IEEE_MODE=FAST /INTEGER_SIZE=32 /MACHINE_CODE /MATH_LIBRARY=ACCURATE /NOMODULE /NAMES=UPPERCASE /OPTIMIZE=(INLINE=SPEED,LEVEL=4,NOLOOPS,NOPIPELINE,TUNE=GENERIC,UNROLL=0) /NOPAD_SOURCE /REAL_SIZE=32 /NORECURSIVE /REENTRANCY=NONE /ROUNDING_MODE=NEAREST /NOSEPARATE_COMPILATION /SEVERITY=(WARNING=WARNING) /SHOW=(NOINCLUDE,MAP) /SOURCE_FORM=FREE /STANDARD=NONE /NOSYNCHRONOUS_EXCEPTIONS /NOSYNTAX_ONLY /NOTIE /NOVERSION /VMS /WARNINGS=(ALIGNMENT,NOARGUMENT_CHECKING,NODECLARATIONS,GENERAL,GRANULARITY, NOTRUNCATED_SOURCE,UNCALLED,UNINITIALIZED,NOUNUSED,USAGE) /NODIAGNOSTICS /INCLUDE=FORT$INCLUDE: /LIST=FORT$DKB300:[PROJ]X.LIS;4 /OBJECT=FORT$DKB300:[PROJ]X.OBJ;5 /NOLIBRARY COMPILER: Compaq Fortran V7.x-xxxx COMPILATION STATISTICS CPU time: n.nn seconds Elapsed time: n.nn seconds Pagefaults: nnn I/O Count: nn