360 Assembly/360 Instructions/USING

The USING pseudo-instruction is used to inform the assembler of the contents of various registers which are to be used in base-displacement addressing. It does not generate any executable instructions, it provides information to the assembler.

The format for the USING pseudo-instruction is:

USING address,register1[,register2[,...]]

Register1 can be any of the general purpose registers 1 through 15. It tells the assembler that this register has been loaded with the address specified as the first parameter. Because many instructions - including branch instructions - treat register 0 as a non-action or containing the actual value 0, register 0 should not be used for this purpose. A second (or subsequent) register, indicated by the parameter register2 optionally provides a second base register, and is presumed to contain the address of the first parameter plus 4096. Each subsequent register, if specified, is presumed by the assembler tocontaino the address 4096 above the address specified in the preceding register

Example:

PROG      START 0
          BALR  12,0
          USING *,12,11
          LA    11,4095(12)
          LA    11,1(11)

In the above example, the USING pseudo-instruction tells the assembler that register 12 is established as the base register for the first 4096 bytes of this module, and that register 11 is established for the second 4096 bytes. After register 12 has been loaded with the current address through the BALR instruction, register 11 is loaded with the address 4096 bytes later in the program. Note that this uses the older LA instruction, which cannot add more than 4095 to the value contained in a register, so two LA instructions must be used. While this combination of instructions will work on all models of IBM hardware as well as competitor's equipment, later versions of IBM hardware such as the z/Series provide more efficient instructions for this purpose.

If a specific location is addressed by more than one register, the assembler may become confused and issue an MNOTE level 4 (warning) because it is not sure which register to use, in which case it uses the highest numbered register pointing to the address in question. However, if the using addresses of two or more registers overlap, the assembler will choose the register resulting in the lowest displacement address generated. The following example will demonstrate. This example is from an assembler listing.

000000                                       1 ************
000000                                       2 * Determine which register the assembler uses  
000000                                       3 * Author - Paul Robinson    
000000                                       4 * Date   - 11/28/20
000000                                       5 *****************
000000                                       6          TITLE 'Using test'
000000                                       7          PRINT NOGEN
000000                                       8 *
000000                                       9 MAIN     CSECT 
000000                                      10          USING MAIN,8
000000 90ECD00C                             11          STM   14,12,12(13)
000004 188F                                 12          LR    8,15          Reg 8 now contiains start address
000006 45F0806C                00006C       13          BAL   15,START 
00000C 0000000000000000                     14          DC    18F'0'
000054 D4C1C9D540404040                     15          DC    CL8'MAIN'          Create a marker visible during coredumps
00005C F1F161F2F861F2F0                     16          DC    CL8'11/28/20'     Date compiled 
000064 F0F14BF0F3404040                     17          DC    CL8'01.03'       Version number of program
00006C 50FD0008                             18 START    ST    15,8(13)          Link savearea to preious savearea
000070 50DF0004                             19          ST    13,4(15)
000074 18DF                                 20          LR    13,15             R13 now points to new savearea
000076                                      21          USING MAIN+8,13
000076                                      22          WTO   'Program Started'
000090                                      28 *
000090 4150D4C0                0004C8       29          LA    5,ITEM
000094                                      30 *
000094 4120D0D8                0000E0       31          LA    2,BLANKS
000098 4130D4C0                0004C8       32          LA    3,ITEM
00009C 4140D0D4                0000DC       33          LA    4,X
0000A0                                      34 *
0000A0                                      35          USING X,4
0000A0                                      36          USING ITEM,3
0000A0                                      37          USING BLANKS,2
0000A0                                      38 *
0000A0 41202000                0000E0       39          LA    2,BLANKS
0000A4 41303000                0004C8       40          LA    3,ITEM
0000A8 41404000                0000DC       41          LA    4,X
0000AC                                      42 *
0000AC 41503000                0004C8       43          LA    5,ITEM
0000B0                                      44 *
0000B0                                      45          WTO   'Program ended.'
0000C8 58D0D004                             51          L     13,4(,13) Restore old savearea
0000CC 41F00000                             52          LA    15,0
0000D0 58E0D00C                             53          L     14,12(,13)
0000D4 982CD01C                             54          LM    2,12,28(13)
0000D8 07FE                                 55          BR    14            And leave
0000DA                                      56 *
0000DC 00000000                             57 X        DC    A(MAIN)
0000E0 4040404040404040                     58 BLANKS   DC    1000C' '
0004C8 00000000                             59 ITEM     DC    A(0)
0004CC                                      60          END

Here is how the program was assembled.

