This chapter provides detailed information about compiling and linking Assembler modules.
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:
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.
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.
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 :
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.
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.
To link multiple Assembler modules where the calls reference entry points in the called programs rather than their external names, you need to:
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.
If you want to link modules dynamically at run-time, you have two choices:
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.
If you want to link some modules statically and others dynamically, you need to:
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.
You must use dynamic linking if your Assembler module calls a COBOL module. There are two methods of dynamically linking to COBOL modules:
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.
Link files can also contain the following commands:
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.
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.
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.