DSNAP$ 1R2D -- ER SNAP$ Replacement with Enhanced Functionality
DSNAP$ is a MASM library routine which can be used to replace the SNAP$ Executive Request to perform debugging snapshots during execution of a Basic Mode program. It is compatible to the extent that calls to L$SNAP and L$SNAPI may be converted to calls to D$SNAP and D$SNAPI with no further changes needed, including storing the address in $+6 just before an L$SNAP call (but see address field for specifying an ACW register).
DSNAP$ has additional capabilities beyond SNAP$, including these choices:
1. Batch or demand width.
2. Dumping formats: Octal, Fieldata, ASCII, or any combination.
3. A, X, and/or R registers; or minor register set.
4. Ability to send snaps to an alternate print file.
5. Option to pause after every screen if dumping on demand terminal.
6. Snap ID can be up to 132 characters.
Use of DSNAP$ requires the D$SNAP procedure element and the relocatable DSNAP$.
D$SNAP,'options' SNAPID,regs,words,address LC,'PRTFIL',work-area
(The D$SNAPI call is identical.)
All parameters are optional, and consist of the following:
'options' - a string of one or more option characters:
AXR - Dump any combination of A, X, or R registers. See also M option. Register dumps from these options will always be in octal. Registers may also be given in the address field to allow other formats.
B - Use batch width (132). If neither B nor T is used, DSNAP$ will decide the width based on the run type (batch or demand).
D - Print duplicate (repeated) lines; by default, they are skipped.
F - Dump memory words in Fieldata. Compare with O and Q.
Hk- If dumping in ASCII, substitute character k for high-value characters (greater than 0177) -- default is space. k immediately follows H.
J - Join the words of alpha dumps; don't leave spaces between.
Lk- If dumping in ASCII, substitute character k for low-value characters (less than 040) -- default is space. k immediately follows L.
M - Dump the minor register set (X8-X11, A0-A5, R1-R3). May be accompanied by any combination of A, R, or X to limit output to one or two lines; if none is used, will assume all.
M-option register dumps optimize space usage as follows:
Demand: MX (X8-X11), MA (A0-A3), MR (A4-A5,R1-R3)
Batch: MX (X8-X11,R1-R3), MA (A0-A5), MR (X8-X11,R1-R3)
N - If an alternate print file is used, do not initialize it with a @BRKPT.
O - Dump memory words in octal, the default. May be combined with F and Q. Registers are always dumped in octal only.
P - Send the snap to an alternate print file. If the print file name is not supplied, assume 'DSNAP$PRT'. The user is responsible for doing a @BRKPT to close out the file. (The utility MORE's B option can accomplish this.)
Q - Dump memory words in ASCII. Compare with F and O.
S - Print SNAPID only instead of full header line. Compare with '-'.
T - Use terminal width (79). See B.
Wnn - Wait (pause) terminal output after every nn lines. If nn is omitted or less than 10, will default to 21. Ignored if batch or breakpointed.
When snapping, DSNAP$ will pause with the prompt 'MORE->'. Reply <Enter> to continue, X to terminate this DSNAP$ call, or @EOF to stop pausing unless a previously unused W-option DSNAP$ call is reached.
Z - Always initialize pause (W) count on this call. Otherwise, successive DSNAP$ calls using pause for the same work area will inherit the remaining pause line count of the previous such call. This means that in a program with several D$SNAP calls, only one needs to have the W option to activate pausing for all of them.
0 - Number the dumped memory from 0. This can make it easier to read a packet dump. The '0' must not immediately follow a 'Wnn' pause count. The dumped area's actual start address will be included in the header.
- - Do not print the DSNAP$ header line.
$ - If a label occurs on the D$SNAP call, attach it to the DSNAP$ packet rather than the address of the call. When this is done, the following offsets to the label may be modified to affect DSNAP$ output:
1,,S3 - Initial pause value for W option.
4,,H1 - Word count of area to be snapped.
4,,H2 - Address of area to be snapped.
6,,S3 - Word count of SNAPID. If 0, H2 is address of SNAPID ACW.
6,,H2 - Address of SNAPID (always Fieldata). Note that if the SNAPID at the original address generated by the D$SNAP call is modified, it may not exceed the original word count. If a SNAPID longer than the original is desired, it must be at a different address or stored as an ACW (word count,address) in H2.
SNAPID - ID to identify this snap. This may be supplied as either a 1-132 character string in 'single quotes', or as a register containing the ACW for the SNAPID (word-count,address). SNAPIDs are always Fieldata. If present, SNAPID will appear first in the header line that precedes each DSNAP$ dump, followed by DSNAP$ level, BDI:address called from, time, and date. If SNAPID is longer than 18 characters (12 if the '0' option is used), it will appear on a line by itself before the rest of the header. See also the 'S' and '-' options.
regs - registers to dump: 1 (R), 2 (A), 4 (X), or any combination. Equivalent to the X, A, and R option characters.
words - number of words of memory to dump. Since the upper 3 bits of this field are not used for register dump flags, its maximum value is 262143. The practical maximum for a Basic Mode bank (01000-0777777) is 261632.
address - starting address in memory to dump. If words is 0 and address is any register, DSNAP$ will assume that this register has been loaded at execution time with the ACW (word count, address) to use for snapping, and will retrieve the actual snap information from there.
The address to dump may also be among the registers, allowing them to be dumped as if they were words in memory, including alternate formats (ASCII & Fieldata) as well as combinations.
LC - Location counter in which to generate the DSNAP$ packet. Note that both D$SNAP and D$SNAPI accept this parameter; the difference between the two procs is how they perform when LC is not present: D$SNAP will generate the packet inline; while D$SNAPI will assume a location counter of 0 unless the current LC is 0, in which case it will assume 2.
LC is considered "present" if there is a 2nd field in the proc call, regardless of whether the location counter is explicitly coded, unless the MASM level is 6R3B or later, in which case the $IBITS test for a void field will be used.
'PRTFIL' - a 1-12 character filename to use as an alternate print file where the snap is to be directed. If the file is not pre-assigned, it will be @ASG,T with the default maximum. Unless the N option is used, the file will be initialized with a @BRKPT the first time it is accessed for the work area used by this DSNAP$ call.
The presence of 'PRTFIL' will force the P option if not set.
work-area - A 90-word buffer used by DSNAP$ for creating print lines, saving user registers, and other data. If omitted, will use the default DSNAP$WORK, which is included in DSNAP$. Normally, only one work area will be needed. Reasons for needing more might be if multiple activities take snaps, or if different snaps are to go to different print files.
All DSNAP$ packets and work areas must be collected below the 65K window.