LINK


LINK

     Creates an executable program file by merging the
relocatable object modules from all the files in its FROM=
parameter. Those files may correspond to object files, relocatable
files, or a combination of them. It also searches any relocatable
libraries mentioned in the RL= parameter list and merges any
modules within those libraries that resolve an external reference.

SYNTAX

     LINK [FROM=file[,file... ][;TO=destfile]
[;RL=rlfile[,rlfile...]...]
[;XL=xlfile[,xlfile...]...]
[;CAP=caplist]
[;NMSTACK=nmstacksize]
[;NMHEAP=nmheapsize]
[;UNSAT=unsatname]
[;PARMCHECK=checklevel]
[;PRIVLEV=priv_level]
[;PRI=priority_level]
[;MAXPRI=max_priority_level]
[;SHARE]
[;ENTRY=entryname]
[;NODEBUG]
[;MAP]
[;SHOW]

NOTE

This command follows the more flexible MPE/iX command line syntax.
Refer to the MPE/iX Commands Reference Manual (32650-90003)


PARAMETERS


file The name of an object file or a relocatable library
file. It may be any binary file of type NMOBJ or
NMRL. All relocatable objects in the FROM=
specified list are merged to form the program file
specified by destfile. If you omit this parameter,
LINK merges the object modules in the file
$OLDPASS.

destfile The name of the program file (type NMPRG) where
LINK places the resulting executable object module.
If destfile does not exist, LINK creates a new one
for you. If destfile does exist, it will be
destroyed and replaced by the object module created
by the current link operation.

rlfile The name of a relocatable library file (type NMRL)
that resolves an external reference made by an
object module in the FROM= file list. LINK searches
the relocatable libraries in the RL list in the
order in which you list them. If a module from one
library calls a routine in another library and then
that routine in turn refers to a module in the first
library, you may need to include the first library
twice so that LINK can resolve this "circular"
reference.

xlfile The name of an executable library (type NMXL). The
loader searches every executable library in the XL
list in an attempt to resolve external references
that remain in a program file.

caplist The list of capability attributes to be assigned to
the program file. The program will run only if the
group and account have matching capabilities. (The
system or account manager assigns these capabilities
to your group and account). Permissible values are

BA - Local Batch Access
IA - Interactive Access
PM - Privileged Mode
MR - Multiple RINs
DS - Extra Data Segments
PH - Process Handling

When you omit this parameter, LINK assigns BA and I
to the program file by default.

nmstacksize The maximum size, in bytes, to which the NM stack
may grow. This must be a decimal number. The
default is 0 (zero), which currently instructs MPE
XL to assign a system-defined constant as the value
of nmstacksize.

nmheapsize The maximum size, in bytes, to which the NM heap may
grow. This must be a decimal number. The default
is -1, which currently instructs the command to
assign a system-defined constant as the value of
nmheapsize.

unsatname The name of a procedure that the Loader substitutes
in place of any external reference that cannot be
resolved in a program file. If you omit this
parameter and any external references remain
unresolved, the Loader reports a load-time error.

checklevel An integer specifying the maximum level of checking
that LINK performs in binding external references to
procedures. All checking levels that are indicated
in external references and procedure definitions are
reduced (but never increased) to the specified
level. If you omit this parameter, LINK sets the
value to 3.

Permissible values for checklevel are

0 No parameter check.

1 Check of the symbol type descriptor.

2 Perform Level 1 checking, then check
the number of arguments that the
import procedure passed against the
minimum and maximum range that were
declared in the export procedure.

3 Perform Level 2 checking, then check
the type of each argument that was
passed.

If the checking level is restricted (reduced) and
reportable type errors are detected, they will be
reported not as errors but as warnings.

entryname The name (label) of the point within a program where
execution begins. When you omit this parameter, the
Loader begins execution from the primary program
entry point (which corresponds to a program's main
procedure or outer block). However, by including
the ENTRY= option, you may override this default
value and begin execution from the specified entry
point. If the Loader fails to find a symbol that
matches the entry point name, it reports a
load-time error.


priv_level Determines the privilege level used by the
executable program file. This parameter changes the
privilege level of all procedures in the symbol and
export tables (of the relocatable object file) that
were set during compilation. The default is the
privilege level set during compilation.

The values for priv_level are:

0 - System level access

1 - Unused

2 - Privileged level access

3 - User level access

priority_level Specifies the execution priority that the program
will have at runtime. 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.

max_priority_level Specifies the maximum execution priority that the
program can have at runtime. The priority_level has
to be either BS, CS, DS, ES, or a number between
100 and 255 inclusive. See the PRI= keyword of
the RUN command for more information.

SHARE Specifies that the data symbols should be
exportable and importable (shared) in the resulting
executable file.

NODEBUG Strips all symbolic debugging information from the
resulting program file. If you omit this parameter,
the file will contain debugging information if the
source file was compiled with this option.

MAP Prints a symbol map to the list file, LINKLIST.

SHOW Displays the name of each object module as it is
being merged into the program file. You may include
this option to verify the order in which LINK
processes each module.


OPERATION


This command creates an executable program file by merging
the relocatable object modules from all the files in its
FROM= parameter. Those files may correspond to object files,
relocatable files, or a combination of them. It also
searches any relocatable libraries mentioned in the RL=
parameter list and merges any modules within those libraries
that resolve an external reference.

The FROM=, RL=, and XL= parameters allow a series of file
names. You may name each file individually, or you may provide
an indirect file by preceding that file's name with the caret
symbol (^).

This command may be issued from a session, job, or program,
but not in BREAK. Pressing [Break] suspends the execution of
this command. Entering RESUME continues the execution.


EXAMPLE(S)

     LINK FROM=OBJCODE;TO=EXECPROG;NMSTACK=50000;MAP;SHOW

This command merges the object modules from the OBJCODE and
places them into the program EXECPROG. It assigns a program
stack of 50,000 bytes and requests LINK to build a map and
display the name of each object module as it is being linked.

LINK FROM=OBJCODE;TO=EXECPROG;RL=LineDraw,ArcDraw;CAP=BA

This command merges the object modules from the OBJCODE into
program file EXECPROG and searches the relocatable libraries
LineDraw and ArcDraw to resolve external references. The
resulting program file can be executed only in batch mode by
anyone with user mode access.

LINK FROM=A,MAIN; TO=MYPROG; SHARE; RL=LIBCSHR.LIB.SYS; XL=MYXL

This command links module A and module MAIN and shares data so
that data symbols in the program file MYPROG can be exported and
imported to and from the executable library MYXL.

The Link Editor uses three standard files, $STDINX, $STDIN,
and $STDLIST, which are briefly explained below. (For more
complete information, read the Link Editor/XL Reference Manual
(32650-90030).

$STDINX

The Link Editor reads its commands from $STDINX. For
interactive sessions this is the terminal keyboard. For a
batch job, it is the job stream file.

You can redirect $STDINX to another file. The file must be
an unnumbered ASCII file containing valid HP Link Editor/XL
commands. Enter a RUN commands with the STDIN option. For
example, to use the file SCRIPT as the standard input file,
enter the command

RUN LINKEDIT.PUB.SYS;STDIN=SCRIPT

If you start the Link Editor using the LINK command, or if
you execute it by passing a command in the INFO string of
the RUN command, $STDINX is not used. Instead, the single
command is executed and the Link Editor terminates.

The Link Editor writes all prompts, error messages and other
information to $STDLIST. During an interactive session,
this is your terminal. For a batch job, the output
spoolfile is used.

You can use another device for $STDLIST. Use the RUN
command with the STDLIST option. Note that when you do this
interactively, the command prompts do not appear on the
screen. For example, to send the Link Editor output to the printer

FILE LINKOUT;DEV=LP
RUN LINKEDIT.PUB.SYS;STDLIST=*LINKOUT

Link Editor listings and maps are send to the file LINKLIST,
not to $STDLIST. The listings and maps sent to LINKLIST are:

o The symbol map produced by the MAP option of the LINK command.

o The listing produced by the LISTPROG command.

o The listing produced by the LISTOBJ command.

o The listing produced by the LISTRL command.

o The listing produced by the MAP option of the ADDXL command.

o The listings produced by the LISTXL command.

LINKLIST output goes to $STDLIST, but you can redirect it
to another file or device by using the FILE command. To
send the listing of the relocatable library LIBRL to the printer

FILE LINKLIST;DEV=LP
LINKEDIT
LinkEd> LISTRL RL=LIBRL
LinkEd> EXIT

ADDITIONAL INFORMATION

Manuals:    HP Link Editor/iX Reference Manual (32650-90030)
HP Link Editor/iX Technical Addendum (32650-90476)