═══ 1. ASDT - Application/System Debugging Tool ═══ Preface This manual describes the IBM Application/System Debug Tool, ASDT, which aids software debugging under IBM Operating System/2. Using ASDT, you can: o Debug OS/2 device drivers and applications that run in either the protected or real mode or both. o Gain control from OS/2 via Int 1, Int 3, NMI, or a hot key. Additionally, gain control on certain error conditions (Int 0, Int 6, Int C, and Int D). o Step execution (single, multiple, or procedure). o Stop program execution at up to 162 specified points. o Display or alter processor registers. o Display or alter processor memory (ASCII or EBCDIC translation). o Display LDT, GDT, and IDT entries. o Assign register or variable contents to other registers or variables. o Search memory to find a character string in hex, ASCII, or EBCDIC. o Compare two areas of memory. o Copy one area of memory to another. o Fill an area of memory with a specific character. o Disassemble blocks of instructions (ASM86(*) or Intel (MASM) mnemonics). o Evaluate numeric expressions with scratch pad space for results. o Maintain a separate screen for your program. o Support APA modes for all adapters. o Read in a profile during initialization phase for later execution. o Print out the ASDT screen, formatted instructions, or formatted memory. o Terminate the current process and return to OS/2. o Invoke user-defined function routines. o Identify the invocation path of the current thread or of a thread associated with a specific breakpoint. o Halt and resume threads to view screen groups or to begin a new OS/2 session. o Restore/take specific interrupts to/from OS/2 to support device drivers that have a need to control these interrupts. o Use multiple screens or a remote terminal to view both your application screen and the ASDT screen at the same time. o Use the 80386 hardware debug registers to trap instruction execution or specific memory reads or writes. * - ASM86 is an IBM Internal cross assembler (not provided with this program). ASDT uses a full screen format to display breakpoints, registers, memory, disassembled instructions, and other information. System Requirements ASDT runs on an IBM PC/AT or PS/2 under OS/2 1.1 and later and uses approximately 122KB of memory. ═══ 1.1. Getting Started ═══ ═══ 1.1.1. Introduction ═══ ASDT runs under IBM OS/2 as a device driver. It runs in both the protected (virtual) mode and the DOS compatibility box (real) mode. This user's guide and reference manual deals mostly with the protected-mode aspects of ASDT. However, it points out some key areas of differences of ASDT operation in protected mode versus real mode. Where the manual is not explicit about this, you should assume similar actions for either mode. The device driver or application program that you wish to debug should contain an Int 3 at a location where you want ASDT to gain control the first time. This location is often the first instruction of your device driver or application program. You can also make ASDT gain control through an NMI or a hot key. The ASDT hot key is the PrtSc key (by default), which must be activated before ASDT will recognize it as a request to obtain control. You can activate the hot key either by using the SK command (see SK - Set Keyboard Hot Key) or by using the /K option discussed below. ═══ 1.1.2. Installing ASDT ═══ 1. Use LoadRam2 (supplied on the diskette) to unpack the ASDT.RAM file (in the PROGRAMS directory of the diskette) into a directory specified by the PATH statement in your CONFIG.SYS. For example, from the diskette drive prompt (eg. A:), type: LOADRAM2 A:\PROGRAMS\ASDT.RAM C:\PSTOOLS /D This should unpack the following files into the PSTOOLS directory on your C drive (providing that this directory exists): README TXT // General guidelines ASDT EXE // the first of two EXE files for ASDT. ASDT2 EXE // the second of two EXE files for ASDT. UX DLL // the DLL file for ASDT. ASDT INF // Help file -- type 'VIEW ASDT' (For more information on LoadRam2 see the help provided with LoadRam2, or type "LoadRam2 ?" ). 2. Copy UX.DLL into a sub-directory which is in your LIBPATH statement in the CONFIG.SYS file. (e.g. C:\PSTOOLS\DLL). 3. Add the following commands to your CONFIG.SYS file: DEVICE=[PATH] ASDT.EXE [profile] [options] DEVICE=[PATH] ASDT2.EXE where: profile - a file containing ASDT commands (file name must be fully qualified) options - /K=nn - set nn as the hot key scan code (=nn is optional, and ASDT defaults the hot key to be the PrtSc key) /M - have ASDT use multiple screens /R=n - have ASDT use a remote terminal (using COMn) /U=nn - specify the user mask for ASDT (nn represents the user mask) /W - have ASDT use window assumptions /n - (where n is one of 0, 1, 2, 3, 6, C, or D) have ASDT not take over INT n This allows OS/2 to install ASDT as a device driver. After installation, ASDT can gain control on various interrupts or a hot key. If you want to debug another device driver during its initialization phase, make sure ASDT is installed prior to that device driver in your CONFIG.SYS file. You may specify an ASDT profile file name for ASDT to read in. Once ASDT is in control, you can execute your profile with the EP - Execute Profile command. ═══ 1.1.3. How to Begin Debugging with ASDT ═══ To begin debugging, you need to know how to do several key things. The following list describes these debugging steps and assumes the default ASDT function keys are set. Debug Task ASDT Command to Use Start ASDT To cause ASDT to take control from OS/2, run the program you wish to debug making sure it contains an Int 3 instruction ('CC'x). Note: ASDT can gain control through several interrupts. However, an Int 3 instruction that has been inserted into your program is the most common interrupt taken. Single Step ST (key F8) Executes one instruction in your program. Set Breakpoints Sn Sets one of the breakpoints to an address in your program. Examples: S1 = CS:IP+23 sets a breakpoint 23 bytes from the instruction about to be executed. Execute EX (key F7) Executes your program until it terminates, until it reaches a breakpoint, or until it reaches an ASDT-captured interrupt. Set Registers Set any register by entering its name followed by an expression containing its new value. Examples: AX=BX+CX sets register AX. ES=DS sets register ES. BP=SP+CX sets register BP. Disassembly/Memory L1-L9, M1-M6 Creates a disassembly or memory window (whichever is the primary window) on one of the window area lines. Windowing NW (key F4) Toggles among disassembly, memory, LDT/GDT, and IDT windows. Get Help HP (key F1) Displays a single help screen listing ASDT commands. Return to OS/2 TP (key F3) In protected mode, TP is valid only for processes that are not running at level 0. For those processes that are running at level 0, you need to execute (EX) to completion to return to OS/2. In the DOS compatibility box, you should use the TP command only to terminate an application (not a device driver, a resident interrupt handler, etc.). See Entering ASDT Commands for a discussion of ASDT command line handling and Window Area for a discussion of ASDT window editing. ═══ 1.1.4. Function Keys ═══ ASDT sets function keys F1-F10 for you. You can change them to other valid ASDT commands, and you can also set the shifted, controlled, and alternate function keys. The default keys are: F1 Help (HP) F2 Define Keys (DK) F3 Terminate Process (TP) F4 Next Window (NW) F5 Repeat Find (FX) F6 Application Screen (SC) F7 Execute User Program (EX) F8 Single Step User Program (ST) F9 Procedure Step User Program using S9 (S9=EX+IL;EX;S9) F10 Retrieve Command (RC) ═══ 1.2. Using the ASDT Display ═══ For the disassembly and memory windows, the ASDT display has the following areas: Line 1 ASDT's name, release, release date, primary window, current character translation, and current screen. Lines 2-3 breakpoints and scratch pad variables. Line 4 general registers, flags, and top four words of stack. Line 5 specific registers and flags. Line 6 selector registers. Line 7 SP register, instruction pointer, code origin, and step count. Line 8 address about to be executed, location counter, next instruction (disassembled), and operand address and contents. Line 9 command line. Line 10 messages and trace information. Lines 11-25 window area containing line numbers, new window indications, and views of disassembly, memory, or table elements. For the LDT/GDT and IDT windows, the following changes are made: Line 1 GDT address, IDT address, LDT register, process id, thread id, and task state register. Line 8 LDT/GDT or IDT indicator, address about to be executed, location counter, next instruction (disassembled), and operand address and contents. Lines 11-25 LDT/GDT or IDT window containing line numbers and LDT, GDT, or IDT descriptor entries. A disassembly line is divided into three editable sections: the selector and offset parts of the address, the hexadecimal instruction, and the instruction's operand value. In addition, ASDT displays the instruction mnemonic and the operand address. A memory line is divided into three editable sections: the selector and offset parts of the address, the hexadecimal memory, and the equivalent ASCII/EBCDIC characters. An LDT, GDT, or IDT line is divided into these sections: an index into the descriptor table, the type of descriptor, and other information based on the type of descriptor. LDT, GDT, and IDT lines are not editable. You can move the cursor anywhere on the command line and can move it off the command line to the disassembly or memory window area. You use the command line to enter ASDT commands and the window area to view or edit instructions, memory, and descriptors. The following sections discuss how to enter ASDT commands, how to move the cursor within the disassembly or memory window, and how to alter instructions or memory. ═══ 1.2.1. Memory Format ═══ On lines above the command line, ASDT displays memory in register format; i.e., not byte-reversed. ASDT also uses this format for the operand values at the right edge of disassembly lines below the command line. On memory lines below the command line, memory is displayed in Intel byte-reversed format. ═══ 1.3. Entering ASDT Commands ═══ ═══ 1.3.1. Command Line Input ═══ You use the command line for entering all of the ASDT commands. When you press the ENTER key, ASDT processes the command line. Command processing begins with the first command on the command line and continues with the remaining commands. You separate commands with semicolons. Command line processing also stops when ASDT encounters an invalid command. When command line processing finishes, the cursor moves to the beginning of the command line. The command line is cleared unless the first character of the command line is a slash (/) or unless an error was encountered. The sole function of the slash at the beginning of the command line is to preserve the command line so you can see and use it again. You can place as many commands on the command line as will physically fit. You can place one or more blanks before or after each command. There is no restriction on the sequence or combinations of commands. ═══ 1.3.2. Profile Input ═══ An alternative to typing ASDT commands on the command line is reading them in from a profile on disk. This profile, which you can create with any standard editor, is read in at ASDT installation time. Its commands are executed with the Execute Profile (EP) command (See EP - Execute Profile for more information.) All commands in the profile must follow standard ASDT command rules; that is, they are processed as if they had been entered on the command line. They must fit on the command line, which is 76 characters long. A slash at the beginning of a line in a file is ignored. The following discussion of command handling applies to the command line and to profiles. ═══ 1.3.3. Command Parsing ═══ The command line format is as follows: [/] cmd = opnd [ ; cmd = opnd ; cmd = opnd ; . . . ] If the optional slash at the beginning is present, ASDT will not erase the command line when it finishes processing the commands. If you wish to enter more than one command on the command line at a time, separate the commands with semicolons. Commands are always two characters in length. You can follow the last command with a semicolon. This trailing semicolon does not affect command line processing. However, it allows you to use the Tab key to position the cursor after the last command if you wish to add another command. The blanks as well as the "=" sign between the "cmd" and the "opnd" are optional. This condensed syntax is not elegant, but you can save unnecessary keystrokes by using it: cmdopnd;cmdopnd;cmdopnd; . . . ═══ 1.3.4. Specifying Operands ═══ An operand begins with the first non-blank (other than =) following the command and continues to a semicolon or continuous blank characters. If there are only blanks following the command, the operand is null. Expression Evaluation Most operands are expressions. An expression is one or more terms which are added together. A term may be a decimal or hexadecimal number, one of the processor registers, or one of the ASDT variables. The ASDT variables include the breakpoints (V1-V9 and S1-S9) displayed on the ASDT screen, the memory address variables (L1-L9 and M1-M6) displayed on the ASDT screen, and the other variables (M7-M9) that are not displayed. These other variables can be used as scratch pad space for expression or address calculations. (See "Valid Terms" below for a complete list of ASDT variables.) The "+" and "-" signs may precede terms. The optional "+" sign performs no function but can improve operand readability. The "-" sign negates the term before the addition is performed. You can precede a term with multiple signs, and you can use blanks freely between terms and their signs. Terms which are processor registers or ASDT variables are always two characters in length. Decimal and hexadecimal terms have variable length. A blank, sign, special operator, or another term must follow a numeric term to delimit that numeric term; there is no such requirement for register or variable terms. Decimal terms are distinguished from hexadecimal terms by a trailing decimal point. Indirect terms are distinguished from other terms by a trailing "%" character and optional length. Indirect terms allow you to use the contents of a memory location indirectly. When you specify an indirect address, ASDT uses the location contents for the number of bytes you specify. All calculation results are displayed in hexadecimal format. Decimals, hexadecimals, registers, and variables are all converted to hexadecimal format for calculation. Expression Examples The following examples portray several different ASDT commands with various operand expressions and terms. CO = CS:4E8 assign CS and offset 4E8 to CO V1 = 10. + 20. + 44. decimal arithmetic M7 = AX + 4A23 - 10. combined arithmetic S1 = CO:13 set breakpoint at CO + 13 AX = ES:BX%4%2 set AX to contents of memory pointed to by a 4-byte pointer, which is pointed to by ES:BX Expression Syntax In the following equivalent examples, the ASDT variable V1, the negative value of processor register BX, hexadecimal 4A, and the processor register AX are added together with the result being placed into the AX processor register. AX = V1 - BX + 4A + AX optimum readability AX=V1-BX+4A+AX optional blanks removed AX V1-BX 4A AX optional "=" and "+" removed AXV1-BX4A AX fewest keystrokes Valid Terms The following list shows all of the valid processor register and ASDT variable terms which you can use in an expression. Hexadecimal, decimal, and indirect terms are also valid. ┌──────────────────────────────────────────────────────┐ │ AH CH DI FL LD TS │ │ AL CL DL FX M1-M9 V1-V9 │ │ AX CO DS GD OP XS │ │ BH CS DX ID SI │ │ BL CT EC IL SP │ │ BP CX ES IP SS │ │ BX DH EX LC S1-S9 │ └──────────────────────────────────────────────────────┘ It is useful to remember that all registers and variables displayed on the screen (except the binary flag bits) are valid terms for an expression. All registers and variables displayed on the screen including the binary flag bits are valid ASDT commands. Most commands are also the name of a variable (e.g., AX, DS, or L1). When one of these commands is used, there is an assignment to the variable. For example, the command AX=BX+123 assigns the value BX+123 to AX. It is important to remember that AX is the command because in some cases the assignment causes other results. For example, S1=DS:BX+123 causes ASDT to assign the value DS:BX+123 to S1 and activates the breakpoint S1. Some ASDT variables are not commands. They are the EC, GD, ID, IL, and OP variables. The EC variable is the error code that is returned by OS/2 when a general protection fault occurs. ASDT initializes EC to 0, and EC changes value with each Int D. The GD and ID variables allow you to use the base address of the GDT and the IDT in physical address expressions. The IL variable holds the current instruction's length in bytes while the OP variable has the address of the byte/word referenced by the current instruction (if any). Address Evaluation ASDT expects addresses to be in one of two forms: selector:offset or physical address. If the address expression contains a colon (:), a selector register (CS, DS, ES, SS, or XS), or an ASDT variable that is in selector:offset form, then ASDT assumes the address is in selector:offset form. In this case, the selector must reference a valid descriptor, and the offset must be within the segment limit for that descriptor. Any other address is considered to be a physical address, and ASDT treats it as a six-hexadecimal digit (higit) number. Note: In real mode, the address evaluation expected is either a segment:offset or a physical address. In the case of segment:offset addresses, all segments are considered valid. The physical address range, however, is limited by the 1M line (5-higit number). ═══ 1.3.5. Moving on the Command Line ═══ ASDT recognizes the following function keys on the command line: Enter Moves the cursor to the beginning of the command line and executes the commands on the command line. Home Moves the cursor to the beginning of the command line. End Moves the cursor to the end of text on the command line. Up Arrow Moves the cursor to the first line of the disassembly or memory edit area (valid only in a disassembly or memory window). Down Arrow Moves the cursor to the first line of the disassembly or memory edit area (valid only in a disassembly or memory window). Left Arrow Moves the cursor left one position unless the cursor is at the beginning of the command line. Right Arrow Moves the cursor right one position unless the cursor is at the end of the command line. PgUp Scrolls the window up the number of lines in the window (valid only in an LDT/GDT or IDT window). PgDn Scrolls the window down the number of lines in the window (valid only in an LDT/GDT or IDT window). Ctrl-PgUp Scrolls the window up one line (valid only in an LDT/GDT or IDT window). Ctrl-PgDn Scrolls the window down one line (valid only in an LDT/GDT or IDT window). Tab Moves the cursor to the next command on the command line and wraps around from the last command to the first command. Back Tab Moves the cursor to the previous command on the command line and wraps around from the first command to the last command. Spacebar Replaces the character at the cursor position with a blank and moves the cursor right one position. Backspace Moves the cursor left one position, erases the character at the new cursor position, and moves the remainder of the command line left one position. Insert Changes the insert mode. A caret at the beginning of the command line indicates that insert mode is active. Del Erases the character at the cursor and moves the remainder of the command line left one position. Shift Shifts to upper case and reverses the effect of Caps Lock. Caps Lock Shifts to upper case for the alphabetic keys. Ctrl-Home (Clear) erases the entire command line and places the cursor at the beginning of the command line. Ctrl-End (Clear End-of-Line) erases the command line beginning at the cursor position continuing to the end of the command line. PrtSc Causes the ASDT screen to be printed. ASDT recognizes the following function keys while the user program is executing: PrtSc As the default hot key, interrupts user program if the /K option was specified or the SK command was issued prior to executing the user program. Note: ASDT assumes that you want to print your screen when you depress the shift key at the same time that you depress the PrtSc key. On some hardware configurations, you need to depress the shift key a full second or two before depressing the PrtSc key to have ASDT ignore the keystrokes and allow OS/2 to print your screen. This key will be replaced as the hot key if the /K=nn option or SK=nn command is issued (nn will act as the scancode of the hot key). ═══ 1.4. Window Area ═══ The window area occupies the bottom portion of the ASDT display. This area is where you view disassembled instructions, memory, LDT/GDT descriptors, and IDT descriptors. You can access the window area through window commands, individual window line commands, and direct editing in the window itself. The window consists of fifteen lines. Each line has a line identifier that is used to address the lines with commands. These identifiers are the ASDT variables L1 through L9 and M1 through M6. Each window line displays its identifier at the beginning of the line. You can address any window line in any window with the L1-L9 and M1-M6 commands. There is always a primary window. The primary window is the type of line that is displayed on line L1, the first line in the window display area of ASDT. Initially, the primary window is disassembly. The primary window can be disassembly, memory, LDT/GDT, or IDT. You can set up a secondary window for disassembly and memory windows. If the primary window is disassembly, then the secondary window must be memory. If the primary window is memory, then the secondary window must be disassembly. You can divide all primary windows into multiple window segments. Every primary window line shows an asterisk near the front of the line when that line starts a window segment. Multiple window segments allow you to view more than one disassembly, memory, LDT/GDT, or IDT address at once. You can set up the window area in any of the following configurations: Window Type Contents Segments Browse Edit Disassembly 15 disassembly lines 1-15 Yes Yes Memory 15 memory lines 1-15 Yes Yes Disasm/Memory 15 disasm/memory lines 1-14,1 Yes Yes Memory/Disasm 15 memory/disasm lines 1-14,1 Yes Yes LDT/GDT 15 LDT/GDT lines 1-15 Yes No IDT 15 IDT lines 1-15 Yes No ═══ 1.4.1. Window Contents ═══ The disassembly window area shows portions of memory as hexadecimal instructions and disassembled mnemonics for those instructions. A disassembly window consists of one to fifteen lines showing a contiguous block of disassembled instructions. Each disassembly line shows an address (either selector:offset or six-higit physical), the hexadecimal instruction, its ASM86 or Intel (MASM) mnemonic, an operand address and operand contents (byte or word) if appropriate. Within a disassembly window you may alter and scroll through instructions. You can switch the mnemonic format with the DA (Disassemble ASM86) and DM (Disassemble MASM) commands. Also, if the disassembly line is in the range of the code origin (CO), ASDT displays a "$" near the front of the line and displays the disassembly line address as :offset, where the offset is from the CO. This allows you to display a disassembly segment that matches your assembly listing. The memory window area shows portions of memory. A memory window consists of one to fifteen memory lines showing a contiguous block of memory. Each memory line shows an address (either selector:offset or six-higit physical), sixteen bytes (one paragraph) of memory in hexadecimal format, and the same sixteen bytes in either ASCII or EBCDIC format. You can switch the format with the AS (ASCII) and EB (EBCDIC) commands. Within a memory window you may alter and scroll through memory. The LDT/GDT window area shows LDT and GDT descriptors. Each LDT/GDT line shows the table index, the descriptor type, and other descriptor information based on the descriptor type. Likewise, the IDT window area shows IDT descriptors. Within an LDT/GDT or IDT window, you may scroll through descriptor table entries. These windows are browsing windows and do not allow you to edit the descriptor table entries. Note: The LDT/GDT and IDT windows are not available for display while ASDT is operating in real mode. ═══ 1.4.2. Moving Among Windows ═══ A set of ASDT commands is available to move among all of the ASDT windows. Moving among the different windows changes the primary window. In a disassembly or memory window, the primary window type is displayed near the top right corner of the ASDT screen. In an LDT/GDT or IDT window, the primary window type is on the left side, near the middle of the ASDT screen. Use the following commands to switch windows: MW (switch to memory), LW (switch to LDT/GDT), VW (switch to IDT), and DW (switch to disassembly). To toggle among the windows, use the NW (Next Window) command or press the F4 key. On entry, the primary window is disassembly. ═══ 1.4.3. Moving in the Disassembly and Memory Windows ═══ The disassembly and memory windows are edit windows. ASDT recognizes commands on the command line and the following function keys while editing these window areas: Enter Moves the cursor to the beginning of the command line and executes the commands on the command line. Home Moves the cursor to the beginning of the command line but does not execute the commands on the command line. Up Arrow Moves the cursor up one line. When the cursor reaches the top of the window, it wraps around to the bottom line. Down Arrow Moves the cursor down one line. When the cursor reaches the bottom of the window, it wraps around to the top line. Left Arrow Moves the cursor left to the next position where ASDT accepts keystrokes. When the cursor reaches the beginning of a line, it wraps to the end of the previous line. Right Arrow Moves the cursor right to the next position where ASDT accepts keystrokes. When the cursor reaches the end of a line, it wraps to the beginning of the next line. Ctrl-Left Arrow Scrolls the window up one byte. Ctrl-Right Arrow Scrolls the window down one byte. PgUp Scrolls the window up the number of lines in the segment. PgDn Scrolls the window down the number of lines in the segment. Ctrl-PgUp Scrolls the window up one line. Ctrl-PgDn Scrolls the window down one line. Tab Moves the cursor right to the next column. The cursor wraps as it does with the Right Arrow. Back Tab Moves the cursor left to the previous column. The cursor wraps as it does with the Left Arrow. Spacebar Functions similarly to the Right Arrow except that the Spacebar is a valid data key when entering character data. Backspace Functions similarly to the Left Arrow. Del Deletes the window in which the cursor is located and combines it with the previous window. If only one window exists, no action is taken. Shift Shifts to upper case and reverses the effect of Caps Lock. Caps Lock Shifts to upper case for the alphabetic keys. Ctrl-Home Moves the cursor to the beginning of the command line and erases the entire command line. PrtSc Causes the ASDT screen to be printed. The LDT/GDT and IDT windows are browse windows. ASDT recognizes commands on the command line and the command line function keys while browsing these window areas. See Moving on the Command Line for a list of these keys. When the window area is being used by the Compare Memory (CM) function, different sets of function keys are available. See CM - Compare Memory for details. ═══ 1.4.4. Altering Disassembly and Memory ═══ Creating Windows A new window is created by entering a new address for the desired line. This is done by typing over the old address or by entering one of the L1-M6 commands on the command line. ASDT defines that line as the first line of a disassembly or memory window. ASDT displays an asterisk at the left of the address to indicate that the line begins a new window. The end of any window is determined by the first line of the following window. An "opposite mode" window segment is created by entering an MW or DW command on the command line if you are in a disassembly or memory window mode. For example, to create a memory window segment in the disassembly window at line L8, enter MW L8 on the command line. To create a disassembly window segment in the memory window at line M2, enter DW M2 on the command line. Altering Data within a Window You can alter disassembled instructions with hexadecimal input. To do this, move the cursor to the appropriate byte in the hex area and type over the data that is displayed. Each keystroke results in a modification of the instruction; that is, ASDT updates the instruction as each hexadecimal digit is entered. You can alter memory with hexadecimal or character input. To do this, move the cursor to the appropriate byte in either the hex or the character area and type over the data that is displayed. Each keystroke results in a modification of memory; that is, one nibble is modified for each hexadecimal digit entered, and one full byte is modified for each character entered in the character area. ASDT updates a window area line under any of the following conditions: o The cursor is on the window line. o The window containing the line is assigned an address. For example, if there is only one window, the command "L1=L1" will result in all lines being updated. o Any command that results in user program execution: EX or ST. To prevent unintentional data alteration, ASDT will not move the cursor from the address area to the hexadecimal area when a character key is pressed. Use one of the cursor keys or the space bar to move the cursor into the hexadecimal display area from the address area. Deleting a Window Delete a disassembly or memory window and combine it with the previous window by pressing the Del key with the cursor anywhere in the window or by entering the appropriate L1-M6 command without a parameter. When the primary window is disassembly, the DW command deletes the memory window segment if present. When the primary window is memory, the MW command deletes the disassembly window segment if present. ═══ 1.5. Setting Breakpoints ═══ ASDT provides permanent, complex, and procedure step breakpoints. On each of the nine ASDT display screens, you can have up to eighteen permanent or complex breakpoints or up to seventeen permanent or complex breakpoints and one procedure step breakpoint. ═══ 1.5.1. Permanent Breakpoints ═══ The permanent breakpoints are divided into primary and secondary groups. The primary group is named S1 through S9, and the secondary group is named V1 through V9. The difference between the S group and the V group is that the S breakpoints default to an "on" or active condition when set, and the V breakpoints default to an "off" or inactive condition when set. V breakpoints must be specifically turned on to become active. The breakpoints are divided this way to give you visible breakpoints and scratch pad space on each screen. Since nine active breakpoints are usually enough for a given debug session, the nine inactive breakpoints serve as scratch pad variables to hold intermediate calculations or base addresses. Usually, you will use V1 through V9 as scratch pad variables and S1 through S9 as breakpoints. However, if you need more breakpoints on a screen, you can turn any of the V variables on so that it becomes an active breakpoint. ═══ 1.5.2. Procedure Stepping ═══ ASDT provides a single temporary breakpoint which is used as a procedure step or module step facility. This function is provided on a function key (F9) because it consists of several ASDT commands. The procedure step is performed by setting a breakpoint at the instruction following the current instruction, executing, and then removing the breakpoint. You will use the procedure step most frequently for CALL, INT, and REP instructions. If you are stepping through your program and you reach one of these instructions, the procedure step command sequence "S9=EX+IL;EX;S9" will execute the subroutine or block of code and stop at the instruction following the CALL, INT, or REP instruction. This uses breakpoint S9 as a substitute for an automatic module step function. This function is assigned to function key F9. If you plan to use the built-in procedure step function, you should not set a breakpoint in S9 since it will be replaced by the procedure step breakpoint. Of course, you can set other breakpoints as procedure step breakpoints yourself by issuing the appropriate commands. ═══ 1.5.3. Breakpoint Addresses ═══ ASDT supports two types of breakpoints. A breakpoint can be either a 6-higit physical address or a selector:offset address. ASDT displays breakpoints in a relative address format whenever possible. If the breakpoint address is not more than 64KB greater than the active code origin (CO) address, ASDT displays the breakpoint as an offset preceded by a "$." Otherwise, if the same condition is true for CS, ASDT displays the breakpoint as an offset preceded by a "+." If ASDT can not display a selector:offset breakpoint address as an offset of either the CO or the CS, then ASDT displays this breakpoint as an offset preceded by a "*." All inactive selector:offset breakpoint addresses are displayed as an offset preceded by a "?." Physical addresses that can not be displayed as an offset of either the CO or the CS are shown in a 6-higit format. Inactive physical address breakpoints are always displayed in the 6-higit format. Null breakpoints are displayed as "......" Note: When in real mode, you will set segment:offset breakpoints and physical address breakpoints. The physical address breakpoints will be limited to 5 higits even though they will be displayed as 6 higits. ═══ 1.5.4. Complex Breakpoints ═══ You can change any active ASDT breakpoint to a complex breakpoint with the CB command. Complex breakpoints have an optional condition and an optional count. You will use complex breakpoints most often to stop when your program meets a particular condition or when it executes the nth occurrence of a particular instruction. Counts are also useful inside loops. You can have both complex breakpoints and regular breakpoints set at the same time. For each complex breakpoint, ASDT takes the breakpoint only when its condition and count satisfy the requirements. Otherwise, it returns control to your program for further execution. To set a complex breakpoint, you must first have an active breakpoint. You create an active breakpoint with the appropriate V1-V9 or S1-S9 command. Then you use the CB command to add a condition and a count to the breakpoint to make it complex. You can display the current condition, count, and occurrence count for a complex breakpoint by issuing the CB command with the breakpoint name as an operand; i.e., "CB S5." ASDT will display the breakpoint's condition and count on the command line so you can change them and reenter them easily. It also displays the occurrence count, or the number of times the complex breakpoint has been hit, on the message line. ═══ 1.5.5. Multi-process, Multi-thread Breakpoints ═══ All breakpoints that are set are maintained across all processes and threads that are running. You can deactivate a breakpoint that is set for one process or thread while ASDT has control over some other process or thread. Similarly, you can reactivate a breakpoint that belongs to another process or thread. See S1-S9 - Set Breakpoints S1-S9 and D1-D9 - Select Display for details on how to deactivate and reactivate breakpoints. Pay particular attention to the caveats given. ═══ 1.5.6. Sticky Breakpoints ═══ You can force ASDT to stop on every occurrence of a breakpoint by using the SB command. This sticky nature is usually reserved for physical address breakpoints and GDT virtual address breakpoints. See the SB - Sticky Breakpoint command for more information. ═══ 1.6. 80386 Hardware Debug Registers ═══ In addition to the V1-S9 breakpoints, ASDT allows you to set the 80386 hardware debug registers (assuming that you are running on an 80386). The debug registers support both instruction and data breakpoints and can pinpoint when a data item (for example) is altered. See T0 - Suspend/Reactivate 80386 Hardware Debug Registers and T1-T4 - Set 80386 Hardware Debug Registers for details on how to set/reset and arm/disarm these 80386 debug registers. ═══ 1.7. Indirect Addressing ═══ In addition to numeric values and ASDT variables, you can use indirect addressing to reference the contents of memory. This allows you to examine and use memory contents without having to look at the memory locations directly using the various ASDT windows. ═══ 1.7.1. How to Use Indirect Addresses ═══ ASDT distinguishes indirect addresses by a trailing "%" and an optional length. The syntax for an indirect address is: target = expr %L where: target = the variable or register you wish to change, expr = an ASDT expression for an address, % = the trigger for an indirect address, and L = the number of bytes you want to reference. Valid values for L are 1, 2, and 4. If you do not specify any value for L, then L defaults to 1. If L is 4, ASDT treats the 4 bytes in memory as a 4-byte (selector:offset) pointer. L must follow immediately after the "%." ═══ 1.7.2. Indirect Addressing Examples ═══ The following examples illustrate various ways you can use indirect addresses: AX = DS:SI %2 uses (DS:SI) -> memory for 2 bytes. AH = DS:SI % uses (DS:SI) -> memory for 1 byte. S1 = SS:BP%4 uses (SS:BP) -> memory for 4 bytes. BL = DS:SI %4 % uses (DS:SI) -> memory to get a selector:offset pointer, which will in turn be used to access 1 byte of memory. ═══ 1.8. Hints for Using ASDT ═══ ═══ 1.8.1. Profile Use ═══ ASDT will read a profile from disk if you specify the profile name in the CONFIG.SYS file. The Execute Profile (EP) command is used to execute the commands in the profile. You can put any valid ASDT command or string of commands into a profile. Suggested commands include Define Key (DK) commands that define function keys that don't have defaults, commands to set up the display and colors as you want them, and common ASDT commands you use each time you debug a program. ═══ 1.8.2. Disassembly ═══ ASDT provides a single instruction disassembly function even when you don't have a disassembly window shown. The disassembly of the next instruction to be executed, identified by the "EX" display, is always shown. If you set the primary window to disassembly, then disassembled instructions are shown beginning at L1, and ASDT will track the next instruction to be executed and will always display it at L1. You can indicate whether ASM86 or Intel mnemonics are to be used by using the DA (Disassemble ASM86) or the DM (Disassemble MASM) command. If the instruction has an operand which references memory, the operand address is calculated and displayed as the OP variable. The non-displayed Instruction Length (IL) variable contains the length of the current instruction in bytes. You can use the variables OP and IL as command operands. For example, use the command L1=OP to display the contents of memory at the current instruction's operand address. This is the same operand address shown at the right side of the first instruction in the disassembly window. Use the IL variable when procedure stepping, as in "S9=EX+IL;EX;S9," which sets a breakpoint at the instruction following the one about to be executed. The disassembly function shows the instruction when a breakpoint is set. The disassembly indicates that you have set the breakpoint at the proper place and should help prevent inadvertent breakpoints in the middle of instructions. If a breakpoint is placed in the middle of an instruction, the breakpoint will not be hit during normal execution, and the instruction will probably be changed so that it executes incorrectly. ═══ 1.8.3. Display Screens and Breakpoints ═══ A useful debugging technique is to use a different ASDT display (D1-D9) for each program (process) or code segment (CSECT or thread) being debugged. You can switch from screen to screen and can also save the contents of one screen into another. On each screen, the CO, breakpoints, disassembly locations, and memory locations are unique. The registers and flags are the same across screens. When an EX or ST command is executed, and the processor is subsequently stopped by a breakpoint, the ASDT display screen containing that breakpoint is automatically displayed. If the processor is stopped by something other than a breakpoint, the ASDT display that was active at the time of the EX or ST remains active. Each of the nine displays has nine V breakpoints and nine S breakpoints available, which provides a total of 162 possible breakpoints. The S breakpoints are turned on when set, but the V breakpoints are not turned on until set on with a command. This gives the V breakpoints visible scratch pad function. ═══ 1.8.4. Viewing Other OS/2 Sessions ═══ Viewing other OS/2 sessions while under ASDT requires a few steps. First, you need to issue the HT command. After the current thread has been halted, you can then enter Alt-Esc keystrokes to locate a specific session (your host 370 session included). If you choose to switch to your host 370 session, you could view listings of the halted thread. The Ctrl-Esc sequence will enable you to begin another session at this point, too. Returning to ASDT requires a few steps as well. First, you need to enter Alt-Esc keystrokes to get back to the screen group that contains the halted thread. Then you can depress the hot key (if it is enabled) to reenter ASDT. Finally, you should issue the RT command to allow the halted thread to resume. Note: You should realize that when you halt a thread under ASDT, other threads will still be running. If any of these threads cause an ASDT-trapped event, ASDT will get control again. Additionally, the "complexion" of your ASDT environment may have changed somewhat when you return to ASDT since other processes are running. ═══ 1.8.5. Multiple Screens ═══ ASDT can be moved to the secondary terminal (if you have two adapters attached) with the "CG MS" command. Your application will be displayed on one of your two terminals. ASDT knows to display its screen on the opposite terminal when you issue the "CG MS" command. To tell ASDT to use multiple screens from its invocation, use the /M parameter. See CG - Configuration for more information about multiple screens. The "CG MS" command can be placed in a profile or can be assigned to a function key. ═══ 1.8.6. Remote Terminal ═══ ASDT can be moved to a remote terminal (if you have one connected via a COMn port (n=1 or 2)) with the "CG RT n" command. Your application will be displayed on the host machine's terminal. ASDT knows to display its screen on the remote terminal when you issue the "CG RT n" command. To tell ASDT to use a remote terminal from its invocation, use the /R=n parameter. See CG - Configuration for more information about remote terminals. The "CG RT n" command can be placed in a profile or can be assigned to a function key. ═══ 1.8.7. User-defined Functions ═══ ASDT will allow you up to nine user-defined functions that you can call from within ASDT. When ASDT gives control to a user-defined function, that routine is running as a level 3 application. Hence, you can use these routines to call OS/2 I/O service routines that ASDT can not call from level 0. A potential function for these routines is to perform some sort of statistical tracking for a particular session. All user-defined routines (U1-U9) must reside in the dynamic load library, UX.DLL. You can create your own UX.DLL or substitute members for the one that comes with ASDT. If you use the UX.DLL that comes with ASDT, then you can use the command "U2 SC" to have ASDT print its screen to the file ASDT.OUT. See U1-U9 - User-defined Functions for additional information concerning user-defined functions. ═══ 1.9. ASDT Command Reference ═══ This section describes each of the available ASDT commands. Commands are listed alphabetically except for command groups, which are at the beginning of the list. These groups are the general register commands, the selector register commands, the specific register commands, the flag commands, and the vector commands. In many cases, a command description will apply to a set of commands. For example, the commands V1, V2, ..., V9 are described under the command format "V1-V9." ═══ 1.9.1. AX BX CX DX AH AL BH BL CH CL DH DL - General Register ═══ Purpose: Alters the contents of the specified processor register. Format: reg [= expr] reg Any of AX, BX, CX, DX, AH, AL, BH, BL, CH, CL, DH, or DL. expr Any ASDT expression. Examples: AX = 13B Places '013B'x into the AX register. CX = V1 + BX - 2 Places the sum of the contents of variable V1, the BX register, and -2 into the CX register. DX = DS Copies the contents of the DS register into the DX register. CL = DH Copies the contents of the DH register into the CL register. Remarks: You can alter the general registers (AX, BX, CX, and DX) in their entirety or as 8-bit registers (AL, AH, BL, BH, CL, CH, DL, and DH). ASDT uses only the least significant 16 bits or 8 bits that result from an expression evaluation to set the 16-bit or 8-bit register. ASDT truncates any additional bits and displays a warning message. A null operand sets the register to zero. ═══ 1.9.2. CS DS SS ES - Selector Register ═══ Purpose: Alters the contents of the specified selector register. Format: reg [= expr] reg Any of CS, DS, SS, or ES. expr Any ASDT expression. Examples: CS = 1C42 Places the hexadecimal value '1C42' into the CS register. ES = SS Copies the contents of the SS register into the ES register. DS = XS Copies the contents of the XS selector register variable into the DS register. Remarks: To save and restore selector register contents, use the XS selector register variable. ASDT treats XS just like a real selector register. Updating the CS register also updates the EX and LC displays. A null operand sets the selector register to zero. ═══ 1.9.3. SI DI SP BP - Specific Register ═══ Purpose: Alters the contents of the specified processor register. Format: reg [= expr] reg Any of SI, DI, SP, or BP. expr Any ASDT expression. Examples: BP = 13B Places '013B'x into the BP register. SI = V1 + BX - 2 Places the sum of the contents of variable V1, the BX register, and -2 into the SI register. Remarks: ASDT uses only the least significant 16 bits that result from an expression evaluation to set the register. ASDT truncates any additional bits and displays a warning message. Updating the IP register also updates the EX and LC displays. A null operand sets the register to zero. ═══ 1.9.4. FL AF CF DF IF OF PF SF TF ZF - Flag Register ═══ Purpose: Alters the contents of the processor flag register. Format: flag [= expr] flag Any of FL, AF, CF, DF, IF, OF, PF, SF, TF, or ZF. expr Any ASDT expression. Examples: CF = 0 Sets the carry flag bit to '0'b. FL = F246 Sets the flag register to 'F246'x. Remarks: The FL command is used to alter the contents of the entire flag register. The command operand is evaluated, and the least significant 16 bits of the evaluation are placed into the FL register. ASDT truncates any additional bits and displays a warning message. A null operand sets the entire register to zero. The remaining commands are used to alter individual bits within the flag register. If the command operand is null or evaluates to zero, ASDT sets the flag bit to zero; otherwise, it sets the flag bit to one. ═══ 1.9.5. AS - ASCII ═══ Purpose: Changes the current character translation to ASCII. Format: AS Examples: AS All characters are displayed in ASCII format. Remarks: Changes the characters displayed in the right side of the memory area and the interpretation of the Code Origin CSECT name. The current character translation mode (ASCII or EBCDIC) is shown on the top line near the right of the screen. Initially, the screen is in ASCII format. Choices are ASCII and EBCDIC (EB). ═══ 1.9.6. CA - Color Attributes ═══ Purpose: Sets the specified color attribute to the given value. Format: CA [term] [value] term one of the following: N Normal attribute. H Highlight attribute. R Reverse attribute. value The hexadecimal color code. The range of the number is '00'x to 'FF'x where the first higit describes the background color and the second higit describes the character color. Examples: CA N 07 ASDT sets the normal attribute to white on black. CA H 4F ASDT sets the highlight attribute to bright white on red. CA R 71 ASDT sets the reverse attribute to blue on white. CA ASDT sets the normal, highlight, and reverse attributes to their default values. Remarks: The CA command has no function when ASDT is on a monochrome display. Defaults: normal screen text is defaulted to bright white on blue (1F), highlighted text defaults to yellow on blue (1E), and reverse video text is red on white (74). The majority of the ASDT screen is in normal text. Highlighting is used to signal items such as an active breakpoint or the code origin name. Reverse video is used to signal events such as a breakpoint encountered. Make sure you do not set a character color equal to its background color; parts of the screen will be impossible to read if this occurs. If this happens for the normal attribute, the screen will go blank, but ASDT will still be functioning. To read the screen again, type CA and enter it even though you can't see it. This resets ASDT's color attributes to their default values. The following chart shows the available colors and their numbers: Number Color Number Color ------ ----- ------ ----- 0 Black 8 Gray 1 Blue 9 Light Blue 2 Green A Light Green 3 Cyan B Light Cyan 4 Red C Light Red 5 Magenta D Light Magenta 6 Brown E Yellow 7 White F High intensity White ═══ 1.9.7. CB - Complex Breakpoint ═══ Purpose: Sets an active breakpoint as a complex breakpoint with optional condition and count, displays the current condition and count, or displays all complex breakpoints. Format: CB [ bkpt ] [ cond ] , [ count ] bkpt Any ASDT breakpoint (V1-V9 or S1-S9) that is active on the current ASDT display screen. cond An expression for a condition to be satisfied before ASDT takes the breakpoint. count Any expression for the number of times for ASDT to hit the breakpoint before it takes the breakpoint. Examples: CB S1 AX = 3 , 10 Sets S1 as a complex breakpoint. The condition to be met is for AX to equal three, and ASDT will take the breakpoint the sixteenth time this occurs at the S1 breakpoint's address. CB V3 ES:DI <> DS:SI Sets V3 as a complex breakpoint. The condition to be met is for the contents of ES:DI not to equal the contents of DS:SI. ASDT will take the breakpoint the first time this occurs at the S1 breakpoint's address. CB Displays all eighteen breakpoints for the current ASDT display screen and shows complex breakpoints with their conditions, counts, and occurrence counts. CB V8 Displays the condition and count fields for breakpoint V8 on the command line so you can edit them and reenter them. Also displays the current occurrence count for V8 on the message line. Remarks: You can create a complex breakpoint from any active breakpoint. For introductory information about complex breakpoints, see Setting Breakpoints. You use the CB command to create a new complex breakpoint, modify an existing complex breakpoint, return a complex breakpoint to a simple breakpoint, and to display all of the complex breakpoints for the active ASDT screen (D1-D9). If you issue the CB command without any operands, ASDT replaces the ASDT screen with a complex breakpoint window. This display replaces the ASDT screen with complex breakpoint information. The complex breakpoint window displays each possible complex breakpoint (V1-V9 and S1-S9). For each active breakpoint that is complex, the address, condition, count, and occurrence count are all displayed. For each active simple breakpoint, the address is displayed. This screen is a "browse" window that does not allow you to edit anything. Tapping any key restores the ASDT screen. ═══ 1.9.8. CG - Configuration ═══ Purpose: Define the display configuration to use. Format: CG [= term] term one of the following: null reset to single screen. MS use multiple screens. RT n use COMn (n=1 or 2) to communicate with a remote terminal. Examples: CG MS Changes ASDT to the color display if the monochrome display is the primary display; changes ASDT to the monochrome display if the color display is the primary display. CG RT n Has ASDT write its screen to a remote terminal using the COMn port (n=1 or 2). CG Changes ASDT to the primary display. Remarks: The CG MS command switches between displays if you have more than one monitor installed. Make sure you do not use this command if you have only one display adapter. If this happens, ASDT will issue an error message and will not use multiple screens. The use of multiple screens can be set at ASDT installation time with the /M option as well. With this option, you will have ASDT using the secondary display when it gains control. Issuing the CG (null) command will always cause ASDT to share the primary display with your application. The CG RT n command switches ASDT to a remote terminal that you have hooked up via the COMn port (n=1 or 2). This serves a similar function to that of CG MS. However, CG MS can not be used with a PS/2 as it does not support multiple adapters. It is up to you to set the baud rate or any other communication parameters as ASDT only writes to the COMn port. It is useful to place a command like MODE COM1:19200,E,7,1 in your STARTUP.CMD even though you may change the mode under OS/2 at any time. The use of a remote terminal can be set at ASDT installation time with the /R=n option as well. With this option, you will have ASDT using the remote terminal when it gains control. Issuing the CG (null) command will always cause ASDT to collapse back to the display of your application. ═══ 1.9.9. CM - Compare Memory ═══ Purpose: Compares two memory blocks and displays the differences between them. Format: CM [addr1] , [addr2] , [length] addr1 Any ASDT expression for the starting address of one memory block. addr2 Any ASDT expression for the starting address of the other memory block. length Any ASDT expression for the number of bytes to compare. Examples: CM SS:BP , SS:BP+100 , 100 Compares 256 bytes from the location specified by SS:BP with the same number of bytes from the location specified by SS:BP+100. The first 112 bytes of each area are shown on the screen, and mismatches are highlighted in the first area. The function keys described below are active. CM 123456,236541,16. Compares 16 bytes from physical location 123456 with the same number of bytes from physical location 236541. The function keys described below are active. Remarks: ASDT displays the two compared areas on the screen beginning at addresses L1 and L8. Differences between the two areas are highlighted in the first area. Seven lines of each memory area are shown on the screen, and the number of mismatches on the screen and in the entire area are shown on the message line. You can scroll the window up and down in the compared areas. ASDT recognizes the following function keys in Compare Memory mode: Esc Returns to normal ASDT operation and restores the edit area of the screen. Home Scrolls the compare window up to the beginning of the compare field. PgUp Scrolls the compare window up one screen (seven lines). PgUp takes no action if the first byte of the compare field is displayed. PgDn Scrolls the compare window down one screen (seven lines). PgDn takes no action if the last byte of compared memory is displayed at the beginning of the display area. Ctrl-Left Arrow Scrolls the compare window up one byte. Ctrl-Left Arrow takes no action if the first byte of the compare field is displayed. Ctrl-Right Arrow Scrolls the compare window down one byte. Ctrl-Right Arrow takes no action if the last byte of compared memory is displayed at the beginning of the display area. ═══ 1.9.10. CO - Code Origin ═══ Purpose: Tells ASDT your program's starting address so that ASDT can compute and display a Location Counter which corresponds to your assembly listing. Format: CO [= expr] expr Any ASDT expression. Examples: CO = CS:A426 indicates that your module begins at offset A426 from your program's code segment. ASDT displays the CO as "+A426." CO = CS:200 indicates that your module begins at offset 200 from your program's code segment. ASDT displays the CO as "+0200." Remarks: The CO facility enables you to think in terms of your assembly listing without having to do relocation arithmetic. ASDT displays the Code Origin in a relative address format if possible. Relative addresses are designated with a "+" for CS. If the CO was set with a selector:offset expression and the CO selector is the same as the CS selector, then the CO will be displayed as an offset preceded by a "+." Otherwise, a CO that was set with a selector:offset expression will be displayed in the selector:offset format. If the CO was set with a physical address expression and this physical address is less than 64K greater than the CS base address, then the CO will be displayed as an offset preceded by a "+." Otherwise, a CO that was set with a physical address expression will be displayed in a 6-higit address format. A null CO is displayed as "....:....." See Setting Breakpoints for more information. If the CSECT begins with a JUMP instruction around the name of the CSECT as shown below, the name will be displayed following the CO display. ASDTSMP CSECT J LABEL1 DC AL1(8) DC S'ASDTSMP ' LABEL1 DS 0C . . . A null operand sets the CO variable to null. Whenever CO is set, ASDT looks to see if the memory location specified contains a short jump instruction. If this instruction is found, ASDT assumes that the CSECT name follows 3 bytes further. ASDT will then display this CSECT name (up to 8 characters) in ASCII or EBCDIC depending on the current display mode. ═══ 1.9.11. CP - Copy Memory ═══ Purpose: Copies one memory block to another. Format: CP [addr1] , [addr2] , [length] addr1 Any ASDT expression for the starting address of the source memory block. addr2 Any ASDT expression for the starting address of the target memory block. length Any ASDT expression for the number of bytes to copy. Examples: CP DS:100 , DS:200 , 30. Copies 30 bytes from the location specified by DS:100 to the location specified by DS:200. CP L1 , L1+1 , 100 Makes 256 copies of the character at the memory location addressed by L1 filling the memory bytes which start at L1+1. This can be used as a "fill memory" function. Remarks: The Copy Memory function allows the source block and target block to overlap, so you could make changes that you don't expect if you specify blocks that overlap. An easy way to fill a block of memory with a specific character is to set L1 to point to the first byte, change the first byte to the character wanted, and then issue the command "CP L1,L1+1,length" where you specify the number of copies wanted for the length field. You may wish to compare two memory blocks after one has been copied to the other. (See CM - Compare Memory.) ═══ 1.9.12. CT - Step Count ═══ Purpose: Sets the default step count (the number of user program instructions to execute with the ST command). Format: CT [= expr] expr Any ASDT expression. Examples: CT 8 ASDT sets the step count to eight. CT ASDT sets the step count to one. Remarks: ASDT uses only the least significant 16 bits that result from an expression evaluation to set the CT. ASDT truncates any additional bits and displays a warning message. When you enter the ST command without an operand, ASDT gets the number of user program instructions to be executed from the CT variable. If the operand is omitted from the CT command, ASDT sets the step count to one. ═══ 1.9.13. DA - Disassemble ASM86 ═══ Purpose: Changes the current disassemble mode to IBM ASM86 format. (ASM86 is an IBM Internal cross assembler, not provided with this program). Format: DA Examples: DA Instructions will be disassembled using IBM ASM86 mnemonics. Remarks: Disassembles the instructions pointed to by CS:IP using IBM ASM86 mnemonics. Initially, all disassembled instructions are shown in IBM ASM86 mnemonics. Choices are IBM ASM86 mnemonics (DA) or Intel (MASM) mnemonics (DM). ═══ 1.9.14. DK - Define Key ═══ Purpose: Sets up, changes, or removes a function key definition. Format: DK [key I/D [cmds]] key The key to be defined (F1, F2, ..., F10, S-F1, S-F2, ..., S-F10, C-F1, C-F2, ..., C-F10, A-F1, A-F2, ..., A-F10). I Place the commands on the command line and execute them immediately when the function key is pressed. D Place the commands on the command line when the function key is pressed but do not execute them. cmds A string of valid ASDT commands entered as you would enter them on the command line. This string may contain semicolons, and the first command may begin with a slash. Examples: DK S-F9 I DM ASDT sets the Shift-F9 (S-F9) key to the string "DM." Each time the S-F9 key is pressed, ASDT shows disassembled instructions in Intel (MASM) mnemonics. DK A-F2 D DA ASDT sets the Alt-F5 (A-F5) key to the string "DA." Each time the A-F5 key is pressed, ASDT puts this string on the command line. DK C-F1 ASDT removes any command definition for the Ctrl-F1 (C-F1) key. You do not use the I/D keyword when removing a key definition. DK ASDT displays the current settings of all of the function keys. Remarks: ASDT supports the function keys F1 through F10, shifted function keys S-F1 through S-F10, controlled function keys C-F1 through C-F10, and alternate function keys A-F1 through A-F10. This provides a total of 40 function keys. ASDT provides default definitions for keys F1 through F10. You can change these by redefining the key(s) you want to change. The definitions are listed in Function Keys If you want to redefine existing keys or define additional ones, you can include DK commands in the profile you invoke when you start ASDT. You must enter the I (immediate) or D (deferred) keyword when you define a key. It is not required when you remove a key definition. If you press a function key which has no definition, ASDT displays a message and takes no other action. ASDT maintains an 800-byte buffer for commands associated with function keys. If you define many keys to be long commands, it is possible to run out of room in the buffer. If this happens, ASDT will display a message, and you will not be able to make any additional key definitions in the current ASDT session. You can still use keys that are already defined and can redefine existing keys. ═══ 1.9.15. DM - Disassemble MASM (Intel) ═══ Purpose: Changes the current disassemble mode to the Intel (MASM) format. Format: DM Examples: DM Instructions will be disassembled using Intel (MASM) mnemonics. Remarks: Disassembles the instructions pointed to by CS:IP using Intel (MASM) mnemonics. Initially, all disassembled instructions are shown in ASM86 mnemonics. Choices are IBM ASM86 mnemonics (DA) or INTEL (MASM) mnemonics (DM). ═══ 1.9.16. DW - Disassembly Window ═══ Purpose: Switches to Disassembly Window mode. Format: DW [value] value The line number (L1-M6) at which to start the disassembly window. Examples: DW ASDT switches the edit portion of the ASDT display to a disassembly window and sets the primary window mode to disassembly. If a secondary memory window is displayed, ASDT removes it. DW M1 ASDT switches lines M1 through M6 of the ASDT display to show disassembled instructions. The primary window mode of ASDT is not changed. Remarks: The disassembly window displays instructions in both hexadecimal and disassembled format. If applicable, ASDT also displays the operand of the instruction. ASDT displays the primary window (disassembly or memory) in the upper right portion of the ASDT screen. If the primary window is disassembly, then L1 and the following disassembly lines track the current CS:IP as your program runs. ASDT also tracks CS:IP for a secondary disassembly window. Initially, the primary window is disassembly. See the MW - Memory Window command, which changes to a memory window and the NW - Next Window command, which switches among all of the ASDT windows. ═══ 1.9.17. D1-D9 - Select Display ═══ Purpose: Selects or sets one of the nine ASDT display screens. Format: Dn [Ds or ON or OFF] n Any of 1-9. Indicates which screen is being selected (D1-D9). s Any of 1-9. Indicates which screen is being saved (D1-D9). ON Activates the breakpoints for Dn. OFF Suspends the breakpoints for Dn. Examples: D4 OFF All the active breakpoints for screen D4 are suspended. D5 Screen D5 is selected as the active ASDT screen. D2 = D1 The contents of screen D1 are saved in screen D2. Remarks: These variables are common to all nine displays: registers, memory, M7-M9, and step count. These variables are unique to each display: V1-V9, S1-S9, L1-L9, M1-M6, and CO. After ASDT has finished executing a block of user instructions, it will display the screen containing the active breakpoint that terminated the execution. If more than one screen contains that same active breakpoint, ASDT will display the lowest numbered screen. The breakpoints of a screen (e.g., Dy) do not have to be activated when ASDT is displaying another screen (e.g., Dx) unless they had been deactivated previously; that is, when you switch screens from Dy to Dx, Dy's breakpoints remain active. Note: When you issue a Dn ON command, the breakpoints for the Dn screen are associated with the current process and thread ids. This was implemented in this manner so that you could reactivate breakpoints for an entire screen whose breakpoints had become deactivated due to a thread's or process's having terminated. This is different from the results that you would get if you issued Sn ON commands for the various deactivated breakpoints on the current screen. See S1-S9 - Set Breakpoints S1-S9 to learn how reactivating breakpoints with the Sn ON command differs from the Dn ON command. Note: You can not deactivate or reactivate a virtual real mode breakpoint while in protected mode and vice versa. Additionally, you can not deactivate or reactivate a physical address breakpoint that is above the 1M line in real mode. See Display Screens and Breakpoints for a discussion of how to use the nine ASDT display screens to your advantage. ═══ 1.9.18. EB - EBCDIC ═══ Purpose: Changes the current character translation to EBCDIC. Format: EB Examples: EB All characters are displayed in EBCDIC format. Remarks: Changes the characters displayed in the right side of the memory area and the interpretation of the Code Origin CSECT name that may be displayed. The current character translation mode (ASCII or EBCDIC) is shown on the top line near the right of the screen. Initially, the screen is in ASCII format. Choices are ASCII (AS) and EBCDIC. ═══ 1.9.19. EP - Execute Profile ═══ Purpose: Executes a profile containing a series of ASDT commands. This profile must have been read in by ASDT during the initialization phase. Format: EP Examples: EP Executes commands from ASDT's profile storage area. Remarks: ASDT does not support disk I/O after the OS/2 initialization phase. Hence, you must have ASDT read your profile in during this initialization phase. ASDT stores your profile in its internal data area where your commands can be retrieved and executed with the EP command. To have ASDT read in your profile, you need to specify the fully qualified profile name in your CONFIG.SYS file. You can specify ASDT parameters along with a profile name. See Installing ASDT for the syntax rules that allow you to specify a profile and ASDT parameters. ASDT limits a profile to 1600 bytes. This includes carriage returns, line feeds, and end-of-file markers. ASDT does not recognize tabs and can not process commands that are greater than 76 characters long (not including trailing blanks, carriage return, and line feed). Commands from a file are executed one at a time. If an invalid command is encountered, the appropriate ASDT message is displayed, and profile processing is aborted. You can execute a profile that has been read in as often as you like by reissuing the EP command. ═══ 1.9.20. EX - Execute ═══ Purpose: Passes control of the processor to your program. Format: EX Examples: EX Gives control to your program, which begins executing at the current CS:IP. Remarks: Execution of your program begins at the point determined by the sum of the CS and IP registers. ASDT restores your display screen and sets active breakpoints in your program before execution begins. Control is retained by OS/2 until ASDT receives an interrupt. When ASDT regains control, you are shown the reason in the form of a message or breakpoint highlight. ASDT saves your display screen and removes the breakpoints from your program. The processor registers and memory display reflect the processor status at the time of the interrupt. If any breakpoints were overlayed by execution of your program, the breakpoint display is blinked to indicate that that breakpoint was not active for a portion of your program execution. Note: The first instruction of your program is single-stepped before the breakpoints are inserted. This permits execution to begin at the point of a breakpoint without stopping immediately. ASDT sets function key F7 to the EX command on entry. ═══ 1.9.21. F FA FC FE FX - Find, Find ASCII, Find CSECT, Find EBCDIC, Find Hex ═══ Purpose: Find character or hexadecimal strings in memory. Format: Ft [ string ] [ , s ] [ , hiaddr ] t Type of find (one of the following): null current mode (ASCII, CSECT, hex, or EBCDIC) A ASCII C CSECT E EBCDIC X Hex string The string to be found in memory. This string may be delimited by quotes (" "). s Search technique (one of the following): * task search (LDT first then the GDT (only in protected mode)) expr any ASDT expression that determines a selector for the single segment to search. If ", hiaddr" is specified, then this "s" expression is interpreted as the lower bound physical address of a system-wide search range. hiaddr any ASDT expression that is interpreted as the higher bound physical address of a system-wide search range. Examples: /FX 123E4 Does a repeat find of the '0123E4'x search argument throughout the task's immediate segment register areas. /FA buffer; L1 = FX Does a repeat (task) find of the ASCII-string (buffer) and displays memory beginning at the location where the string was found. FE "Top of Data" , DS Tries to find the EBCDIC-string (Top of Data) in memory beginning at the start of the DS segment up to its segment limit. FA " garbage dump ", * Tries to find the ASCII-string ( garbage dump ) in memory using the task search technique. FC SINT3, CS Tries to find the CSECT name (SINT3) in the current CS segment. FC AINTHND, 000000, 400000 Tries to find the CSECT name (AINTHND) in the system-wide address range starting at physical address 0 and ending at physical address 4M. FC - Tries to find the closest (previous) CSECT address relative to the current CS and IP address. Remarks: Task searching is employed for all finds until you specify some selector or physical address expression after a comma. (Task searching has no meaning in real mode.) The technique last used is employed in any repeat find. ASDT will interpret any expression used in a system-wide search technique (", s, hiaddr") as a physical address. If the string is found, the FX variable contains the address of the string. If the string is not found, the FX variable remains as it was before the search request. Since the second character of the F command is a blank, at least one blank must always follow the F command. It will operate in the current character translation mode (ASCII, CSECT, hex, or EBCDIC). Character strings may not include semicolons. Commas are special characters and denote that either a task search indicator ("*"), a selector expression, or a system-wide address range follows. (Note that a system-wide address will include two commas.) If you want a comma to be part of your string, enclose the string in quotes. For strings without delimiting quotes, leading blanks are always ignored yet trailing blanks are ignored only if there is no delimiting comma present. Every blank or comma (within the enclosing quotes) is considered part of the search string when the quotes are used. For the F, FA, FC, and FE commands, the string may include upper or lower case characters, numbers, special characters, and blanks. For the FX command, the string may contain any of the 16 hexadecimal digits. If an odd number of hexadecimal digits are entered for the FX command, the string is padded on the left with one hexadecimal zero digit. The length of a search string is limited by the command line length. However, the verification message will only display the first eight characters of the search string. Searching starts at the beginning of the LDT's first valid data or code descriptor selector (task search), at the beginning of the most recently specified selector (segment search), or at the beginning of a physical address range (system-wide search) unless a repeat find is done. For repeat find, the search begins where the previous search terminated. Task searching continues on through the GDT once the LDT has been exhausted. System-wide searching is limited by the 1M line in real mode. The FC command will have ASDT search only those descriptor selectors that reference valid code segments (when system-wide search is not being used). If the CSECT is found, ASDT will set the CO - Code Origin variable if a jump ('EB'x) instruction is discovered three bytes prior to the CSECT address. FC - can be used to have ASDT search for a CSECT name previous to the current CS:IP address. Repeated use of this command will have ASDT continue hunting for the next previous CSECT name within the CS address space (wrapping at offset 0 and the CS limit). If the search string is omitted, the previous string will be used. The repeat find function may be performed by adding a slash to the beginning of any of the find commands or by using the F5 key. ASDT sets function key F5 to the FX command on entry. ═══ 1.9.22. HP - Help ═══ Purpose: Display information about ASDT. Format: HP Examples: HP Displays a screen containing all the ASDT commands in logical groupings. Remarks: The help screen temporarily replaces the ASDT screen. Press any key to return to the ASDT screen. ASDT sets function key F1 to the HP command on entry. ═══ 1.9.23. HT - Halt Thread ═══ Purpose: To suspend the current thread and exit ASDT to OS/2. Format: HT Examples: HT Suspends the current thread and returns your session to OS/2. Remarks: HT should be used primarily to scan other screen groups. The most popular subset of this action is to view your host session. By entering the HT command (which has ASDT halt the current thread and return to OS/2) and then entering a series of Alt-Esc keystrokes or a Ctrl-Esc sequence, you can view listings of the halted thread on your host session. To return to ASDT, you need to enter a series of Alt-Esc keystrokes until you are back in the same screen group where you had ASDT suspend the thread. Now you can enter the hot key (if you have the hot key option enabled) to give control back to ASDT. Finally, you can enter the RT - Resume Thread command which will allow your thread to be resumed. You can halt up to ten threads if you want. Halting threads as they give control to ASDT allows you to see what impact the remaining threads that are running have on the system. You can not halt a thread at a breakpoint. This is due to the fact that ASDT inserts your breakpoints for you before it halts the thread. This command works for real mode as well except that you can only halt one application at a time. If you halt more than one real mode application (before resuming), ASDT will lose track of all but the latest real mode "thread." ═══ 1.9.24. IB - Input Byte ═══ Purpose: Reads one byte from a designated port (into a register if specified). Format: IB port [, reg] port The I/O port address from which the byte is to be read. reg The 8-bit register into which the byte is to be placed. Examples: IB 40 , AL Reads one byte from I/O port '0040'x and places it in register AL. The port and the value read are shown in a message. IB 21 Reads one byte from I/O port '0021'x and displays the port and the value read in a message. Remarks: To read a port but not place the value read into a register, you can omit the register name and the message line will display the value read. ═══ 1.9.25. IP - Instruction Pointer ═══ Purpose: Alters the contents of the instruction pointer, updates the EX variable, and updates the LC variable if appropriate. Format: IP [= expr] expr Any ASDT expression. Examples: IP = 13B ASDT sets the variable IP to '013B'x. If the Co variable has any value other than null, ASDT tries to maintain the following relationship: CO:LC = CS:IP This lets you think in terms of your assembly listing offsets. Remarks: ASDT uses only the least significant 16 bits that result from an expression evaluation to set the IP. ASDT truncates any additional bits and displays a warning message. Updating the IP register also updates the EX and LC displays. A null operand sets the IP to zero. ═══ 1.9.26. IW - Input Word ═══ Purpose: Reads one word from a designated port (into a register if specified). Format: IW port [, reg] port The I/O port address from which the byte is to be read. reg The 16-bit register into which the byte is to be placed. Examples: IW 58 , DX Reads one word from I/O port '0058'x and places it in register DX. The port and the value read are shown in a message. IW 31 Reads one word from I/O port '0031'x and displays the port and the value read in a message. Remarks: To read a port but not place the value read into a register, you can omit the register name and the message line will display the value read. ═══ 1.9.27. LC - Location Counter ═══ Purpose: Sets the pseudo-variable, Location Counter (LC), and updates either the IP variable or the CO variable. Format: LC [= expr] expr Any ASDT expression. Examples: LC = 12D ASDT sets the pseudo-variable LC to '012D'x. If the CO variable is null, ASDT sets the CO variable according to the formula CO = CS:IP-LC If CO is a physical address, then the CS base address is used. This provides an alternate means for setting the CO. When CO is null, the command LC=12D tells ASDT that the program counter (CS:IP) corresponds to the assembly listing LC value of 012D. ASDT computes the origin address and puts it into CO. If the CO variable has any value other than null, ASDT tries to maintain the following relationship: CO:LC = CS:IP If CO is a physical address, then the CS and CO base addresses are used. This lets you think in terms of your assembly listing offsets. Remarks: Normally, you use the Location Counter (LC) in conjunction with the Code Origin (CO) command to display a program location counter that corresponds with the offsets in your assembly listing. You should be familiar with the CO command before using the LC command. ASDT uses only the least significant 16 bits that result from an expression evaluation to set the LC. ASDT truncates any additional bits and displays a warning message. The LC command with a null operand sets both the CO and the LC to null. ═══ 1.9.28. LD - LDT Register ═══ Purpose: Alters the contents of the LDT register. Format: LD [= P expr] P Trigger to have ASDT interpret the expression as a physical address. expr Any ASDT expression. Examples: LD = 38 ASDT sets the LDT register to '38'x. LD P128E3A ASDT associates the user's LDT base address with 128E3A. Remarks: The current LDTR is changed when you enter the LD command. When you change the LDT register, the user program may not be able to continue with the altered value. ASDT uses only the least significant 16 bits that result from an expression evaluation to set the LDT register. ASDT truncates any additional bits and displays a warning message. When a physical address is used (indicated by a leading P), ASDT associates the user's LDT base address with the one provided. ASDT ensures that the address you specify does indeed point to a valid LDT. You can not step, terminate, or execute when you have changed the associated user's LDT base address in this manner. The idea behind this form of the LD command is to allow you to view another process's LDT entries. The LD command with a null operand restores the user program's LDT register and its base address to the incoming values. If you attempt to set the LDT to an invalid value or have ASDT associate the user's LDT with a physical address that does not reference an LDT, ASDT will display a message and will not act upon your request. Note: This command can not be used in real mode. ═══ 1.9.29. LW - LDT/GDT Window ═══ Purpose: Switches to LDT/GDT Window Mode. Format: LW [ * ] Examples: LW ASDT switches the edit portion of the ASDT display to an LDT/GDT window and sets the primary window mode to LDT/GDT. LW * Has ASDT compress out all the invalid descriptors in its LDT/GDT display. Remarks: The LDT/GDT window displays descriptor table entries in a decoded, readable format. Each table entry line displays one descriptor table entry. For an LDT/GDT window, ASDT replaces the top line of the ASDT display with the GDT address, the IDT address, the LDT register, the process id, the thread id, and the task state register. It displays the primary window on the left side of the middle of the ASDT screen. See the NW - Next Window command, which switches among all of the ASDT windows. Note: This command can not be used in real mode. ═══ 1.9.30. L1-L9 - Alter Window Area ═══ Purpose: Alter the disassembly and memory edit portion of the ASDT display or the LDT/GDT or IDT portion of the ASDT display by changing the address of a window display line. Each disassembly/memory address variable is displayed either as a selector:offset address or as a 6-higit physical address. Each LDT/GDT or IDT address variable is displayed as a 4-higit index. Format: Ln [= expr] n The L variable to be manipulated. expr Any ASDT expression. Examples: L1 = 123456 (disassembly/memory windows) Places the hexadecimal value 123456 into the L1 variable and displays the contents of that physical address location. L2 = SS:SP (disassembly/memory windows) Places the contents of registers SS and SP into the selector and offset of variable L2 to display your current stack. L8 = 002F (LDT/GDT window) Places the hexadecimal value 002F into the L8 variable and displays the descriptor found as if 002F had been used as a selector (in this case, the descriptor will be in the LDT). L9 = 0003 (IDT window) Places the hexadecimal value 0003 into the L9 variable and displays the descriptor found at the fourth descriptor slot in the IDT. Remarks: An L1-L9 command without a parameter causes the window that begins with the specified line to be combined with the previous window. If the specified line is not the beginning of a window, the command merely causes the display to be updated. When you have a secondary window set up, i.e., a memory window in disassembly mode or a disassembly window in memory mode, you can set any of the primary address variables and the first address variable of the secondary window. You cannot set the other secondary window address variables. (Secondary windows are valid only for the disassembly and memory windows.) Commands L1-L9 have the same function as typing over an address in the window. (Typing over an address in a window is valid only in a disassembly or memory window.) L1-L9's advantages include the use of expressions and leaving the cursor on the command line. When a window address variable is updated with one of these commands, that variable defines the beginning of a window; the remaining address variables in that window are also updated. Scrolling and skipping functions may be performed for the disassembly and memory windows with these commands in conjunction with the "/" key and the ENTER key: "/ L1 = L1 - 10" - does a vertical scroll (upward). "/ L5 = L5 + 1" - does a horizontal scroll (right). "/ L1 = L1 + 200" - does a downward skip through memory and can be useful for locating a large text buffer in memory. These commands may be used in conjunction with one of the FIND commands to search memory for the occurrence of an item: / FA string ; L1 = FX (memory window) The above sequence searches memory for an ASCII character string and, upon finding the string, displays it. Scrolling and skipping functions may be performed for the LDT/GDT or IDT windows using the PgUp, PgDn, Ctrl-PgUp, and Ctrl-PgDn keys. For example: "PgUp" - does a vertical scroll of the L1 window (upward). "Ctrl-PgDn" - does a scroll of one line of the L1 window (downward). Note: Note that the PgUp, PgDn, Ctrl-PgUp, Ctrl-PgDn, Ctrl-Left Arrow, and Ctrl-Right Arrow keys provide scrolling in the disassembly and memory edit windows (not on the command line). ═══ 1.9.31. MW - Memory Window ═══ Purpose: Switches to Memory Window mode. Format: MW [term] term The line number (L1-M6) at which to start the memory window. Examples: MW ASDT switches the edit portion of the ASDT display to a memory window and sets the primary window mode to memory. If a secondary disassembly window is displayed, ASDT removes it. MW L9 ASDT switches lines L9 through M6 of the ASDT display to show memory. The primary window mode of ASDT is not changed. Remarks: The memory window displays memory in hexadecimal and either ASCII or EBCDIC format. Each memory line displays one paragraph (sixteen bytes) of memory. ASDT displays the primary window (disassembly or memory) in the upper right portion of the ASDT screen. If the primary window is disassembly, then L1 and the following disassembly lines track the current CS:IP as your program runs. ASDT also tracks CS:IP for a secondary disassembly window. See DW - Disassembly Window command, which changes to a disassembly window and NW - Next Window command, which switches among all of the ASDT windows. ═══ 1.9.32. M1-M6 - Alter Window Area ═══ Purpose: Alter the disassembly and memory edit portion of the ASDT display or the LDT/GDT or IDT portion of the ASDT display by changing the address of a window display line. Each disassembly/memory address variable is displayed either as a selector:offset address or as a 6-higit physical address. Each LDT/GDT or IDT address variable is displayed as a 4-higit index. Format: Mn [= expr] n The M variable to be manipulated. expr Any ASDT expression. Examples: M1 = A88762 (disassembly/memory windows) Places the hexadecimal value A88762 into the M1 variable and displays the contents of that physical address location. M2 = CS:IP (disassembly/memory windows) Places the contents of registers CS and IP into the selector and offset of variable M2 to display your current instruction. M4 = 0020 (LDT/GDT window) Places the hexadecimal value 0020 into the M4 variable and displays the descriptor found as if 0020 had been used as a selector (in this case, the descriptor will be in the GDT). M6 = 0008 (IDT window) Places the hexadecimal value 0008 into the M6 variable and displays the descriptor found at the ninth descriptor slot in the IDT. Remarks: An M1-M6 command without a parameter causes the window that begins with the specified line to be combined with the previous window. If the specified line is not the beginning of a window, the command merely causes the display to be updated. When you have a secondary window set up, i.e., a memory window in disassembly mode or a disassembly window in memory mode, you can set any of the primary address variables and the first address variable of the secondary window. You cannot set the other secondary window address variables. (Secondary windows are valid only for the disassembly and memory windows.) Commands M1-M6 have the same function as typing over an address in the window. (Typing over an address in a window is valid only in a disassembly or memory window.) M1-M6's advantages include the use of expressions and leaving the cursor on the command line. When a window address variable is updated with one of these commands, that variable defines the beginning of a window; the remaining address variables in that window are also updated. Scrolling and skipping functions may be performed with these commands in conjunction with the "/" key and the ENTER key: "/ M1 = M1 - 10" - does a vertical scroll (upward). "/ M5 = M5 + 1" - does a horizontal scroll (right). "/ M1 = M1 + 200" - does a downward skip through memory and can be useful for locating a large text buffer in memory. These commands may be used in conjunction with one of the FIND commands to search memory for the occurrence of an item: / FA string ; M1 = FX (memory window) The above sequence searches memory for an ASCII character string and, upon finding the string, displays it. Scrolling and skipping functions may be performed for the LDT/GDT or IDT window using the PgUp, PgDn, Ctrl-PgUp, and the Ctrl-PgDn keys. For example: "PgUp" - does a vertical scroll of the L1 window (upward). "Ctrl-PgDn" - does a scroll of one line of the L1 window (downward). Note: Note that the PgUp, PgDn, Ctrl-PgUp, Ctrl-PgDn, Ctrl-Left Arrow, and Ctrl-Right Arrow keys provide scrolling in the disassembly and memory edit windows (not on the command line). ═══ 1.9.33. M7-M9 - Set Variables M7-M9 ═══ Purpose: Sets variables M7-M9. These variables provide scratch pad space. Each variable consists of either 6 hexadecimal digits or a selector:offset depending on whether the address is virtual or physical. Format: Mn [= expr] n The M variable to be manipulated. expr Any ASDT expression. Examples: M7 = 33F9AB Places the value '33F9AB'x into the M7 variable. M8 = V1 : DI Places the contents of variable V1 and register DI into the selector and offset of variable M8. Remarks: Since these variables are not displayed, ASDT shows you a confirmation message indicating the variable name and value each time one of these variables is set. M7 = 111111 + 222222 produces the confirmation message M7 = 333333 In order to display the contents of one of these variables, you can copy the contents into a V1-V9 variable (V5=M8), or you can copy the variable into itself to produce a confirmation message (M8=M8). The selector and offset portions of the M7-M9 variables are kept separately, so you can use these variables when you want to keep both selector and offset parts of an address. A variable command with a null operand sets the variable to null. ═══ 1.9.34. NW - Next Window ═══ Purpose: Switches to the next ASDT window (memory, LDT/GDT, IDT, or disassembly). Format: NW Examples: NW Switches among the ASDT windows in the following order: o Disassembly o Memory o LDT/GDT o IDT Remarks: ASDT switches the edit portion of the ASDT display to the next window in the sequence, and sets the primary window to the next window. The disassembly window displays instructions in both hexadecimal and disassembled format. If applicable, ASDT also displays the operand of the instruction. The memory window displays memory in hexadecimal and either ASCII or EBCDIC format. Each memory line displays one paragraph (sixteen bytes) of memory. The LDT/GDT and IDT windows display descriptor table entries in a decoded, readable format. Each table entry line displays one descriptor table entry. Note: ASDT will not enter the LDT/GDT or IDT window while you are in real mode. For disassembly and memory windows, ASDT displays the primary window in the upper right portion of the ASDT screen. For LDT/GDT and IDT windows, ASDT replaces the top line of the ASDT display with the GDT address, the IDT address, the LDT register, the process id, the thread id, and the task state register. It displays the primary window on the left side of the middle of the ASDT screen. If the primary window is disassembly, then L1 and the following disassembly lines track the current CS:IP as your program runs. ASDT also tracks CS:IP for a secondary disassembly window. Refer to MW - Memory Window, LW - LDT/GDT Window, VW - IDT Window, and DW - Disassembly Window for more information. ASDT sets function key F4 to the NW command on entry. ═══ 1.9.35. OB - Output Byte ═══ Purpose: Writes one byte to a designated port. Format: OB port [, value] port The I/O port address to which the byte is to be written. value The register, expression, or ASDT variable to output to the port. Examples: OB 40 , DL Writes the contents of the DL register to I/O port '0040'x. The port and the value written are shown in a message. OB 21 , BH + CH Writes the sum of the contents of the BH and CH registers to I/O port '0021'x. OB 38 Writes '00'x to I/O port '0038'x. OB AH , AL Writes the contents of the AL register to the port specified by the contents of the AH register. Remarks: ASDT writes a zero to the port if you omit the value. ═══ 1.9.36. OW - Output Word ═══ Purpose: Writes one word to a designated port. Format: OW port [, value] port The I/O port address to which the word is to be written. value The register, expression, or ASDT variable to output to the port. Examples: OW 58 , AX Writes the contents of the AX register to I/O port '0058'x. The port and the value written are shown in a message. OW 21 , BX + CX Writes the sum of the contents of the BX and CX registers to I/O port '0021'x. OW 38 Writes '0000'x to I/O port '0038'x. OW AX+BX , 10 Writes '10'x to the port specified by the sum of the contents of the AX and BX registers. Remarks: ASDT writes a zero to the port if you omit the value. ═══ 1.9.37. PD - Print Disassembly ═══ Purpose: Prints the current ASDT disassembly window at the LPT1 address. Format: PD [expr] expr Any ASDT expression to represent the number of bytes to be disassembled and printed. Examples: PD 100 ASDT starts disassembling and printing from the disassembly window L1 address for 256 bytes. Remarks: If expr is null, then ASDT will print from the disassembly L1 address to the end of the designated segment. Note: :LPT1 is assumed and if expr is null while the disassembly window L1 address is physical, ASDT will disassemble and print 64K bytes! ═══ 1.9.38. PI - Program Identification ═══ Purpose: Identifies the current thread's invocation path. Format: PI [= Sn] Sn Any of the ASDT breakpoints, V1-V9 and S1-S9. Examples: PI Prints the current thread's invocation path on the ASDT message line. PI S4 Prints the invocation path of the thread that is associated with the S4 breakpoint on the ASDT message line. Remarks: PI is useful in determining what program caused ASDT to get control. This is especially helpful on a general protection fault. Note: You can use this command in real mode, too. ═══ 1.9.39. PM - Print Memory ═══ Purpose: Prints the current ASDT memory window at the LPT1 address. Format: PM [expr] expr Any ASDT expression to represent the number of bytes to be formatted and printed. Examples: PM 200 ASDT starts formatting and printing from the memory window L1 address for 512 bytes. Remarks: If expr is null, then ASDT will print from the memory L1 address to the end of the designated segment. Note: :LPT1 is assumed and if expr is null while the memory window L1 address is physical, ASDT will format and print 64K bytes! ═══ 1.9.40. PR - Print Screen ═══ Purpose: Prints the current ASDT screen. Format: PR Examples: PR Prints the ASDT screen to the printer at the LPT1 address. Remarks: ASDT uses the LPT1 address for printing. You can also type the PrtSc key while ASDT is in control to obtain a printout of ASDT's screen. ═══ 1.9.41. RC - Retrieve Command ═══ Purpose: Re-displays the last command line that was executed. Format: RC Examples: RC Re-displays the last command line that was entered and places the cursor at the end of the command line. Remarks: ASDT saves the contents of up to ten command lines in a circular queue. Repeated RC commands will re-display the last ten command lines in reverse order. Commands entered via function keys or from a profile are not included in the saved command line queue. ASDT sets function key F10 to the RC command on entry. ═══ 1.9.42. RI - Restore Interrupt command ═══ Purpose: Restores an ASDT interrupt to OS/2. Format: RI = expr expr Any ASDT expression that indicates which interrupt you want ASDT to restore to OS/2. Examples: RI 0 ASDT restores control of interrupt 0 to OS/2. RI C ASDT restores control of interrupt '0C'x to OS/2. Remarks: ASDT controls various interrupts to gain control when some action that generates one of these interrupts occurs. There are times when your device driver needs to control one of these ASDT interrupts. By using the RI command, you can have ASDT relinquish control of a specific interrupt. You can tell ASDT not to take over a specific interrupt during its installation by using the /n parameter (where n is one of 0, 1, 2, 3, 6, C, or D). See TI - Take Interrupt Command for information on how to take an ASDT interrupt away from OS/2 for ASDT's usage. ═══ 1.9.43. RK - Reset Keyboard Hot Key ═══ Purpose: Resets ASDT's monitoring for a hot key. Format: RK Examples: RK ASDT no longer monitors keystrokes when it is not in control. Remarks: Subsequent hot key keystrokes do not return processor control to ASDT. The use of the keyboard hot key can be set at ASDT installation time with the /K option or at any other time with the SK command. Setting this option causes ASDT to monitor all keystrokes when it is not in control to see if you have requested the hot key function. When your program is running and this option is set, a hot key will return control to ASDT. Resetting this option with the RK command removes ASDT keystroke monitoring duties. ═══ 1.9.44. RT - Resume Thread ═══ Purpose: Resumes threads that were halted by the HT command. Format: RT [= pid] pid The process id of a specific thread that you halted with the HT command. Examples: RT ASDT resumes in LIFO fashion any threads that were halted using the HT command. RT 000B ASDT resumes the thread that was halted by using the HT command and has a process id number of eleven. Remarks: The RT command allows a previously halted thread to resume its processing. You can use the HT - Halt Thread and RT commands in conjunction with other keystrokes to view your host listings. If you intend to resume halted threads in some other manner than the default LIFO fashion adopted by the RT command, then you need to remember the process id that is associated with each thread that you halt. ASDT displays a thread's process id at the top line in either the LDT/GDT or IDT window. See LW - LDT/GDT Window and VW - IDT Window for these windowing commands. Note: This command works for real mode as well except that you can only halt one application at a time. Additionally, you will have no need of a process id as a parameter. ═══ 1.9.45. SB - Sticky Breakpoint ═══ Purpose: To make a specific breakpoint or all breakpoints sticky. Sticky is defined to mean that ASDT will stop on a given breakpoint regardless of the current PID and TID. Format: SB [= ON or OFF or Sn ON or Sn OFF] Sn Any ASDT breakpoint (V1-S9). Examples: SB ON Sets a global sticky flag, which tells ASDT to stop on every 'CC'x (breakpoint interrupt) that is encountered. SB OFF Resets the global ASDT sticky flag so that a decision is made by ASDT on whether to stop on the current breakpoint based on PID and TID comparisons. SB S3 ON Makes S3 sticky without affecting the status of any other breakpoint. SB S3 OFF Resets S3's sticky status to normal (unless SB ON has set the global sticky flag). Remarks: Normally, ASDT expends a great deal of energy to determine whether it should stop on a 'CC'x that has been encountered. Depending on the current PID and TID and the PID and TID that were in effect when you set a breakpoint, ASDT tries to determine if it should stop execution of your program or yield control back to OS/2. However, if the global sticky flag is on or if an individual breakpoint that is hit is sticky, then ASDT knows to take control regardless of PID and TID information. Note: ASDT always considers physical address breakpoints, GDT virtual address breakpoints, and real mode breakpoints to be sticky. ═══ 1.9.46. SC - Screen ═══ Purpose: Replaces the ASDT full screen display with the user program display. Format: SC Examples: SC Displays the user program's screen and waits for any key to be pressed. Remarks: Since ASDT uses the display screen to communicate with you, it saves your program's screen each time ASDT is entered and restores that screen each time it returns control to your program. When ASDT is active and you wish to view your screen instead of the ASDT screen, enter the SC command. Tapping any key restores the ASDT screen. ASDT sets function key F6 to the SC command on entry. ═══ 1.9.47. SK - Set Keyboard Hot Key ═══ Purpose: Sets hot key monitoring by ASDT. Format: SK [= nn] Examples: SK ASDT monitors keystrokes when it is not in control to see if you have typed the currently-defined hot key. This defaults to the PrtSc key. SK 4A Defines the hot key to scancode 4A, which is the keypad minus. Remarks: Subsequent hot key keystrokes return processor control to ASDT. The use of the keyboard hot key can be set at ASDT installation time with the /K option. Setting this option causes ASDT (when it is not in control) to monitor keystrokes searching for a hot key. When your program is running and this option is set, a hot key will return control to ASDT. Resetting this option with the RK command removes ASDT's monitoring of keystrokes. ═══ 1.9.48. SR - System Reset ═══ Purpose: Performs a system reset. Format: SR Examples: SR Re-ipls the machine causing control to be given to the boot-strap loader. Remarks: This command is useful if you want a fresh power-on of the system without turning the power switch off and on. Memory is not rechecked, and it is cleared. ASDT does not regain control with this command. ═══ 1.9.49. ST - Step ═══ Purpose: Executes a specified number of user program instructions. Format: ST [= expr] expr Any ASDT expression. Examples: ST 4 Four user program instructions are executed. Remarks: If the operand is null, the number of instructions executed defaults to the value of the step count variable (CT). Your display screen is restored, one user program instruction is executed, the breakpoints are activated, and the remaining user program instructions are executed. Program execution is terminated by one of the interrupts ASDT handles, by a breakpoint, or by the step count. The reason for termination is displayed with a message or a breakpoint highlight. Execution of your program always begins at the location pointed to by CS:IP. ASDT uses only the least significant 16 bits that result from an expression evaluation to set the ST value. ASDT truncates any additional bits and displays a warning message. Be aware of interrupts that prevent processor control from passing to ASDT. The timer, for example, would cause an interrupt between each depression of the ENTER key. Since ASDT resets the IF flag before executing each user program instruction, it is not always aware of user program instructions which modify the IF flag. At those times when ASDT does not keep the IF flag properly updated, it is your responsibility to update the IF flag via the IF command. ASDT sets function key F8 to the ST command on entry. ═══ 1.9.50. S1-S9 - Set Breakpoints S1-S9 ═══ Purpose: Sets the breakpoints that are displayed near the top of the ASDT display screen. Each breakpoint is either an absolute, 6-higit physical address, or it is a selector:offset address. It is displayed as a 6-higit address or as an offset from some selector or as "....." to indicate that the breakpoint is null. Format: Sn [= expr or ON or OFF] n The S breakpoint to be manipulated. expr Any ASDT expression. ON Activates Sn as a breakpoint. OFF Suspends Sn as a breakpoint. Examples: S1 = 345C00 Sets the S1 breakpoint to address hex 345C00. If this address is below or more than 64KB above the CS and the CO, the breakpoint is displayed as "345C00." S2 = CO + 4 Sets the S2 breakpoint to four bytes beyond the current code origin address. The breakpoint is displayed as "$0004." S5 = CS:CX Sets the S5 breakpoint to the current code segment plus the contents of the CX register. The breakpoint is displayed with a leading "+." S8 OFF Deactivates the S8 breakpoint. Remarks: When a breakpoint is activated, the instruction at that address is disassembled and displayed on the message line. When any of the active breakpoints is encountered during the execution of a user program, execution is stopped and control is given to ASDT. In addition to the nine S1-S9 breakpoints, the nine V1-V9 variables may be used for address stops to provide a maximum of eighteen address stops per screen. Since there are nine ASDT screens, a total of 162 address stops may be active at any given time. ASDT displays active breakpoints in a relative address format if possible. A relative address is designated by a "$" for CO, a "+" for CS, or a "*" for any other selector when the breakpoint is not a 6-higit physical address. When a breakpoint is not active, ASDT displays it as a 6-higit address if it is a physical address, otherwise it is displayed as a 4-higit offset with a leading "?." The following examples show how breakpoints are displayed under the various conditions: Command CO Setting CS Base Address CS Setting Resulting Display S1=CO+200 3D5900 200000 002F S1:$0200 S5=CO-1A5 +5900 3D0000 001F S5:+575B S8=3D5900 null 3D0000 001F S8:+5900 S2=2D0003 3D5900 100000 004F S2:2D0003 S1=DS:4567 +5900 3D0000 001F S1:*4567 S1=CO;S1 OFF 3D5900 200000 002F S1:3D5900 S1=CO;S1 OFF 003F:0004 3D0000 001F S1:?0004 ASDT highlights active breakpoints on the ASDT display screen. Once you deactivate a breakpoint with an OFF operand, it remains deactivated until it is reactivated with an ON operand. Note: ASDT will not reactivate a breakpoint for a process or thread that has terminated. This is due to the fact that every breakpoint has a process id, a thread id, and an LDT associated with it when it is set. You may deactivate and reactivate the breakpoint while its associated information is still valid, but you can not reactivate it once its thread has been terminated. If you want to reactivate a screen's breakpoints and associate their addresses with the current process id, thread id, and LDT, then issue a Dn ON command Note: When in real mode, you will set segment:offset breakpoints and physical address breakpoints. The physical address breakpoints will be limited to 5 higits even though they will be displayed as 6 higits. You can not set, deactivate, or reactivate a virtual real mode breakpoint while in protected mode and vice versa. Additionally, you can not set, deactivate, or reactivate a physical address breakpoint that is above the 1M line in real mode. A breakpoint command with a null operand sets the breakpoint to null. A special form of breakpoint, the procedure step, is used to run an entire module or section of code that is invoked with a CALL, INT, or REP instruction. ASDT provides a procedure step function, which uses S9 to set a breakpoint at the instruction following the one about to be executed. If the instruction about to be executed is a CALL, INT, or REP, the effect is for the entire module to be executed. The command sequence is "S9 = EX+IL;EX;S9." ASDT sets function key F9 to the procedure step command sequence on entry. You can change active breakpoints into complex breakpoints with the CB - Complex Breakpoint command. See also Setting Breakpoints. ═══ 1.9.51. TI - Take Interrupt Command ═══ Purpose: Takes an ASDT interrupt from OS/2 for ASDT's usage. Format: TI = expr expr Any ASDT expression that indicates which interrupt you want ASDT to take from OS/2. Examples: TI 2 ASDT takes control of interrupt 2 from OS/2. TI D ASDT takes control of interrupt '0D'x from OS/2. Remarks: ASDT controls various interrupts to gain control when some action that generates one of these interrupts occurs. There are times when your device driver needs to control one of these ASDT interrupts. By using the RI - Restore Interrupt command, you can have ASDT relinquish control of a specific interrupt. By using the TI command, you can have ASDT regain control of the specific interrupt. ═══ 1.9.52. TP - Terminate Process ═══ Purpose: Terminates the current process that ASDT is monitoring. Format: TP Examples: TP ASDT terminates the current process (program) and returns to OS/2. Remarks: TP allows you to end a process that ASDT has intercepted. This is useful when a stack limit violation or a general protection fault has caused ASDT to gain control. ASDT can not terminate a process that is running at level 0. ASDT will issue a warning message if you try to do this, and will not attempt to terminate the process. Additionally, if you issue TP for a device driver that ASDT is monitoring during the initialization phase, the system will hang. ASDT sets function key F3 to the TP command on entry. Note: In the DOS compatibility box, you should use the TP command only to terminate an application (not a device driver, a resident interrupt handler, etc.). ═══ 1.9.53. TS - Task State Register ═══ Purpose: Alters the contents of the TSR. Format: TS [= expr] expr Any ASDT expression. Examples: TS = 2A ASDT sets the task state register to '2A'x. Remarks: The current TSR (task state register) is changed when you enter the TS command. When you change the TSR, your program may not be able to continue with the altered value. ASDT uses only the least significant 16 bits that result from an expression evaluation to set the TSR. ASDT truncates any additional bits and displays a warning message. The TS command with a null operand restores your program's TSR to its original value. If you attempt to set the TSR to an invalid value, ASDT will display a message and will not set the register. Note: This command can not be used in real mode. ═══ 1.9.54. T0 - Suspend/Reactivate 80386 Hardware Debug Registers ═══ Purpose: Suspends or reactivates the 80386 hardware debug registers (DR0-DR3). Format: T0 [= ON or OFF] ON Reactivates all DRx that have settings. OFF Suspends all DRx that have settings. Examples: T0 OFF Keeps DR0-DR3 disarmed upon exit from ASDT. T0 ON Reactivates all of DR0-DR3 that have settings. Remarks: If you reference the T1-T4 commands (see T1-T4 - Set 80386 Hardware Debug Registers) you will notice that ASDT will deactivate your DR0-DR3 settings for various reasons that generally deal with the fact that the PID under which you set DR0-DR3 has been switched out or terminated. T0 ON will reactivate any suspended hardware debug register setting and will associate the current PID (in protected mode) with it. Note: You can not reactivate a virtual real mode DRx breakpoint while in protected mode and vice versa. Additionally, you can not reactivate a physical address breakpoint that is above the 1M line in real mode. This also implies that certain DRx breakpoints will be "lost" if you enter ASDT in one mode after having set DRx breakpoints in the opposite mode. These DRx breakpoints will be reestablished once you enter ASDT in the mode that they were first set. ═══ 1.9.55. T1-T4 - Set 80386 Hardware Debug Registers ═══ Purpose: Sets the 80386 hardware debug registers (DR0-DR3). Each DRx is set by using the Tn command where n is 1-4 and x=n-1. ASDT uses the information specified with the T1-T4 commands to load DR0-DR3 and DR7 upon return to OS/2. Format: Tn [= opnds or ON or OFF] n The DRx register to be set (x=n-1); e.g., the T4 command sets DR3. null ASDT retrieves information about DRx's current setting and places this data on the command line for review or editing. opnds operands (addr,action,len,context,exact) that must appear in this order. Only addr is required. addr Any ASDT expression that defines the address that you want DRx to monitor. A virtual address will have ASDT calculate the linear address whereas a physical address will be loaded into DRx as is. action I (breaks on instruction execution only), W (breaks on data writes only), or R (breaks on data reads or writes but not on instruction fetches). The default action is W. len 1, 2, or 4 to specify the length of the data item to be monitored. The 80386 hardware requires that multiple-byte fields be aligned on their proper boundaries. For the I action, ASDT will force the length byte to 1. The default length is 1 byte. context G (global level) or L (local level). The default context is global. exact E (exact data breakpoint match) or к (for inexact data breakpoint match). The 80386 processor slows the execution so that data breakpoints are reported on the instruction that causes them when the exact option is indicated. The default is exact. ON Reactivates DRx. OFF Suspends DRx. Examples: T1 5F:0245,I Sets DR0 to stop on instructions referenced at this location. T2 123456,R,2,G,к Sets DR1 to stop on data reads/writes from/to this location without the exact option. T3 OFF Deactivates DR2. T1 Places the current settings associated with DR0 on the ASDT command line for review or editing. Remarks: In general, ASDT is allowing you to set the 80386 hardware registers as mentioned in the Intel 80386 Programmer's Reference. You should apprise yourself with this reference guide before using the T1-T4 commands. The 80386 hardware automatically resets the local enable bits of DR7 at every task switch to avoid unwanted breakpoint conditions in the new task. However, OS/2 does not implement hardware task switching. Hence, ASDT does the best it can to determine when a hardware debug register is "truly" hit for your settings; i.e., if you use local context, ASDT looks to see if the current PID (when in protected mode) matches the one that was in effect when you set DRx. If the PIDs do not match, ASDT disables the local context DRx, and returns control to OS/2. Note: Global context means that ASDT will not check DRx's PID. ASDT just assumes that you always want the trap. The same holds true for all physical address DRx settings regardless of context. Even so, ASDT will deactivate a DRx with a global context if it determines that the virtual address does not use the GDT and its PID has been killed. Note: You can not reactivate a virtual real mode DRx breakpoint while in protected mode and vice versa. Additionally, you can not reactivate a physical address breakpoint that is above the 1M line in real mode. This also implies that certain DRx breakpoints will be "lost" if you enter ASDT in one mode after having set DRx breakpoints in the opposite mode. These DRx breakpoints will be reestablished once you enter ASDT in the mode that they were first set. See T0 - Suspend/Reactivate 80386 Hardware Debug Registers for a method that allows you to suspend or reactivate all 4 DR0-DR3 registers at once. ═══ 1.9.56. UM - User Mask ═══ Purpose: Displays and optionally sets the interrupt controller mask while ASDT has processor control. Format: UM [= value] value The interrupt mask value (must evaluate to '00'x through 'FF'x). Examples: UM Displays the current ASDT mask for the 8259 interrupt levels. UM BC Sets the user mask to 'BC'x, which allows only the keyboard and diskette interrupts while ASDT has control (assuming that these interrupts were not disabled by your program). Remarks: ASDT will not let you set a value which disables the keyboard. When ASDT gets control, ASDT saves the current interrupt mask register (I/O port '21'x). It then ORs the value you select with the current mask. Note: This means you cannot enable interrupts in ASDT that were disabled in your program. ASDT initializes the user mask to '00'x. You can specify another initial value for ASDT with the /U=nn parameter used by ASDT during installation (nn represents the byte that you want to serve as the user mask). The UM command allows you to specify which 8259 interrupt levels are to be masked off while in ASDT. However, when ASDT returns control to your program (via the EX, HT, ST, and TP commands), it restores the previously saved interrupt mask register value. Because of the complex nature of this command, only those familiar with 8259 interrupt levels and operation should use it. ═══ 1.9.57. U1-U9 - User-defined Functions ═══ Purpose: Allows you to call some of your own routines while under ASDT. Format: Un [= expr] n 1-9 to designate the member, U1-U9, of the dynamic load library, UX.DLL, that you want to call. expr Any ASDT expression that evaluates to a 32-bit pointer that you want to pass to your routine. Examples: U3 DS:23 Invokes U3, a member of the dynamic load library, UX.DLL, and passes it the 32-bit pointer, DS:23. U9 Invokes U9, a member of the dynamic load library, UX.DLL, without passing it a parameter. Remarks: ASDT assumes that you have the dynamic load library, UX.DLL, located in a library path that is searched by OS/2. You can define routines, U1-U9, for this DLL that can be called by ASDT using the U1-U9 commands. A 32-bit pointer is optionally passed as a parameter to your routine. It is up to you to make sure that your routine allows or does not allow for these two words on the stack. ASDT gives control to your routine, which runs as a level 3 application extension to ASDT. ASDT puts in all of the breakpoints that you have defined before control is given to your routine. This needs to be done as the CPU is yielded when a level 3 application thread is running. ASDT will "spin" on any breakpoint that is encountered while your routine has control. Hence, ASDT will not be reentered while your routine is running unless some error condition interrupt occurs. If this happens, the results are unpredictable. As a consequence of this, you should not put any 'CC'x breakpoints in any of your UX.DLL routines. It is your responsibility to preserve the DS, SS, SP, and BP registers for ASDT. ASDT waits for your routine to return control to it before it continues its processing. If you use the UX.DLL provided with ASDT, you can issue the "U2 SC" command to have ASDT dump its screen contents to a file named ASDT.OUT. The SC variable is a special parameter that is a level 3 selector:offset to the internal screen buffer of ASDT. It can be used as a parameter to any of the user-defined functions. Note: This command can not be used in real mode. ═══ 1.9.58. VW - IDT Window ═══ Purpose: Switches to IDT Window Mode. Format: VW Examples: VW ASDT switches the edit portion of the ASDT display to an IDT window and sets the primary window mode to IDT. Remarks: The IDT window displays descriptor table entries in a decoded, readable format. Each table entry line displays one descriptor table entry. For an IDT window, ASDT replaces the top line of the ASDT display with the GDT address, the IDT address, the LDT register, the process id, the thread id, and the task state register. It displays the primary window on the left side of the middle of the ASDT screen. Also see the NW - Next Window command which switches among all of the ASDT windows. Note: This command can not be used in real mode. ═══ 1.9.59. V1-V9 - Set Variables V1-V9 ═══ Purpose: Sets the variables that are displayed near the top of the ASDT display screen. These variables provide scratch pad space and additional breakpoints. Each breakpoint is either an absolute, 6-higit physical address, or it is a selector:offset address. It is displayed as a 6-higit address or as an offset from some selector or as "....." to indicate that the breakpoint is null. Format: Vn [= expr or ON or OFF] n The V breakpoint to be manipulated. expr Any ASDT expression. ON Activates Vn as a breakpoint. OFF Suspends Vn as a breakpoint. Examples: V1 = CS:IP + 2B8 Adds '2B8'x to the current program counter and places the result in the V1 variable. V2 = V1 + AX Places the sum of the contents of variable V1 and the AX register into the V2 variable. V5 = CO:CX;V5 ON Sets the V5 breakpoint to the current code origin plus the contents of the CX register and activates the breakpoint. The breakpoint is displayed with a leading "$." Remarks: At times, it may be useful to use one or more of the V1-V9 variables as address stops (breakpoints). ASDT displays active breakpoints in a relative address format if possible. A relative address is designated by a "$" for CO, a "+" for CS, or a "*" for any other selector when the breakpoint is not a 6-higit physical address. When a breakpoint is not active, ASDT displays it as a 6-higit address if it is a physical address, otherwise it is displayed as a 4-higit offset with a leading "?." The default state for the V breakpoints is inactive. See Setting Breakpoints and S1-S9 - Set Breakpoints S1-S9 for more information. ASDT highlights active breakpoints on the ASDT screen. Once you activate a variable with an ON operand, it remains activated until it is deactivated either with an OFF operand or by being set to null. Note: ASDT will not reactivate a breakpoint for a process or thread that has terminated. This is due to the fact that every breakpoint has a process id, a thread id, and an LDT associated with it when it is set. You may deactivate and reactivate the breakpoint while its associated information is still valid, but you can not reactivate it once its thread has been terminated. If you want to reactivate a screen's breakpoints and associate their addresses with the current process id, thread id, and LDT, then issue a Dn ON command. Note: When in real mode, you will set segment:offset breakpoints and physical address breakpoints. The physical address breakpoints will be limited to 5 higits even though they will be displayed as 6 higits. You can not set, deactivate, or reactivate a virtual real mode breakpoint while in protected mode and vice versa. Additionally, you can not set, deactivate, or reactivate a physical address breakpoint that is above the 1M line in real mode. A breakpoint command with a null operand sets the breakpoint to null. You can change active breakpoints into complex breakpoints with the CB - Complex Breakpoint command. ═══ 1.9.60. WA - Window Assumption ═══ Purpose: Causes ASDT to make assumptions about the selector used for setting the window, breakpoint, and CO variables during assignment commands. Format: WA [ON or OFF] Examples: WA ON Causes ASDT to use window assumptions. WA OFF Causes ASDT to stop using window assumptions. Remarks: Window assumptions affect assignments to the window, breakpoint, and CO variables. Some examples follow that assume that ASDT is using window assumptions: CO 35 - CO gets CS:35 S8 1234 - S8 gets CO+1234 or CS:1234 depending on whether the code origin is set L1 IP - L1 gets CS:IP if CO is null L1 LC - L1 gets CO+LC if CO is set Note: ASDT will use a physical address if you specify a source constant or variable that is greater than 'FFFF'x. If you specify a source constant or variable that consists of a selector and an offset, ASDT will use that selector and offset. The /W option has ASDT use window assumptions, too. ═══ 1.9.61. XS - Extra Selector Register ═══ Purpose: Alters the contents of the extra selector register variable. Format: XS [= expr] expr Any ASDT expression. Examples: XS = 1C42 Places the value '1C42'x into the XS variable. XS = CS Copies the contents of the CS register into the XS variable. Remarks: To save and restore selector register contents, use the XS segment register variable. ASDT treats XS just like a real selector register. ASDT uses only the least significant 16 bits that result from an expression evaluation to set the XS variable. ASDT truncates any additional bits and displays a warning message. A null operand sets the XS variable to zero. ═══ 1.10. ASDT Messages ═══ This section describes all of the messages that may appear on the ASDT display screen message line. A message either indicates that an action was taken or describes an error that has occurred. If you have trouble understanding an error or what action to take in response to an error, refer to the appropriate command in ASDT Command Reference. Messages are listed by subject. ═══ 1.10.1. General Messages ═══ BREAKPOINT(S) DEACTIVATED ASDT deactivated at least one breakpoint. This usually happens due to the fact that some process or thread has terminated, and ASDT can no longer track breakpoints with that process or thread. BREAKPOINT CONFLICTS WITH MODE ASDT can not set, deactivate, or reactivate at least one breakpoint because it was set in real mode and you are now in protected mode or vice versa. COMMAND "xx" NOT RECOGNIZED The command you issued was not a valid ASDT command. INVALID SELECTOR SPECIFIED The selector you have specified for some ASDT command is invalid. LDT BASE ADDRESS HAS CHANGED You tried to execute an ASDT command that requires the LDT to be what it was upon entry. CMD USED ONLY IN PROTECT MODE You tried to execute an ASDT command that is valid only in the protected mode, and you are executing in real mode. ═══ 1.10.2. Invocation Messages ═══ COLOR DISPLAY NOT PRESENT You specified the /M option in your CONFIG.SYS file, and ASDT does not detect the presence of a color display adapter. DIVIDE-BY-ZERO INTERRUPT (0) ASDT gained control via a divide by zero interrupt. This usually indicates an error in your program, but does not necessarily indicate a division error. ERROR READING PROFILE: xxxxxxx ASDT failed when it tried to read in a profile due to some specification by you in the CONFIG.SYS file. GENERAL PROTECTION FAULT xxxx ASDT gained control because an Int D occurred. This indicates that there was a general protection fault. The error code is shown and is retained in the ASDT variable, EC. HOT KEY INTERRUPT ASDT gained control because you typed the currently defined hot key. The hot key yields control to ASDT if you have issued an SK command or if you invoked ASDT with the /K option. MONOCHROME DISPLAY NOT PRESENT You specified the /M option in your CONFIG.SYS file, and ASDT does not detect the presence of a monochrome display adapter. NMI SWITCH INTERRUPT (2) ASDT gained control due to an Int 2 being issued. This usually means that you hit the NMI switch. PARAMETER UNRECOGNIZED: /x ASDT did not recognize an invocation parameter that you specified in the CONFIG.SYS file. SINGLE STEP TRAP INTERRUPT (1) ASDT gained control because the trap flag (TF) was set while the processor was executing an instruction. You may clear this flag with the TF command and continue if desired. STACK LIMIT VIOLATION ASDT gained control because an Int C occurred. This indicates that the stack limit was violated. 386 DEBUG REGISTER TRAP (DRn) ASDT gained control because the 80386 hardware debug register n signalled an event. INVALID OPCODE INTERRUPT (6) ASDT gained control because an invalid opcode was detected by the execution unit or the type of operand is invalid for the given opcode. ═══ 1.10.3. Expression Evaluation Messages ═══ UNRECOGNIZED OPERAND: xxxxxxxx A term in the command expression you entered was not valid. WARNING: OPERAND TRUNCATED This message warns you that the operand you specified is too large to fit in the target register or variable. ASDT fits as much as possible and truncates the rest. ═══ 1.10.4. "CA" Command Messages ═══ CONFLICTS WITH xxxxxxxxxx The color attribute you specified is the same as another attribute (normal, highlight, or reverse). Each attribute must be different. ═══ 1.10.5. "CB" Command Messages ═══ BREAKPOINT IS NOT ACTIVE You attempted to set a complex breakpoint when that breakpoint was inactive. Activate or set the breakpoint address before setting up the complex condition and count. BREAKPOINT IS NOT COMPLEX You have requested to see the complex definition of a particular breakpoint, but that breakpoint is not complex. BREAKPOINT NOT RECOGNIZED The complex breakpoint you have attempted to set is not a valid breakpoint. COMPLEX BREAKPOINT DEACTIVATED A complex breakpoint's occurrence count has matched the count, and ASDT has taken the breakpoint. ASDT deactivates the breakpoint. CONDITION MUST BE < 16 CHARS ASDT limits a complex condition field to 15 characters. COUNT FIELD EXPRESSION INVALID You have specified an unrecognized ASDT expression for the count field. OCCURRENCE COUNT = xx ASDT displays the complex condition and count for the breakpoint you requested. SYNTAX: CB SX CONDITION,COUNT ASDT displays the syntax for the command. VALID OPERATOR NOT FOUND ASDT expects one of the following logical operators for a complex condition: <, >, =, <=, >=, or <>. 1ST EXPRESSION IS INVALID You have requested an unrecognized ASDT expression for the left half of the complex breakpoint condition. 2ND EXPRESSION IS INVALID You have requested an unrecognized ASDT expression for the right half of the complex breakpoint condition. ═══ 1.10.6. "CG" Command Messages ═══ COLOR DISPLAY NOT PRESENT You specified the MS parameter for the CG command, and ASDT does not detect the presence of a color display adapter. MONOCHROME DISPLAY NOT PRESENT You specified the MS parameter for the CG command, and ASDT does not detect the presence of a monochrome display adapter. USING MULTIPLE SCREENS ASDT is using the secondary display because the multiple screen configuration has been selected. USING REMOTE TERMINAL ASDT is using the remote terminal display because this configuration has been selected. USING SINGLE SCREEN ASDT is using the primary display because the multiple screen or remote terminal configuration has been reset. ═══ 1.10.7. "CM" Command Messages ═══ INVALID ADDRESSING EXPRESSION One of the two memory addressing expressions is not acceptable to ASDT. LENGTH FIELD EVALUATES TO 0 You have specified an ASDT expression for the length field that evaluates to 0. Hence, the command is not executed. SEGMENT LIMIT WILL BE VIOLATED A segment limit violation will occur if ASDT compares the two memory blocks for the length that you have specified. SYNTAX: CM ADDR1,ADDR2,LENGTH ASDT displays the syntax for the command. xxx OF xxxxx MISMATCHES ASDT is comparing the two memory blocks and is displaying as much of the two blocks as possible. The number of mismatches shown on the screen and the total number of mismatches are displayed. ═══ 1.10.8. "CP" Command Messages ═══ INVALID ADDRESSING EXPRESSION One of the two memory addressing expressions is not acceptable to ASDT. LENGTH FIELD EVALUATES TO 0 You have specified an ASDT expression for the length field that evaluates to 0. Hence, the command is not executed. SEGMENT LIMIT WILL BE VIOLATED A segment limit violation will occur if ASDT copies the memory block to the indicated destination for the length that you have specified. SYNTAX: CP ADDR1,ADDR2,LENGTH ASDT displays the syntax for the command. ═══ 1.10.9. "DK" Command Messages ═══ FUNCTION KEY BUFFER IS FULL You have exceeded the amount of space ASDT has set up for commands associated with function keys. The total amount of space for function key commands is 800 bytes. KEY IS NOT DEFINED You pressed a function key that has not been defined. No action was taken by ASDT. KEY "xxxxx" DEFINED The function key definition you specified was added to the list of function keys. KEY "xxxxx" DEFINITION REMOVED The function key definition you specified was removed from the list of function keys. ═══ 1.10.10. "DW," "MW," "LW," and "VW" Command Messages ═══ INVALID DESCRIPTOR You tried to use L1-M6 as a source variable while you were in an LDT/GDT or IDT window, and the descriptor that was referenced is not valid. OPERAND NOT ALLOWED ASDT does not allow an LDT/GDT or IDT secondary window. ═══ 1.10.11. "EP" Command Messages ═══ ASDT PROFILE WAS NOT READ IN No profile was read in during the initialization phase. Hence, the EP command can not be executed. COMMAND TOO LONG - ABORTED A command in the specified profile is too long to fit on ASDT's command line. PROFILE NOT ENTIRELY READ IN ASDT has a limit on the total number of bytes it will read in for a profile during the initialization phase. If your profile contains more than 1600 bytes, it will be truncated. ═══ 1.10.12. "EX" Command Messages ═══ EX COMMAND ALLOWS NO OPERANDS You specified an operand with the EX command, and ASDT will not allow operands to be used with the EX command. ═══ 1.10.13. "F," "FA," "FC," "FE," and "FX" Command Messages ═══ xxxxxxxx FOUND AT xxxxxxxx The search string you requested was found at the memory location displayed at the right. STRING xxxxxxxx NOT FOUND The search string you requested could not be found. * OR SELECTOR EXPR REQUIRED You have a "," delimiter, which indicates the need for either a following "*" (task search indicator) or ASDT selector expression (for a single segment search). ═══ 1.10.14. "HT" and "RT" Command Messages ═══ ASDT CAN NOT RESUME THE THREAD ASDT can not resume a halted thread because that thread has terminated. HT COMMAND ALLOWS NO OPERANDS You specified an operand with the HT command, and ASDT will not allow operands to be used with the HT command. NO HALTING AT A BREAKPOINT ASDT will not allow you to halt a thread at a breakpoint. This is due to the fact that ASDT inserts your breakpoints for you before it halts the thread. NO THREADS CURRENTLY HALTED ASDT can not resume any threads because none are halted. PID SPECIFIED IS NOT FROZEN ASDT can not resume a specific thread of the process id (pid) that you specified because it did not halt a thread of that particular pid. TOO MANY THREADS HALTED ASDT currently allows only ten threads to be halted at the same time. PARAMETER ^USED IN REAL MODE The RT command does not need a parameter to reflect the process id in real mode. ═══ 1.10.15. "IB," "IW," "OB," and "OW" Command Messages ═══ VALUE xxxx OUTPUT TO PORT xxxx This message lists the port to which you wrote data and the value of that data. VALUE xxxx READ FROM PORT xxxx This message listed the port from which you read data and the value of that data. ═══ 1.10.16. "LD" Command Messages ═══ INVALID DESCRIPTOR You tried to use an index that referenced a descriptor that is not a valid LDT descriptor. INVALID LDT BASE ADDRESS You tried to alter the current LDT base address to a physical address that is not the start of a valid LDT. ═══ 1.10.17. "L1-M6" and "M7-M9" Command Messages ═══ CAN'T SET "Lx" IN THIS WINDOW You have a split disassembly/memory window and have tried to set a second window segment in the secondary window. ASDT allows only one secondary window segment (e.g., one memory window in disassembly mode). Mx = xxxxxx ASDT has set the contents of the displayed variable as shown (e.g., M7 = 999003, or Mx = 1234:99AF). ═══ 1.10.18. "PD and PM" Command Messages ═══ SEGMENT LIMIT WOULD OVERFLOW A segment limit violation would occur if ASDT prints the disassembly or memory block for the length that you have specified. ═══ 1.10.19. "PI" Command Messages ═══ ASDT CAN NOT LOCATE THE PATH ASDT can not find the current thread's invocation path. This happens most often with device drivers during the initialization phase. BREAKPOINT IS NOT SET The breakpoint you have attempted to use as a parameter to the PI command is valid, but it has no value associated with it. Hence, it has no process or thread associated with it either. BREAKPOINT NOT RECOGNIZED The breakpoint you have attempted to use as a parameter to the PI command is not valid. C:\TEST\BIN\TEST.EXE This is an example of a successful program identification by ASDT. ═══ 1.10.20. "PR" Command Messages ═══ PRINT CANCELLED DUE TO ERROR ASDT detected a problem with the printer. The printing operation has been terminated. ═══ 1.10.21. "RI" and "TI" Command Messages ═══ ASDT DOESN'T OWN THE INTERRUPT ASDT is not the current owner of the interrupt that you wish to restore to OS/2. ASDT DOESN'T USE THE INTERRUPT The operand you specified does not indicate an interrupt that ASDT uses. ASDT ALREADY HAS THE INTERRUPT You are trying to take an interrupt for ASDT that it already owns. RI(TI) COMMAND REQUIRES AN OPERAND Both of these commands require a specified interrupt as an operand. INTERRUPT ^USED IN REAL MODE While in real mode, you tried to take or restore an interrupt that ASDT does not use for real mode. REAL INT TAKEN/IDT LEFT AS IS While in real mode, you tried to take an interrupt that ASDT uses in both real mode and protected mode. ASDT was able to take the real-mode interrupt from the IVT, but it was not able to take the protected-mode interrupt from the IDT. REAL INT GIVEN/IDT LEFT AS IS While in real mode, you tried to restore an interrupt that ASDT uses in both real mode and protected mode. ASDT was able to restore the real-mode interrupt to the IVT, but it was not able to restore the protected-mode interrupt to the IDT. ═══ 1.10.22. "RK" and "SK" Command Messages ═══ HOT KEY HAS BEEN DISABLED ASDT will no longer monitor keystrokes for a hot key. HOT KEY DEFINED AS 'nn'X The hot key has been set as the scancode nn. ═══ 1.10.23. "SB" Command Messages ═══ BREAKPOINT IS NOT ACTIVE You attempted to set a breakpoint as sticky or as not sticky and it is inactive. Activate or set the breakpoint address before trying to change its sticky status. BREAKPOINT NOT RECOGNIZED The breakpoint that you wish to make sticky is not a valid breakpoint. SB COMMAND REQUIRES AN OPERAND You have not specified an operand for the SB command, and it requires one. ═══ 1.10.24. "SC" Command Messages ═══ TAP ANY KEY TO RETURN TO ASDT This message informs you that you are viewing your program's display screen. Tapping any key will return to the ASDT screen. ═══ 1.10.25. "S1-S9" and "V1-V9" Command Messages ═══ Sx: xxxxxxxxxxxx The indicated breakpoint has been activated. The string shown is the disassembled instruction at the breakpoint. Sx: INVALID AS A BREAKPOINT ASDT can not set the breakpoint at the address that you have specified. Check to see that the address uses a valid selector and that the offset falls within the selector's segment limit (assuming that this is a virtual address). Additionally, check to see that you are not trying to reactivate a breakpoint whose thread or process has terminated. ═══ 1.10.26. "TP" Command Messages ═══ ENVIRONMENT WILL NOT PERMIT TP ASDT can not terminate the process if it is currently running at level 0. ═══ 1.10.27. "T0-T4" Command Messages ═══ ADDRESS NOT ALIGNED FOR LENGTH The T1-T4 command address that you have specified does not match its corresponding field length. Two-byte fields must be aligned on word boundaries, and four-byte fields must be aligned on doubleword boundaries. HARDWARE REGISTER NOT ACTIVE You are attempting to use one of the T1-T4 (null) commands for editing purposes, and Tn is not active. INSUFFICIENT SPACE FOR Tn NULL You are attempting to use one of the T1-T4 (null) commands for editing purposes, and you have not left enough room on the ASDT command line for Tn's parameter display. T0 COMMAND REQUIRES AN OPERAND You are attempting to use the T0 command without an operand. It requires either ON or OFF. 80386 HARDWARE IS NOT PRESENT You are attempting to use one of the T0-T4 commands, and you are not running on a 386-based machine. ═══ 1.10.28. "UM" Command Messages ═══ INTERRUPT CONTROLLER MASK = xx ASDT has read the contents of the interrupt controller mask register. INVALID SETTING - KEYBD MASKED You attempted to set the interrupt mask to a value which masks off the keyboard. ASDT does not allow this. ═══ 1.10.29. "U1-U9" Command Messages ═══ PROBLEMS WITH ACCESS OF UX.DLL Either ASDT could not load the dynamic link library, UX.DLL, or it could not find the member that you specified. ═══ ═══ If you are not sure what directories are defined by your PATH statement, enter PATH on an OS/2 command line and they will be listed. If you would like to create a new directory for the program, ensure that you modify the PATH statement in CONFIG.SYS accordingly. ═══ ═══ If you are not sure what directories are defined by your LIBPATH statement, check your CONFIG.SYS file for the line beginning "LIBPATH=". The directories listed on this line are those that are checked by a running program when looking for a DLL. If you would like to create a new directory for the DLL, ensure that you modify the LIBPATH statement accordingly. ═══ ═══ ASM86 is an IBM Internal cross assembler (not provided with this program). ═══ ═══ /K causes ASDT to get control whenever you press the hot key. The hot key defaults to the PrtSc key. However, if you use the /K=nn form of this option, ASDT will define the nn scancode as the hot key. E.g., /K=4A will set the keypad minus as the hot key. Use the hot key to give control to ASDT from your application, the OS/2 PM shell, etc. See SK - Set Keyboard Hot Key for more information. ═══ ═══ /M causes ASDT to use two screens for debugging if you have more than one display adapter. See CG - Configuration for more information. ═══ ═══ /R=n causes ASDT to use a remote terminal for debugging if you have one hooked up via COMn (n=1 or 2). See CG - Configuration for more information. ═══ ═══ /U=nn changes the user mask default from '00'x to 'nn'x for the 8259 interrupt controller register. See UM - User Mask for more information. ═══ ═══ /W causes ASDT to make certain assumptions about offset assignments to specific ASDT variables. See WA - Window Assumption for more information. ═══ ═══ /n causes ASDT not to take over a specific interrupt during its installation. This allows your device driver to control that interrupt. See RI - Restore Interrupt for more information.