home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 6 File
/
06-File.zip
/
dumputil.zip
/
DMP.DOC
< prev
next >
Wrap
Text File
|
1996-04-11
|
20KB
|
429 lines
Grope file manipulation utilities
Overview 2
A short description of each utility 2
Installation 2
Inquiries 3
DMP 3
CAP 6
EXPORT 7
IMPORT 7
Appendix A - field types 8
Overview
This document contains a short description of the interactive file
manipulation utilities: CAP, DMP, EXPORT and IMPORT, which allow a
user to interactively manipulate data files for which the record
structure is known.
The utilities are all based on the ability to parse C language struct
definitions. The user supplies a C header file containing a struct
definition (or definitions), that represent the record layout of the
data file that the user wishes to manipulate. The utility uses this to
build a symbol table, which contains field data type and field offset
information, which is then used to manipulate the data on a field by
field basis.
A short description of each utility
DMP - This program produces a field by field dump of a data file.
Fields that are stored in a format that is incomprehensible to humans
are automatically converted to a human readable format. I.e. binary
numbers are displayed as decimal, EBCDIC characters are displayed as
ASCII etc. The utility can produce a simple text dump or it can
produce a series of forms, which allow the user the added benefit of
being able to edit the data in a file. In this instance the data is
converted back to its machine format prior to being written to disk.
CAP - This utility allows the user to capture data to a file without
writing any code to do so. Typically one may want to quickly generate
a data file for use in a specific application. This is useful during
the testing and development stages of a programming project, which is
being written in C, as it allows the user to use the header files for
the project to generate data.
EXPORT - This utility allows a user to dump the contents of a data
file to a text file in which the data is stored in ASCII delimited
format. This is useful for exporting files, which the user may wish to
import into a database, which supports importing files in ASCII
delimited format.
IMPORT - This utility allows the user to import a ASCII delimited text
file into a data file. All fields are translated from their ASCII form
into the machine equivalent.
Limitations
The software accompanying this document is for demonstration purposes
only. It is a fully functional copy of the package with the following
restrictions: No support for the following 'C' data types : long,
float/double. No support for the special data types : Bcd, ebcdic and
binary. Limited macro preprocessing.
Installation
The accompanying disk contains a version of the utilities for both OS/2
and DOS. To install the utilities for OS/2 copy the files in the OS2
directory to an appropriate directory on your hard disk and modify the
path statement in the config.sys file. To install the utilities for DOS
copy the files in the DOS directory to an appropriate directory on your
hard disk and modify the path statement in the autoexec.bat file.
Inquiries
Any queries relating to this software can be sent to John Holton,
Internet address: sftfocus@iaccess.za. The postal address of Softfocus
cc is P.O. Box 51380, Waterfront, Cape Town, South Africa, 8002. The
telephone number is 27-21-237633 and the fax number is 27-21-236633.
DMP
This use of dmp is probably best illustrated by example. I have
created a file called "test.h", which contains the structure
definitions of the file "test". The records in "test" are defined by
the structure DETAILS, which contains another sub structure called
ADDRESS.
This is the contents of "test.h".
typedef unsigned char BYTE;
typedef unsigned long DWORD;
typedef struct ADDRESS{
char addlines[4][30];
char phone[10];
char zip[5];
}ADDRESS;
typedef struct DETAILS{
char name[20];
char sex;
DWORD salary;
ADDRESS address;
}DETAILS;
To get a dump of the file test one would enter the following command
string:
dmp -htest.h -pDETAILS -dtest
Where:
-h is the header file in which the record definitions are contained.
-p is the primary symbol which defines the record structure of the
file, "test". In this instance "DETAILS" defines the record structure.
-d is the data file that one wishes to dump, in this case "test".
The dmp utility will then produce the listing below.
Note that the dump contains a field by field view of each record and
is far easier to read than a conventional dump which has no knowledge
of the structure of the records being dumped. This becomes even more
apparent the more complicated the structure as one would have to
manually work out the field offset to determine the contents of a
possibly deeply nested field. The dmp utility also translates the
field data into it decimal/character equivalent which again makes the
data content much easier to read. Note that the dmp utility also
supports the use of output redirection symbol, >, which allows the
user to direct the output to a data file.
Record number 001
-----------------
Field Name Type Hex Value Dec/Char
equivalent
DETAILS.name ( achr) 66 72 65 64 20 62 6c 6f : fred.blo
67 67 73 00 00 00 00 00 : ggs.....
00 00 00 00 : ....
DETAILS.sex ( char) 6d : m
DETAILS.salary ( dword) d2040000 : 1234
DETAILS.address.addlines[0] ( achr) 35 20 6d 6f 72 61 79 20 : 5.moray.
70 6c 61 63 65 00 00 00 : place...
00 00 00 00 00 00 00 00 : ........
00 00 00 00 00 00 : ......
DETAILS.address.addlines[1] ( achr) 6f 72 61 6e 6a 65 7a 69 : oranjezi
63 68 74 00 00 00 00 00 : cht.....
00 00 00 00 00 00 00 00 : ........
00 00 00 00 00 00 : ......
DETAILS.address.addlines[2] ( achr) 63 61 70 65 20 74 6f 77 : cape.tow
6e 00 00 00 00 00 00 00 : n.......
00 00 00 00 00 00 00 00 : ........
00 00 00 00 00 00 : ......
DETAILS.address.addlines[3] ( achr) 73 6f 75 74 68 20 61 66 : south.af
72 69 63 61 00 00 00 00 : rica....
00 00 00 00 00 00 00 00 : ........
00 00 00 00 00 00 : ......
DETAILS.address.phone ( achr) 34 36 31 34 34 30 36 00 : 4614406.
00 00 : ..
DETAILS.address.zip ( achr) 38 30 30 31 00 : 8001.
If one wished to edit the data in the file "test", one would enter the
following command string:
dmp -htest.h -pDETAILS -dtest -e
-h specifies the name of the C header file in which the structure
definitions are contained.
-p specifies the primary struct name that defines the record.
-d specifies the name of the data file that is to be dumped or edited.
-e specifies that the dmp program must generate forms enabling the
user to edit and modify the data in the records.
The user will then be presented with a form defining the top most
level of the structure being dumped. The first line of the form is
broken up as follows: The label on the left is the name of the current
structure. The portion to the right gives the record number that is
being displayed together with the full name of the structure relative
to the overall structure. This will become more apparent as we delve
more deeply into the structure.
Each subsequent line of the form represents each field in the
structure. The name of each field is displayed on the left. This is
followed by the type of field. (List of field types can be found in
appendix A). Followed by the actual field contents. Note that this
system automatically translates data into is character equivalent,
making it much easier to understand than the hex data produced by a
conventional dump. Once the user modifies a record the data is
translated back to its date equivalent based on the field type, before
being written to disk.
The user may move around in the form using the return key or the
down/up arrow keys. One can delete the contents of a field by pressing
Alt-d and once the contents of the form have been modified the user
can press Alt-G to rewrite the record to disk. Pressing Alt-f will
cause the program to exit. Pressing the Page Dn key will cause the
program to display the next record without modifying the current one.
The top level form for the record defined by DETAIL appears below.
Note that each field name if followed by its field type (for a
complete description of the field types see Appendix A). This
information if followed by a field containing the actual data in
translated form. Note that in the case of the address field, the field
is represented by a + sign. This signifies that there is a sub
structure for which there will be an additional form. If the user
presses the Enter key while in this field the form associated with the
substructure will be displayed.
+------------------------------------------------------------+
| DETAILS [Record:1] DETAILS |
| |
| |
| |
| name ( achr) fred bloggs |
| sex ( char) m |
| salary ( dword) 1234 |
| address (struct) + |
| |
+------------------------------------------------------------+
The address field contains more deeply nested structures. In this
instance the addlines field which is a multi-dimensional array of
character strings. Pressing the Enter key in this instance will
present the user with a field allowing him or her to specify the index
of the array element that they wish to edit. Note that this index form
automatically increments if one simply presses the enter key without
changing the value. I.e. it will automatically step through each
successive array element unless told to go to a specific element.
+----------------------------------------------------------+
| address(s) [Record:1] DETAILS.address |
| |
| |
| |
| addlines ( array) + |
| phone ( achr) 4614406 |
| zip ( achr) 8001 |
| |
+----------------------------------------------------------+
+-------------------------------------------------------+
| Element [0-3] |
| |
| ONE_DIMENSION.rowIndex ( short) 0 |
| |
+-------------------------------------------------------+
+-----------------------------------------------------------------------+
| addlines[0] [Record:1] DETAILS.address.addlines[0] |
| |
| |
| |
| addlines ( achr) 5 moray place |
| |
+---------------------------------------------------------------------- +
In this way one can navigate through the forms that represent the
various structures that make up the record. It is not necessary to go
to a deeply nested substructure if the user only wishes to modify the
higher level portion - pressing the Alt-G key at any point will store
the modified record and automatically display the top level structure
of the next record.
Additional optional parameters.
-o Specifies the starting offset from which the dmp program will dump
the data.
Syntax: -o[number]
I.e. -o100 will start dumping the file from offset 100 (decimal). Note
that the first byte of the file is at offset 0. If you do not specify
the -o parameter the dmp program will start dumping the file from
offset 0.
-z specifies the structure packing boundary which conforms with the
compiler that created the file. Syntax: -Zp[number]
This option sets the packing of data in structures and unions to the
same boundary. The <number> field represents 1-, 2-, or 4-byte
boundaries where each structure member is stored after the first one.
If you do not use the -z parameter, structure members are packed on
1-byte boundaries--that is, they are stored contiguously.
CAP
The capture program allows a user to capture data to a file. If the
file does not exist it will be created. If it does exist the data will
be appended to the file. The operation of the program is very similar
to that of the dmp program and will not be discussed here.
The command line parameters that the program accepts are as follows:
-h Header file name
-p Primary symbol
-d Data file
For example to capture data to the file "test" one would enter the
following command string:
cap -htest.h -pDETAILS -dtest
EXPORT
The export utility will export data from a flat binary file to an
ASCII delimited file in which each record is separated by a carriage
return/linefeed combination and each field is delimited by a comma -
the default delimiter.
export -htest.h -pDETAILS -dtest -ftest.exp
"fred bloggs",m,1234,"5 moray place","oranjezicht","cape town","south
africa","4614406","8001",(cr/lf)
"maria bloggs",m,333,"5 morag place","oranjezicht","cape town","south
africa","4614406","8001",(cr/lf)
Usage -hHeaderFile -dDataFile -pPrimarySymbol -fOutputFileName [-
$Delimeter] [-zPacking] [-oOffset]");
Additional Parameters
-h Header file
-d Data file
-p Primary Symbol
-f Output file name
Optional Parameters
-$ Delimiter
-z Structure packing
-o Starting offset in the data file
IMPORT
The import utility allows the user to create a data file by importing
records that are contained in an ASCII delimited file. Each record is
separated by a carriage return/linefeed. For example if one wished to
create a file called "newtest" from the data in "test.exp" (See the
export example) one would enter the following command line.
import -htest.h -pDETAILS -dnewtest -itest.exp
Where
-h represents the header file in which the structure definitions are
contained.
-p represents the primary symbol.
-d represents the name of the file that one wishes to create. (If the
file already exists the data will be appended to it).
-i represents the name of the import file in which the delimited data is
contained.
Optional parameters
-$ represents the field delimiting character. (The system defaults to a
',').
-z represents the packing boundary.
-l represents the name of a log file, which will record any errors in
the input process.
Note that the import and export utilities are useful if one wishes to
modify the record layout of a file. I.e. if one wanted to increase the
size of a field in the record one could export the file, then delete the
original file, modify the header file and then import the file using the
new structure.
Appendix A - field types
The field types displayed next to the field names in forms and in text
are as follows:
Displayed 'C' Additional description
text equivalent
byte unsigned
char
char char
ebcdic EBCDIC
dword unsigned
long
long long
ushort unsigned
short
short short
uint unsigned
int
int int
ptr pointer
achr array of
char
abcd array of The utilities support the
binary additional keywords of signed
coded bcd and unsigned bcd. A struct
decimal field specified as signed bcd
uses the first byte to specify
the sign and the length. An
unsigned bcd number has no
sign/length byte preceding the
number. A 10 digit signed bcd
number would be declared as
follows: signed bcd number[6];
I.e one byte for the
sign/length byte and the 5
bytes for the packed decimal
number.
bin binary
abin array of Due to the memory storage
binary system used by Intel
processors, an unsigned int
would be stored in reverse
order. I.e the least
significant byte is stored
first. A binary number however
is stored in its correct
sequence. Therefore one would
declare a two byte binary
number as follows: binary
number[2];
aebc array of
ebcdic
enum enum Enum values are displayed in
dumps as their value
equivalents. I.e a field
declared as having a enum
range of {small,medium,large}
would display the value
'medium' if the data contained
an integer value of 1.
bcd binary
coded
decimal
struct struct
array array of
unknown
type
float float