1 Unofficial XMACRO Documentation Date: May 14, 1985 Edited by: Mary Flynn and Brad Coxhead 1 Disclaimer This is an accumulation of several peoples work. The Documents written by others are prefaced by their name. We don't guarantee the absolute correctness of the document and the work is a unofficial guide to only assist the Structured Macro Users. 1 Table of Contents 1. Installation Instructions pp 1-2 2. Structured Macros Member Names pp 3-8 3. Northern Illinois University Documentation pp 9-23 4. Pennsylvania State University Documentation pp 24-48 a. XREAD, XPRNT, XPNCH pp 24-27 b. XDUMP, XSNAP pp 28-33 c. XGET, XPUT pp 34-36 d. XSAVE, XRETURN pp 37-46 e. XHEXI, XHEXO pp 47-49 5. Listing of XMACROS pp 50 to end 1 Unofficial XMACRO Doc - May Contain Errors Page 1 Installation Instructions: If you are attempting to use the Structured Macros I can only assume that you know what you want to use them for and how they work. Both these topics are beyond the scope of this document. This document will list the datasets included in the Structured Macros and show you how to install them on your system. It also lists the code of most of the Macros. These Macros will work only on a IBM or IBM compatable system. Use IEHMOVE to copy each of the data sets to your account. //jobname JOB ,'name',TIME=(0,5),REGION=256K /*JOBPARM TAPES=1 //STEP1 EXEC PGM=IEHMOVE //SYSPRINT DD SYSOUT=A //SYSUT1 DD UNIT=PUB,SPACE=(TRK,(2,1)) //INPUT DD UNIT=TAPE,VOL=SER=006010, // DISP=(OLD),LABEL=8 //OUTPUT DD DSN=A10BEC1.STRUCS,UNIT=DISK,VOL=SER=ACA007, // SPACE=(TRK,(2,1,1)),DISP=(NEW,KEEP) //ACA007 DD UNIT=DISK,VOL=SER=ACA007,DISP=OLD //SYSIN DD * COPY PDS=T90PJH1.STRUCS,TO=DISK=ACA007, X FROM=TAPE=(006010,8),RENAME=A10BEC1.STRUCS, X TODD=OUTPUT // 1 Unofficial XMACRO Doc - May Contain Errors Page 2 In order for your assembler source program to access the Northern Illinois Sturctured Macros, there are a number of Job Control Language (JCL) statements that must be included. I am making the assumption that you have taken CSCI 465 or the equivalent thereof. The following JCL can be used to access the macro libraries needed to convert your assembler source code to object code. You will need to use the Loader or Linkage Editor to then execute your program. // job cards //STEP1 EXEC PGM=IFOX00 //SYSLIB DD DSN=T90PJH1.STRUCS,DISP=SHR, macro libraries // DCB=BLKSIZE=6400 // DD DSN=SYS1.MACLIB,DISP=SHR // DD DSN=SYS2.MACLIB,DISP=SHR //SYSGO DD DSN=object module created by assembler // UNIT=DISK, // DISP=(NEW,PASS,DELETE), // SPACE=(3200,(20,10)) //SYSPRINT DD SYSOUT=A source listing and error messages //SYSUT1 DD UNIT=PUB, work data set // DISP=(NEW,DELETE,DELETE), // SPACE=(3500,(400,50)) //SYSUT2 DD UNIT=PUB, work data set // DISP=(NEW,DELETE,DELETE), // SPACE=(3500,(400,50)) //SYSUT3 DD UNIT=PUB, work data set // DISP=(NEW,DELETE,DELETE), // SPACE=(3500,(400,50)) //SYSIN DD * . . . Assembler source code . . // 1 Unofficial XMACRO Doc - May Contain Errors Page 3 Listing of Structured Macros Members STRUCS 4 TRACKS (4 USED) COND CPARSE DO ELSE ENDDO ENDIF EXLBL GENCODE GETCC IF PUSHNEST CSCI466.PROCLIB 2 TRACKS (2 USED) CICS CICS466 DFSDUMP IMSASM IMSSEG IMSSORT CICSSIM.MACLIB 17 TRACKS (17 USED) DFHBMS DFHBMSDS DFHCSADS DFHDC DFHDCT DFHDCTDS DFHFC DFHFCT DFHFCTDS DFHFIOA DFHFWADS DFHMDF DFHMDI DFHMSD DFHPC DFHPCT DFHPCTDS DFHPPT DFHPPTDS DFHSAADS DFHSC DFHTC DFHTCADS DFHTCT DFHTCTTE DFHTD DFHTDIA DFHTDOA DFHTIOA DFHTS DFHTSIOA 1 Unofficial XMACRO Doc - May Contain Errors Page 4 ASSIST.LOADLIB 11 TRACKS (11 USED) ASSIST ASSISTV CICS.PROCLIB 2 TRACKS (1 USED) CSCICICS IMSSIM.LOADLIB 11 TRACKS (11 USED) CBLTDLI DFSDUMP ERRPROC IMS IMSSORT IMSV1L1 CICSSIM.LOADLIB1 5 TRACKS (3 USED) CICS DFHFCT DFHPCT DFHPPT DFHTCT CICSSIM.LOADLIB2 5 TRACKS (3 USED) CICS DFHDCT IMSSIM.MACLIB 8 TRACKS (8 USED) CHEKFLD DATASET DBD DBDGEN FIELD FINISH FLDTBGEN PCB PREFXGEN PSBGEN SEGM SEGMCHEK SEGTBGEN SENSEG 1 Unofficial XMACRO Doc - May Contain Errors Page 5 SYS2.MACLIB 21 TRACKS (21 USED) $CALL ASMDATE ASMPARM ASMTIME BIF ENQUIRE EQUREGS EXPARMGN FLAG IEFJFCBN IF INVERT INVERTF MISIR NOTIFY PRIME QUERY REGS RESET RESETF RRPARMGN RXPARMGN SET SETF SIADDR SICAD SIDEFS SIFATR1 SIFATR2 SIFREQ SIFSTAT SIFTCB SIPAD SIRAD SISAD SITAD SSIALIST SSIE SSIESECS SSIE2 SSIE3 SSISLIST SYSGET SYSPRINT SYSPUT TERME XCALL XCHAR XDECI 1 Unofficial XMACRO Doc - May Contain Errors Page 6 SYS2.MACLIB (continued) XDECO XDUMP XGET XGPGEN XHEXI XHEXO XIDENT XIOGN XIONR XLIMD XLOOK XMUSE XOPENBLK XPNCH XPRNT XPUT XREAD XRETURN XSAVE XSET XSNAP XSRNR XSRTR XSTOP XTIME XXGPSRCH CSCI565.MACLIB 5 TRACKS (3 USED) DISPMSG DISPQUE NETAD QDELETE RECEIVE RECEIVEX SEND SENDX SETNAME CSCI565.LOADLIB 5 TRACKS (4 USED) $$$RECV $$$SEND $DISPQUE $QDELETE $RLSERTN $SETNAME $TCBZERO FILEPROC FINDLNK INTER LMOVE MATCHAL NETAD QDELETE SETNAME SNDRSPEC TEMPNAME TESTIT 1 Unofficial XMACRO Doc - May Contain Errors Page 7 VTAM.LOADLIB 5 TRACKS (2 USED) FRONTEND SYS2.CALLIB 5 TRACKS (3 USED) ABDUMP ABDUMPS ABEND ABENDS FORTSORT GDATE MISIRPL PDSRTN QCARDS QLINES QTIME QUERY SORTA SORTB SORTC SORTD SORTDD SORTEC SORTMS SORTSZ WEEKDAY WEKDAY XXXXDECI XXXXDECO XXXXGET XXXXHEXI XXXXHEXO XXXXOPEN XXXXPNCH XXXXPRNT XXXXPUT XXXXREAD XXXXSNAP XXXXTIME 1 Unofficial XMACRO Doc - May Contain Errors Page 8 CSCI565.TESTLLIB 5 TRACKS (5 USED) $$$RECV $$$SEND $DISPQUE $NETAD $QDELETE $RLSERTN $SETNAME $TCBZERO FILEPROC FINDLNK INTER LMOVE MATCHAL NETAD NINTER OLDINTER SNDRSPEC 1 Unofficial XMACRO Doc - May Contain Errors Page 9 NIU STRUCTURED MACROS Introduction The NIU structured macros have been designed to facilitate the implementation of the standard structured programming constructs in the IBM assembler language. These constructs include: IF THEN ELSE DO WHILE * * V * * * * * ********>* * * * V *<*** ***>* * * * * * * * * * * * * * * * * V * V * * ****>* ********* ********* * * * * * * * * * * * * * * * * * * V * * * * * * ********* ********* * V * * * ********* * * * * * V V * * * ********>*<******** * * * * * ********* * * * * * V V *<******** For those familiar with IBM's concept 14 macros, implementation of the above constructs may be accomplished by coding the NIU structured macros exactly as you would code the concept 14 IF ELSE ENDIF and DO WHILE (only operand supported) ENDDO macros. 1 Unofficial XMACRO Doc - May Contain Errors Page 10 The macros have also been designed to allow the following extensions to the standard structured constructs: IF CASE ANALYSIS DO WHILE CASE ANALYSIS * * V * ********* ***************>* *<******** ********>* * V * *<** **>* * * ********* * * * * * * *<****** **********>* V V * V * * <* ****>* * ******* ******* * ******* * * * * * * * * * * * * * * V V * * * * * * ETC * * * ******* ******* * * ******* ******* * ******* * * * * * * * * * * * * * * * * ETC * * V * V * * ******* ******* * * V **>* *<** V * * * * * ********>* *<******** * * * * V * ********* * V >* *<**** * * * ******>* * * * * ********* * * * * * V *<**************V * V *<************* * V All of the above structures can be implemented using the following macros: IF, ELSE, ENDIF, DO, ENDDO, and COND. An explanation of each construct and examples of each follows. IF macro set. The IF THEN ELSE construct can be implemented as follows: IF condition THEN code if condition is true ELSE optional code if condition is false ENDIF 1 Unofficial XMACRO Doc - May Contain Errors Page 11 A condition may be specified as any legitimate operand of the COND macro (except the ELSE operand). A discussion of conditions and the COND macro is presented in a later section. THEN may be coded following the condition, but since it serves only as a comment, it must be preceded by a space. ELSE is optional; if the condition is not true and ELSE is not coded, control is passed to the next instruction following the ENDIF. IF COND COND COND (ELSE) ENDIF. This macro set supports a case study logic structure of the following form: * V *********** *<******************* ********************>* * * * * * *<********* **********>* * * * * * * V V * V *********** *********** * *********** * * * * * * * * * * * E T C * * * * * * * * * *********** *********** * *********** * * * * * V * V * * *********>* *<********** * V * * V *******************>* *<******************** *********** * V 1 Unofficial XMACRO Doc - May Contain Errors Page 12 An example of how this structure may be implemented is presented in the following coding sequence. IF COND condition-1 code if condition-1 is true COND condition-2 code if condition-2 is true . . . COND condition-n code if condition-n is true COND ELSE (implies NOT all of the previous conditions) code for ELSE condition ENDIF Coding rules for the IF COND COND (ELSE) ENDIF structure: 1) Coding IF (with no operands) signifies the beginning of an IF COND COND (ELSE) ENDIF sequence. 2) At least one COND with any operand other than ELSE (see COND description) must be coded immediately after an IF macro. 3) Every IF must have a corresponding ENDIF which signifies the end of the sequence of code. 4) Rules for COND ELSE: a) At least one other COND (not having ELSE as an operand) must precede the COND ELSE. b) The COND ELSE must be the last COND coded in the particular sequence, therefore only one COND ELSE per sequence is allowed. 1 Unofficial XMACRO Doc - May Contain Errors Page 13 General information about the IF COND COND (ELSE) ENDIF 1) Only the code associated with (i.e. following) the first true condition will be executed. It is the user's responsibility to ensure that this will produce the desired results. 2) The COND ELSE is optional, however, if none of the COND conditions are true, the code following the COND ELSE will be executed. If none of the COND conditions are true and COND ELSE was not coded, the program will be abnormally terminated with user code of 50. Note that the simple IF THEN ELSE setup may be implemented with the following coding sequence: IF COND condition code if condition is true COND ELSE code if condition is not true ENDIF DO MACRO SET. A simple DO WHILE: * * ***********>* * V * * * * * * * * * * *******>* * * * * * * * * * * * * * * * V * * *********** * * * * * * * * * * * * * * *********** * * * * *<**********V * V *<************ * V 1 Unofficial XMACRO Doc - May Contain Errors Page 14 may be implemented with the DO and ENDDO macros with the following coding sequence: DO WHILE--condition code to execute while condition is true ENDDO Once again, the reader is referred to the COND section for a discussion of conditions. The WHILE operand of the DO, however, should be coded: WHILE=simple condition as a keyword parameter for simple conditions (i.e. conditions not containing an AND, OR, ANDIF, or, ORIF) and: WHILE,compound condition as a positonal parameter for compound conditions. DO WHILE CASE ANALYSIS. This macro set supports a loop case study logic of the following form: * * ******************************>* * V * *********** * *<******************** *******************>* * * * * * * * *<************* *************>* * * * * * * * * V V * * * ********* ********* * * * * * * * * * * * * * * E T C * * * * * * * " * ********* ********* * * * * * * * * * V * V * * * *************>* *<************* * * V * * * * ********************>* * * * ************* * * * * *<*****************************V * V *<*********************** V 1 Unofficial XMACRO Doc - May Contain Errors Page 15 and may be implemented in a coding sequence of the following type: DO COND condition-1 code if condition-1 is true COND condition-2 code if condition-2 is true . . . COND condition-n code if condition-n is true ENDDO The loop is terminated when none of the COND conditions associated with the DO ENDDO are true. In this case, control is passed to the first instruction beneath the ENDDO. Rules for coding: 1) A DO with no operands signifies the beginning of a DO WHILE case analysis sequence. 1 Unofficial XMACRO Doc - May Contain Errors Page 16 2) Every DO must have a corresponding ENDDO. 3) COND within a DO may not be coded with the ELSE parameter. An assembly error will be generated if this is attempted. 4) Only the code associated with (or beneath) the first true COND condition will be executed on each pass through the loop. It is the programmer's responsibility to ensure that this will produce the desired results. CODING OF CONDITIONS. A condition may be coded as an operand of the DO or IF macros for simple IF THEN ELSE or DO WHILE structures, or as an operand of the COND macro in the IF or DO WHILE case analyses. Simple conditions. A simple condition may be coded as any of the following four types: 1) A condition code value in parentheses -- this would be used to test the value of the condition code as set by a previous instruction. For example, in the simple case: SR R15,R15 CLC FIELD1,FIELD2 IF (2) if cc=2 (i.e. FIELD1 > FIELD2) LA R15,4 put 4 into R15 ENDIF After execution of this code, if the condition code was be set to 2 as a result of the CLC instruction, then R15 would contain a 4, otherwise R15 would remain 0. IF case analysis example: Suppose we wish to compare FIELD1 to FIELD2 and set R15 to 0 if the fields are equal, 4 if FIELD1 < FIELD2, or 8 if FIELD1 > FIELD2. 1 Unofficial XMACRO Doc - May Contain Errors Page 17 (Initially R15 contains garbage.) CLC FIELD1,FIELD2 IF COND (8) (i.e. fields equal) SR R15,R15 COND (4) (i.e. FIELD1 < FIELD2) LA R15,4 COND (2) (i.e. FIELD1 > FIELD2) LA R15,8 ENDIF The above code would produce the desired results. 2) The second type of simple condition is an extended mnemonic is parentheses. The ones provided by the macros are presented in Table 1. User defined mnemonics can also be used provided that they have been equated previously in the assembly. TABLE 1. EXTENDED MNEMONICS CASE MNEMONICS MEANING COMPLEMENT after compare H, GT high, greater than NH, LE instructions L, LT low, less than NL, GE E, EQ equal NE after arithmetic P plus NP instructions M minus NM Z zero NZ O overflow NO after test under O ones NO mask instructions M mixed NM Z zeros NZ 1 Unofficial XMACRO Doc - May Contain Errors Page 18 For example, in the simple DO WHILE: LA R9,40 S R9,=F'4' DO WHILE=(NM) execute loop while R9 >= 0 CALL SUBROUT,((R9)) S R9,=F'4' ENDDO The effect of this code would be to test the value of the condition code in the DO macro as set by either of the subtract instructions and excute the code within the loop until until R9 is negative. At ths time, control would be passed to the first instruction following the ENDDO. 3) The third type of simple condition is any instruction setting the conditon code (other than a comparison instruction) followed by a desired condition code value. Note that in the previous example, it was necessary to include the subtract instruction both just before the loop was entered and also as the last instruction within the loop. This type of situation can frequently be avoided by use of an arithmetic instructon as a simple condition. The format of this type of condition is: (cc setting instruction, mnemonic or) condition code value for example: LA R9,40 DO WHILE=(S,R9,=F'4',NM) CALL SUBROUT,((R9)) ENDDO This example would have the same effect as the previous example. Notice the opcode and all operands are separated by commas. Use in the DO WHILE case analysis: Suppose we want a loop to continue until R10 contains a negative number -- furthermore every time we enter the loop, we wish to call ZEROPROC if R10 equals 0 or POSPROC if R10 is positive. The following code would implement this idea. 1 Unofficial XMACRO Doc - May Contain Errors Page 19 DO COND (LTR,R10,R10,Z) CALL ZEROPROC COND (LTR,R10,R10,P) CALL POSPROC,((R10)) ENDDO Types of Conditions. 4) The fourth and last type of simple condition is a compare instruction. This is coded for a 2 operand compare instruction as follows: (comparison,operand1,extended mnemonic or,operand2) opcode condition code value mnemonic A comparison instruction is any instruction that has an opcode mnemonic beginning with 'C' (e.g. CR, CLI, CP, etc.) and sets the condition code. A 3 operand compare instruction is also allowed. It is coded the same as a 2 operand comparison with the condition code value (or mnemonic) placed between the second and third operands. An example on the use of this type of condition might be to process update transactions based on a field called TRANCODE where A=add, C=change, and D=delete. The following code could implement the processing of a transaction: 1 Unofficial XMACRO Doc - May Contain Errors Page 20 IF COND (CLI,TRANCODE,EQ,C'A') trancode = A? CALL ADD call ADD, if yes COND (CLI,TRANCODE,EQ,C'C') trancode = C? CALL CHANGE COND (CLI,TRANCODE,EQ,C'D') trancode = D? CALL DELETE COND ELSE if none of the previous conditions was true, then CALL ERROR TRANCODE is invalid, so call ERROR routine ENDIF The code beneath the COND ELSE is executed when none of the previous conditions is true. In this case, this would be an error condition. If none of the conditions is true and the COND ELSE is omitted, the program would be ABENDed. COMPOUND CONDITIONS. A compound condition is 2 or more simple conditions separated by logical operators. The valid logical operators are AND, OR, ANDIF, and ORIF. The compound conditions can be broken into three types. Type I conditions are those containing only the AND and OR operators. Type I conditions will satisfy most condition configurations. A valid Type I condition would be: A and B e.g. (TM,BYTE,B'00110001',NZ),AND,(CLI,FLAG,EQ,C'Y') Conditions can be further compounded as follows: A or B and C Logical operators AND and OR are evaluated in the logical hierarchy AND before OR therefore, Type I conditions are disjunctive and the above condition has implied parentheses as: A or (B and C) similiarly, A and B or C and D and E or F 1 Unofficial XMACRO Doc - May Contain Errors Page 21 would evaluate with parentheses implied as follows: (A and B) or (C and D and E) or (F) This hierarchy of evaluation can be altered with the use of Type II and Type III conditions. Type II conditions are those containing the logical operator ANDIF. This operator has the effect of putting parentheses around the Type I group on either side of the ANDIF. The operator has no logical difference from the AND operator unless at least 1 of the Type I groups on either side contains an OR. Thus, the previous example can be altered as in the following: (A) ANDIF (B OR C) ANDIF ((D AND E) OR F) (A) ANDIF (B OR C) ANDIF (D) ANDIF (E OR F) As one can see, when ANDIF is used exclusively instead of AND, the result is a purely conjunctive condition. A Type III condition is one containing the logical operator ORIF. This operator has the effect of placing parentheses around the Type I or Type II condition on either side of the ORIF. It has no logical difference from the OR operator unless at least 1 of the the groups on either side of the ORIF is a Type II condition. The following examples show the effect of the ORIF. ((A OR B) ANDIF (C OR D)) ORIF ((E AND F) OR G) ((A AND B) OR (C AND D)) ORIF ((E OR F) ANDIF (G OR H)) ORIF ((I) ANDIF (J OR K OR L) ANDIF (M)) The following examples illustrate when the ANDIF and ORIF have no logical difference from the AND and OR operators. These situations should be avoided. ((A AND B)) ANDIF ((C AND D)) ((A AND B) OR C) ORIF ((D AND E) OR F) 1 Unofficial XMACRO Doc - May Contain Errors Page 22 As an example of using compound conditions, let me extend the example of handling an update transaction to include processing a series of update transactions (until an end of file condition occurs). Recall, TRANCODE = A for add, = C for change, = D for delete, and EOFFLAG = N means not end of transaction file. DO COND (CLI,EOFFLAG,EQ,C'N'),AND,(CLI,TRANCODE,EQ,C'A') CALL ADD COND (CLI,EOFFLAG,EQ,C'N'),AND,(CLI,TRANCODE,EQ,C'C') CALL CHANGE COND (CLI,EOFFLAG,EQ,C'N'),AND,(CLI,TRANCODE,EQ,C'D') CALL DELETE COND (CLI,EOFFLAG,EQ,C'N') CALL ERROR ENDDO 1 Unofficial XMACRO Doc - May Contain Errors Page 23 Nesting. The occurence of any structured sequence is allowed in the code associated with another 'higher level' structured sequence. This nesting may occur up to 50 levels deep. As an example, we can further 'clean up' the update example by the following use of nesting: GET NEXTRAN,TRANBUFF DO WHILE=(CLI,EOFFLAG,EQ,C'N') IF COND (CLI,TRANCODE,EQ,C'A') CALL ADD COND (CLI,TRANCODE,EQ,C'C') CALL CHANGE COND (CLI,TRANCODE,EQ,C'D') CALL DELETE COND ELSE CALL ERROR ENDIF GET NEXTTRAN,TRANBUFF ENDDO The code within each structured sequence should always be indented in order to improve readability. CALL CHANGE COND (CLI,TRANCODE,EQ,C'D') 1 Unofficial XMACRO Doc - May Contain Errors Page 24 The Pennsylvania State University Computation Center Contributed Program Contributor: John R. Mashey Computer Science Department 360 Assembler V.5.O. Jan 1973 ASSEMBLER UNIT-RECORD INPUT-OUTPUT MACROS PURPOSE Three macros XREAD (card READer), XPRNT (line PRINTer), and XPNCH (card puNCH) provide easy assembler 1/0 facilities with the following features: a) Only 1 statement is needed for each operation. No OPEN's, CLOSE's, DCB's, etc are required. b) REGISTERS - no registers are destroyed by these macros. c) CONDITION CODE - XPRNT and XPNCH preserve the con dition code. XREAD sets it to indicate end-of-file occurrence. d) JOB CONTROL LANGUAGE - under most cirumstances, little or no extra JCL will be needed. e) number of characters - may be specified in several different ways, may be any length up to maximum for device, and can be varied at execution time for maximum flexibility. f) XSET macro may be used to temporarily cancel output messages, input statements to be omitted, etc, during assembly time. USE All three macros use the same form of calling sequence: label is an optional statement label xmacro is one of XREAD, XPRNT, XPNCH area the address of the area to be read or written. This may be specified in two different ways: a) Anything valid in a LA instruction, for example HERE, SYM+8(5), 2(4,6) =CL10'OMESSAGE' are all acceptable. b) Either (O) or (RO), indicating that register o con tains the area address. 1 Unofficial XMACRO Doc - May Contain Errors Page 25 length specifies the number of bytes to be transferred. This length should be in the range 1 to maximum LENGTH FOR THE DEVICE (80 FOR XREAD, XPNCH, AND 133 FOR XPRNT). IF THE LENGTH IS INCORRECT, IT WILL BE IGNORED, AND THE MAXIMUM LENGTH USED. THE LENGTH MAY BE SPECIFIED IN THREE DIFFERENT WAYS: a) Directly, by providing an expression in the macro call. b) By default, by providing only an area address, which will cause the appropriate maximum length to be used. c) Indirectly, at execution time, by coding an ex pression enclosed in parenthesis, indicating a general purpose register which contains the number of bytes to be read or written. CONDITION CODE XREAD sets the CC as follows: CC = 0 - a card was read, and length characters transferred CC = 1 - end-of-file was encountered-no more cards CARRIAGE CONTROLS XPRNT requires the first character of the area to be a valid carriage control character. JOB CONTROL LANGUAGE The macros will accept DD cards with various DDNAMES, but have been designed to use JCL already present in cer tain cataloged procedures, in order to minimize the amount of extra JCL. The DD cards required for each macro are listed below. Note that the PSU catalogued procedure ASGCLG already contains a FT06F001 DD card, so this need not usually be supplied by the user. MACRO DD CARD FORM DDNAMES ALLOWED(for xxxxx) XREAD //DATA.xxxxx DD * XREAD, INPUT, FT05F001 XPRNT //DATA.xxxxx DD SYSOUT=A XPRNT, FT06F001 XPNCH //DATA.xxxxx DD SYSOUT=B XPNCH, FT07F001 ***NOTE*** If you want to use the macros in combined FORTRAN- Assembler programs, you must supply the x-ddnames, rather than using the FORTRAN ones. USAGE OF XSET The macro XSET (described in writeup on XSNAP/XSTOP/XSET), may be used to selectively cancel and restore generation of any of these macros. It is used as follows: XSET name=onoff where name is XREAD, XPRINT, or XPNCH, and onoff is either ON or OFF, which either permits or deletes generation of the specified macro until it is changed again by another XSET. 1 Unofficial XMACRO Doc - May Contain Errors Page 26 GENERAL INFORMATION Each macro has an associated CSECT which it calls to perform the actual 1/0 operations. The characteristics of these CSECTS are listed below, together with their DCB's. If the DCB's are unsatisfactory, they may be altered prior to the first macro call, since the DCB names are all entry point names also. MACRO MAX LENGTH CSECT NAME CSECT LENGTH DCB NAME XREAD 80 xxxxREAD 576 xxREDCB XPRNT 133 xxxxPRNT 700 xxPRDCB XPNCH 80 xxxxPNCH 596 xxPNDCB xxxxOPEN 532 XXXXOPEN is called by all the csects to do the openning of their dcb's for them. The relevant parameters of the current DCB's used are as follows: XXREDCB DCB DSORG=PS,MACRF=GM,RECFM=F,BUFNO=1,LRECL=80, BLKSIZE=80 XXPRDCB DCB DSORG=PS,MACRF=PM,RECFM=FA,BUFNO=1,LRECL=133, BLKSIZE=133 XXPNDCB DCB DSORG=PS,MACRF=PM,RECFM=F.BIFMP=1,LRECL=80, BLKSIZE=80 STORAGE REQUIREMENTS Each call on any of the macros generates from 32-42 bytes of code depending on initial alignment and options used. This is in addition to the storage required by any of the three CSECT's used. GLOBAL SET VARIABLES Each of the macros used a GBLB variable of the form &nameST, where name is the name of the given macro. These are used in conjunction with XSET to control macro generation. INNER MACROS CALLED Each of the macros uses the inner macro XIONR. 1 Unofficial XMACRO Doc - May Contain Errors Page 27 SAMPLE PROGRAM The following program reads, prints, and punches cards, and shows some of the various ways of specifying the macro operands. //EXEC ASGCLG //SOURCE.INPUT DD * TITLE ' TEST PROGRAM FOR 1/0 MACROS' TESTX10 CSECT XSAVE TR=NO set up linkage, base register XSET XPRNT=OFF cancel XPRNT for a while XPRNT =CL50' THIS MESSAGE IS NOT GENERATED', 50 XSET XPRNT=ON allow XPRNT's again LA 0,CARD save address of card XPRNT =CL40'1 TEST EXAMPLES', 40 skip to new page LA 2,50 set up length in register XPRNT =CL50'0 WILL READ,PRINT,PUNCH',(2) TLOOP XREAD CARD use default length=80 BNZ TDONE branch on end-of-file XPNCH (0) use previously loaded address XPRNT CARD-1,81 print card, with carriage cont B TLOOP go back for next card TDONE XPRNT MESSAGE,L'MESSAGE print ending message XRETURN SA=*,TR=NO MESSAGE DC CL100'OSUCCESSFULL COMPLETION OF TEST' CARD DS CL80 end //DATA.XPNCH DD SYSOUT=B required for card punch //DATA.INPUT DD * THIS IS THE FIRST TEST CARD THIS IS THE SECOND TEST CARD THIS IS LAST TEST CARD-END-OF-FILE FOLLOWS REFERENCES: see the XGET/XPUT writeup for more generalized macros allowing access to any sequential files. Also see XMSYSGEN for an overview of the X-MACRO system. 1 Unofficial XMACRO Doc - May Contain Errors Page 28 THE PENNSYLVANIA STATE UNIVERSITY Computation Center CONTRIBUTED PROGRAM Contributor: John R. Mashey, Computer Science Department 360 ASSEMBLER LANGUAGE WRITEUP REVISED JANUARY 1973(V.5.0) EXTENDED SNAP AND DUMP MACROS INTRODUCTION Xdump provides a very simple command for obtaining either a dump of the general purpose registers, or of a single area of main storage. The output is identified by printing the location at which the XDUMP was invoked. XDUMP is a special case of XSNAP, and calls it create code. XSNAP is a much more flexible macro. General purpose registers may be stored for later inspection if it is not desired to have them printed immediately. In addition to the printing of the GP registers, the float-ing point registers and any number of storage areas can be printed by one XSNAP, in any desired combination. Any storage areas may be dis-played, and may be specified by labels, base-displacements, dummy sec-tion symbols. An optional label may be provided to further identify the output. XSNAPs may be cancelled at assembly time using the XSET macro, and may be made conditional at execute time by making tests on values in registers or storage. XSNAP modifies neither the condition code nor the registers, and can thus be used at any point in a program at which addressibility exists. TYPICAL USAGE a) Print GP registers (XDUMP with no operands). XDUMP b) Print a single block of storage (up to 4095 bytes). XDUMP AREA,LENGTH LENGTH bytes starting at AREA c) Print GP registers, floating registers, and a storage area. (labeled as shown, with 100 bytes starting at X). XSNAP T=FL,LABEL='REGS,AREA X',STORAGE=(X,X+100) d) Print 2 storage areas, no registers. Areas are specified by RX- type addresses in this case, including DSECT symbols X1 and X2. e) Print (GP registers in this case) only when specified test is met, in this case, only if value in register 2 is greater than 100. XSNAP LABEL='AFTER 100TH TIME IN LOOP',IF=((2),H,=F'100') 1 Unofficial XMACRO Doc - May Contain Errors Page 29 XDUMP USE XDUMP can be used in one of two basically different ways: a) GENERAL PURPOSE REGISTER DUMP XDUMP Coding XDUMP with no operands prints the contents of the user's general purpose registers, in hexadecimal notation. The registers are preceded by a header line like the following: BEGIN XSNAP - CALL # AT CCAAAAAA USER REGISTERS # is the number of calls made to XDUMP so far, for identification. CCAAAAAA shows the last 32 bits of the user's PSW, in hexadecimal. CC gives the ILC, CC, and Program mask at the time of the XDUMP. AAAAAA gives the approximate address of the XDUMP macro expansion, and thus can be used to distinguish between the output of different XDUMP statements. *NOTE* XDUMP, is the same as XDUMP with no operand. b) STORAGE DUMP XDUMP area,length area is any RX-type address (anything allowed in a LA instruction) length is an absolute expression having value from 1 to 4095. Coding XDUMP with an address and length produces a dump of a user storage area, beginning at the address given by area, and ending at address area + length. The resulting output includes a header line like the above, fol-lowed by a hexadecimal and alphanumeric dump of the selected storage area. The storage is printed in lines showing two groups of four full-words, preceded by the memory address of the first word in each line, and followed by the alphanumeric representation of the 32 bytes on the line, with letters, numbers, and blanks printed directly, and all other characters translated to periods. The storage printed is also preceded by a line giving the address limits specificied in the XDUMP. If the length is omitted, the value 4 is used as a default. EXAMPLES OF XDUMP USAGE XDUMP AREA+10,80 XDUMP 8(1,4),100 XDUMP FULLWORD use default value of 4 XDUMP TABL(3),12 # Unofficial XMACRO Doc - May Contain Errors Page 30 XSNAP USE XSNAP may be coded with any of the operands shown, in any order, since all are keyword operands. It is called as follows: label XSNAP T=,LABEL=,STORAGE=,IF= label is an optional statement label. T= (Type of action to be performed for registers) T=PRINT requests that the GP registers be printed, as given by XDUMP. Storage areas may of course be printed in ) addition (STORAGE=). T=NOREGS requests that GP registers NOT be printed. If no STORAGE= is specified, this produces exactly 1 line of output, which can be used for program tracing. T=FLOAT requests both GP and floating point registers to be printed. T=(FLOAT,NOREGS) requests floating point registers, but NOT GP regs. T=STORE causes the GP registers to be saved into a well-labeled area, but does not create any printed output. The register area is originally generated filled with -1's (hexadecimal 'FF's), and is immediately preceded by the LABEL= string if it exists, or by the label generated on the register area (of form XX####B), if no LABEL= was used. The area is followed by 'XXXX' to make it easy to find. By examining such an area in a dump, the user can immediately determine: a) whether control ever passed through a given point (register area has values other than X'FF'). b) the contents of the registers the LAST time control passed through the given XSNAP. Note that the LABEL= option helps identify each XSNAP. If it is not used, the XX####B label placed before the area also appears in the assembly Cross-Reference listing, so it is still easy to locate. Note that this option is especially useful for placing inside heavily-used loops in a program in which intermittent/unpredictable errors occur. 1 Unofficial XMACRO Doc - May Contain Errors Page 31 Any of the types above may be abbreviated by the first two letters: PRINT = PR, NOREGS = NO, FLOAT = FL, STORE = ST **DEFAULT** T=PRINT is the default value used if not supplied. LABEL='string' (identification LABEL printed as XSNAP heading) The 'string' is any character string usable as a C-type constant in a DC statement, and is used as the XSNAP heading if it prints anything at all. The register area label (XX####B) is used if LABEL= is omitted. STORAGE=(list) (areas of main STORAGE to be dumped) This option accepts a list of ADDRESS PAIRS, each pair specifying the limits of an area of memory to be printed, from the address given by the first operand to that given by the second, from the third to the fourth, etc. There may be any even number of addresses, seperated by commas. Each of the address specifications in each pair may be written in either of the following forms (in any combination): a) any label or expression usable in an A-type address constant. b) *expression, where expression is 40 or less characters long, and is acceptable as the second operand of a Load Address instruction. Thus, base-displacement forms, doubly-indexed expressions, and dummy section symbols can all be used if preceded by an *. The following is a legal example of a STORAGE= operand: STORAGE= (A,B+7000,*4(2,R3),*AREA+3(4),*DSECT1,*DSECT1A,(A,*A) IF=(opa,relation,opb) (perform XSNAP only IF condition exists) Operands opa and opb are compared in some way. The XSNAP prints output only whenever the relation between the two operands is true. The relation is specified using the same codes as the Extended Mnemonics of the Branch on Condition: H,L,E,O,P,M,Z,NH, NL,NE,NO,NP,NM,NZ. Thus, an XSNAP WITH IF=(FLAG,NE,1) dumps only when value of FLAG is Not Equal to 1. The operands are compared in different ways depending on whether they are registers, storage, or immediate operands. The 3 cases are: OPERAND FORMS COMPARISON GENERATED MEANING (OPA) (OPB) CR (OPA),(OPB) OPA,OPB BOTH DESIGNATE REGISTERS (OPA) OPB C (OPA),OPB OPA: REGISTER, OPB: STORAGE FULLWORD OPA OPB CLI OPA,OPB OPA: ADDRESS,OPB: IMMEDIATE OPERAND For flexibility, adding a fourth operand to the sublist allows it to be used as the opcode in the comparison: IF=(TAG,O,X'F0',TM) would generate TM TAG,X'F0' and print only if result is Ones condition. 1 Unofficial XMACRO Doc - May Contain Errors Page 32 The IF option can be a powerful debugging tool. Dumping can be allowed only when a specific condition exists. For example, if an error occurs only after a loop is executed several thousand times, IF can make an XSNAP print nothing the first (2000, for example) times, then print: IF=((register with loop counter),H,=F'2000'). For programs which pro-cess many input cards, it becomes possible to turn debug output on just before an input card known to be causing trouble, without printing out-put for the preceding cards. This is done by checking the input for a special debug flag value, then setting a flag byte in memory, which can be tested by many XSNAPs to determine whether printing is desired. In fact, if an 8-bit value can be obtained from an input card, 8 se-perate groups of XSNAPs can be individually controlled. SUPPRESSION OF XDUMP AND XSNAP CODE GENERATED After a program is debugged, it is often useful to be able to suppress all debug code, without actually removing the cards from the deck. Coding XSET XSNAP=OFF suppresses all XDUMP and XSNAP code following the XSET. They can be restored by coding XSET XSNAP=ON, and this process repeated as desired. Also note that XSET can be used similarily for other X-MACROS, with multiple operands as desired: XSET XSNAP=OFF,XSAVE=OFF,XRETURN=OFF is quite common. RESTRICTION AND NOTES XDUMP and XSNAP are usable ONLY where addressibility exists. A common error is to write the following code at an exit point of a CSECT L 13,4(13) RESTORE SAVE AREA POINTER LM 14,12,12(13) RESTORE REGISTERS XSNAP . . . BR 14 The above code sequence typically results in a branch SOMEWHERE, since the program has destroyed whatever base register the XSNAP was assembled under. Such errors are extremely difficult to locate. In order to recieve dumping output from XSNAP or XDUMP, the user should supply a DD card for the execution step of his program, using the DDNAME XSNAPOUT. Typical such cards are: //DATA.XSNAPOUT DD SYSOUT=A (at Penn State) //GO.XSNAPOUT DD SYSOUT=A (standard IBM cataloged procedures) If XSNAPOUT is omitted, XSNAP will use one of the following DD names: XPRNT, SYSPRINT, FT06F001 (in that order) 1 Unofficial XMACRO Doc - May Contain Errors Page 33 XDUMP and XSNAP operate by calling a CSECT named XXXXSNAP, which performs the actual dumping. If it does not find the DDNAME XSNAPOUT it will issue a message to the system log and ABEND U0300. It should be noted that it is impossible for XXXXNAP to cause an interrupt un-less the user program has destroyed some of its code. Thus, any abnor-mal end with PSW inside XXXXSNAP is probably caused by user error. If XSNAP and XPRNT are used in the same program, the output of each is usually seperate. The following XSNAPOUT card may be used in-stead to obtain XPRNT and XSNAP output merged together: //DATA.XSNAPOUT DD UNIT=AFF=FT06F001 (AT PSU, MAY NOT WORK ELSEWHERE) REFERENCES The following documents of other X-macros may be of use: XMSYSGEN, XREAD/XPRNT/XPNCH. 1 Unofficial XMACRO Doc - May Contain Errors Page 34 THE PENNSYLVANIA STATE UNIVERSITY Computation Center CONTRIBUTED PROGRAM Contributor: Richard W. Fowler 360 ASSEMBLER V.5.0. Jan 1973 EXTENDED ASSEMBLER I/O COMMANDS PURPOSE Two macros XGET (eXtended GET) and XPUT (eXtended PUT), provide easy assembler I/O facilities for up to 20 files each simultaneously. a) Only 2 statements are needed for each operation. LA R1,=CL8'ddname' XGET or XPUT area address,length Example: LA 1,=CL8'CARDS' XGET AREA,80 //DATA.CARDS DD * The above example will read in a card file. b) Only register 1 is destroyed, but the user destroys it with the LA instruction. c) Condition code is set to indicate end-of-file, error condtions, and normal execution. THESE MACROS ARE EXACTLY LIKE THE XREAD/XPRNT/XPNCH MACROS IN their form of calling sequence, except that the maximum length is 32767. i.e., the area address may be any RX-type address, or (0) or (R0), the latter two indicating that the address is already present in register 0. Likewise, the length is an absolute expression giving the length, a register enclosed in parentheses (such as (1) or (R2)). or a default value (80 for XGET, 133 for XPUT) if the operand is omitted. CONDITION CODES XGET and XPUT set the CC as follows: CC=0 ---I/O occurred; CC=1 ---XGET only --- end-of-file encountered; CC=2 or 3 --- ERROR occurred. Either file not opened or error occurred while processing, file closed if possible or necessary. CARRIAGE CONTROLS If XPUTting to a printer file, the first character of the area must be a valid carriage control character. CLOSING OF FILE Performing an XGET or XPUT with a length of zero causes the designated file to be closed, so that it may be reread, for example. 1 Unofficial XMACRO Doc - May Contain Errors Page 35 JOB CONTROL LANGUAGE There are no extra DD cards in the catalogued procedures, therefore, unless using a dd that is in the procedure, the user must specify everything. CARD READER //DATA.XXXXX DD * PRINTER //DATA.XXXX DD SYSOUT=A,DCB=(RECFM=FA,BLKSIZE=133) CARD PUNCH //DATA.XXXXX DD SYSOUT=B,DCB=(RECFM=F,BLKSIZE=80) TAPE //DATA.XXXXX DD VOL=SER=YYYYY,DSN=ZZZ,UNIT=2400, // DCB=(RECFM=FB,LRECL=DD.BLKSIZE=DDD) DISK //DATA.XXXXX DD DSN=&&TEMP,UNIT=SYSDA, // SPACE=(CYL,(5,1)),DCB=(RECFM=FB,BLKSIZE=DDD) Note that these macros need the dcb to be specified, (or on the file), Thus, many DD cards in the procedure may require the DCB to be added. GENERAL INFORMATION Each macro has an associated CSECT which it calls to perform the actual I/O operations. The characteristics are as follows: MACRO MAX LENGTH CSECT NAME CSECT LENGTH XGET 32767 XXXXGET 964 XPUT 32767 XXXXPUT 996 STORAGE REQUIREMENTS Each call on any of the macros generates from 32-42 bytes of code, depending on initial alignment and options used. This is in addition to the storage required by any of the CSECTS used. Each macro calls the inner macro XIONR, which is the same macro called by the XREAD, etc, macros. ***NOTE*** User must load into register 1 the adddress of an eight byte character string, left justified and padded with blanks if necessary. This string represents the XXXXX of the //DATA.XXXXX DD cards. REFERENCES: see the XREAD/XPRNT/XPNCH writeup for the simpler and more specific I/O commands provided. Also see the XMSYSGEN writeup which describes the various properties and generation of the entire X-MACRO system. 1 Unofficial XMACRO Doc - May Contain Errors Page 36 EXAMPLE OF XGET AND XPUT USAGE The following program reads/writes several files in parallel. TEST1 CSECT BALR 12,0 USING *,12 SR 0,0 * * THIS PROGRAM WILL PROCESS A FEW FILES IN PARRALLEL, * LOOP LA 1,CL8'CARD' POINT TO AN INPUT FILE XGET AREA,80 DO THE INPUT BNE DONE BRANCH ON ENDFILE, * XREAD AREA2,80 DO NORMAL INPUT LA 1,CL8'PAPER2' POINT TO A PRINTER FILE XPUT AREA-1,81 DO OUTPUT,NOTE CARRIAGE CONTROL LA 1,=CL8'PAPER2' POINT TO OTHER PRINTER FILE XPUT AREA2-1,81 DO OUTPUT ON OTHER FILE B LOOP TRY AGAIN DONE BR 14 RETURN, IMPLICITLY CLOSE OTHER FILES DC CL1' ' AREA DS CL80 DC CL1' ' AREA2 DS CL80 END The extra JCL for the above is as follows: //DATA.PAPER DD SYSOUT=A,DCB=(RECFM=FA,LRECL=133,BLKSIZE=133) //DATA.PAPER2 DD SYSOUT=A,DCB=(RECFM=FA,LRECL=133,BLKSIZE=133) //DATA.CARD DD * THIS STUFF IS READ AT THE SAME TIME AS ANOTHER FILE IS READ ****** THE LAST CARD *** //DATA.INPUT DD * THIS IS THE NORMAL INPUT FILE AND IS READ AT THE SAME TIME AS ANOTHER FILE IS READ ********* THE LAST CARD ************ 1 Unofficial XMACRO Doc - May Contain Errors Page 37 THE PENNSYLVANIA STATE UNIVERISTY Computational Center CONTRIBUTED PROGRAM Contributor: John R. Mashey, Computer Science Department 360 ASSEMBLER LANGUAGE writeup revised April 1972 (v.4.0) EXTENDED SAVE AND RETURN MACROS INTRODUCTION XSAVE and XRETURN provide various serivices for assembler language program linkage using OS/360 conventions. While offering many more options than SAVE and RETURN, they use defaults, thus allowing that few operands need be coded. Some of the services provided are: a) Saving or restoring any range or ranges of registers on program entry or exit, in a more general way than SAVE or RETURN. b) Automatic initialization of 1 or more base registers for a program. c) Creating standard entrypoint identifier coding at a program entry. d) Generating reentrant code, using GETMAIN and FREEMAIN calls. e) Creating an AUTOMATIC PROGRAM TRACE or REGISTER DUMP whenever a module is entered or exited. f) Permitting easy usage in CSECT's with multiple entries/exits. TYPICAL USAGE The following shows the most common ways to use XSAVE and XRETURN: a) CSECT with a single entry point, at the CSECT name: ACSECT CSECT XSAVE ..... the code for the csect. XRETURN SA=* EXIT POINT: ALSO CREATE SAVE AREA b) CSECT with single entry and exit, using register 13 as both a base register and save area pointer, generating save area inside XSAVE: BCSECT CSECT XSAVE BR=13 CUASE SAVE AREA TO BE HERE ..... the code for the csect. XRETURN 1 Unofficial XMACRO Doc - May Contain Errors Page 38 c) CSECT with multiple entry points: CCSECT CSECT ENTRY C1,C2 SEVERAL ENTRIES C1 XSAVE ..... the code for section C1 of CCSECT. C1EXIT XRETURN C2 XSAVE ..... the code for section C2 of CCSECT. C2EXIT XRETURN SA=* SAVE AREA AFTER LAST XRETURN ONLY The macros are described below, with arguments listed basically in order of importance. A programmer not yet familiar with S/360 linkage should concentrate on the options: RGS=, SA=, and BR= where they exist. XSAVE PURPOSE XSAVE is used at any entry point (CSECT, START, or ENTRY label) in an assembler program to save registers according to the standard conventions, set up new base register(s), and possibly perform program tracing and various other optional services. USE The macro allows 8 keyword operands, which can be used in almost any combination or omitted as desired. Reasonable default values are supplied so that few operands need normally be coded. It is called: label XSAVE RGS=,BR=,SA=,ID=,TR=,REEN=,OPT=,AD= label is an optional statement label. 1 Unofficial XMACRO Doc - May Contain Errors Page 39 RGS= (ReGisterS) This operand specifies the register(s) to be saved into the calling programs's save area in the standard locations. It can specify that NO registers, a single range of registers, or multiple ranges of registers be saved, with the following operand types: RGS=NO no registers are saved. RGS=(list) list specifies the registers to be saved, where each item in the list is either: a) A single register designation (number or equate symbol) OR b) A pair of register designations, separated by a dash, showing the (inclusive) range of registers that should be stored. For example, RGS=(14-15,2-12) causes registers 14,15 and all of 2 through 12 to be saved appropriately. *** DEFAULT VALUE *** if omitted, RGS=(14-12) is assumed, (normal linkage). BR= (Base Register(s)) BR lists the base register(s) to be set up for the program just entered. It is either a single register, or a list of 2-4 of them, enclosed in parentheses, and separated by commas. If the latter format is used, a multiple using statement and appropriate register-loading statements are generated. If the first (or only) register is 13, a save area is generated in the middle of the xsave, so that register 13 can be used both as a base register and as a save area pointer. WARNING: If register 13 is specified, do not code XRETURN SA=* later in the csect. *** DEFAULT *** BR=12 is assumed if this option is omitted. 1 Unofficial XMACRO Doc - May Contain Errors Page 40 SA= (Save Area) This option specifies the name of a save area to be used, and also controls whether the program actually has a save area or not (if it is a lowest-level routine calling no others, it might have none). SA=NO no code is generated for linking save areas, and no area is referenced by XSAVE code. Register 13 is unchanged, so this option should only be used by a routine which calls no others. SA=* this is normal linkage, with following actions: a) Register 13 (calling program's save area) is loadedinto another register. b) The address of the called program's save area is placed into register 13. c) The two registers are saved correctly to fill in the standard forward and backward linkage between calling and called programs' save areas. Part b) creates the statement LA 13,saveareaname, as follows: a) If this is the first XSAVE in a CSECT, a 'standard name' (unique to that CSECT) is created by the macro and referenced. b) If this is not the first XSAVE, the current standard name' is used regardless of how it was originally created. SA=name this specifies the same kind of linkage as SA=*, execpt that the name becomes the 'standard name'. Briefly, the 'standard name' allows XSAVE and XRETURN macros to use and generate appropriately-named save areas, allowing either complete control over naming, or the conventions of giving no names. *** DEFAULT *** If omitted, SA=* is assumed, giving standard linkage, with all XSAVE(s) in a CSECT referring to the SAME save area name. 1 Unofficial XMACRO Doc - May Contain Errors Page 41 ID= (IDentifier) ID specifies an identifying character string to be created just after the entry point. It aids debugging by making the entry point easy to locate in the dump, and may printed in dump save area traces. ID=NO no identifier is created. This saves space and time. ID=* the identifier created is the first of the following found: the statement label if one is coded on the XSAVE; the name of the CSECT in which the XSAVE is used, or $PRIVATE if the CSECT is unnamed. ID=string the string (1-255 characters) is the identifier. *** DEFAULT *** If omitted, ID=* is assumed, thus creating some kind of ID. TR= (TRace) TR provides for automatic program tracing or register dumping whenever the entry point is given control, a useful debugging feature. TR=NO no trace code is provided. TR=* the message '*** name ENTERED ***' is printed on entry, where name is either the label on the XSAVE, or the name of its CSECT. TR='message' 'message' is printed on entry to the program. TR=SNAP the message (as in TR=*) is printed, followed by a dump if the GP registers, before they get changed by called program. TR=('message',snap) 'message' and registers are printed. *** DEFAULT *** TR=* is assumed, thus normally provide a dump (but see section at end called SPECIAL CONSIDERATIONS FOR TRACE CODE). 1 Unofficial XMACRO Doc - May Contain Errors Page 42 REEN=exp (REENtrant code) REEN requires that reetrant code be generated, and gives the number of bytes to be acquired via GETMAIN, IN ADDTION TO the 72 bytes needed for the standard savearea. The address of the acquired area is placed in register 13, so that first usable working storage begins at 72(13). If the called program uses the orginal values of register 15,0,1, they must be included in the registers saved by the RGS= option. The value exp may be an absolute expression. WARNING: this method is slow for heavily-used routines. OPT= (OPTional declartions) OPT provides for declaration of CSECT or ENTRY and/or TITLE. OPT=CSECT the label (required) on the XSAVE is declared a CSECT OPT=ENTRY the label (required) on the xsave si declared to be an ENTRY OPT=TITLE a TITLE is generated before any other code, and displays the label on the XSAVE statement. OPT=(TITLE,xxxxx) xxxxx is either CSECT or ENTRY, combining the above. AD= (ADdress constant addressibility) In some cases it may be necessary to have several entry points in a CSECT which share common USING conditions; AD can be used to do this. An address constant of the name specified is loaded into the first (or only) base register (BR=), and addressibility declared. Typically the address constant refers to the name of the CSECT. 1 Unofficial XMACRO Doc - May Contain Errors Page 43 XRETURN PURPOSE XRETURN is used to return from a module entered at an XSAVE, and is used to restore registers, set return code in register 15, perform program trace, and possibly generate a 72-byte save area referenced by XSAVE code. USE The macro has 7 keyword operands, coded or omitted as desired: label XRETURN RGS=,SA=,RC=,RP=,T=,TR=,REEN= label is an optional statment label RGS= (ReGisterS) This specifies the registers to be restored from the original calling program's save area, and is coded just like XSAVE RGS= option. *** DEFAULT *** RGS=(14-12) is assumed, restoring all registers. SA= (Save Area) This option can be used to control the return linkage code, and if desired, creates an 18-fullword save area (filled with zeros for debugging purposes), immediately following XRETURN's executable code. SA=NO The macro assumes that the routine is a lowest-level routine which calls no others. It generates neither the save area itself, nor the code to reload register 13 with the address of the caller's save area. register 13 is assumed to still point at the caller's save area. WARNING: use only paired with XSAVE SA=NO, else errors will occur. SA=* an 18-fullword save area is generated, labeled with the current 'standard name' described under XSAVE SA=* above. SA=name the save area is generated, and labeled with the name given. 1 Unofficial XMACRO Doc - May Contain Errors Page 44 *** DEFAULT *** IF SA is completely omitted, no save area is generated, but a save area is assumed to exist somewhere, and code generated to restore the previous save area pointer. The reason for this default is that any csect having several entry points still needs only 1 save area, which is typically generated only by the LAST XRETURN, so that it is addressible by all of the XSAVEs and XRETURNs in one CSECT. RC= (Return Code) Specifies a return code value to exist in register 15 on return to the calling program. The user need not worry about possible conflicts with RGS=, since RC overides any inclusion of register 15 in the RGS= option. RC=exp expression less than 4096 to be placed in register 15. RC=(r) specifies register currently containing the return code. RP=exp (Return Past register 14) RP provides a form of multiple (nonstandard) return to the calling program. The last instruction generated is not the usual BR 14, but B exp(14) instead. The value of exp is usually a multiple of 4, so that the calling program has 1 or more Branch statements following the call to the routine. T=* (Tag save area) This requests that byte 12 of the calling program's save area be set to x'FF' just before control is returned. This is useful for debugging, and is sometimes used by FORTRAN error-handling routines. TR= (TRace code) This option is coded exactly as is XSAVE TR=, and does the same thing execpt that the message printed is '*** name EXITED ***', where the name is either the label on the XRETURN or the CSECT name. 1 Unofficial XMACRO Doc - May Contain Errors Page 45 REEN=exp (REENtrant code) REEN specifies reentrant code generation, and should be matched only with an XSAVE REEN=exp, where the two expressions are the same. The area addressed by register 13, of length exp+72, is freed using the FREEMAIN macro. WARNING: if this option is used, it is impossible for the XRETURN code to ever restore the values of registers 15, 0, 1 which existed on the calling program prior to entering the called module. Note that normal conventions require only that registers 2-12 be restored. SPECIAL CONSIDERATIONS FOR TRACE CODE Note that the TR= options call the XSNAP (for SNAP options), or XPRNT for the others, so that the relevant writeups should be studied if any problems arise. In particular, the SNAP options may require a card like the following to be inserted for the execution step of the program (before or after a SYSUDUMP card): //GO.XSNAPOUT DD SYSOUT=A The trace code (and ONLY the trace code) created by XSAVE and XRETURN can be eliminated by coding the following: XSET XSAVE=OFF,XRETURN=OFF, and can be allowed again by replacing OFF by ON, as many times as desired. This allows leaving trace code in a program until it is debugged, then eliminating it by adding one XSET card at the beginning of the program. SYMBOLIC REGISTER EQUATES Symbolic register equate may be used anywhere, and can be any symbols, except that any used for registers 13, 14, or 15 must end in those characters, i.e., WORK13, R14, REG 15. 1 Unofficial XMACRO Doc - May Contain Errors Page 46 SAMPLE USAGE The following sample program assumes that EQU's have been set up for R0 EQU 0, ... R15 EQU 15. * TYPICAL USAGE FOLLOWS. XSAVE CALL PROG2 XRETURN SA=*,RC=4 RETURN TO OS WITH RETURN CODE OF 4 * FOLLOWING CALLS EXTREME AND UNTYPICAL. PROG2 XSAVE RGS=(R14,r0-r1,5-12),br=(11,10),opt=(title,csect) CALL LOWEST CALL LOWEST LEVEL ROUTINE LA R3,5 SET UP LIMIT ON RECURSION DEPTH CALL RECURSE CALL RECURSIVE ROUTINE CALL PROG3 CALL PROG4 B BAD RETURN HERE OR SKIP VIA RP= SR 15,15 CLEAR FOR RETURN CO = 0 BAD XRETURN RGS=(14,0-1,5-12),SA=*,T=*,RC=(R15) * LOWEST LEVEL ROUTINE FOLLOWS: NOTE CODE GENERATED LOWEST CSECT XSAVE TR=('RECURSION',SNAP),REEN=0,OPT=ENTRY BCT R3,CONTINU LOOP, RECURSING B RETB GIVE UP NOW CONTINU CALL RECURSE CALL MYSELF AGAIN RETB XRETURN REEN=0 RETURN, FREE STORAGE * ENTRIES PROG3 AND PROG4 HAVE SAME ADDRESSIBILITY PROG3 XSAVE OPT=ENTRY,SA=P3SAVE,BR=(12,11,10),AD=PROG3 PROG3A XRETURN RC=(R3),T=* PROG4 XSAVE OPT=ENTRY,AD=PROG3,BR=(12,11,10),ID=PROG3 LTR R0,R0 TEST TO DECIDE BZ ZERO SKIP TO RP=0 XRETURN RP=4 BRANCH OVER BAD ABOVE ZERO XRETURN RP=0,T=*,SA=* SAVE AREA, RP END REFERENCES The following documents of other X-macros may be of use: XMSYSGEN, EQUREGS, XDUMP/XSNAP, XREAD/XPRNT/XPNCH The reader is also referred to the following manuals: C28-6827 IBM S/360 OS FORTRAN IV (G&H) PROGRAMMER'S GUIDE (Appendix C. - save areas and linkage). C28-6646 IBM S/360 OS Supervisor and Data Management Services (pp.10-18 approx: linkage, reentrancy). C28-6547 IBM S/360 OS Supervisor and Data Management Macro Instructions (macros CALL, SAVE, RETURN) 1 Unofficial XMACRO Doc - May Contain Errors Page 47 THE PENNSYLVANIA STATE UNIVERSITY Computation Center CONTRIBUTED PROGRAM Contributor: Alan Artz 360 Assembler language April,1972 Extended Hexidecimal Conversion Macros INTRODUCTION XHEXI and XHEXO provide easy conversion of hexadecimal numbers for input and output. The value of a hexadecimal number can be read from a card using XREAD, converted from character mode to a hexadecimal number, and the converted number is placed in the specified general purpose register with XHEXI. XHEXO provides an easy way to convert internal hexadecimal to an output form that can be printed using XPRNT. XHEXI also places the address of the first non-hexadecimal number in register one, but if more than eight digits are scanned, the address of the ninth is placed in register 1. TYPICAL USAGE The following shows the most common usage of the macros XHEXI and XHEXO: A) Take a character number from an area called CARD and convert it to hex in Register 2. XHEXI 2,CARD convert number B) Take a series of numbers from a card and store them on a full-word-boundry. LA 3,AREA address of storage LA 1,CARD address of numbers TOP XHEXI 2,0(1) convert number ST 2,0(3) store it LA 3,4(3) advance storage pointer BNO TOP keep on going This bit of code takes character numbers from an area called CARD, converts them to internal hex, and then stores them in a location called AREA. The card was probably read in with the XREAD instruction. C) Take a number in a register and convert it and place it in an output area to be printed. XHEXO 2,AREA+1 convert number XPRNT AREA,8 print number AREA DC CL9' ' storage for number 1 Unofficial XMACRO Doc - May Contain Errors Page 48 XHEXI USE: XHEXI REGISTER,ADDRESS XHEXI, in the general form shown above where REGISTER is any general purpose register and ADDRESS is anything legal in an RX instruction, is used to do the following: 1. Beginning at the location ADDRESS, memory is scanned until the first non-blank character is found. 2. If the first character found is anything but a legal hexa-decimal character(0-9,A-F), the condition code is set to overflow and this address is placed in register 1. If the REGISTER is anything but register 1, its contents remain unchanged. 3. One to eight hexadecimal characters are scanned, the number converted to hexadecimal, and the result is placed in REGISTER. The value placed in the register is internal hexadecimal with leading zeros included and the number is right justified. 4. Register one is set to the address of the first non-hexadecimal character. With this in mind, the user should not code register one as REGISTER. This allows you to scan across the card for any number of character strings. The strings should be separated by blanks. The end of the string could be flagged with any non-hexadecimal character and a test could be made after a Branch Overflow (see sample program). 5. If more than eight hex digits are found, register one is set to the address of the ninth. This allows the user to scan across long strings of numbers. XHEXO USE: XHEXO REGISER,ADDRESS XHEXO in the general form shown above converts the value in REGISTER and places it in a right-justified 8-byte field beginning at ADDRESS. It can be easily printed using an XPRINT instruction. 1 Unofficial XMACRO Doc - May Contain Errors Page 49 SAMPLE PROGRAM USING XHEXI AND XHEXO This program reads a data card with an unknown number of hexadecimal numbers on it. The end of the data string is denoted by a '%' punched after the last number. The numbers are stored after being converted using XHEXI, and then converted for output using XHEXO. LA 3,STORAGE WHERE NUMBERS STORED XREAD CARD,80 READ IN CARD XPRNT CARD,80 ECHO PRINT LA 1,CARD ADDRESS OF CARD FOR SCANNING LOOP XHEXI 2,0(1) CONVERT NUMBER PUT IN 2 BO ILLEGAL CHECK FOR END XHEXO 2,AREA PUT NUMBER IN OUTPUT AREA XPRNT REP,28 PRINT CARD AND MESSEGE ST 2,0(3) STORE NUMBER LA 3,4(3) INCREASE INDEX B LOOP GET NEXT NUMBER ILLEGAL CLI 0(1),C'%' SEE IF END OF STRING BE DONE YES DONE XPRNT =CL50' ILLEGAL CHARACTER STOP',50 DONE ....MORE INSTRUCTIONS..... CARD DC 81C' ' STORAGE FOR OUTPUT STORAGE DS 20F STORAGE FOR NUMBERS REP DC C' THE NUMBER IN R2 IS' AREA DC CL8' ' STORAGE FOR OUTPUT NUMBER REFERENCES The following documents of the other X-macros may be of use: XREAD/XPRNT/XPNCH, XMSYSGEN.