Chapter 1: Compiling and Linking Assembler Modules

This chapter provides detailed information about compiling and linking Assembler modules.

1.1 Setting Compiler Directives

You can use directives to control the way the Assembler Compiler behaves. For normal operation you need no more than a few directives. Most of the time, you use the default values.

Note that setting some directives affects the default setting of other directives. For example, setting one directive might automatically unset another directive, and some directive settings are mutually exclusive.

You can set directives in the IDE simply by making selections in the Build Settings dialog box, at either project or program level. These appear in Build Settings at the bottom of the page.

You can also enter directives not already set by typing them into Additional Directives. As you type into Additional Directives, the directives you add appear in Build Settings.

Directives set at project level automatically apply to all Assembler programs within the project, unless you override them at program level.

The build settings are distributed over four Assembler pages in the Build Settings dialog box: General, Link, Preproc (for Preprocessor) and Adv (for Advanced). You can set directives to:

Create debug information. The compiler stores the debug information in files progname.idf and progname.idx, where progname is the name of your program.
Create optimized code. An optimized code compilation fully resolves references to addresses in macro code. If the compilation of your program involves the execution of many macros, you can reduce the total compilation time by specifying this directive.
Mark the code as serially reusable. This prevents reloading of the module each time it is called.
Generate a listing file with optional cross-reference listing.
Link the module automatically; see the section Linking Modules for more information.
Mark the code as re-entrant. This has the same effect as marking code as serially reusable.
Resolve external calls at link time; see the section Linking Modules for more information.
Set addressing mode and residency mode; see the section Memory Requirements in the chapter Run-time Considerations for more information .
Specify what type of load module is to be produced, an executable code file or a data table.
Specify whether the module includes EXEC CICS commands, which will need to be preprocessed.
Use macros that have been partly pre-compiled, rather than recompiling them from the source file. If a macro source file has changed since the date of pre-compilation, it is recompiled anyway. Note that if you have changed a copybook that is included in a macro file, you should always recompile the macro file from the source file.
Create Assembler Analysis Tool files. These are files that assist in the analysis of Assembler programs. For example, you could use them to help you locate date fields that need changing to work correctly in the year 2000 and beyond.
Provide a value for $SYSPARM, which is a variable that can be used within an Assembler module to determine which parts of the code to assemble.

More detailed information is available in the pop-up help in the Build Settings dialog box and in the reference help; click Help Topics on the Mainframe Express Help menu, then on the Contents tab click Reference, Assembler Option, Compiler Directives or Linker Directives.

1.2 Linking Modules

When you build a project containing one or more Assembler modules, the Assembler Compiler first creates an object code file (.obj) for each module. Next, you can either have the Assembler compiler automatically link the object code file into an executable load module (.390) or you can run a separate linker process that combines several object modules into a single linked load module. The link process uses its own link file (.lin) containing link commands. The Assembler automatically searches for external references in CALL commands in the object code files and includes additional object code files as necessary to resolve the external references.

Linking modules when you build the project is known as static linking. You can also link modules dynamically at execution time, when external references in LINK or LOAD commands are resolved.

1.2.1 Program Structures and Linking

You can statically link one or more Assembler modules in several types of executable program structure, using build settings and an optional link file. Your executable program can consist of :

A single Assembler module which is either executed stand-alone or is dynamically called from another Assembler program or a COBOL program.
Several Assembler modules, one of which is the main module that calls the other modules. The main module calls the called modules using their external names (that is, there is only one entry point in each called program).
Several Assembler modules, one of which is the main module that calls the other modules. The main module calls the other modules using entry points other than the modules' external names.

1.2.1.1 Single Assembler Module

To link a single stand-alone Assembler module, you simply need to ensure that Automatically link module is checked. You can find this check box on the Link page of the Assembler page in the Build Settings for Project dialog box or the Build Settings for filename dialog box.

1.2.1.2 Multiple Assembler Modules with Calls Using External Names

