Updated: 11 December 1998

OpenVMS Linker Utility Manual

Operator commands perform 32-bit arithmetic operations on the low-order longwords of operands popped from the stack. The linker evaluates expressions in Post Fix Polish form. All arithmetic operations are performed in signed 32-bit two's complement integers. There is no provision for floating-point, string, or quadword computation. Attempts to divide by zero produce a zero result and a nonfatal warning message. Upon completion of the operation, the result is pushed back on the stack. The contents of the high-order 32 bits of the result are not predictable. Therefore the result should be popped from the stack with a longword store command (ETIR$C_STO_LW) rather than a quadword store command (ETIR$C_STO_QW).

The operator commands check the context saved by previous stack or operator commands. If one of the operands is defined by a shareable image, then the other operand must be a constant and the operation must be addition or subtraction. The context saved for the result is the context of the relocatable operand. In those cases where both operands are relocatable, neither is allowed to be external, so the saved context for the result simply indicates that it is relocatable and not external.

Table B-10 lists the operator commands and related values, together with a brief description of each command.

Table B-10 Operator Commands

Value	Command	Description
100	ETIR$C_OPR_NOP (No-Operation)	No operation results.
101	ETIR$C_OPR_ADD (Add)	Stack is popped twice. The two popped values are added, and the result is pushed back onto the stack. Stack pointer is decremented.
102	ETIR$C_OPR_SUB (Subtract)	Stack is popped twice. First value popped is subtracted from the second, and the result is pushed back onto the stack. Stack pointer is decremented.
103	ETIR$C_OPR_MUL (Multiply)	Stack is popped twice. The values are multiplied and the result is pushed back onto the stack. Stack pointer is decremented.
104	ETIR$C_OPR_DIV (Divide)	Stack is popped twice. The second value popped is divided by the first value popped, and the result is pushed back onto the stack. Stack pointer is decremented.
105	ETIR$C_OPR_AND (Logical AND)	Stack is popped twice. The result is the logical AND of the two operands. The result is pushed back onto the stack. Stack pointer is decremented.
106	ETIR$C_OPR_IOR (Logical Inclusive OR)	Stack is popped twice. The result is the inclusive OR of the two operands. The result is pushed back onto the stack. Stack pointer is decremented.
107	ETIR$C_OPR_EOR (Logical Exclusive OR)	Stack is popped twice. The result is the exclusive OR of the two operands. The result is pushed back onto the stack. Stack pointer is decremented.
108	ETIR$C_OPR_NEG (Negate)	Stack is popped once. The value is negated and pushed back onto the stack. Stack pointer is unchanged.
109	ETIR$C_OPR_COM (Complement)	Stack is popped once. The value is complemented and pushed back onto the stack. Stack pointer is unchanged.
110	ETIR$C_OPR_INSV (Insert Field)	Not supported in structure level 2.
111	ETIR$C_OPR_ASH (Arithmetic Shift)	Stack is popped twice. The second value popped specifies the shift count and direction to be applied to the first value popped. When the shift count is negative, the bits are shifted right with replication of the sign bit. When the shift count is positive, the bits are shifted left with zeros moved into low-order bits. The result is pushed back onto the stack. Stack pointer is decremented.
112	ETIR$C_OPR_USH (Unsigned Shift)	Not supported in structure level 2.
113	ETIR$C_OPR_ROT (Rotate)	The stack is popped twice. The second value popped specifies the rotation count and direction to be applied to first value popped. When the rotation count is positive, the bits in the first value popped are rotated left; when negative, right. The rotation count must have an absolute value of 0 to 32. The result is pushed back onto the stack. Stack pointer is decremented.
114	ETIR$C_OPR_SEL (Select)	Stack is popped two or three times. If the first value popped evaluates to TRUE (low bit set), another value is popped, leaving the top value on the resulting stack unchanged. If the first value popped evaluates to FALSE (low bit clear), the stack is popped two more times. The value popped by the second of the three pops is pushed back onto the stack, replacing the value removed by the third pop. In both cases, the stack pointer is decremented by two.
115	ETIR$C_OPR_REDEF (Redefine Symbol to Current Location)	Not supported in structure level 2.
116	ETIR$C_OPR_DFLIT (Define a Literal)	Not supported in structure level 2.
117--149		Reserved to Digital.

