HP OpenVMS Systems Documentation

OpenVMS Programming Concepts Manual

The OpenVMS Calling Standard defines the concepts and conventions used by common languages to invoke routines and pass data between them. This chapter briefly describes the following calling standard conventions:

• Register usage
• Stack usage
• Argument list
• Argument passing
• Returns

Refer to the OpenVMS Calling Standard for more detail on calling conventions and for standards defining argument data types, descriptor formats, and procedures for condition handling and stack unwinding.

18.1 Hardware Registers

Registers in the hardware provide the necessary temporary storage for computation within OpenVMS software procedures. The number of registers available and their usage vary between the Alpha and VAX systems.

18.1.1 Register Usage for OpenVMS VAX

The calling standard defines several VAX registers and their use, as listed in Table 18-1.

By definition, any called routine can use registers R2 through R11 for computation and the AP register as a temporary register.

18.1.2 Register Usage for OpenVMS Alpha

On Alpha systems, there are two groups of 64-bit wide, general-purpose Alpha hardware registers:

• Integer
• Floating point

The first 32 general-purpose registers support integer processing; the second 32 support floating-point operations.

18.1.2.1 Integer Registers

The calling standard defines the Alpha general-purpose integer registers and their use, as listed in Table 18-2.

18.1.2.2 Floating-Point Registers

A stack is a last-in/first-out (LIFO) temporary storage area that the system allocates for every user process. The system keeps information about each routine call in the current image on the call stack. Then, each time you call a routine, the system creates a structure on the stack, defined as the stack frame.

Stack frames and call frames are synonymous. A call frame for each procedure has a specified format containing pointers and control information necessary in the transfer of control between procedures of a call chain. Stack frames (call frames) of standard calling procedures differ between Alpha and VAX systems.

18.2.1 Stack Procedure Usage for VAX

Figure 18-1 shows the format of the stack frame created for the called procedure by the CALLG or CALLS instruction. The stack frame (pointed to by SP) is in the context of the current procedure, and call frames (pointed to by FP) are the preserved stack frames of other active procedures in the call chain. The stack frame (call frame) for each procedure in the chain contains the following:

• A pointer to the call frame of the previous procedure call, defined as the frame pointer (FP).
  Note that FP points at the condition handler longword at the beginning of the previous call frame. Unless the procedure has a condition handler, this longword contains all zeros. See the OpenVMS Calling Standard for more information on condition handlers.
• The argument pointer (AP) of the previous routine call.
• The stored address (program count) of the point at which the routine was called. Specifically, this address is the program count from the program counter (PC) of the instruction following the call to the current routine.
• The contents of other general registers. Based on a register save mask specified in the control information of the second longword, the system restores the saved contents of the identified registers to the calling routine when control returns to it.

Figure 18-1 Call Frame Generated by CALLG and CALLS Instructions

The contents of the stack located at addresses following the call frame belong to the calling program; they should not be read or written by the called procedure, except as specified in the argument list. The contents of the stack located at addresses lower than the call frame (at FP) belong to interrupt and exception routines; they are modified continually and unpredictably.

The called procedure allocates local storage by subtracting the required number of bytes from the stack provided on entry. This local storage is freed automatically by the RET instruction.

18.2.1.1 Calling Sequence

At the option of the calling procedure, the called procedure is invoked using the CALLG or CALLS instruction, as follows:

     CALLG    arglst, procedure
     CALLS    argcnt, procedure

CALLS pushes the argument count argcnt onto the stack as a longword and sets the argument pointer, AP, to the top of the stack. The complete sequence using CALLS follows:

     push     argn
     .
     .
     .
     push     arg1
     CALLS    #n, procedure

If the called procedure returns control to the calling procedure, control must return to the instruction immediately following the CALLG or CALLS instruction. Skip returns and GOTO returns are allowed only during stack unwind operations.

The called procedure returns control to the calling procedure by executing the return instruction (RET).

Note that when a routine completes execution, the system uses the FP in the call frame of the current procedure to locate the frame of the previous procedure. The system then removes the stack frame of the current procedure from the stack.

18.2.2 Stack Procedure Usage for Alpha

On Alpha systems, when a standard procedure is called, the language compiler creates a stack frame for that procedure. The stack format of a stack frame procedure consists of a fixed part (the size of which is known at compile time) and an optional variable part. There are two basic types of stack frames:

• Fixed size
• Variable size

Figure 18-2 illustrates the format of the stack frame for a procedure with a fixed amount of stack. The SP register is the stack base pointer for a fixed-size stack. In this case, R29 (FP) typically contains the address of the procedure descriptor for the current procedure.

The optional parts of the stack frame are created only as required by the particular procedure. As shown in Figure 18-2, the field names within brackets are optional fields. The fixed temporary locations are optional sections of any stack frame that contain language-specific locations required by the procedure context of some high-level languages.

The register save area is a set of consecutive quadwords in which registers that are saved and restored by the current procedure are stored. The register save area (RSA) begins at the location pointed to by the RSA offset. The contents of the return address register (R26) are always saved in the first register field (SAVED_RETURN) of the register save area.

Use of the arguments passed in memory appending the end of the frame is described in Section 18.4. For more detail concerning the fixed-size stack frame, see the OpenVMS Calling Standard.

Figure 18-2 Fixed-Size Stack Frame Format

Figure 18-3 illustrates the format of the stack frame for procedures with a varying amount of stack when PDSC$V_BASE_REG_IS_FP is 1. In this case, R29 (FP) contains the address that points to the base of the stack frame on the stack. This frame-base quadword location contains the address of the current procedure's descriptor.

