/*----------------------------------------------------------------------------*/
/*  usd2.hlp                                                                  */
/*----------------------------------------------------------------------------*/

#V 1.2 04/01/1990

#a
 <FUNC KEYS>
 <VIEWPORTS>
 BACKGROUND     Conceal Viewport
 BREAKPOINT     Set S/W Breakpoint
 CLEAR          Clear S/W Breakpoint
 CREATE         Create Symbol
 DELETE         Delete Symbol
 DOUBLE         Double Floating Point
 DOWNLOAD       Download File
 FLOAT          Single Floating Point
 FOREGROUND     Reveal Viewport
 HELP           USD2 Command Help
 HISTORY        Command History
 INCLUDE        Include Command File
 ISTEP          Instruction Step
 JOURNAL        Log Output File
 LOAD           Load Symbol Table
 LOG            Log Command File
 MODULE         Directory Module
 OPTIONS        Optional Functions
 QUERY          Symbol/Address Query
 SOFTKEY        Define SoftKey Macro
 SYMBOL         List Symbol
 UPDATE         Enable/Disable Viewport Update
 UPLOAD         Upload File
 URECALL        Recall Window/Softkey
 USAVE          Save Window/Softkey

#h

 FUNCTION KEYS:

   <F1>                        On line help
   <F2>                        MICE-II "r" command
   <F3>                        Last history buffer command
   <F4>                        Next history buffer command
   <F5>                        IStep
   <F6>                        IStep Over
   <F7>                        IStep FOrever
   <F8>                        IStep Over FOrever
   <F9>                        Toggle-zoom command viewport
   <Shift-F1> - <Shift-F8>     Softkey K1-K8

#h


    Viewport Name     |     Foreground ( initial screen )
   -------------------+-----------------------------------
     BREAKPOINT       |                no
     CODE             |                yes
     COMMAND          |                yes
     REGISTER         |                yes
     STACK            |                no
     TRACE            |                no

#h

 BACKground  {Breakpoint|CODe|COMmand|Register|Stack|Trace}

------------------------------------------------------------

 BACKground       is  the   command  to  conceal  or   hide 
                  unnecessary viewport from the screen.

 Breakpoint|CODe  are the viewport-to-hide options.
 |COMmand|......

#h

 BREakpoint  [address]

------------------------------------------------------------

 BREakpoint  is  the command to set  a  software  execution
             breakpoint. If "BReakpoint" is entered without 
             any   parameter,  breakpoints   arranged   and 
             consecutively   numbered  according   to   the 
             sequence they were entered, will display.

 address     is the memory location of  software  execution
             breakpoint.  Address may be expressed  in  hex 
             value  or with any USD-II symbol format,  i.e.
             [%%module]%symbol.

#h

 CLEar  [no1 [no2]]

------------------------------------------------------------

 CLEar  is  the  command to  delete one  or  more  software
        breakpoints.  If no specific breakpoint  number  is
        specified, all breakpoints are  deleted.

 no1    is the reference number of a particular  breakpoint
        to  be deleted or where a series of breakpoints  to
        be deleted is to begin.

 no2    is the reference number of the breakpoint  where  a
        series of breakpoints to be deleted ends.


 Whenever breakpoint(s) is deleted, the breakpoint  listing
 is  automatically  resorted to  maintain  the  consecutive
 sequence of the breakpoint reference numbers.

#h

 CReate  symbol_name hex_address

------------------------------------------------------------

 CReate       is the command to create a global symbol. Any
              symbol  created by this command is  temporary
              and   effective  only  during   the   current
              session.  It will not be written back to  the
              symbol file.

 symbol_name  is the symbol to be  created with any of  the
              alphanumeric  characters except  the  percent
              sign  <%>. The percent sign <%> is only  used
              as a prefix to every symbol name.

 hex_address  is the symbol address. If  the  segment value
              is omitted from  the command line  and it's a
              segmented  address  format,  the  default  CS
              value will be used as the segment value.