B.4.4 Control Commands

Control commands manipulate the linker's location counter. Table B-11 lists the control commands and related values, together with a brief description of each command.

Table B-11 Control Commands

Value	Command	Description
150	ETIR$C_CTL_SETRB (Set Relocation Base)	The stack is popped. The low-order longword of the value is placed in the image location counter. The stack pointer is decremented.
151	ETIR$C_CTL_AUGRB (Augment Relocation Base)	Argument is a signed longword. The value of this longword is added to the current image location counter. Stack pointer is unchanged.
152 1	ETIR$C_CTL_DFLOC (Define Location)	The stack is popped. The low-order longword of the popped value is used as an index. The value of the current DST location counter is then saved under this index.
153 1	ETIR$C_CTL_STLOC (Set Location)	The stack is popped. The low-order longword of the value is used as an index to locate a DST location counter saved by a previous DEFINE LOCATION command. The current DST location counter is updated with the saved DST location counter. The stack pointer is decremented.
154 1	ETIR$C_CTL_STKDL (Stack Defined Location)	The stack is popped. The low-order longword of the popped value is used as an index to locate a DST location counter saved by a previous DEFINE LOCATION command. The saved DST location counter is pushed back on the stack. The stack pointer is unchanged.
155--199		Reserved to Digital.

There are two types of conditional store commands. The first type declares conditional linkage, and assigns the linkage a unique index. The second type enables the linker to replace an instruction in the code stream. If an instruction is replaced, the linker is able to identify the conditional linkage that the original instruction relied on and eliminate the relocation that would otherwise have been generated for it. This is called linkage retirement. Linkage retirement leaves the storage allocated for the linkage intact but eliminates the relocations. Linkage retirement is not supported for structure level 2; the linker unconditionally generates relocations for all linkages.

B.4.5.1 Defining Conditional Linkage with Address-Related Commands

Table B-12 lists the commands for allocating conditional linkage with the arguments that follow the size field.

The ETIR$C_STC_LP_PSB command is used to pass signature information associated with the procedure to the linker. The linker propagates this information to the fix-up section with a special type of fix-up when the /NONATIVE_ONLY switch is specified. The signature information is used by the image activator to build jackets at activation time if the routine resides in a translated image. The signature is opaque to the linker. For more information about the format of OpenVMS procedure signatures, see the OpenVMS Calling Standard.

Table B-12 Summary of Store Conditional Commands for Linkage

Value	Command	Arguments
200	ETIR$C_STC_LP (Store Conditional Linkage Pair)	Not supported in structure level 2
201	ETIR$C_STC_LP_PSB (Store Conditional Linkage Pair Plus Signature)	Linkage Index (longword) Procedure Name (counted string) Signature Length (byte, may be 0) Signature (only if length is positive)
202	ETIR$C_STC_GBL (Store Conditional Global)	Linkage Index (longword) Global Name (counted string)
203	ETIR$C_STC_GCA (Store Conditional Code Address)	Linkage Index (longword) Procedure Name (counted string)
204	ETIR$C_STC_PS (Store Conditional Psect Plus Offset)	Linkage Index (longword) Psect index (longword) Offset (quadword)

The linkage index argument common to all of these commands is a positive integer value that must be unique to the module. Each index identifies a quadword of linkage. The commands used to declare a conditional linkage pair (ETIR$C_STC_LP and ETIR$C_STC_LP_PSB) reserve two index values. For example, if the index value 3 is declared, the index value 4 is implicitly declared. The linkage index is used by subsequent instruction replacement commands to identify the linkage on which the original instruction was dependent.

Linkage that is declared with a conditional linkage command and a nonzero linkage index can be used only by instructions that are identified by one of the instruction-related conditional store commands listed in Section B.4.5.2. Linkage that is declared with a conditional linkage command and a zero linkage index is not conditional. Improper use of conditional linkage cannot be detected by the linker and will result in incorrect program execution.

The linker assumes that its image location pointer points to the linkage being declared when the conditional store command is processed. If the linkage is needed, the linker will fill it with different values depending on the command as indicated in Tables B-13 and B-14. (Note that for structure level 2, the linker always fills in and relocates linkages.) The term symbol vector offset designates an offset into the symbol vector of the image that defined the symbol. The type of relocation or fix-up applied to the value in the linkage pair is specified in parentheses.

