7.   Using KEYpak File Reporter

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.

Using File Reporter as a Stand-alone Program

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.

Options

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.

Return Values

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.

Using File Reporter as an API

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.

Return information

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

File Formats

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.