This document describes the specific mapping of Software AG IDL data types, groups, arrays and structures to the COBOL programming language. See also hints and restrictions on the Software AG IDL data types valid for all programming language bindings under IDL Data Types in the IDL Editor documentation.
This document covers the following topics:
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 | COBOL Data Type | Note |
|---|---|---|---|
A |
Alphanumeric | PIC X( |
|
AV |
Alphanumeric variable length | not supported | |
AV[ |
Alphanumeric variable length with maximum length | PIC X( |
13 |
B |
Binary | PIC X( |
11 |
BV |
Binary variable length | not supported | |
BV[ |
Binary variable length with maximum length | PIC X( |
11,13 |
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 X |
9,11 |
I2 |
Integer (medium) | PIC S9(4) BINARY |
10,12 |
I4 |
Integer (large) | PIC S9(9) BINARY |
10,12 |
K |
Kanji | PIC G( |
5 |
KV |
Kanji variable length | not supported | |
KV[ |
Kanji variable length with maximum length | PIC G( |
5,13 |
L |
Logical | PIC X |
6,7 |
N |
Unpacked decimal | PIC S9( |
2 |
NU |
Unpacked decimal unsigned | PIC 9( |
2 |
P |
Packed decimal | PIC S9( |
2 |
PU |
Packed decimal unsigned | PIC 9( |
2 |
T |
Time | PIC 9(15) |
3 |
U |
Unicode | PIC N( |
8 |
UV |
Unicode variable length | not supported | |
UV |
Unicode variable length with maximum length | PIC N( |
8,13 |
See also hints and restrictions on the Software AG IDL data types valid for all programming language bindings under IDL Data Types in the IDL Editor documentation.
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.
For COBOL, the total number of digits (number1+number2) is
lower than the maximum of 99 that EntireX supports. See IDL Data Types.
It varies by operating system and COBOL compiler. To enable more total number of digits than 18,
a compiler directive (option) may be required.
z/OS
The total number of digits (number1+number2) is restricted to 31 digits. The compiler option AR(E) is generated into the client interface objects and server skeletons if more than 18 digits are defined in the IDL.
BS2000
The total number of digits (number1+number2) is restricted to 31 digits.
z/VSE
The total number of digits (number1+number2) is restricted to 18 digits.
Other Operating Systems or Compilers
Refer to your COBOL compiler documentation to see whether compiler directives or options exist.
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 | COBOL | DCOM | .NET | Java | Natural | PL/I | XML.
The time corresponds to the format PIC 9(15). The value contained has
the form YYYYMMDDHHIISST. This form corresponds to COBOL DATE/TIME
functions.
When floating-point data types are used, rounding errors can occur, so that the values of senders and receivers might differ slightly.
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 because Fujitsu Siemens compilers do not support DBCS.
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'.
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.
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.):
Case False: Move X'00' to data-name.
Case True: Move X'01' to data-name.
The length is given in Unicode code units following the Unicode standard UTF-16.
z/OS and IBM Compiler
Unicode requires the IBM Enterprise compiler.
Unicode is represented in UTF-16 big-endian format (CCSID 1200).
BS2000
Unicode requires a compiler that supports COBOL data type NATIONAL.
See BS2000 Prerequisites.
Unicode is represented in UTF-16 big-endian format.
Other Operating Systems or Compilers
Refer to your COBOL compiler documentation.
COBOL for operating systems z/OS, BS2000, z/VSE 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.
The value range for COBOL data type BINARY on z/OS, BS2000, z/VSE
and IBM i depends on the COBOL compiler settings:
With COBOL 85 standard, the mapped COBOL data type BINARY is more
restrictive than the IDL data types I2 and I4. See IDL Data Types.
This means that COBOL RPC clients cannot send
(and COBOL RPC servers cannot return) the full value range defined by the IDL
types I2 and I4. On the other hand, COBOL RPC clients and COBOL RPC servers may
receive a value range (from a non-COBOL RPC partner) outside of the value range
of your COBOL data type.
Without COBOL 85 standard, the value range of the COBOL
data type BINARY depends on the binary field size, thus matches the IDL data
type exactly. In this case, there are no restriction regarding value ranges.
To match the value range of IDL type I2 and I4 exactly, depending on the operating system, the following compiler directive (option) is generated into the client interface objects and server skeletons:
z/OS and z/VSE
the IBM compiler option TRUNC(BIN)
Other Operating Systems or Compilers
refer to your COBOL compiler documentation to see whether compiler directives or options exist.
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 conversion will be
performed.
Supported for operating systems z/OS, BS2000, z/VSE and IBM i only.
With variable length fields with maximum (AVn,
BVn, KVn and UVn),
connecting COBOL to endpoints with a concept of real 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 data
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 in the IDL Editor documentation.
If your application relies on trailing SPACEs, HEX ZEROs or Unicode code points U+0020,
you cannot use a mapping to variable length fields with maximum (AVn, BVn, KVn and UVn);
Use a mapping to fixed length types instead: An, Bn, Kn and Un.
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.
If you are using a so-called server mapping file, the target COBOL server program is located with the help of this file. A server mapping file is a Designer file with extension .cvm. See Server Mapping Files for COBOL. See also Locating and Calling the Target Server under z/OS (CICS, Batch, IMS) | BS2000.
If you are not using a server mapping file, the IDL library name as specified in the IDL file is ignored.
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.
If you are using a so-called server mapping file, the target COBOL server program is located with the help of this file. A server mapping file is a Designer file with extension .cvm. See Server Mapping Files for COBOL. This provides the following advantages:
IDL program names are not limited to 8 characters and do not have to match the target COBOL server program names.
Target COBOL server program names (COBOL subprograms) can be customized during wrapping. See Customize Automatically Generated Server Names.
If you are not using a server mapping file, the target COBOL server program must match the IDL program name. In this case:
The length of the IDL program names is limited by your COBOL system (often 8 characters).
The set of allowed characters for IDL program names is restricted by your COBOL system and the underlying file system.
It is your responsibility as application developer to ensure that these requirements are met. See Locating and Calling the Target Server under z/OS (CICS, Batch, IMS) | BS2000.
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
Fixed Arrays
Fixed arrays within the IDL file are mapped to fixed COBOL tables.
See the array-definition under Software AG IDL Grammar in the IDL Editor documentation for the syntax on how to
describe fixed arrays within the IDL file and refer to
fixed-bound-array-index.
IDL Unbounded Arrays with Maximum
IDL unbounded arrays with maximum are mapped to COBOL tables with the
DEPENDING ON clause. See COBOL Tables with Variable Size - DEPENDING ON Clause under COBOL to IDL Mapping in the IDL Extractor for COBOL documentation. Note the following:
The from-value of the DEPENDING ON clause is always 1.
ODO objects for justification of the number of occurrences are generated into the client interface objects and server skeletons.
When a 2/3 dimensional unbounded array is received from a partner,
all vectors of the second dimension must have the same length, i.e. the array
forms a rectangle. The same applies to the third dimension (all vectors must
have the same length), the array forms a cuboid. If these rules are violated,
unexpected behavior occurs. For illustration, see picture under array-definition under Software AG IDL Grammar in the IDL Editor documentation.
Sending a 2/3 dimensional unbounded array to a partner violating the rule above is not possible: COBOL does not allow you to set vector lengths differently.
A maximum upper bound given with the IDL unbounded array defines the maximum COBOL table size.
The COBOL table can vary from 1 to this maximum. See array-definition under Software AG IDL Grammar in the IDL Editor documentation
for the syntax on how to describe unbounded arrays within the IDL file and refer to unbound-array-index.
Depending on your target COBOL compiler, 2- and 3-dimensional unbounded arrays may not be supported (e.g. BS2000).
The Designer generates the COBOL interface objects and server (skeletons) without considering restrictions of the target COBOL compiler. See your COBOL compiler documentation for possible workarounds, for example using compiler switches or compiler options.
IDL Unbounded Arrays without Maximum
IDL unbounded arrays without a maximum are mapped to COBOL tables with the UNBOUNDED keyword.
There is no upper bound limitation also on the COBOL side. They are restricted to clients on z/OS with standard linkage
calling convention
(CICS | Batch | IMS) to its client interface object.
See Using IDL Unbounded Groups or Arrays without Maximum for more information.
IDL Unbounded Arrays without Maximum
IDL unbounded arrays without a maximum are not supported by COBOL Wrapper server generation and EntireX RPC servers under
z/OS (CICS, Batch, IMS) |
BS2000 |
CICS IPIC |
CICS ECI |
IMS Connect |
CICS Socket Listener.
Groups within the IDL file are mapped to COBOL structures using level numbers.
See the group-parameter-definition for the syntax on how to describe groups within the IDL file.
For groups with an array definition (including fixed, maximum upper bound or without upper bound) the same applies as for arrays, see Mapping Fixed and Unbounded Arrays. Additionally note the following:
If unbounded groups are nested, and depending on your target COBOL compiler, they may not be supported (e.g. BS2000).
There is a restriction on the number of indices. Most COBOL compilers support a maximum of 7 indices.
The Designer generates the COBOL interface objects and server (skeletons) without considering restrictions of the target COBOL compiler. See your COBOL compiler documentation for possibilities to work round the restrictions, for example using compiler switches or compiler options.
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 in the IDL Editor documentation 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 InOut 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
direction-attribute.
This direction specification is reflected in the generated COBOL interface object as follows:
Direction attributes do not change the COBOL call interface because parameters are always treated as "called by reference".
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.
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 in the IDL Editor documentation for the syntax on how
to describe attributes within the IDL file and refer to
direction-attribute.
The direction attribute sent from any RPC client, for example EntireX Adapter, Java, DCOM, C, COBOL, .NET, XML and PL/I is considered. It is taken from the IDL file and any (optional) server mapping file (.cvm) to the related IDL file.
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
direction-attribute.
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:
*SYNC in the commands
CRTCBLMOD or CRTBNDCBL for the usage of the SYNCHRONIZED clause.
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.