This document describes the specific mapping of Software AG IDL data types, groups, arrays and structures to the PL/I programming language. See also remarks and hints on the Software AG IDL data types valid for all language bindings under Software AG IDL File. The following topics are covered here:
The following metasymbols and informal terms are used for the IDL in the table below.
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".
| Software AG IDL | Description | PL/I Data Type | Notes | Client Support |
Server Support |
|---|---|---|---|---|---|
Anumber |
Alphanumeric | CHAR(number) |
1 | x | x |
CHAR(*) |
1, 2 | ||||
AV |
Alphanumeric variable length | not supported | |||
AV[number] |
Alphanumeric variable length with maximum length | CHAR(number) VAR |
1, 16 | x | x |
CHAR(*) VAR |
1,2 | ||||
Bnumber |
Binary | BIT(number * 8) |
3, 15 | x | x |
BIT(*) |
3, 2 | ||||
BV |
Binary variable length | not supported | |||
BV[number] |
Binary variable length with maximum length | BIT(number*8) VAR |
3, 15 | x | |
D |
Date | CHAR(8)DATE('YYYYMMDD') |
4 | x | x |
F4 |
Floating point (small) | FLOAT DEC(6) |
5, 10 | x | x |
FLOAT BIN(21) |
2, 5, 10 | ||||
F8 |
Floating point (large) | FLOAT DEC(16) |
5, 10 | x | x |
FLOAT BIN(53) |
2, 5, 10 | ||||
I1 |
Integer (small) | BIN FIXED(7) |
12 | x | x |
I2 |
Integer (medium) | BIN FIXED(15) |
x | x | |
I4 |
Integer (large) | BIN FIXED(31) |
x | x | |
Knumber |
Kanji | GRAPHIC (number/2) |
6 | x | x |
GRAPHIC (*) |
2, 6 | ||||
KV |
Kanji variable length | not supported | |||
KV[number] |
Kanji variable length with maximum length | GRAPHIC (number/2) VAR |
6, 16 | x | x |
GRAPHIC (*) VAR |
2, 6 | ||||
L |
Logical | BIT(1) |
7, 14 | x | x |
Nnumber1[.number2] |
Unpacked decimal | PIC 'S(number1)9[V(number2)9]' |
13 | x | x |
NUnumber1[.number2] |
Unpacked decimal unsigned | PIC '(number1)9[V(number2)9]' |
13 | x | x |
Pnumber1[.number2] |
Packed decimal | DEC FIXED (number1+number2,number2) |
8 | x | x |
PUnumber1[.number2] |
Packed decimal unsigned | DEC FIXED (number1+number2,number2) |
8, 9 | x | x |
T |
Time | CHAR(17) |
11 | x | x |
Unumber |
Unicode | WIDECHAR(number) |
x | x | |
UV |
Unicode variable length | not supported | |||
UVnumber |
Unicode variable length with maximum length | WIDECHAR(number) VAR |
x | x |
See also the hints and restrictions valid for all language bindings under IDL Data Types.
Notes:
DATETIME function.
ERX_TRUE and ERX_FALSE defined in the
include file RPCAPI. See PL/I Wrapper Modules Delivered as Sources on z/OS.
(number1+number2) of digits is restricted by
your PL/I environment, usually 15 or 31 depending on the PL/I compiler in use.
See your compiler documentation. The number of digits after the decimal point
(number2) is restricted by the IDL. The value range of -127 to 128 of PL/I for
number2 is not supported. See IDL Data Types.
FLOAT will be used: On S/390 systems this is "Hexadecimal
floating-point".
DATETIME function. The fractional part of a second (hundredths and
thousandths of a second) is restricted by the IDL. See IDL Data Types. On receive, hundredths and thousandths are
set to zero, whereby on a send they are cut off.
(number1+number2) is restricted by
your PL/I environment, usually 15 or 31 depending on the PL/I compiler in use.
See your compiler documentation.
ALIGNED
attribute is given in the IDL. The data type L used by servers without
alignment is not supported.
ALIGNED
attribute is given in the IDL. The data type B used by servers without
alignment is not supported.
The library name is sent from a client to the server. Special characters are not replaced. The library alias is not sent to the server. In the RPC server the library name sent may be used to locate the target server. See Locating and Calling the Target Server under z/OS (CICS, Batch, IMS) | UNIX | Windows | Micro Focus | BS2000/OSD | z/VSE (CICS, Batch) | IBM i.
For a batch interface (TARGET=BATCH_xxx)
the library alias as given in the library-definition of the IDL
File is used to compose the name of an include file with DECLARE ENTRY
statements to describe the PL/I generated interfaces. The generated name is
<library-alias>. If no library alias is given, the library name as given
in the library definition of the IDL file is used instead. See library-definition under Software AG IDL Grammar.
The library name sent along with the client RPC request is not used in PL/I servers. See Locating and Calling the Target Server under CICS | z/OS Batch | z/OS IMS.
The program name is sent from a client to the server. Special characters are not replaced. The program alias is not sent to the server.
In the RPC server the program name sent is used to locate the target server. See Locating and Calling the Target Server under z/OS (CICS, Batch, IMS) | UNIX | Windows | Micro Focus | BS2000/OSD | z/VSE (CICS, Batch) | IBM i.
The program alias names as given in the
program-definition of the IDL file are
mapped to procedure or function names within the generated PL/I sources.
used to compose the file names of the generated output files. Therefore they must be names that are supported by the underlying file system.
When building procedure, function and source file names, the special characters '&', '+', '-', '.' and '/' are replaced by the character underscore '_' valid for PL/I names. Other special characters used in the program alias name are not changed and may lead to compilation errors when compiling the generated sources.
For a batch interface (TARGET=BATCH_xxx)
An include file and a source file are generated for every
program-definition given in the IDL. The generated names
for both are <program-alias>. When the program alias is not given in the
program-definition the program name is used instead.
For a CICS interface (TARGET=CICS_xxx)
A source file is generated for every
program-definition given in the IDL. The generated name is
<program-alias>. When the program alias is not given in the
program-definition the program name is used instead.
Example:
A program name of #HU$GO in the IDL results in #HU$GO_ as the
procedure name for the PL/I programming language and source file names #HUG$GO
and #HUG$GO.
There is no program name mapping on the server side. The RPC Server for PL/I calls the server using the program name sent along with the client RPC request. See Locating and Calling the Target Server under CICS | z/OS Batch | z/OS IMS.
When building parameter names the special characters '&', '+', '-', '.' and '/' allowed within names of parameters of the IDL, are mapped to the character underline '_' valid for PL/I names. The characters '#', '$' and '@' are allowed in PL/I and are not changed. Trailing and leading special characters are not removed.
HU&GO results in HU_GO as a valid PL/I parameter name.
&HUGO- results in _HUGO_ as a valid PL/I parameter name.
Depending whether you are using the client or the server side, there
are several possibilities regarding arrays. See also the
array-definition under Software AG IDL Grammar in the IDL Editor documentation for the syntax on how to describe
fixed arrays and unbounded arrays within the IDL file, and refer to
fixed-bound-array-index.
Fixed arrays within the IDL file are mapped to fixed PL/I arrays. The dimension and upper bounds are kept.
Example: The IDL definition "MYARRAY (A5/1:10)" is
mapped to the PL/I array "MYARRAY (10) CHAR(5)".
Unbounded arrays with and without maximum-upper-bound are
not supported by PL/I client-side wrapping.
Example: The IDL definition "MYARRAY (A10/1:V10)" as well
as "MYARRAY (A10/1:V)" is not supported.
Fixed arrays within the IDL file are mapped to fixed PL/I arrays. The dimension and upper bounds are kept.
Example: The IDL definition "MYARRAY (A5/1:10)" is
mapped to the PL/I array "MYARRAY (10) CHAR(5)".
Note:
An RPC server with a PL/I array defined with asterisks is supported on
the server side and is an alternative mapping to an array with fixed upper
bounds of the same dimension.
Example: The IDL definition "MYARRAY (A5/10,10,10)"
can either be mapped to the PL/I array
"MYARRY (10,10,10) CHAR(5)" or the PL/I array
"MYARRAY (*,*,*) CHAR(10)".
The RPC server source can be manually modified.
Unbounded arrays with or without maximum-upper-bound are mapped to PL/I
arrays defined with asterisks. The dimension is kept.
Example: The IDL definitions
"MYARRAY (A5/V10)" and
"MYARRAY (A5/1:V)" are mapped to the PL/I array
"MYARRAY (*) CHAR(5)".
Groups within the IDL file are mapped to the PL/I structures or PL/I
arrays of structures using level numbers. See the
group-parameter-definition under Software AG IDL Grammar for the syntax on how to
describe groups within the IDL file.
Structures within the IDL file are dissolved at the location where they
are used. They are mapped to PL/I structures using level numbers like groups.
See the structure-parameter-definition (IDL) under Software AG IDL Grammar for the syntax
on how to describe structures within the IDL file.
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). See the attribute-list under Software AG IDL Grammar for the syntax on
how to describe attributes within the IDL file and refer to the
direction-attribute.
The direction specification is reflected in the generated client interface objects as follows:
Direction attributes do not change the PL/I call interface.
Usage of direction attributes may be useful to reduce data traffic between RPC client and RPC server.
Parameters with the IN attribute are sent from the RPC client to
the RPC server.
Parameters with the OUT attribute are sent from the RPC server to
the RPC client.
Parameters with the IN and OUT attribute are sent from the RPC
client to the RPC server and then back to the RPC client.
Only the direction information of the top-level fields (level 1) is relevant. Group fields always inherit the specification from their parent. A different specification is ignored.
The RPC Server for PL/I considers the direction attribute send from
any RPC client Java, DCOM, C, COBOL, NET , XML and PL/I. Parameters with the IN
attribute are not sent back to the RPC client.
See the attribute-list under Software AG IDL Grammar for the syntax of
attributes in the IDL file and refer to
aligned-attribute.
A PL/I client can send the parameters with the ALIGNED attribute to an
RPC server. The RPC server decides (depending on programming language and
environment) whether the parameter is aligned or not. The ALIGNED attribute is
not considered in the generated PL/I client interface itself.
The RPC Server for PL/I server considers ALIGNED parameters as needed,
when the ALIGNED attribute is sent by an RPC client Java, DCOM, C, COBOL, .NET,
PL/I XML and PL/I.
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, i.e. a client using a function can call a server implemented as a procedure and vice versa.
It is possible to call the remote procedure as a function and not as a
procedure, if you prefer it, if it suits your interface and if the client
interface objects are generated with a Batch interface (TARGET=BATCH_xxx). An
EXEC CICS LINK interface (TARGET=CICS_xxx) cannot be invoked as a
function. However, you can call a batch interface within CICS.
Example. 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);
The client template generates a PL/I function instead of a PL/I procedure if the following is true:
A batch interface is generated, i.e. the value for the template
option TARGET is set to "BATCH_xxx"
In the interface description (IDL file) the last
parameter's name is function_result. The
name function_result is not case-sensitive.
parameter's direction is Out. See attribute-list under Software AG IDL Grammar.
parameter is a scalar variable, i.e. not an array, group or structure.
The RPC Server for PL/I is able to call any PL/I procedure and any PL/I function. For a PL/I function, the returned parameter is always the last parameter.