Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!zaphod.mps.ohio-state.edu!sdd.hp.com!apollo!beierl_c
From: beierl_c@apollo.HP.COM (Christopher Beierl)
Newsgroups: comp.sys.apollo
Subject: Re: function prototype mystery?
Message-ID: <510284ac.20b6d@apollo.HP.COM>
Date: 16 Apr 91 16:04 GMT
References: <1991Apr11.164655.17092@milton.u.washington.edu>
Sender: root@apollo.HP.COM
Reply-To: beierl_c@apollo.HP.COM (Christopher Beierl)
Organization: Hewlett-Packard Apollo Division - Chelmsford, MA
Lines: 68

In article <1991Apr11.164655.17092@milton.u.washington.edu> etb@milton.u.washington.edu (Eric Bushnell) writes:
>I don't understand the argument declarations used
>in the following function prototype. Could someone
>give me a clue? I tried RTFM, with no luck.
>... 
>void proc2_$get_info(
>        uid_$t          &p2_uid,
>        proc2_$info_t   *info,
>        pinteger        &info_buf_len,  /* size of info buffer (bytes) */
>        status_$t       *sts
>);
>
>What do the &'s do to the first and third arguments?
>...
>What works is something like
>  proc2_$get_info(p2_uid,&info,bufferlength,&status).
>  Why? Is this some kind of apollo-ism, or something ANSI-like?

The relevant FM is the Domain C Language Reference, section
3.15 Reference Variables -- Domain Extension.  See also Chapter 7,
Cross-Language Communication, and Appendix E, Using std_$call, in
the same FM.

Domain/C has added reference variables as an extension (borrowed from
C++) in order to facilitate cross-language communications.  The problem
being addressed is that Pascal and FORTRAN both pass arguments by
reference, while C passes its arguments by value.

Prior to the addition of function prototypes and reference variables
in Domain/C, the std_$call mechanism was the only supported method
for cross-language communication.  For instance, the declaration for
proc2_$get_info() from /sys/ins/proc2.ins.c is:

    std_$call void proc2_$get_info();

When a call is made to a routine declared with std_$call the C compiler
automatically passes the address of all arguments, rather than their
value.  This makes it possible to make cross-language calls, but at
the expense of distorting the appearance of the call in C source code.
For example, since it is declared std_$call, a call to proc2_$get_info
would look something like this:

    proc2_$get_info(p2_uid, info, info_buf_len, status);

rather than the more "natural" way it would appear if it was actually
a C routine and didn't need the std_$call:

    proc2_$get_info(p2_uid, &info, info_buf_len, &status);

The addition of reference variables and prototypes (used in the *.h files)
allows us to use a less blunt tool than std_$call and indicate on a per
argument basis whether we need to transparently pass by reference.  Thus
with the proper prototype we can access Pascal and FORTRAN routines as if
the were written in C, and can use the more natural C calling conventions
in our C application programs.  This makes life MUCH easier for the C
programmer!

I strongly recommend that you make use of the *.h files with their
function prototypes and reference variables rather than the *.ins.c
files which use std_$call.

-Chris


=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 Christopher T. Beierl  Internet: beierl_c@apollo.HP.COM;beierl_c@apollo.com
 Apollo Computer, Inc.      UUCP: {mit-eddie,yale,uw-beaver}!apollo!beierl_c
 A Subsidiary of Hewlett-Packard                       Phone: (508) 256-6600