Functional Specification 137-14705-000 Rev 01 14 January 1988 Working Draft 02 FUNCTIONAL SPECIFICATION VAX IMAGE BUILD TOOLS VAX IMAGE BUILD TOOLS VAX IMAGE BUILD TOOLS VAX IMAGE BUILD TOOLS VAX IMAGE BUILD TOOLS Prepared by Martin Brunecky ______________________________ (Signature) January 14, 1988 Approved: ________________________________________ Systems Programming Manager Date ________________________________________ Director of Systems Development Date ________________________________________ R and D Review Chairperson Date Auto-trol Proprietary Information Auto-trol Proprietary Information Auto-trol Proprietary Information Auto-trol Proprietary Information Auto-trol Proprietary Information For Internal Use Only VAX IMAGE BUILD TOOLS Summary of changes from working draft 01 Summary of changes from working draft 01 Summary of changes from working draft 01 Summary of changes from working draft 01 Summary of changes from working draft 01 1. IMGGEN - added "A" option (Anaylyze) to assist in finding commons shared by multiple subsystems 2. IMGBLD - name changed form IMGGEN.COM to avoid confusion 3. IMGBLD - added DCL global symbols generation: - IMG$LINKSTATUS - linker exit status - IMG$REBUILD - image rebuild occured - IMG$SHAREABLE - resulting image is sahreable - IMG$COMPATIBLE - resulting image compatible with reference one - IMG$NEWMAJID - new major ID if the image ahs been patched 4. IMGCHK - added DCL global symbols generation: - IMG$SHAREABLE - resulting image is sahreable - IMG$COMPATIBLE - resulting image compatible with reference one - IMG$NEWMAJID - new major ID if the image ahs been patched 5. IMGXFR - new procedure for dynamic transfer vector generation 6. Added Usefull Hints paragraph. 7. Added an example of MAKES7K use. ii VAX IMAGE BUILD TOOLS TABLE OF CONTENTS CONTENTS 1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . 1 1.1 VMS Executable and Shareable Images . . . . . . . 1 1.2 VMS Image Build . . . . . . . . . . . . . . . . . 2 2 OBJECTIVES . . . . . . . . . . . . . . . . . . . . . 2 3 REFERENCE DOCUMENTS . . . . . . . . . . . . . . . . 3 4 GENERAL DESCRIPTION . . . . . . . . . . . . . . . . 4 4.1 Product Structuring . . . . . . . . . . . . . . . 4 4.2 Inter-image Global Data Access . . . . . . . . . . 5 4.3 Procedural interface compatibility . . . . . . . . 5 4.4 VMS Executable Image Build . . . . . . . . . . . . 6 4.5 VMS Shareable Image Build . . . . . . . . . . . . 7 4.6 Dynamic VMS Shareable Image Load . . . . . . . . . 9 5 DESIGN DESCRIPTION . . . . . . . . . . . . . . . . 10 5.1 Functional requirements . . . . . . . . . . . . 10 5.2 Product Link Process . . . . . . . . . . . . . . 10 5.3 Image Link Process . . . . . . . . . . . . . . . 11 5.4 Test Link Process . . . . . . . . . . . . . . . 13 5.5 Support Files Generation . . . . . . . . . . . . 14 5.6 Shareability and Compatibility Checking . . . . 15 5.7 Dynamic Shareable Image Load . . . . . . . . . . 18 5.7.1 Dynamic Transfer Vector . . . . . . . . . . . . 18 5.7.2 User Error Handling Routine . . . . . . . . . . 19 5.7.3 Dynamically Loaded Image Debugging . . . . . . . 20 5.7.4 Dynamic Transfer Vector Module Generation . . . 20 5.8 Usefull Hints . . . . . . . . . . . . . . . . . 21 6 CONSTRAINTS AND LIMITATIONS . . . . . . . . . . . 22 6.1 Control File Maintenance . . . . . . . . . . . . 22 6.2 Dynamic Transfer Vector Generation . . . . . . . 22 6.3 Limitations in Control File Syntax . . . . . . . 22 6.4 Limitations in Image Compatibility Checking . . 22 7 NAMING CONVENTIONS . . . . . . . . . . . . . . . . 23 7.1 Resulting File Names . . . . . . . . . . . . . . 23 7.2 Temporary File Names . . . . . . . . . . . . . . 23 7.3 Tools External Names . . . . . . . . . . . . . . 24 7.4 Tools Internal Names . . . . . . . . . . . . . . 24 7.5 Tools Languages . . . . . . . . . . . . . . . . 24 8 ROUTINES and FUNCTIONS . . . . . . . . . . . . . . 25 9 DATA STRUCTURES . . . . . . . . . . . . . . . . . 27 9.1 VMS Image Build Control File . . . . . . . . . . 27 9.2 Global Data Description File . . . . . . . . . . 30 9.3 Logical Names Definition File . . . . . . . . . 30 10 ERROR-EXCEPTION HANDLING . . . . . . . . . . . . . 31 APPENDIX A SHAREABLE IMAGE LAYOUT i VAX IMAGE BUILD TOOLS APPENDIX B IMAGE BUILD CONTROL FILE APPENDIX C DYNAMIC TRANSFER VECTOR MODULE APPENDIX D MAKES7K USE EXAMPLE 2 VAX IMAGE BUILD TOOLS INTRODUCTION INTRODUCTION INTRODUCTION INTRODUCTION INTRODUCTION 1 INTRODUCTION Any current software products are internally structured into modules modules modules modules modules (procedures, function, subroutines). This modular approach works very well for products consisting of a few up to several hundred modules. With increasing product complexity, such as ATTC S5000, S7000 products, another level of structuring is needed. Such a level in product structure hierarchy is subsystem subsystem subsystem subsystem referred to as a subsystem throughout this documment. A subsystem typically performs certain class of functions, has multiple entry points, it's own internal data and (in some instances) accesses data which are global to the entire product. It is highly desirable that subsystems: o may be built and released asynchronously (independent of the other subsystems within a single product) o may be loaded on an as-needed basis (saving computer resources if a particular subsystem is not used). Under Aegis, both requirements may be satisfied by implementing the subsystem as a "sub-bind library" Under VMS, both requirements may be satisfied by implementing the subsystem as a "shareable image" Under UNIX 5.3, subsystem implementation using a "shareable image" will be possible in the near future. This document discusses all the aspects of the VMS shareable image use in the context above. It defines tools intended to simplify builds in such a case, and also defines specific support for dynamic shareable image load. VMS Executable and Shareable Images VMS Executable and Shareable Images VMS Executable and Shareable Images VMS Executable and Shareable Images 1.1 VMS Executable and Shareable Images An executable VMS image is the program, linked by the VMS linker from object modules. Executable image is ready to execute in the context of VMS process Even without the user knowing, most executable images are linked referencing several standard VMS system shareable images (such as VMSRTL.EXE, MTHRTL.EXE, FORRTL.EXE and other). VMS shareable image is a pre-linked set of object modules, which 1 VAX IMAGE BUILD TOOLS INTRODUCTION may be accessed via a set of marked entry points, or named global data. Shareable image is invoked on behalf of an executing executable image, either at image activation, or dynamically at runtime. VMS shareable image allows for inter-process code and data sharing (to reduce memory use in multiprocessing environment, or for inter-process communication using global data). However, VMS shareable image may be used in a context of a single process as well: - to improve product structuring - to increase product flexibility - to enable independent release of product subsystems - to dynamically load subsystems only when necessary - to save link time and computer resources - to allow bi-directional calls between subsystems VMS Image Build VMS Image Build VMS Image Build VMS Image Build 1.2 VMS Image Build The image build process on the VMS/VAX is mostly considered a very simple task, not requiring any special knowledge nor arrangements. In the case of larger images, the simplistic approach "only" causes some performance penalty. Since the shareable image build is not quite simple, several tools are necessary to standardize and simplify the task of building complex VAX images. OBJECTIVES OBJECTIVES OBJECTIVES OBJECTIVES 2 OBJECTIVES This Functional Specification intends to: * Provide basic information needed to understand VMS shareable image implementation, use and restrictions. * Address the problems and specifics of VMS shareable image build * Define facilities alowing dynamic VMS shareable image load * Define tools required for consistent builds and test-builds * Define tools required for the build formal checking 2 VAX IMAGE BUILD TOOLS REFERENCE DOCUMENTS REFERENCE DOCUMENTS REFERENCE DOCUMENTS REFERENCE DOCUMENTS REFERENCE DOCUMENTS 3 REFERENCE DOCUMENTS S5000 On site binding VAX VMS LINKER reference manual 3 VAX IMAGE BUILD TOOLS GENERAL DESCRIPTION GENERAL DESCRIPTION GENERAL DESCRIPTION GENERAL DESCRIPTION GENERAL DESCRIPTION 4 GENERAL DESCRIPTION Product Structuring Product Structuring Product Structuring Product Structuring 4.1 Product Structuring Large software products (ATTC S7000, S5000) need to be structured into several relatively independent subsystems. Because of close subsystems relations, such a structuring can not be accomplished by breaking the product into several independent images or processes (except for building several products subsets, each with a limited functionality). Using either Aegis sub-bind libraries or VMS/UNIX shareable images, many products may be structured similarly to the following: ___________ |___________| Executable Image ROOT | _____|_____ ______ | | | |_ Shareable CORE | |-|______| | supported by several | |---|______| support images |___________| / (contains global data) / | \ / ______/ ___|__ \_____/ | | | | | | Shareable APPLICATIONS |______| |______|--|_____| (dynamically loaded) CORE is the most commonly used set of product routines and global data. It may be built using support subsystems, which provide for core environment independency (for example, HW-specific workstation interface may be one of the support subsystems). SUPPORT subsystems typically do not reference CORE and are called by procedural interface either from CORE or from APPLICATION. In essence, all the VMS support (runtime) libraries present SUPPORT subsystems. APPLICATION subsystems are called by the CORE to perform specific functions. They may call CORE and SUPPORT subsystems, and (if needed) reference global data in CORE. Using the concept of "dynamic image load", applications may call each other (but not reference it's data). 4 VAX IMAGE BUILD TOOLS GENERAL DESCRIPTION Inter-image Global Data Access Inter-image Global Data Access Inter-image Global Data Access Inter-image Global Data Access 4.2 Inter-image Global Data Access GLOBAL DATA access presents the major complication in using VMS global global global global shareable image. In contrary to APOLLO, any references to global data link data link data link data link data are resolved at the link time. Therefore, any changes to global data size and/or position on the VMS may require a re-build of all images involved. LIMITATION LIMITATION LIMITATION LIMITATION LIMITATION VMS global data access handling does NOT allow images to be built where shareable image (1) references global data BBB in image (2), and at the same time the image (2) references global data AAA in image (1): ____________ |____________| / \ _______/ \_______ (1) | AAA |<---| | (2) | |--->| BBB | |_______| |_______| The primary reason is the VMS linker behavior: In the shareable image (1) build, the linker needs the image (2) to determine the position of the global data BBB. But the image (2) does not exist, since to build image (2) the linker needs image (1), to determine the position of global data AAA. | | The only solution to the problem above is to place both global | data (AAA and BBB) in separate shareable image, linked BEFORE | images (1),(2): | ____________ | |____________| | / \ | _______/ \_______ | (1) | | | | (2) | |_______| |_______| | \____________/ | | -AAA | | | -BBB | | |____________| Procedural interface compatibility Procedural interface compatibility Procedural interface compatibility Procedural interface compatibility 4.3 Procedural interface compatibility To allow for independent subsystem (application) release, it is necessary to guarantee that the right routines are be called in any release of the referenced shareable image, without a need to 5 VAX IMAGE BUILD TOOLS GENERAL DESCRIPTION re-build the caller. For any shareable image, VMS provides a mechanism to maintain independency and compatibility. Using "transfer vectors", shareable image entry points are placed at fixed locations at the beginning of the image, regardless of the routine code placement. Thus the reference to image_base+offset always transfers control to the same routine. For an image loaded using "dynamic image load" (similarly to Aegis INLIB), entry points are located at run-time, and any calls are dynamically routed to proper routine (by the code located in caller). VMS Executable Image Build VMS Executable Image Build VMS Executable Image Build VMS Executable Image Build 4.4 VMS Executable Image Build Building an Executable VMS image is a straight forward process. The VMS linker applies many defaults, so that the user typically does not have to specify any options, unless specific requirements are the issue. Each VMS image is composed of IMAGE CLUSTERS. Normally, there is only one, DEFAULT_CLUSTER. The linker loads code and data sections into image clusters in a simple organized way: * Within each image cluster, the LINKER collects together module contributions to each named program section (PSECT), and loads such sections into image in alphabetical order. * Within each PSECT, the linker loads code/data in the alphabetical order of the module names. The above LINKER default behavior results in module code and data widely separated in the image. Therefore, module execution typically has to bring into core pages from multiple image locations. If naming convention does not automatically place related modules together, modules calling each other are widely separated again, thus further increasing paging needs. Hence, for performance consideration, explicit image layout control is desirable. 6 VAX IMAGE BUILD TOOLS GENERAL DESCRIPTION VMS Shareable Image Build VMS Shareable Image Build VMS Shareable Image Build VMS Shareable Image Build 4.5 VMS Shareable Image Build As stated in the introduction, the Shareable Image does not necessarily need to be (code)shared - there may be several other reasons to use pre-linked code. The following discussion concentrates on Position Independent (PIC) shareable images, with NO inter-process data sharing. The BASED shareable image usage is too clumbersome, and inter-process data sharing is not an issue as of yet. In general, VMS shareable image is a portion of code and data, which is mapped into process virtual address space either at the image activation or at runtime. Any global symbols (entry points) accessible in the shareable image must be marked at the link time (UNIVERSAL linker option). Any global data in the shareable image are made (automatically by the linker) accessible to any other image linked to it. At run time, the image activator resolves (relocates) any calls to the shareable image entry points, and any reference to its global data. Contrary to Apollo INLIB, which does full-scale runtime global symbol and data resolution, the VMS entry point and global data references are resolved AT THE LINK TIME - as offsets relative to the image starting address. The runtime activation merely updates information, applying a uniform offset to any global reference (the only exception to that rule is the dynamic shareable image load, described later). Therefore, the shareable image must exist prior to any other image that references it, and VMS linker extracts the information about entry point position (or global data position and size) from the shareable image file. To maintain compatibility between shareable image releases, VMS uses the concept of "transfer vectors". Using transfer vectors, the shareable image entry points appear to be always at fixed locations in the image (typically at the beginning of the image). The entry point position is preserved even if the actual code changes (in size and placement). Therefore, the shareable image may be updated without re-linking any other image referencing it. However, the "transfer vector" module must be coded in MACRO, and it's entry point sequence always preserved to guarantee such compatibility. 7 VAX IMAGE BUILD TOOLS GENERAL DESCRIPTION The major problem with a VMS shareable image build are global data sections, generated by most of the VMS compilers. 1. Any FORTRAN COMMON or VAX-C GLOBAL DATA generate a program section with GLOBAL, SHAREABLE, OVERLAID attributes. - SHAREABLE means sharing among several VMS processes - which is not the case in ATTC application. - GLOBAL makes data externally accessible. - OVERLAID implies "common" data usage - any reference to such data uses the same starting location. Compiler generated defaults may be overridden at the link names names names names time, presuming that names of such global data are known. 2. Global data reference is resolved at link time, and is only offset at image activation. Thus any global data size and position must be explicitly controlled to guarantee compatibility between several builds of the same image. Any change here means compatibility loss, without any VMS linker nor runtime warning. 3. Any image that references global data defined within a shareable image must match program section attributes for this data in the shareable image. Typically, this requires an explict override of compiler generated defaults. Any incompatible attributes are reported by the LINKER, giving a trace of unwanted global data access. The solution to the global data problems is as follows: 1. The build process must know NAMES of any global data generated by the compilers. 2. Any global data, which should NOT be accessed from outside of a shareable image, must be redefined either to LOCAL or NOSHAREABLE at the image link. 3. Any global data, which are to be accessed by shareable image callers, must be collected into an explicit image CLUSTER following image transfer vector, or placed in a special, data-only shareable image. Using data-only shareable images may significantly simplify data-compatibility issue. However, increasing shareable images count adds image activation overhead (opening each image file). 8 VAX IMAGE BUILD TOOLS GENERAL DESCRIPTION Dynamic VMS Shareable Image Load Dynamic VMS Shareable Image Load Dynamic VMS Shareable Image Load Dynamic VMS Shareable Image Load 4.6 Dynamic VMS Shareable Image Load Normally, any shareable image referenced by the executable image are loaded at the image activation time. The VMS image activator automatically loads and maps any shareable images used at the link time into process virtual address space. Such images can only be referenced in a single direction. Using the VMS RTL function LIB$FIND_IMAGE_SYMBOL, the executing image may force dynamic load of any image linked as "shareable" at run-time, and call any symbol in any of the images previously loaded. The RTL function returns the absolute address of a requested shareable image entry point (by name), and the user may call this absolute address. The dynamically loaded shareable image references to other shareable images (entry points, global data) are automatically resolved at the load. Once loaded, shareable images can NOT be unloaded. NOTE Accessing global data in a dynamically loaded shareable image goes beyond this specification. Part of this specification defines a MACRO module referred to as dynamic transfer vector dynamic transfer vector dynamic transfer vector dynamic transfer vector dynamic transfer vector. This module and related SIMGLD routine are designed to efficiently handle calls to the dynamically loaded image, avoiding the LIB$FIND_IMAGE_SYMBOL overhead on subsequent calls. The actual call overhead on a second call is limited to a single JMP #address instruction. The implementation also provides for a user supplied error handling routine, to be called at any image-load related error (replacing standard VMS exception signaling). 9 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION DESIGN DESCRIPTION DESIGN DESCRIPTION DESIGN DESCRIPTION DESIGN DESCRIPTION 5 DESIGN DESCRIPTION Functional requirements Functional requirements Functional requirements Functional requirements 5.1 Functional requirements The build procedure for an image, structured using several shareable images, has to be as simple as possible. There must be an easy way to build individual components, and to modify the build process for testing. The build procedure must provide for compatibility checking with previous releases, in case of the "official build" such checking must enforce re-builds if necessary. Since the build process involves several files, which change in case of any image configuration change, the proposed implementation builds all such files "on the fly", using a single CONTROL FILE. The CONTROL FILE concept also simplifies changes related to the VMS operating system evolution, isolating REQUIREMENTS (contained within a control file) from the actual build process IMPLEMENTATION. Link requirements for any product component (shareable or executable image) are defined using the CONTROL FILE. For development purposes (maketest), the same file may be used, allowing override of any information contained there. Product Link Process Product Link Process Product Link Process Product Link Process 5.2 Product Link Process The product link process must allow for a complete product link (all components), or for selective, partial links only. * Full build links all the product components (images). * Partial link checks pre-requisites availability, and links only requested set of images. In both cases, any image that is intended to be compatible with the previous build must be checked for compatibility requirements. Detailed implementation of the product link process goes beyond this specification. 10 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION Image Link Process Image Link Process Image Link Process Image Link Process 5.3 Image Link Process The image link process is frequently related to existence of pre-requisites, i.e. shareable images it links. On the other hand, link of the shareable image that is used as a pre-requisite for any other components must: * guarantee image shareability requirements * attempt to meet compatibility with the previous release * guarantee notification if compatibility requirements are not satisfied. For any shareable image link, each image must be checked to make sure any global data are declared NOSHR, i.e. each VMS process running such image will use it's own copy of global data. The image build process flow: 1. Assign any logical names used by the control file 2. Check pre-requisite files presence 3. Generate necessary support files 4. Compile support files, if needed 5. LINK the image 6. Perform image shareability checks 7. Perform image compatibility checks 8. Repeat steps 3-7 if necessary 9. Update the image ID if necessary | The IMGBLD procedure is used to replace the SHRGEN procedure used | in AUOSI 10.nn and S7K 11.nn shareable image builds: | $@IMGBLD bldid lnmfil ctlfil [updfil] [refimg] [opt] [targ] [def] $@IMGBLD bldid lnmfil ctlfil [updfil] [refimg] [opt] [targ] [def] $@IMGBLD bldid lnmfil ctlfil [updfil] [refimg] [opt] [targ] [def] $@IMGBLD bldid lnmfil ctlfil [updfil] [refimg] [opt] [targ] [def] | $@IMGBLD bldid lnmfil ctlfil [updfil] [refimg] [opt] [targ] [def] where: bldid bldid bldid bldid * bldid Build identification in format rrbb (release, build) | lnmfil lnmfil lnmfil lnmfil | * lnmfil Logical names definition file (may be "" or "NONE") ctlfil ctlfil ctlfil ctlfil * ctlfil Main build control file. The name portion is used for any temporary files, and for the output files: - [target]namerrbb.EXE - resulting image - [target]namerrbb.MAP - resulting map - [target]namerrbb.SHR - "stub" shareable image 11 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION updfil updfil updfil updfil * updfil - Update control file (used by test build procedure) | refimg refimg refimg refimg | * refimg - Reference image filename. Global data sizes from | such an image are used for the build. Compatibility checking | compares resulting size and position for any such data. May | be specified as "" or "NONE". option option option option * option - Build process options, combination of letters: E E E E - E Executable - build an executable image S S S S - S Shareable - build a shareable image T T T T - T Template - build a shareable image STUB (template) N N N N - N NoVector - do not use the transfer vector module D D D D - D Debug - create debug image M M M M - M Map - create image map F F F F - F Full - create full image map C C C C - C Cross - create map with cross reference L L L L - L Leave - leave (do not delete) temporary support files U U U U - U Use - use support files created by previous (L) run R R R R - R Rebuild - rebuild image to meet shareability requirement (no writeable sections) P P P P - P Patch - patch the resulting image major ID if not compatible to the reference image A A A A | - A Analyze - don't extract global data from shareable | images (used for unintended common sharing checks). B B B B | - B TraceBack - build image with NOTRACEBACK linker option target target target target * target - Target for created files (if not current default) def def def def * def - Default directory to use (if not current default) | For use by calling procedure, the following DCL GLOBAL symbols | are defined by IMGBLD.COM: | | - IMG$LINKSTATUS - linker exit status from last LINKER run | - IMG$REBUILD - image rebuild occured (YES=1) | - IMG$SHAREABLE - resulting image is sahreable (YES=1) | - IMG$COMPATIBLE - resulting image compatible with reference | one | - IMG$NEWMAJID - new major ID if the image has been patched | The IMGGEN procedure uses the IMGGEN.EXE program to create necessary support files according to requirements prescribed in the build control file (and optional update file). Support MACRO-32 modules (Global Data Sizes definition and Transfer Vector modules) are compiled and image linked according to specified options. 12 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION The resulting shareable image is checked for shareability requirements. If the image contains any writeable global data R R R R (and the Rebuild option was specified), procedure creates new update control file and repeats the entire build. If the reference image is specified, new image is checked to match global data sizes and positions. If any of those does not P P P P match and Patch option was specified, new image is patched to increase global section major ID. Test Link Process Test Link Process Test Link Process Test Link Process 5.4 Test Link Process The test link process (maketest) does not necessarily have to adhere to all of the compatibility requirements. The related components re-link does not have to happen automatically. However, re-build in case of non-compliance with shareability requirements has to happen automatically. The procedure proposed to replace "MAKETEST" uses IMGGEN.COM, but applies product-specific defaults: $ @MAKEprod compon [updfile] [opt] [refbld] [newcore] [newlogs] $ @MAKEprod compon [updfile] [opt] [refbld] [newcore] [newlogs] $ @MAKEprod compon [updfile] [opt] [refbld] [newcore] [newlogs] $ @MAKEprod compon [updfile] [opt] [refbld] [newcore] [newlogs] $ @MAKEprod compon [updfile] [opt] [refbld] [newcore] [newlogs] where: prod prod prod prod * prod - Product designation (S7K, S5K etc.) compon compon compon compon * compon - Component to build (i.e. CORE, PDIE), or an explicit (new) control file pathname. updfile updfile updfile updfile * updfile - Update file. Uses the CTL file format. If missing, procedure prompts for any update modules, and builds the compon_UPD.CTL file interactively. | opt opt opt opt | * opt - Options, refer to IMGBLD options refbld refbld refbld refbld * refbld - Reference CORE build ID, if not "the current one" For the CORE builds, "refbld" defines reference CORE to be compatible with. Empty or NONE requests new CORE with no attempt for compatibility. newcore newcore newcore newcore * newcore - Explicit CORE, if not "the current one" newlogs newlogs newlogs newlogs * newlogs - Replacement logical names file, replacing the product standard one. | Procedure prompts for any arguments missing or specified as empty | ("") on the command line. Then it applies defaults based on 13 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION | product requirements, current build level, and other. It also provides the default logical names file (if necessary). It submits the IMGGEN procedure with a proper set of arguments to perform the build in BATCH environment, using product specific queue (S7KQUE), or standard sys$batch que if product specific que does not exist. Support Files Generation Support Files Generation Support Files Generation Support Files Generation 5.5 Support Files Generation Support files generation must be fast. It must use a single main control file, and provide for an additional - modification control file (which in most cases will be very simple). Support files generation must support selective support files generation. To make the support files generation fast, the IMGGEN.EXE program is used. IMGGEN produces the following files: - VMS Linker OPTION file - Transfer vector (MACRO) module - Global data declaration (MACRO) module - Dynamic transfer vector (MACRO) module The IMGGEN command format is: $ IMGGEN ctlfile updfile refimg bldid options $ IMGGEN ctlfile updfile refimg bldid options $ IMGGEN ctlfile updfile refimg bldid options $ IMGGEN ctlfile updfile refimg bldid options $ IMGGEN ctlfile updfile refimg bldid options where: ctlfile ctlfile ctlfile ctlfile - ctlfile - Control file with image link requirements. The control file name portion is used for any files generated. updfile updfile updfile updfile - updfile - Control file with update requirements. This argument is for test builds only, to change the standard build control file requirements. NONE specifies empty file. refimg refimg refimg refimg - refimg - Reference image. If present, IMGGEN will extract all the global data information from that image in an attempt to make current link data-compatible. The same global data / size will be forced into a new image. NONE specifies empty image. bldid bldid bldid bldid - bldid - Build ID in format rrbb options options options options - options - IMGGEN action options expressed by a combination of E E E E - E Executable - build files for an executable image S S S S - S Shareable - build files for a shareable image build 14 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION T T T T - T Template - build files for a shareable image STUB N N N N - N NoVector - do NOT build and use transfer vector module X X X X - X Xfer - generate the dynamic transfer vector module only A A A A | - A Analyze - do NOT use global data definition from | shareable images (for use in unintended common reference | checks). The LINKER OPTIONs file is generated if any of E,S,T is used. The Global Data Module is generated if the control file prescribes any global data size, or refimg exists. The transfer vector module is generated if either S or T is specified, using N[ovect] for a shareable image is discouraged (the linker may attempt to base an image without transfer vector). Shareability and Compatibility Checking Shareability and Compatibility Checking Shareability and Compatibility Checking Shareability and Compatibility Checking 5.6 Shareability and Compatibility Checking Both steps apply to shareable images only. In both cases, the image GST (Global Symbol Table) must be scanned for global data definition, and: * For shareability checks, any global data must hold VMS PSECT attribute NOSHR. Otherwise, multiple processes will share the same data, and the image would have to be installed as a writeable file (INSTALL qualifiers /SHARE /WRITE). * For compatibility checks, any global data must have the same position and size in both images checked. * For compatibility checks, any entry points must be at the same position (address). IMGCHK IMGCHK IMGCHK IMGCHK The IMGCHK procedure provides the top-level tool for image checking: $ @IMGCHK image [refimg] [opt] $ @IMGCHK image [refimg] [opt] $ @IMGCHK image [refimg] [opt] $ @IMGCHK image [refimg] [opt] $ @IMGCHK image [refimg] [opt] where: image image image image * image - the image to be checked for shareability refimg refimg refimg refimg * refimg - reference image, to check compatibility against opt opt opt opt * opt - options combined from letters: 15 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION P P P P - P Patch the image. If the image is not compatible with a reference one, use PATCH to increase it's global section MAJOR ID. E E E E - E Entry points compatibility checking required (not implemented). | For use by calling procedure, the following GLOBAL DCL symbols | are defined by IMGSCA.COM: | | - IMG$SHAREABLE - resulting image is sahreable (YES=1) | - IMG$COMPATIBLE - resulting image compatible with reference | one | - IMG$NEWMAJID - new major ID if the image has been patched | NOTE: NOTE: NOTE: NOTE: NOTE: A full compatibility checking should check the entry point addresses as well. Since other tools described here guarantee that, and checking will add a significant overhead, such a step is not implemented as of yet. 16 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION IMGSCA IMGSCA IMGSCA IMGSCA The IMGCHK procedure uses the IMGSCA program to extract information from the shareable image GST (Global Symbol Table): $ IMGSCA image options output $ IMGSCA image options output $ IMGSCA image options output $ IMGSCA image options output $ IMGSCA image options output where: image image image image * image - pathname to an image to scan options options options options * options - scan options combined from letters: E E E E - E - Entry = list entry points M M M M - M - Modular procedure = list PROCEDURE entry points S S S S - S - SPSECT = list shareable PSECTs P P P P - P - PSECTs = list all PSECTS C C C C - C - Check all SPSECTs to be NOSHR 1 1 1 1 - 1 - list name only 2 2 2 2 | - 2 - list COMMON=name, size, position (default) 3 3 3 3 | - 3 - list GLOBAL=name 4 4 4 4 | - 4 - list LOCAL=name Since some compiler declare entry points as "entry" (option E) while other as "procedure" (option M), combination EM gives listing of all available entry points in shareable image. output output output output * output - output data file pathname. For the output data file format see the DATA STRUCTURES section. 17 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION Dynamic Shareable Image Load Dynamic Shareable Image Load Dynamic Shareable Image Load Dynamic Shareable Image Load 5.7 Dynamic Shareable Image Load The Dynamic Shareable Image load refers to shareable image activation at the runtime (as opposed to standard shareable image activation at the executable image start time). Since VMS currently provides only limited support for dynamic image load, several additional facilities are defined here. Dynamic Transfer Vector Dynamic Transfer Vector Dynamic Transfer Vector Dynamic Transfer Vector 5.7.1 Dynamic Transfer Vector The Dynamic Transfer Vector module defines prescribed entry CALLERs CALLERs CALLERs CALLERs points for the CALLERs reference. Thus, the dynamic transfer calls calls calls calls vector module is linked into the image which calls defined entry points of the dynamically loaded image. The generation of the Dynamic Transfer Vector module is included within IMGGEN, since the entry point names available for calls are the same as defined by the build control file for the called image. Normally, the dynamic transfer vector(s) generation will be performed as part of the build pre-set. NOTE, transfer vector(s) must be kept in a separate object library, since they re-define entry points to regular, actual routines. The input for dynamic transfer vector is: - the shareable image path-name (VMS logical name must be used, never the explicit pathname). Each application should select logical names in compliance with ATTC VMS product installation / naming standards. - the error handling routine name. If not specified, any errors in image load are signalled by standard VMS exception signalling (warnings are supressed by SIMGLD). - the list of entry point names to access in a dynamically loaded shareable image. Note, all such entry points must be made "UNIVERSAL" (marked) in the shareable image link. The dynamic transfer module defines a "pseudo-entry" point for each entry requested in the dynamically loaded image. Initially, SIMGLD SIMGLD SIMGLD SIMGLD this pseudo-entry is loaded with a call to the SIMGLD AUOSI 11.nn routine. At the first call to pseudo-entry, SIMGLD loads a required shareable image using information from the dynamic transfer vector (image name, entry point name). It calls LIB$FIND_IMAGE_SYMBOL, and receives the real entry point absolute 18 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION virtual address (in the loaded shareable image). SIMGLD than re-builds original pseudo-entry to contain direct jump to the called code, and moves the procedure entry mask to pseudo-entry. Thus, on the first call, the required entry is called indirectly; any subsequent calls jump directly into called code. Examples of the dynamic transfer vector code: Before a first call: Entry ENTRY_NAME,^M JSB G^SIMGLD+2 ...... (image name and error routine pointers) .ASCID /ENTRY_NAME/ After a first call: Entry ENTRY_NAME,^M JMP ENTRY_NAME_code_start ...... User Error Handling Routine User Error Handling Routine User Error Handling Routine User Error Handling Routine 5.7.2 User Error Handling Routine after after after after User error handling routine will be called by SIMGLD after an error in image load has occured (not as an exception handler): USRERR ( IMGPATH, ENTRY, ISTAT, VMSSTS ) USRERR ( IMGPATH, ENTRY, ISTAT, VMSSTS ) USRERR ( IMGPATH, ENTRY, ISTAT, VMSSTS ) USRERR ( IMGPATH, ENTRY, ISTAT, VMSSTS ) USRERR ( IMGPATH, ENTRY, ISTAT, VMSSTS ) where: * IMGPATH, Character*(*), Image logical name * ENTRY, Character*(*), Entry point name * ISTAT, Integer*4, AUOSI error status code: - STIFIS - Invalid filespec (image not a logical name) - STPROG - Program not found (error activating image) - STRESX - Resources exceeded (insufficient virtual space) - STNCOM - Component not found (entry not found) - STPEND - Request pending (build problems within image) - STFATL - Fatal AUOSI error (unable to translate status) * VMSSTS Integer*4, VMS error status code 19 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION Dynamically Loaded Image Debugging Dynamically Loaded Image Debugging Dynamically Loaded Image Debugging Dynamically Loaded Image Debugging 5.7.3 Dynamically Loaded Image Debugging In order to DEBUG a shareable image, it must be linked using the DEBUG option. Since dynamically loaded images are not present at image start-up time, it is impossible to set-up breakpoints before the image actually loads. To enable debugging, the SIMGLD routine allows the software to break into the debuger at the first call to a specified entry in the dynamically loaded image. Such an entry must be defined prior to image start as a DCL symbol: $ ATTC_DEBUG_IMAGE_ENTRY := " " $ ATTC_DEBUG_IMAGE_ENTRY := " " $ ATTC_DEBUG_IMAGE_ENTRY := " " $ ATTC_DEBUG_IMAGE_ENTRY := " " $ ATTC_DEBUG_IMAGE_ENTRY := "name" where name is the required entry breakpoint. The SIMGLD generates a debugger breakpoint after the image has been loaded, but before the first call to required entry. At this point, the user must set required image (DBG>SET IMAGE image_name) and any further breakpoints. NOTE, only the debugged image must be linked with DEBUG option, any other images used may use a standard link. | | | Dynamic Transfer Vector Module Generation Dynamic Transfer Vector Module Generation Dynamic Transfer Vector Module Generation Dynamic Transfer Vector Module Generation | 5.7.4 Dynamic Transfer Vector Module Generation | | To simplify the task of dynamic transfer vector module generation | from build control file, IMGXFR.COM procedure is provided: $@IMGXFR ctlfile bldid [library] [option] $@IMGXFR ctlfile bldid [library] [option] $@IMGXFR ctlfile bldid [library] [option] $@IMGXFR ctlfile bldid [library] [option] | $@IMGXFR ctlfile bldid [library] [option] | | where: | ctlfile ctlfile ctlfile ctlfile | - ctlfile - Control file with image entry points and image | logical name definition. The control file name portion is | used for the module generated. | bldid bldid bldid bldid | - bldid - Build identification (bbrr), used internally for | module identification. | library library library library | - library - Object module library, if present, resulting object | module will be replaced in this library and deleted. | options - Letter L (Leave) leaves the module MACRO source in options - Letter L (Leave) leaves the module MACRO source in options - Letter L (Leave) leaves the module MACRO source in options - Letter L (Leave) leaves the module MACRO source in | - options - Letter L (Leave) leaves the module MACRO source in default directory default directory default directory default directory | default directory | Any errors in module generation are reported as VMS exit status. Any errors in module generation are reported as VMS exit status. Any errors in module generation are reported as VMS exit status. Any errors in module generation are reported as VMS exit status. | Any errors in module generation are reported as VMS exit status. 20 VAX IMAGE BUILD TOOLS DESIGN DESCRIPTION 5.8 Usefull Hints 5.8 Usefull Hints 5.8 Usefull Hints 5.8 Usefull Hints | 5.8 Usefull Hints | Using VAX image build tools requires understanding of VAX Using VAX image build tools requires understanding of VAX Using VAX image build tools requires understanding of VAX Using VAX image build tools requires understanding of VAX | Using VAX image build tools requires understanding of VAX shareable image concepts. The following topics attempt to shareable image concepts. The following topics attempt to shareable image concepts. The following topics attempt to shareable image concepts. The following topics attempt to | shareable image concepts. The following topics attempt to address the most frequently asked questions: address the most frequently asked questions: address the most frequently asked questions: address the most frequently asked questions: | address the most frequently asked questions: | How do I find out names of all the commons in a new image? How do I find out names of all the commons in a new image? How do I find out names of all the commons in a new image? How do I find out names of all the commons in a new image? | How do I find out names of all the commons in a new image? | | Use IMGBLD (or MAKES7K, etc) and DO NOT list any GLOBAL nor LOCAL | data in control file. After the build you may scan resulting | image using IMGSCA programm. | How do I get a list of GLOBAL data (Commons) from existing image How do I get a list of GLOBAL data (Commons) from existing image How do I get a list of GLOBAL data (Commons) from existing image How do I get a list of GLOBAL data (Commons) from existing image | How do I get a list of GLOBAL data (Commons) from existing image ? ? ? ? | ? Use the IMGSCA programm: | $ RUN AT$SYSTEM:IMGSCA $ RUN AT$SYSTEM:IMGSCA $ RUN AT$SYSTEM:IMGSCA $ RUN AT$SYSTEM:IMGSCA | $ RUN AT$SYSTEM:IMGSCA imagepathname S2 TT: imagepathname S2 TT: imagepathname S2 TT: imagepathname S2 TT: | IMGSCA>imagepathname S2 TT: | | IMGSCA will list all the global data on your terminal (TT:). | | My LINK dies with "ATTEMPTED STORE LOCATION OUTSIDE IMAGE ..." My LINK dies with "ATTEMPTED STORE LOCATION OUTSIDE IMAGE ..." My LINK dies with "ATTEMPTED STORE LOCATION OUTSIDE IMAGE ..." My LINK dies with "ATTEMPTED STORE LOCATION OUTSIDE IMAGE ..." | My LINK dies with "ATTEMPTED STORE LOCATION OUTSIDE IMAGE ..." | | Build contains module with Fortran DATA statement which attempts | to intialize COMMON in one of shareable images referenced. You | have to investigate in which image this common and particular | module should be ... | I suspect my image uses other image commons without my knowledge I suspect my image uses other image commons without my knowledge I suspect my image uses other image commons without my knowledge I suspect my image uses other image commons without my knowledge | I suspect my image uses other image commons without my knowledge | | Remove (comment out) any GLOBAL=name definitions from control | file and use either IMGBLD or MAKES7K with added option "A" | (Analyze). Build process will not use global data definitions | from shareable images. Any common referenced by your image, but | present in on of shareable images will be reported as | "CONFLICTING ATTRIBUTES for PSECT name" by the LINKER. | 21 VAX IMAGE BUILD TOOLS CONSTRAINTS AND LIMITATIONS CONSTRAINTS AND LIMITATIONS CONSTRAINTS AND LIMITATIONS CONSTRAINTS AND LIMITATIONS CONSTRAINTS AND LIMITATIONS 6 CONSTRAINTS AND LIMITATIONS Control File Maintenance Control File Maintenance Control File Maintenance Control File Maintenance 6.1 Control File Maintenance The image build control file must be maintained to reflect any changes to the subsystem layout (new routines, old routines removal, global data names / sizes changes). Such changes should be discovered by the programmer updating the subsystem. However, mechanism must be set in place to propagate such changes to the build control file source control. | | | Dynamic Transfer Vector Generation Dynamic Transfer Vector Generation Dynamic Transfer Vector Generation Dynamic Transfer Vector Generation | 6.2 Dynamic Transfer Vector Generation | | The transfer vector generation is a separate step in product | build, not covered by the IMGGEN nor MAKExxx procedures. The | sub-system build control files merely assume dynamic transfer | vector is already present and up-to date. Thus, explicit | transfer vector generation using IMGXFR.COM must be a separate | step in product build. Limitations in Control File Syntax Limitations in Control File Syntax Limitations in Control File Syntax Limitations in Control File Syntax 6.3 Limitations in Control File Syntax The Control file defines all the object modules, object libraries and shareable images to be used in a particular image build. The VMS linker is extremely flexible in formats of module specification. To keep the control file processing fast and simple, only LIMITED subset of the VMS-LINKER acceptable specifiers may be used. For supported formats, see the Vax Image Build Control File in DATA STRUCTURES. Control file format as defined here is not fully upwards compatible with the format used by SHRGEN.COM facility (S7K 11.nn builds). Limited edit is required. Limitations in Image Compatibility Checking Limitations in Image Compatibility Checking Limitations in Image Compatibility Checking Limitations in Image Compatibility Checking 6.4 Limitations in Image Compatibility Checking The current compatibility checking does NOT check the entry point names sequence, assuming this will be maintained using the Control File. Checking may be implemented later, if necessary. 22 VAX IMAGE BUILD TOOLS NAMING CONVENTIONS NAMING CONVENTIONS NAMING CONVENTIONS NAMING CONVENTIONS NAMING CONVENTIONS 7 NAMING CONVENTIONS Resulting File Names Resulting File Names Resulting File Names Resulting File Names 7.1 Resulting File Names Generated files are always composed using: - Product or component name - Build identification (release, build number) - Filename extension rrbb rrbb rrbb rrbb productrrbb.type where types are defined as: .EXE .EXE .EXE .EXE - .EXE - shareable or executable image file .SHR .SHR .SHR .SHR - .SHR - stub (template) image file .MAP .MAP .MAP .MAP - .MAP - image map Temporary File Names Temporary File Names Temporary File Names Temporary File Names 7.2 Temporary File Names Temporary files are created in default directory using name in a form: productcode.ext where: codes are defined as: _OPT _OPT _OPT _OPT - _OPT - linker option file _VEC _VEC _VEC _VEC - _VEC - transfer vector module _GDS _GDS _GDS _GDS - _GDS - global data size definition module _XFR _XFR _XFR _XFR - _XFR - dynamic transfer vector module _RBL _RBL _RBL _RBL - _RBL - update control file for automatic rebuild types are defined as: .OPT .OPT .OPT .OPT - .OPT - linker option file .MAR .MAR .MAR .MAR - .MAR - MACRO-32 source file .OBJ .OBJ .OBJ .OBJ - .OBJ - object module created by MACRO compiler 23 VAX IMAGE BUILD TOOLS NAMING CONVENTIONS Tools External Names Tools External Names Tools External Names Tools External Names 7.3 Tools External Names Any external names (entry points, global data) used in the VMS image build tools must use the prefix: IMG IMG IMG IMG IMG Any entry point name is limited to 6 characters, including IMG Any global data name is limited to 6 characters, including IMG Tools Internal Names Tools Internal Names Tools Internal Names Tools Internal Names 7.4 Tools Internal Names Since the image build tools are VMS-specific, the naming restrictions are those of VMS languages. However, strict explicit declaration of every name is required. Any FORTRAN module MUST use the VMS specific IMPLICIT NONE statement. Tools Languages Tools Languages Tools Languages Tools Languages 7.5 Tools Languages According to build procedures functionality requirements, the user interface uses the DCL procedure. For performance sake, and where the task can not be accomplish via DCL, FORTRAN code is used, since FORTRAN provides an easiest interface to VMS system environment. The code sections working with VMS OBJECT LANGUAGE uses the VMS MACRO, in order to efficiently use bit manipulations. Also, VMS OBJECT LANGUAGE DEFINITIONS are not commonly available to FORTRAN. 24 VAX IMAGE BUILD TOOLS ROUTINES and FUNCTIONS ROUTINES and FUNCTIONS ROUTINES and FUNCTIONS ROUTINES and FUNCTIONS ROUTINES and FUNCTIONS 8 ROUTINES and FUNCTIONS The following AUOSI 11.nn VMS specific routine is used: SIMGLD SIMGLD SIMGLD SIMGLD SIMGLD - Dynamic Image Load. This routine has to be called by the dynamic transfer vector only, NEVER by the application. The following top level DCL procedures are provided: | o IMGBLD.COM - Generic VMS Image build procedure. o IMGCHK.COM - Image compatibility checking procedure. o MAKES7K.COM - Image build procedure for S7K TEST image build o MAKES5K.COM - Image build procedure for S5K TEST image build The following utility programs / tools are used: o IMGGEN.EXE - Build support files generator. Processes the build control file(s) and creates files necessary for the build. o IMGSCA.EXE - Image scanner. Analyzes shareable image GST table, giving information about any global data sections and entry points. The following modules are used: o IMGGEN - IMGGEN root. Command parsing, general control o IMGSCA - IMGSCA root. Command parsing, general control o IMGOPN - Open the image file to map into memory o IMGSIG - Signal error messages o IMGGST - Global Symbol Table analyzer module (MACRO) o IMGCTL - Access and pre-process Control File record o IMGPRS - Parse and process the Control File record o IMGSHR - Access, Map and process shareable image GSD o IMGCOM - Generate the Global Data Size module (commons) o IMGVEC - Generate the TRANSFER VECTOR module file o IMGXFR - Generate the DYNAMIC TRANSFER VECTOR module file o IMGOPT - Generate the LINKER OPTION file o IMGPLL - Parse VAX LINKER format line o IMGRMF - Remove module file definition from table 25 VAX IMAGE BUILD TOOLS ROUTINES and FUNCTIONS The following global data are used: o IMGCOM - Argument transfer among IMGOPN and IMGMAP The following modules define local data structures: o IMGPAR.INC - Parameter file, defines local data sizes o IMGDAT.INC - Fortran Structures definitions o IMGCOM.INC - IMGCOM common declaration 26 VAX IMAGE BUILD TOOLS DATA STRUCTURES DATA STRUCTURES DATA STRUCTURES DATA STRUCTURES DATA STRUCTURES 9 DATA STRUCTURES VMS Image Build Control File VMS Image Build Control File VMS Image Build Control File VMS Image Build Control File 9.1 VMS Image Build Control File The major data structure used by the image build software is the Image Build Control File. It may contain comments (mandatory comment is a standard header including history log), and any combination of supported IMGGEN commands. Comments are recognized by the "!" character, and may appear either in column one, or at the end of any valid command. Some of the control file command are intended for use in the update CTL file only, i.e. in a file which is used by the "maketest" procedure to update / modify the standard CTL file. Control file commands Control file commands Control file commands Control file commands Control file commands CLUSTER CLUSTER CLUSTER CLUSTER * CLUSTER=name Forces all the subsequent modules (FILE=) into a named cluster. If CLUSTER= is not used, or cluster name is empty, standard VMS LINKER DEFAULT_CLUSTER is used. FILE=pathname FILE=pathname FILE=pathname FILE=pathname * FILE=pathname defines modules and/or libraries to use in the image build. FILE command is position dependent - any modules specified are collected into currently opened image cluster (or DEFAULT_CLUSTER, if none). Any modules specified in the update CTL file are checked against already defined modules table, and replace previous definition of such a module using the current cluster. Supported formats are: - FILE=pathname/SHARE - FILE=pathname/LIB - FILE=pathname/INC=module - FILE=pathname/INC=(module,module) - FILE=pathname Continuation lines are NOT supported. Always use LOGICAL names to specify libraries, shareable images or directories containing explicit modules. NOTE, any shareable image specified will be scanned for global data (unless Analyze option is used). Any global data found in shareable image override the definition in the CTL and update files. 27 VAX IMAGE BUILD TOOLS DATA STRUCTURES ENTRY ENTRY ENTRY ENTRY * ENTRY=name,sequence Defines the entry point name, to be used for - Linker UNIVERSAL=name option, to make shareable image entry accessible to callers - Shareable image transfer vector module entry - Dynamic image load transfer vector module entry The sequence number is required to maintain the entry point sequence (for compatibility reasons). Should any entry point become obsolete, use ENTRY=OBSOLETE,number. The IMGGEN will generate a dummy (return only) entry in the transfer vector table. In an update CTL file, any entry sequence numbers are ignored. Additional entry points are simply added at the end of the transfer vector table. NOENTRY NOENTRY NOENTRY NOENTRY * NOENTRY=name (update CTL file only) cancels the existing ENTRY (defined in standard CTL file). The transfer vector entry for such module will be replaced with a RET instruction. TABSZ TABSZ TABSZ TABSZ * TABSZ=nnn Prescribes the transfer vector table size (entries) for images with upwards compatibility requirements. The fixed size of the transfer vector table will guarantee position of the image GLOBALDATA cluster, which follows the TRANSFER_VECTOR cluster. Any unused transfer vector entries will be loaded with a RET instruction. LOCAL LOCAL LOCAL LOCAL * LOCAL=name Defines named data (global data, Fortran common) to become LOCAL to image cluster. LOCAL=name can NOT be used for data used by modules explicitly forced into different image clusters. LOCAL data will be allocated in the cluster with a first module referencing such data. LOCAL data are invisible to shareable image caller. NOTE, any Fortran COMMONS or VAX-C global data must be defined either as LOCAL or GLOBAL to satisfy image shareability requirements. GLOBAL GLOBAL GLOBAL GLOBAL * GLOBAL=name[,size] or COMMON COMMON COMMON COMMON COMMON=name[,size] (for compatibility with SHRGEN) Defines global data name [and size]. Defined data become global, accessible to shareable image caller(s). The size should be used for shareable image where upwards compatibility is required. If size is specified, IMGGEN will generate a module with requested global data size declaration, and use it in image build. Any global data listed in GLOBAL=name will be forced into image cluster GLOBAL_DATA, which follows the transfer vector cluster TRANSFER_VECTOR. 28 VAX IMAGE BUILD TOOLS DATA STRUCTURES OPTION OPTION OPTION OPTION * OPTION=linker-option,par,par.... Defines any explicit VMS linker option required to build an image. In the update CTL file, the unique options will supersede those specified in a standard CTL file. NOTE, for shareable images use OPTION=GSMATCH=LEQ,majid,minid as a cornerstone for image compatibility tracing. This option must be used in the link of the shareable image (typically CORE) referenced in builds of any other images. GSMATCH is not necessary for dynamically loaded images. Images with the same "majid" and increasing "minid" are considered upwards compatible. Change in "majid" flags loss of compatibility. IMAGE IMAGE IMAGE IMAGE * IMAGE=name,error_routine Image LOGICAL name for a dynamic shareable image load transfer vector. Image name is used only in the dynamic transfer vector build, if not specified, defaults to the control file name (name portion). Error_routine is the name (entry point) of a routine to be called in case of dynamic load error. If empty, standard VMS exception will be generated. @pathname @pathname @pathname @pathname * @pathname[/nosize] This invokes the indirect (nested) CTL file. The /NOSIZE qualifier forces processing to ignore any global data sizes defined in any GLOBAL=name,size statements within a nested file. Default pathname is .CTL;0 29 VAX IMAGE BUILD TOOLS DATA STRUCTURES Global Data Description File Global Data Description File Global Data Description File Global Data Description File 9.2 Global Data Description File The global data description file is generated by the IMGSCA program. Defines all the shareable image global data sections, sizes, position in the image (starting offset) and section attributes. Special separators are used to make use of the DCL DIFFERENCE "ignore comments" facility. NOTE, the IMGSCA programm may generate also limited output formats. 1 2 3 4 5 6 7 123456789012345678901234567890123456789012345678901234567890123456789012 COMMON=CAPSCREW_DATA ,00002906 ! VAL=0000350C FLG:019D COMMON=CCCSET ,00000001 ! VAL=00004068 FLG:019D | | | | global data name size starting addr flags (1-32 characters) (decimal) (hexadecimal) (hex) Except for global data explicitly forced into named cluster, global data always appear in order sorted (ascending) by name - the way VMS linker loads named PSECTs into image. Logical Names Definition File Logical Names Definition File Logical Names Definition File Logical Names Definition File 9.3 Logical Names Definition File Logical names definition file supplies the IMGGEN procedure with all the logicals necessary during the link process. The logical names order is important, since logical names defined later may override logical names specified earlier. A single record defines one logical name, comments are allowed using exclamation point in column 1 or at the pathname end: ! This is a comment line masterlib>LIB_DISK:[proddir]MASTER.OLB ! Master | | | | logical delimiter pathname comment name NOTE NOTE NOTE NOTE NOTE: For increased flexibility, VMS logical names should be used for any pathnames used during the build. Also, image structuring into subsystems should be reflected at the object module library level, using a single object module library per subsystem, and also a single object module library logical name per subsystem. 30 VAX IMAGE BUILD TOOLS ERROR-EXCEPTION HANDLING ERROR-EXCEPTION HANDLING ERROR-EXCEPTION HANDLING ERROR-EXCEPTION HANDLING ERROR-EXCEPTION HANDLING 10 ERROR-EXCEPTION HANDLING Any errors encountered in the VMS image build process are reported using standard VMS "full" error message syntax, even though not always generated by the VMS message facility. Any non VMS system component returns appropriate VMS severity value, with the DCL "suppress message" status bit set ON. %FAC-X-IDENT, Description %FAC-X-IDENT, Description %FAC-X-IDENT, Description %FAC-X-IDENT, Description %FAC-X-IDENT, Description Severity codes (X) used are: I I I I * I - X'00000001 information (success otherwise) W W W W * W - X'10000003 warning (possible error, process continues) E E E E * E - X'10000002 error F F F F * F - X'10000004 fatal error (part) of process failed 31 APPENDIX A SHAREABLE IMAGE LAYOUT SHAREABLE IMAGE LAYOUT SHAREABLE IMAGE LAYOUT SHAREABLE IMAGE LAYOUT SHAREABLE IMAGE LAYOUT A-1 SHAREABLE IMAGE LAYOUT SHAREABLE IMAGE LAYOUT SHAREABLE IMAGE LAYOUT SHAREABLE IMAGE LAYOUT SHAREABLE IMAGE LAYOUT Using the tools described in this functional specification results in a standardized (shareable) image layout. Some items (clusters) will be missing in some images, depending on build requirements. _________________ 0000000 | TRANSFER_VECTOR | Transfer Vector Entry Points | | | | Block of RET statements up to 8*TABSZ |_________________| 8*TABSZ | GLOBAL_DATA | Global Data Sections | | (alphabetically sorted by name) |_________________| | NAMED_CLUSTER_1 | User defined cluster (if any) |_________________| | NAMED_CLUSTER_2 | User defined cluster (if any) |_________________| | DEFAULT_CLUSTER | Default cluster, typically contains | | program sections: | | $AAAXFR - dynamic transfer vectors | | $CODE - Fortran, C code | | $LOCAL - local R/W data | | $PDATA - local readonly data | | data declared as LOCAL | | |_________________| | | Image Fixup Vectors |_________________| (created by the LINKER) NOTE, the disk image file layout is DIFFERENT to that of image layout in memory. The image file contains: - Image Header with basic image information and image section descriptors. - Image sections to be directly mapped into virtual memory - Debugger symbol table (debug image only) - Global symbol table (shareable image only) Imge file does NOT contain image sections for DEMAND ZERO DATA, t.e. sections which may be created at the image activation, using the image section descriptor in image header (such sections are mapped into a page file). Typically, most of the Fortran COMMONs and module local data result in DEMAND ZERO SECTION creation. A-2 APPENDIX B IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE B-1 IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE ! DEMOCORE.CTL - DEMO CORE Example ! ############################################################### ! # (C) Copyright 1985 Auto-trol Technology Corporation # ! # # ! # This program is the sole property of Auto-trol Technology # ! # Corporation and is considered a trade secret and/or a # ! # proprietary product of Auto-trol Technology Corporation. # ! # Use or disclosure of this program by other than Auto-trol # ! # Technology Corporation and its assigned licensees and # ! # customers is strictly forbidden by law. # ! # # ! # Use, duplication or disclosure by the Government is subject # ! # to restrictions as set forth in subdivision (b)(3)(ii) of # ! # the Rights in Technical Data and Computer Software clause # ! # at 252.227.7013. # ! ############################################################### ! /BEGIN MODULE HEADER/ /STANDARD MODULE HEADER/ ! ! NAME -- DEMOCORE.CTL ! ! PURPOSE -- ! Example of the Control file for VAX DEMO CORE ! shareable image build. ! ! HISTORY -- ! 03/18/86,,,MXB, Initial definition ! ! /END MODULE HEADER/ /STANDARD MODULE HEADER/ ! ############################################################### ! ! The CORE major ID has to be changed either if any entry ! points are added to core, or any global data are modified. ! OPTION=GSMAT=LEQ,11,25 ! CORE global data are used by APPLICATIONs ! GSMATCH guards against incompatible image use. OPTION=DZRO_MIN=100 ! Reduce the Image Sections count OPTION=UNSUP=1 ! Allow DZRO compression for shareable image ! ! The following FILE section defines all the modules and libraries ! loaded into DEFAULT_CLUSTER. ! FILE=DEMO_AUOSI_SHR/SHARE ! DEMO Auosi shareable image FILE=DEMO_CORE_LIB/LIB ! DEMO Core modules library ! FILE=DEMO_XFER_LIB/INCLUDE=(DEMOAPPL_XFR) ! APPLICATIONS transfer vector FILE=DEMO_XFER_LIB/INCLUDE=(DEMOBEZI_XFR) ! BEZIER transfer vector ! FILE=DEMO_CORE_LIB/INCLUDE=PDBLCK ! Data initialization modules FILE=DEMO_CORE_LIB/INCLUDE=NCAPTTBL B-2 IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE IMAGE BUILD CONTROL FILE ! RECRSV cluster contains all routines called recursively: ! CLUSTER=RECRSV FILE=DEMO_CORE_LIB/INCLUDE=QRCBEG FILE=DEMO_CORE_LIB/INCLUDE=ECPID FILE=DEMO_CORE_LIB/INCLUDE=JG07 ! ! MACROS cluster keeps frequently called routines together ! CLUSTER=MACROS FILE=DEMO_CORE_LIB/INCLUDE=QSTART FILE=DEMO_CORE_LIB/INCLUDE=WSARIO FILE=DEMO_CORE_LIB/INCLUDE=QEND ! ! The following list defines all the globally accessible CORE data, ! to be collected in the GLOBAL_DATA cluster, giving size in bytes ! to enforce data compatibility: ! GLOBAL=ADVDP ,00000154 ! GLOBAL=APLSVI ,00000016 ! GLOBAL=BLKGPX ,00000020 ! GLOBAL=BZASC ,00000012 ! ! ! The following list defines all the CORE data to become LOCAL ! to the CORE image. NOTE, such data must be referenced within ! a single image cluster only: ! LOCAL=DYNFGA LOCAL=DYNFIG LOCAL=EDCOM ! ! To guarantee the position of the GLOBAL_DATA cluster, the ! transfer vector table must have fixed length between releases. ! Allocated 1 page, giving maximum of 512/8=64 entries ! TABSZ=512 ! Required transfer vector table size ! ! Following is the list of DEMO CORE entry points: ! IMAGE=DEMO_CORE,DEMERR ! SHR image logical name, load error handler ! ENTRY=AD2000 ,1 ! Main DEMOCORE entry point ENTRY=AIAAD ,2 ! AI routines ENTRY=AIAADM ,3 ! ENTRY=AIAATT ,4 ! ENTRY=AIAAUD ,5 ! ENTRY=AIABCF ,6 ! ! ! Finish B-3 APPENDIX C DYNAMIC TRANSFER VECTOR MODULE DYNAMIC TRANSFER VECTOR MODULE DYNAMIC TRANSFER VECTOR MODULE DYNAMIC TRANSFER VECTOR MODULE DYNAMIC TRANSFER VECTOR MODULE C-1 DYNAMIC TRANSFER VECTOR MODULE DYNAMIC TRANSFER VECTOR MODULE DYNAMIC TRANSFER VECTOR MODULE DYNAMIC TRANSFER VECTOR MODULE DYNAMIC TRANSFER VECTOR MODULE .TITLE DEMOAPPL_XFR Transfer vector module .IDENT /0101/ ;+ ; (C) Auto-trol Technology Corporation 1987 ; ; This module contains the Dynamic Transfer Vector ; transfering calls to DEMO_APPL ; ; Created 13-FEB-87 10:14:25 ; by CHICO::BRUNECKY ; from file DRA1:[BRUNECKY.IMG]DEMOAPPL.CTL;4 ; using IMGGEN 0101 ;- ; .MACRO DYNXFER,modnam,?l1,?l2,?l3 .ALIGN LONG ; Longword aligned .ENTRY modnam,^M; Entry mask to replace JSB G^SIMGLD+2 ; JSB to replace by JMP l1: .WORD USRERR-l1+8 ; Offset to ERR adr .BYTE l3-l2 ; Entry name length l2: .ASCII /modnam/ ; Entry name l3: .ENDM ; ; Our transfer vectors use a very specific Psect: ; Non shareable, writeable, PIC instructions ; .PSECT $AAAXFR,PIC,CON,REL,LCL,NOSHR,EXE,RD,WRT,LONG ; USRERR: .ADDRESS ILDERR ; Load error handler routine IMGNAM: .ASCID %DEMO_APPL% ; Shareable image logical name ; DYNXFER APPL01 ; Entry APPL01 DYNXFER APPL02 ; Entry APPL02 DYNXFER APPL03 ; Entry APPL03 DYNXFER APPL04 ; Entry APPL04 ; .END C-2 APPENDIX D MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE D-1 MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE CHICO> type mymod.for ! Test module with new common Subroutine MYMOD(IDAT) COMMON/NEW_INT/I COMMON/NEW_REA/R R=I+IDAT Return End CHICO> for/debug/noopt mymod.for CHICO> dir *corex*.exe ! Private core used for testing Directory DRA1:[USER.S7K] S7KCOREXTEST.EXE;1 CHICO> @makes7k *MAKES7K, S7K component to build [or CTL file pathname]: sgri *MAKES7K, Enter update CTL file [def=prompt for modules]: %MAKES7K-I-NEWUPD, Creating update file DRA1:[USER.S7K]S7KSGRIXTEST_UPD.CTL;2 *MAKES7K, Enter update object module pathname [none=end]: MYMOD.TMP %MAKES7K-E-NOXMOD, Nonexistent module *MAKES7K, Enter update object module pathname [none=end]: MYMOD *MAKES7K, Enter update object module pathname [none=end]: *MAKES7K, Enter option combination (SRDMFC) [default=SRD]: *MAKES7K, Enter reference build ident or NONE [def=1124]: *MAKES7K, Enter CORE to use [def=DRC2:[GSYS]S7KCOREX1124.EXE;1]: S7KCOREXTEST *MAKES7K, Enter log. names file [def=DRA1:[USER.S7K]S7KX1124.LNM]: %MAKES7K-I-NEWLNM, Temp. logical names file created: DRA1:[USER.S7K]S7KSGRIXTEST_LNM.TMP;3 Job IMGGEN (queue S7KQUE, entry 431) started on S7KQUE Job IMGGEN (queue S7KQUE, entry 431) completed CHICO> CHICO> type imggen_s7ksgrix.log $ SET NOVERIFY %IMGBLD-I-STARTT, Starting at 26-FEB-1987 11:56:52.96 %IMGBLD-I-BLDFIL, Building support files for S7KSGRIX build TEST %IMGBLD-I-BLDFIL, Building image files for S7KSGRIX build TEST %LINK-W-WRNERS, compilation warnings in module SIVWIN file DRC2:[GRI.LIB]S7KGRI.OLB;1 %IMGBLD-I-BLDCHK, Build results checking for S7KSGRIX build TEST %IMGGEN-E-SHRSEC, shareable writeable PSECT NEW_INT %IMGGEN-E-SHRSEC, shareable writeable PSECT NEW_REA %IMGBLD-W-NEWUPD, New update CTL file created: DRA1:[USER.S7K]S7KSGRIX_RBL.CTL;2 %IMGBLD-W-IREBLD, Rebuilding image with added SPSECT definition %IMGBLD-I-BLDFIL, Building support files for S7KSGRIX build TEST %IMGBLD-I-BLDFIL, Building image files for S7KSGRIX build TEST %LINK-W-WRNERS, compilation warnings in module SIVWIN file DRC2:[GRI.LIB]S7KGRI.OLB;1 %IMGBLD-I-BLDCHK, Build results checking for S7KSGRIX build TEST %IMGBLD-I-FINISH, Terminated at 26-FEB-1987 11:58:31.12 USER job terminated at 26-FEB-1987 11:58:31.33 CHICO> CHICO> type s7ksgrix_rbl.ctl ! Update file modified by IMGBLD GLOBAL=NEW_INT D-2 MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE MAKES7K USE EXAMPLE GLOBAL=NEW_REA FILE=DRA1:[USER.S7K]MYMOD.OBJ;2 ! Update module, entered by MAKES7K CHICO> D-3