#h

 DELete  symbol_name

------------------------------------------------------------

 DELete       is the command to delete an existing  symbol.
              Only symbols created by "CReate" command  can
              be deleted with this command.

 symbol_name  specifies  the symbol to be  deleted.  Symbol
              should include the percent sign (%) prefix.

#h

 DOUble  [Physical] [address [data-1 [...data-8]]]

------------------------------------------------------------

 DOUble      is the command for Memory Modify and specifies
             the  desired data format  as  double-precision
             (64-bit).

 Physical    classifies type of address as  "physical"  for
             MICE-32 80386  and  MICE-16 80286.  Otherwise,
             the address is "logical".

 address     specifies the location where the Memory Modify
             operation  is to begin.  It is  a  hexadecimal
             address  in the memory space of the  emulation
             CPU.

             Address  may be expressed in hex value  or  in
             any     USD-II     symbol     format,     i.e.
             [%%module]%symbol.

 data-1...8  are the floating-point values. Up to 8  values
             may   be  entered.  A   floating-point   value
             consists of the following:

          [sign] integer_part [.fractional_part] [exponent]


 If  no  parameter  is entered,  the  USD-II  displays  the
 starting address content  of the current PC  and waits for
 further  input. To  change the value held  in the location
 displayed,  enter a new  floating-point value,  then press
 <CR> to go to the  next location  in memory or <Ctrl-J> to
 go to the preceding location. Pressing  <CR>  or  <Ctrl-J>
 alone,  without  first inputting  a new value, leaves  the
 contents   of   the  location  unchanged;  pressing  <ESC>
 terminates the function.

#h

 DOwnload  filename [UP|UD|SP|SD|P|R]

------------------------------------------------------------

 DOwnload     is the command to download an object  file to
              MICE.

 filename     is the file to be downloaded

 UP|UD|SP|SD  are the four optional memory space  types  of
              MICE-16 68000:
              - User Program (UP)
              - User Data (UD)
              - Supervisor Program (SP)
              - Supervisor Data (SD)
              Hence, these options are applicable and to be
              specified  only when USD-II  is  linked  with
              MICE-16    68000.  If   no    parameter    is
              entered,  "SP" will default.

 P|R          is  the instruction to load   MICE-32   80386
              Descriptor    Table  and  enter   into    "P"
              (Protected)  Mode, or to download data in   a
              real  (R)  mode.  Hence these parameters  are
              applicable to MICE-32 80386 only.


 To   download  an  object  file  to  MICE  memory,   input
 DOwnload   followed  by  the  name  of  the  file  to   be
 downloaded.   The  file  may be of an  Intel  hex,   Intel
 binary (OMF),  Motorola S,  or Tektronix hex format. After
 the  object  file  is downloaded,  the  symbol table  file
 specified by the download filename,  is then automatically
 loaded immediately.

 To  abort downloading after it has been initiated,   press
 <ESC> and the message-

          "DOWNLOAD ABORTED!"

 will display.

 Also  note that if downloading is unsuccessful, an   error
 message-

          "DOWNLOAD FAILURE!"

 will display and USD-II will exit from this command.

#h

 FLoat  [Physical] [address [data-1 [...data-8]]]

------------------------------------------------------------

 FLoat       is the command for Memory Modify and specifies
             the  desired data format  as  single-precision
             (32-bit).

 Physical    classifies type of address as  "physical"  for
             MICE-32 80386  and  MICE-16 80286.  Otherwise,
             the address is "logical".

 address     specifies the location where the Memory Modify
             operation  is to begin.  It is  a  hexadecimal
             address  in the memory space of the  emulation
             CPU.

             Address  may be expressed in hex value  or  in
             any     USD-II     symbol     format,     i.e.
             [%%module]%symbol.

 data-1...8  are the floating-point values. Up to 8  values
             may   be  entered.  A   floating-point   value
             consists of the following:

          [sign] integer_part [.fractional_part] [exponent]


 If  no  parameter  is entered,  the  USD-II  displays  the
 starting address content  of the current PC  and waits for
 further  input. To  change the value held  in the location
 displayed,  enter a new  floating-point value,  then press
 <CR> to go to the  next location  in memory or <Ctrl-J> to
 go to the preceding location. Pressing  <CR>  or  <Ctrl-J>
 alone,  without  first inputting  a new value, leaves  the
 contents   of   the  location  unchanged;  pressing  <ESC>
 terminates the function.