Table B-13 Contents of Linkage When Symbol Is Local to the Image

Command	First Quadword	Second Quadword
ETIR$C_STC_LP	Not supported in structure level 2
ETIR$C_STC_LP_PSB	Image offset of procedure entry (Quadword relocation)	Image offset of procedure descriptor (Quadword relocation)
ETIR$C_STC_GBL	Image offset of global data (Quadword relocation)	Not applicable
ETIR$C_STC_GCA	Image offset of procedure entry (Quadword relocation)	Not applicable
ETIR$C_STC_PS	Image offset of (psect + offset) (Quadword relocation)	Not applicable

Table B-14 Contents of Linkage When Symbol Is External to the Image

Command	First Quadword	Second Quadword
ETIR$C_STC_LP	Not supported in structure level 2
ETIR$C_STC_LP_PSB	Symbol vector offset (Linkage pair with signature fix-up)	Zero
ETIR$C_STC_GBL 1	Symbol vector offset (Quadword .ADDRESS fix-up)	Not applicable
ETIR$C_STC_GCA 1	Symbol vector offset (Code address fix-up)	Not applicable
ETIR$C_STC_PS 1 (Only if psect is OVR,REL,GBL)	Symbol vector offset (Quadword .ADDRESS fix-up)	Not applicable

B.4.5.2 Optimizing Instructions with Instruction-Related Commands

Figure B-11 shows the offsets used by the linker to test for replacement and the replacement instructions that are used. The following commands might be used to replace a sequence of instructions used to call procedure B from inside procedure A:

• ETIR$C_STC_NOP
• ETIR$C_STC_LDA
• ETIR$C_STC_BSR

The ETIR$C_STC_NOP passes the addresses used to calculate the offset D2. If D2 can be expressed as a signed 21-bit integer, the linker replaces the first LDQ instruction with the instruction specified by the command. (For example, the compiler might specify BIS R31,R31,R31, an instruction that does nothing and uses very few CPU cycles). The replacement of the first LDQ instruction anticipates the replacement of the JSR instruction and eliminates a memory reference, that is, the reference to the linkage pair that contains the address of the procedure entry for B. If D2 is too large to be expressed as a signed 21-bit integer, the linker does not do the replacement. The linker cannot delete the storage that contained the LDQ instruction (instead of replacing it with a NOP instruction) because the offset d that was calculated by the compiler would no longer be valid.

Figure B-11 Optimization of a Standard Call

The ETIR$C_STC_LDA command passes the addresses used to calculate the offset D1. If D1 can be expressed as a signed 16-bit integer, the linker replaces the second LDQ instruction with the LDA instruction supplied by the command and fills in the 16-bit offset field with D1. This replacement eliminates a memory reference to the second half of the linkage pair, which contains the address of the procedure descriptor for B. If D1 is too large to be expressed as a signed 16-bit integer, the linker does not do the replacement. This replacement can happen independently of the replacement of the other LDQ and JSR instructions.

Finally, the ETIR$C_STC_BSR command passes the same addresses as ETIR$C_STC_NOP (so that they will fail or succeed together), and the same test is done again. If the test succeeds, the linker replaces the JSR instruction with the BSR instruction supplied by the command and fills in the 21-bit offset field with D2.

Table B-15 lists the commands for optimizing the instruction stream. The default instruction stream must be placed in memory (typically with an ETIR$C_STO_IMM command) before the instruction-related commands are issued. The linker cannot detect attempts to optimize instructions that have not previously been placed in memory. Each command in the table has the following arguments (excluding the ETIR$C_STC_NBH_PS and ETIR$C_STC_NBH_GBL commands, which are not supported in structure level 2). The argument abbreviations are used by the commands in Table B-15 to describe the operation of the command.

Argument	Abbreviation	Size
Linkage Index	LI	Longword
Psect Index 1	PS1	Longword
Offset 1	OFF1	Quadword
Replacement instruction	REPINS	Longword
Psect Index 2	PS2	Longword
Offset 2	OFF2	Quadword
Global Name (_GBL commands only)	GNAM	Counted String
Psect Index 3 (_PS commands only)	PS3	Longword
Offset 3 (_PS commands only)	OFF3	Quadword

