Version 9.5 SP1
 —  EntireX Natural Wrapper  —

Software AG IDL to Natural Mapping

This document describes the specific mapping of Software AG IDL data types, groups, arrays and structures to the Natural programming language. Please note also the remarks and hints on the IDL data types valid for all language bindings found in the IDL file. See Software AG IDL File.

This document covers the following topics:


Mapping IDL Data Types to Natural Data Formats

In the table below, the following metasymbols and informal terms are used for the IDL.

Software AG IDL Description Natural Data Format Notes
Anumber Alphanumeric Anumber  
AV Alphanumeric variable length A DYNAMIC  
AVnumber Alphanumeric variable length with maximum length A DYNAMIC  
Bnumber Binary Bnumber  
BV Binary variable length B DYNAMIC  
BVnumber Binary variable length with maximum length B DYNAMIC  
D Date D 3,5
F4 Floating point (small) F4 2
F8 Floating point (large) F8 2
I1 Integer (small) I1  
I2 Integer (medium) I2  
I4 Integer (large) I4  
Knumber Kanji Anumber 1
KV Kanji variable length A DYNAMIC 1
KVnumber Kanji variable length with maximum length A DYNAMIC 1
L Logical L  
Nnumber[.number] Unpacked decimal Nnumber[.number]  
NUnumber[.number] Unpacked decimal unsigned Nnumber[.number]  
Pnumber[.number] Packed decimal Pnumber[.number]  
PUnumber[.number] Packed decimal unsigned Pnumber[.number]  
T Time T 4,5
Unumber Unicode Unumber  
UV Unicode variable length U DYNAMIC  
UVnumber Unicode variable length with maximum length U DYNAMIC  

See also the hints and restrictions valid for all language bindings under IDL Data Types.

Notes

1. Data type K is an RPC-specific data format that is not part of the Natural language.
2. When floating-point data types are used, rounding errors can occur, so that the values of senders and receivers might differ slightly. This is especially true if client and server use different representations for floating point data (IEEE, HFP).
3. 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:

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)
4. Count of tenths 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:
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)
5. 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

Top of page

Mapping Library Name and Alias

Client Side

If you are using client interface objects (recommended) generated for the client side (see Using the Natural Wrapper for the Client Side), the IDL library name as specified in the IDL file (there is no 8 character limitation) is sent from a Natural client to the server. Special characters are not replaced. The IDL library alias is neither sent to the server nor used for other purposes on the Natural client side.

If you are using instead so-called stubs generated with SYSRPC (not recommended) or stubless Natural RPC (also not recommended), the IDL library name as specified in the IDL file is not supported by Natural. By default, a Natural client sends the library name SYSTEM to the server. To send a library name other than SYSTEM from a Natural client to a server, the following steps are required for the client:

Server Side

A Natural RPC Server considers the library name (up to 8 characters) received from a RPC client only if the Natural Logon option is set by the sending RPC client.

EntireX RPC client components provide a possibility to set the Natural Logon option. See Natural Logon or Changing the Library Name and the documentation of the EntireX RPC client component.

Top of page

Mapping Program Name and Alias

Client Side

If you are using client interface objects (recommended) generated with the Natural Wrapper for the client side (see Using the Natural Wrapper for the Client Side), the IDL program name as specified in the IDL file (there is no 8-character limitation) is sent from a Natural client to the server. Special characters are not replaced. The IDL program alias is not sent to the server, but it is used to derive the suggestion for the source file names of the client interface objects (NSN, PDA, PGM) instead using the IDL program names. See Step 2: Customize Natural Client Names.

If you are using instead so-called stubs generated with SYSRPC (not recommended) or stubless Natural RPC (also not recommended) the IDL program name as specified in the IDL must match the name in your CALLNAT statement. In this case the IDL program is limited to 8 characters. Example:

CALLNAT 'MYSRV' P1 P2 P3

Server Side

If you are using a so-called client-side server mapping file (see CVM File) the target RPC server (Natural subprogram, extension .NSN) is located with the help of this file. This has the following advantages:

The CVM file is generated either during wrapping (see Using the Natural Wrapper for the Server Side) or during extraction (see IDL Extractor for Natural). It is wrapped into the RPC client components and the relevant information is sent from a client to the server. Therefore it is important to generate or extract the target Natural RPC (Natural subprogram, extension .NSN) server first, before creating any RPC client component.

If you are not using a CVM file, the target RPC server (Natural subprogram, extension .NSN) must match the IDL program name. In this case the length of the IDL program name is limited to 8 characters.

Top of page

Mapping Parameter Names

The parameter names as given in the IDL file are replaced by artificial names in the generated Natural interface object (stub subprogram). See parameter-data-definition under Software AG IDL Grammar.

Top of page

Mapping Fixed and Unbounded Arrays

Top of page

Mapping Groups and Periodic Groups

Groups within the IDL file are mapped to Natural groups. See the group-parameter-definition under Software AG IDL Grammar for the syntax on how to describe groups within the IDL file.

Top of page

Mapping Structures

Structures within the IDL file are mapped to Natural groups. See structure-definition under Software AG IDL Grammar for the syntax on how to describe structures within the IDL file.

Top of page

Mapping the Direction Attributes IN, OUT and INOUT

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 by Natural as follows:

See the attribute-list under Software AG IDL Grammar for the syntax on how to describe attributes within the IDL file and refer to direction attribute.

Note:
If you define an interface object layout in the Natural application SYSRPC, the meaning of the direction attributes IN and OUT are reversed compared to the IDL:

Top of page

Mapping the ALIGNED Attribute

The ALIGNED attribute is not relevant for the programming language Natural. However, a Natural client can send the ALIGNED attribute to an RPC server where it might be needed. To do this you need a Natural interface object (stub subprogram) that has been generated from an IDL file.

See the attribute-list under Software AG IDL Grammar for the syntax of attributes in the IDL file and refer to the aligned attribute.

Top of page

Calling Servers as Procedures or Functions

The IDL syntax allows definitions of procedures only. It does not have the concept of a function. A function is a procedure which, in addition to the parameters, returns a value. Procedures and functions are transparent between clients and server. This means a client using a function can call a server implemented as a procedure, and vice versa.

Client and Server Side

The Natural RPC does not support functions.

Top of page