EntireX IDL to C mapping

The following metasymbols and informal terms are used for the IDL.

• The metasymbols [ and ] enclose optional lexical entities.
• The informal term number (or in some cases number1.number2) is a sequence of numeric characters, for example 123.

Notes: 

1. It is possible to map the data type to the C data type unsigned char[..] without null termination (mainframe Natural, COBOL, PL/I style) or C style string (C data type char[.. + 1] with null termination). The mapping is controlled with the Mapping options when you generate source files from IDL. See Generate C source files from EntireX IDL files .
2. It is possible to map the data type to the C data type wchar_t[..] without null termination (mainframe Natural, COBOL, PL/I style) or to a C style wide character string ( C data type wchar_t[.. + 1] with null termination). The mapping is controlled with the Mapping options when you generate source files from IDL. See Generate C source files from EntireX IDL files .
3. The field length is given in bytes.
4. The data type ERX_HVDATA is an RPC-specific data type in the header file erxVData.h for handling variable-length data types. See API Function Descriptions for Variable-length Data Types AV, BV, KV and UV.
5. Date and Time values are mapped in mainframe-style packed format.
6. The binary value zero is treated as FALSE. Contents other than a binary zero are treated as TRUE.
7. Unpacked format is an internal representation of numbers with a specified number of digits used in mainframe environments (Natural, COBOL, PL/I).
8. Packed format is an internal representation of numbers with a specified number of digits used in mainframe environments (Natural, COBOL, PL/I). ERX_GET_PACKED_LENGTH is a macro within the header file erx.h used to evaluate the length of a field in bytes with packed contents.
9. It is possible to map the data type to double or unpacked. The mapping is controlled with the Mapping options when you generate source files from IDL. See Generate C source files from EntireX IDL files.
   • For unpacked, the total number of digits (number1+number2) is 99.
   • For double, it depends on your target environment how many significant digits are supported. In most environments 15 - 16 digits, which means for exact results the total number of digits (number1+number2) should be less than 16.
   If you connect two endpoints, the total number of digits used must be lower or equal than the maxima of both endpoints. For the supported total number of digits for endpoints, see the notes under data types N, NU, P and PU in Mapping IDL Data Types to target language environment C | COBOL | .NET | Java | Natural | PL/I | XML.
10. It is possible to map the data type to double or packed. The mapping is controlled with the Mapping options when you generate source files from IDL. See Generate C source files from EntireX IDL files.
    • For unpacked the total number of digits (number1+number2) is 99.
    • For double, it depends on your target environment how many significant digits are supported. In most environments 15 - 16 digits, which means for exact results the total number of digits (number1+number2) should be less than 16.
    If you connect two endpoints, the total number of digits used must be lower or equal than the maxima of both endpoints. For the supported total number of digits for endpoints, see the notes under data types N, NU, P and PU in Mapping IDL Data Types to target language environment C | COBOL | .NET | Java | Natural | PL/I | XML.
11. For float and double, rounding errors can occur, so that the values of senders and receivers might differ.
12. Count of days AD (anno domini, after the birth of Christ). The valid range is from 1.1.0001 up to 28.11.2737. Mapping of the number to the date in the complete range from 1.1.0001 on, follows the Julian and Gregorian calendar, taking into consideration the following rules:

    1

    Years that are evenly divisible by 4 are leap years.

    2

    Years that are evenly divisible by 100 are not leap years unless rule 3, below, is true.

    3

    Years that are evenly divisible by 400 are leap years.

    4

    Before the year 1582 AD, rule 1 from the Julian calendar is used. After the year 1582 AD, rules 1, 2 and 3 of the Gregorian calendar are used.

    See the following table for the relation of the packed number to a real date:

    Table 2. Relation of the packed number to a real date

    Date / Range of Dates	Value / Range of Values
    1.1.0000	0 (special value - no date)
    undefined dates	1 - 364 (do not use)
    1.1.0001	365
    1.1.1970	719527 (start of C-time functions)
    28.11.2737	999999 (maximum date)

13. Count of tenth of seconds AD (anno domini, after the birth of Christ). The valid range is from 1.1.0001 00:00:00.0 up to 16.11.3168 9:46:39 plus 0.9 seconds.
    See the following table for the relation of the packed number to a real time:

    Table 3. Relation of the packed number to a real time

    Time / Range of Times	Value / Range of Values
    1.1.0000 00:00:00.0	0 (special value - no time)
    undefined times	1 - 315359999
    1.1.0001 00:00:00.0	315360000
    1.1.1970 00:00:00.0	621671328000 (start of C-time functions)

