, 00002000 THE PENNSYLVANIA STATE UNIVERSITY 00004000 Computation Center 00006000 00008000 CONTRIBUTED PROGRAM 00010000 Contributor: John R. Mashey, Computer Science Dept. 00012000 00014000 360 ASSEMBLER LANGUAGE XMACRO PACKAGE 00016000 Program: July 1970(V.4.0), Jan. 1973 (V.5.0) Writeup: Jan. 1973 00018000 00020000 XMACRO PACKAGE - SUMMARY,IMPLEMENTATION, SYSTEM GENERATION00022000 00024000 PURPOSE 00026000 This writeup is provided to summarize the characteristics and00028000 facilities of the XMACRO PACKAGE, and enable a system programmer to00030000 add the macros and subroutines to a system. 00032000 00034000 INTRODUCTION 00036000 The XMACRO package is a system of macro definitions and assembler00038000 subprograms which together offer a number of useful facilities to the00040000 assembler language programmer. In general, the parts of the system00042000 have been written following these design considerations: 00044000 ERROR-PROOF - the programs supply a great deal of error checking,00046000 and also make assumptions where required. The macros are particularly00048000 notable for the fact that they do not disturb registers or condition00050000 code, and so can normally be used almost anywhere. 00052000 SIMPLICITY - the programs are designed with many default options,00054000 and generally require as little information from the programmer as00056000 possible. 00058000 FLEXIBILITY - the programs attempt to supply many options which00060000 are not required, but can be used to good advantage by the sophisticated00062000 programmer. The design generally allows students to use the macros00064000 effectively over a period of increasing knowledge. 00066000 00068000 ***NOTE*** AT THE CURRENT TIME, ALL OF THESE MACROS ARE SUPPORTED00070000 UNDER OS/360 AND EQUIVALENT SYSTEMS. Some of the macros can be used in00072000 any systems, since they have no system-dependent code. The ones which00074000 perform I/O may require modifications to run under DOS or other systems.00076000 00078000 The various macro definitions included in the system generally00080000 fall into several different categories, which are as follows:00082000 00084000 1. DEBUGGING macros. 00086000 XSNAP provides dumping of registers and storage, and permits 00088000 the output to be produced or not, depending on both assembly-time00090000 and execution-time tests. XDUMP is a simpler version of XSNAP,00092000 provided mainly for compatibility with ASSIST. XSTOP supplies a00094000 simple way to control infinite loops in programs. 00096000 00098000 2. INPUT-OUTPUT macros. 00100000 XPNCH, XPRNT, XREAD offer simple procedures for performing the00102000 input-output operations for card punch, line printer, and card00104000 reader. A single macro call suffices for each operation, thus00106000 requiring no OPEN's, DCB's, etc, and little extra JCL is needed.00108000 XGET and XPUT allow more flexibility, providing the ability to give00110000 dynamically for each call the file to be referenced. Thus, these00112000 macros can support tape, disk, drum I/O besides unit-record I/O.00114000 00116000 , 00118000 XMSYSGEN-2 00120000 00122000 3. SUBROUTINE LINKAGE macros. 00124000 XSAVE and XRETURN generate standard OS/360 subroutine entry 00126000 and exit code, like the SAVE and RETURN macros, but offering many00128000 additional services. These include printing trace messages on00130000 subroutine entry/exit, setting up base registers, and generating00132000 save areas. 00134000 00136000 4. DECIMAL CONVERSION macros 00138000 XDECI allows the user to perform free-format conversion of 00140000 decimal characters strings. A single call of XDECI scans for a00142000 decimal number, ignoring leading blanks, converts the value to00144000 binary, places it in a register, and also supplies a scan pointer00146000 to the end of the string, allowing for multiple numbers on an00148000 input card, for example. XDECO converts a binary register value00150000 to edited decimal form, suitable for later output. 00152000 00154000 5. HEXADECIMAL CONVERSION macros 00156000 XHEXI AND XHEXO perform the same conversions as XDECI and 00158000 XDECO, except the input string used by XHEXI contains hexadecimal00160000 numbers. Also with XHEXO, a register's contents may be printed00162000 out in hexadecimal form. 00164000 00166000 6. GENERATION CONTROL macro 00168000 The macro XSET can be used to suppress generation of many of 00170000 the other XMACROs. This permits debugging code to remain in a00172000 program, but suppressed for a production program. XSNAP, XSTOP,00174000 and the I/O macros can be eliminated entirely, and the trace code00176000 supplied by XSAVE and XRETURN can be removed. 00178000 00180000 7. REGISTER EQUATE macro 00182000 EQUREGS can be used to generate set(s) of register equate 00184000 symbols. Although it is not an integral part of the XMACRO system,00186000 it is included because the XMACROs generally allow equate symbols00188000 to be used to indicate registers. 00190000 00192000 8. MISCELLANEOUS SUPPORT macros 00194000 Various macros are used directly or indirectly by the macros 00196000 listed above. XCHAR permits right-end substring extraction with00198000 safety. XIDENT is used by XSAVE to create any identifier code00200000 needed at entry points. XIOGN is used to generate the supporting00202000 control sections for the I/O macros, and can be called to create00204000 new or different I/O modules tailored to the requirements of a00206000 given installation. XIONR is called by the I/O macros to generate00208000 a data block and call to the appropriate I/O module. XLOOK is used00210000 to look up one operand in a list, and is utilized by many of the00212000 other macros for decoding operands. XMUSE aids XSAVE in setting00214000 up USINGs, and XSRNR is used to generate register save/restore00216000 code for XSAVE and XRETURN. Finally, XSRTR creates trace and00218000 register dumping code when needed by XSAVE and XRETURN. 00220000 XGPGEN, XXGPSRCH are used for generation of XGET/XPUT support. 00222000 00224000 9. ASSIST COMPATIBILITY macros 00226000 A number of the macros above are used to allow ASSIST programs00228000 to be run as is under the system directly. In addition to the00230000 XLIMD macro, which is supplied for compatibility only and creates00232000 no code, the macros required are XDECI, XDECO, XDUMP, XGET, XHEXI,00234000 XHEXO, XPRNT, XPUT, XREAD, and all their inner macros. 00236000 , 00238000 XMSYSGEN-3 00240000 MACRO SUMMARY TABLE 00242000 Macro Flags Code Uses | Macros Calls Module 00244000 Name Size(dec) Macros | Used Support Size 00246000 (bytes) | By Module (bytes) 00248000 -----------------------------------------------------------------00250000 EQUREGS P 0 | 00252000 | 00254000 XCHAR G 0 | XRETURN,XSAVE,XSRNR 00256000 | 00258000 XDECI A P 50-56 | XXXXDECI 144 00260000 | 00262000 XDECO A P 42-44 | XXXXDECO 80 00264000 | 00266000 XDUMP A P 80-150 XSNAP | XXXXSNAP 2094 00268000 XGET AGPS 32-42 XIONR | XXXXGET 950 00270000 XHEXI A P 44-46 | XXXXHEXI 504 00272000 XGPGEN A 1000 ABEND,CLOSE | -> creates XXXXGET/PUT modules 00274000 DCB,FREEMAIN,FREEPOOL,GET,| 00276000 GETMAIN,OPEN,PUT,XXGPSRCH | 00278000 XHEXO A P 42-44 | XXXXHEXO 108 00280000 XIDENT - | XSAVE 00282000 | 00284000 XIOGN A G 500-up ABEND,CLOSE, | -> creates XXXXREAD,PRNT, etc m00286000 DCB,FREEPOOL,GET/PUT,WTO, | 00288000 XOPENBLK | 00290000 | 00292000 XIONR A P - | XGET,XPNCH, (any XXXX- I/O) 00294000 | XPRNT,XPUT,XREAD 00296000 XLIMD P 0 | 00298000 | 00300000 XLOOK AG 0 | XSAVE,XSNAP 00302000 | XSRTR 00304000 XMUSE - | XSAVE 00306000 XOPENBLK AGPS - OPEN | XIOGN 00308000 XPNCH AGPS 32-42 XIONR | XXXXPNCH 664 00310000 | 00312000 XPRNT AGPS 32-42 XIONR | XSRTR XXXXPRNT 768 *1 00314000 XPUT AGPS 32-42 XIONR | XXXXPUT 1000 00316000 XREAD AGPS 32-42 XIONR | XXXXREAD 592 00318000 | 00320000 XRETURN GPS 2-up XCHAR,XSRNR | XXXXPRNT 768 *2 00322000 XSRTR | XXXXSNAP 2094 *2 00324000 XSAVE GPS 0-up XCHAR,XIDENT | XXXXPRNT 768 *2 00326000 XLOOK,XSRNR, | XXXXSNAP 2094 *2 00328000 XSRTR | 00330000 XSET GP 0 | 00332000 | 00334000 XSNAP AGPS 80-up XLOOK | XDUMP,XSRTR XXXXSNAP 2094 *1 00336000 | 00338000 XSRNR G - XCHAR | XRETURN,XSAVE 00340000 | 00342000 XSRTR G - XLOOK,XPRNT | XRETURN,XSAVE *3 00344000 XSNAP | 00346000 XSTOP GPS 36-46 | 00348000 XXGPSRCH AGPS - | XGPGEN 00350000 , 00352000 XMSYSGEN-4 00354000 00356000 NOTES ON THE MACRO SUMMARY TABLE 00358000 00360000 The meaning of the code letters under Flags is as follows:00362000 A : the macro is directly or indirectly required for complete00364000 compatibility with ASSIST assembler programs. 00366000 G : the macro references global set symbols, as noted in the next00368000 section. 00370000 P : the macro is a public macro, i.e., it can be made generally00372000 available, and a writeup exists which is easily distributable.00374000 S : the code generation of the macro can be affected by use of the00376000 XSET macro, which can be used to cancel or allow debug code. 00378000 00380000 The values given under Code Size are approximate in some cases. If00382000 a value of 0 is given, the macro definitely generates no code. If00384000 a dash is noted, the macro is an inner macro which generates code,00386000 but its size is included in the public macro which calls it. The00388000 value #-up indicates that the macro can generate wildly varying00390000 amounts of code, depending on the operands coded. However, these00392000 macros generally go to great lengths to generate the minimum00394000 possible amount of code. 00396000 00398000 The lists of macros used and macros used by give only XMACROs00400000 used or used by directly, and do not include any IBM macros used.00402000 00404000 *1 calls to these modules may be generated depending on the type00406000 of operand coded in a TR= option of XSAVE and XRETURN, and 00408000 will not be called if that macro is turned offby XSET at the 00410000 time the code is generated. 00412000 00414000 *2 XRETURN and XSAVE may call these modules, as noted in *1.00416000 00418000 00420000 *3 XSRTR is called to analyze the TR= option for both XRETURN00422000 and XSAVE, and generates approriate calls to XPRNT or XSNAP 00424000 as required. If trace code is not to be included, this macro 00426000 can be dummied out to eliminate the possibility of any trace 00428000 and dumping code. In addition, it can be altered to add 00430000 additional tracing features, such as adding an IF= test on 00432000 the embedded XSNAP, having it dump storage areas, etc. See 00434000 the macro definition itself for details. 00436000 00438000 00440000 GLOBAL SET SYMBOL TABLE 00442000 The following table is provided for the programmer who 00444000 wishes to ensure that any set symbols he uses will not cause00446000 conflicts with those employed by XMACROs. 00448000 , 00450000 XMSYSGEN-5 00452000 00454000 Variable Type Used by Comments 00456000 Name Macros 00458000 -------------------------------------------------------------------00460000 &XCSECT GBLC XSAVE used to save &SYSECT 00462000 &XIOGNST GBLB XIOGN dsect generation cntrl00464000 &XPNCHST GBLB XPNCH,XSET generation control 00466000 &XPRNTST GBLB XPRNT,XSET,XSRTR generation control 00468000 &XREADST GBLB XREAD,XSET generation control 00470000 &XRETUST GBLB XRETURN,XSET generation control 00472000 &XSAVE GBLC XRETURN,XSAVE current savearea name 00474000 &XSAVEST GBLB XSAVE,XSET TR= generation control00476000 &XSNAPST GBLB XSET,XSNAP,XSRTR generation control 00478000 &XSTOPST GBLB XSET,XSTOP generation control 00480000 &XTIMEST GBLB XSET, (XTIME-future) generation control 00482000 &XXCHAR GBLC XCHAR,XRETURN,XSAVE,XSRNR returns substring 00484000 &XXLOOK GBLA XLOOK,XSAVE,XSNAP,XSRTR returns list index 00486000 -------------------------------------------------------------------00488000 NOTES ON THE GLOBAL SET SYMBOL TABLE 00490000 00492000 Each generation control variable (one ending with characters ST)00494000 allows code generation by the corresponding macro when it has its00496000 initial value of 0, and suppresses it when set to 1 by XSET. Note00498000 that the only code of XSAVE and XRETURN which is suppressed is the00500000 trace code generated by calls to XSRTR. 00502000 00504000 The XTIME macro mentioned is part of a timing system which is00506000 still under test, and so is not yet available. 00508000 00510000 SUPPORT MODULE TABLE 00512000 Many of the XMACROs create calls to support modules which 00514000 actually perform the requested operations. In general, these00516000 calls are transparent to the registers and condition code. This00518000 table lists these modules and some of their characteristics.00520000 00522000 Module Size(dec) Comments 00524000 -------------------------------------------------------------------00526000 XXXXDECI 144 used by XDECI. does scanning and conversion. 00528000 00530000 XXXXDECO 80 used by XDECO. does output conversion. 00532000 00534000 XXXXGET 950 manages XGET files 00536000 00538000 XXXXHEXI 504 used by XHEXI, does scanning and conversions 00540000 00542000 XXXXHEXO 108 used by XHEXO, does the output conversions. 00544000 00546000 XXXXOPEN ? called by I/O modules to do special OPEN 00548000 00550000 XXXXPNCH 664 XPNCH support. generated by 1 call to XIOGN. 00552000 00554000 XXXXPRNT 768 XPRNT support. generated by 1 call to XIOGN. 00556000 XXXXPUT 1000 manages XPUT files 00558000 00560000 00562000 XXXXREAD 592 XREAD support. generated by 1 call to XIOGN. 00564000 00566000 XXXXSNAP 2094 XSNAP, XDUMP support. 00568000 , 00570000 XMSYSGEN-6 00572000 00574000 ADDING XMACRO PACKAGE TO A SYSTEM 00576000 00578000 Two files on the distribution tape can be used to add the 00580000 components of the XMACRO package to the appropriate system 00582000 libraries (note: consult the writeup ASDISTRB, which lists all the 00584000 files on the distribution tape and also gives other information 00586000 about them). This process can be summarized as follows: 00588000 00590000 1. From the file XMACDEFS create a partitioned dataset of 00592000 the macro definitions, using the utility IEBUPDTE. 00594000 2. From the file XMSOURCE create a partitioned dataset of 00596000 the source programs of the required support modules. 00598000 3. Assemble each member of the second dataset and place it 00600000 (or a load module form of it) into an appropriate library 00602000 of object modules or load modules. Note that the first 00604000 partitioned dataset must be concatenated to SYS1.MACLIB 00606000 when performing these assemblies, since a number of the 00608000 modules use certain of the macros (EQUREGS, XIOGN). 00610000 00612000 The remainder of this section gives an example of the programs 00614000 required to perform this process. It is assumed that the symbol 00616000 disttape is the name of the distribution tape, and that LABEL=# 00618000 gives the correct label number for each file used, as described 00620000 in the FILELIST writeup. It is also assumed that the reader is 00622000 familiar with the IBM utility IEBUPDTE. 00624000 00626000 STEP 1. CREATE MACRO LIBRARY 00628000 The file XMACDEFS contains all of the macro definitions, in 00630000 alphabetical order, separated by IEBUPDTE control cards, which00632000 are of the following form: 00634000 00636000 ./ ADD LEVEL=40,SOURCE=0,NAME=macroname 00638000 00640000 Thus, the following program will add all the macros to the dataset00642000 called XMACRLIB. For best use, this dataset should be one which00644000 is included in the SYSLIB cards of local catalogued procedures00646000 for assembler usage, i.e., the macros should be added to the local00648000 written system macro library, if one exists. 00650000 00652000 //CREATEXM EXEC PGM=IEBUPDTE,PARM=NEW 00654000 //SYSPRINT DD SYSOUT=A 00656000 //SYSIN DD UNIT=tape,VOL=SER=disttape,LABEL=#,DSN=XMACDEFS, 00658000 // DISP=(OLD,PASS) 00660000 //SYSUT2 DD UNIT=unit,VOL=SER=volser,DSN=XMACRLIB,DISP=(NEW,CATLG),00662000 // SPACE=(CYL,(1,,1)),DCB=SYS1.MACLIB 00664000 00666000 Note that the SPACE allocation may need to be altered, but 00668000 the DCB must be the same as SYS1.MACLIB, in order for it to be00670000 concatenated with it and used by the assembler later. 00672000 00674000 If changes must be made to the macro definitions, an extra 00676000 preliminary pass can be made using IEBUPDTE to create a modified00678000 version of XMACDEFS on another file, then running the above sort00680000 of program using the new file. Unwanted macros can be deleted this00682000 way. 00684000 , 00686000 XMSYSGEN-7 00688000 00690000 STEP 2. CREATE PARTITIONED DATASET OF SOURCE MODULES 00692000 The file XMSOURCE contains the source programs for the 00694000 support modules which may be required by the XMACROs. They are00696000 separated by ./ ADD cards in the same way as are the macro00698000 definitions. Thus the following program can be used to create00700000 a source library containing them: 00702000 00704000 //CREATESO EXEC PGM=IEBUPDTE,PARM=NEW 00706000 //SYSPRINT DD SYSOUT=A 00708000 //SYSIN DD UNIT=tape,VOL=SER=disttape,LABEL=#,DSN=XMSOURCE,00710000 // DISP=(OLD,KEEP) 00712000 //SYSUT2 DD UNIT=unit,VOL=SER=volser,DSN=XMODLIB,DISP=(NEW,CATLG),00714000 // SPACE=(CYL,(1,,1) 00716000 00718000 Again, if modifications are desired, IEBUPDTE can be used to 00720000 make them before this step is done. In particular, the I/O support00722000 modules may require modification to make them more convenient for00724000 a particular installation. This should generally involve only00726000 coding a different set of operands in the calls to XIOGN which00728000 actually generate the I/O modules (XXXXPNCH,XXXXPRNT,XXXXREAD).00730000 The writeup XIOGN/XIONR should be consulted for details on00732000 creating I/O modules tailored to specific needs. Note that the00734000 source programs given (which each consist of a few macro calls)00736000 are those used at PSU, and are set up to follow local conventions.00738000 A typical modification might be to make XPNCH, XPRNT, and XREAD use00740000 SYSPUNCH, SYSPRINT, and SYSIN instead of the DDNAMEs supplied.00742000 00744000 After this step has been completed, the dataset should include00746000 the members XXXXDECI, XXXXDECO, XXXXGET, XXXXHEXI, XXXXHEXO, 00748000 XXXXOPEN, XXXXPRNT, XXXXPNCH, XXXXPUT, XXXXREAD, and XXXXSNAP, if 00750000 none of them have been deleted. 00752000 00754000 STEP 3. ASSEMBLE SOURCE MODULES 00756000 The following program assembles the source module XXXXSNAP. 00758000 The same process should be repeated for other modules desired.00760000 00762000 //ASSMBL EXEC ASMFC 00764000 //ASM.SYSLIB DD DSN=XMACRLIB,DISP=SHR 00766000 // DD DSN=SYS1.MACLIB,DISP=SHR 00768000 //ASM.SYSIN DD DSN=XMODLIB(XXXXSNAP),DISP=SHR 00770000 00772000 The resulting object module can be placed in an object module 00774000 library, or if ASMFCL (or equivalent) is used, the resulting load00776000 module (on SYSGO) can be placed in a load module library.00778000 00780000 After all of the macros and support modules have been added 00782000 to their respective libraries, they may be tested using the test00784000 programs supplied in the file XMACTEST. This file should be00786000 punched, and the programs used as test decks. Note that the00788000 Job Control Language cards which are part of this file may have00790000 to be modified to fit local conditions, since they are currently00792000 set up for PSU catalogued procedures. This will be especially00794000 necessary if DDNAMEs are changed for the I/O modules. 00796000 00798000