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 document Software AG IDL File. The following topics are covered here:


Mapping IDL Data Types to PL/I Data Types

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

  • 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 x x
CHAR(*) VAR 1,2    
Bnumber Binary BIT(number * 8) 3,14 x x
BIT(*) 2,3    
BV Binary variable length not supported      
BV[number] Binary variable length with maximum length BIT(number*8) VAR 3,14   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)   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,15 x x
GRAPHIC (*) VAR 2,6    
L Logical BIT(1) 7,13 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 in the IDL Editor documentation.

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 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.
  14. 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.
  15. For the client side the IDL data type may produce a warning message during compilation, which can be ignored.

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) | C | .NET | Micro Focus | BS2000 | z/VSE (CICS, Batch).

Client Side

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 in the IDL Editor documentation.

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.

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) | C | .NET | Micro Focus | BS2000 | z/VSE (CICS, Batch).

Client Side

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.

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.

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.

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

  • 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.

Server Side

  • 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)".

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 in the IDL Editor documentation for the syntax on how to describe groups within the IDL file.

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 in the IDL Editor documentation for the syntax on how to describe structures within the IDL file.

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 in the IDL Editor documentation 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:

  • 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.

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.

Mapping the ALIGNED Attribute

See the attribute-list under Software AG IDL Grammar in the IDL Editor documentation 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.

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 servers, that is, 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:

  • 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 in the IDL Editor documentation.

    • parameter is a scalar variable, i.e. not an array, group or structure.

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.