14. The relation between the packed number of a Date and Time data type is as follows:

    tenths of a second per day	=24*60*60*10 = 864000
    number of time	= number of date	* 864000
    315360000	= 365	* 864000	1.1.0001 00:00:00.0
    621671328000	= 719527	* 864000	1.1.1970 00:00:00.0
    number of date	= number of time	/ 864000	 
    365	= 315360000	/ 864000	1.1.0001
    719527	= 621671328000	/ 864000	1.1.1970

15. The no date value is the internal state of a #DATE (Natural type D) variable after a RESET #DATE is executed within Natural programs. This internal state is not a valid date. The no date value can be transferred as the invalid date 1.1.0 from RPC clients to servers and vice versa. C Wrapper supports Natural no date value. C Wrapper passes 0 to the C application when no date is received. With the same value of 0, the C application can send no date to its partner (client or server).
16. The no time value is the internal state of a #TIME (Natural type T) variable after a RESET #TIME is executed within Natural programs. This internal state is not a valid time. The no time value can be transferred as the invalid time 1.1.0 0:00:00.0 from RPC clients to servers and vice versa. C Wrapper supports Natural no time value. C Wrapper passes 0 to the C application when no time is received. With the same value of 0, the C application can send no time to its partner (client or server).
17. The Unicode encoding provided (on receive) or expected (on send) on the API depends on the width of the wchar_t data type in your environment:

    Table 4. Unicode encoding

    Size of wchar_t	UTF Version Used
    2 bytes (Windows)	UTF-16
    4 bytes (Linux)	UTF-32

    The endianness (big endian or little endian) of the Unicode encoding that is used (UTF-16-LE, UTF-16-BE, UTF32-LE or UTF32-BE) is the same as the hardware architecture of the machine.
18. In environments where sizeof(wchar_t) is 4 bytes, only Unicode characters from the Basic Multilingual Plane are supported (code points U+0000 to U+FFFF except U+D800 to U+DFFF reserved for leading and trailing surrogates). Unicode characters from Supplementary Planes (code points U+10000 to U+10FFFF) are not supported.
19. In environments where sizeof(wchar_t) is 4 bytes, the number of UTF-16 Unicode code points (after character conversion from UTF-32 to UTF-16) must be less than or equal to number. Note the following:
    • Unicode characters from the Basic Multilingual Plane (code points U+0000 to U+FFFF except U+D800 to U+DFFF, reserved for leading and trailing surrogates) require one code point in UTF-16
    • Unicode characters from Supplementary Planes (code points U+10000 to U+10FFFF) require two code points in UTF-16

The IDL syntax allows you to define parameters as IN parameters, OUT parameters, or IN OUT parameters (which is the default if nothing is specified). This direction specification is reflected in the generated C interface object as follows:

• Parameters with the IN attribute are sent from the RPC client to the RPC server. When the parameter is a simple parameter (that is, no fixed or unbounded array, no group and no structure) the parameter is provided with the method call by value. Complex parameters such as fixed and unbounded arrays, groups and structures are provided with the call by reference method.
• Parameters with the OUT attribute are sent from the RPC server to the RPC client. They are always provided with the call by reference method.
• Parameters with the IN and OUT attribute are sent from the RPC client to the RPC server and then back to the RPC client. They are always provided with the call by reference method.

The function float sin(float x) will be called as a function - and not as a procedure - when defined in the IDL file as follows:

Library ... is
  Program 'sin' is
    Define Data Parameter
      1 x (F4) In
      1 Function_Result (F4) Out
    End-Define

it can be invoked as:

y = sin(x);

When you generate source files from IDL (see Generate C source files from EntireX IDL files ), a C function instead of a C procedure is generated if the following is true for the interface description in the IDL file:

• The last parameter's name is function_result. The name function_result is case-insensitive.
• The last parameter's direction is Out. See attribute-list.
• The last parameter is a scalar variable, that is, not an array.
• The last parameter is of type and length:

  Table 5. interface description in the IDL file

  EntireX IDL	Description	Note
  I1	Integer (small)	2
  I2	Integer (medium)	2
  I4	Integer (large)	2
  A1	Alphanumeric with length 1	2
  B1	Binary with length 1	2
  L	Logical	2
  Nnumber [.number]	Unpacked decimal	1, 2
  Pnumber [.number]	Packed decimal	1, 2
  NUnumber [.number]	Unpacked decimal unsigned	1, 2
  PUnumber [.number]	Packed decimal unsigned	1, 2

  Notes: 

  1. The data types must be mapped to double. See Mapping options when you generate C source files from EntireX IDL files.
  2. The type of the function returned is defined by Mapping IDL data types to C data types .