HP 3000 Manuals HP 3000 Manuals
Operation
This section describes the use of H2cpy, starting with the command line
syntax.
H2cpy Syntax
H2cpy is a self-contained application which you run from the command
line. The syntax of the H2cpy command is:
h2cpy inputfile [outputfile] [options]
where:
inputfile is the C header file to be converted. If no extension is
specified, the .h extension is added. If the file is not
in the current directory, any directories specified in the
INCLUDE environment variableare searched.
If the inputfile contains #include statements, the files
they specify are read immediately and converted into COBOL
statements.
outputfile is the main output file. If the -M (multiple files) option
is used, only the simple data definitions are placed in
this file. If the -M option is not used, all output is
placed in this file. See the section The Multiple-Files
(-M) Option for more information.
If outputfile is not specified, a file with the same base
name as inputfile and an extension of .cpy
is created. If outputfile has no extension, an extension
of .cpy is added.
options controls the behavior of H2cpy. An option begins with a
dash (-). Options are not case sensitive. For example,
-M, and -m specify the same option. The options and their
descriptions appear in the following section.
On DOS, Windows and OS/2, the forward slash (/can be used in place of the
dash (-) to denote an option. Thus, /M, /m, -M and -m all specify the
same option. In this manual, the dash is used for H2cpy options. (DOS,
Windows and OS/2)
H2cpy Options.
Option Description
-------------------------------------------------------
-Cx The value of x specifies the case of the
COBOL text output:
Value Effect''
U All output is upper case.
L All output is lower case.
M The output is mixed case. All COBOL
reserved
words are upper case. All user-defined
names
have an upper-case first letter; the rest
of the
name is lower case. For example, the -CM
option would produce output as follows:
Caps-Io-Dummy''
The default is to output reserved words in
upper case. All other text is output in
the same case as it appears in the C
header file.
-Dname Defines a name whose existence can be
tested by #ifdef and #ifndef statements in
the header file. For example, any
definitions between #ifdef and #endif in
the following are included only if INCL_PM
has been defined; otherwise, they are
ignored:''
#ifdef INCL_PM . . . #endif
A name can be defined with the C #define
directive or with the -D option. The -D
option allows a name to be defined without
having to change the original C header
file. For example:
-DINCL_BASE
defines the name INCL_BASE.
To include the full set of definitions for
OS/2 programming, you should specify the
options: (OS/2)
-DINCL_PM -DINCL_BASE
Names are case sensitive. For example,
INCL_PM andincl_pm are considered
different names.
Note:
For Windows, you do not need to specify
the -D option since the default is to
include all the definitions.(Windows)
Table 16-0. (cont.)
Option Description
-In The value n is the number of spaces to
indent successive levels of a COBOL
record. (The default value is one space.)
For example, -I4 gives a four-space
indent:
03 level-1.
05 level-2.
07 level-3.
05 level-2-2.
-Lnn The value nn sets the starting level for
data definitions written by H2cpy. For
example, -L07 starts all elementary data
definitions and records at level 07. (The
default value is 03.)
All subsequent levels are numbered two
greater than the previous level. For
example:
07 char pic x comp-x.
07 points.
09 points-x pic s9(4) comp-5.
09 points-y pic s9(4) comp-5.
-M Creates multiple COBOL files. See the
section The Multiple-Files (-M) Option for
more information. The default is to write
all definitions and constants to a single
file.
-Pnn The value nn sets the column at which to
position the PIC and VALUE clauses. For
example, -P40 places them at column 40.
If the item's name extends beyond column
(nn - 2), the clause is placed at the next
acceptable column. Column 49 is the
default.
-Q All record fields have qualified
references.
The default is to prefix each field in a
structure by the name of the structure.
This gives the field a unique name. If -Q
is specified, the field name is not
prefixed. For example, consider the
following C definition:
typedef struct {
SHORT x;
SHORT y;
}POINTS;
For the preceding example, the default
output from H2cpy would be:
03 points.
05 points-x pic s9(4) comp-5.
05 points-y pic s9(4) comp-5
If the -Q option were specified, H2cpy
would output:
03 points.
05 x pic s9(4) comp-5.
05 y pic s9(4) comp-5.
Table 16-0. (cont.)
Option Description
-Snn The value nn is the starting column for
text. For example, -S10 starts all text
at column 10. The default is for text to
start at column 12.
-Ttag The tag is a prefix for all fields in
records output by H2cpy. The tag can be
up to ten characters. For example, using
the option -T:pts:, the POINTS structure
defined earlier would be translated as:
03 :pts:.
05 :pts:-x pic s9(4) comp-5.
05 :pts:-y pic s9(4) comp-5.
This option can be combined with the -M
option to permit using the COBOL's
COPY...REPLACING feature to include
structure definitions in your programs.
See the section Translating typedef
Statements for Structures for more
information.
-Vn The value of n defines the level of
messages output by H2cpy. The default is
-V1. The following list describes the
possible values and output:
Value Output
0 Only error messages are displayed.
1 A start-up banner and the names of all
files being translated are displayed, in
addition to error messages.
2 Each line of COBOL is displayed as it is
translated, in addition to the level-1
messages.
-16 Specifies a 16-bit run-time system and
causes integer data types to be translated
to:
pic s9(sz) comp-5
where:
sz is a level 78 item defined at the top
of the resultant COPY-files. The
following conditional compilation
construct is used, thereby making the
value of sz 4.
$if 32bit defined
78 sz value 9.
$else
78 sz value 4.
$end
You can change this conditional
compilation construct if you want by
changing the value of sz.
If you do not explicitly specify either
this option or the -32 option, then by
default H2cpy translates integer data
types to pic s9(4) comp-5.
When the multiple-files option (-M) is
used in conjunction with this option, all
files, apart from the .78 file, will
contain the conditional compilation
construct at the top of the file.
Table 16-0. (cont.)
Option Description
-32 Specifies a 32-bit run-time system. This
causes integer data types to be translated
to:
pic s9(sz) comp-5
where:
sz is a level 78 item defined at the top
of the resultant COPY-files. The
following conditional compilation
construct is used, thereby making the
value of sz 9.
78 32bit value 1.
$if 32bit defined
78 sz value 9.
$else
78 sz value 4.
$end
You can change this conditional
compilation construct if you want by
changing value of sz.
If you do not explicitly specify either
this option or the -16 option, then by
default H2cpy translates integer data
types to pic s9(4) comp-5.
When the multiple-files option (-M) is
used in conjunction with this option, all
files, apart from the .78 file, will
contain the conditional compilation
construct at the top of the file.
Examples.
The following example command line translates the file pm.h. The output
is written to pm.cpy. All COBOL text is lower case.
h2cpy pm -cl
The next example command line translates the file os2.h. H2cpy creates
multiple files; the main file is conv.cpy. COBOL text output is mixed
case. Each line of COBOL is displayed as it is translated.
All OS/2 definitions will be translated.
Each field in each record is prefixed by the text :name:. The INCL_PM
and INCL_BASE identifiers are defined because they are required for
proper interpretation of the header file.
h2cpy os2.h conv.cpy -m -cm -v2 -dincl_pm -dincl_base t:name:
The final example translates the Windows header file WINDOWS.H. The
translation produces WINDOWS.78 which contains the constants used by
Windows programs and WINDOWS.CPY which contains all the simple type
definitions used by Windows programs. Additionally a separate file is
created for each structure defined in WINDOWS.H.
h2cpy windows.h windows.cpy -m
The Multiple-Files (-M) Option.
By default, H2cpy writes all COBOL definitions to outputfile. All
translations for typedef statements are written first, followed by all
translations of #define statements.
The -M option creates more than one output file. H2cpy writes all
elementary data items it has translated to outputfile. For example,
consider the following C definitions:
typedef unsigned short SHANDLE;
typedef void far *LHANDLE;
They are translated as follows:
03 shandle pic 9(4) comp-5.
03 lhandle pointer.
03 lhandle-comp5 redefines lhandle pic 9(9) comp-5.
For details on the third entry, see the section COMP-5 Redefinition for
Pointers later in this chapter.
H2cpy writes all translated constants to a second file. This file's
base-name is the base-name of outputfile, but the extension is .78. For
example, if the main output file is os2.cpy, H2cpy writes the constants
to os2.78. The constants are defined in the C files in #define
statements. These are translated into level-78 items in the output
files.
Each record structure is written to its own file. The file's base name
is the first eight characters of the typedef name. The file's extension
is always .cpy. If this naming convention causes more than one file to
have the same name, the second file is given an extension of .c01, the
third an extension of .c02, and so on.
For example, if a header file has the following structure names, which
are not unique in the first eight characters:
ORDERS_GCARC
ORDERS_GCBOX
ORDERS_GCPARC
ORDERS_GSAP
when using the -M option, these structures would be placed in the files
ORDERS_G.cpy, ORDERS_G.c01, ORDERS_G.c02, and ORDERS_G.c03.
To permit easy identification of which structure is written to which
file, a list of structures and their associated files is included at the
end of the main output file.
Using Split78
Having run H2cpy against a C header file containing just #define
statements, you can split that file into a set of separate files using
split78.
split78 is invoked from the command line as follows:
split78 inputfile
where:
inputfile is a COBOL COPY-file containing only 78-level items.
split78 creates output files with name prefix 78 where prefix is the
prefix (up to the first hyphen) used in the name of a 78-level item.
Every item with the same prefix is placed into the COPY-file with that
prefix as its name.
When you run split78, if an output file already exists, new items are
simply added to the end of it. Hence, if you run split78 twice on the
same COPY-file, each output file will contain duplicate 78-level items.
To avoid accidents, split78 will ask you to confirm that no .78files
exist in the current directory when you invoke it.
Converting C Statements
This section explains how H2cpy translates #define and typedef
statements.
Translating #define Statements.
H2cpy translates all #define statements that associate a name with a
particular value (that is, those lines that define a constant). These
are converted into COBOL level-78 items.
Consider the following #define statements:
#define SEVERITY_UNRECOVERABLE 0x0010
#define PROC_NAME 5
#define QWL_HMQ (-4)
#define WS_CLIPCHILDREN 0x20000000L
#define HWND_BOTTOM (HWND)4
#define WS_STR "string"
They are translated as follows:
78 severity-unrecoverable value h"10".
78 proc-name value 5.
78 qwl-hmq value -4.
78 ws-clipchildren value h"20000000".
78 hwnd-bottom value 4.
78 WS-STR value "string".
Notice that the #define statement for hwnd-bottom includes type
information. This is ignored when the constant is translated into COBOL.
Any arithmetic operations in a #define statement are evaluated before the
statement is translated into COBOL. For example, the following #define
statements:
#define A 1
#define B A + 1
are translated as:
78 a value 1.
78 b value 2.
H2cpy writes constants to the output file in the following order:
1. All constants with the same prefix are grouped together. (The
prefix is the part of the name preceding the first underscore.
For example, the prefix of ABB_BACK_MIX_MODE is ABB.)
2. The groups are then written in alphabetical order. Constants
within each group are written in the order that they appear in the
original C header file.
3. Constants without a prefix (that is, whose names do not contain an
underscore) are grouped together at the end of the file. If a
particular prefix is part of only one constant's name, that
constant is also placed at the end.
If you select the -M option, you can use a COPY statement to add the file
containing the constants to a program. Alternatively, you can edit the
file to select those constants you want to include in a program.
Some C files contain constants whose names are the same as COBOL reserved
words. H2cpy recognizes the more common reserved words, and it prefixes
the matching constant's name with C- in the COBOL file. The words
recognized are:
ADDRESS
ALTERNATE
CONTROL
ERROR
FALSE
FIXED
NULL
READ
RELATIVE
TRUE
WRITE
For example:
#define NULL 0
is translated TO:
78 c-null value 0.
Translating Typedef Statements for Simple Types.
COBOL does not have any type-defining mechanism equivalent to C's
typedef. Therefore, H2cpy produces templates of data definitions that
can be modified and used in COBOL programs.
For example, the following line defines the type USHORT in a C file:
typedef unsigned short USHORT;
In the resulting COBOL file, the output line is:
03 ushort pic 9(4) comp-5.
To use a data item that is defined as type USHORT, use the definition
produced by H2cpy to establish the COBOL usage. For example, to define a
data item a of type USHORT, use the definition of ushort produced by
H2cpy. The resulting line of code is:
03 a pic 9(4) comp-5.
Translating Typedef Statements for Structures.
Structure definitions in C header files are translated into COBOL record
structures. By default, the structure name prefixes each field. If only
one data item of a structure type is used in a program, the COBOL record
can be used as produced by H2cpy.
For example, suppose the C file contains the following definition for the
structure FILEFINDBUF:
typedef struct FILEFINDBUF {
FDATE fdateCreation;
FTIME ftimeCreation;
FDATE fdateLastAccess;
FTIME ftimeLastAccess;
FDATE fdateLastWrite;
FTIME ftimeLastWrite;
ULONG cbFile;
ULONG cbFileAlloc;
USHORT attrFile;
UCHAR cchName;
CHAR achName[13];
} FILEFINDBUF;
H2cpy translates the FILEFINDBUF structure (assuming an indent value of
three) as:
03 filefindbuf.
05 filefindbuf-fdatecreation pic 9(4) comp-5. *>Bit field
05 filefindbuf-ftimecreation pic 9(4) comp-5. *>Bit field
05 filefindbuf-fdatelastaccess pic 9(4) comp-5. *>Bit field
05 filefindbuf-ftimelastaccess pic 9(4) comp-5. *>Bit field
05 filefindbuf-fdatelastwrite pic 9(4) comp-5. *>Bit field
05 filefindbuf-ftimelastwrite pic 9(4) comp-5. *>Bit field
05 filefindbuf-cbfile pic 9(9) comp-5.
05 filefindbuf-cbfilealloc pic 9(9) comp-5.
05 filefindbuf-attrfile pic 9(4) comp-5.
05 filefindbuf-cchname pic X comp-X.
05 filler occurs 13.
07 filefindbuf-achname pic X comp-X.
If a program requires only one data item of this type, you can use the
definition of filefindbuf exactly as it was translated. If more than one
data item of a particular structure type is required, you must do one of
the following:
* Rename the group item and use COBOL qualification to access the
elementary items it contains.
* Rename the group item and all of the elementary items it contains
to give unique names.
* Use the -T option when H2cpy is run to produce a tag prefix. If
-T is combined with the -M option, a file is created that can be
used with COBOL's COPY...REPLACING mechanism.
For the FILEFINDBUF structure, running H2cpy with the options -M -T:tag:
produces the file FILEFIND.CPY, containing the following:
03 :tag:.
05 :tag:-fdatecreation pic 9(4) comp-5. *>Bit field
05 :tag:-ftimecreation pic 9(4) comp-5. *>Bit field
05 :tag:-fdatelastaccess pic 9(4) comp-5. *>Bit field
05 :tag:-ftimelastaccess pic 9(4) comp-5. *>Bit field
05 :tag:-fdatelastwrite pic 9(4) comp-5. *>Bit field
05 :tag:-ftimelastwrite pic 9(4) comp-5. *>Bit field
05 :tag:-cbfile pic 9(9) comp-5.
05 :tag:-cbfilealloc pic 9(9) comp-5.
05 :tag:-attrfile pic 9(4) comp-5.
05 :tag:-cchname pic x comp-X.
05 filler occurs 13.
07 :tag:-achname pic x comp-X.
To declare two data items a and b that have the data item names as
prefixes for the fields, use the following lines:
copy "filefind.cpy" replacing ==:tag:== by ==a==.
copy "filefind.cpy" replacing ==:tag:== by ==b==.
Using these lines produces the following COBOL data definitions:
03 a.
05 a-fdatecreation pic 9(4) comp-5. *>Bit field
05 a-ftimecreation pic 9(4) comp-5. *>Bit field
05 a-fdatelastaccess pic 9(4) comp-5. *>Bit field
05 a-ftimelastaccess pic 9(4) comp-5. *>Bit field
05 a-fdatelastwrite pic 9(4) comp-5. *>Bit field
05 a-ftimelastwrite pic 9(4) comp-5. *>Bit field
05 a-cbfile pic 9(9) comp-5.
05 a-cbfilealloc pic 9(9) comp-5.
05 a-attrfile pic 9(4) comp-5.
05 a-cchname pic X comp-X.
05 filler occurs 13.
07 a-achname pic X comp-X.
03 b.
05 b-fdatecreation pic 9(4) comp-5. *>Bit field
05 b-ftimecreation pic 9(4) comp-5. *>Bit field
05 b-fdatelastaccess pic 9(4) comp-5. *>Bit field
05 b-ftimelastaccess pic 9(4) comp-5. *>Bit field
05 b-fdatelastwrite pic 9(4) comp-5. *>Bit field
05 b-ftimelastwrite pic 9(4) comp-5. *>Bit field
05 b-cbfile pic 9(9) comp-5.
05 b-cbfilealloc pic 9(9) comp-5.
05 b-attrfile pic 9(4) comp-5.
05 b-cchname pic X comp-X.
05 filler occurs 13.
07 b-achname pic X comp-X.
If prefixing a field name with the name of the structure results in a
total name length greater than 30 characters, H2cpy truncates the prefix
to reduce the name length to 30 characters. For example, consider the
following C structures:
typedef struct FOCAMETRICS {
ULONG ulIdentity;
ULONG ulSize;
CHAR szFamilyname[32];
CHAR szFacename[32];
SHORT usRegistryId;
SHORT usCodePage;
SHORT yEmHeight;
} FOCAMETRICS;
typedef struct FONTDEFINITIONHEADER {
ULONG ulIdentity;
ULONG ulSize;
SHORT fsFontdef;
SHORT fsChardef;
} FONTDEFINITIONHEADER;
typedef struct FONTSIGNATURE {
ULONG ulIdentity;
ULONG ulSize;
CHAR achSignature[12];
} FONTSIGNATURE;
typedef struct FOCAFONT {
FONTSIGNATURE fsSignature;
FOCAMETRICS fmMetrics;
FONTDEFINITIONHEADER fdDefinitions;
} FOCAFONT;
The resulting translation of FOCAFONT (assuming an indent of three and a
PIC column value of 42) is:
03 focafont.
05 focafont-fssignature.
07 focafont-fssignatur-ulidentity pic 9(9) comp-5.
07 focafont-fssignature-ulsize pic 9(9) comp-5.
07 filler occurs 12.
09 focafont-fssignat-achsignature pic X comp-X.
05 focafont-fmmetrics.
07 focafont-fmmetrics-ulidentity pic 9(9) comp-5.
07 focafont-fmmetrics-ulsize pic 9(9) comp-5.
07 filler occurs 32.
09 focafont-fmmetric-szfamilyname pic X comp-X.
07 filler occurs 32.
09 focafont-fmmetrics-szfacename pic X comp-X.
07 focafont-fmmetric-usregistryid pic S9(4) comp-5.
07 focafont-fmmetrics-uscodepage pic S9(4) comp-5.
07 focafont-fmmetrics-yemheight pic S9(4) comp-5.
05 focafont-fddefinitions.
07 focafont-fddefiniti-ulidentity pic 9(9) comp-5.
07 focafont-fddefinitions-ulsize pic 9(9) comp-5.
07 focafont-fddefinitio-fsfontdef pic S9(4) comp-5.
07 focafont-fddefinitio-fschardef pic S9(4) comp-5.
Notice how some fields in this structure, such as:
focafont-fssignatur-ulidentity
have shortened prefixes to keep the length to 30 characters.
COMP-5 Redefinition for Pointers.
H2cpy adds a redefinition for all variables that are defined as pointers.
The redefinitions are defined as COMP-5, and their names are the original
names suffixed with COMP5. For example, if the .h file contains:
typedef far void *LHANDLE
H2cpy produces the following redefinition:
03 lhandle pointer.
03 lhandle-comp5 redefines lhandle pic 9(9) comp-5.
Other C Constructs Recognized
In addition to #define and typedef, H2cpy recognizes the following
C-language directives.
Directive H2cpy Behavior
-------------------------------------------------------
#ifdef These five directives control conditional
#ifndef #if compilation. H2cpy acts on them to ensure
#else #endif that only the definitions actually
required are translated. The -D option
can be used to define names that these
directives recognize.
#include H2cpy opens the files specified in
#include statements and immediately
translates their contents into equivalent
COBOL statements.
H2cpy searches only the current directory
for file-names specified in quotes.
File-names specified in angle brackets are
first searched for in the current
directory, then in the directories
specified in the INCLUDE environment
variable.
H2cpy Limitations
H2cpy cannot translate some elements of C header files into COBOL because
there is no direct correspondence between the languages:
* Underscore characters (_) in C identifiers are converted to
hyphens (-) in COBOL names. If a C identifier begins with a
hyphen, the hyphen is discarded, because COBOL identifiers cannot
begin with a hyphen.
* C data items defined as type char can have arithmetic performed on
them and can be used as alphanumeric items.
H2cpy treats items defined as type char and unsigned char as PIC X
COMP-X. This allows arithmetic to be performed on such fields. To
allow alphanumeric operations to be performed on these fields, you
must redefine the fields as PIC X only. For example:
01 a PIC X COMP-X.
01 b REDEFINES a PIC X.
* Macros created in C #define statements cannot be translated into
COBOL. The following is an example of an untranslatable macro:
#define MAKEUSHORT(l, h) (((USHORT)(l)) | ((USHORT)(h)) < 8)
COBOL has no corresponding construct. H2cpy simply ignores all C
macros it encounters.
Note that this means that some definitions in the Windows 3.0
header files cannot be converted. A set of converted files from
Windows 3.0 is included with this system as part of the
demonstration programs.(Windows)
* Fields defined as bit fields cannot be directly translated into
COBOL. H2cpy determines the number of bits in the structure and
translates it into a COMP-5 field of the appropriate size. The
comment Bit field is added to the line to indicate the original C
definition was a bit field.
Consider the following C definition:
typedef struct _FTIME {
unsigned twosecs: 5;
unsigned minutes: 6;
unsigned hours: 5;
} FTIME;
Because an item declared as type _FTIME occupies 16 bits (5+6+5),
_FTIME is translated as:
03 ftime PIC 9(4) COMP-5. *&>Bit field
The limitations above mean that the H2cpy feature cannot convert
header files for all versions of Windows in all environments. See
your Release Notes for details. (Windows)