ibm:vm370-lib:cmshelp:per.helpcmd
PER
CMS Commands
- per.helpcmd.txt
PER CP Privilege Class: G Use the PER ccommand to trace specified program events and to record the results at the terminal, on a virtual spooled printer, or on both terminal and printer. The format of the PER command is: +----------+------------------------------------------------------------------+ | PER | Branch [addr-range] [controls, modifiers and options] | | | Greg[n] [hex-number] [controls, modifiers and options] | | | Ifetch [hex-data] [controls, modifiers and options] | | | Mask addr hex-data [controls, modifiers and options] | | | PAgetrace [page-size] [controls, modifiers and options] | | | STore addr-range [controls, modifiers and options] | | | STore addr hex-data [controls, modifiers and options] | | | | | | controls: | | | Dump | | | SAve traceset-name | | | GET traceset-name | | | Clear [traceset-name] | | | ENd | | | Query traceset-name | * | | | modifiers: | | | OFF | | | Range addr-range | | | options: | | | CMd cmd1[;cmd2[;...cmdn]] | | | SKip dec-number | | | STEp dec-number | | | RUn|NORun PRint|NOPrint TErminal|NOTerminal | +----------+------------------------------------------------------------------+ where: BRANCH [addr-range] causes successful branch instructions to be traced. If addr-range is not specified all successful branch instructins will be displayed; if addr-range is specified a traceback of the last five successful branch instructions will be displayed when a branch into that range occurs. GREG[n] [hex-number] causes the alteration of either all general registers or the register specified by n to be traced. If hex-data is specified only alterations to the given value are traced. Whenever an alteration occurs the instruction doing the altering and the new contents of the register are displayed. IFETCH [hex-data] causes instruction fetches to be traced. If hex-data is specified only instructions that match the hex-data will be traced. MASK addr hex-data causes the alteration of the bits at address addr specified by the hex-data mask to be traced. PAGETRACE [page-size] causes the transfer of control between segments of main storage to be traced and time stamped. If pagesize is specified memory is divided into segments of that size. Memory may also be segmented by using the RANGE keyword in conjuction with PAGETRACE. STORE [addr-range] | [addr hex-data] causes storage alterations to be traced. If addr-range is specified then only alterations of storage within that range are traced. If addr hex-data is specified then only alteration of the storage at addr to the given hex-data is traced. DUMP causes the traceback table containing the last six successful branches to be displayed on the terminal. A traceback table is maintained only if a branch trace is in effect. SAVE traceset-name causes a copy of the current trace set to be saved under the given name. The current trace set is still active and unchanged. GET traceset-name causes the current trace set (if any) to be replaced by a copy of the named trace set. The named trace set is unchanged. CLEAR [traceset-name] causes the current trace set to be cleared, or if a trace set name is given the named trace set to be cleared. END causes all PER trace sets to be cleared. QUERY [traceset name] | [*] causes the contents of the current trace set to be displayed if no operand is given. If an * is specified the names of the saved trace sets are displayed. If traceset-name is specified the contents of the named trace set are displayed. OFF halts tracing of the specified type (BRANCH, IFETCH, etc.). RANGE addr-range causes the tracing for a given trace type to be limited to instructions fetched from within the specified range. The range keyword may be omitted if there is no ambiguity as to the application of the range. SKIP dec-number causes the specified number of events to be skipped between displays. STEP dec-number causes the number of displays specified to be made between entries to CP command environment. TERMINAL | NOTERMINAL causes output to be directed to the terminal; NOTERMINAL stops output to the terminal. RUN | NORUN continues the program execution after the PER output to the terminal has completed and does not enter the CP command environment. RUN is equivalent to a STEP of infinity. NORUN stops program execution after the PER output to the terminal and enters the CP command environment. PRINT | NOPRINT causes PER output to a virtual spooled printer. Both PRINT and TERMINAL may be specified at the same time. NOPRINT causes output to a virtual printer to be stopped. CMD cmd1[;cmd2[;...cmdn]] specifies a CP command or a list of CP commands to be executed when the given event occurs. PER operands: addr is used to specify a logical storage location. It must consist of one to six contiguous hex digits. hex-data is used to specify hexidecimal data. It must consist of an even number of contiguous hex digits. hex-number is used to specify a word of hex data. It must consist of one to eight contiguous hex digits. It will be padded with zeros on the left to fill out the word. addr-range is used to specify a range of logical storage locations. It may be any of the following: addr specifies a single byte in storage. addr-addr2 specifies all storage locations from addr to addr2 inclusive. addr- specifies all storage locations from addr to FFFFFF inclusive. -addr specifies all storage locations from 0 to addr inclusive. addr.hexl specifies hexl number of contiguous storage locations starting at addr. dec-number is used to specify a decimal number. It must be a number from 0 to 2147483647. traceset is used to specify a named trace set. It must consist of one to eight contiguous nonblank characters. page-size is used to specify the size of the segments that memory is to be divided into with the PAGETRACE keyword. It must consist of one of the following: nnnnnnnn a decimal number. nnnnnK a decimal number followed by a K. This specifies a page size of nnnnn times 1024. Usage notes: 1. The keywords on the command line may be specified in any order. Each command may cause one or more PER elements to be built. Each element has a single type (BRANCH, IFETCH, etc.) plus associated RANGE and options (SKIP, RUN, etc.). If more than one PER trace type is specified an element for each type is built. Any options or modifiers specified on this command line will be in effect for all the trace elements constructed from this command line. 2. When an element is created STEP 1, SKIP 0, NORUN and TERMINAL are assumed unless otherwise specified. 3. If modifiers or options are specified and no PER trace elements are specified, the modifiers or options apply to all elements in the current trace set. 4. If an instruction modifies a register that is used in one of its operand addresses, PER may not be able to determine the operand address. 5. Address ranges are wrap around, that is if the second address in the range is lower than the first, the storage locations specified are from the first address to FFFFFF and from 0 to the second address. 6. PER trace output and consequent entry into the CP command environment always occurs after the instruction execution is complete. 7. Self modifying instructions will cause erroneous processing of PER output. 8. When tracing in a virtual machine with only one printer, the PER data is intermixed with other data sent to the virtual printer. To seperate PER information define another printer with a lower virtual address than the previously defined printer. 9. Whenvever 10000 interupts of a given type (Ifetch, Branch, Greg or Store) occur with no PER output a PER "blip" is produced. This consists of an * followed by the first character of the interupt type (i.e. *I for Ifetch). 10. If the type, options and data (if any) are the same in any two elements and their ranges (if any) either overlap or are adjacent, those two elements will be merged into a single element. Responses: The following symbols are used in the responses recieved from PER: vvvvvv virtual storage address tttttt virtual transefer address xxxxxxxx virtual instruction zzzzzzzz hexadecimal data oooooo virtual operand address kkkkkkkk virtual time in hex microseconds zz low order byte of register in an execute instruction dddddddd data mnem mnemonic for instruction CC=n condition code number > transfer of control : traceback table entry *PER TRAPS CLEARED* This response is issued when all tracing is cleared. Branch instructions: vvvvvv mnem xxxxxxxx tttttt CC=n RR Instructions: vvvvvv mnem xxxx CC=n RX or RS Instructions: vvvvvv mnem xxxxxxxx oooooo CC=n SS type Instructions: vvvvvv mnem xxxxxxxxxxxx oooooo oooooo CC=n General register alteration vvvvvv mnem xxxxxxxx oooooo CC=n Gnn=zzzzzzzz Execute instructions: vvvvvv EX xxxxxxxx zz vvvvvv mnem xxxxxxxx oooooo CC=n Page trace output *PGT* vvvvvv kkkkkkkkkkkkkkkk Branch traceback: TRACEBACK TABLE: :vvvvvv mnem xxxxxxxx tttttt nnnnnnnn TIMES up to six entries Data stop output: DATA AT vvvvvv=zzzzzzzz (for whatever data was specified) Usage Examples: Ifetch Ifetch specifies the tracing of the fetching of instructions from main storage. In the following example a trace of the fetching of all instructions is specified. per i >017A70 LTR 12F3 CC=0 CP b 017A72 LM 980E0BE0 000BE0 CC=0 CP b 017A76 BR 07FE 0170A6 CC=0 CP It is possible to restrict the PER trace output to only those instructions that match specified hex data as in the following example where only those instructions having a first byte of X'0A' are traced. per i 0a >016EFE SVC 0ACA CC=0 DATA AT 016EFE=0A CP b R; >0173A0 SVC 0ACA CC=0 DATA AT 0173A0=0A Store Store causes tracing of alterations of main storage. In the following example all storage alterations are traced. per st >013B3C STM 900EF03C 00247C CC=1 *STORE* CP b >013B44 MVI 9200D07A 0024BA CC=1 *STORE* CP b 013B48 OI 9620D1A6 0025E6 CC=1 *STORE* CP It is possible to restrict the tracing of store events to only those that store within a specified range as in the following example where only alterations of storage locations 7A0 to 800 are traced. per st 7a0-800 R; ind >01C89C MVI 92403000 0007A0 CC=3 *STORE* CP b 01C8A0 MVC D28030013000 0007A1 0007A0 CC=3 *STORE* CP b >01C9A6 EX 4450C54E 02 01CBDE MVC D20030004000 0007A0 000716 CC=2 *STORE* CP It is also possible to restrict the trace to the alteration of a given storage location to a given value. In the first of the following examples the storing of x'40' at location 7A0 is traced and in the second the storing of X'D840E4' at 7A0 is traced. per st 7a0 40 R; q u >01C89C MVI 92403000 0007A0 CC=3 *STORE* DATA AT 0007A0=40 CP b USERS=46 DIALED=42 PEAK=48 R; per st 7a0 d840e4 R; q u >01C9A6 EX 4450C54E 02 01CBDE MVC D20030004000 0007A0 000716 CC=2 *STORE DATA AT 0007A0=D840E4 CP b USERS=46 DIALED=41 PEAK=48 R; Branch Branch specifies the tracing of successful branches. Whenever a branch trace is in effect a table of the last 5 successful branches is maintained which can be displayed using the DUMP control. It is also possible to specify that output is to be produced only if a branch into a given range occurs. In the following example brances to the address 1BEE0 are traced. per b 1bee0 R; >01B5B6 BALR 05EF 01BEE0 CC=2 TRACEBACK TABLE: :01C80A BALR 05EF 01B6C0 :01B6DC BZ 4780F026 01B6EC :01B6F4 BZ 4780F044 01B70A :01B536 BZ 4780C032 01B548 :01B550 BZR 078F 01B594 CP b q u >01B5B6 BALR 05EF 01BEE0 CC=2 TRACEBACK TABLE: :01C80A BALR 05EF 01B6C0 :01B6DC BZ 4780F026 01B6EC :01B6F4 BZ 4780F044 01B70A :01B536 BZ 4780C032 01B548 :01B550 BZR 078F 01B594 CP b USERS=44 DIALED=42 PEAK=48 R; Greg Greg causes the tracing of the alteration of general purpose registers. In the following example the alteration of all registers is traced. per g >017A70 LTR 12F3 CC=0 G03=00000000 G15=00000000 CP b 017A72 LM 980E0BE0 000BE0 CC=0 G01=000007A0 G02=00000000 G06=00000005 G12=00016E60 G14=500170A6 CP b >0170B4 LR 18DF CC=1 G13=00000000 CP b 0170B6 LA 4110B184 0025C4 CC=1 G01=000025C4 CP The trace output may be restricted to the alteration of a given register or registers to a given value or values as in the following example. per g15 0 >017A70 LTR 12F3 CC=0 G15=00000000 CP b >013C32 SR 1BFF CC=0 G15=00000000 CP b >011F5A SR 1BFF CC=0 G15=00000000 CP Pagetrace Pagetrace causes the tracing of the transfer of control between specified segments of memory. Memory may be segmented either by the pagesize operand of pagetrace or by use of the RANGE keyword. In the following example memory is segmented into pieces of 4096 bytes. per pag 4096 *PGT* 017A70 0000008239850000 CP b *PGT* 013B38 0000008239916000 CP b *PGT* 011CC0 0000008239A88000 CP b *PGT* 013BD2 0000008239CBE000 CP b *PGT* 0170C0 0000008239DA5000 CP b *PGT* 011F4C 0000008239E11000 CP Mask Mask causes tracing of the alteration of specified bits in main storage. In the following example the alteration of the first bit in the byte at 25E7 is traced. per m 25e7 80 R; li JTIME @SSEMBLE EP001P ASM3705 EP001Q ASM3705 hx >01C156 OI 9680F1A7 0025E7 CC=1 *STORE* DATA AT 0025E7=81 CP b CAIXXPRT DECK RASPMAN DISKLOAD CP EDIT >004D20 MVI 920071A7 0025E7 CC=0 *STORE* DATA AT 0025E7=00 CP b CMS Range Range is used to segment memory. In the case of ifetch, branch, greg, mask and store is is used to restrict the range of the instruction addresses that will be traced. In the case of pagetrace it is used to specify the segments of memory. More than one range may be specified for any element. If no range is specified a range of 0-FFFFFF is assumed. In the following example the ifetch trace is restricted to only those instructions fetched from E000 to E00F and 1FF00 to 1FFB0. per i e000-e00f 1ff00-1ffb0 b R; T=3.36/22.41 01:20:58 q n >00E000 BALR 05C0 CC=0 CP b 00E002 LA 4140CFFF 00F001 CC=0 CP b 00E006 LA 41404001 00F002 CC=0 CP b 00E00A ST 50E0CE4E 00EE50 CC=0 CP b 00E00E LA 41201008 000850 CC=0 CP b >01FF08 LTR 1230 CC=0 CP b 01FF0A BNP 47D0C12E 01FF8E CC=0 CP b 01FF0E CLI 95402000 0007A0 CC=0 Skip Skip causes the number of events specified to be skipped between displays. In the following example skip causes every fifth event to be displayed. per i skip 5 >0170AA BNZ 4770C254 0170B4 CC=1 CP b >013B38 L 58F00600 000600 CC=1 CP b >013B48 OI 9620D1A6 0025E6 CC=1 CP b >013B7E CLI 955C1010 0025D4 CC=0 CP Step Step causes the specified number of displays to be made between entries into the CP command environment. In the following example 5 displays are made between entries into the CP command environment. per i step 5 >017A70 LTR 12F3 CC=0 017A72 LM 980E0BE0 000BE0 CC=0 017A76 BR 07FE 0170A6 CC=0 >0170A6 CH 49F0C6C0 017520 CC=1 0170AA BNZ 4770C254 0170B4 CC=1 CP b >0170B4 LR 18DF CC=1 0170B6 LA 4110B184 0025C4 CC=1 0170BA L 58F006F0 0006F0 CC=1 0170BE BALR 05EF 013B38 CC=1 >013B38 L 58F00600 000600 CC=1 CP Cmd Cmd causes specified CP commands to be executed when the associated per event occurs. In the following example when a store at 7a0 occurs a message is sent, the per tracing cleared and the virtual machine put to sleep. per st 7a0 run cmd m * store at 7a0 occurred;per c;sl R; ind >01C890 MVI 92003000 0007A0 CC=0 *STORE* 12:01:08 MSG FROM KERRY : STORE AT 7A0 OCCURRED *PER TRAPS CLEARED* ZZZzzz.. Dump Dump causes the current contents of the branch traceback table to be displayed. A traceback table is maintained whenever any sort of branch trace is in effect. In the following example a branch trace that will not be satisfied is turned on and dump is used to display the branches occuring before the SVC. per b 0 tr svc TRACE STARTED q u *** 017030 SVC 00CA ==> 01229C CP per dump TRACEBACK TABLE: :0176EC BNZ 4770F01E 0176F6 :017714 BXLE 8734F034 01770C 4 TIMES :01772C BM 4740F088 017760 :01776E BXLE 8734F090 017768 34 TIMES :01777C BR 07FE 016FFA :016FFC BNZ 4770C1B2 017012 Save, Get, Clear and Query Save, Get, Clear and query are used respectively to save, retrieve, delete and display PER trace sets. The following are some examples of the use of these controls. per i 83 print noterm 20000- per st 250-300 70000-75000 per b 1fffc 20000- run per q IFETCH 83 RANGE 20000:FFFFFF PRINTER STORE 250:300 RANGE 70000:75000 TERMINAL BRANCH 1FFFC RANGE 20000:FFFFFF RUN TERMINAL per save set1 per c per q TRACE SET DOES NOT EXIST per i 60000-70000 per q IFETCH RANGE 60000:70000 TERMINAL per q set1 IFETCH 83 RANGE 20000:FFFFFF PRINTER STORE 250:300 RANGE 70000:75000 TERMINAL BRANCH 1FFFC RANGE 20000:FFFFFF RUN TERMINAL per get set1 per q IFETCH 83 RANGE 20000:FFFFFF PRINTER STORE 250:300 RANGE 70000:75000 TERMINAL BRANCH 1FFFC RANGE 20000:FFFFFF RUN TERMINAL per cl set1 per c *PER TRAPS CLEARED*
ibm/vm370-lib/cmshelp/per.helpcmd.txt · Last modified: 2023/08/06 13:36 by Site Administrator