#h

 FOreground  {Breakpoint|CODe|COMmand|Register|Stack|Trace}
             [{BLAck|Red|Green|BLUe|Yellow|Magenta|Cyan
              |White} [BLAck|Red|Green|BLUe|Yellow|Magenta
              |Cyan|White]]

------------------------------------------------------------

 FOreground       is  the  command  to  bring  forward  the
                  hidden viewports on the screen and at the
                  same   time,   defining   the    viewport
                  background and viewport text colors.

 Breakpoint|CODe  are the viewport-to-reveal options.
 |COMmand|...

 BLAck|Red|...    are options for viewport background color
                  and text color (first and second group of
                  color options respectively).


 With CGA/Hercules monitors, the red, green and blue colors
 are turned to black. Yellow, magenta and cyan colors  will
 become white.

#h

 HElp  [USD2]

------------------------------------------------------------

 HElp  is the command to display command syntax listing  of
       USD-II or of the currently linked MICE-8/16/32.

 USD2  is the option to display all USD-II command syntax.


 If no parameter is entered, the "HElp" command will be the
 same as the "HElp" command  of the MICE-8/16/32 with which
 USD-II is currently linked.

 "HElp"  for USD-II commands is also accessible with  mouse
 from the USD-II "HELP" menu of the menu bar  where user is
 directed to a pop-up window displaying command summary and
 individual command descriptions.

 If user wishes to access MICE-II HELP feature, enter <?>

#h

 HIStory  [number]

------------------------------------------------------------

 HIStory  is the command to repeat a selected  line command
          from  Command History stored in  history  buffer.
          "HIStory"  alone without parameter  will  display
          the  stored line commands arranged and  numbered
          in chronological order.

 number   is  the  reference  number  (1  to  32)  of   the
          particular  line command in the  command  history
          buffer, specified to be repeated.


 USD-II  provides  a history buffer where up to 32  of  the
 most  recently  executed  line commands  are automatically
 stored. Contents of the history buffer may be displayed to
 select a  line command to be repeated. This eliminates the
 need to constantly re-keying frequently used commands.

 This command is also accessible from the USD-II  "HISTORY"
 menu  of the menu bar where user is directed to  a  pop-up
 window  displaying scrollable menu for the 32 of the  most
 recently executed line commands.

#h

 INClude  filename [(arg0,...,arg9)]

------------------------------------------------------------

 INClude       is the command to execute   a   user-defined
               command file.

 filename      is the command file to be executed.

 arg0,...arg9  are the arguments   (MICE/USD-II   commands,
               command   parameters, sub-commands,   nested
               commands,   macros, values,  etc.)   defined
               to  substitute the corresponding   variables
               (%0, %1, %2,...%9) specified  in the command
               file.


 When "INClude" command is executed, the variables (%0, %1,
 %2,...%9)  specified in the command file  are  substituted
 with  the argument  in the same sequence they appeared  in
 the  command line as shown below. Note that arguments  are
 to   be  entered  separated  by  commas  and  enclosed  in
 parenthesis-

               >INC INITIAL.INC(100,10,200,8F,0,3FFFF)

 When  executed, "100" replaces "%0", "10"  replaces  "%1",
 "200" replaces "%2", etc., in the command file.


 Sub-commands:

   BELL  [count]
   ECHO  [ON|OFF]
   ERROR  {ABORT|CONTINUE}
   GET  str
   GOTO  label
   IF [_NOT] / ELSE
   INClude
   LOOP
   LOOPEND  [count]
   PAUSE  [str|count]
   REMark  str
   TICK  [count]
   :label
   \
   %0 - %9

