[Prycroft Six][Software][MVS Mods][TSO TEST]

Updating TSO TEST

The TEST TSO command is the interactive debugger which comes with MVS. Like some other commands (most notably EDIT or E) the command comes with a set of subcommands supplied by IBM. TEST has two subcommand tables. The first is the one populated by IBM. The second is one intended for use by installations wishing to extended the number of subcommands available from within a TEST session. Below is a sample job stream for adding new subcommands to TEST.

In this example, several TSO commands are being registered so that they can be issued from within a TEST session. They are IM to allow virtual storage examination, QUEUE (and its alias QUE) to allow access to assembler and link edit listings, and REVIEW (and its alias REV) to allow data set contents examination. (While Q is also an alias of QUEUE, it is not being registered here because Q is also the short name of the QUALIFY subcommand of TEST.)

Further, two subcommands written specifically for TEST are being added. They are FIND (or F) to allow a block of virtual storage to be searched for specific data, and LISTBK (or LB) which lists all active breakpoints that are currently set.

The new FIND subcommand processor is a load module called IKJEG9FI, and the new LISTBK subcommand processor is a load module called IKJEG9LB. General TSO commands are given control via IKJEGCIV which is the TEST "command invoker" (to quote the TITLE statement from its source).

The source of these two TEST subcommands is in CBT file 300. Their load modules which are known to work from MVS 3.8 to OS/390 2.7 (and known to not work on OS/390 2.9) are available from CBT file 135.

The source in file 300 does not cater for 31-bit addressing, but the load modules in file 135 report 8-hex digit addresses. Despite this, and the fact they are marked AMODE=31 and RMODE=ANY they can be used on pre-XA system levels. The cause of their lack of functionality under z/OS has probably more to do with their reliance on a TEST I/O service to display data on the terminal than with their detailed internal logic and data structure processing.

Note that TEST usually resides in the SYS1.CMDLIB data set, and that the user subcommand table is contained in the TEST program.

Now, since this is a non-SMP update to the operating system we want a simple procedure to redo it, and a simple procedure to undo it.

Because the process involves the creation of a new program without changing any existing software, the procedure to redo it is to rerun the job (which should be done whenever SMP maintenance updates the "real" TEST program), and the procedure to undo it is to simply delete the program created by the job depicted below.

So what is this new program? It is simply a copy of TEST with an updated user subcommand table.

So how does the system know to use the new TEST? Because it is installed into a linklist library ahead of SYS1.CMDLIB in the linklist.

What would happen if the TEST in SYS1.CMDLIB was updated directly by this job? Nothing untoward - it should work without any problems. But it is simpler to undo all changes if the original data is available unchanged.

In the sample job below, SYS1.PPLIB is the linklist data set placed ahead of SYS1.CMDLIB in the linklist.

Note that SYS1.PPLIB is not a data set shipped on the Tur(n)key MVS System CD. I created it on my system and edited SYS1.PARMLIB(LNKLST00) to add it as the first data set behind SYS1.LINKLIB in the linklist. Check that all data set names are valid for your system before running the job.

Click here to see the following JCL as a text file.

//GREGT    JOB (S),G.PRICE,CLASS=A,COND=(0,NE),
//             MSGCLASS=X,NOTIFY=GREG
//*
//* JOB TO ADD SUBCOMMANDS TO TSO TEST. THIS IS DONE BY
//* 1. ASSEMBLING A NEW TEST USER SUBCOMMAND TABLE.
//* 2. LINK EDITING THIS TABLE INTO A LINKLIST LIBRARY
//*     WHICH IS PLACED AHEAD OF SYS1.CMDLIB IN THE LINK LIST.
//* 3. RELINKING THE TEST COMMAND PROCESSOR TO INCLUDE THE
//*     NEW USER SUBCOMMAND TABLE INTO THIS LIBRARY.
//* NOTE: THE ORIGINAL TEST COMMAND IS LEFT UNCHANGED
//*     IN SYS1.CMDLIB. TO UNDO THIS MOD DELETE THE TEST
//*     LOAD MODULE FROM THE TARGET LIBRARY.
//* 4. RERUN THIS JOB WHENEVER SMP MAINTENANCE UPDATES
//*     THE TEST COMMAND IN SYS1.CMDLIB.
//*
//* ADDED SUBCOMMANDS CAN INCLUDE SUBCOMMANDS WRITTEN SPECIFICALLY FOR
//* TEST, AS WELL AS GENERAL TSO COMMANDS TO BE RECOGNISED BY TEST.
//* TSO COMMANDS SHOULD BE ASSOCIATED WITH MODULE IKJEGCIV.
//*
//* (NOTE THAT Q IS THE SHORT NAME OF QUALIFY - A TEST SUBCOMMAND.)
//*
//ASM     EXEC PGM=IFOX00,PARM='NODECK,OBJECT'
//SYSLIB   DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=MVSSRC.SYM101.F01,DISP=SHR
//SYSUT1   DD DSN=&&SYSUT1,UNIT=VIO,SPACE=(1700,(600,100))
//SYSUT2   DD DSN=&&SYSUT2,UNIT=VIO,SPACE=(1700,(300,50))
//SYSUT3   DD DSN=&&SYSUT3,UNIT=VIO,SPACE=(1700,(300,50))
//SYSPRINT DD SYSOUT=*,DCB=BLKSIZE=1089
//SYSPUNCH DD SYSOUT=B
//SYSGO    DD DSN=&&OBJSET,UNIT=VIO,SPACE=(80,(200,50)),
//             DISP=(MOD,PASS)
//SYSIN    DD *
         TITLE ' TSO TEST USER SUBCOMMAND TABLE '
         IKJEGSUB (FIND,F,IKJEG9FI),                                   +
               (IM,,IKJEGCIV),          TSO COMMAND                    +
               (LISTBK,LB,IKJEG9LB),                                   +
               (QUEUE,QUE,IKJEGCIV),    TSO COMMAND                    +
               (REVIEW,REV,IKJEGCIV),   TSO COMMAND                    +
               CSECT=USER               DO NOT ALTER IBM SUPPLIED LIST
         END
/*
//*
//* SYSLMOD SHOULD POINT TO A LINKLIST LIBRARY AHEAD OF
//* SYS1.CMDLIB IN THE LINK LIST. CHECK SYS1.PARMLIB(LNKLST??).
//LKED1   EXEC PGM=IEWL,PARM=(REFR,RENT,REUS,LIST,NCAL,MAP)
//SYSLIN   DD DSN=&&OBJSET,DISP=(OLD,DELETE)
//SYSLMOD DD DSN=SYS1.PPLIB(TEST),DISP=SHR
//SYSUT1   DD DSN=&&SYSUT1,UNIT=VIO,SPACE=(1024,(50,20))
//SYSPRINT DD SYSOUT=*
//LKED2   EXEC PGM=IEWL,PARM=(REFR,RENT,REUS,LIST,NCAL,MAP)
//SYSLMOD DD DSN=SYS1.PPLIB,DISP=SHR
//CMDLIB   DD DSN=SYS1.CMDLIB,DISP=SHR
//SYSUT1   DD DSN=&&SYSUT1,UNIT=VIO,SPACE=(1024,(50,20))
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD *
REPLACE IKJEGSCU
INCLUDE CMDLIB(TEST)
INCLUDE SYSLMOD(TEST)
ENTRY IKJEGINT
NAME TEST(R)
/*
//

Feedback

For enquiries or feedback please email Greg Price.

[Up]