Statements: native

The native statement inserts native code into the implementation of a Chora method.

Syntax

Form 1:

native{native‑code}

Form 2:

native(exchange‑variable,exchange‑variable, ... ){native‑code}

Discussion

The native statement allows the mixing of target specific code (e.g. written in ANSI C or JavaScript) together with the platform independent Chora code. This is particularly useful when implementing driver components to interact and exchange data with the target system. During the code generation, the native-code is copied into the corresponding target function or method. Following example demonstrates the usage of the native statement:

var bool shouldStartTheEngine = ...;

if ( shouldStartTheEngine )
  native
  {
    /* Some ANSI C extern function declaration  */
    extern void StartEngine( void );

    /* Call the C function */
    StartEngine();
  }

The Chora compiler, in turn, is not able to interpret and understand the target specific content of the native-code. During prototyping the Chora compiler ignores all native statements and reports only a warning. To avoid this Chora warning you can use the conditional compilation directives like $if to conditionally exclude the native statement:

var bool shouldStartTheEngine = ...;

if ( shouldStartTheEngine )
  $if !$prototyper
    native
    {
      /* Some ANSI C extern function declaration  */
      extern void StartEngine( void );

      /* Call the C function */
      StartEngine();
    }
  $else
    trace "START THE ENGINE";
  $endif

With the second version of the native statement you can additionally list local variables and arrays you intend to access within the native-code block. This formal designation ensures, that none of the affected members is renamed or eliminated during the compilation or code generation. Once designated, the local variables and arrays can be read and modified from the native-code by using their original names and the target specific syntax to access locally declared variables. For example:

var   int32 device_id      = ...;
array int32 setting_values[4];

$if !$prototyper
  // The variable 'device_id' and the array 'setting_values' should be accessible
  // from the native code block. The native code will assign new values to the
  // array items.
  native ( device_id, setting_values )
  {
    /* Some ANSI C extern function declaration  */
    extern int GetDeviceSetting( int aDeviceId, int aSettingId );

    /* Call the C function to get some setting values */
    setting_values[0] = GetDeviceSetting( device_id, SOME_SETTING_ID_POWER );
    setting_values[1] = GetDeviceSetting( device_id, SOME_SETTING_ID_MODE   );
    setting_values[2] = GetDeviceSetting( device_id, SOME_SETTING_ID_PORT   );
    setting_values[3] = GetDeviceSetting( device_id, SOME_SETTING_ID_STATUS );
  }
$endif

// Now, the array contains values initialized in the native code block. These can be
// evaluated now in Chora code
if ( setting_values[0] > 100 )
  trace "OVERLOAD";

[...]

if ( setting_values[3] == 0 )
  trace "STATUS OK";

Please note, the curly braces { and } enclosing the native-code are syntactical elements of the native statement itself. If the native-code also contains curly braces, it is important that each opening brace { is balanced with a corresponding closing } brace, otherwise the Chora compiler is not able to recognize the end of the native-code. To insert an unbalanced curly brace, prefix it explicitly with the backslash sign \. For example:

native
{
  printf( "Unbalanced brace \{" );
}