#h

 IStep  [Over] [count|FOrever]

------------------------------------------------------------

 IStep    is the command for instruction step. This command
          executes   instruction  by  single-stepping   and
          returns  to command prompt mode  after  executing
          the  command. IStep alone without  any  parameter
          will   result  to  a  single   step   instruction
          execution. After each step,  the  REGISTER,  CODE
          and STACK viewports information are also  updated
          accordingly  if their respective  updating toggle
          is enabled.

 Over     is  the option  to  treat  subroutines  as normal
          instructions. With  this  option, user  needs not
          step into subroutines which he  is not  concerned 
          about. USD-II will  run  through such subroutines
          in  real  time. Note  that  this  option  is  NOT
          applicable to MICE-II.

 count    is  a  hexadecimal  value  from  1H   to   0FFFFH
          specifying  the number of times  the  instruction
          program  has to step.

 FOrever  is the option to  step  instruction  continuously
          until  forced  to stop  by  pressing  <ESC>  key.


 User  may increase stepping  speed  by  disabling viewport
 update feature  on some viewports as described in "UPDate"
 command.

#h

 JOurnal  [filename [APPEND]|CLOSE]

------------------------------------------------------------

 JOurnal   is   the  command to log  all  of   the  COMMAND
           Viewport  activities  (input and response) to an
           assigned  filename as they took place  during  a
           debugging  session. "JOurnal" alone without  any
           parameter  will display the journal filename and
           the journal toggle status.

 filename  is  the  filename created to  store  the  logged
           COMMAND Viewport activities.

 APPEND    is  the  instruction which must  be  entered  to
           append  the  newly logged   activities  into  an
           existing  filename. Otherwise existing  data  in
           the file  will be automatically overwritten.

 CLOSE     is  the  option  to  save  the  logged   COMMAND
           Viewport activities into the assigned  filename,
           and then end the logging session.

#h

 LOAd  filename

------------------------------------------------------------

 LOAd      is  the command to load  symbol file  from  disk
           into USD-II.

 filename  specifies the symbol file to be loaded.

#h

 LOG  [filename [APPEND]|CLOSE]

------------------------------------------------------------

 LOG       is the command to log all of the  command  lines
           to an assigned filename as they are entered  and
           executed  during  a  debugging  session.   "LOG"
           alone  without  any parameter will  display  the
           log filename and the log toggle status.

 filename  is  the  filename created to  store  the  logged
           command lines.

 APPEND    is  the  instruction which must  be  entered  to
           append  the newly logged command lines  into  an
           existing  filename. Otherwise existing  data  in
           the file will be automatically overwritten.

 CLOSE     is the option to save the logged  command  lines
           into  the  assigned filename, and then  end  the
           logging session.

#h

 MODUle

------------------------------------------------------------

 MODUle  is the command to display all modules existing  in
         the symbol file. When available, current module is
         distinguished from other modules with an  asterisk
         (*) prefix.

#h

 OPTions  [{Symbol|Log|Journal|Breakpoint} {ON|OFf}]

------------------------------------------------------------

 OPTions     is   the   command   to    activate/deactivate
             available  USD-II  optional  features.  If  no
             parameter is entered, current "OPTions" status
             will display.

 Symbol      is  the option which  offers  symbolic  output
             format  for MICE Disassemble, single-Step  and
             List trace buffer commands.

 Log         is   the   option   to   log   all   of    the
             executed command lines to a filename.

 Journal     is  the  option to  log  all  of  the  COMMAND
             viewport activities (input and response) to  a
             filename.

 Breakpoint  is  the  option to set a  software   execution
             breakpoint.

 ON|OFf      is  the  toggle  to  enable  or  disable   the
             Symbol/Log/Journal/Breakpoint feature.

#h

 QUEry  {symbol|hex_address}

