A Software AG IDL file contains definitions of the interface between client and server. The IDL file is used by Software AG wrappers to generate RPC clients, RPC servers and tester etc. on the basis of these definitions.
The IDL file can be edited by the IDL Editor provided by plug-ins for Eclipse.
This document contains a descriptive introduction to IDL files. The syntax of IDL files in a formal notation is given in the document The IDL Grammar. This document covers the following topics:
The IDL's syntax looks similar to a Software AG Natural parameter data definition statement.
Library 'EXAMPLE' Is
Program 'CALC' Is
Define Data Parameter
1 Operator (A1) In
1 Operand_1 (I4) In
1 Operand_2 (I4) In
1 Function_Result (I4) Out
End-Define
The syntax is described in a formal notation in the document The IDL Grammar.
The table below uses the following metasymbols and informal terms for the Software AG IDL.
The metasymbols [ and ] surround optional lexical entities.
The informal term number (or in some cases number.number) is a sequence of numeric characters, for example 123.
| Type and Length | Description | Example | See Notes |
|---|---|---|---|
| Anumber | Alphanumeric | A100 | 1, 2, 7, 17 |
| AV | Alphanumeric variable length | AV | 1, 2, 7 |
| AVnumber | Alphanumeric variable length with maximum length | AV100 | 1, 2, 7, 17 |
| Bnumber | Binary | B10 | 1, 2, 15 |
| BV | Binary variable length | BV | 1, 2, 15 |
| BVnumber | Binary variable length with maximum length | BV128 | 1, 2, 15 |
| D | Date | D | 3, 4, 13 |
| F4 | Floating point (small) | F4 | 11, 13, 16 |
| F8 | Floating point (large) | F8 | 12, 13, 16 |
| I1 | Integer (small) | I1 | 8 |
| I2 | Integer (medium) | I2 | 9 |
| I4 | Integer (large) | I4 | 10 |
| Knumber | Kanji | K20 | 1, 2, 7, 17, 18 |
| KV | Kanji variable length | KV | 1, 2, 7, 18 |
| KVnumber | Kanji variable length with maximum length | KV200 | 1, 2, 7, 17, 18 |
| L | Logical | L | 3, 14 |
| Nnumber[.number] | Unpacked decimal | N8 or N8.2 | 6, 13 |
| NUnumber[.number] | Unpacked decimal unsigned | NU2 or NU6.2 | 6, 13 |
| Pnumber[.number] | Packed decimal | P12 or P10.3 | 6, 13 |
| PUnumber[.number] | Packed decimal unsigned | PU3 or PU4.2 | 6, 13 |
| T | Time | T | 3, 5, 13 |
| Unumber | Unicode | U100 | 2, 19 |
| UV | Unicode variable length | UV | 2, 19 |
| UVnumber | Unicode variable length with maximum length | UV200 | 2, 19 |
Note that equivalents of the data types are not necessarily supported in every target programming language environment. Also value ranges of the mapped data type can differ. See Mapping Software AG IDL Data Types to the target language environment: C, COBOL, PL/I, DCOM, Java, .NET.
There is, however, an absolute limit (1 GB) which cannot be exceeded.
The maximum length you can specify depends on your hardware and software configuration (apart from this product).
The length is implicit and must not be specified.
The supported range is from 1.1.0001 up to 31.12.9999. Dates BC (before the birth of Christ) are not supported.
It is also possible to transfer 1.1.0000 as a value. This is a special value (because there is no year 0) and denotes "no date" is given. The no date value is the internal state of a #DATE variable (Natural type D) after a RESET #DATE is executed within Natural programs. The target language environment determines how 'no date' is handled.
See the notes under data type D in the section Mapping Software AG IDL Data Types to the target language environmentC, Java or .NET.
The data type T has two different meanings:
A time-only meaning, which transfers a time without a date. The time-only meaning always uses the invalid date 1.1.000 for the date part. The time part has a value range from 00:00:00.0 to 23:59:59.9. This time-only meaning is not supported.
A timestamp meaning, consisting of a date and time.
The supported range is from 1.1.0001 0:00:00.0 up to 31.12.9999 23:59:59.9. Dates BC (before the birth of Christ) are not supported.
It is also possible to transfer 1.1.0000 0:00:00.0 as a value. This is a special value (because there is no year 0) and denotes "no time" is given. The "no time" value is the internal state of a #TIME (Natural type T) variable after a RESET #TIME is executed within Natural programs. The target language environment determines how "no time" is handled.
See the notes under data type T in the section Mapping Software AG IDL Data Types to the target languageC, Java or .NET.
The term number[.number] describes the number as it is: The first number is the number of digits before the decimal point and the second number is the number of digits after the decimal point. The total number of digits (before and after the decimal point) must not exceed 29. The number of digits after the decimal point must not exceed 7.
The length is given in bytes, not in number of characters.
The valid integer range is from -128 up to +127.
The valid integer range is from -32768 up to +32767.
The valid integer range is from -2147483648 up to +2147483647.
The following term restricts the valid range which can be transferred from -n.nnnnnn+Enn up to +n.nnnnnn+Enn. A mantissa of 7 decimal digits and an exponent of 2 decimal digits.
The following term restricts the valid range which can be transferred from -n.nnnnnnnnnnnnnnn+Enn up to +n.nnnnnnnnnnnnnnn+Enn. A mantissa of 16 decimal digits and an exponent of 2 decimal digits.
The real valid range and precision can be restricted by the mapping to the target language environment.
Valid values are TRUE and FALSE.
The length is given in bytes.
When using floating-point values, errors due to rounding can occur when converting to the target language environment. Thus, values from sender and receiver might differ slightly.
In environments where multibyte (non-modal) and double-byte (modal) codepages are used (in Asian countries but only rarely in western countries, except for Unicode encodings e.g. UTF-8.)
after conversion from the sender's codepage to the receiver's codepage the amount of data may increase.
to fit the field length restriction given by the IDL data may be truncated by the conversion routine used.
It is only in environments where single-byte codepages are used that the amount of data does not increase. Thus data is not truncated.
For more information see Internationalization for RPC-based Components in What is the Best Internationalization Approach to Use?
The IDL types K and KV fields allow for IBM modal codepages to transfer double-byte data without SO and SI bytes. This feature is designed for use in Asian countries.
If SAGTRPC is used as the conversion method in the broker:
SO and SI bytes may not be contained in IDL type K and KV fields
double-byte characters are allowed in IDL type K and KV fields only
single-byte characters cannot be transferred in IDL type K and KV fields
If SAGTRPC User Exit is used as the conversion method in the broker:
the handling of the different IDL type fields depends on the implementation of the SAGTRPC User Exit.
This is the customer's responsibility. See Writing SAGTRPC User Exits under Windows, UNIX or z/OS.
For more information see Internationalization for RPC-based Components in What is the Best Internationalization Approach to Use?
The length is given in 2-byte Unicode code units following the Unicode standard. UTF-16. The maximum length is restricted to 805306367 2-byte code units.
Depending on your target environment and target programming language the mapping may follow a different Unicode standard e.g. UTF-32.
Statements and their lexical entities can begin in any column and are separated by any number of whitespace characters: blank, new line carriage return, horizontal tab, and form feed.
The maximum line length allowed in an IDL file is 256 characters.
Comments can be entered in the following ways:
If the entire line is to be used for a user comment, enter an asterisk or a slash and an asterisk in columns 1 and 2 of the line:
* USER COMMENT /* USER COMMENT
If only the latter part of a line is to be used for a user comment, enter an asterisk or slash asterisk.
1 NAME (A20) * USER COMMENT 1 NUMBER (A15) /* USER COMMENT
Group and parameter names
can be defined with the following characters:
characters: a to z
characters: A to Z
digits: 0 to 9 (a digit must not be the first character)
special characters: - _ $ # & @ + /
other characters are not allowed.
are limited to a maximum length of 31 characters
are not allowed to be the same as a valid type-length specification.
For example:
1 P1 (P1) In Out
is invalid and will cause an error because the name P1 is identical to the type-length P1
must adhere to the rules of the target programming language, for example to permitted special characters or reserved keywords.
cannot be defined as the following reserved names:
ALIGNED, CALLNAT, DATA, DEFINE, END-DEFINE, IMS, IN, INOUT, IS, LIBRARY, OUT, PARAMETER, PROGRAM, RCODE, STRUCT, VERSION.
must be unique and must not conflict with those of the target programming language, see the following portion of an IDL file
Define Data Parameter 1 AA (I2) 1 AA (I4) 1 long (I4) End-define
and the output generated with the client.tpl as the template for target language C:
short int AA; long AA; /*erroneous, double declaration*/ long long; /*erroneous, double declaration*/
The ambiguous declaration of AA and long is passed unchecked and the stub will be generated. As you can see, this is not valid C syntax.
The following rules apply to library, library alias, program, program alias and structure names:
Names are restricted by length. Library, library alias, program and program alias are restricted to a maximum length of 128 characters. A structure name is restricted to a maximum length of 31 characters.
Names must adhere to the rules of the target programming language, for example regarding permitted special characters or reserved keywords.
Names should not start with the prefix "SAG". The prefix "SAG" is used within the delivered Software AG IDL files. See:
Names must be unique and different within the IDL file after conversion of the name to lowercase or uppercase characters. You cannot use the same name for a library, library alias, program, program alias and structure
Example: The following names are not allowed within an IDL file:
MYLIBRARY and MyLibrary
CALC and Calc
MYSTRUCTURE and mystructure
