900 Series HP 3000 Computers HP Link Editor/XL Reference Manual ABCDE HP Part No. 32650-90030 Printed in U.S.A.
The information contained in this document is subject to change without notice. HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett-Packard shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance or use of this material.
Print History DRAFT 11/7/97 The following table lists the printings of this document, together with the respective release dates for each edition. The software code printed alongside the current edition date indicates the version level at the time the manual was issued. Many product releases do not require changes to the document. Therefore, do not expect a one-to-one correspondence between product releases and document editions.
Preface This manual describes the HP Link Editor/XL subsystem and how you use it with 900 Series HP 3000 computer systems. The manual assumes that you are an experienced programmer, but not necessarily familiar with \linkers" and \loaders". This manual contains the following chapters: Chapter 1 Gives an overview of HP Link Editor/XL - what it is, when to use it and how it works. This chapter also summarizes the di erences between Link Editor/XL and its MPE counterpart, the MPE V Segmenter.
Additional Documentation This manual does not discuss the MPE XL operating system in detail. Only those aspects relevant to HP Link Editor/XL are mentioned. Similarly, details about compiling a program using HP COBOL II, HP FORTRAN 77, HP Pascal, and HP C are only discussed to the extent that they a ect how you use HP Link Editor/XL. See the appropriate operating system or language manual for complete information about those subjects.
Conventions In a syntax statement, commands and keywords must be entered in exactly the order shown, though you can enter them in either uppercase or lowercase. For example: CASE SHOWJOB can be entered as any of the following: showjob ShowJob SHOWJOB It cannot, however, be entered as any of the following: shojwob italics Shojob SHOW_JOB In a syntax statement, a word in italics represents a parameter or argument that you must replace with an actual value.
lename[,TEMP] When several elements are stacked within brackets, you can select one or none of the elements. In the following example, you can select devicename or deviceclass or neither. The elements cannot be repeated.
[ ... ] In a syntax statement, horizontal ellipses enclosed in brackets indicate that you can repeatedly select the element(s) that appear within the immediately preceding pair of brackets or braces. In the example below, you can select itemname zero or more times. Each instance of itemname must be preceded by a comma: [, itemname] [...] In the example below, you only use the comma as a delimiter if itemname is repeated; no comma is used before the rst occurrence of itemname : [ itemname] [,...] | ...
base pre xes Bits ( bit:length ) The pre xes %, #, and $ specify the numerical base of the value that follows: %num speci es an octal number # num speci es a decimal number $ num speci es a hexadecimal number If no base is speci ed, decimal is assumed. When a parameter contains more than one piece of data within its bit eld, the di erent data elds are described in the format Bits ( bit:length ) bit is the rst bit in the eld and length is the number of consecutive bits in the eld.
Contents 1. Introduction to HP Link Editor/XL When To Use HP Link Editor/XL . . . . . If You're Familiar with MPE V Segmenter . . . How HP Link Editor/XL Works . . . . . . Creating Executable Program Files . . . . Using Relocatable Libraries . . . . . . . Using Executable Libraries . . . . . . . Where To Go from Here . . . . . . . . . . DRAFT 11/7/97 . . . . . . . . . . . . . . . . . . . . . 1-2 1-3 1-4 1-4 1-8 1-8 1-9 2. Getting Started with HP Link Editor/XL Linking One Relocatable Object File . .
Using Indirect Files . . . . . . . . . . . Re-executing HP Link Editor/XL Commands Checking the Execution Status of Commands Executing MPE XL Commands . . . . . . Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 3-13 3-14 3-15 3-16 4. Creating Executable Program Files The Executable Program File Commands . . . The Executable Program Commands Reference ALTPROG . . . . . . . . . . . . . . . LINK . . . . . . . . . . . . . . . . . . LISTOBJ . . . . . . . . . . . . . . . .
7. Advanced Topics The MPE XL Programming Environment Virtual Memory . . . . . . . . . . External Calls . . . . . . . . . . . Privilege Levels . . . . . . . . . . Long Branch Stubs for Procedure Calls Procedure Labels . . . . . . . . . . HP Link Editor/XL Environment Files Stack Unwinding . . . . . . . . . . Millicode . . . . . . . . . . . . . . Improving Performance with Locality Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figures 1-1. Creating an Executable Program File . . . . . . 1-2. Creating an Executable Program File from Three Relocatable Object Files . . . . . . . . . . 2-1. Linking One HP COBOL II Relocatable Object File 2-2. Linking Two HP FORTRAN 77 Relocatable Object Files . . . . . . . . . . . . . . . . . . . 2-3. Relinking Two HP FORTRAN 77 Relocatable Object Files . . . . . . . . . . . . . . . . . . . 2-4. Creating a Relocatable Library and Adding Modules to It . . . . . . . . . . . . . . . . . . . 2-5.
2-24. 2-25. 2-26. 3-1. 4-1. 5-1. 5-2. 5-3. 5-4. 5-5. 6-1. 6-2. 6-3. 6-4. 6-5. 7-1. DRAFT 11/7/97 The HP Pascal Source File, EX3BSRC . . . . . The HP Pascal Source File, EX3CSRC . . . . . The HP Pascal Source File, EX3DSRC . . . . . The Files Used by HP Link Editor/XL . . . . . Executable Program File Commands . . . . . . Files Used for Creating and Maintaining a Relocatable Library File . . . . . . . . . . The Structure of a Relocatable Library . . . . . Relocatable Library Commands . . . . . . . .
Tables 4-1. 4-2. 5-1. 6-1. Symbol Types and Scopes (LISTOBJ) . . . . Symbol Types and Scopes (LISTPROG) . . . Symbol Types and Scopes (LISTRL) . . . . . Symbol Types and Scopes (LISTXL) . . . . . . . . .
1 Introduction to HP Link Editor/XL HP Link Editor/XL is a software tool that prepares compiled programs for execution on HP 3000 Series 900 computers. HP Link Editor/XL also lets you create and maintain libraries containing subprograms that you frequently use. This chapter explains when to use HP Link Editor/XL and gives an overview of how it works. It also compares it to its MPE V counterpart, the MPE V Segmenter.
When To Use HP Link Editor/XL Most HP compilers (for example, HP COBOL II) let you compile, link, and execute a program in one step. Or you can compile and link in one step. In these cases, you do not execute HP Link Editor/XL directly to perform the linking function. It is executed automatically. There are occasions, however, when you may want to compile and link a program yourself in separate steps.
If You're Familiar with MPE V Segmenter . . . DRAFT 11/7/97 If you've used the MPE V Segmenter, the following list should quickly familiarize you with how it di ers from HP Link Editor/XL (for a complete discussion of the di erences between MPE V Segmenter and HP Link Editor/XL, see appendix F): HP Link Editor/XL processes relocatable object les and relocatable libraries.
How HP Link Editor/XL Works HP Link Editor/XL (the \link editor") processes object code produced by high-level language compilers, such as HP COBOL II. Object code is saved in relocatable object les . The link editor links relocatable object les for execution by assigning memory locations to them and any external routines that they use. In addition to creating executable program les, you can use HP Link Editor/XL to create and maintain relocatable and executable libraries.
Figure 1-1. Creating an Executable Program File When the link editor links separately compiled relocatable object les or relocatable modules from a relocatable library, it must be able to nd procedure and variable name references ( symbols ) used in the modules. Since compilers process only one compilation unit at a time, they cannot resolve references outside the compilation unit. The unresolved references are called external references .
HP Link Editor/XL begins by merging relocatable object modules so that the executable program contains all the code and data in the input les. Figure 1-2 shows how an executable program le is created from three relocatable object les. Figure 1-2.
If a relocatable library is searched during linking, only those modules that export unresolved symbols are included in the executable program le. When relocatable object modules are merged, many external references are resolved. References that are still unresolved are external calls and are resolved when the program is loaded for execution. (The loader subsystem of the MPE XL operating system resolves external calls. It searches executable libraries and the MPE XL System Library.
Using Relocatable Libraries A relocatable library (RL) is a le containing one or more relocatable object modules which can be incorporated into executable program les during linking. Use relocatable libraries for routines that you want to become integral parts of executable program les. When a relocatable object module is linked into a program, the program contains its own unique copy of the module.
Where To Go from Here Now that you have read this chapter, you should have a general idea of how HP Link Editor works and the les that it uses. Continue reading chapters 2 and 3. Chapter 2 gives short examples of common ways to use HP Link Editor/XL and chapter 3 gives details about the les that HP Link Editor/XL uses and how to enter commands. Use chapters 4, 5 and 6 as reference chapters. See chapter 7 for information about some of the more advanced ways to use HP Link Editor/XL.
2 Getting Started with HP Link Editor/XL This chapter presents simple examples of the basic ways to use HP Link Editor/XL. The link editor commands are not discussed in detail. Rather, the intent is to give you a quick overview of how to use them to accomplish some common tasks. Chapters 3 through 6 give additional information about the commands that appear in this chapter. The examples in this chapter show how to do the following: Link one relocatable object le. Link several relocatable object les.
Linking One Relocatable Object File Link a relocatable object le yourself, rather than have it linked automatically, when you want to use le names or execution-time defaults that vary from the defaults supplied by the compiler. (Execution-time defaults include type checking levels, capability-class attributes, stack size, and heap size).
Linking Several Relocatable Object Files When compiling large programs that consist of several separately compiled modules, you must execute HP Link Editor/XL directly. It is a good idea to split a large program into modules because each module can be modi ed and recompiled independently. You can use the link editor at any time to relink the modules, creating a new executable program le. Figure 2-2 shows the commands that compile and link two HP FORTRAN 77 source les, EX2ASRC and EX2BSRC.
Using a Relocatable Library Relocatable libraries enable you to share procedures (subprograms) with other subprograms while letting you modify and compile them independently. The next three sections explain the primary ways to use relocatable libraries. They show how to place the subroutines and functions contained in a source le into a relocatable library and how to use them once they are placed there.
Searching a Relocatable Library Figure 2-5 shows how to link the relocatable object le, EX2AOBJ, using the relocatable library, LIBRL, to resolve external references. (This library was created in gure 2-4.) The :LINK command produces the executable program le, EX2PROG. :LINK FROM=EX2AOBJ;RL=LIBRL;TO=EX2PROG Figure 2-5. Searching a Relocatable Library Updating a Relocatable Library Figure 2-6 shows how to replace a relocatable object module in a relocatable library.
Using an Executable Library Routines in executable libraries can be shared by many programs; each program uses the same physical copy of code. Though you name executable libraries using the link editor, these libraries are not searched until the executable program le is loaded for execution. (The loader searches the executable libraries, resolving external references, much like the link editor searches relocatable libraries.
Alternatively, when you add relocatable object modules to an executable library, you can merge several of them into one module. Figure 2-8 shows how to merge ve relocatable object les (LIB10BJ, LIB2OBJ, LIB3OBJ, LIB4OBJ, and LIB5OBJ) into one executable module in the library. (The name of the new executable module is the source le name of the rst relocatable object le added, LIB1SRC.
Updating an Executable Library Figure 2-10 shows how to replace an executable module in an executable library. The executable module, EX2BOBJ (created in gure 2-7), is replaced by a newly-compiled version. Once the HP FORTRAN 77 source le, EX2BSRC, is recompiled (line 1), the link editor XL command on the third line sets the default executable library to LIBXL. To update the existing executable module, the old version is purged and a new one added.
Using Both Relocatable and Executable Libraries within a Program Creating the Relocatable Library A complex program may use a combination of several types of libraries, and additionally, might also require certain calls to system intrinsic routines to complete its tasks. The next three sections show how to link a program that incorporates both a relocatable library and an executable library, as well as calls to speci c system intrinsics.
Linking with Libraries and Relocatable Object Files Figure 2-13 shows how to link object les with a relocatable library using the link editor LINK command while specifying a needed executable library with a parameter to the :RUN command. First, the :PASXL compile command is used to create a relocatable object named EX3AOBJ from the source le EX3ASRC. EX3ASRC represents the main program; see gure 2-23 in the \Sample Programs".
As an alternative to specifying the executable libraries needed on the :RUN command, it might be useful to specify them at the time of linking. This allows you to simply invoke the :RUN command with no knowledge of the executable libraries needed at run time. :LINKEDIT LinkEd> LINK FROM=EX3AOBJ,EX3BOBJ;RL=EX3LIBRL;XL="EX3LIBXL" LinkEd> EXIT :RUN $OLDPASS Figure 2-14.
Sample Programs This section lists the HP COBOL II, HP FORTRAN 77, and HP Pascal source les used in the examples in the previous sections of this chapter.
IDENTIFICATION DIVISION. PROGRAM-ID. EX1. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT IFILE SELECT PFILE DATA DIVISION. FILE SECTION. FD IFILE. 01 IREC. 05 NAME 05 SOC-SEC 05 HIRE-DATE. 10 MO 10 DA 10 YR 05 SALARY 05 FD PFILE. 01 PREC. 05 SOC-SEC 05 05 NAME 05 05 HIRE-DATE. 10 MO 10 10 DA 10 10 YR 05 01 HREC. 05 HSOC-SEC 05 HNAME 05 HHIRE-DATE ASSIGN "IFILE". ASSIGN "PFILE". PIC X(30). PIC X(9). PIC PIC PIC PIC PIC XX. XX. XX. S9(6). X(29). PIC PIC PIC PIC X(9). XX. X(30). XX.
WORKING-STORAGE SECTION. 01 LNCNT PIC S9(4) BINARY VALUE 60. 01 W-DATE. 05 WYR PIC XX. 05 PIC X(4). PROCEDURE DIVISION. P1. ACCEPT W-DATE FROM DATE. OPEN INPUT IFILE OUTPUT PFILE. PERFORM WITH TEST AFTER UNTIL SOC-SEC OF IREC = ALL "9" READ IFILE AT END MOVE ALL "9" TO SOC-SEC OF IREC NOT AT END IF WYR = YR OF IREC THEN ADD 1 TO LNCNT IF LNCNT > 50 PERFORM HEADINGS END-IF MOVE SPACES TO PREC MOVE CORR IREC TO PREC WRITE PREC AFTER ADVANCING 1 LINE END-IF END-READ END-PERFORM CLOSE IFILE PFILE STOP RUN.
C C C C C C C C This program prints an amortization table for a loan with regular payments on the first of each month. It calculates prepaid interest from the current date until the end of the current month, and begins the amortization at the beginning of the next month. Input to the program is the current date (in month, day, year form), the principal amount, annual interest rate, and the term of the loan in years.
C Print the amortization table SUBROUTINE PRTTAB(PRIN, RATE, TERM, PAYMNT) DOUBLE PRECISION PRIN, RATE, PAYMNT INTEGER TERM DOUBLE PRECISION ACCINT, PPRIN, PINT, RPRIN CHARACTER*3 DW, WKDAY COMMON MONTH, DAY, YEAR INTEGER MONTH, DAY, YEAR ACCINT = 0.
C C C C JULIAN returns the Julian date for the given month, day, and year. The Julian date calculated here is valid from Mar 1, 1900 to Feb 28, 2100. It is the astronomical date for noon on that day. INTEGER FUNCTION JULIAN(MONTH, DAY, YEAR) INTEGER MONTH, DAY, YEAR PARAMETER (J1900 = 2415020) INTEGER JAN1, MON1 INTEGER MTABLE(12) DATA MTABLE /0,31,59,90,120,151,181,212,243,273,304,334/ C Find Julian date for Jan 1 of given year. JAN1 = J1900 + INT(365.25D0 * (YEAR-1900) + 0.
GOTO 1 2 RETURN END C C WKDAY returns a 3-letter name of the day of the week given the month, day, and year. CHARACTER*3 FUNCTION WKDAY(MONTH, DAY, YEAR) INTEGER MONTH, DAY, YEAR, JDATE, DW INTEGER JULIAN CHARACTER*3 DAYTAB(7) DATA DAYTAB /'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'/ JDATE = JULIAN(MONTH, DAY, YEAR) DW = MOD(JDATE+1, 7) WKDAY = DAYTAB(DW+1) RETURN END C C ADDDAT adds the given number of months, days, and years to the date supplied in the first three arguments.
C C AMORT returns the periodic payment for an amortized loan given principal, periodic interest rate, and term. DOUBLE PRECISION FUNCTION AMORT(PRIN, RATE, TERM) DOUBLE PRECISION PRIN, RATE INTEGER TERM AMORT = PRIN * RATE / (1.0 - (1.0+RATE) ** (-TERM)) RETURN END Figure 2-17.
C C C C JULIAN returns the Julian date for the given month, day, and year. The Julian date calculated here is valid from Mar 1, 1900 to Feb 28, 2100. It is the astronomical date for noon on that day. INTEGER FUNCTION JULIAN(MONTH, DAY, YEAR) INTEGER MONTH, DAY, YEAR PARAMETER (J1900 = 2415020) INTEGER JAN1, MON1 INTEGER MTABLE(12) DATA MTABLE /0,31,59,90,120,151,181,212,243,273,304,334/ C Find Julian date for Jan 1 of given year. JAN1 = J1900 + INT(365.25D0 * (YEAR-1900) + 0.
C MDY converts a Julian date to month, day, year format. SUBROUTINE MDY(JDATE, MONTH, DAY, YEAR) INTEGER JDATE, MONTH, DAY, YEAR, YDATE PARAMETER (J1900 = 2415020) INTEGER MTABLE(12) DATA MTABLE /31,28,31,30,31,30,31,31,30,31,30,31/ YEAR = 1900 + INT((JDATE-J1900) / 365.25D0) DAY = JDATE - JULIAN(1, 1, YEAR) + 1 MTABLE(2) = 28 IF (MOD(YEAR,4) .EQ. 0) MTABLE(2) = 29 MONTH = 1 1 IF (DAY .LE. MTABLE(MONTH) .OR. MONTH .GE. 12) GOTO 2 DAY = DAY - MTABLE(MONTH) MONTH = MONTH + 1 GOTO 1 2 RETURN END Figure 2-19.
C C WKDAY returns a 3-letter name of the day of the week given the month, day, and year. CHARACTER*3 FUNCTION WKDAY(MONTH, DAY, YEAR) INTEGER MONTH, DAY, YEAR, JDATE, DW INTEGER JULIAN CHARACTER*3 DAYTAB(7) DATA DAYTAB /'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'/ JDATE = JULIAN(MONTH, DAY, YEAR) DW = MOD(JDATE+1, 7) WKDAY = DAYTAB(DW+1) RETURN END Figure 2-20.
C C ADDDAT adds the given number of months, days, and years to the date supplied in the first three arguments. SUBROUTINE ADDDAT(MONTH, DAY, YEAR, NMONS, NDAYS, NYRS) INTEGER MONTH, DAY, YEAR, NMONS, NDAYS, NYRS INTEGER JDATE, JULIAN YEAR = YEAR + NYRS MONTH = MONTH + NMONS IF (MONTH .GT. 12) THEN YEAR = YEAR + (MONTH-1)/12 MONTH = MOD(MONTH-1,12) + 1 END IF IF (NDAYS .GT. 0) THEN JDATE = JULIAN(MONTH, DAY, YEAR) + NDAYS CALL MDY(JDATE, MONTH, DAY, YEAR) END IF RETURN END Figure 2-21.
C C AMORT returns the periodic payment for an amortized loan given principal, periodic interest rate, and term. DOUBLE PRECISION FUNCTION AMORT(PRIN, RATE, TERM) DOUBLE PRECISION PRIN, RATE INTEGER TERM AMORT = PRIN * RATE / (1.0 - (1.0+RATE) ** (-TERM)) RETURN END Figure 2-22.
{This program queries the system using defined system intrinsics in order to print the device number, the user, group, and account name, and the current date and time.} program myprog (input, output); type pac1 = packed array [1..10] of char; pac2 = packed array [1..30] of char; var user, group, acct: pac1; date : pac2; dev : shortint; {"external" signifies these routines will be found in other modules.
$subprogram$ program sub1; {Here, who is specified as an intrinsic.} procedure who; intrinsic; {This procedure calls the system intrinsic who to return the device the current user is logged on to. who command defaults are used for the 1st 7 parameters, as documented in the MPE XL Intrinsics Reference Manual.} procedure p1(var dev: shortint); begin who(,,,,,,,dev); end; {The main program is defined elsewhere.} begin end. Figure 2-24.
$subprogram$ program sub2; type pac1 = packed array [1..10] of char; procedure who; intrinsic; {This procedure calls the system intrinsic who to return the name of the current user, group, and account. who command defaults are used for the 1st 3 parameters, as documented in the MPE XL Intrinsics Reference Manual.} procedure p2(var user, group, acct: pac1); begin who(,,,user, group, acct); end; {The main program is defined elsewhere.} begin end. Figure 2-25.
$subprogram$ program sub3; type pac2 = packed array [1..30] of char; {dateline is specified as an intrinsic} procedure dateline; intrinsic; {This procedure calls the system intrinsic dateline to return the current date and time. dateline is documented in the MPE XL System Intrinsics Manual.} procedure p3(var date: pac2); begin dateline(date); end; {The main program is defined elsewhere.} begin end. Figure 2-26.
3 Using HP Link Editor/XL Files and Commands This chapter discusses the les that HP Link Editor/XL uses when it links a program, with or without libraries, and when it builds and maintains relocatable and executable libraries. The chapter also explains how to start and end HP Link Editor/XL and the rules for entering commands.
The Files Used By HP Link Editor/XL Figure 3-1 shows the les that the link editor uses. The next seven sections in this chapter discuss them in detail. Figure 3-1.
The Relocatable Object File A relocatable object le is output from compilation. It can also be created by the link editor EXTRACTRL command. When it is produced by a compiler, it consists of one relocatable object module regardless of the number of procedures or subprograms the source le contains. When it is produced by the EXTRACTRL command, it can consist of many relocatable object modules; however, these modules cannot be accessed individually with the LINK command.
To create a relocatable library le, you must have save access to the group where the le will be located. To modify an existing relocatable library, you must have write access to the le. To list the contents of a library or to copy modules out of it, you must have read access to it.
The $STDLIST File HP Link Editor/XL writes all prompts, errors, and informational messages to the standard list le, $STDLIST. When running in an interactive session, your terminal is the device used for $STDLIST. When running a batch job, the output spool le is used. If you wish, you can change the standard assignment for $STDLIST. Enter a :RUN command with the STDLIST option to name the le or device to use. (Note that when you do this and run interactively, command prompts do not appear on the screen.
The Executable Program File Executable program les are created by the LINK command. They are in binary format - ready to be loaded into memory and executed by the MPE XL :RUN command. Executable program les have the lecode NMPRG (1030). You can use the LISTPROG command (see chapter 4) to list the symbol table of an executable program le. To use LINK to create an executable program le, you must have save access to the group where the le is located.
Starting HP Link Editor/XL There are three ways to start HP Link Editor/XL: Enter the :LINKEDIT command at the MPE XL prompt: :LINKEDIT HP Link Editor/XL displays its command line prompt, LinkEd>, and waits for you to enter a command. Each time you enter a command, it is executed and you are prompted to enter another. This continues until you end the link editor with the EXIT command (see the next section).
Ending HP Link Editor/XL Three events terminate HP Link Editor/XL: When you explicitly end HP Link Editor/XL, by entering the EXIT command: LinkEd> EXIT You can abbreviate the EXIT command as E, EX, or EXI. (The commands QUIT, Q and BYE also terminate HP Link Editor/XL.) When end-of- le in $STDINX is encountered. End-of- le can occur when $STDINX is redirected to a disc le or when an :EOD command is encountered in it. When an error occurs in a batch job.
Entering HP Link Editor/XL Commands Using Upper and Lower Case Characters The following sections discuss the rules for entering HP Link Editor/XL commands. (The link editor reads commands from the standard input le, $STDINX. For more information on $STDINX see \The $STDINX File" section in this chapter.) When entering HP Link Editor/XL commands, you can enter them in either upper case or lower case, or a mixture of the two. There is one instance when case is signi cant.
following command uses default values for the rst two parameters of the LINK command, but speci es a value (LIBRL) for the third: :LINK ,,LIBRL 3-10 Using HP Link Editor/XL Files and Commands DRAFT 11/7/97 02:46
Continuing Commands from One Line to Another If you need more than one line to enter a command, end all lines except the last with an ampersand (&). This example shows how to enter a LINK command on three lines: LinkEd> LINK FROM=SAMPOBJ1, SAMPOBJ2, SAMPOBJ3, SAMPOBJ4, SAMPOBJ5, & SAMPOBJ6, SAMPOBJ7; TO=SAMPPROG; RL=LIBRL1, LIBRL2; & XL=MYXL; MAP Do not use ampersands in indirect les. (See the next section for information about indirect les.
To use an indirect le in a command, precede its name by a caret (^).
Re-executing HP Link Editor/XL Commands Similar to the MPE XL Command Interpreter, HP Link Editor/XL keeps a list of the last 20 commands you entered. You can view this list by entering the LISTREDO command. Then, you can enter the DO or REDO command to execute a command from the list. You use DO and REDO the same way you do as an operating system command except you cannot use the EDIT= parameter. The following example shows how you can use the REDO command to correct a simple typing mistake.
Checking the Execution Status of Commands When you're running a batch job and an error occurs, HP Link Editor/XL sets the system Job Control Word (JCW) to FATAL (octal 100000, hexadecimal 8000, decimal 32768). This causes MPE XL to ush the remainder of the job. By entering an MPE XL :CONTINUE command in the job le, you can continue the job and then test the JCW. The link editor sets two other Job Control Words when it nishes.
Executing MPE XL Commands While you're using HP Link Editor/XL, you can enter a programmatically executable MPE XL operating system command. To do this, precede the MPE XL command with a colon (:). For example, to execute the LISTF command, type: LinkEd> :LISTF See the MPE XL Commands Reference Manual for a complete description of all the MPE XL commands.
Getting Help HP Link Editor/XL provides an online Help facility similar to that used by the MPE XL Command Interpreter and other MPE XL subsystems. Request Help to clarify the syntax of an HP Link Editor/XL command or to list an example of how to use it.
4 Creating Executable Program Files This chapter discusses executable program les and how HP Link Editor/XL creates and displays them. It also explains how to display symbols in a relocatable object le.
The link editor creates executable program les from relocatable object les and relocatable libraries as follows. First, it merges the speci ed relocatable object les and libraries into one module and resolves inter-module references. Then, it searches the speci ed relocatable libraries resolving external references to symbols unde ned after the merge operation.
The Executable Program File Figure 4-1 shows the link editor commands that are discussed in this chapter along with the les that they use. Commands Figure 4-1.
The Executable Program Commands Reference 4-4 The link editor commands that create and display executable program les and that display symbols in a relocatable object le are listed below. Each command is discussed in detail in the sections which follow in this chapter. ALTPROG Alters the user-de nable elds of a program le a ecting the behavior of the program at run time. LINK Creates an executable program le. LISTOBJ Displays symbols in a relocatable object le.
ALTPROG This command allows the user to manipulate those elds of a program le which dictate the behavior of the program at run time. It is especially useful in that programs may be adjusted without having to link them a second time. Most of the options and keywords available can be overridden by the :RUN command. ALTPROG If a keyword is speci ed but no argument is given, then the corresponding eld in the le speci ed will be reset to its default value. ALTPROG [PROG= le] [, le]... [;XL= xl le [, xl le]...
ALTPROG BA - Local Batch Access max stack size max heap size unsat name Default: If no capabilities are speci ed, the executable le's capability set will default to BA and IA. Sets the maximum stack size, in bytes, for the resulting executable program. The program uses the stack to store a procedure's local variables and for control purposes. You can override this value using the NMSTACK parameter of the :RUN command. Default: the system-con gured value.
ALTPROG block). Entry names must be primary or secondary entry types. priority level max priority level DRAFT 11/7/97 If entry name was not previously speci ed, or has more characters than the previous entry name speci ed, the link editor will attempt to allocate enough space for the new string. Since this entry name can be of arbitrary length, it is possible to get an error message from the link editor when not enough space is available.
This command creates an executable program le. It does this by merging the relocatable object modules from all the les in the FROM= parameter. (These les can be relocatable object les, relocatable library les, or a combination of both.) The link editor also searches the relocatable libraries speci ed by the RL= parameter and includes the modules in those libraries containing de nitions that resolve external references. LINK Syntax LINK [FROM= source le [, source [;TO= dest le] [;RL= rl le [, rl le]...
LINK rl le xl le cap list Names a relocatable library le that resolves external reference(s) contained in the source le or in another rl le . The le must have a lecode of NMRL. The link editor searches the relocatable libraries in the RL list according to the order in which you list them. Therefore, if a module from one library calls a routine in another library and that routine refers to a module in the rst library, you must name the rst library a second time to resolve this circular reference.
LINK max heap size unsat name parameter of the :RUN command. Default: the system-con gured value. Sets the maximum heap size, in bytes, for the resulting executable program. The program uses the heap for dynamic storage allocation. You can override this value using the NMHEAP parameter of the :RUN command. Default: the system-con gured value. Names the procedure which the loader uses to satisfy unresolved externals. This procedure must reside in an executable library that is speci ed at run time.
LINK check level priv level Determines the type checking error level that the link editor uses while binding external references to procedures and global variables. All relocatable object modules indicate a checking level for each reference and each de nition of a procedure or a global variable. When binding an external reference to a de nition, the link editor compares the type information at the lower of the two checking levels speci ed by the reference and the de nition.
LINK priority level max priority level 4-12 Speci es the execution priority that the program will have at run time. The priority level has to be either BS, CS, DS, ES, or a number between 100 and 255 inclusive. This value can be overridden by the PRI= keyword on the :RUN command. Speci es the maximum execution priority that the program can have at run time. The priority level has to be either BS, CS, DS, ES, or a number between 100 and 255 inclusive.
LINK entry name NODEBUG MAP SHOW Names the point within a program where execution begins. ENTRY= lets you override the primary program entry point. If the symbol that matches entry name is not found, an error occurs. Entry name is case sensitive. You can override this parameter using the ENTRYPOINT parameter of the :RUN command. Default: starts execution from the primary program entry point (corresponding to a program's main procedure or outer block).
This command displays (on LINKLIST) the symbols in a relocatable object le. LISTOBJ If you do not specify which symbols to display using the parameters listed below, the following types of symbols are displayed: Procedure and program entry points. Imported code symbols. HP COBOL II chunk symbols. Exported data symbols, except compiler-generated symbols beginning with $, S$, or C$. Certain compiler-generated static data symbols, beginning with M$, which appear in HP COBOL II listings.
LISTOBJ Example LinkEd> LISTOBJ EX1OBJ This command displays symbols in the relocatable object le, EX1OBJ. (The source program for EX1OBJ is EX1SRC and is shown in gure 2-11.) The rst part of the listing is a header that gives general information about the relocatable object module. MODULE NAME shows the name of the relocatable object module and VERSION gives its format version. LENGTH shows the number of bytes (in hexadecimal) in the relocatable object module.
LISTOBJ Understanding the Symbol Listing This section describes the elds that appear in the symbol listing produced by this command. Column Description Sym Name C H X P Sym Type Contains the name of the symbol. If the name exceeds 25 characters, it is truncated and an asterisk appears in the rst truncated position. Contains the type checking level of the symbol. See the PARMCHECK= check level parameter of the ADDXL and LINK commands for a de nition of the values that appear in this column.
LISTOBJ Lset Name DRAFT 11/7/97 Speci es the name of the locality set to which this symbol belongs. Only user-de ned locality sets are listed.
LISTOBJ Table 4-1. Symbol Types and Scopes (LISTOBJ) Sym Type 4-18 Sym Scope Description abs univ A symbol that de nes a non-relocatable symbol or value and is visible to other object modules. abs local A symbol that de nes a non-relocatable symbol or value and is invisible to other object modules. abs unsat A symbol that references a non-relocatable symbol. code local A local label generated by the compiler, a user label or a local label within a millicode routine.
LISTOBJ Table 4-1. Symbol Types and Scopes (LISTOBJ) (continued) Sym Type DRAFT 11/7/97 Sym Scope Description mod local An HP Pascal module name. null univ Internal symbol. null local Internal symbol. null unsat Internal symbol. plab local An export stub created for a procedure or function (declared in a relocatable object module) whose address has been taken. pri_p univ The main entry point into an outer block of a program le.
This command displays (on LINKLIST) the symbols in an executable program le. This command produces the same output as the MAP option of the LINK command. LISTPROG If you do not specify which symbols to display using the parameters listed below, the following types of symbols are displayed: Procedure and program entry points. Unresolved external symbols. Imported code symbols. HP COBOL II chunk symbols. Exported data symbols, except compiler-generated symbols beginning with $, S$, or C$.
LISTPROG LinkEd> LISTPROG EX1PROG Example This command displays symbols in the executable program le, EX1PROG. (The source program for EX1PROG is EX1SRC and is shown in gure 2-11.) The rst part is the header which gives general information about the executable program le. PROGRAM names the executable program le. XL LIST shows the names of executable libraries speci ed in the XL parameter of the LINK command.
LISTPROG Understanding the Symbol Listing This section describes the elds that appear in the symbol listing produced by this command. Column Description Sym Name C H X P Sym Type Contains the name of the symbol. If the name exceeds 25 characters, it is truncated and an asterisk appears in the rst truncated position. Contains the type checking level of the symbol. See the PARMCHECK= check level parameter of the ADDXL and LINK commands for a de nition of the values that appear in this column.
LISTPROG local symbols (values displayed in the lp+ format), Lset Name DRAFT 11/7/97 this column shows the address of the XRT entry for this import stub. For stub local symbols, this column contains the address of the stub (a promotion stub or an import stub). For all data univ symbols, this column contains the address of a literal (if not represented in dp+ format) or the o set from the dp (data pointer) register. For all other symbols, it shows the address of the symbol.
LISTPROG Table 4-2. Symbol Types and Scopes (LISTPROG) Sym Type 4-24 Sym Scope Description abs univ A symbol that de nes a non-relocatable symbol or value and is visible to other object modules. abs local A symbol that de nes a non-relocatable symbol or value and is invisible to other object modules. code local A local label generated by the compiler, a user label or a local label within a millicode routine.
5 Maintaining Relocatable Libraries This chapter describes how HP Link Editor/XL creates and maintains relocatable libraries. It begins by describing relocatable libraries and how they are used. The rest of the chapter discusses the link editor commands for manipulating relocatable libraries. Figure 5-1 shows the les that the link editor uses when creating and maintaining relocatable libraries. Figure 5-1.
Relocatable Libraries A relocatable library contains relocatable object modules and a Library Symbol Table. Figure 5-2 illustrates the structure of a relocatable library. Figure 5-2.
Relocatable libraries are useful for storing subprograms since subprograms contain common routines that are used frequently. As an example, if several programs use the same routine, you can place it in a relocatable library. Then, to incorporate the routine in each program, name the library when you link the program using LINK. The link editor merges the relocatable object module containing the routine into each program le.
The Relocatable Library Commands HP Link Editor/XL provides a full set of commands to manipulate relocatable object modules within relocatable libraries. All relocatable libraries start as compiled relocatable object code. Use the ADDRL command to place the relocatable object modules produced by a compiler into a relocatable library. You can extract selected modules from a relocatable library and put them into a new relocatable object le with the EXTRACTRL command.
The Relocatable Library Commands Reference DRAFT 11/7/97 The following HP Link Editor/XL commands manage relocatable libraries. Each command is discussed in detail in the sections which follow in this chapter. ADDRL Adds relocatable object modules from a relocatable object le to a relocatable library. BUILDRL Builds and initializes a le as a new relocatable library. This library becomes the current relocatable library for subsequent interactive commands.
This command takes relocatable object modules, which are compiled from one or more source les, and puts them into a relocatable library. To add a relocatable object module from another relocatable library, use the COPYRL command. ADDRL ADDRL FROM= source le [, source le]... [;TO= dest le] [;MERGE [;RL= rl le [, rl le]...]] [;SHOW] [;REPLACE] Syntax Parameters source le dest le MERGE rl le 5-6 Names the relocatable object le containing the module(s) to add to the relocatable library.
ADDRL SHOW REPLACE DRAFT 11/7/97 use a relocatable library to resolve external references. Displays (on $STDLIST) the name of each relocatable object module added to the relocatable library. All les speci ed in the FROM= and RL= parameters are displayed. Default: do not display the names of relocatable object modules.
ADDRL LinkEd> ADDRL FROM=ARC,LINE,TANGENT Examples This command adds each of the relocatable object modules within the relocatable object les ARC, LINE, and TANGENT as distinct relocatable object modules to the current relocatable library. When using ADDRL, you normally omit the MERGE parameter. By omitting MERGE, you create a separate relocatable object module in the relocatable library corresponding to each relocatable object module in the object le. Figure 5-4 illustrates this. Figure 5-4.
ADDRL LinkEd> ADDRL FROM=LINEDRAW;TO=BOXDRAW;MERGE;RL=ARC,LINE;SHOW This command merges the relocatable object modules in the relocatable object le LINEDRAW, with the modules from the relocatable libraries ARC and LINE that resolve external references, then adds a single relocatable object module containing this code to the relocatable library BOXDRAW. The link editor also displays the name of each relocatable object module it processes during the MERGE operation.
This command creates a new relocatable library le. The directory of the relocatable library le is initialized and symbol space is reserved. This command also makes the new library the current relocatable library for subsequent interactive commands. BUILDRL BUILDRL RL= rl le [;LIMIT= max modules] Syntax Parameters rl le max modules Examples Names the new relocatable library (it is created with the lecode NMRL). The name must conform to the conventions established for all MPE XL le names.
CLEANRL This command eliminates fragmentation that may exist in a relocatable library le. CLEANRL Although relocatable libraries can expand in size, expansion beyond a certain point fragments the Library Symbol Table (so access to that library is slower). The CLEANRL command rebuilds the library, while allocating su cient space in the library's internal tables for expansion.
This command copies relocatable object modules from one relocatable library to another. You can copy speci c modules by their entry point, module, and block data name (HP FORTRAN 77) or by their locality set name. COPYRL Syntax Parameters 5-12 COPYRL [ENTRY= entry name [ ,entry name]...] [;MODULE= module name [ ,module name]...] [;BLOCKDATA= blockdata name [, blockdata name]...] [;LSET= lset name [ ,lset name]...
COPYRL source le dest le DRAFT 11/7/97 Names the relocatable library containing the modules to copy. The le must have an NMRL lecode. Default: the current relocatable library established by the last BUILDRL or RL command. (If you use the default, you must enter the TO= dest le parameter.) Names the relocatable library where the modules are placed. When dest le is an existing le, it must have the lecode NMRL. Default: the current relocatable library established by the last BUILDRL or RL command.
COPYRL REPLACE Examples Speci es that when symbols in the module(s) being copied are duplicates of symbols in any module in the destination library, then the modules with duplicate symbols residing in the destination library are removed. The new module is added before any of the modules in the library are removed.
EXTRACTRL This command extracts selected relocatable object modules from a relocatable library and places them into a new relocatable object le. You can extract speci c modules by their entry point, module and block data name (HP FORTRAN 77) or by their locality set name. EXTRACTRL This command does not delete the extracted modules from the relocatable library. Syntax Parameters DRAFT 11/7/97 EXTRACTRL [ENTRY= entry name [ ,entry name]...] [;MODULE= module name [ ,module name]...
EXTRACTRL source le 5-16 see if locality sets are available). You can enter an indirect le for this parameter. Names the relocatable library containing the modules to extract. The le must have the lecode NMRL. Default: the current relocatable library established by the last BUILDRL or RL command.
EXTRACTRL object le Examples Names the relocatable object le to be created (it is created with the lecode NMOBJ). The name must conform to the conventions established for MPE XL le names. The le must not already exist in the speci ed group. If it does, an error message is printed. Default: the system le, $NEWPASS.
This command hides one or more procedure entry points contained in the relocatable object modules of a relocatable library. HIDERL HIDERL takes e ect when the relocatable object module containing the hidden entry points is added (using ADDXL) to an executable library. The entry points are hidden from the loader at run time. Thus, HIDERL lets you keep procedure entry points private within a module and avoid name con icts among procedures.
LISTRL This command displays (on LINKLIST) the symbols contained in relocatable object modules of a relocatable library. (You may need this information for the COPYRL, EXTRACTRL and PURGERL commands.) LISTRL If you do not specify which symbols to display using the parameters listed below, the following types of symbols are displayed: Procedure and program entry points. Imported code symbols. HP COBOL II chunk symbols. Exported data symbols, except compiler-generated symbols beginning with $, S$, or C$.
LISTRL Parameters rl le Names the relocatable library to list. The le must have an NMRL lecode. Default: the current relocatable library established by the last BUILDRL or RL command. The next four parameters (ENTRY, MODULE, BLOCKDATA, and LSET) identify speci c modules to list. You can use any one by itself, or you can use them in combination. If you omit these parameters, the entire relocatable library is listed. entry name Lists the module(s) that de ne (export) the symbolic entry name .
LISTRL Example LinkEd> LISTRL RL=LIBRL;CODE;ENTRYSYM This command displays symbols in the LIBRL relocatable library. It also displays all procedure and program entry points. (The library is the one that is created in gure 2-4.) The rst part of the listing is the relocatable library header. LIBRARY NAME gives the le name of the relocatable library and VERSION is its format version.
LISTRL MODULE NAME VERSION LENGTH : LIB3SRC : 85082112 : 000004B8 Sym Name ---wkday julian MODULE NAME VERSION LENGTH Sym Name ---amort FTN_DTOI 5-22 Sym Lset Scope Name ----- ---univ unsat C H X P Sym Type - - - - ---3 3 3 entry 3 code 3 code Sym Lset Scope Name ----- ---univ unsat unsat C H X P Sym Type - - - - ---3 3 3 entry 0 code Sym Lset Scope Name ----- ---univ unsat : LIB4SRC : 85082112 : 00000530 Sym Name ---adddat julian mdy MODULE NAME VERSION LENGTH C H X P Sym Type - - - - ---3 3 3
LISTRL Understanding the Symbol Listing This section describes the elds that appear in the symbol listing produced by this command. Column Description Sym Name C H X P Sym Type Contains the name of the symbol. If the name exceeds 25 characters, it is truncated and an asterisk appears in the rst truncated position. Contains the type checking level of the symbol. See the PARMCHECK= check level parameter of the ADDXL and LINK commands for a de nition of the values that appear in this column.
LISTRL Lset Name 5-24 Speci es the name of the locality set to which this symbol belongs. Only user-de ned locality sets are listed.
LISTRL Table 5-1. Symbol Types and Scopes (LISTRL) Sym Type DRAFT 11/7/97 Sym Scope Description abs univ A symbol that de nes a non-relocatable symbol or value and is visible to other object modules. abs local A symbol that de nes a non-relocatable symbol or value and is invisible to other object modules. abs unsat A symbol that references a non-relocatable symbol. code local A local label generated by the compiler, a user label or a local label within a millicode routine.
LISTRL Table 5-1. Symbol Types and Scopes (LISTRL) (continued) Sym Type 5-26 Sym Scope Description mod local An HP Pascal module name. null univ Internal symbol. null local Internal symbol. null unsat Internal symbol. plab local An export stub created for a procedure or function (declared in a relocatable object module) whose address has been taken. pri_p univ The main entry point into an outer block of a program le.
PURGERL This command deletes selected modules from a relocatable library. You can purge speci c modules by their entry point, module, and block data name (HP FORTRAN 77) or by their locality set name. PURGERL Syntax PURGERL 2 3 8 ,entry name . .. 3 ENTRY= entry name > 2 > < name ... ;MODULE= module name ,module 3 2 , blockdata name ... ;BLOCKDATA= blockdata name > > 2 3 : ;LSET= lset name ,lset name . . .
PURGERL relocatable library established by the last BUILDRL or RL command.
PURGERL Examples LinkEd> PURGERL LSET=CLIP;RL=WINDOWS This command deletes all relocatable object modules that belong to the CLIP locality set from the WINDOWS relocatable library. LinkEd> PURGERL MODULE=GRAPH This command deletes the relocatable object module named GRAPH from the current relocatable library.
This command reveals hidden symbols in the relocatable object modules of a relocatable library. (REVEALRL reverses the e ect of the HIDERL command.) REVEALRL This command takes e ect when the module containing the symbol is added to an executable library. The symbol can be used by the loader to resolve external references between executable modules. Thus, the e ect of REVEALRL is to reveal the symbol to the loader at run time.
RL This command makes an existing relocatable library the current (working) relocatable library. This relocatable library becomes the default library in subsequent command operations. RL You must have read and write access to the relocatable library. RL RL= rl Syntax Parameters Example rl le le Names an existing relocatable library. The le must have an NMRL lecode. LinkEd> RL RL=BOXDRAW This command makes BOXDRAW the current relocatable library.
This command displays (on $STDLIST) the name of the current (working) relocatable library. SHOWRL To change the current relocatable library, use the RL command. To create a relocatable library and make that library the current relocatable library, use the BUILDRL command. SHOWRL Syntax Example LinkEd> SHOWRL This command displays the name of the current relocatable library.
6 Maintaining Executable Libraries This chapter explains how to build and maintain executable libraries. The chapter begins by describing executable libraries and comparing them to relocatable libraries. The remainder of the chapter provides a detailed description of each of the executable library commands. Since the task of building and maintaining executable libraries resembles the task of building and maintaining relocatable libraries, much of this chapter parallels the information in chapter 5.
Executable Libraries An executable library contains executable modules and a Library Symbol Table. Figure 6-2 illustrates the structure of an executable library. Figure 6-2. The Structure of an Executable Library Executable libraries contain executable modules having the following characteristics: Executable modules are in a form that can be executed directly. Executable modules are shared - only one copy of the code need exist on the system.
The Executable Library Commands Several of the executable library commands resemble relocatable library commands. For example, the XL, LISTXL, and SHOWXL commands (corresponding to the RL, LISTRL, and SHOWRL commands) let you specify the current executable library or display information about an executable library.
The Executable Library Commands Reference 6-4 The remainder of this chapter discusses in detail each of the link editor commands that manage executable libraries. The executable library commands are: ADDXL Adds relocatable object modules from a relocatable object le or from a relocatable library to an executable library. BUILDXL Builds and initializes a new executable library. This library becomes the current executable library for subsequent interactive commands.
ADDXL This command adds relocatable object modules to an executable library from either a relocatable object le or a relocatable library. ADDXL Syntax Parameters ADDXL FROM= source le [ ,source le]... [;TO= dest le] [;MERGE [;RL= rl le [, rl le]...]] [;SHOW] [;PARMCHECK= check level] [;PRIVLEV= priv level] [;XLEAST= xleast level] [;MAP] [;REPLACE] [;ENTRY= entry name [ ,entry name]...] [;MODULE= module name [ ,module name]...] [;BLOCKDATA= blockdata name [, blockdata name]...
ADDXL rl le 6-6 explain MERGE in more detail. Default: do not merge relocatable object modules. Names a relocatable library that the link editor searches during a MERGE operation to resolve external references. The le must have an NMRL lecode. When you want to include several relocatable library les, you can name each library individually, or you can provide an indirect le name containing a list of le names. Precede the indirect le name with a caret symbol (^). Default: no relocatable library is used.
ADDXL SHOW check level priv level Displays (on $STDLIST) the name of each relocatable object module as it is merged into the executable library. Use this parameter to verify the order in which the link editor processes each module. Default: do not display relocatable object modules. Determines the type checking error level that the link editor uses while binding external references to procedures and global variables.
ADDXL 123- xleast level MAP 6-8 Unused Privileged level access User level access Default: the privilege levels set during compilation by compiler directives. Determines the privilege level at which calling procedures must be executing to use the executable module. Enter a value from zero to three (see the values for the priv level parameter, above). Default: use the existing privilege levels of the executable module.
ADDXL REPLACE Speci es that when symbols in the module being added are duplicates of symbols in any module in the destination library, then the modules with duplicate symbols residing in the library are removed. The new module is added before any of the modules in the library are removed. The next four parameters (ENTRY, MODULE, BLOCKDATA, and LSET) identify the modules to add from the relocatable library. (Do not use these parameters when the source le is a relocatable object le.
ADDXL Examples LinkEd> ADDXL FROM=FILEOPEN;TO=FILEREAD This command takes the relocatable object modules from the relocatable object le FILEOPEN and adds them to the FILEREAD executable library.
ADDXL When you omit the MERGE parameter, the link editor links each relocatable object module independently, then adds that module to the executable library. It doesn't attempt to resolve references between modules or library routines. Thus, each relocatable object module in the object le has its counterpart in the executable library. Figure 6-4 illustrates this process. Figure 6-4.
ADDXL LinkEd> ADDXL FROM=FILEI0,FILEREAD,FILEWRIT;MERGE;RL=FILEUTIL This command merges the relocatable object modules from the relocatable object les FILEIO, FILEREAD and FILEWRIT, as well as using those modules from the FILEUTIL relocatable library that resolve external references, and then places a single executable module (called FILEIO) into the current executable library.
BUILDXL This command builds and initializes a new executable library. The new library becomes the current (working) executable library for subsequent interactive commands. BUILDXL BUILDXL XL= xl le [;LIMIT= max modules] Syntax Parameters xl le max modules Examples Names the executable library to be created (it is created with lecode NMXL). The name must conform to the MPE XL le naming conventions. If the le already exists, the link editor ignores the command and prints an error message.
This command eliminates fragmentation which may exist in an executable library. CLEANXL Although executable libraries can expand in size, expansion beyond a certain point fragments the Library Symbol Table so access to that library becomes slower. The CLEANXL command takes a fragmented library and rebuilds that library, while allocating su cient space in the library's internal tables to allow for expansion.
COPYXL This command copies executable modules from one executable library to another. You can copy individual modules by their module, block data subprogram, procedure entry point, or locality set name. COPYXL Syntax Parameters DRAFT 11/7/97 COPYXL [ENTRY= entry name [ ,entry name]...] [;MODULE= module name [ ,module name]...] [;BLOCKDATA= blockdata name [, blockdata name]...] [;LSET= lset name [ ,lset name]...
COPYXL source le 6-16 Names the executable library that the link editor searches to nd the speci ed modules. The le must have an NMXL lecode. Default: the current executable library established by the last BUILDXL or XL command. (If you use the default, you must enter the TO= dest le parameter.
COPYXL dest le REPLACE Examples Names the executable library where the modules are placed. When dest le is an existing le, it must have the lecode NMXL. Default: the current executable library established by the last BUILDXL or XL command. (If you use the default, you must enter the FROM= source le parameter.
This command lists (on LINKLIST) symbols contained in selected executable modules of an executable library. (You may need this information for the COPYXL and PURGEXL commands.) LISTXL If you do not specify which symbols to display using the parameters listed below, the following types of symbols are displayed: Procedure and program entry points. Imported code symbols. HP COBOL II chunk symbols. Exported data symbols, except compiler-generated symbols beginning with $, S$, or C$.
LISTXL The next four parameters (ENTRY, MODULE, BLOCKDATA, and LSET) identify speci c modules to list. You can use any one by itself, or you can use them in combination. If you omit these parameters, the entire executable library is listed. entry name Lists the modules that de ne (export) the symbolic entry name . You can enter an indirect le for this parameter. Entry name is case sensitive.
LISTXL Example LinkEd> LISTXL XL=LIBXL;ALL;VALUE This command displays all symbols in the LIBXL executable library, including compiler-generated local symbols. Symbols are sorted and displayed by their value. The executable library is the one created in gure 2-7. The source program (EX2BSRC) is listed in gure 2-13. The rst part of the listing is the executable library header. LIBRARY NAME is the le name of the executable library. VERSION is the format version of the library.
LISTXL LIBRARY NAME VERSION MODULE COUNT MODULE LIMIT : : : : LIBXL 85082112 1 500 MODULE NAME ----------EX2BSRC MODULE NAME VERSION LENGTH Sym Name ---julian mdy wkday adddat amort $neg3 $neg5 $neg6 $pos $pos_for_17 $neg10 $neg $neg_for_17 $neg12 $neg15 $neg17 $u17 $7 $pos7 $1 $2 $neg7 $8 $neg7_shift $3 $4 $neg9 $neg14 t1 finish div_ovfl julian mdy wkday adddat DRAFT 11/7/97 START ----00129000 LENGTH -----00004078 : EX2BSRC : 85082112 : 00004078 C H X P Sym Type - - - - ---3 3 3 entry 3 3 3 entry 3
LISTXL amort $UNWIND_START $UNWIND_END $RECOVER_END $RECOVER_START L$2 L$3 L$6 $global$ julian.M$2 $dp$ mdy.M$3 wkday.
LISTXL Understanding the Symbol Listing This section describes the elds that appear in the symbol listing produced by this command. Column Description Sym Name C H X P Sym Type Contains the name of the symbol. If the name exceeds 25 characters, it is truncated and an asterisk appears in the rst truncated position. Contains the type checking level of the symbol. See the PARMCHECK= check level parameter of the ADDXL and LINK commands for a de nition of the values that appear in this column.
LISTXL Lset Name 6-24 this column shows the address of the XRT entry for this import stub. For stub local symbols, this column contains the address of the stub (a promotion stub or an import stub). For all data univ symbols, this column contains the address of a literal (if not represented in dp+ format) or the o set from the dp (data pointer) register. For all other symbols, it shows the address of the symbol. Speci es the name of the locality set to which this symbol belongs.
LISTXL Table 6-1. Symbol Types and Scopes (LISTXL) Sym Type DRAFT 11/7/97 Sym Scope Description abs univ A symbol that de nes a non-relocatable symbol or value and is visible to other object modules. abs local A symbol that de nes a non-relocatable symbol or value and is invisible to other object modules. code local A local label generated by the compiler, a user label or a local label within a millicode routine.
This command purges selected modules from an executable library. You can purge individual modules by their entry point, module, and block data name (HP FORTRAN 77) or by locality set name. PURGEXL Syntax PURGEXL 2 3 8 ,entry name . .. 3 ENTRY= entry name > 2 > < name ... ;MODULE= module name ,module 3 2 , blockdata name ... ;BLOCKDATA= blockdata name > > 2 3 : ;LSET= lset name ,lset name . . .
PURGEXL executable library established by the last BUILDXL or XL command. Examples LinkEd> PURGEXL LSET=FILEINTRINS;XL=FILEIO This command deletes every executable module that belongs to the FILEINTRINS locality set in the FILEIO executable library. LinkEd> PURGEXL MODULE=SEEK This command deletes the executable module named SEEK from the current executable library.
This command displays (on $STDLIST) the name of the current executable library established by the last XL or BUILDXL command. SHOWXL SHOWXL Syntax Example LinkEd> SHOWXL This command displays the name of the executable library established by the last BUILDXL or XL command.
XL This command selects an existing le as the current executable library. This library is used as the default library for subsequent command operations. XL XL XL= xl Syntax Parameters Example xl le le Names an existing executable library. The le must have an NMXL lecode. LinkEd> XL XL=FILEIO This command makes FILEIO the current executable library.
7 Advanced Topics In the MPE XL environment, you can program e ectively without an explicit knowledge of HP Link Editor/XL and how it works. However, when working on complex applications, you may need to take advantage of certain advanced features of the link editor. This requires that you explicitly run the link editor to override its default values. The topics discussed in this chapter include: A description of the MPE XL programming environment. A brief description of the millicode library, MILLI.LIB.
The MPE XL Programming Environment Virtual Memory The paragraphs which follow in this section cover the aspects of the MPE XL environment that a ect HP Link Editor/XL and how it links programs. A program running under MPE XL has at least two spaces , where a space is a xed-length block of virtual memory. One is a code space and the other is a data space. A virtual address is composed of a space identi er and a space o set, both of which are 32 bits long.
The link editor places all code and literals in the rst quadrant of the code space, and all data in the second quadrant of the data space. Thus, every executable module, whether in a executable program le or in an executable library, consists of one code space and one data space. When the program is loaded, a new code space is created for the code in the executable program le and for each executable library that is loaded to satisfy external references. Only one data space is created.
Privilege Levels The HP Precision Architecture provides four levels of privilege. Level 0 is the most privileged and allows complete access to all system resources. Level 3 is the least privileged. MPE XL establishes the following meanings for the privilege levels: 0 Restricted to the MPE/XL kernel. 1 Reserved for future use. 2 Privileged Mode. Programs with PM capability execute at this level. This privilege level provides access to most operating system features and security checks are streamlined.
Long Branch Stubs for Procedure Calls Compilers generate a single branch-and-link instruction for all procedure calls. The instruction has a limited addressing range 256K bytes in either direction from the call. If the call is external, the link editor places the import stub within this range. If the call is internal, the target may be out of range. In this case, the link editor builds a long branch stub within reach of the call.
HP Link Editor/XL Environment Files When you use the LINK and ADDXL commands, the link editor includes two les, NRT0.LIB.SYS and XL0.LIB.SYS, into the executable modules that are produced. These les de ne: The standard subspaces that control how the link editor arranges the code and data spaces. Since MPE XL compilers group the various parts of a relocatable object le into separate subspaces, the link editor can combine like subspaces together within each space.
Millicode DRAFT 11/7/97 HP Link Editor/XL automatically searches the standard system relocatable library, MILLI.LIB.SYS , when you execute the LINK and ADDXL commands. This library contains millicode routines that supplement common low-level operations in programs. It is searched after user relocatable libraries.
Improving Performance with Locality Sets You can improve the performance of large programs by arranging the code so that sets of procedures that call one another frequently are located in one contiguous area of virtual memory. You do this by using compiler directives to assign procedures to a locality set . The compilers place locality set information in relocatable object modules, and HP Link Editor/XL uses this information (during linking) to arrange the code.
A Messages This appendix lists messages that you may encounter while using HP Link Editor/XL. Self-explanatory messages and those which relate to syntax errors, such as missing or extraneous characters in commands, are not listed in this appendix. To assist you in nding the solution to a problem, several messages may be displayed. Look up each message in this appendix to get complete information about the action to take. Messages are preceded by unique reference numbers that indicate the error type.
User Errors (1000-1499) User errors result from entering incorrect commands or from using the commands incorrectly. User errors cause the command that you entered to fail. You must correct the cause of the error and re-enter the command. |||||||||||||||||||||||||||||| ||| 1001 MESSAGE PROGRAM ENTRY POINT "!" NOT FOUND CAUSE HP Link Editor/XL could not nd an entry point for the procedure. ACTION Check to make sure an outer block is present in the link or check that the NRT0.LIB.
DRAFT 11/7/97 MESSAGE DUPLICATE SYMBOL "!" IN "!" CAUSE HP Link Editor/XL found two relocatable object modules that de ne the same symbol. (The error message names the le that contains the second de nition.) ACTION Be sure that you have not linked the same module twice. Also ensure that two source les have not declared the same procedure name, outer block, global variable or BLOCK DATA subprogram.
|||||||||||||||||||||||||||||| ||| 1005 MESSAGE FOUND ! DUPLICATE SYMBOL(S) CAUSE This message summarizes the number of duplicate symbols originally detected and listed by error message 1004. ACTION Take the appropriate \action" for each duplicate symbol that was identi ed by error message 1004. |||||||||||||||||||||||||||||| ||| 1006 MESSAGE UNSATISFIED SYMBOLS: CAUSE A relocatable object module that is being linked has referenced an unde ned symbol.
of the PARMCHECK option of the LINK and ADDXL commands, type checking mismatches are either warnings or errors.) Not all of the type mismatches (warning numbers 1502-1507) may actually be errors; this message indicates the number that are errors. ACTION DRAFT 11/7/97 Check your source code and recompile, or request a lower type checking level using the PARMCHECK option.
|||||||||||||||||||||||||||||| ||| 1021 MESSAGE INDIRECT FILES NESTED TOO DEEPLY (MAXIMUM DEPTH IS 10) CAUSE An indirect le may contain a reference to another indirect le. You can use up to ten levels of indirect les. ACTION Check for an indirect le that references itself, or for a set of indirect les that contains a chain of circular references.
|||||||||||||||||||||||||||||| ||| 1025 DRAFT 11/7/97 MESSAGE EXPECTED FILECODE NMPRG OR NMXL FOR TO= FILE CAUSE You tried to LINK into an existing translated le. ACTION Use a di erent lename for the TO= keyword of the LINK command, or, purge the existing output le and try the LINK command again.
|||||||||||||||||||||||||||||| ||| 1042 MESSAGE INCOMPATIBLE NUMBER OF ARGUMENTS: ! (!, !) CAUSE The named procedure is referenced in one source le and de ned in another source le, but the type checking information indicates that the two declarations are incompatible. ACTION Check the source code and correct the incompatibility, or request a lower type checking level through the PARMCHECK parameter of the LINK or ADDXL command (so this error is reported as a warning).
the parameter number is listed on the following line. ACTION DRAFT 11/7/97 Check the source code and correct the incompatibility, or request a lower type checking level through the PARMCHECK parameter of the LINK or ADDXL command (so this error is reported as a warning).
|||||||||||||||||||||||||||||| ||| 1045 MESSAGE INCOMPATIBLE MODE: ! (!, !) CAUSE The named procedure or global variable is referenced in one source le and de ned in another source le, but the type checking information indicates that the two declarations are incompatible. If the symbol refers to a procedure and the incompatibility is with its parameters, the parameter number is listed on the following line.
the two declarations are incompatible. If the symbol refers to a procedure and the incompatibility is with its parameters, the parameter number is listed on the following line. ACTION DRAFT 11/7/97 Check the source code and correct the incompatibility, or request a lower type checking level through the PARMCHECK parameter of the LINK or ADDXL command (so this error is reported as a warning).
|||||||||||||||||||||||||||||| ||| 1100 MESSAGE "ENTRY=" NAME IS LONGER THAN 132 CHARACTERS CAUSE HP Link Editor/XL restricts the names for symbols in library symbol tables to 132 characters, but you entered an entry point name that exceeds this limit. ACTION Give the entry point a name that contains 132 characters or less.
ACTION DRAFT 11/7/97 Either open a default le and enter the same command, or re-enter the command using the FROM= parameter.
|||||||||||||||||||||||||||||| ||| 1104 MESSAGE NO CURRENT RELOCATABLE LIBRARY IS OPEN; YOU MUST SPECIFY AN RL FILE CAUSE Certain library maintenance commands let you omit the RL= le and use a currently active relocatable library instead. In this case, you omitted the RL= parameter, but no relocatable library le was selected as the currently active relocatable library.
|||||||||||||||||||||||||||||| ||| 1107 DRAFT 11/7/97 MESSAGE "RL=" FILES MAY NOT BE SPECIFIED WITHOUT ALSO SPECIFYING THE MERGE OPTION CAUSE The ADDRL and ADDXL commands allow you to specify relocatable libraries to resolve external references only when you request the MERGE option. ACTION Re-enter the command using the MERGE option.
|||||||||||||||||||||||||||||| ||| 1108 MESSAGE "UNSAT=" NAME IS LONGER THAN 132 CHARACTERS CAUSE HP Link Editor/XL restricts the names for entries in library symbol tables to 132 characters. You have given an UNSAT procedure a name that exceeds this limit. ACTION Give the UNSAT procedure a name that contains 132 characters or less. |||||||||||||||||||||||||||||| ||| 1109 MESSAGE ! IS NOT A LEGAL VALUE FOR PARMCHECK. IT MUST BE IN THE RANGE [0..
DRAFT 11/7/97 MESSAGE SYMBOL "!", ENCOUNTERED IN "!", WAS PREVIOUSLY DEFINED CAUSE When adding modules to a library, HP Link Editor/XL encountered a new de nition for a previously de ned symbol. ACTION Check that you have not added the same module twice. Also ensure that two source les have not declared the same procedure name or BLOCK DATA subprogram.
|||||||||||||||||||||||||||||| ||| 1112 MESSAGE ATTEMPT TO OPEN/CREATE FILE "!" FAILED CAUSE Certain HP Link Editor/XL commands attempt to open or create a le to serve as an input source or an output destination. In this case, HP Link Editor/XL either tried to open a le that doesn't exist, or tried to create a new le but found a le with that name already exists. ACTION Consult the section of the manual that describes the command you are using and determine whether or not the named le should exist.
DRAFT 11/7/97 MESSAGE "! IS NOT A LEGAL VALUE FOR XLEAST. IT MUST BE IN THE RANGE [0..3]" CAUSE You have used an illegal value for the XLEAST parameter of the LINK or ADDXL commands. ACTION Re-enter the command using a value between 0 and 3 for the XLEAST parameter.
|||||||||||||||||||||||||||||| ||| 1116 MESSAGE LINK FAILED CAUSE When HP Link Editor/XL encounters an error during the linking process, it prints this \summary" message as its last message before terminating. ACTION Refer to the \action" description for the previously listed error messages. Once you have resolved those problems, this message goes away. |||||||||||||||||||||||||||||| ||| 1117 MESSAGE LIMIT FOR A LIBRARY MUST BE IN THE RANGE [1..
DRAFT 11/7/97 CAUSE An option to the LINK command lets you specify a NMHEAP value. This number must be a positive integer. ACTION Re-enter the LINK command using a valid number for the NMHEAP parameter.
|||||||||||||||||||||||||||||| ||| 1120 MESSAGE ONE OF { ENTRY, LSET, MODULE } MUST BE SPECIFIED CAUSE The syntax for the PURGERL and PURGEXL commands requires that you specify which object modules you want to delete by either their entry point name, their module name, or their locality set name. You have omitted this parameter. ACTION Re-enter the PURGERL or PURGEXL command and specify which modules you want to delete.
|||||||||||||||||||||||||||||| ||| 1123 DRAFT 11/7/97 MESSAGE INDIRECT INPUT FILE "!" MUST BE AN ASCII FILE CAUSE A le that you used as an indirect le is a binary le rather than an ASCII le. ACTION Create your indirect les using a text editor and save them as ASCII les. If you have followed this procedure, check that you have spelled the name of the indirect le correctly.
|||||||||||||||||||||||||||||| ||| 1124 MESSAGE EXPECTED FILECODE ! FOR FILE "!" CAUSE The input or output le you used with the link editor command does not have the correct lecode. ACTION Be sure you have spelled the le's name correctly. If you have, check the description for the command you are using to be sure you are using the correct le as your input source or output destination.
quote mark (') or double quotes ("), but you can't mix the two. ACTION DRAFT 11/7/97 Re-enter the REDO/DO command, using the same quotation marks at both ends of the search string.
|||||||||||||||||||||||||||||| ||| 1128 MESSAGE REDO/DO NUMBER IS OUT OF RANGE OF REDO STACK CAUSE The DO and REDO commands accept either a search string or an integer parameter that identi es an entry on the redo stack. In this case, the number you supplied does not correspond to any of the values on the redo stack. ACTION Use the LISTREDO command to verify the command number you wish to repeat.
command is a valid HP Link Editor/XL command (or the word \help").
|||||||||||||||||||||||||||||| ||| 1132 MESSAGE ATTEMPT TO REDO FAILED CAUSE You have edited the response from a REDO command, but the resulting command is invalid. The link editor ignores the edited command. ACTION Refer to the description of the REDO command in the MPE XL Commands Reference Manual , then use the supported conventions for editing commands.
DRAFT 11/7/97 MESSAGE ATTEMPT TO WRITE TO FILE LINKLIST FAILED. FILE MAY BE FULL CAUSE When attempting to write to a le speci ed as the LINKLIST le in a le equation, the end of le was encountered. ACTION Exit HP Link Editor/XL and increase the size of the LINKLIST le.
|||||||||||||||||||||||||||||| ||| 1137 MESSAGE FILE "!" HAS A CORRUPT FILE END CAUSE The named le has the correct lecode but contains a corrupted eld in its header record. This usually indicates that the le has been corrupted, or that an invalid le has been created with a lecode which the HP Link Editor/XL recognizes. ACTION Verify that you have entered the correct le and that you have spelled the name correctly. If the le name is correct, replace or rebuild the le.
|||||||||||||||||||||||||||||| ||| 1140 DRAFT 11/7/97 MESSAGE FILE "!" HAS A CORRUPT IMPORT TABLE CAUSE The named le has the correct lecode but contains a corrupted eld in its header record. This usually indicates that the le has been corrupted, or that an invalid le has been created with a lecode which HP Link Editor/XL recognizes. ACTION Verify that you have entered the correct le and that you have spelled the name correctly. If the le name is correct, replace or rebuild the le.
|||||||||||||||||||||||||||||| ||| 1141 MESSAGE FILE "!" HAS A CORRUPT MODULE CAUSE The named le has the correct lecode but contains a corrupted eld in its module directory. This usually indicates that the le has been corrupted, or that an invalid le has been created with a lecode which HP Link Editor/XL recognizes. ACTION Verify that you have entered the correct le and that you have spelled the name correctly. If the le name is correct, replace or rebuild the le.
LKEDCAT.PUB.SYS. ACTION DRAFT 11/7/97 Check to be sure LKEDCAT.PUB.SYS exists. If not, contact your System Manager.
|||||||||||||||||||||||||||||| ||| 1145 MESSAGE LIBRARY "!" IS CORRUPT. USE EITHER A CLEANRL OR A CLEANXL COMMAND TO CLEAN THE LIBRARY CAUSE The library contains errors. ACTION If this is a relocatable library, use the CLEANRL command to clean it. If it is an executable library, use the CLEANXL command. |||||||||||||||||||||||||||||| ||| 1146 MESSAGE LIBRARY "!" IS CORRUPT CAUSE The library contains errors. ACTION Re-create the library.
|||||||||||||||||||||||||||||| ||| 1149 MESSAGE THE STRING TABLE IN FILE ! DOES NOT HAVE ENOUGH SPACE FOR THE STRING ! CAUSE While doing an ALTPROG command using the XL=, ENTRY=, or UNSAT= keywords, the le you tried to alter does not have enough room in its string table to hold the new string. ACTION Use the :RUN command to override the attributes stored in the program le. Or, link the program le again with the desired keyword speci ed on the LINK command.
|||||||||||||||||||||||||||||| ||| 1154 MESSAGE THE ! FIELD DOES NOT EXIST IN PROGRAM FILE !. THE FIELD WAS NOT CHANGED. CAUSE While doing an ALTPROG command you speci ed a keyword which changes a eld in the program le which does not exist in the program le you speci ed. This can only happen if you are trying to alter the PRI or MAXPRI elds in a program le built with an older link editor. ACTION If the elds are necessary for your application, you must link the application with this link editor.
Warning Messages (1500-1999) Warning messages signal potential error situations. HP Link Editor/XL produces an executable program le, but erroneous results may occur at run time. |||||||||||||||||||||||||||||| ||| 1502 MESSAGE INCOMPATIBLE NUMBER OF ARGUMENTS: ! (!, !) CAUSE The named procedure is referenced in one source le and de ned in another source le, but the type checking information indicates that the two declarations are incompatible.
ACTION A-38 Check the source code and correct the incompatibility, or ignore the warning.
|||||||||||||||||||||||||||||| ||| 1505 MESSAGE INCOMPATIBLE MODE: ! (!, !) CAUSE The named procedure or global variable is referenced in one source le and de ned in another source le, but the type checking information indicates that the two declarations are incompatible. If the symbol refers to a procedure and the incompatibility is with its parameters, the parameter number is listed on the following line. ACTION Check the source code and correct the incompatibility, or ignore the warning.
|||||||||||||||||||||||||||||| ||| 1509 A-40 MESSAGE COMMON BLOCK REQUESTS FOR "!" HAVE DIFFERENT LENGTHS CAUSE The named common block was de ned in one subprogram with a longer length than its initialization length. ACTION Since this is a warning, no action is required. HP Link Editor/XL allocates enough space for the common block with the larger size, but only the part declared in the BLOCK DATA subprogram is initialized.
|||||||||||||||||||||||||||||| ||| 1510 MESSAGE INVALID SYMBOL TYPE FOR PLABEL (!, !) CAUSE HP Link Editor/XL was asked to create a procedure label for the named symbol in the given source le, but the symbol is not a procedure name. ACTION This message usually indicates a compiler error. Record the steps that produced this error then report the problem to your System Manager.
System Errors (2000-2999) System errors are le and system resource errors. They cause the command that you entered to fail. Contact your System Manager to resolve the problem. |||||||||||||||||||||||||||||| ||| 2001 MESSAGE ATTEMPT TO SEEK IN "!" FAILED CAUSE This message usually indicates that an input le has been corrupted, or that an output le cannot be written because of system resource limitations. An MPE XL le system error message is usually printed to help clarify the problem.
|||||||||||||||||||||||||||||| ||| 2003 MESSAGE ATTEMPT TO READ FROM "!" FAILED CAUSE This message usually indicates that an input le has been corrupted. An MPE XL le system error message is usually printed to help clarify the problem. ACTION If the problem pertains to a relocatable object le, try recompiling the source le that produced that object module. If you have exceeded the le space limit for your group, either purge unwanted les or ask your System Manager to extend your le space limit.
ACTION A-44 Check with your System Manager to verify that the system has enough free disc space for swapping. If the program declares a very large array, try to revise the program so that the data is allocated dynamically rather than by a static array declaration; otherwise, try to reduce the size of the array.
|||||||||||||||||||||||||||||| ||| 2100 MESSAGE ATTEMPT TO CLOSE FILE "!" FAILED CAUSE A le system error has occurred while HP Link Editor/XL was trying to closed the indicated le. ACTION Using the accompanying le system error message, correct the problem and try the command again. If the problem persists, document the steps that produced the error and report the problem to your System Manager.
A-46 CAUSE A le system error occurred when HP Link Editor/XL tried to close the LINKLIST le. ACTION Using the accompanying le system error message, correct the problem and try the command again. If the problem persists, document the steps that produced the error and report the problem to your System Manager.
|||||||||||||||||||||||||||||| ||| 2105 MESSAGE ATTEMPT TO OPEN LKEDHELP.PUB.SYS FAILED CAUSE HP Link Editor/XL failed to nd the LKEDHELP.PUB.SYS le. ACTION Check that the LKEDHELP.PUB.SYS le is present on your system and that it has not been overwritten by some other le. Also ensure that you do not have a le equate for LKEDHELP.PUB.SYS. |||||||||||||||||||||||||||||| ||| 2106 MESSAGE OUT OF DISK SPACE CAUSE HP Link Editor/XL has run out of disk space.
Language Subsystem Errors (3000-3999) Language subsystem errors usually indicate errors in an input relocatable object le. The relocatable object le may have been corrupted after compilation, or there may be a compiler error. Save the corrupt version of the le in case you need it when reporting the error. Recreate the le and retry the command. If the error recurs, document the steps that produced it and contact your System Manager.
NRT0.LIB.SYS . ACTION DRAFT 11/7/97 Check that the NRT0.LIB.SYS le is present on your system and that it has not been overwritten with some other le. Also ensure that you do not have a le equate for NRT0.LIB.SYS . If the problem persists, document the steps that produced this error and report the problem to your System Manager.
|||||||||||||||||||||||||||||| ||| 3004 MESSAGE CAN'T FIND SUBSPACE FOR ! CAUSE HP Link Editor/XL automatically de nes three symbols for programs: etext, edata and end. These symbols are placed at the end of the code, initialized data, and uninitialized data subspaces, respectively. The $DATA$ and $BSS$ subspaces must be de ned in one of the input les, and are normally de ned in NRT0.LIB.SYS. ACTION Check that the NRT0.LIB.
DRAFT 11/7/97 CAUSE In order to generate an executable le that the loader can accept, the subspace records for the \code" space must precede those for the \data" space. Normally, the declarations contained in the NRT0.LIB.SYS le ensure that this happens. ACTION Check that the NRT0.LIB.SYS le is present on your system and that it has not been overwritten with some other le. Also ensure that you do not have a le equate for NRT0.LIB.SYS .
|||||||||||||||||||||||||||||| ||| 3008 MESSAGE TOO MANY LOADABLE SPACES CAUSE The loader rejects an executable le that contains more than two loadable spaces (a $TEXT$ space for code and a $PRIVATE$ space for data). If a program attempts to declare any other loadable space, HP Link Editor/XL issues this error message. ACTION This is a compiler error. Record the steps that produced this error and report it to your System Manager.
ACTION DRAFT 11/7/97 This is a compiler error. Record the steps that produced this error and report the problem to your System Manager.
|||||||||||||||||||||||||||||| ||| 3013 MESSAGE SUBSPACE LENGTH NOT EQUAL INIT LENGTH CAUSE A relocatable object module contains a subspace with a non-zero initialization length but a larger subspace length. ACTION This is a compiler error. Record the steps that produced this error and report the problem to your System Manager.
DRAFT 11/7/97 MESSAGE FIXUP HAS INVALID EXPRESSION SELECTOR CAUSE A relocatable object module contains a corrupt \ xup request" record. The one or two lines that follow this message gives the le and subspace that require the xup, and the symbol which is referenced by that location. ACTION This is a compiler error. Record the steps that produced this error and report the problem to your System Manager.
|||||||||||||||||||||||||||||| ||| 3017 MESSAGE FIXUP HAS INVALID FIELD SELECTOR CAUSE A relocatable object module contains a corrupt \ xup request" record. The one or two lines that follow this message gives the le and subspace that require the xup, and the symbol which is referenced by that location. ACTION This is a compiler error. Record the steps that produced this error and report the problem to your System Manager.
ACTION DRAFT 11/7/97 This is a compiler error. Record the steps that produced this error and report it to your System Manager.
|||||||||||||||||||||||||||||| ||| 3020 MESSAGE TARGET OF CONDITIONAL BRANCH IS OUT OF RANGE CAUSE A conditional branch instruction is attempting to reach a memory location that is not reachable through a single instruction. Normally, HP Link Editor/XL replaces single-instruction branches with a chained branch when necessary. The two lines that follow this message give the le and subspace o set of the branch instruction, and the symbol which is being referenced. ACTION This is a compiler error.
branches with a chained branch when necessary. The two lines that follow this message give the le and subspace o set of the branch instruction, and the symbol which is being referenced. ACTION DRAFT 11/7/97 This is a compiler error. Record the steps that produced this error and report it to your System Manager.
|||||||||||||||||||||||||||||| ||| 3024 MESSAGE FIXUP REFERS TO INVALID SYMBOL CAUSE A \ xup request" record indicates that a reference is being made to a symbol whose symbol type is not valid for the xup. ACTION This is typically a compiler error. Document the steps that produced this error and report the problem to your System Manager.
DRAFT 11/7/97 MESSAGE !: CORRUPT LIBRARY FILE (INCORRECT HEADER CHECKSUM) CAUSE The named le has the correct lecode but contains an incorrect \checksum" in its library header record. This usually indicates that the relocatable library le has been corrupted, or that a non-library le has been created with an NMRL lecode. ACTION Verify that you have speci ed a relocatable library le, that it is the correct one and that its name is spelled correctly.
|||||||||||||||||||||||||||||| ||| 3030 MESSAGE !: MISSING LIBRARY SYMBOL TABLE CAUSE The named relocatable library le has no symbol table. This usually indicates that the relocatable library le has been corrupted, or that a non-library le has been created with an NMRL lecode. ACTION Verify that you have speci ed a relocatable library le, that it is the correct one and that its name is spelled correctly. It the le and lecode are correct, replace or rebuild the le.
correct one and that its name is spelled correctly. It the le and lecode are correct, recreate the le.
|||||||||||||||||||||||||||||| ||| 3033 MESSAGE !: CORRUPT OBJECT FILE (INCORRECT HEADER CHECKSUM) CAUSE The named le has the correct lecode but contains an incorrect \checksum" in its header record. This usually indicates that the relocatable object le has been corrupted, or that a non-relocatable object le has been created with an NMOBJ lecode. ACTION Verify that you have speci ed a relocatable object le, that it is the correct one and that its name is spelled correctly.
ACTION This message indicates a compiler error. Record the steps that produced the error and report the problem to your System Manager. |||||||||||||||||||||||||||||| ||| 3036 DRAFT 11/7/97 MESSAGE FIXUP HAS A SELECTOR MISMATCH CAUSE An invalid xup request was found in a relocatable object le during the xup translation in the linker. ACTION This is a compiler error. Record the steps that produced the error and report the problem to your System Manager.
|||||||||||||||||||||||||||||| ||| 3037 MESSAGE FIXUP IS NOT A PROCEDURE CALL CAUSE A xup request record in a relocatable object le is invalid. ACTION This is a compiler error. Record the steps that produced the error and report the problem to your System Manager. |||||||||||||||||||||||||||||| ||| 3038 MESSAGE BAD UNWIND DESCRIPTOR CAUSE A corrupt unwind descriptor was found in a relocatable object le. ACTION This is a compiler error.
DRAFT 11/7/97 MESSAGE ILLEGAL COMBINATION OF RELOCATABLE SYMBOLS CAUSE A xup request record in a relocatable object le is invalid. ACTION This is a compiler error. Record the steps that produced the error and report the problem to your System Manager.
|||||||||||||||||||||||||||||| ||| 3042 MESSAGE EXPRESSION STACK UNDERFLOW CAUSE A xup request record in a relocatable object le is invalid. ACTION This is a compiler error. Record the steps that produced the error and report the problem to your System Manager. |||||||||||||||||||||||||||||| ||| 3043 MESSAGE INVALID FIXUP: "!" CAUSE A xup request record in a relocatable object le is invalid. ACTION This is a compiler error.
target of the loader xup is invalid. It is illegal to have initialized code pointers point into data. Make sure that the code does not contain code pointers which are initialized to point into data (it is possible to make this error when writing in assembly). ACTION DRAFT 11/7/97 If the code does not contain initialized code pointers which point into data, or the program consists of only high-level source language (eg. Pascal, COBOL, etc.), then this is a compiler error.
|||||||||||||||||||||||||||||| ||| 3047 MESSAGE INVALID ALIGNMENT OF DATA CAUSE The alignment speci ed in a xup request record in a relocatable object le is invalid. ACTION This is a compiler error. Record the steps that produced the error and report the problem to your System Manager. |||||||||||||||||||||||||||||| ||| 3048 MESSAGE DIVISION BY 0 IN AN EXPRESSION CAUSE A xup request in a relocatable le contains a DIV expression that has an invalid (0) divisor. ACTION This is a compiler error.
It the le and lecode are correct, replace or rebuild the le. |||||||||||||||||||||||||||||| ||| 3101 DRAFT 11/7/97 MESSAGE !: NOT A VALID OBJECT FILE (CORRUPT FILE ID) CAUSE The named le has the correct lecode but contains a corrupted eld in its header record. This usually indicates that the le has been corrupted, or that an invalid le has been created with a lecode which HP Link Editor/XL recognizes.
|||||||||||||||||||||||||||||| ||| 3102 MESSAGE !: NOT A VALID PROGRAM FILE (CORRUPT FILE ID) CAUSE The named le has the correct lecode but contains a corrupted eld in its header record. This usually indicates that the le has been corrupted, or that an invalid le has been created with a lecode which HP Link Editor/XL recognizes. ACTION Verify that you have entered the correct le and that its name is spelled correctly. It the le and lecode are correct, replace or rebuild the le.
Internal Errors (4000-4999) DRAFT 11/7/97 Internal errors are errors caused by the link editor subsystem. Internal errors cause link editor commands to abort. If you encounter any of these messages, document the steps that produced the error, then report the problem and error number to your Hewlett-Packard representative.
B Using HP Link Editor/XL with HP COBOL II/XL This appendix discusses the HP COBOL II/XL compiler conventions that relate speci cally to HP Link Editor/XL. The following items explain how you use the conventions to successfully create executable program les. (For details about compiler conventions, see the HP COBOL II Reference Manual , the HP COBOL II/XL Programmer's Guide or the HP COBOL II/XL Reference Manual Supplement .
Data is local (SP relative) if the PROGRAM-ID paragraph contains an INITIAL clause, or if the program contains the $CONTROL DYNAMIC directive.
Locality sets When an HP COBOL II relocatable object le contains multiple chunks of code, the locality set name is the name entered for the PROGRAM-ID. When the relocatable object le contains a single chunk, no locality set is used. Type checking The compiler generates the following type checking information for parameters in non-intrinsic CALL statements: 1. A type checking level of 3. 2. The parameter-passing method is by reference or value. 3.
C Using HP Link Editor/XL with HP FORTRAN 77/XL This appendix discusses the HP FORTRAN 77/XL compiler conventions that relate speci cally to HP Link Editor/XL. The following items explain how you use these conventions to successfully create executable program les. (For details about the compiler conventions shown, see the HP FORTRAN 77/XL Reference Manual .
unit(s) to be placed in a locality set (the directive remains in e ect until the next $LOCALITY directive). If you do not use the $LOCALITY directive, CODE is the default locality set name.
Type checking Two compiler directives specify the level of type checking that the link editor uses when resolving references between HP FORTRAN 77 subroutines and functions. They are $CHECK_FORMAL_PARM and $CHECK_ACTUAL_PARM and they are described in the next two paragraphs. $CHECK_FORMAL_PARM associates a check level with the formal declaration of the subroutine or function.
D Using HP Link Editor/XL with HP Pascal/XL This appendix discusses the HP Pascal/XL compiler conventions that relate speci cally to HP Link Editor/XL. The following items explain how you use these conventions to successfully create executable program les. (For details about the compiler conventions shown, see the HP Pascal Programmer's Guide .
The EXTERNAL option can be used with the GLOBAL option to compile procedures and functions separately. When EXTERNAL appears in a source le, the compiler generates information about global variables. This allows them to be coupled with identical variables in an outer block that are compiled with the GLOBAL option. The compiler generates object code only for procedures and functions; not for the statement part of the outer block.
Routines in an executable library cannot reference program globals. This includes INPUT and OUTPUT. The GLOBAL compiler option prepares information about all global variables declared in the outer block. It allows the variables to be coupled with identical variables that are compiled with the EXTERNAL option. The compiler generates object code for the outer block, as well as for all procedures and functions.
E Using HP Link Editor/XL with HP C/XL This appendix discusses the HP C/XL compiler conventions that relate speci cally to HP Link Editor/XL. The following items explain how you use these conventions to successfully create executable program les. (For details about the compiler conventions shown, see the HP C/XL Reference Manual Supplement .
If you do not enter the LOCALITY pragma, CODE is the default locality set name. Type checking The C compiler speci es 0 (no checking) as the type checking level for all C functions. There are no compiler directives that let you change the level of type checking that the link editor uses when resolving references between C functions.
F Differences Between HP Link Editor/XL and MPE V Segmenter This appendix summarizes the di erences between linking programs on MPE V systems using the MPE V Segmenter, and linking programs on MPE XL systems using the HP Link Editor/XL. If you are an experienced MPE V user, it should help you to understand the most important di erences between MPE V Segmenter and HP Link Editor/XL.
Differences in the Programming Environment Creating an e cient programming environment implies the e ective use of a computer's resources. Thus, utilities that make demands on a system's processing time and memory allocation must e ciently use the architecture of the parent computer. The main di erences between HP Link Editor/XL and the MPE V Segmenter relate to di erences between the underlying architecture of the Series 900 systems and the segmented architecture of MPE V systems.
USL Files and Relocatable Object Files Compilers on both MPE V and MPE XL systems read source les and generate object code for them, consisting of blocks of machine instructions. MPE V compilers create relocatable binary modules (RBMs), which are placed in USL les. MPE XL compilers create relocatable object modules, which are placed in relocatable object les or relocatable libraries.
Relocatable Libraries Relocatable libraries on both MPE V and MPE XL systems let you e ciently organize code units. They are similar in that they contain a collection of relocatable code units that are used during linking to resolve external references. The commands used to manipulate relocatable libraries under MPE V and MPE XL have the following similarities : The ADDRL command adds code units to a relocatable library. The BUILDRL command creates a relocatable library.
Segmented and Executable Libraries Executable libraries on MPE XL systems are similar to segmented libraries (SLs) on MPE V systems. Executable libraries contain executable code that is used by the loader at run time to resolve external references. Modules in executable and segmented libraries are shared by programs running concurrently.
G HP Link Editor/XL Command Summary This appendix serves as a quick reference to the syntax of the HP Link Editor/XL commands. The commands are listed alphabetically. ADDRL FROM= source le [, source le]... [;TO= dest le] [;MERGE [;RL= rl le [, rl le]...]] [;SHOW] [;REPLACE] ADDXL FROM= source le [ ,source le]... [;TO= dest le] [;MERGE [;RL= rl le [, rl le]...]] [;SHOW] [;PARMCHECK= check level] [;PRIVLEV= priv level] [;XLEAST= xleast level] [;MAP] [;REPLACE] [;ENTRY= entry name [ ,entry name]...
CLEANRL [RL= rl le] [;COMPACT] [;LIMIT= max modules] CLEANXL [XL= xl le] [;COMPACT] [;LIMIT= max modules] COPYRL [ENTRY= entry name [ ,entry name]...] [;MODULE= module name [ ,module name]...] [;LSET= lset name [ ,lset name]...] [;FROM= source le] [;TO= dest le] [;REPLACE] COPYXL [ENTRY= entry name [ ,entry name]...] [;MODULE= module name [ ,module name]...] [;BLOCKDATA= blockdata name [ ,blockdata name]...] [;LSET= lset name [ ,lset name]...
LINK [FROM= source le [, source le]...] [;TO= dest le] [;RL= rl le [, rl le]...] [;XL= xl le [, xl le]...
LISTRL [RL= rl le] [;ENTRY= entry name [ ,entry name]...] [;MODULE= module name [ ,module name]...] [;BLOCKDATA= blockdata name [ ,blockdata name]...] [;LSET= lset name [ ,lset name]...] [;ALL] [;CODE] [;DATA] [;ENTRYSYM] [;MILLICODE] LISTXL [XL= xl le] [;ENTRY= entry name [ ,entry name]...] [;MODULE= module name [ ,module name]...] [;BLOCKDATA= blockdata name [ ,blockdata name]...] [;LSET= lset name [ ,lset name]...] [;ALL] [;CODE] [;DATA] [;ENTRYSYM] [;MILLICODE] [;STUB] [;VALUE] PURGERL 2 3 8 name . . .
REVEALRL ENTRY= entry name ;ALL [;RL= rl RL RL= rl le] le SHOWRL SHOWXL XL XL= xl DRAFT 11/7/97 le HP Link Editor/XL Command Summary 02:46 G-5