20.2 Writing the Assembly-Language Procedure

MASM 6.0 simplifies the coding required for linking MASM routines to high-level-language routines. You can use the new PROTO directive to write procedure prototypes, and the new INVOKE directive to call external routines. This list summarizes the ways MASM simplifies procedure-related tasks.

The PROTO directive improves error checking on argument types.

INVOKE pushes arguments onto the stack and converts argument types to types expected when possible. These arguments can be referenced by their parameter label, rather than as offsets of the stack pointer.

The LOCAL directive following the PROC statement saves places on the stack for local variables. These variables can also be referenced by name, rather than as offsets of the stack pointer.

PROC sets up the appropriate stack frame according to the processor mode.

The USES keyword preserves registers given as arguments.

The C calling conventions specified in the PROC syntax allow for a variable number of arguments to be passed to the procedure.

The RET keyword adjusts the stack upward by the number of bytes in the argument list, removes local variables from the stack, and pops saved registers.

The PROC statement lists parameter names and types. The parameters can be referenced by name inside the procedure.

The complete syntax and parameter descriptions for these procedure directives are explained in Section 7.3, “Procedures.” This section summarizes information from Section 7.3 by giving a template you can use for writing a MASM routine to be called from a high-level language.

The template looks like this:

Label PROC [[distance langtype visibility <prologueargs> USES reglist parmlist]]
LOCAL varlist
.
.
.
RET
Label ENDP

Replace the italicized words with appropriate keywords, registers, or variables as defined by the syntax in Section 7.3.3, “Declaring Parameters with the PROC Directive.”

The distance (NEAR or FAR) and visibility (PUBLIC, PRIVATE, or EXPORT) that you give in the procedure declaration override the current defaults. In some languages, the model can also be specified with command-line options.

The langtype determines the calling convention for accessing arguments and restoring the stack. See Section 20.1 for information on calling conventions.

The types for the parameters listed in the parmlist must be given. Also, if any of the parameters are pointers, the assembler does not generate code to get the value of the pointer references. You must write this code yourself. An example of how to do this is in Section 7.3.3.

If you need to code your own stack-frame setup manually, or if you do not want the assembler to generate the standard stack setup and cleanup, see Section 7.3.2, “Passing Arguments on the Stack,” and, in Section 7.3.8.2, “User-Defined Prologue and Epilogue Code.”