EntireX Version 9.7
 —  EntireX PL/I Wrapper  —

Software AG IDL to PL/I Mapping

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:


Mapping IDL Data Types to PL/I Data Types

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

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,8 x x
CHAR(*) VAR 1,2    
Bnumber Binary BIT(number * 8) 3,15 x x
BIT(*) 2,3    
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,11 x x
FLOAT BIN(21) 2,5,11    
F8 Floating point (large) FLOAT DEC(16) 5,11 x x
FLOAT BIN(53) 2,5,11    
I1 Integer (small) BIN FIXED(7) 13 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]' 8 x x
NUnumber1[.number2] Unpacked decimal unsigned PIC '(number1)9[V(number2)9]' 8,10 x x
Pnumber1[.number2] Packed decimal DEC FIXED (number1+number2,number2) 8,9 x x
PUnumber1[.number2] Packed decimal unsigned DEC FIXED (number1+number2,number2) 8,9,10 x x
T Time CHAR(17) 12 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:

  1. The maximum length is restricted by the PL/I programming language, usually 32767 characters, i.e. 32767 bytes in the IDL. A warning message is produced during the generation process if this limit is exceeded.
  2. This form is an alternative PL/I mapping for the server side. It is not directly generated by the PL/I Wrapper. The RPC Server source file can be manually modified.
  3. The maximum length is restricted by the PL/I programming language, usually 32767 bits, i.e. 4095 bytes in the IDL (the data type length in PL/I is a multiple of 8 of the length given in the IDL). A warning message is produced during the generation process if this limit is exceeded.
  4. The format for date is compatible with the date part of the built-in PL/I DATETIME function.
  5. When floating-point data types are used, rounding errors can occur, so that the values of senders and receivers might differ slightly.
  6. For IDL data type K and KV, graphic support - also known as DBCS support - must be switched on in your PL/I compiler; see your compiler documentation on how to switch on graphic support. The maximum length for graphic is restricted by the PL/I programming language, usually 16383 graphics, i.e. 32766 bytes in the IDL (the graphic data type length in PL/I is half the length given in the IDL, therefore the length given in the IDL must be even). A warning message is produced during the generation process if this limit is exceeded.
  7. The logical values are defined as '1'b for true and '0'b for false. We recommend using the values ERX_TRUE and ERX_FALSE defined in the include file RPCAPI. See PL/I Wrapper Modules Delivered as Sources on z/OS.
  8. For PL/I, the digits after decimal point (number2) supported by EntireX is 7, and the total number of digits (number1+number2) supported by EntireX is 29. This is lower than the maximum of 99 supported by EntireX. See IDL Data Types.

    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 section Mapping IDL Data Types to target language environment C | CL | COBOL | DCOM | .NET | Java | Natural | PL/I | RPG | XML.

    To enable a total number of digits greater than 15 for PL/I, a compiler directive (option) may be required. See your compiler documentation.

  9. The value range of -127 to 128 of PL/I for number2 is not supported.
  10. Negative values cannot be sent by clients and will be rejected on a send.
  11. For servers, the "typical" platform-dependent representation of FLOAT will be used: On S/390 systems this is "Hexadecimal floating-point".
  12. The value for time has the form YYYYMMDDHHIISST00 compatible with the PL/I 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.
  13. For the stubless RPC Server the compiler must use a 1-byte field for the target PL/I data type. It is not supported by the PL/I for MVS & VM V1R1.1 compiler. For PL/I Wrapper clients there are no restrictions; any compiler can be used.
  14. For the server side the data type L is aligned, even if no ALIGNED attribute is given in the IDL. The data type L used by servers without alignment is not supported.
  15. For the server side the data type B is aligned, even if no ALIGNED attribute is given in the IDL. The data type B used by servers without alignment is not supported.
  16. For the client side the IDL data type may produce a warning message during compilation, which can be ignored. Linkage and execution are possible. For the PL/I for MVS & VM V1R1.1 Compiler, the warning message is IEL0872 'ADDR' BUILTIN FUNCTION RETURNS A POINTER TO THE TWO-BYTE LENGTH FIELD PRECEDING THE VARYING STRING VALUE.

Top of page

Mapping Library Name and Alias

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.

Client Side

For a batch interface (TARGET=BATCH_xxx)

Server Side

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.

Top of page

Mapping Program Name and Alias

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.

Client Side

The program alias names as given in the program-definition of the IDL file are

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)

For a CICS interface (TARGET=CICS_xxx)

Example:

Server Side

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.

Top of page

Mapping Parameter Names

Client and Server Side

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.

Example

HU&GO results in HU_GO as a valid PL/I parameter name.
&HUGO- results in _HUGO_ as a valid PL/I parameter name.

Top of page

Mapping Fixed and Unbounded Arrays

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.

Client Side

Server Side

Top of page

Mapping Groups and Periodic Groups

Client and Server Side

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.

Top of page

Mapping Structures

Client and Server Side

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.

Top of page

Mapping the Direction Attributes In, Out, 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). 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.

Client Side

The direction specification is reflected in the generated client interface objects as follows:

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.

Server Side

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.

Top of page

Mapping the ALIGNED Attribute

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

Client Side

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.

Server Side

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.

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, i.e. a client using a function can call a server implemented as a procedure and vice versa.

Client Side

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:

Server Side

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.

Top of page