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 Static 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 Dynamic Linking

If you want to link modules dynamically at run-time, you have two choices:

You can code your calling module to check whether the called module is already available. This way you retain the option to link modules statically sometimes. Each calling module that calls another module first tests the external reference address, and then if it is zero, issues a LOAD for the module, saving the address in the external reference field, then a BALR to go to the called module. With this method you must also specify the Linker directive NCAL when you build the executable program; to do this, uncheck Resolve external calls at link time on the Link page of the Assembler page in the Build Settings dialog box. With NCAL set, the linker issues warnings that external references were not resolved and stores zero in each field holding the address of an external reference.
You can code your calling module to link dynamically always. You simply issue a LOAD for the module you want to link to, then a BALR to branch to it. With this method it makes no difference whether you specify the NCAL Linker directive or not.

We recommend that you also mark each module in this environment as reentrant and serially reusable, so that modules are not deleted and reloaded for each call. To mark a module as reentrant, check Mark module as reentrant on the General page of the Assembler page in the Build Settings dialog box. To mark a module as serially reusable, check Mark load module as serially reusable on the Link page of the Assembler page in the Build Settings dialog box.

If you want to use static linking on module that is normally dynamically linked, and its END statement names a default entry point for the module, you may need to provide an ENTRY command in the link file to override the default entry point. This is because the Linker sets the entry point for the entire executable program to the entry point named on the END statement of the final included module.

1.2.3 Mixing Static and Dynamic Linking

If you want to link some modules statically and others dynamically, you need to:

Specify the Linker directive CALL when you build the executable program; to do this, check Resolve external calls at link time on the Link page of the Assembler page in the Build Settings dialog box. With CALL set, the linker attempts to resolve all external references.
Ensure that for each module that you want to call dynamically, you include an INCLUDE command in the link file with the operand TYPE=COBOL. When the Linker processes the INCLUDE command, it does not actually include the 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 module.

If there are any entry points defined in the statically linked modules that match entry points in the dynamically linked modules, you must also use the Linker directive NOEXPORT, to prevent the linker from making any of the entries in the executable program available to calling programs, and ALIAS link file commands for the statically linked modules, including the main executable program. This technique gives you precise control over the type of linking you use for each module.

Link file commands are discussed in more detail in the sections Link File INCLUDE Commands and Other Link File Commands, and they 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. Linker directives 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, Linker directives.

1.2.4 Assembler Modules that call COBOL Modules

You must use dynamic linking if your Assembler module calls a COBOL module. 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 so that the COBOL program can determine the correct number of parameters.

1.2.5 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.6 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.
CHANGE. Use this command to change the names of external symbols in the object module named in the next INCLUDE command

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.