Version 9.6
 —  EntireX COBOL Wrapper  —

Software AG IDL to COBOL Mapping

This document describes the specific mapping of Software AG IDL data types, groups, arrays and structures to the COBOL programming language. Please note also the remarks and hints on the IDL data types valid for all language bindings found under Software AG IDL File.

This document covers the following topics:


Mapping IDL Data Types to COBOL Data Types

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

Software AG IDL Description COBOL Data Type Note
Anumber Alphanumeric PIC X(number)  
AV Alphanumeric variable length not supported  
AV[number] Alphanumeric variable length with maximum length PIC X(number) 14
B number Binary PIC X(number) 12
BV Binary variable length not supported  
BV[number] Binary variable length with maximum length PIC X(number) 12, 14
D Date PIC 9(8) 1
F4 Floating point (small) USAGE COMP-1 4
F8 Floating point (large) USAGE COMP-2 4
I1 Integer (small) PIC S9(2) COMP-5 10
PIC X 9,13
I2 Integer (medium) PIC S9(4) COMP-5 10
PIC S9(4) BINARY 11,13
I4 Integer (large) PIC S9(9) COMP-5 10
PIC S9(9) BINARY 11,13
Knumber Kanji PIC G(number/2) DISPLAY-1 5
KV Kanji variable length not supported  
KV[number] Kanji variable length with maximum length PIC G(number/2 DISPLAY-1) 5, 14
L Logical PIC X 6,7
Nnumber1[.number2] Unpacked decimal PIC S9(number1) [V(number2)] 2
NU number1[.number2] Unpacked decimal unsigned PIC 9(number1) [V(number2)] 2
P number1[.number2] Packed decimal PIC S9(number1) [V(number2)] PACKED-DECIMAL 2
PU number1[.number2] Packed decimal unsigned PIC 9(number1) [V(number2)] PACKED-DECIMAL 2
T Time PIC 9(15) 3
Unumber Unicode PIC N(number) NATIONAL 8
UV Unicode variable length not supported  
UVnumber Unicode variable length with maximum length PIC N(number) NATIONAL 8, 14

See also the hints and restrictions under Software AG IDL File valid for all language bindings.

Notes:

  1. The date corresponds to the format PIC 9(8). The value contained has the form YYYYMMDD. This form corresponds to COBOL DATE functions. This is an IBM extension of COBOL85 standard.

  2. Depending on your COBOL compiler and settings, the number of digits may be restricted, which means that number1+ number2 must be less than or equal to 18. Please note the number of digits after the decimal point. See IDL Data Types.

    To enable range values with more than 18 digits, depending on the operating system, the following compiler directive (option) is generated into the client interface objects and server skeletons if more than 18 digits are defined in the IDL.

    Under z/OS and z/VSE:

    Under all other operating systems or compilers:

  3. The time corresponds to the format PIC 9(15). The value contained has the form YYYYMMDDHHIISST. This form corresponds to COBOL DATE/TIME functions.

  4. When floating-point data types are used, rounding errors can occur, so that the values of senders and receivers might differ slightly.

  5. The length for IDL data type is given in bytes. For COBOL the length is in DBCS characters (2 bytes). IDL data type K is not supported under BS2000/OSD because Fujitsu Siemens compilers do not support DBCS.

  6. To inspect the Boolean value of a data item of IDL type Logical, you can specify PIC X followed by condition names (similar code is generated for scalar logical IDL types):

     level-number data-name PIC X.
     88           data-name-false value X'00'.
     88           data-name-true  value X'01' thru X'FF'.

    Under IBM i,

    The SYMBOLIC CHARACTERS clause in the SPECIAL-NAMES paragraph is not supported. The following COBOL statements demonstrate how you can define alternatively a character, named HEX-00, with a value of hexadecimal zero to be used for comparison:

     WORKING-STORAGE SECTION.
     01  HEX-00-B           PIC 9(4) BINARY VALUE 0.
     01  HEX-00-H REDEFINES HEX-00-B.
        02  FILLER         PIC X.
        02  HEX-00         PIC X.
  7. To set the Boolean value of a Logical data item, specify the following hexadecimal values in a one-byte data field (e.g. defined as PIC X.):

  8. The length is given in Unicode code units following the Unicode standard UTF-16.

    Under z/OS and IBM Compiler:

    Under BS2000/OSD:

    Under Micro Focus (UNIX and Windows):

    Under all other operating systems or compilers:

  9. COBOL for operating systems z/OS, z/VSE, BS2000/OSD and IBM i does not have a corresponding data type for a compatible I1 mapping. The mapping to COBOL PIC X data type should be seen as a FILLER variable. If including an I1 data type into the interface is required, it is your responsibility as application developer to process the content of this parameter provided (during receive) and expected (during send) correctly. Negative values are given as the two's complement binary number.

  10. Supported for Micro Focus COBOL for operating systems UNIX and Windows only.

  11. The value range for COBOL data type BINARY on z/OS, z/VSE, BS2000/OSD and IBM i depends on the COBOL compiler settings:

  12. COBOL does not have a corresponding data type for a compatible B/BV mapping. Thus the mapping is to COBOL PIC X data type. EntireX RPC transports the (binary) data as it is: no character translation or conversion will be performed.

  13. Supported for operating systems z/OS, z/VSE, BS2000/OSD and IBM i only.

  14. With variable length fields with maximum (AVn, BVn, KVn and UVn), mapping to endpoints with a concept of reals string types - such as Java, .NET, C, XML, Web services etc. - is straightforward. The transfer of data in the RPC data stream depends on the actual length of the string and not the field size, as seen in COBOL. For the COBOL side, the actual content length of such fields is determined using a trim mechanism. For AVn, all trailing SPACEs are ignored before send. After receive, the content is padded with trailing SPACEs up to the COBOL field size. For BVn, HEX ZERO is used instead of SPACE; for UVn, Unicode code point U+0020. See also the notes under IDL Data Types under Software AG IDL File in the IDL Editor documentation.

