Passing Atoms in Canonical Form

This section deals with passing atoms in canonical form, that is, as unsigned integers.

     Prolog:  +atom
     C:       QP_atom x;
     Pascal:  x: integer
     FORTRAN: integer x
     

The argument must be instantiated to an atom, otherwise the call will signal an error. An unsigned integer representing the Prolog atom is passed to the foreign function. Atoms can be converted to strings through the functions QP_string_from_atom() or QP_padded_string_from_atom() (see fli-p2f-atm-a2s).

     Prolog:  -atom
     C:       QP_atom *x
              *x = ...
     Pascal:  var x: integer
              x := ...
     FORTRAN: integer x
              x = ...
     

A pointer to an unsigned integer is passed to the function. It is assumed that the function will overwrite this unsigned integer with its result. This result should be a canonical representation of an atom already obtained from Prolog, or one generated through the function QP_atom_from_string() or the function QP_atom_from_padded_string() (see fli-p2f-atm-a2s). Returning an arbitrary integer will have undefined results. When the foreign function returns, the atom represented by the unsigned integer being pointed to is unified with the corresponding argument of the Prolog call. The argument can be of any type; if it cannot be unified with the returned atom, the call fails. If the foreign function does not overwrite the unsigned integer, the result is undefined.

     Prolog:  [-atom]
     C:       QP_atom f(...)
                {
                  QP_atom x;
                  return x;
                }
     Pascal:  function f(...): integer;
                var x: integer;
                begin
                  f = x;
                end
     FORTRAN: integer function f(...)
                integer x
                f = x
              end
     

No argument is passed to the foreign function. The return value from the function is assumed to be an unsigned integer, which should be a canonical representation of an atom already obtained from Prolog, or one generated by one of the functions QP_atom_from_string() or QP_atom_from_padded_string() (see fli-p2f-atm-a2s). Returning an arbitrary integer will have undefined results. The atom represented by the unsigned integer is unified with the corresponding argument of the Prolog call. The argument can be of any type; if it cannot be unified with the returned atom, the call fails.