To link multiple Assembler modules where all the calls reference the external names of the called modules, you need to ensure that Automatically link module and Resolve external calls at link time are checked for the main module (the calling module) and unchecked for the called modules.

You can find both these check boxes on the Link page of the Assembler page in the Build Settings for Project dialog box or the Build Settings for filename dialog box.

Since all the calls reference the modules' external names, the Assembler Compiler finds and locates all the called modules in your Assembler source libraries, and builds the main and called modules into one .390 file.

1.2.1.3 Multiple Assembler Modules with Calls Using Entry Points

To link multiple Assembler modules where the calls reference entry points in the called programs rather than their external names, you need to:

Ensure that Automatically link module is unchecked for all the modules in the project. You can find this check box on the Link page of the Assembler page in the Build Settings dialog box.
Ensure that Resolve external calls at link time is checked on the General page of the Linker page in the Build Settings dialog box .
Create a link file (.lin) that lists all the object files to be included with the main module in the executable file.This link file must have the same name as the main module. For example if the main module has the name mymain.mlc, the link file must have the name mymain.lin. See the section Link File INCLUDE commands for more information about link files.

When the project is built, the Assembler Linker looks in the .lin file to find out which object files need to be included in the executable file.

1.2.2 Assembler Modules that call COBOL Modules

You cannot statically link Assembler modules with COBOL modules in one executable program. However, there are two methods of dynamically linking to COBOL modules:

You can issue a CALL macro call in your Assembler program. With this method you also need to include an INCLUDE command in a link file for the module you want to link to. When the Linker processes the INCLUDE command, it does not actually include the COBOL module, but instead generates and includes a small Assembler module. When the CALL is executed at run time, the Assembler module loads and links to the COBOL module.
You can issue a LOAD macro call in your Assembler program. Again, the LOAD macro does not load the COBOL module directly, but instead creates and loads an Assembler module the address of which is returned by the LOAD. You then issue a BALR instruction specifying this address. The Assembler module then performs the dynamic link to the COBOL module. Note that if you use this option you must set the high bit in the last parameter address to the number of parameters being passed.

1.2.3 Link File INCLUDE commands

You need an INCLUDE command in your link file for each module that you want to be linked with the main module to produce one .390 file. The INCLUDE command is documented in full in the on-line help; click Help Topics on the Mainframe Express Help menu, then on the Contents tab click Reference, Assembler Option, Link File Commands.

Here is an example of a link file. Assume that assemA is the main Assembler module that calls assemB, assemC and cobolD (with two parameters). The link file assemA.lin contains the following three records:

INCLUDE SYSLIB(assemB)
INCLUDE SYSLIB(assemC)
INCLUDE SYSLIB(cobolD),TYPE=CBL,PARMS=2

The TYPE parameter specifies the language of the called module and is optional; it defaults to ASM (for Assembler) if the main module is Assembler. The PARMS parameter specifies the number of parameters to be passed to the called program; you only need to specify it if TYPE = CBL (for COBOL) . There are options that allow you to call a COBOL IMS program and to call a program with a variable number of parameters.

1.2.4 Other Link File Commands

Link files can also contain the following commands:

NAME. Use this command to specify a name for the executable file other than the name of the source. For example, the name of the source file might be myprog.mlc, but you may want the executable to have the name program1.390
ENTRY. Use this command if the executable file you are building may be called by another program, and you want all such calls to enter the program at a particular entry point, rather than the beginning of the program.
ALIAS. Use this command to create an alias for the executable file that you are building. The alias is created in the Mainframe Express entry point mapping file mfentmap.dat.

These link file commands are documented in full in the online help; click Help Topics on the Mainframe Express Help menu, then on the Contents tab click Reference, Assembler Option, Link File Commands.

1.3 Entry Point Mapping

If one module calls another using the LOAD statement and the call is to an entry point within the module rather than to the external name of the module, you need to specify the relationship between the entry point and the module. You do this by editing the Mainframe Express entry point mapping file mfentmap.dat. For further information see the chapter Compatibility with the Mainframe Environment in your User's Guide.