------------------------------------------------------------

 QUEry        is the command to query for the address  of a
              specified  symbol  or  the  symbol name  of a
              specified address. USD-II will search through
              the symbol table and list all occurrences  of
              the specified symbol or address.

 symbol       is  the  corresponding  symbol  name  of  the
              address    in   query.   Module    name    in
              "[%%module]%symbol" symbol format may also be
              specified, but only the specified module will
              be searched.

 hex_address  is  the  corresponding  hexadecimal   address
              setting of the symbol name in query.

#h

 SOFtkey  {K1|K2|K3|K4|K5|K6|K7|K8} command_description

------------------------------------------------------------

 SOFtkey      is  the  command  to  define  a  function-key
              operated macro command to replace one or more
              chained standard line commands.

 K1...K8      is the function-key  (<F1> to <F8>)  assigned
              to combine with <Shift> key  to form  a macro
              command name.

 command_     specifies   the   line   command(s)   to   be
 description  substituted by the <Shift>  and  function-key
              (<F1> to <F8>) combination. If more than  one
              line  command  are  specified,  they   should
              chained and separated with a semi-colon (;).

#h

 SYMbol  [All|Global|module_name]

------------------------------------------------------------

 SYMbol       is  the  command to display  symbols.  If  no
              parameter  is  given, symbols  under  current
              module will be listed.

 All          is  the  option  to   display   all   symbols
              including global symbols (from symbol file or
              created by "CReate" command) and  symbols  in
              each module.

 Global       is the option to display global symbols (from
              symbol file or created by "CReate" command).

 module_name  specifies  the module name  under  which  the
              symbols are to be displayed. Module name must
              be  prefixed  with  double  percent  (%%)  to
              distinguish it from the hex value in the MICE
              command.

#h

 UPDate  [{Breakpoint|CODe|Register|Stack|Trace} {ON|OFf}]

------------------------------------------------------------

 UPDate           is the command to enable or disable  data
                  updates  on BREAKPOINT,  CODE,  REGISTER,
                  STACK and TRACE viewports while  relevant
                  command is being executed.

 Breakpoint|CODe  are the viewports in which data  updating
 |Register|...    feature may be enabled or disabled.

 ON|OFf           is the enable/disable toggle.

#h

 UPload  filename [I [X|P]|T [X|P]|M|UP|UD|SP|SD]

------------------------------------------------------------

 UPload       is  the command to upload  object  code  from
              MICE to a specified filename.

 filename     is the file to be uploaded.

 I            Intel hex or extended Intel hex.

 T            Tektronix hex.

 X|P          are the two types of optional  memory  spaces
              of MICE-8 8052:
              - Data Memory (X)
              - Program Memory (P)
              Hence, these options are applicable and to be
              specified  only  when USD-II is  linked  with
              MICE-8 8052. If no parameter is entered,  "P"
              will default.

 M            Motorola hex.

 UP|UD|SP|SD  are the four types of optional memory  spaces
              of MICE-16 68000:
              - User Program (UP)
              - User Data (UD)
              - Supervisor Program (SP)
              - Supervisor Data (SD)
              Hence, these options are applicable and to be
              specified  only when USD-II is   linked  with
              MICE-16  68000. If no parameter  is  entered,
              "SP" will default.


 To  upload  object code to the specified  filename,  input
 "UPload"  followed by the name of the file to be  uploaded
 and  the  desired  memory space type. If  the  MICE  model
 running on USD-II is of Intel 8086/88, 80186/188, 80286 or
 80386, then the Code Segment value for the object code  to
 be uploaded  will  display. Then  the memory range request
 message-

          "Upload memory range: "

 will  display.  Respond with the range to be  uploaded  or
 press  <ESC>  to terminate upload command. More  than  one
 segment may be uploaded. The uploaded memory contents  are
 then sent through MICE to a disk file.

 If  <ESC>  is  entered or  uploading  is  unsuccessful,  a
 warning message-

          "UPLOAD ABORTED!"

 will display and the command is aborted.

