I've written a new version of QBREAK. But I used this one while I was testing. It still works fine, if anyone would like to use it. I've made a couple changes to it, so it's better than it was, and I'll post the new version.
In an IBM mainframe environment, there's a TSO-TEST option that's available to assembler (and COBOL) programs that allows users to specify TEST when assembling a program. Then, during execution from your terminal, TEST allows users to set break-points via instruction labels, and run the program online, stopping at the location(s) specified, and look at registers and the contents of memory. Some folks use that a lot, others not much.
There's a similar function in Z390, but break-points must be specified by memory address. When running a test, specifying an address is very good. But if you want to specify several addresses, it's pretty tiresome. Worse, if you have to start over, it's really tiresome.
QBREAK can read a listing, and a control file, and create a series of break points. A user can then specify TEST(ddname) of a file that contains all of the break-points, set them, and turn control back to the user. Restarting the test is almost instantaneous if needed. QBREAK and TEST(ddname) together make the TEST function much easier to use. The QBREAK //SYSIN file (for old mainframe users, // implies that a ddname follows) looks like:
LOADLOC=80000. (start of your pgm in memory)
LABEL=BEGIN,ERR*,WHERE+12.
LABEL=DATA 256
COMMAND=C:\USERS\LIN\DOCUMENTS\Z390CODE\ADSTRING.BREAK
Stop at the location of BEGIN.
Stop at the location of any label starting with ERR
Stop 18 bytes past the address of the WHERE label. WHERE+12 would be 12 bytes past the location of the WHERE label. Periods matter.)
Create a 256 byte display instruction for the location of DATA. (Default length is 96.)
Note, if there are 2 or more duplicate entries in the LABEL= file, the first will be used. Any other will be ignored.
When you run QBREAK, break commands are written to the //BREAK file. Your input can contain labels of both instructions, and data areas. An op-code of DS or DC is assumed to be a data area and will create a display command (except DS 0H is considered to be an instruction, and will generate a break command)
Break commands (in IBM land they're called AT commands, hence the "A" in Z390) are written to both the //BREAK file, and also the console (your terminal).
Display commands are ONLY written to your terminal.
Commands are written in the order found in the listing.
COMMAND= .
COMMAND=C:\USERS\LIN\DOCUMENTS\Z390CODE\ADSTRING.BREAK
COMMAND= Simply writes anything after = to your terminal (so I won't forget). (The example is the file name of the .BAT file I use to start asmlg, ez390, etc.)
When I'm working, I have 3 BAT files that I use. (actually more, but these are of interest):
- ASMLG assemble, link, and test
- QBREAK create the file of break points I'm interested in
- EZ390 run a test with break-points set
===== I actually have a file that I start a new program with. I change all ASDF to my pgm name: =====
AGO .START
C:\USERS\LIN\DOCUMENTS\Z390CODE\ASDF
ASDF ASM
SET G=C:\USERS\LIN\DOCUMENTS\Z390CODE\ASDF
SET SYSPRINT=%G%.SYSPRINT
SET SYSIN=%G%.SYSIN
SET IN=%G%.INPUT
SET OUT=%G%.OUT
SET BREAK=%G%.BRAKE.BRAKE.TXT
BAT\ASMLG %G%.MLC TIME(2)
ASDFTT TEST
SET G=C:\USERS\LIN\DOCUMENTS\Z390CODE\ASDF
SET SYSPRINT=%G%.SYSPRINT
SET SYSIN=%G%.SYSIN
SET IN=%G%.INPUT
SET OUT=%G%.OUT
SET BREAK=%G%.BRAKE.BRAKE.TXT <===== break points for TEST
BAT\EZ390 %G%.MLC TEST(BREAK) TIME(2999)
` ASDFB QBREAK
SET GB=C:\USERS\LIN\DOCUMENTS\Z390CODE\ASDF\BREAK
SET G=C:\USERS\LIN\DOCUMENTS\Z390CODE\ASDF
SET LISTING=%G%.PRN
SET SYSIN=%GB%.SYSIN.TXT
SET BREAK=%GB%.BREAK.TXT <=== created by QBREAK
SET SYSPRINT=%GB%.SYSPRINT.TXT
BAT\EZ390 %GB%.MLC
LOADLOC=80000. BREAK POINTS
LABEL=Z,ZZ
.START ANOP
* ---------------------------------
MACRO
&LBL ERR &BC,&MSG,®S=NO
LCLC &L,&GOTO
LCLA &N
&N SETA K'&MSG-3
&L SETC 'SYS&SYSNDX'
&GOTO SETC 'ERR'
&LBL REVB &BC,&L.Z
AIF ('®S' EQ 'NO').A
&GOTO SETC 'ERR-4'
.A BAL R14,&GOTO
DC AL1(&N),C&MSG
&L.Z DS 0H
MEND
* ----------------------- internal macros ----------
MACRO
&LBL $$LA ®,&FLD $$LA REVB ????
AIF ('&FLD(1,1)' NE '(').A
&LBL LA ®,0&FLD
MEXIT
.A ANOP
&LBL LA ®,&FLD
MEND
* ---------------------------------
MACRO
&LABEL REVB &COND,&TO
LCLC &C,&B
LCLA &LEN
AIF ('&COND' NE 'B').ADDREM
&LABEL NOP &TO
MEXIT
.ADDREM ANOP
&LEN SETA K'&COND
AIF ('&COND'(2,1) NE 'N').ADD
&B SETC '&COND'(3,&LEN-2)
AGO .DOIT
.ADD ANOP
&B SETC '&COND'(2,&LEN-1)
&B SETC 'N&B'
.DOIT ANOP
&LABEL B&B &TO
MEND
* ---------------------------------
ASDF START 0
USING *,13,12
YREGS
DS 13F
ORG ASDF
STM 14,12,12(13)
ST 15,8(13)
ST 13,4(15)
LA 13,0(15)
LA 12,4095
LA 12,1(12,13)
L 4,0(1)
===== Old description with the history of my thinking while I was writing QBREAK. =====
QBREAK creates break points for assembler programs in the Z390 test environment. (BTW, if you're using Z390, then you want to get the SPFlite editor.) I used to be an assembler programmer, and still like it -- maybe wish I could still do it would be more accurate. Lots of us old assembler programmers wrote programs to scan a file looking for character strings, and I'm not an exception. But after a few years, Joe Blank demoed his program (DUMPER, written at Fireman's fund) at the bank and it was better than mine. He contracted with Compuware to do marketing and DUMPER was renamed to to FILEAID. But I still like writing such scan programs.
When I was 14 or so, I was given a HEXED puzzle, that I really liked. At the bank, I wrote a program to find all 2339 solutions. But, later I was asked if I had solutions for 5x12, 4x15, and 3x20 boards in addition to the traditional 6x10. I didn't. And my program could not be adapted for those board sizes. SO, I'm rewriting it. (And still have a partly finished string search program.)
The Z390, assembler and emulator works really well. And it's free. The SPFlite editor also works really well, and it's free. (Although George, the author would like $25 that I've given him a couple times -- it's that good.) Where's all this leading?
The HEXED puzzle program is a challenge, with pointers to pointers, to dsects, etc. And dementia isn't helping a whole lot. Maybe it will work. The Z390 assembler has a TEST option similar to IBM's, that I use all the time.
QBREAK (remember where this started) reads the listing, and creates break points based on labels. There's a new option to Z390 that allows a file of break points to be read, and then control is transferred to the terminal. The QBREAK source program is published, although one more change is needed once I understand what's needed by the Z390 batch option.
The SYSPRINT file is a record of the run.
The LISTING file is the assembler listing (PRN) file.
The SYSIN file contains control cards for the QBREAK program that look like:
LOADLOC=80000
LABEL=Q*,LOAD*,NORM,LOADLOC (Q* = any label that starts with Q)
LABEL=BADSIN+6,PUTSYS-6 (NORM = only that specific string)
LABEL=LOADLOC,WTO,LINE 120 (BADSIN+6 = the instruction 6 bytes after BADSIN)
LABEL=DW 12 (DW 12 lists 12 bytes of data at that label)
(A blank in col-1 is a comment)
LABEL=GOTSYSIN+8
LABEL=PLUSMINU+0C.
Note, you could code LABEL=GET,GET+12, but only the first entry in the list will be used.
In addition, when there's +12 or data length, it must be the only, or last, entry in the list.
(if you mess that up, then junk will be created.) Also, commands are created in the order
that the labels are found in the listing, regardless of the order in which they are specified.
The BREAK file will contain the calculated break (AT) commands:
A 80000.+00012. Q1
A 80000.+00018. Q2
A 80000.+00022. Q3
A 80000.+0002C. Q4
A 80000.+00116.+6 BADSIN (SET BREAK BEFORE OR AFTER THE LABELED INSTRUCTION)
A 80000.+00126.-6 PUTSYS
A 80000.+0015C.+8 GOTSYSIN
A 80000.+0024E.+0C. PLUSMINU (A = SET BREAK POINT)
L 80000.+00278. 96 LOADLOC (L = LIST A DATA FIELD)
A 80000.+00288. QLOADLOC
A 80000.+002A0. LOADLOCR
A 80000.+00414. QLBL
A 80000.+006DE. QLABEL
L 80000.+00AC8. 12 DW
L 80000.+00AD8. 96 WTO
L 80000.+00ADC. 120 LINE