Version 1 - Release 1
Test Control System (TCS) is a debugging tool modeled after the original DBC product written by Dave Cole. As a mainframe software developer once I discovered DBC many years back I quit using TSO TEST. DBC was far more powerful and user friendly than TEST. DBC evolved into the XDC product line still marketed by Dave Cole.
As I was developing code for FSI I was constantly frustrated by using TSO TEST to debug my code. As a result I began to think I needed to develop a DBC-like debugger for MVS 3.8. One day I was having lunch with a couple of friends still in the software business and the subject of XDC came up as we were talking. As we discussed XDC I stated that I thought I would write a simple version for MVS 3.8 to make my own life easier. I then began to design how a debugger would operate and then began to develop code. The result was my initial version of TCS which existed as a "Proof Of Concept". This allowed me to learn how a debugger for MVS 3.8 could be written. At the time my plans were to do a complete rewrite. The rewrite was started and then forgotten for a few years. In the fall of 2008 I decided to once again start working on the rewrite.
Version 1.1 March 2, 2009 corrects several bugs. New commands are "L register", "S Q addr",and "L Q". In addition a new addressing mode has been implemented using the Qualifier. Finally the TCSCALL and TCSCMD commands are added.
First, let me say that TCS is not based on any DBC code but it does operate much like the way I remember DBC operating. Dave Cole is still the King of Debuggers and a great man.
Standard Disclaimer
TCS is a part-time fun project that I started working on as a result of developing FSI.
There is a lot of room for enhancement and improvement if you would like to help take this project forward. When I get more spare time I may try to improve upon what I have here.
Using TCS
Currently TCS can only be used under TSO as it uses TGET and TPUT for all I/O.
Establish the TCS environment by doing the following:
LOAD EP=TCS
LR R10,r0
ESTAE (R10)
This will cause the TCS module to be loaded into storage and an ESTAE recovery environment to be established. When an ABEND occurs, the TCS module will receive control.
A "Hard Coded" Breakpoint can be assembled into the source code using the following:
DC X'00DEAD00'
When this instruction is executed, an program interrupt will be generated causing a SOC1 type ABEND. TCS will recognize this as a hard-coded breakpoint.
A message can be associated with a Hard Coded Breakpoint: DC
DC X'00DEAD',AL1(msg-len),C'Message Text'
For example:
DC X'00DEAD',AL1(32),C'ENTERING MAIN PROCESSING ROUTINE'
A command or set of commands can also be associated with a Hard Coded Breakpoint:
DC X'00DEAD',X'0100',C'command;command',X'00'
For exampple:
DC X'00DEAD0100',C'L PSW;L REGS',X'00'
The command string must be terminated with a null charcter.
The following commands are recognized by TCS. Multiple commands may be specified by using the semicolon ";" separator.
| Command | Parameters | |
| L | PSW | List the contents of the Program Status Word |
| L | REGS | List the contents of all 16 General Purpose Registers |
| L | register | List the contents of a single register (R0-R15) |
| L | ATS | List all active breakpoints |
| L | Q | Show the value of the current Qualifier |
| D | addr [lines] | Display the contents of virtual storage at addr The optional lines parameter specifies how many lines of storage to dump. The default number of lines is 4, the maximum number of lines is 16. |
| F | addr [lines] | Format (disassemble) the contents of virtual storage at addr The optional lines parameter specifies how many lines of storage to dump. The default number of lines is 4, the maximum number of lines is 16. |
| AT | addr | Set a breakpoint at addr |
| OFF | addr | Remove a breakpoint at addr |
| MAP | module library | Build a map of the CSECTS in a module. This allows you to specify a CSECT name as a qualifier to a module for an address expression. |
| S | Q address | Set the Qualifier to the module[csect] the address is contained in |
| T | addr | Set a tracepoint at addr. A tracepoint is like a breakpoint except it is automatically removed when the tracepoint is hit. |
| T | [ I ] | Trace Instruction. If the no parameter is specifed on the trace instruction it is assumed to be an instruction trace. This causes the next instruction to be executed and then the debugger reentered. |
| T | B | Trace Branch. This causes execution to continue until the next "Branch" instruction is reached. |
| T | BY | Trace Branch Yes. This causes execution to continue untily the next "Branch" instruction that will cause a branch is reached. |
| T | BN | Trace Branch No. This causes execution to continue until the next "Branch" instruction that will not cause a branch is reached. |
| Z | addr=value | Modify the contents of virtual storage at addr changing it to value |
| Z | reg=value | Modify General Purpose Register reg changing its contents to value |
| GO | [addr] | Resume execution at next instruction or if addr is specified, at the specified address. |
| END | Terminate execution of the program being debugged. | |
| Full Screen Interface Commands | ||
| %AUTOFF | Disable Automatic Command Execution | |
| %AUTON | Enable Automatic Command Execution | |
| %BOTTOM | Scroll to the bottom of the display buffer | |
| %CLEAR | Clear the contents of the display buffer | |
| %DOWN | Scroll down | |
| %FIND | Find a string in the display buffer | |
| %FSOFF | Turn Full Screen Mode off, use line commands | |
| %FSON | Turn Full Screen On | |
| %RETRIEVE | Retrieve the last command entered | |
| %SHOW | Show the PFK settings | |
| %TOP | Scroll to the top of the display buffer | |
| %UP | Scroll up | |
| %NN=commands | Set PKF NN to the command string | |
| +Ncommand |
Set Automatic Command N to command string Automatic commands are executed automatically each time the user is prompted for input. |
|
| +N | Delete Automatic Command N | |
Operands specified in brackets [ ] are optinoal.
reg is a register specification in the form Rn or nR (for example 4R or R13).
addr is an address specification. It can begin with the value of the PSW, a Register, a module or a Virtual Address. It may further be modified by offsets (+ or -) and an indirect specification ( % ). Examples are:
12R% The address contained in Register 12
R13%+4%
09EAC0
10%+4%
mymodule+A0
mymodle.acsect+48%
mymodle.acsect+48%+24%%
Using The Qualifier
S Q PSW% /* Set the qualifier to the module the PSW is in */
/* The Qualifier can now be accessed as "." (period) */
F .+8C /* will format beginning at +8C from the beginning of Qualifier module
value specifies either a hex value or a character value:
Z R3=04
Z 8R%+1A='NEW TEXT VALUE'
Z PSW%=0700
TCSCALL and TCSCMD
The TCSCALL and TCSCMD commands can be used to place a called program or command processor unter test. The TCSCALL command will run a program under test passing in a parameter list using startard parameter list. The TCSCMD command is an alias for TCSCALL and will place a command processor under test passing it a standard CPPL in register one. A special DD Name of TASKLIB may be used to establish a load library for the program under test.
TCSCALL program parameter[,parameter...]
TCSCMD program parameter [parameter...]
Installing TCS
The TCS load module is supplied in IEBCOPY unload format. The block size is 19069. It should probably be installed in a LINKLIST data set. I would suggest using SYS2.LINKLIB. It can also be included in a STEPLIB dataset contained in your TSO LOGON PROC.
Sample JCL to install
//TCSINSTL JOB (5222),'TCS INSTALL',CLASS=A,MSGCLASS=A
//COPY EXEC PGM=IEBCOPY
//SYSPRINT DD SYSOUT=*
//TAPE DD DSN=TCS.V0R1M0.DIST,DISP=(OLD,KEEP),
// UNIT=TAPE,VOL=SER=TCS110
//LIB DD DISP=SHR,DSN=SYS2.LINKLIB
//SYSIN DD *
C I=TAPE,O=LIB
/*
//
| tcs110.aws |
| tcs010.aws.zip |
Problems or Questions
Please contact me at tommy@tommysprinkle.com
Thanks, -Tommy