The Linkage Index argument must be nonzero and point to the linkage declared with an address-related conditional store command. The PS1 and OFF1 arguments are used to calculate the location of the instruction that needs to be replaced. For the commands that deal with NOP and BSR instructions, the PS2 and OFF2 arguments point to the base of the calculation, typically, JSR + 4 . The commands for replacing the LDA instruction use PS2 and OFF2 to point to the base of the linkage section. The PS3 and OFF3 arguments point to the procedure entry point for the NOP and BSR commands and to the procedure descriptor for the LDA commands.

Table B-15 Summary of Store Conditional Commands for Instruction Replacement

Value	Command	Description
205	ETIR$C_STC_NOP_GBL (Store Conditional NOP at Global Address)	Store a NOP (specified in REPINS) at (PS1 + OFF1) if the longword displacement from (PS2 + OFF2) to the procedure entry associated with GNAM can be expressed as a signed 21-bit integer.
206	ETIR$C_STC_NOP_PS (Store Conditional NOP at Psect Plus Offset)	Store a NOP (specified in REPINS) at (PS1 + OFF1) if the longword displacement from (PS2 + OFF2) to (PS3 + OFF3) can be expressed as a signed 21-bit integer.
207	ETIR$C_STC_BSR_GBL (Store Conditional BSR at Global Address)	If the longword displacement from (PS2 + OFF2) to the procedure entry associated with GNAM can be expressed as a signed 21-bit integer, then insert the displacement into the low-order 21 bits of the BSR (specified in REPINS) and store it at (PS1 + OFF1).
208	ETIR$C_STC_BSR_PS (Store Conditional BSR at Psect Plus Offset)	If the longword displacement from (PS2 + OFF2) to (PS3 + OFF3) can be expressed as a signed 21-bit integer, then insert the displacement into the low-order 21 bits of the BSR (specified in REPINS) and store it at (PS1 + OFF1).
209	ETIR$C_STC_LDA_GBL (Store Conditional LDA at Global Address)	If the byte displacement from (PS2 + OFF2) to the procedure descriptor associated with GNAM can be expressed as a signed 16-bit integer, then insert the displacement into the low-order 16 bits of the LDA instruction (specified in REPINS) and store it at (PS1 + OFF1).
210	ETIR$C_STC_LDA_PS (Store Conditional LDA at Psect Plus Offset)	If the byte displacement from (PS2 + OFF2) to (PS3 + OFF3) can be expressed as a signed 16-bit integer, then insert the displacement into the low-order 16 bits of the LDA instruction (specified in REPINS) and store it at (PS1 + OFF1).
211	ETIR$C_STC_BOH_GBL (Store Conditional BSR or Hint at Global Address)	If the longword displacement from (PS2 + OFF2) to the procedure entry associated with GNAM can be expressed as a signed 21-bit integer, then insert the displacement into the low-order bits of the instruction specified in REPINS and store it at (PS1 + OFF1). If the displacement is too large or the global name is defined by a shareable image, insert a hint into the low-order 14 bits of the instruction at (PS1 + OFF1).
212	ETIR$C_STC_BOH_PS (Store Conditional BSR or Hint at Psect Plus Offset)	If the longword displacement from (PS2 + OFF2) to (PS3 + OFF3) can be expressed as a signed 21-bit integer, then insert the displacement into the low-order bits of the instruction specified in REPINS and store it at (PS1 + OFF1). If the displacement is too large, insert a hint into the low-order 14 bits of the instruction at (PS1 + OFF1).
213	ETIR$C_STC_NBH_GBL (Store Conditional (NOP and BSR) or Hint at Global Address)	Not supported in structure level 2.
214	ETIR$C_STC_NBH_PS (Store Conditional (NOP and BSR) or Hint at Psect Plus Offset)	Not supported in structure level 2.

Instruction replacement will fail when any of the following conditions occur:

• The linker qualifier /NOREPLACE is specified.
• The displacement cannot be expressed in the number of bits specified for each command listed in Table B-15.
• The linker qualifier /SECTION_BINDING=CODE is specified and the call and the destination are in different image sections.
• A command with the _GBL suffix is used and the global name is defined by a shareable image.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4548PRO_024.HTML