The optional parts of the stack frame are created as required by the particular procedure. As shown in Figure 18-3, field names within brackets are optional fields. The fixed temporary locations are optional sections of any stack frame that contain language-specific locations required by the procedure context of some high-level languages.

A compiler can use the stack temporary area pointed to by the SP base register for fixed local variables, such as constant-sized data items and program state, as well as for dynamically sized local variables. The stack temporary area may also be used for dynamically sized items with a limited lifetime, for example, a dynamically sized function result or string concatenation that cannot be directly stored in a target variable. When a procedure uses this area, the compiler must keep track of its base and reset SP to the base to reclaim storage used by temporaries.

The register save area is a set of consecutive quadwords in which registers saved and restored by the current procedure are stored. The register save area (RSA) begins at the location pointed to by the offset PDSC$W_RSA_OFFSET. The contents of the return address register (R26) is always saved in the first register field (SAVED_RETURN) of the register save area.

Use of the arguments passed in memory appending the end of the frame is described in Section 18.4. For more detail concerning the variable-size stack frame, see the OpenVMS Calling Standard.

Figure 18-3 Variable-Size Stack Frame Format

A procedure value is an address value that represents a procedure.

On Alpha systems, the procedure value in R27 is the address of the procedure descriptor that describes that procedure. So any OpenVMS Alpha procedure can be invoked by calling the stored address at offset 8 from the procedure descriptor (PDSC) starting address (procedure value).

On VAX systems, the procedure value is the address of the procedure entry mask that begins the actual code sequence of the procedure.

18.4 Argument List

The calling standard defines a data structure called the argument list. An argument list is a sequence of locations in memory that represents a routine parameter list and possibly includes a function value. You use an argument list to pass information to a routine and receive results.

On VAX systems, the first longword in an argument list (see Figure 18-4) stores the number of arguments (the argument count, n) as an unsigned integer value. The maximum argument count is 255. The remaining 24 bits of the first longword are reserved for use by Compaq and must be 0.

Both integer and floating-point values can be an argument passed in the argument list. Note that a 64-bit floating-point argument counts as 2 longword arguments in the list.

Figure 18-4 Structure of a VAX Argument List

On Alpha systems, arguments are quadwords, and the calling program passes arguments in an argument item sequence. Each quadword in the sequence specifies a single argument. The argument item sequence is formed using R16--21 or F16--21 (a register for each argument). The argument item sequence can have a mix of integer and floating-point items that use both register types but must not repeat the same number. For example, an argument list might use R16, R17, F18, and R19. If there are more than six arguments, the argument items overflow to the end of the stack, as shown in Figure 18-5.

Figure 18-5 Alpha Argument List Format

The calling procedure must pass to the called procedure information about the argument list. For high-level languages, this is performed by the language processor. In the argument information (AI) register (R25), the quadword format is the structure shown in Figure 18-6. The AI register contains the argument count in the first byte. Table 18-4 describes the argument information fields in detail.

Figure 18-6 Argument Information (AI) Register (R25) Format

Each high-level language supported by OpenVMS provides a mechanism for passing arguments to a procedure. The specifics of the mechanism and the terminology used, however, vary from one language to another. For specific information, refer to the appropriate high-level language user's guide.

OpenVMS system routines are external procedures that accept arguments. The argument list contains the parameters that are passed to the routine. Depending on the passing mechanisms for these parameters, the forms of the arguments contained in the argument list vary. As shown in Figures 18-7 and 18-8, argument entries labeled arg1 through argn are the actual parameters, which can be any of the following addresses or value:

• An uninterpreted 32-bit value on VAX or 64-bit value on Alpha systems is passed by value.
• An address of a data value is passed by reference.
• An address of a descriptor that contains a pointer to a data value is passed by descriptor (for example, a string might be the data value).

Figure 18-7 Alpha Procedure Argument-Passing Mechanisms

Figure 18-8 VAX Procedure Argument-Passing Mechanisms

OpenVMS programming reference manuals provide a description of each OpenVMS system routine that indicates how each argument is to be passed. Phrases such as "an address" and "address of a character string descriptor" identify reference and descriptor arguments, respectively. Terms like "Boolean value," "number," "value," and "mask" indicate an argument that is passed by value.

18.5.1 Passing Arguments by Value

When your program passes an argument using the by value mechanism, the argument list entry contains either the actual uninterpreted 32-bit VAX value or a 64-bit Alpha value (zero- or sign-extended) of the argument. For example, to pass the constant 100 by value, the calling program puts 100 directly in the argument list or sequence. For more information about passing 64-bit Alpha values, refer to Chapter 11.

All high-level languages (except C) require you to specify the by-value mechanism explicitly when you call a procedure that accepts an argument by value. For example, FORTRAN uses the %VAL built-in function, while COBOL uses the BY VALUE qualifier on the CALL [USING] statement.

A FORTRAN program calls a procedure using the by-value mechanism as follows:

     INCLUDE  '($SSDEF)'
     CALL LIB$STOP (%VAL(SS$_INTOVF))

A BLISS program calls this procedure as follows:

     LIB$SIGNAL (SS$_INTOVF)

The equivalent VAX MACRO code is as follows:

     PUSHL    #SS$_INTOVF        ; Push longword by value
     CALLS    #1,G^LIB$SIGNAL    ; Call LIB$SIGNAL

A C language program calls a procedure using the by-value mechanism as follows:

 #include <starlet.h>         /* Declare the function*/
       .
       .
     enum  cluster0
        {
           completion, breakdown, beginning
        }  event;

     int status;
     event = completion;
       .
       .
     status = sys$setef(event);     /* Set event flag */