IBM OBJECT MODULE UTILITIES 1 USING THE UTILITIES 1.1 CONVERTING A FILE 1.2 INVOKING THE CONVERTER ROUTINE 1.3 DUMPING AN OBJECT MODULE 1.4 LOADING THE MODULES 2 OVERVIEW OF CONVERTER ACTIONS 2.1 COALESCING AREAS 2.2 ESD DICTIONARY 2.3 GENERATION OF AREAS 2.4 INITIALISATION DATA 2.5 RELOCATION PROCESSING 2.6 END CARD 3 BUILDING THE UTILITIES 1 USING THE UTILITIES ------------------- 1.1 CONVERTING A FILE ----------------- The command TOIBMOBJ is used to convert a standard EMAS object file into the standard IBM object module format. The normal format of a call is TOIBMOBJ(emasobj,ibmobj,listing) The standard object file in 'emasobj' is converted into IBM format and stored in the file 'ibmobj'. If 'ibmobj'is not specified then the converted file is stored in the file 'emasobj'. If 'listing' is not specified then the listing is sent to .OUT. The IBM standard object format only allows a maximum of 8 characters for a name. The converter therefore has to truncate all data and procedure names to 8 characters . The converter generates a warning for each name which is truncated and an error if it detects any duplicate names. An error is also reported if any addresses or offsets require more than 24 bits since the IBM object module format only supports 24 bits. If any errors are reported then the object file is not converted. The converter will fix up any references it can and suppresses the unnecessary external references. References to common are never suppressed to ensure that the correct length of common block is created on loading. To enable the IBM loader to fix up procedure references the converter has to generate three external names for each prcedure name. The name of the head of GLA for the procedure is obtained by forcing the first character of the name to be lowercase. The name of the head of code for the procedure is obtained by forcing the third character of the name to be lowercase. If there are less than three characters in the name then an @ is appended to the name to get the head of code name. The procedure name itself names the entry point for the procedure in the code. Any single word (code or data) references in the input file cannot be converted as it is not known whether they should be fixed up as code or data. An error is reported if any such single word references are present. The generated file uses a standard character file header and the body of the file consists of a sequence of 80 byte records using the standard IBM object module formats. 1.2 INVOKING THE CONVERTER ROUTINE ------------------------------ The routine CONVTOIBM can be invoked to convert a connected file and has the specification below %EXTERNALROUTINESPEC CONVTOIBM(%INTEGER IFILE,OFILE,%INTEGERNAME FLAG) where IFILE is the connection address for the file to be converted. OFILE is the connection address for the file which is to receive the converted file.This file should be made sufficiently large to hold the converted module. The output file should be at least (input file size*80)//56 bytes to allow for the overheads with the IBM format. FLAG This will be set non-zero if any errors are detected (e.g. duplicate names) and will be zero if only warnings are generated. The values are 0 at most warnings 1 duplicate names generated 2 more than 24 bits required 3 unable to create workspace All messages are sent to the current selcted output channel. Some error conditions (internal consistency check fails) will cause the routine to %STOP. 1.3 DUMPING AN OBJECT MODULE ------------------------ The contents of the generated file can be examined by the utility IBMDUMP which decodes the file and produces an analysis of the file contents. The utility is called by IBMDUMP ibmobj,listing The IBM object module file 'ibmobj' is dumped and the listing is sent to the file 'listing'. If 'listing' is not specified then it defaults to .OUT. The utility expands the records into a more readable format and uses the names for areas rather than the ESD id's. The utility provides the ESD identifier, name,ESD type and all relevant fields in hex for each ESD entry. A maximum of 226 bytes of the TXT of each csect is dumped if the listing is to .OUT. Each RLD entry is represented useing the format csect_name+hex_offset dc v(hex_const+ext_name) where hex_const is the contents of the store location being relocated. Any specified entry point and/or length in the END card is reported. The utility should work correctly with all files generated by TOIBMOBJ but may not cope with all object module files. 1.4 LOADING THE MODULES ------------------- The utility IBMLOAD can be used to link and load a set of IBM object modules into a segment for use with the 360 simulator. The loader is called by IBMLOAD listing,entry,stack length The first parameter specifies where the output is to be sent and it defaults to .OUT. The second parameter can be used to specify the name of the entry point to the loaded program. This entry point is only used if there is no procedure entry point specified on an END card in any of the loaded modules. The third parameter specifies the stack length to be used and defaults to 8096 bytes. The utility first prompts (SEGMENT:) for the name of the file for the segment which will hold the loaded program. It then prompts (FILE:) for the names of the input object module files which are to be loaded. This list of input files is terminated by a response of .END. The utility is capable of loading the object modules generated by TOIBMOBJ but may not load all IBM object modules. The main restrictions are 1) It assumes that each SD specifies its length in the ESD entry. 2) That the SD entry which is home for an LD occurs before the LD entry in the ESD. 3) All relocations are treated as full word relocations. The segment generated by the loader has the following format bytes use 0- &1F Header for file &20- &5F Contents of general registers 0 to 15 at start up. Register 14 is assumed to contain the entry point address, with GR11 the stack pointer, GR12 head of code for entry pt, GR13 head of GLA for the entry pt. &60 Start address of code area i.e. area that instructions can be fetched from.. &64 Length of code area. &68 Start of GLA i.e. read/write area. &6C Length of GLA. &70 Start of stack area. &74 Length of stack. &100 If I#STKTOP is not declared then this word is defined by the loader to be it. &104-&FFF Are used to hold invalid opcodes and all undefined references are pointed to one of these word. &1000- Holds the code,GLA etc and the stack whichis placed after all the loaded modules. Any refences which have not been resolved by the input modules are finally checked to see if they can be linked up with the routines the IBM simulator provides. The loader provides the link to each of the routines listed below if they are not already resolved. S#NDIAG S#IOCP S#STOP S#WRITE S#PRINT S#PHEX S#IEXP S#ILOG S#ISQRT S#PRINTF S#SUBSTR S#READ PROMPT RDFILEAD NWFILEAS The loader always produces a symbol table which reports the address that all external symbols have been loaded at. Any unresolved references are marked with an *. 2 OVERVIEW OF CONVERTER ACTIONS ----------------------------- 2.1 COALESCING AREAS ---------------- All the input areas must be converted into a single SD except for any initialised common areas. INITCMN has to be treated separately as each named common area which has been initialised has to be mapped into a separate SD, to enable the IBM loader to deal with it as common correctly. Areas 1-5 and 7 are coalesced into a single SD in that order, each sub-areais aligned on a quadruple word boundary to ensure alignment is correct. Area 6 (INITCMN) is split into its constituent named comon blocks (i.e. SD's). The array BASEOF(1:7) is set up to give the offsets of each of the sub-areas in the coalesced area (area 6 is tacked on behind the rest even though it is logically separate SD's). 2.2 ESD DICTIONARY -------------- The next step is to build the ESD dictionary for the output module, the entries for the dictionary are built from a) each procedure entry b) each data entry c) each procedure reference d) each data reference Since we are only generating one SD (apart from INITCMN) we need to determine the name of the csect and map all other entries as LD (i.e. entry points within a csect). The name of the csect has to be matched to byte 0 of the csect since it would otherwise look as if each module had a PC at the start and this would cause errors when loading or linking modules. The name for the csect is given by the following rules:- 1)The first entry name which corresponds to byte 0 of the code area if there is one. 2)Failing that it is the name of the head of code corresponding to the entry pt nearest the start of the combined area . 3)If there are no entry points or the name from step 2 is already used then the name is taken to be @UNKNOWN. Each entry or reference is treated as described below:- a) Procedure entry or reference Each entry point requires us to generate three ESD entries An esd entry for the head of the code (as seen by compiler), the name being the entry pt name prefixed by @,and pointing to start of SD. An esd entry for the head of GLA (as seen by compiler), the name being the entry pt name prefixed by #, and pointing to start of GLA. An esd entry for the entry pt in the code, the name being the entry pt name itself. These three entries are used to set up the 'descriptor' for the entry pt in any module which references the entry pt. All the entries are LD's for entry pts and ER's for references. b) Data entry or references Each data entry requires a single LD entry in the ESD and a data reference requires a single ER entry in the ESD. If the data entry lies in INITCMN however the entry is mapped to an SD since it has to be treated as a separate csect. Similarly a data reference to a common block must be mapped to a CM entry rather than an ER. We must also keep enough information in our ESD dictionary to enable us to resolve any procedure references which point to within the module. We cannot leave it to the IBM loader to fix these up as all entry pts are LD's and so cannot be referenced from the RLD. Such resolveable references are fixed up as internal relocation requests and are not inserted in from the ESD as ER's. Any references will not be fixed up but will always be left to the IBM loader. 2.3 GENERATION OF AREAS ------------------- The contents of areas 1,2,3,4,5 and 7 are all generated as being coalesced into SD number 1 in that order. The ESD list is then scanned and the contents of each named common block in area 7 (init cmn) are writen out as a separate SD. Each SD is written out as a contiguous sequence of TXT records with no gaps in the body of each SD. To enable subsequent steps to manipulate the memory image the address of the first TXT card for each SD is stored in the ESD entry for the csect. The map ADDRESS provides access to the byte specified by any valid ESD identifier and offset within the corresponding csect. Only bytes can be addressed in this way since two logically adjacent bytes might in fact be on two separate TXT cards. The routine FIND ID is used to map the (area,offset) pair into an (csect identifier,csect offset) pair which can then be used by ADDRESS. Any area but 6 is in csect 1 and the mapping is very simple. Any references to area 6 (i.e. init cmn) have to be treated differently since this area is split up into separate csects (one for each named common block). The routine returns the csect for which the csect offset is minimised. 2.4 INITIALISATION DATA ------------------- The initialisation requests are applied before any processing is done of the relocation requests. 2.5 RELOCATION PROCESSING --------------------- Each of the relocation requests are mapped into a standard RLD entry. After generating the RLD entries to map the relocation requests, the RLD entries to provide access to external proedures and data are built up. If any references can be fixed up internally they are fixed up as internal rather then external relocation. References to common data are however left to be resolved by the loader to ensure that the length of common blocks is correct when loaded. 2.6 END CARD -------- The first main entry point (if any) in the input module is marked on the END card as the entry point to the module. 3 BUILDING THE UTILITIES ---------------------- The source and object files for the utilities consist of Source Object ------ ------ SIBMDRIVER IBMDRIVER SCONVTOIBM CONVTOIBM SGENOBJ GENOBJ SIBMNAME IBMNAME SIBMDUMP IBMDUMP SIBMLOAD IBMLOAD The three object files IBMDRIVER,CONVTOIBM,GENOBJ are linked to create the object file TOIBMOBJ. Both IBMLOAD and TOIBMOBJ use the common module IBMNAME to convert an EMAS name into its equivalent IBM name as descibed above.