Document revision date: 30 March 2001

## OpenVMS Linker Utility Manual

Previous | Contents | Index

### B.4.3 Operator Commands

Operator commands perform arithmetic on operands popped from the stack. The linker evaluates expressions in Post Fix Polish form. If the structure level EMBH$B_STRLVL is EOBJ$C_STRLVL64, all operations are performed using signed 64-bit two's complement integers. Otherwise, the low-order longwords of operands are used and operations are performed using signed 32-bit two's complement arithmetic. 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. When longword arithmetic is used, 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 Compaq.

### 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 Compaq.

1This command is legal only in debugger information (DBG) and traceback information (TBT) records. For each object module, a list of debugger indexes is kept. These commands operate on the list for the object module in which the DBG or TBT record occurs.

### B.4.5 Conditional Store Commands

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

1Not supported for structure level 2.

#### B.4.5.2 Optimizing Instructions with Instruction-Related Commands

At the direction of the compiler, the linker is able to optimize portions of the instruction stream. The compiler identifies replacements with one of the instruction-related commands listed in Table B-15. These commands supply a reference to the linkage (previously defined with one of the commands listed in Table B-12 ), a replacement instruction, and some conditions for the linker to test.

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.

Previous | Next | Contents | Index

| privacy and legal statement |
4548PRO_024.HTML