Section 16.1 - General Information on Interfacing to Other Languages

1. Pragma import "imports" a subprogram from another ("foreign") language into an Ada program. Use pragma import if you want to call, for example, an existing C function.
2. Pragma export "exports" an Ada subprogram to a "foreign" language. For example, if you've written an Ada procedure and want to call it from C, use pragma export.
3. Pragma Convention specifies that a specified type should use the storage conventions of a given "foreign" language. It is also used on subprograms if they are "callback" subprograms (described below).

Here's an example of each:

  pragma Import(C, getenv);  -- Use the C program getenv in my Ada program.
  pragma Export(COBOL, Read_Sensor); -- Provide Ada procedure "Read_Sensor"
                                     -- to the COBOL compiler.
  pragma Convention(Fortran, State_Vector) -- Read and write State_Vector
                                     -- using Fortran storage conventions
                                     -- (e.g. column-major format)

Here is the BNF for these pragmas:

  import_pragma ::= "pragma Import("
                        [ "Convention =>" ] language ","
                        [ "Entity =>" ] unit
                        [ "," [ "Link_Name =>" ] link_name ]  ");"

  export_pragma ::= "pragma Export("
                        [ "Convention =>" ] language ","
                        [ "Entity =>" ] unit 
                        [ "," [ "Link_Name =>" ] link_name ]  ");"

  convention_pragma ::= "pragma Convention("
                        [ "Convention =>" ] language ","
                        [ "Entity =>" ] unit ");"

Ada compilers always support the Convention (language) Ada, naturally enough. Your Ada compiler probably also supports the languages C, Fortran, and possibly COBOL. GNAT supports C++ as the language name CPP, and you can also interface Ada and C++ programs by having both use the C convention to send information to each other. For assembly language modules, use the name of the high level language that the module's interface mimics.

The "Link_Name" parameter often isn't necessary, but it's useful in some circumstances, for example, if you need access to an object whose name has been "mangled" in a way the Ada compiler doesn't know about or if the name is not a legal Ada identifier (such as names with leading underscores).

"Callback" subprograms are subprograms which have access (pointer) values held in some external location and are then called later using that external value. If you have an Ada subprogram that will be called this way, use pragma Convention on both the subprogram and on the access type used. This is useful, for example, in dealing with the X window graphical user interface (GUI).

If the "main" subprogram is not in Ada, there is an additional issue to consider called "elaboration". The actual main subprogram should make sure that the environment for Ada is correctly set up. This is done automatically if the main subprogram is in Ada, but if it isn't, you have to do it yourself. The Ada RM section B.1(39) suggests that compilers provide subprograms called "adainit" to start up the Ada environment and "adafinal" to clean it up after the Ada subprograms have stopped running. If you need to have a non-Ada main subprogram, check your compiler manual to see if it supports this and if there are any restrictions on what is and is not permitted.

Quiz:

You're writing an Ada program and want to directly call an existing C function called display. Which of the following pragmas should you use?

1. pragma Import(C, display);
2. pragma Export(C, display);
3. pragma Convention(C, display);

Go back to the previous section	Skip to the next section	Go up to lesson 16 outline

The master copy of this file is at "http://www.adahome.com/Tutorials/Lovelace/s16s1.htm".