• On line 13, the branch is to hexadecimal adderss 8C in the program (label START), and in the instruction, It is assembled as 45F0806C, where 45 is the hexadecimal opcode of the BAL instruction, F being register 15, the first 0 indicating no Index register was used, and 806C is a base-displacement address of hexadeciaml address 08C plus the address in register 8, which was used because of the USING pseudo-instruction on line 10.
• On line 29, the instruction is assembled as 4150D4C0 where 41 is the LA instruction, the 5 means register 5 is the target register to be loaded, the first 0 again indicating no Index register was used, and {{mono|D4C0|| is used indicating that the address is 4C0 hexadecimal bytes plus the address in register 13. This is correct, as ITEM is located at hexadecimal address 4dc8 in the program. The assembler uses register 13 because the using statement on line 21 places the displacement in register 13 as 8 bytes closer to ITEM than register 8.
• Similarly, for the instructions on lines 31-33, the address in Register 13 is "closer" to (the (displacement is less) than register 8, so register 13 is used.
• The instructions on lines 35-37 tell the assembler that registers 2-4 point to these locations.
• On lines 39-41, since the assembler has been told each of these registers points to the item that they are being told to load the address, in each case, that register has a displacement of 0 from the target address, so that register (with an offset of 0) is used.
• On line 43, the assembler was told register 3 is the same address as ITEM, so the assembler uses register 3 with a displacement of 0. Compare this to the identical instruction on line 29, where the address in register 13 produces the smallest displacement, so it was used rather tan register 8.

Here is an example of an inline subroutine which sets up a temporary base register for the subroutine. For the purpose of this example it is assumed that R14 is equated to 14, R15 is equated to 15 etc., to provide cross reference - see EQU Assembler pseudo-instruction)

* some typical assembler instructions showing comments to the right
        L     R15,=A(MOVE)                    Load sub-routine address into R15                   
        BALR  R14,R15                         Go to the sub-routine ===>
*                                             ....return here with return code in R15
*
*****************************************
*  Move the input to output             *
*****************************************
MOVE    EQU   *                               Start of a sub-routine called "Move"
        USING *,R15                           Tell the assembler reg. 15 points to
*                                             this address 
        MVC   OUTPUT,INPUT                    Move the input to the output area 
        SR    R15,R15                         Clear register contents (set Return code = 0)
        BR    R14                             return to caller
        DROP  R15                             Tell assembler we are no longer using
*                                             register 15 and resume using previous register
*
TABLE   DC    C'ABCDEFGHIJKLMNOPQRSTUVWXYZ'   Table of letters of the alphabet
INPUT   DS    Cl80                            Input area
OUTPUT  DS    Cl80                            Output area

As the above example stated, the USING pseudo-instruction tells the assembler that a specific register contains the specified address, while the DROP pseudo-instruction tells the assembler that register can no longer be used, until it is specified in another USING pseudo-instruction.

By convention

• Operating systems often use register 0 and 1 in Supervisor Calls and expect values or address of a list of values to be provided using one or both of these registers; they are also often used (sometimes along with register 15) to return result values from Supervisor Calls. For this reason, register 1 should not be used as a base register in an executable code section, but is acceptable to reference a DSECT mapping labels to the displacement from Register 1.
• Some operating systems and certain instructions may provide or use Register 2 and/or Register 15, so care should be taken if Register 2 or 15 is used as the base register in an assembly language module that issues supervisor calls or macros that issue supervisor calls.
• The Linux operating system on the 390/zSystem hardware uses registers 1 through 6 for arguments, so these registers should not be considered to remain the same or be usable after a supervisor call on S/390 Linux.
• Register 13 is often used as a pointer to an 18-word register save area (for programs running in 24 or 32 bit mode), so it should only be used for this purpose. If the program is not calling any subroutines and saves the value of register 13 on entry, and restores it on exit, register 13 may be used for any purpose. However, if register 13 is being used for some other purpose where it is not pointing to a save area, this should be documented in the program so that anyone doing maintenance on the program in the future is not confused by this practice. Note, register 13 can be used for other purposes such as to point to a rewritable area (such as for reentrant programs that dynamically acquire memory) or for anything else, as long as the first 18 words it points to are available as a register save area.
• Register 14 is often used as the return address for the program to exit back to the caller (or the operating system if the program is not a subroutine). If the program saves register 14 on entry, and restores it on exit, register 14 may be used for any purpose.
• Register 15 is typically provided as the entry point of the program, and thus is acceptable as the USING register; only if the program must itself call a subroutine, then it must establish a different register as its base register. However, some operating systems also use register 15 in addition to registers 0 and 1 to return values, so it may be best not to use register 15 as a base register if the routine issues supervisor calls or macros that issue supervisor calls.

Address can be * for the current program counter, or it can be a label in the current module, or a label plus a value. This allows the assembler to know which base register to use for references to addresses in the current module. It may also be used when referencing a DSECT to assign to labels used in the DSECT a base/displacement address.

A main program (i.e. not a subroutine which has a base register loaded by the caller) would use the BALR or BASR instruction to load the contents of a base register, then issue a USING pseudo-instruction to inform the assembler that the particular register was available as a base register.