# Getting Started

In this chapter we assume that H2D is properly installed and configured (See Chapter Configuring H2D).

- Creating a working directory
- Invoking H2D
- H2D usage example
- Error reporting

## Creating a working directory

Redirection files give you complete freedom over where you keep your header files and any files which H2D itself creates for further use. It is recommended to work in a project oriented fashion --- i.e. to have a separate directory hierarchy for each set of header files you wish to translate.

In this case, each project shall have a main working directory. The script called `h2dwork` may be used to create the required subdirectories and a redirection file. For example, to create a directory structure for a project called `myproj` in the current directory, issue the following commands:

`mkdir myproj`
`cd myproj`
`h2dwork`

Note: Since H2D preserves directory hierarchies of original header files. you may also need to create additional subdirectories. See File inclusion for more information.

## Invoking H2D

H2D is implemented as a command line utility called `h2d`. To translate a header file (or a set of header files), type

`h2d { HeaderFile } { Option } [ -prj=ProjectFile ]`

at the command prompt, where `HeaderFile` is a header file name.

The syntax for `Option` is described in Configuration file.

If you specify the `-prj` option, each header will be translated as if it was specified in a `!module directive` in `ProjectFile`.

To process a project file, type

`h2d =p ProjectFile { Option }`

To view the default option values, type

`h2d =o`

If invoked without parameters, the utility prints a brief help information.

## H2D usage example

Copy the H2D sample included in your XDS or H2D distribution to a working directory and type

`h2d =p example.h2d`

at the command prompt. The H2D banner line will appear:

`H2D v1.30 (c) XDS 1996-1997`
`File example.h`

After translation the following lines will be displayed:

`no errors, lines 23.`
`----------------------------------------------`
`Files 1, lines 23, no errors, time 0:3.`

showing the number of errors, the number of source lines in the file, and some statistics. The following files will be generated:

`h2d_example.def` | basic definition module
`h2d_example.h` | definitions of types generated by H2D
`mac_example.def` | macro definition module
`mac_example.mod` | prototype macro implementation module

## Error reporting

When H2D detects an error in the input file, it displays an error report. It contains the file name and position (line and column numbers) where the error occurred:

`Error [ example.h 16:44 ] ** Duplicate identifier 'insert'`

The error which is often encountered is

`Error [...] ** Expected , or ;`

In most cases it means that an identifier is undefined for some reason. Try to put "," or ";" at the specified position to find out what is the problem source.