Path: utzoo!utgpu!jarvis.csri.toronto.edu!rutgers!mit-eddie!apollo!oj
From: oj@apollo.COM (Ellis Oliver Jones)
Newsgroups: comp.sys.apollo
Subject: Re: GPR Colour Maps
Summary: why .h files are better than .ins.c files
Message-ID: <4447a4f4.208ba@apollo.COM>
Date: 7 Jul 89 16:07:00 GMT
References: <8907051320.AA03260@umix.cc.umich.edu> <4442004a.d5b2@apollo.COM>
Reply-To: oj@apollo.com (Ollie Jones)
Organization: Apollo Computer, Chelmsford, MA
Lines: 72

Herr Koenigsson followed up with me privately asking why
it was better to use .h files than .ins.c files.  Here's
my answer:

You should try to use .h files whenever possible, not just for
GPR, but for all Domain/OS Aegis-style system services.
                                                           
First of all, these *.h files are only available at SR10 or later.
So, if you are using an SR9.7 or earlier system release, pay no
attention to this posting.

Let's compare a call, for example gpr_$set_color_map,
as it is described in /sys/ins/gpr.ins.c and /usr/apollo/include/gpr.h
In gpr.ins.c, the call is described with the single line
    std_$call void   gpr_$set_color_map ();

In gpr.h, it is described as follows:
  extern void gpr_$set_color_map (
      gpr_$pixel_value_t   & start_index,   /* index of first entry */
      short int            & n_entries,     /* # of entries */
      gpr_$color_vector_t    v,             /* entry values */
      status_$t            * status);       /* returned status */

Notice that there's no description of the data types of parameters to
the call in gpr.ins.c.  It is left completely up to the
programmer to get the data types right when making the call.
The "std_$call" declaration instructs the compiler to
structure the call frame as necessary for calling a Pascal routine.
(GPR, and lots of other Domain/OS system software, is written 
mostly in Pascal.)

In gpr.h, on the other hand, each parameter to the call is described
explicitly, because we use ANSI C-style function prototypes.  
For example, let's look at the first paramter.

      gpr_$pixel_value_t   & start_index,   /* index of first entry */

The "gpr_$pixel_value_t" declares the data type of the item.
The "&" (which is NOT part of ANSI C) declares that the item
is passed by reference (that is, the item's address, not its value,
is placed in the call frame).  "&" has the same effect as declaring
a parameter "IN" in Pascal.  Some of the items have a "*" rather than
a "&". These parameters are explicitly declared to be pointers to
data types (the equivalent of "IN OUT" in Pascal).
The "start_index" is the name of the parameter.

The presence of this function prototype in the gpr.h
file allows the compiler to typecheck the parameters you
pass to procedures.  This saves much trouble.

Furthermore, the PRISM (DN10000) C compiler is capable
of passing parameters of type float and double in floating-point
registers, but only if it can tell (by the presence of
the function prototype) that the parameters are indeed
floating-point numbers.  This is good for performance.

You do have to do some code-conversion to switch over to
.h files. Primarily, you have to make sure that you're 
explicitly passing pointers for all the "*" parameters.
The old std_$call convention didn't require this.
We typically don't convert old (working) code, but
we do use .h files for all new C-language development.

A side point:  If you don't install Aegis when installing SR10,
you don't get the .ins.c (or .ins.ftn or .ins.pas files).  You
do get the .h files, however.  You also get the libraries,
just not the header files.   (Please save your napalm and
don't flame us for this, we already know it's a big 
inconvenience.)

Regards,
/Ollie Jones (speaking for myself, not necessarily for HP)