home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 6 File / 06-File.zip / dumputil.zip / DMP.DOC < prev    next >
Text File  |  1996-04-11  |  20KB  |  429 lines
  1.                      Grope file manipulation utilities
  2.  
  3.  
  4.           Overview                                               2
  5.           A short description of each utility                    2
  6.           Installation                                           2
  7.           Inquiries                                              3
  8.           DMP                                                    3
  9.           CAP                                                    6
  10.           EXPORT                                                 7
  11.           IMPORT                                                 7
  12.           Appendix A - field types                               8
  13.  
  14.        Overview
  15.  
  16.  This  document  contains a short description of  the  interactive  file
  17.  manipulation  utilities: CAP, DMP, EXPORT and  IMPORT,  which  allow  a
  18.  user  to  interactively  manipulate data files  for  which  the  record
  19.  structure is known.
  20.  
  21.  The  utilities are all based on the ability to parse C language  struct
  22.  definitions.  The  user supplies a C header file  containing  a  struct
  23.  definition  (or definitions), that represent the record layout  of  the
  24.  data file that the user wishes to manipulate. The utility uses this  to
  25.  build  a symbol table, which contains field data type and field  offset
  26.  information, which is then used to manipulate the data on  a  field  by
  27.  field basis.
  28.  
  29.        A short description of each utility
  30.  
  31.  DMP  -  This  program produces a field by field dump of  a  data  file.
  32.  Fields  that are stored in a format that is incomprehensible to  humans
  33.  are  automatically  converted to a human readable format.  I.e.  binary
  34.  numbers  are  displayed as decimal, EBCDIC characters are displayed  as
  35.  ASCII  etc.  The  utility can produce a simple  text  dump  or  it  can
  36.  produce  a  series of forms, which allow the user the added benefit  of
  37.  being  able  to edit the data in a file. In this instance the  data  is
  38.  converted back to its machine format prior to being written to disk.
  39.  
  40.  CAP  -  This utility allows the user to capture data to a file  without
  41.  writing  any code to do so. Typically one may want to quickly  generate
  42.  a  data  file for use in a specific application. This is useful  during
  43.  the  testing and development stages of a programming project, which  is
  44.  being  written in C, as it allows the user to use the header files  for
  45.  the project to generate data.
  46.  
  47.  EXPORT  -  This utility allows a user to dump the contents  of  a  data
  48.  file  to  a  text  file in which the data is stored in ASCII  delimited
  49.  format. This is useful for exporting files, which the user may wish  to
  50.  import  into  a  database,  which supports  importing  files  in  ASCII
  51.  delimited format.
  52.  
  53.  IMPORT - This utility allows the user to import a ASCII delimited  text
  54.  file  into a data file. All fields are translated from their ASCII form
  55.  into the machine equivalent.
  56.  
  57.        Limitations
  58.  
  59.  The  software accompanying this document is for demonstration  purposes
  60.  only.   It is a fully functional copy of the package with the following
  61.  restrictions:  No  support for the following 'C'  data  types  :  long,
  62.  float/double. No support for the special data types : Bcd,  ebcdic  and
  63.  binary. Limited macro preprocessing.
  64.  
  65.        Installation
  66.  
  67.  The  accompanying disk contains a version of the utilities for both  OS/2
  68.  and  DOS.  To install the utilities for OS/2 copy the files  in  the  OS2
  69.  directory  to an appropriate directory on your hard disk and  modify  the
  70.  path  statement in the config.sys file. To install the utilities for  DOS
  71.  copy  the files in the DOS directory to an appropriate directory on  your
  72.  hard disk and modify the path statement in the autoexec.bat file.
  73.        Inquiries
  74.  
  75.  Any  queries  relating  to this software can be sent  to  John  Holton,
  76.  Internet  address: sftfocus@iaccess.za. The postal address of Softfocus
  77.  cc  is  P.O. Box 51380, Waterfront, Cape Town, South Africa, 8002.  The
  78.  telephone number is 27-21-237633 and the fax number is 27-21-236633.
  79.  
  80.        DMP
  81.  
  82.  This  use  of  dmp  is  probably best illustrated by  example.  I  have
  83.  created   a   file  called  "test.h",  which  contains  the   structure
  84.  definitions  of the file "test". The records in "test" are  defined  by
  85.  the  structure  DETAILS, which contains another  sub  structure  called
  86.  ADDRESS.
  87.  
  88.  This is the contents of "test.h".
  89.  
  90.  
  91.  typedef unsigned char BYTE;
  92.  typedef unsigned long DWORD;
  93.  
  94.  typedef struct ADDRESS{
  95.                           char addlines[4][30];
  96.                           char phone[10];
  97.                           char zip[5];
  98.                        }ADDRESS;
  99.  
  100.  typedef struct DETAILS{
  101.                            char name[20];
  102.                            char sex;
  103.                            DWORD salary;
  104.                            ADDRESS address;
  105.                        }DETAILS;
  106.  
  107.  To  get  a dump of the file test one would enter the following  command
  108.  string:
  109.  
  110.  dmp -htest.h -pDETAILS -dtest
  111.  
  112.  Where:
  113.  -h is the header file in which the record definitions are contained.
  114.  -p  is  the  primary symbol which defines the record structure  of  the
  115.  file, "test". In this instance "DETAILS" defines the record structure.
  116.  -d is the data file that one wishes to dump, in this case "test".
  117.  
  118.  The dmp utility will then produce the listing below.
  119.  
  120.  Note  that  the dump contains a field by field view of each record  and
  121.  is  far  easier to read than a conventional dump which has no knowledge
  122.  of  the  structure of the records being dumped. This becomes even  more
  123.  apparent  the  more  complicated the structure as  one  would  have  to
  124.  manually  work  out  the field offset to determine the  contents  of  a
  125.  possibly  deeply  nested  field. The dmp utility  also  translates  the
  126.  field  data into it decimal/character equivalent which again makes  the
  127.  data  content  much  easier to read. Note that  the  dmp  utility  also
  128.  supports  the  use of output redirection symbol, >,  which  allows  the
  129.  user to direct the output to a data file.
  130.  
  131.  Record number 001
  132.  -----------------
  133.  Field Name                    Type     Hex Value        Dec/Char
  134.  equivalent
  135.  DETAILS.name                (  achr) 66 72 65 64 20 62 6c 6f : fred.blo
  136.                                       67 67 73 00 00 00 00 00 : ggs.....
  137.                                       00 00 00 00             : ....
  138.  DETAILS.sex                 (  char) 6d                      : m
  139.  DETAILS.salary              ( dword) d2040000                : 1234
  140.  DETAILS.address.addlines[0] (  achr) 35 20 6d 6f 72 61 79 20 : 5.moray.
  141.                                       70 6c 61 63 65 00 00 00 : place...
  142.                                       00 00 00 00 00 00 00 00 : ........
  143.                                       00 00 00 00 00 00       : ......
  144.  DETAILS.address.addlines[1] (  achr) 6f 72 61 6e 6a 65 7a 69 : oranjezi
  145.                                       63 68 74 00 00 00 00 00 : cht.....
  146.                                       00 00 00 00 00 00 00 00 : ........
  147.                                       00 00 00 00 00 00       : ......
  148.  DETAILS.address.addlines[2] (  achr) 63 61 70 65 20 74 6f 77 : cape.tow
  149.                                       6e 00 00 00 00 00 00 00 : n.......
  150.                                       00 00 00 00 00 00 00 00 : ........
  151.                                       00 00 00 00 00 00       : ......
  152.  DETAILS.address.addlines[3] (  achr) 73 6f 75 74 68 20 61 66 : south.af
  153.                                       72 69 63 61 00 00 00 00 : rica....
  154.                                       00 00 00 00 00 00 00 00 : ........
  155.                                       00 00 00 00 00 00       : ......
  156.  DETAILS.address.phone       (  achr) 34 36 31 34 34 30 36 00 : 4614406.
  157.                                       00 00                   : ..
  158.  DETAILS.address.zip         (  achr) 38 30 30 31 00          : 8001.
  159.  
  160.  If  one wished to edit the data in the file "test", one would enter the
  161.  following command string:
  162.  
  163.  dmp -htest.h -pDETAILS -dtest -e
  164.  
  165.  -h  specifies  the  name of the C header file in  which  the  structure
  166.  definitions are contained.
  167.  -p specifies the primary struct name that defines the record.
  168.  -d specifies the name of the data file that is to be dumped or edited.
  169.  -e  specifies  that  the dmp program must generate forms  enabling  the
  170.  user to edit and modify the data in the records.
  171.  
  172.  The  user  will  then be presented with a form defining  the  top  most
  173.  level  of  the structure being dumped. The first line of  the  form  is
  174.  broken  up as follows: The label on the left is the name of the current
  175.  structure.  The  portion to the right gives the record number  that  is
  176.  being  displayed together with the full name of the structure  relative
  177.  to  the  overall structure. This will become more apparent as we  delve
  178.  more deeply into the structure.
  179.  
  180.  Each  subsequent  line  of  the  form  represents  each  field  in  the
  181.  structure.  The name of each field is displayed on the  left.  This  is
  182.  followed  by  the type of field. (List of field types can be  found  in
  183.  appendix  A).  Followed by the actual field contents.  Note  that  this
  184.  system  automatically  translates data into  is  character  equivalent,
  185.  making  it  much easier to understand than the hex data produced  by  a
  186.  conventional  dump.  Once  the  user modifies  a  record  the  data  is
  187.  translated back to its date equivalent based on the field type,  before
  188.  being written to disk.
  189.  
  190.  The  user  may  move  around in the form using the return  key  or  the
  191.  down/up  arrow keys. One can delete the contents of a field by pressing
  192.  Alt-d  and  once the contents of the form have been modified  the  user
  193.  can  press  Alt-G  to rewrite the record to disk. Pressing  Alt-f  will
  194.  cause  the  program to exit. Pressing the Page Dn key  will  cause  the
  195.  program to display the next record without modifying the current one.
  196.  
  197.  The  top  level  form for the record defined by DETAIL  appears  below.
  198.  Note  that  each  field  name if followed by  its  field  type  (for  a
  199.  complete  description  of  the  field  types  see  Appendix  A).   This
  200.  information  if  followed  by a field containing  the  actual  data  in
  201.  translated form. Note that in the case of the address field, the  field
  202.  is  represented  by  a  + sign. This signifies  that  there  is  a  sub
  203.  structure  for  which there will be an additional  form.  If  the  user
  204.  presses the Enter key while in this field the form associated with  the
  205.  substructure will be displayed.
  206.  
  207.  +------------------------------------------------------------+
  208.  | DETAILS          [Record:1] DETAILS                        |
  209.  |                                                            |
  210.  |                                                            |
  211.  |                                                            |
  212.  | name           (  achr) fred bloggs                        |
  213.  | sex            (  char) m                                  |
  214.  | salary         ( dword) 1234                               |
  215.  | address        (struct) +                                  |
  216.  |                                                            |
  217.  +------------------------------------------------------------+
  218.  
  219.  The  address  field  contains more deeply nested  structures.  In  this
  220.  instance  the  addlines  field which is a  multi-dimensional  array  of
  221.  character  strings.  Pressing  the Enter  key  in  this  instance  will
  222.  present the user with a field allowing him or her to specify the  index
  223.  of  the array element that they wish to edit. Note that this index form
  224.  automatically  increments if one simply presses the enter  key  without
  225.  changing  the  value.  I.e.  it will automatically  step  through  each
  226.  successive array element unless told to go to a specific element.
  227.  
  228.  +----------------------------------------------------------+
  229.  | address(s)          [Record:1] DETAILS.address           |
  230.  |                                                          |
  231.  |                                                          |
  232.  |                                                          |
  233.  | addlines   ( array) +                                    |
  234.  | phone      (  achr) 4614406                              |
  235.  | zip        (  achr) 8001                                 |
  236.  |                                                          |
  237.  +----------------------------------------------------------+
  238.  
  239.  
  240.  +-------------------------------------------------------+
  241.  | Element                          [0-3]                |
  242.  |                                                       |
  243.  | ONE_DIMENSION.rowIndex  ( short) 0                    |
  244.  |                                                       |
  245.  +-------------------------------------------------------+
  246.  
  247.  +-----------------------------------------------------------------------+
  248.  |     addlines[0]             [Record:1]    DETAILS.address.addlines[0] |
  249.  |                                     |
  250.  |                                     |
  251.  |                                     |
  252.  |       addlines          (        achr)      5       moray       place |
  253.  |                                     |
  254.  +---------------------------------------------------------------------- +
  255.  
  256.  In  this  way  one  can navigate through the forms that  represent  the
  257.  various structures that make up the record. It is not necessary  to  go
  258.  to  a deeply nested substructure if the user only wishes to modify  the
  259.  higher  level portion - pressing the Alt-G key at any point will  store
  260.  the  modified record and automatically display the top level  structure
  261.  of the next record.
  262.  
  263.  Additional optional parameters.
  264.  
  265.  -o  Specifies the starting offset from which the dmp program will  dump
  266.  the data.
  267.  Syntax: -o[number]
  268.  I.e.  -o100 will start dumping the file from offset 100 (decimal). Note
  269.  that  the first byte of the file is at offset 0. If you do not  specify
  270.  the  -o  parameter  the dmp program will start dumping  the  file  from
  271.  offset 0.
  272.  
  273.  -z  specifies  the structure packing boundary which conforms  with  the
  274.  compiler that created the file.     Syntax: -Zp[number]
  275.  
  276.  This  option sets the packing of data in structures and unions  to  the
  277.  same  boundary.  The  <number>  field  represents  1-,  2-,  or  4-byte
  278.  boundaries  where each structure member is stored after the first  one.
  279.  If  you  do  not use the -z parameter, structure members are packed  on
  280.  1-byte boundaries--that is, they are stored contiguously.
  281.  
  282.        CAP
  283.  
  284.  The  capture  program allows a user to capture data to a file.  If  the
  285.  file  does not exist it will be created. If it does exist the data will
  286.  be  appended to the file. The operation of the program is very  similar
  287.  to that of the dmp program and will not be discussed here.
  288.  
  289.  The command line parameters that the program accepts are as follows:
  290.  
  291.  -h Header file name
  292.  -p Primary symbol
  293.  -d Data file
  294.  
  295.  For  example  to  capture data to the file "test" one would  enter  the
  296.  following command string:
  297.  
  298.  cap -htest.h -pDETAILS -dtest
  299.  
  300.        EXPORT
  301.  
  302.  The  export  utility will export data from a flat  binary  file  to  an
  303.  ASCII  delimited file in which each record is separated by  a  carriage
  304.  return/linefeed combination and each field is delimited by  a  comma  -
  305.  the default delimiter.
  306.  
  307.  export -htest.h -pDETAILS -dtest -ftest.exp
  308.  
  309.  "fred bloggs",m,1234,"5 moray place","oranjezicht","cape town","south
  310.  africa","4614406","8001",(cr/lf)
  311.  "maria bloggs",m,333,"5 morag place","oranjezicht","cape town","south
  312.  africa","4614406","8001",(cr/lf)
  313.  
  314.  Usage -hHeaderFile -dDataFile -pPrimarySymbol -fOutputFileName [-
  315.  $Delimeter] [-zPacking] [-oOffset]");
  316.  
  317.  Additional Parameters
  318.  
  319.  -h Header file
  320.  -d Data file
  321.  -p Primary Symbol
  322.  -f Output file name
  323.  Optional Parameters
  324.  -$ Delimiter
  325.  -z Structure packing
  326.  -o Starting offset in the data file
  327.  
  328.        IMPORT
  329.  
  330.  The import utility allows the user to create a data file by importing
  331.  records that are contained in an ASCII delimited file. Each record is
  332.  separated by a carriage return/linefeed. For example if one wished to
  333.  create a file called "newtest" from the data in "test.exp" (See the
  334.  export example) one would enter the following command line.
  335.  
  336.  import -htest.h -pDETAILS -dnewtest -itest.exp
  337.  
  338.  Where
  339.  -h represents the header file in which the structure definitions are
  340.  contained.
  341.  -p represents the primary symbol.
  342.  -d represents the name of the file that one wishes to create. (If the
  343.  file already exists the data will be appended to it).
  344.  -i represents the name of the import file in which the delimited data is
  345.  contained.
  346.  
  347.  Optional parameters
  348.  -$ represents the field delimiting character. (The system defaults to a
  349.  ',').
  350.  -z represents the packing boundary.
  351.  -l represents the name of a log file, which will record any errors in
  352.  the input process.
  353.  
  354.  Note that the import and export utilities are useful if one wishes to
  355.  modify the record layout of a file. I.e. if one wanted to increase the
  356.  size of a field in the record one could export the file, then delete the
  357.  original file, modify the header file and then import the file using the
  358.  new structure.
  359.        Appendix A - field types
  360.  
  361.  The field types displayed next to the field names in forms and in text
  362.  are as follows:
  363.  
  364.  Displayed    'C'         Additional description
  365.  text         equivalent
  366.  byte         unsigned    
  367.               char
  368.  char         char        
  369.  ebcdic       EBCDIC      
  370.  dword        unsigned    
  371.               long
  372.  long         long        
  373.  ushort       unsigned    
  374.               short
  375.  short        short       
  376.  uint         unsigned    
  377.               int
  378.  int          int         
  379.  ptr          pointer     
  380.  achr         array of    
  381.               char
  382.  abcd         array of    The utilities support the
  383.               binary      additional keywords of signed
  384.               coded       bcd and unsigned bcd. A struct
  385.               decimal     field specified as signed bcd
  386.                           uses the first byte to specify
  387.                           the sign and the length. An
  388.                           unsigned bcd number has no
  389.                           sign/length byte preceding the
  390.                           number. A 10 digit signed bcd
  391.                           number would be declared as
  392.                           follows: signed bcd number[6];
  393.                           I.e one byte for the
  394.                           sign/length byte and the 5
  395.                           bytes for the packed decimal
  396.                           number.
  397.  bin          binary      
  398.  abin         array of    Due to the memory storage
  399.               binary      system used by Intel
  400.                           processors, an unsigned int
  401.                           would be stored in reverse
  402.                           order. I.e the least
  403.                           significant byte is stored
  404.                           first. A binary number however
  405.                           is stored in its correct
  406.                           sequence. Therefore one would
  407.                           declare a two byte binary
  408.                           number as follows: binary
  409.                           number[2];
  410.  aebc         array of    
  411.               ebcdic
  412.  enum         enum        Enum values are displayed in
  413.                           dumps as their value
  414.                           equivalents. I.e a field
  415.                           declared as having a enum
  416.                           range of {small,medium,large}
  417.                           would display the value
  418.                           'medium' if the data contained
  419.                           an integer value of 1.
  420.  bcd          binary      
  421.               coded
  422.               decimal
  423.  struct       struct      
  424.  array        array of    
  425.               unknown
  426.               type
  427.  float        float       
  428.  
  429.