======
Macros
======

.. index:: Macros

This part describes the C-Macros that are defined in the simple CAN-interface.
In this version of the library, there are no macros with parameters defined.
For this reason, the Macros described here, are in fact constants.

.. index::
   single: SCI_MAJOR_VERSION

SCI_MAJOR_VERSION
-----------------

::

  #define SCI_MAJOR_VERSION 3
  
This is the major version-number of the SCI-library. The version of the library
is composed of a major- and a minor-version number. Together, they form the
complete version number e.g a major-number of 3 and a minor-number of 0
represent version 3.0 of the library.
Note that the current major-version of the library you may use is not
necessarily the one shown in the above definition of `SCI_MAJOR_VERSION`.

.. index::
   single: SCI_MINOR_VERSION

SCI_MINOR_VERSION
-----------------

::

  #define SCI_MINOR_VERSION 0
  
This is the minor version-number of the SCI-library. The version of the library
is composed of a major- and a minor-version number. Together, they form the
complete version number e.g a major-number of 3 and a minor-number of 0
represent version 3.0 of the library.
Note that the current minor-version of the library you may use is not
necessarily the one shown in the above definition of `SCI_MINOR_VERSION`.

.. index::
   single: SCI_VER

SCI_VER
-------

This is the complete version number as an integer. It is calculated as::
  
  SCI_MAJOR_VERSION*100+SCI_MINOR_VERSION. 

.. index::
   single: SCI_IDENTIFIER

SCI_IDENTIFIER
--------------

::

  #define SCI_IDENTIFIER "RTEMS,VCAN"

This is a string that identifies the current implementation of the SCI-library.
Although the interface the library provides is hardware-independent, the
library itself contains hardware dependent code. In fact, the implementation
of the library depends on the used computer-hardware, the operating system and
on one or more drivers for CAN-interface cards.
The `SCI_IDENTIFIER`-string provides information about the underlying
hardware the library is adapted to.
The identifier-string contains of sections, that are separated by commas.
It has two sections, the first contains a string that describes the
operating system, 
the following section describes the used CAN-card drivers.
Note that the above definition of `SCI_IDENTIFIER` is only an example,
your implementation of the SCI-library may have a completely different
identifier-string. In the above example, the Operating
System is RTEMS and the only supported driver is the "VCAN"-driver.

.. index::
   single: SCI_NAMELENGTH

SCI_NAMELENGTH
--------------

::

  #define SCI_NAMELENGTH 20

This is a the number of significant characters that are used by the SCI-library
to distinguish different process-names used in the `sci_open()`-
function. Two names that are not different in the first `SCI_NAMELENGTH`
cannot be distinguished by the library. The above definition of
`SCI_NAMELENGTH` is only an example and your implementation of the
SCI-library may have another significant name-length.

It is guaranteed that `SCI_NAMELENGTH` is not smaller than 20.

.. index::
   single: SCI_PLUGPORT_START

SCI_PLUGPORT_START
------------------

::

  #define SCI_PLUGPORT_START 128
  

This is the number of the first port that can be used as *plug-port*.
A *plug-port* is comparable to real existing CAN ports but all data is
converted by data-conversion functions (*plug-ins*) that are defined
for that specific port. Once a *plug-in* has been defined, a new
*plug-port* is defined too. That *plug-port* can be used like any
other (real-) port. An application that uses sci with that *plug-port*
will not notice that all data-bytes are converted by the *plug-in*. Up to
`SCI_MAX_PLUGPORTS` can be defined, the first *plug-port* is
`SCI_PLUGPORT_START`. *Plug-ins* can be defined with the function
`sci_def_plug_in`.

.. index::
   single: SCI_MAX_PLUGPORTS

SCI_MAX_PLUGPORTS
-----------------

::

  #define SCI_MAX_PLUGPORTS 16
  
This is a the maximum number *plug-ports* that can be defined. See also
the description of `SCI_PLUGPORT_START`.

.. index::
   single: SCI_NUM_ERRCODES

SCI_NUM_ERRCODES
----------------

::
  
  #define SCI_NUM_ERRCODES (SCI_ERR_GENERAL+1)

This is an integer that shows the number of all error codes of data type
`sci_Errcode`.

.. index::
   single: SCI_ERRCODE(sci_ret)

SCI_ERRCODE(sci_ret)
--------------------

::

  #define SCI_ERRCODE(sci_ret) (((sci_ret) & ~SCI_ERROR) >> 16)

This macro extracts the error code from a function return code. Parameter
`sci_ret` must be of type `sci_Return`.

.. index::
   single: SCI_ERR(errcode)

SCI_ERR(errcode)
----------------

::

  #define SCI_ERR(errcode) (SCI_ERROR | ((errcode)<<16))

This macro creates a return code of type `sci_Return` from a given
error code of type `sci_Errcode`. This macro is usually only used internally by
sci.