home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 10 / 10.iso / l / l440 / 2.ddi / CHAP8 / INTRSPY.DOC < prev    next >
Encoding:
Text File  |  1990-09-27  |  8.5 KB  |  288 lines
  1.             INTRSPY & CMDSPY
  2.             --------------------
  3.  
  4.  
  5.     INTRSPY is a TSR that intercepts interrupts, and stores structures and
  6. register contents passed to and from these interrupts. It is accompanied by
  7. it's control program CMDSPY, which is transient, and acts as a compiler of
  8. scripts that specify the interrupts to intercept, the functions and
  9. subfunctions to monitor, and the structures to store.
  10.  
  11.  
  12. Usage of INTRSPY.EXE :
  13.  
  14.     INTRSPY [-rnnnn] [-innnn]
  15.  
  16.  
  17.         where 
  18.             -rnnnn specifies the amount of memory INTRSPY is to allocate
  19.             for result storage (default is 2k)
  20.  
  21.             -innnn specfies the amount of memory INTRSPY is to allocate
  22.             for interrupt handler code. (default is 2k)
  23.  
  24.  
  25. example :
  26.  
  27.     INTRSPY -r24000
  28.  
  29.         runs INTRSPY with an allocation of 24000 bytes of results space,
  30.         and the default 2k of interrupt handler code space.
  31.  
  32.  
  33.  
  34. Usage of CMDSPY.EXE :
  35.  
  36.     CMDSPY  [COMPILE [d:][path]inptfile[.ext] [param-1 [param-2 .. ]]]
  37.             [REPORT [[d:][path]outpfile.ext]]
  38.             [RESTART]
  39.             [FLUSH]
  40.             [STOP]
  41.             [UNLOAD]
  42.  
  43.         where
  44.             COMPILE compiles a script, and instructs INTRSPY to begin 
  45.             monitoring interrupts and storing results specified in the 
  46.             script, and
  47.             inptfile.ext contains script source in the form defined in the
  48.             next section. Any currently active script is stopped, and the
  49.             results area is flushed.
  50.             if the extension is omitted, .SCR is assumed.
  51.  
  52.             REPORT instructs INTRSPY to return the results accumulated so
  53.             far. The file outpfile.ext, if specified, will contain the
  54.             formatted output of the stored results of the current script
  55.             since it was processed unless there has been a subsequent
  56.             FLUSH.
  57.  
  58.             STOP instructs INTRSPY to stop monitoring interrupts, but to
  59.             preserve the results area. 
  60.  
  61.             RESTART instructs INTRSPY to restart, after a STOP command,
  62.             monitoring interrupts on the basis of the currently compiled
  63.             script.
  64.  
  65.             FLUSH instructs INTRSPY to clear down the results area, but
  66.             leave the currently active script intact.
  67.  
  68.             UNLOAD instructs INTRSPY to unload itself from memory. Any
  69.             active script is stopped.
  70.  
  71.  
  72.  
  73. Script language
  74. ---------------
  75.  
  76.     The script language allows 8 main constructs. These are:
  77.  
  78.     INCLUDE, which includes another input file.
  79.  
  80.     STRUCTURE, which defines a data structure
  81.  
  82.     INTERCEPT, which specifies an interrupt, optional functions and
  83.     optional subfunctions, together with the entry and exit processing to
  84.     be done when that interrupt is triggered.
  85.  
  86.     RUN, which allows a DOS program to be exec'ed from within the script
  87.  
  88.     REPORT, 
  89.     FLUSH,
  90.     STOP,
  91.     RESTART, which work exactly like their command line counterparts.
  92.  
  93.  
  94. Syntax
  95. ------
  96.  
  97.     A script file is an ASCII file. All white space is ignored, except
  98.     within literal strings used for results output. Thus indentation and
  99.     splitting constructs across multiple lines may be used for
  100.     readability. Line endings are only used to delimit comments, which are
  101.     started with a semicolon anywhere on a line.
  102.  
  103.  
  104. INCLUDE Syntax
  105. --------------
  106.  
  107.  
  108.     INCLUDE "[d:][path]inptfile[.ext] [param-1 [param-2 ....]]"
  109.  
  110.                 includes the specified file, and substitutes param-1,
  111.                 param-2, etc., in the source in place of the strings %1,
  112.                 %2, etc., respectively, where found.
  113.                 If the extension is omitted, .SCR is assumed.
  114.  
  115.  
  116.  
  117.  
  118. STRUCTURE Syntax
  119. ----------------
  120.  
  121. Let us define a field-definition as
  122.  
  123.     field-type [,field-disp-type [,field-dup]]
  124.  
  125. where
  126.  
  127.     field-type can be BYTE, WORD or DWORD.
  128.  
  129.     field-disp-type can be HEX, BIN, DEC, PTR, DUMP, STRING, ASCII, ASCIIZ
  130.                 (DUMP is a combination of hex and ascii)
  131.  
  132.     field-dup is number of elements, if the field is an array, or
  133.                 length of field in, for example, a string. It may be a numeric
  134.                 literal or predefined constant. In the case of transient
  135.                 definitions (within OUTPUT or SAMELINE statements), field-dup
  136.                 may also refer to a register.
  137.  
  138. Then STRUCTURE syntax looks like
  139.  
  140.     STRUCTURE struct-name FIELDS 
  141.          field-name1 (field-definition)
  142.         [field-name2 (field-definition)]
  143.                                 .
  144.                                 .
  145.         [field-nameN (field-definition)]
  146.  
  147.     struct-name must be a unique structure identifier. 
  148.  
  149.     field-name must be unique within struct-name.
  150.  
  151.  
  152. INTERCEPT Syntax
  153. ----------------
  154.  
  155. Let us define an output-element as
  156.  
  157.     REGS or
  158.     register-name or
  159.     flag-name or
  160.     "string literal" or
  161.     (seg:offs[offs]->struct.field->struct.field->struct) or
  162.     (seg:offs[offs]->struct.field->struct.field->struct.field) or
  163.     (seg:offs[offs]->struct.field->struct.field->field-definition) or
  164.     built-in-constant
  165.  
  166. where
  167.  
  168.     [offs] is an optional numeric literal,
  169.     struct.field-> may appear up to 4 times, and struct and field must 
  170.                     be predefined
  171.     built-in-constant is one of the predefined constants defined in the
  172.                     Predefined Constants section below.
  173.  
  174. Let us then define an output-clause as
  175.  
  176.     OUTPUT output-element [output-element [output-element .....]]]
  177.         or
  178.     SAMELINE output-element [output-element [output-element .....]]]
  179.         or
  180.     STREAM 8-bit-register
  181.     DEBUG
  182.  
  183.         where
  184.             OUTPUT starts a new line,
  185.             SAMELINE attempts to append elements to an existing line,
  186.             STREAM outputs bytes as otherwise unformatted characters
  187.             DEBUG, if the intercept occurs during a RUN statement,
  188.                 enters the pop-up debugger (see The DEBUGGER below).
  189.  
  190. Let us then define a test-clause as
  191.  
  192.         (something==something) or (something!=something)
  193.             where something may be a sgereg, reg16, reg8,
  194.                 flag (oflag, cflag, iflag etc), or built-in-constant
  195.  
  196. let us then define an if-clause as
  197.  
  198.     IF test-clause [AND test-clause [OR test-clause [ ..... ]]]
  199.         [output-clauses]
  200.  
  201.  
  202. then INTERCEPT synatx looks like:
  203.  
  204.     INTERCEPT interrupt-number
  205.         [output-clauses]
  206.         [test-clauses]
  207.         [FUNCTION fnctn-number [fnctn-number .....]
  208.             [output-clauses]
  209.             [test-clauses]
  210.             [SUBFUNCTION sfnctn-number [sfnctn-number ..... ]
  211.                 [output-clauses]
  212.                 [test-clauses]
  213.                     [ON_ENTRY
  214.                         [output-clauses]
  215.                         [test-clauses]]
  216.                     [ON_EXIT
  217.                         [output-clauses]
  218.                         [test-clauses]]]
  219.             [SUBFUNCTION sfnctn-number [sfnctn-number ..... ]
  220.                     .
  221.                     .   ]
  222.         [FUNCTION fnctn-number [fnctn-number ..... ]
  223.                 .
  224.                 .
  225.                 .
  226.                 .       ]
  227.  
  228.  
  229.  
  230. RUN syntax
  231. ----------
  232.  
  233.     RUN "[d:][path]program[.ext] [parm1 [parm2 ....]]"
  234.                 if the extension is omitted, first a .EXE then a .COM file
  235.                 is searched for, either in d:path if specified, or on the
  236.                 DOS search path if both drive and path are omitted.
  237.  
  238.  
  239.  
  240.  
  241. REPORT syntax
  242. -------------
  243.  
  244.     REPORT "[d:][path]outpfile.ext" or "" for STDOUT
  245.  
  246.  
  247.  
  248. STOP syntax
  249. -----------
  250.  
  251.     STOP
  252.             no parameters
  253.  
  254.  
  255. RESTART syntax
  256. --------------
  257.  
  258.     RESTART
  259.             no parameters
  260.  
  261.  
  262. The DEBUGGER
  263. ------------
  264.  
  265.     The Monitor Debugger is a simple interactive debugger that allows
  266.     access to some of CMDSPY's output capabilities from a command line.
  267.  
  268.     Current commands are:
  269.  
  270.         R       -   Displays the registers as they were when the caller
  271.                     generated the interrupt. It replicates the REGS
  272.                     output.
  273.  
  274.         D sreg:reg16[offs]->struct.field->struct.field->field-definition
  275.                 -   Displays an area of memory. The argument to the
  276.                     command is an output-element, but without the
  277.                     parentheses.
  278.  
  279.         X       -   Exit the debugger.
  280.  
  281.         ,     -   Recall previous commands for editing.
  282.  
  283.         The command line is fully editable using <BS>, , ,<CTRL>,
  284.         <CTRL>, <DEL>, <ESC> (clears the command line), and is
  285.         permanently in Insert mode.
  286.  
  287.  
  288.