Top of page

Mapping Library Name and Alias

Client Side

The IDL library name as specified in the IDL file (there is no 8-character limitation) is sent from a client to the server. Special characters are not replaced. The library alias is neither sent to the server nor used for other purposes on the COBOL client side.

Server Side

If you are using a so-called server-side server mapping file the target RPC server (COBOL subprogram) is located with the help of this file. See Server Mapping File (SVM) and Locating and Calling the Target Server under z/OS (CICS, Batch, IMS) | Micro Focus | BS2000/OSD | z/VSE (CICS, Batch) |IBM i.

If you are not using an SVM file, the IDL library name as specified in the IDL file is ignored.

Top of page

Mapping Program Name and Alias

Client Side

The IDL program name as specified in the IDL file (there is no 8-character limitation) is sent from a client to the server. Special characters are not replaced. The program alias is not sent to the server, but during wrapping it is used to derive the suggestion for the source file names of the client interface objects (COBOL subprograms, copybooks) instead of using the IDL program names, see Customize Automatically Generated Client Names.

Server Side

If you are using a so-called server-side server mapping file, the target RPC server (COBOL subprogram) is located with the help of this file. See Server Mapping File (SVM) and Locating and Calling the Target Server under z/OS (CICS, Batch, IMS) | Micro Focus | BS2000/OSD | z/VSE (CICS, Batch) |IBM i. This provides the following advantages:

The SVM file is generated either during wrapping (see Using the Natural Wrapper for the Client Side) or during extraction (see IDL Extractor for COBOL). It is wrapped into the RPC client components and the relevant information is sent from a client to the server. Therefore it is important to generate or extract the target COBOL RPC (COBOL subprogram) server first, before creating any RPC client component.

If you are not using an SVM file, the target RPC server (COBOL subprogram) must match the IDL program name. In this case:

It is your responsibility as application developer to ensure that these requirements are met.

Top of page

Mapping Parameter Names

The parameter names, as given in the parameter-data-definition of the IDL file, are mapped to fields within the LINKAGE section of the generated COBOL client interface objects and COBOL server skeletons.

When building fields within the LINKAGE section, the special characters '#', '$', '&', '+', '-', '.', '/', '@' and '_', allowed within names of parameters, are mapped to the character hyphen '-' valid for COBOL names. Example:

HU$GO results in HU-GO

Trailing and preceding special characters are also removed. Example:

#HUGO$ results in HUGO

Subsequent special characters are replaced by one hyphen. Example:

HU$#$GO results in HU-GO

If the parameter name starts with a digit, e.g. '1', it is prefixed with the character 'P'. Example:

1HUGO results in P1HUGO

Top of page

Mapping Fixed and Unbounded Arrays

Client and Server Side

Top of page

Mapping Groups and Periodic Groups

Client and Server Side

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 COBOL structures like groups. See the structure-definition 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 direction-attribute.

Client Side

This direction specification is reflected in the generated COBOL interface object as follows:

Note that 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.

See the attribute-list under Software AG IDL Grammar for the syntax on how to describe attributes within the IDL file and refer to direction-attribute.

Server Side

If you are using an SVM file, the RPC server considers the direction attribute found in the SVM file.

If your RPC server is generated with a previous version of EntireX without an SVM file, the RPC server considers the direction attribute sent from any RPC client, for example Java, DCOM, C, COBOL, .NET, XML and PL/I.

Top of page

Mapping the ALIGNED Attribute

See the attribute-list under Software AG IDL Grammar for the syntax on how to describe attributes within the IDL file and refer to direction-attribute.

Client and Server Side

This attribute corresponds to the SYNCHRONIZED clause. If it is specified, data will be mapped according to the following rules:

Software AG IDL COBOL Data Type Alignment Notes
F4 USAGE COMP-1 SYNC +4 1
F8 USAGE COMP-2 SYNC +8 1
I2 PIC S9(4) BINARY SYNC +2 1
I4 PIC S9(8) BINARY SYNC +4 1

Notes:

  1. On IBM i, specify the compiler option *SYNC in the commands CRTCBLMOD or CRTBNDCBL for the usage of the SYNCHRONIZED clause.

Top of page

Calling Servers as Procedures or Functions

Client and Server Side

The COBOL 85 standard does not support a concept of functions like the programming languages C or PL/I. Any Software AG IDL program definition is mapped to a COBOL program. See Mapping Program Name and Alias.

Top of page