Quick Reference |
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 explains the syntax of IDL files in a formal notation. A more descriptive introduction to IDL files is given in the document Software AG IDL File. This document covers the following topics:
The following metasymbols are used to define the IDL:
The metasymbols "[" and "]"enclose optional lexical entities.
The metasymbols "{" and "}" enclose optional lexical entities which may be repeated a number of times.
The metasymbol "::=" separates the lexical entity to be defined (on the left) from the definition (on the right).
The metasymbol "|" separates lexical entities on the definition side (on the right) meaning all terms are valid to define the lexical entity to be defined (on the left).
The following basic terms are used to describe the IDL:
The informal term number
is a sequence of
numeric digits e.g. 123.
The informal term string
is a sequence of
characters. It can contain any character except enclosing apostrophes.
Examples are: 'DARMSTADT' '#FRANKFURT'
'&MUNICH'
.
Any terms in uppercase, special characters such as apostrophe, colon (other than the metasymbols above) are terminal lexical entities and must be entered as is.
The term identifier
is a sequence of
characters: a to z
characters: A to Z
digits: 0 to 9 (a digit must not be the first character)
special characters: - _ $ # & @ + / £ æ Æ ø Ø å Å
Software AG IDL |
::= library-definition { library-definition
} |
The IDL may contain any number of library-definitions
.
One library-definition
must be contained in an IDL file.
A library-definition
is the grouping of servers (remote
procedures).
library-definition |
::= LIBRARY 'library-name' [:'library-alias'] IS {
interface } |
library-name |
::= string |
library-alias |
::= string |
interface |
::= program-definition |
structure-definition |
library-definition |
A library-definition is valid until the next
library-definition or end of file.
|
library-name |
|
library-alias |
|
interface |
|
Library 'ServerLibrary' Is ..
Library 'ServerLibrary': 'AliasServerLibrary' Is ..
A program-definition
describes the parameters of servers (remote
procedures).
program-definition |
::= PROGRAM 'program-name' [:'program-alias'] IS |
program-name |
::= string |
program-alias |
::= string |
program-definition |
|
program-name |
|
program-alias |
|
Library 'ServerLibrary' Is Program 'ServerName' Is ..
Library 'ServerLibrary': 'AliasServerLibrary' Is Program 'ServerName' : 'AliasServerName' Is ..
A structure-definition
describes a user-defined type for reusability,
referenced in a structure-parameter-definition
(IDL).
structure-definition |
::= STRUCT 'structure-name' IS |
structure-name |
::= string |
structure-definition |
|
structure-name |
|
Library 'ServerLibrary': 'AliasServerLibrary' Is Struct 'Person' Is ..
The parameter-data-definition
describes the parameters of a server when
it is embedded in a program-definition
. It describes a user-defined type when
it is embedded in a structure-definition
.
parameter-data-definition |
::= DEFINE DATA PARAMETER |
parameter-data-definition |
|
Library 'ServerLibrary' Is Program 'ServerName' Is .. Define Data Parameter ... End-Define
Library 'ServerLibrary': 'AliasServerLibrary' Is Struct 'Person' Is .. Define Data Parameter ... End-Define
The construct simple-parameter-definition
describes the syntax of a
simple parameter, i.e. not a group (groups are described in a
group-parameter-definition
), not a reference to a structure (referencing a
structure is described in structure-parameter-definition
(IDL)).
simple-parameter-definition |
::= level parameter-name
(type-length[/array-definition]) |
level |
::= number |
parameter-name |
::= identifier |
type-length |
See IDL Data Types. |
level |
|
parameter-name |
|
type-length |
The type and length of the parameter. See IDL Data Types. |
... 1 PERSON-ID (N10) 1 PERSON-NAME (A100) ...
The construct group-parameter-definition
describes the syntax of a
group.
group-parameter-definition |
::= level group-name [(/array-definition)] |
level |
::= number |
group-name |
::= identifier |
level |
See simple-parameter-definition .
|
group-name |
|
... 1 PERSON /* this is the group */ 2 PERSON-ID (N10) /* this is a group member */ 2 PERSON-NAME (A100) /* this is also a group member */ ...
The construct structure-parameter-definition
describes the syntax of a
reference to a structure.
structure-parameter-definition |
::= level parameter-name |
level |
::= number |
parameter-name |
::= identifier |
structure-reference |
::= 'structure-name' |
level |
See simple-parameter-definition .
|
parameter-name |
See simple-parameter-definition .
|
structure-reference |
|
STRUCT 'Person' Is /* this defines the structure person */ Define Data Parameter 1 PERSON 2 PERSON-ID (N10) 2 PERSON-NAME (A100) End-Define ... 1 FATHER ('Person') /* this references the structure */ 1 MOTHER ('Person') /* this references the structure */ 1 CHILDS ('Person'/10) /* this references the structure */ ...
Arrays can have either fixed upper bounds or variable upper bounds, so-called unbounded arrays.
array-definition |
::= fixed-bound-array | unbounded-array |
fixed-bound-array |
::= [fixed-bound-array-index [,fixed-bound-array-index
[,fixed-bound-array-index]]] |
unbounded-array |
::= [unbounded-array-index [,unbounded-array-index
[,unbounded-array-index]]] |
fixed-bound-array-index |
::= [lower-bound:] upper-bound |
unbounded-array-index |
::= [1:] V[maximum-upper-bound] |
lower-bound |
::= number |
upper-bound |
::= number |
maximum-upper-bound |
::= number |
array-definition |
|
fixed-bound-array |
|
unbounded-array |
|
fixed-bound-array-index |
|
unbounded-array-index |
Note: |
lower-bound |
|
upper-bound |
|
maximum-upper-bound |
|
... 1 NAMES (A100/10) /* 1 dimensional array */ 1 TUPLES (A100/10,10) /* 2 dimensional array */ 1 TRIPLES (I1/1:20,1:20,1:20) /* 3 dimensional array */ ...
... 1 NAMES (A100/V) /* 1 dimensional array */ 1 TUPLES (A100/V,V) /* 2 dimensional array */ 1 TRIPLES (I1/1:V,1:V,1:V) /* 3 dimensional array */ ...
... 1 NAMES (A100/V10) /* 1 dimensional array */ 1 TUPLES (A100/V10,V10) /* 2 dimensional array */ 1 TRIPLES (I1/1:V20,1:V20,1:V20) /* 3 dimensional array */ ...
Warning: Mixed arrays with fixed upper bounds and variable upper bounds are not supported. (I2/1:V,20,V) is not permitted.(I2/V10,30) is not permitted. |
In the illustration above, the vectors of the second dimension have different lengths. The first vector has a length of 4, the second a length of 3 and the third a length of 2. The same is true for the third dimension with vector length of (3,4,5,6) (2,4,3) and (4,3).
Note:
This type of unbounded array is
not possible if you are using COBOL as the endpoint. In
COBOL, all vectors in a dimension have the same length. A 2-dimensional array
forms a rectangle and a 3-dimensional array forms a cuboid.
For the COBOL Wrapper, see Mapping Fixed and Unbounded Arrays.
For the IDL Extractor for COBOL, see COBOL Tables with Variable Size - DEPENDING ON
Clause.
Attributes describe further parameter properties to correctly map the parameter to the target platform or to optimize the parameter transfer.
attribute-list |
::= [ aligned-attribute ] [ direction-attribute ] [ ims-attribute ] [ choice-attribute ] |
aligned-attribute |
::= ALIGNED |
direction-attribute |
::= IN | OUT | IN OUT | INOUT |
ims-attribute |
::= IMS |
choice-attribute |
::= CHOICE |
aligned-attribute |
|
direction-attribute |
The direction attribute optimizes parameter transfer.
|
ims-attribute |
The ims-attribute marks PCB (Program Communication Block)
parameters for the target platform IMS (IBM's Information Management System).
|
choice-attribute |
The choice-attribute marks a group-parameter-definition as
the surrounding container for multiple possible output (MPO) structures. This kind of IDL syntax is retrieved when extracting,
for example,
from a REDEFINES Clause. See also Mapping Editor IDL Interface mapping function Set Multiple Possible Output (MPO) Structures for interface type DFHCOMMAREA (In same as Out, In different to Out) | Large Buffer (In same as Out, In different to Out) | Channel Container | IMS Connect.
|
1 PERSON_ID (NU12) ALIGNED
... 1 PERSON_ID (NU12) IN 1 PERSON_NAME (A100) OUT ...
... 1 PERSON_ID (NU12) IN OUT 1 PERSON_NAME (A100) IN OUT 1 DBPCB IMS 2 DBNAME (A8) 2 SEG-LEVEL-NO (A2) 2 DBSTATUS (A2) 2 FILLER (A20) ...
... 1 OUTPUT Out 2 PAYMENT-TYPE (A2) 2 PAYMENT-DATA-MPO Choice 3 PAYMENT-DATA (/V1) 4 PAYMENT-DATA (AV256) 3 PAYMENT-DATA-VOUCHER (/V1) 4 VOUCHER-ORIGIN (AV128) 4 VOUCHER-SERIES (AV128) 3 PAYMENT-DATA-CREDITCARD (/V1) 4 CREDITCARD-NUMBER (NU18) 4 CREDITCARD-CODE (NU12) 4 CREDITCARD-VALIDITY (AV8) ...