#h

 URECall  [W|K]

------------------------------------------------------------

 URECall  is  the  command  to  recall  window  status  and
          softkey  definitions   recently  saved   in   the
          USD2.SAV file.

 W|K      W is  specified if  only window status is  to  be
          recalled. Likewise, K is specified when recalling
          softkey definitions alone. If none is  specified,
          both  window status and softkey definitions  will
          be recalled.


 This command is  useful  when  user  wishes  to  recall  a
 recently saved window status and softkey definitions while
 in a USD-II session.

#h

 USAVe  [W|K]

------------------------------------------------------------

 USAVe  is  the  command  to  save  current  window  status
        (including screen layout and  viewport update flag,
        but NOT its contents) and softkey  definitions into
        the USD2.SAV file.

 W|K    W is specified when only the window status is to be
        saved  and  K  is   specified  if   saving  softkey
        definitions  alone.  If  none  is  specified,  both
        window  status  and  softkey  definitions  will  be
        saved.


 To retrive the saved window status and softkey definitions
 from USD2.SAV file while in a USD-II session, use  URECall
 command (Section 3.7.4).

 The latest saved status in the USD2.SAV file (if any) will
 become the  default window status and  softkey definitions
 the  next time USD-II is  invoked,  otherwise the original
 USD-II default status will be recalled.

#h Dummy command for help table process

#l

Conceal Viewport          BACKground  {Breakpoint|CODe|COMmand|Register
                                       |Stack|Trace}
Set S/W Breakpoint        BREakpoint  [address]
Clear S/W Breakpoint      CLEar  [no1 [no2]]
Create Symbol             CReate  symbol_name hex_address
Delete Symbol             DELete  symbol_name
Double Floating Point     DOUble  [Physical] [address [data-1 [...data-8]]]
Download File             DOwnload  filename [UP|UD|SP|SD|P|R]
Single Floating Point     FLoat  [Physical] [address [data-1 [...data-8]]]
Reveal Viewport           FOreground  {Breakpoint|CODe|COMmand|Register
                                       |Stack|Trace}
                                      [{BLAck|Red|Green|BLUe|Yellow|Magenta
                                        |Cyan|White} [BLAck|Red|Green|BLUe
                                        |Yellow|Magenta|Cyan|White]]
USD2 Command Help         HElp  [USD2]
Command History           HIStory  [number]
Include Command File      INClude  filename [(arg0,...,arg9)]
Instruction Step          IStep  [Over] [count|FOrever]
Log Output File           JOurnal  [filename [APPEND]|CLOSE]
Load Symbol Table         LOAd  filename
Log Command File          LOG  [filename [APPEND]|CLOSE]
Directory Module          MODUle
Optional Functions        OPTions  [{Symbol|Log|Journal|Breakpoint}
                                    {ON|OFf}]
Symbol/Address Query      QUEry  {symbol|hex_address}
Define Softkey            SOFtkey  {K1|K2|K3|K4|K5|K6|K7|K8}
                                   command_description
List Symbol               SYMbol  [All|Global|module_name]
Enable/Disable Viewport
       Update             UPDate  [{Breakpoint|CODe|Register|Stack|Trace}
                                   {ON|OFf}]
Upload File               UPload  filename [I [X|P]|T [X|P]|M|UP|UD|SP|SD]
Recall Window/Softkey     URECall  [W|K]
Save Window/Softkey       USAVe  [W|K]
___________________________________________________________________________

FUNCTION KEYS:

  On line help                   <F1> 
  MICE-II "r" command            <F2> 
  Last history buffer command    <F3> 
  Next history buffer command    <F4> 
  IStep                          <F5> 
  IStep Over                     <F6> 
  IStep FOrever                  <F7> 
  IStep Over FOrever             <F8> 
  Toggle-zoom command viewport   <F9>
  Softkey K1-K8                  <Shift-F1> - <Shift-F8>
#l

#e

#w

