File Reporter is a utility available with KEYpak that allows you to identify the file format of a document. At the time of installation, the File Reporter will be automatically installed on your system.
• A stand-alone program to determine the format of any document
• An Application Program Interface (API)
The following pages describe both procedures for the UNIX
environment.
This chapter also lists the file formats detected by the File Reporter.
To determine the format of any document, use the kwad (File Reporter) utility provided with your KEYpak installation.
To run the File Reporter utility, enter the following command at the UNIX prompt:
kwad <document name>
In the above command,<document name> is the name of the document for which you want to determine the file format. For example, if you want to determine the format of the file test.dat, enter:
kwad test.dat
The File Reporter will determine the format of the file and display a one line description similar to the following:
test.dat <AF> Text Word Processor file.
You can also use the kwad command with multiple files. For example to find the file formats for all documents in a directory, enter:
kwad *.*
The File Reporter utility will display a one line description for each document in the directory.
There are two options available with the File Reporter for UNIX. These options allow you to change the output format.
-s
To use this option, use the following syntax of the command:
kwad -s <file name>
The File Reporter will generate a space delimited string of hexadecimal attribute numbers.
For example:
01 02 05 0 0 00 0
Each of the numbers generated by the File Reporter represents an attribute of the file. The following categories of attributes exist:
1. File Class
2. Major Format
3. Minor Format
4. Major Version
5. Minor Version
6. Encapsulation
7. Encryption
For a list of categories and possible values of attributes, refer to the section “File Formats” in this chapter.
In the previous example, the attribute numbers indicate that the file type is ASCII with the following attributes:
File Class - Word Processor
Major Format - ASCII
Minor Format - Text
Major Version - All
Minor Version - All
Encapsulation - None
Encryption - Not encrypted
-f<Mapping File>
This option allows you to define the output through a mapping file. This is done by comparing the attribute numbers (as described in the -s option) with attribute numbers in the mapping file. To use this option, use the following format of the command:
kwad -f<mapping file> <file name>
In the above command, <mapping file> refers to the mapping file on your system. If the -f option is used without the mapping file name, the default mapping file kwad.adc will be assumed.
Mapping File
A mapping file is an ASCII file containing nine fields per line.
The first seven fields are attribute numbers as described in the -s option. A star (*) is used when the field is to be ignored. A good place to use this is in the Minor Version field, as most converters are able to handle all versions of a particular format.
The eighth field is used as a return value and the ninth field contains the one line description of the detected format. When the first seven fields match, the return value is set and the one line description (e.g. An ASCII file) is displayed or sent to the output file.
A dash (-) for the eighth field indicates that the default return value is to be used.
The File Reporter returns a value of 0 when the file format is successfully determined. By default, the following return values are defined:
255 Unable to determine file type
254 Failed to open file (may be mapping file)
253 Failed to find a match in the mapping file
252 Invalid option
0 File
format determined successfully
Note The above values may be changed by using the -f option.
KEYpak can also be integrated into other applications and used as
an API (Application Program Interface).
To determine the format of a file, File Reporter calls the library function kwAutoDet. The
file format information is passed to and from kwAutoDet by a C structure of type adDocDesc. The adDocDesc structure is defined in the
file kwautdef.h.
To use the kwAutoDet function, declare a adDocDesc structure and set adDocDesc.fileRec to the name of the file to be identified. Call kwAutoDet with a pointer to your declared adDocDesc structure. kwAutoDet will fill in the adDocDesc with the values appropriate for the file.
The file information returned in adDocDesc is divided into the following categories:
1. File Class
2. Major Format
3. Minor Format
4. Major Version
5. Minor Version
6. Encapsulation
7. Major Format Descriptions
8. Translator mnemonic
9. Encryption
For possible values of the above categories, refer to the section “File Formats”. The combination of the above categories is the file type.
The return value of the kwAutoDet function is the same as the adDocDesc.adClass field.
If an error occurs while trying to identify the file, the adDoc.Desc.adClass field is set to -1.
Example The following C program is an example of how to use the API. The program must be linked with the libkwad.a library provided with your installation.
#include <stdio.h>
#include <string.h>
#include "kwautdef.h"
int main(int argc, char *argv[])
{
adDocDesc docDesc = {0};
docDesc.fileRec = (char *)argv[1];
if (-1 == kwAutoDet(&docDesc)) printf("Auto-detect failed.\n");
else
{
printf("Class #: %d\n", docDesc.adClass);
printf("Major format #: %d\n", docDesc.adFormat);
printf("Minor format #: %d\n", docDesc.minorFormat);
printf("Major version #: %d\n", docDesc.majorVersion);
printf("Minor version #: %d\n", docDesc.minorVersion);
printf("Encapsulation Method #: %d\n", docDesc.macEncap.encapType);
printf("Major format: %s\n", docDesc.descStr);
printf("KEYpak mnemonic: %s\n", docDesc.mnemStr);
printf("Encription: %d\n", docDesc.isEncripted);
}
}
The File Reporter will provide an output similar to the following:
Class #: 1
Major format #: 2
Minor format #: 0
Major version #: 0
Minor version #: 0
Encapsulation Method #: 0
Major format: ASCII
KEYpak mnemonic: AF
Encryption: 0
This section lists the categories of file attributes and their values supported by the KEYpak File Reporter. For a list of KEYpak supported conversion formats and their mnemonics, see Appendix A.
When you use the File Reporter Stand-alone with the -s option or the File Reporter API, use this section to determine the file attributes from the generated category numbers.