Conference turris::languages

    There are two separate issues here:
    
    1) Portability to different platforms.
    
    	Here you're trying to make sure that a C application can be ported
    	to your API on a different platform simply by re-compiling the
    	application.  For this:
    
    	a) In general, don't use 'int' for sizes, use either size_t or some
    	   'known-size' type of your own (e.g. unsigned32 to mean a unsigned
    	   object of at least 32 bits).
    
    	b) Make sure you only use ANSI-C types in you API definition.
    
    	c) Only use ANSI-specified header files.
    
    2) Re-use of the C interface by other language bindings
    
    	Here you're trying to ensure that you're not using any C-isms that
    	might be difficult for other language processors to use, or cause
    	ugly code in other languages.
    
    	a) Encourage your structure fields to be naturally aligned, while
    	   minimizing the total structure size.  The simplest way to do this
    	   is to list the fields within the struct defn in descending order of
    	   size (or of probable size - you can't be sure of sizes on anything
    	   but your development platform).  This doesn't guarantee
    	   inter-language compatibility, but it makes it more likely.  If
    	   you can, avoid structures.  Don't nest structures.
    
    	b) Don't use null-terminated strings.  Your varying-string
    	   mechanism is one way to achieve this, using dynamic strings is
    	   another, where string_struct would be {int length; char * data},
    	   and strings returned from the API would be malloced within the
    	   API.  If you do this, your API also has to provide a routine to
    	   deallocate strings.  To be friendly to C applications, you can
    	   always add a trailing NULL to your strings, but don't count 
    	   the NULL in your length field.
    
    	c) Use a similar mechanism to pass any contiguous data, but with
    	   void * instead of char *.  If you have non-character contiguous
    	   data, you might want to use void * for everything, so you don't
    	   need two almost identical structure definitions.
    
    	d) Don't use mixed-case for any names, or at least don't
    	   distinguish two things by case alone.
    
    	e) Don't use signals across the API.
    
    There's a DEC internal manual called "Guide to Designing Portable
    Programming Interfaces" that's worth reading.
    
    John

>    <<< Note 350.1 by TUXEDO::WRAY "John Wray, Secure Systems Engineering" >>>
> 
>     2) Re-use of the C interface by other language bindings
>     
>     	Here you're trying to ensure that you're not using any C-isms that
>     	might be difficult for other language processors to use, or cause
>     	ugly code in other languages.

If you want to be callable under the current Ada standard, do not pass
procedure descriptors as parameters to other procedures.

    
    The book referred to a couple back is one of these (I think the first)
    in BOOKIE::NAS$DOC: Ignore the NAS in the title, they just seem to be
    good allround documents on writing portable software, APIs and
    accompanying documentation etc.
    
    NAS-GUIDE-TO-DESIGNING-INTERFACES.PS;1  NAS-GUIDE-TO-DEVELOPING-SW.PS;1
    NAS-GUIDE-TO-USING-INTERFACES.PS;1     
    NAS-MULTIPLATFORM-DOC-GUIDE.PS;1
    NAS-OPEN-SYSTEMS-HANDBOOK.PS;1          NAS-OVERVIEW.PS;3
    
    Richard

  >                       <<< Note 350.2 by EVMS::KILGALLEN >>>
  >                           -< And to be Ada-friendly >-
  >
  > If you want to be callable under the current Ada standard, do not pass
  > procedure descriptors as parameters to other procedures.

   If you really want to be Ada-friendly (the language that was created
   for portability, among other things), supply a proper "Ada binding" to
   the API. The Ada binding typically consists of Ada source code with
   proper Ada declarations of the appropriate types and the Ada "specs"
   of the subprograms. Any "respectable" API has its Ada binding. The
   binding actually "hides" from its the user all the parameter passing
   mechanism stuff and sort of converts it to "Ada mechanism".

  -- Nitsan

Hello,

I am having problems accessing the BOOKIE::NAS$DOC
directory. The message is:

%DIRECT-E-OPENIN, error opening BOOKIE::NAS$DOC:*.*;* as input
-RMS-F-DEV, error in device name or inappropriate device type for operation

Does somebody have some infos on the location of the files.

Thank's a lot,

Jean-Michel

    
    BOOKIE has shut down. I think you'll find the stuff in PROSE::NAS$DOC:
    
    Richard