TIBCO Product Documentation - TIBCO ActiveMatrix ......COBOL, PL/I, and RPG copybook files describe the data structure for the corresponding binary data. You can interpret or create

TIBCO ActiveMatrix BusinessWorks™ Plug-infor Data ConversionUser's GuideSoftware Release 4.6February 2019

Two-Second Advantage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCHEMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (ORPROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THEEMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANYOTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS ANDCONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTEDSOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THECLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOADOR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USERLICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THESOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, ANDYOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BEBOUND BY THE SAME.

ANY SOFTWARE ITEM IDENTIFIED AS THIRD PARTY LIBRARY IS AVAILABLE UNDERSEPARATE SOFTWARE LICENSE TERMS AND IS NOT PART OF A TIBCO PRODUCT. AS SUCH,THESE SOFTWARE ITEMS ARE NOT COVERED BY THE TERMS OF YOUR AGREEMENT WITHTIBCO, INCLUDING ANY TERMS CONCERNING SUPPORT, MAINTENANCE, WARRANTIES,AND INDEMNITIES. DOWNLOAD AND USE OF THESE ITEMS IS SOLELY AT YOUR OWNDISCRETION AND SUBJECT TO THE LICENSE TERMS APPLICABLE TO THEM. BY PROCEEDINGTO DOWNLOAD, INSTALL OR USE ANY OF THESE ITEMS, YOU ACKNOWLEDGE THEFOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO PRODUCTS.

This document is subject to U.S. and international copyright laws and treaties. No part of thisdocument may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIBCO, Two-Second Advantage, TIBCO Rendezvous, TIBCO Business Studio, TIBCO EnterpriseMessage Service, TIBCO Administrator, TIBCO ActiveMatrix BusinessWorks, TIBCO BusinessWorksContainer Edition, and TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion are eitherregistered trademarks or trademarks of TIBCO Software Inc. in the United States and/or othercountries.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform EnterpriseEdition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks ofOracle Corporation in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.

This software may be available on multiple operating systems. However, not all operating systemplatforms for a specific software version are released at the same time. Please see the readme.txt file forthe availability of this software version on a specific operating system platform.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

2

TIBCO ActiveMatrix BusinessWorks™ Plug-in for Data Conversion User's Guide

This and other products of TIBCO Software Inc. may be covered by registered patents. Please refer toTIBCO's Virtual Patent Marking document (https://www.tibco.com/patents) for details.

Copyright © 2004-2019 TIBCO Software Inc. All rights reserved.

TIBCO Software Inc.

3


https://www.tibco.com/patents

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Overview of Data Conversion Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Examples Sending and Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Language Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

COBOL Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Supported Usages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Supported Picture Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Supported COBOL Clauses and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

DATE FORMAT Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

OCCURS … DEPENDING ON Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Handling of Computation Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

COMP Versus COMP-5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

COMP-6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Handling of Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Handling of Numeric-Edited and External Floating-Point Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Numeric Items with Scaling Position P . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

SYNC Clause and Slack Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Insert Slack Byte Items Menu Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Alignment Compatibility with Previous Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Sign Nibbles in Zoned and Packed Decimal Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Unsupported Clauses Features Levels and Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

PL/I Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Declarations and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Data Factoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

* Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Data Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Unions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

The REFER Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

COMPLEX Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

INITIAL Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Data Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

RPG Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

4


Supported RPG Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Mapping of RPG Internal Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Unsupported RPG Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

Handling of Items in Binary Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Dealing with Invalid XML Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Handling of Zoned Decimal Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

EBCDIC Character Sets (Such As Cp037) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

ASCII Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Handling of Floating Point Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Latin Normalization in Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Data Conversion Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Copybook Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Settings Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Copybook Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Import Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Generate from an XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Mapping of XML Schema Types to COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Schema Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Insert Slack Byte Items Menu Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Schema Preview Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Field Configuration Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Configuration of Data-Description Entries for a REDEFINES group Or Union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

Control Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

In-Place Copybook Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Generated Schema Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Parse Copybook Data Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Description Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Fault Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Parsing Incomplete Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Allow Incomplete Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Allow Incomplete Text Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Validation of Elementary Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Connecting Multiple Parse Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Parsing of a Large Number of Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Procedure for Reading in a Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Render Copybook Data Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

5


General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Description Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66

Fault Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67

Item Initialization During Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67

Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73

6


Figures

Sending or Receiving COBOL Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Receiving Data from a COBOL Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Sending Data to a COBOL Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

ACTUAL and CONVERTED Fields on the Field Configuration page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7


TIBCO Documentation and Support Services

How to Access TIBCO Documentation

Documentation for TIBCO products is available on the TIBCO Product Documentation website, mainlyin HTML and PDF formats.

The TIBCO Product Documentation website is updated frequently and is more current than any otherdocumentation included with the product. To access the latest documentation, visit https://docs.tibco.com.

Product-Specific Documentation

Documentation for TIBCO products is not bundled with the software. Instead, it is available on theTIBCO Documentation site. To directly access documentation for this product, double-click thefollowing file:

TIBCO_HOME/release_notes/TIB_bwdcp_version_docinfo.html

where TIBCO_HOME is the top-level directory in which TIBCO products are installed. On Windows,the default TIBCO_HOME is C:\Program Files\tibco. On UNIX systems, the default TIBCO_HOMEis /opt/tibco.

The following documents for this product can be found on the TIBCO Documentation site:

● TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion User’s Guide

● TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion Installation

● TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion Release Notes

How to Contact TIBCO Support

You can contact TIBCO Support in the following ways:

● For an overview of TIBCO Support, visit http://www.tibco.com/services/support.

● For accessing the Support Knowledge Base and getting personalized content about products you areinterested in, visit the TIBCO Support portal at https://support.tibco.com.

● For creating a Support case, you must have a valid maintenance or support contract with TIBCO.You also need a user name and password to log in to https://support.tibco.com. If you do not have auser name, you can request one by clicking Register on the website.

How to Join TIBCO Community

TIBCO Community is an online destination for TIBCO customers, partners, and resident experts. It is aplace to share and access the collective experience of the TIBCO community. TIBCO Community offersforums, blogs, and access to a variety of resources. To register, go to the following web address:

https://community.tibco.com

8


https://docs.tibco.com

https://docs.tibco.com

http://www.tibco.com/services/support

https://support.tibco.com

https://support.tibco.com

https://community.tibco.com

Introduction

COBOL, PL/I, and RPG copybook files describe the data structure for the corresponding binary data.You can interpret or create COBOL, PL/I, or RPG data according to the specified copybook file in theData Conversion palette in the Plug-in.

Overview of Data Conversion PaletteThe Data Conversion palette provides a mechanism for interacting with applications that produceCOBOL, PL/I, or RPG data. Before you can use that data, TIBCO ActiveMatrix BusinessWorks™ mustparse it into XML for access by activities within a process definition.

The Data Conversion palette consists of the following activities:

● Copybook Resource — This shared configuration resource contains COBOL, PL/I, or RPG datastructure, and generates an XML Schema Definition (XSD) schema for input and output mappingsfor activities.

● Parse Copybook Data Activity — This activity parses incoming data according to a specifiedCopybook resource. After parsing, the output XML data conforms to the XSD schema thatcorresponds to the Copybook resource, and other activities can access the data.

● Render Copybook Data Activity — This activity accepts XML data and produces data according tothe COBOL, PL/I, or RPG data structure held in a specified Copybook resource. The formatted datacan then be passed to an application.

Typically, COBOL, PL/I, or RPG applications communicate with other applications by way of amessaging service, such as IBM MQ Series or Java Messaging Service (JMS). These applications can alsoread data from or write data to a file. ActiveMatrix BusinessWorks can retrieve or send COBOL, PL/I, orRPG data by way of a messaging service or the file system.

The following figure illustrates how the Plug-in receives and sends COBOL data to and from amainframe application or a COBOL data file.

9


Sending or Receiving COBOL Data

Examples Sending and Retrieving DataYou can either send data to or retrieve data from a COBOL, PL/I, or RPG application in the DataConversion palette.

These examples illustrate the basic usage of parsing, rendering, sending, and receiving. Yourintegration project might be more complex and require any combination of those tasks in the sameprocess definition.

Receiving Data

This process receives a JMS queue message with COBOL data. The ParseCopybookData activityconverts the data into XML and then passes it to the Handle Incoming Data subprocess.

Receiving Data from a COBOL Application

Sending Data

This process recieves data from an incoming HTTP request and then passes it to the Handle IncomingData subprocess. The data is then passed to the RenderCopybookData activity so that COBOL data canbe created and sent to a COBOL application. The data is then sent to the COBOL application by way ofa JMS Queue Sender activity.

Sending Data to a COBOL Application

10


Language Features

The Plug-in supports a variety of language features.

This Plug-in release introduces new features and functionality. For a complete, detailed list, see theTIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion Release Notes.

During migration, the new features might cause the Plug-in to work differently than expected. Toensure data integrity, if you use ActiveMatrix BusinessWorks processes defined in a previous version ofthe Plug-in, it is good practice that you install the Plug-in and test the processes. If the results are asexpected, migrate the processes to the new version.

COBOL FeaturesThe Plug-in supports some but not all COBOL features.

The COBOL capability of the Plug-in has been tested against IBM Enterprise COBOL for z/OS 3.4.1(5655-G53). Other compilers might produce incompatible data layouts.

Supported Usages

Usage Notes

BINARY COMP, COMPUTATIONAL

COMP-4, COMPUTATIONAL-4


See Handling of Computation Items.


PACKED-DECIMAL, COMP-6,

COMPUTATIONAL-6

DISPLAY Depending on the PICTURE type and the Copybook resourcesettings, the Plug-in converts the data elements with this usageas string or as a numeric type in the XSD schema.

COMP-1, COMPUTATIONAL-1 The Plug-in converts the data element with this usage to thefloat type in the XSD schema.

COMP-2, COMPUTATIONAL-2 The Plug-in converts the data element with this usage to thedouble type in the XSD schema.

Note: The Plug-in supports both IEEE 754 and IBMhexadecimal floating point representations. For details, see Handling of Floating Point Items.

FUNCTION-POINTER The Plug-in converts the data element with this usage to theint type in the output XSD schema.

INDEX

POINTER

PROCEDURE-POINTER The Plug-in converts the data element with this usage to thelong type in the output XSD schema.

11


Supported Picture Types

Picture Type Example Notes

Alphabetic PIC AAA PIC A(12) The Plug-in converts the data element with thispicture type to the string type in the outputXSD schema.Alphanumeric PIC XX PIC X(10)

Alphanumeric-edited PIC XX/XX/XX PIC

XXXBX(3)BX(4)

Numeric-edited PIC 99/99/99 PIC

-9(7).99 PIC +,++

+,999.00

By default, the Plug-in converts the dataelement with this picture type to the stringtype in the output XSD schema. However, youcan select a numeric type on the FieldConfiguration page of the Copybook resource.See Handling of Numeric-Edited and ExternalFloating-Point Items and Field ConfigurationPage.

External Floating Point PIC +99.9999E+99

PIC -9.99999E-99

By default, the Plug-in converts the dataelement with this picture type to the xs:doubletype in the output XSD schema. However, youcan select string on the Field Configurationpage of the Copybook resource. See Handling ofNumeric-Edited and External Floating-PointItems and Field Configuration Page.

Numeric PIC 999 PIC 9(5)

PIC S9(8) PIC

S9(5)V99

If a picture of data element contains a decimalpoint, the Plug-in converts the clause to thedecimal type in the output XSD schema.Otherwise, the conversion is made to one ofthese six integer types in the output XSDschema: short, int, long, unsignedShort,unsignedInt, or unsignedLong.

If the picture contains the sign character, theconverted-to type is a signed integer type.Otherwise, it is an unsigned integer type.

Supported COBOL Clauses and Features

Clause Notes

DATE FORMAT This clause specifies that an item is a date field. For details, see DATE FORMATClause.

OCCURS This clause specifies that the data element defined with the OCCURS clause is afixed-length table.

OCCURS …

DEPENDING ON

This clause specifies that the data element defined with the OCCURS ...DEPENDING ON clause is a variable-length table. For details, see OCCURS …DEPENDING ON Clause.

12


Clause Notes

REDEFINES This clause specifies that two or more items occupy the same storage. The Plug-inconverts the items defined with the REDEFINES clause and the redefined item to achoice element in the output XSD schema.

Note: Each redefined and redefining item must have a fixed length. UsingOCCURS...DEPENDING ON in those items results in an error.

SIGN This clause specifies the position and mode of representation of the operationalsign for the signed numeric item. The Plug-in selects an appropriate XSD type forthe item with this clause.

SYNCHRONIZED This clause specifies an elementary item’s alignment on a natural boundary instorage. For more information, see SYNC Clause and Slack Bytes.

VALUE This clause specifies a data item’s initial content. The VALUE clause is reflected inthe XSD schema. The Render Copybook Data activity generates that value foritems whose values are not specified in the input data.

DATE FORMAT Clause

The COBOL DATE FORMAT clause specifies that a data item is a date field.

COBOL date patterns are mapped to ActiveMatrix BusinessWorks Java date patterns. The day-first ormonth-first option is determined by the state of the Day/Month Order field in the Settings page of theCopybook resource.

COBOL Data Pattern

Java Date Pattern

Day First Month First

XX dd MM

XXYY MMyy MMyy

XXYYYY MMyyyy MMyyyy

XXX DDD DDD

XXXYY DDDyy DDDyy

XXXYYYY DDDyyyy DDDyyyy

XXXX ddMM MMdd

XXXXYY ddMMyy MMddyy

XXXXYYYY ddMMyyyy MMddyyyy

YY yy yy

YYXX yyMM yyMM

13


COBOL Data Pattern

Java Date Pattern

Day First Month First

YYXXX yyDDD yyDDD

YYXXXX yyddMM yyMMdd

YYYY yyyy yyyy

YYYYXX yyyyMM yyyyMM

YYYYXXX yyyyDDD yyyyDDD

YYYYXXXX yyyyddMM yyyyMMdd

The Plug-in does not support date-format patterns that are not specified here. For example, X, YYY, andYYYYX are not supported.

OCCURS … DEPENDING ON Clause

The COBOL OCCURS … DEPENDING ON clause defines a repeating data element whose number ofoccurrences is determined by a numeric item. The Plug-in converts this type of element to a repeatingelement in the XSD.

The syntax of the OCCURS ... DEPENDING clause is as follows:

OCCURS min TO max TIMES DEENDING ON object

In the XSD schema, items with OCCURS ... DEPENDING ON contain the setting maxOccurs = max.However, the schema does not set minOccurs.

Rendering

The number of occurrences rendered is determined by the value of object in the input XML before theitem. The number of supplied occurrences need not match the value of object. Note the following rules:

● If the value of object is greater than the number of occurrences, the Plug-in adds empty elements. Ifthe VALUE clause is specified, the Plug-in initializes the elements accordingly.

● If the value of object is less than the number of occurrences, the Plug-in does not render the extraoccurrences.

● If the value of object is not in min:max range, the Plug-in throws a SerializationExceptionexception.

Parsing

During parsing, the number of occurrences is determined by the value of object in the binary data. If thevalue of object is not in the min:max range, the Plug-in generates an error.

14


The DEPENDING ON clause object that defines the actual number of occurrences does not have to be ofeither an integer or short type. The number of occurrences is determined without errors if the actualvalue (after parsing or before rendering) can be converted to an integer. For example, a PIC X(4) fieldwith the value 0003 means three occurrences. If the value cannot be converted to a number, then anerror occurs.

The Plug-in always trims white spaces before further processing. For example, a PIC X(4) field withthe value “ 3” yields three occurrences.

If a field in the OCCURS ... DEPENDING ON clause is a repeating field, the value for determining theactual number of occurrences is the last value processed before the OCCURS ... DEPENDING ON clause.

Handling of Computation Items

Numeric values in COBOL files are commonly stored in display or character format, that is, as base-10numbers, with each digit represented by the corresponding character. For example, a field defined asPIC 999 that contains the value 123 is stored in three bytes, each byte containing one digit of the value.

When performing computations with numbers, machines can perform the computations significantlyfaster on binary (base-2) numbers than base-10 numbers. Therefore, if a number is stored in a COBOLdata file in binary format, it can be input directly from the file and used in computations. You can usevarious flavors of COMP (such as COMP-3, COMP-4, and so on) to change the storage format from text tobinary form.

COMP Versus COMP-5

For integer fields in COBOL, COMP specifies the storage of half word, full word, or double word (2, 4,and 8 bytes, respectively). However, an additional limitation based on the number of decimal digits inthe PICTURE clause applies.

For instance, even though PIC S9(4) COMP has a signed half-word storage, it limits the values to therange of -9999 though +9999 due to the four decimal places in the PICTURE clause.

To eliminate that limitation, use COMP-5. This usage, though the same as COMP, allows the whole rangeof values representable by a particular number of storage bytes. For example, PIC S9(4) COMP-5 has ahalf-word storage and allows the range of values of -32768 though +32767.

For more details, see the COBOL documentation.

COMP-6

COMP-6 is a feature of Micro Focus COBOL. The Plug-in considers it synonymous to PACKED-DECIMAL.

COMP-6 is only supported as PACKED-DECIMAL. Other interpretations are not supported.

Handling of Names

FILLER is a special name in COBOL. These fields cannot be referenced from a COBOL program and areallowed to occur more than once, because these names do not have to be unique in a copybook.

The Plug-in applies the following processing:

● Copybook items are not required to have unique names. However, if non-unique names areencountered at the same group level or at the top the level, the Plug-in generates unique XSD namesby adding numeric suffixes '-n'. For example, for this copybook:01 ROOT. 02 ITEM PIC X. 02 ITEM PIC X.

The XSD name of the first elementary item is ITEM, but the second item is named ITEM-0.

15


● The Plug-in allows unnamed items. In this case, the XSD name is NO-NAME. If many unnameditems are present at the same group level or at the top the level, the names are made unique byadding numeric suffixes '-n': NO-NAME-0, NO-NAME-1 and so on.

Handling of Numeric-Edited and External Floating-Point ItemsNumeric-edited and external floating-point items in COBOL are numeric items that are represented asformatted text, which is formed according to the PICTURE clause editing rules. You can select theprocessing type to apply in a Copybook resource’s Field Configuration page.

Rules

In the XSD Type column of the Field Configuration page, each numeric-edited item contains the valuestring and a numeric type appropriate for the item’s PICTURE clause. Note these rules:

● If you select string, the Plug-in processes the item as a string and does not validate its content. TheTrim Whitespaces from String Values setting of the Parse Copybook Data activity and the FillerCharacter setting of the Render Copybook Data activity are in effect.

● If you select a numeric XSD type, PICTURE clause editing and deediting are in effect. The Plug-inconverts the string’s text content to a number during parsing and a number to text during renderingaccording to the PICTURE clause’s editing rules.

If the text content of the item do not conform to the PICTURE clause, the Parse Copybook Dataactivity fails.

● The Character Set settings are always in effect.

● The XSD type string is selected by default for numeric-edited items. double is selected by defaultfor external floating-point items.

Exercise caution with the string type. Because the Plug-in performs no validation duringrendering, you might inadvertently supply malformed data to a COBOL program, whichmight lead to an abend or data corruption that might be difficult to track.

Validation

If you select a numeric XSD type, the Plug-in validates the field’s text content during parsing. Anydeviations from the format in the PICTURE clause lead to activity failures.

For example, the value 123 45, for an item with PICTURE 999.99 fails because of the missing decimalpoint in the position number 4.

In many cases, COBOL applies no or minimal validation to the text data of numeric-edited items. If youfind the strict validation that the Parse Copybook Data activity applies to be undesirable, select the XSDtype string or base64Binary in the Field Configuration Page.

The Plug-in also validates the VALUE clause against PICTURE. In case of a mismatch, the Plug-in discardsthe VALUE clause.

Numeric Items with Scaling Position PNumeric items can contain character P in the PICTURE clause. These characters can be present as acontinuous sequence at the beginning or end of PICTURE.

When located at the beginning of the clause, the P character indicates a decimal point followed byzeroes. For example, PIC PPP9 describes values 0.0001 , 0.0002 and so on.

When it is displayed at the end of the clause, the P characters indicate a number of zeroes at the end of avalue. A decimal point is presumed at the end of a value. For example, PIC 9PPP describes values1000 , 2000 , and so on.

The storage size is unaffected by P, and the zeroes are not stored but rather are implicitly added to theactual algebraic value during mathematical operations, MOVE operations, and so on.

16


The Plug-in adds the zeroes as well, so that ActiveMatrix BusinessWorks processes see the impliedalgebraic value. The XSD schema uses a type and constraints that account for the zeroes.

Specifically:

● The Parse Copybook activity adds zeroes to the output values and returns an algebraic value.

● The Render Copybook Data activity accepts an algebraic value and removes zeroes at P positions.

● A BusinessWorks process is free to pass a value that contains non-zero digits at a P position, but theXSD schema does not have enough constraints to validate that. However, if this happens the RenderCopybook Data activity throws an exception to avoid loss of data. If a truncation is desirable,perform it prior to passing data to a Render Copybook activity.

● Characters P in COMP-5 items are not supported. They are ignored and such items are treated asregular unscaled COMP-5 items. The VALUE clause for such items is ignored.

SYNC Clause and Slack BytesBinary items that are aligned at natural storage boundaries might perform better than items that are notaligned. COBOL provides two alignment related features.

SYNC clauseThis clause ensures that the item is placed at the next natural boundary, if applicable. The COBOLcompiler achieves that by inserting slack bytes before the item.

Top-level itemsThe compiler always places top-level copybook items at a double-word (8-bytes) boundary. Forexample, if your copybook contains more than one item at the top level, then there might be a gap infront of the second and the following items:01 TOP-LEVEL1. 02 ....01 TOP-LEVEL2. 02 ...01 TOP-LEVEL3. 02 ...

In the above, TOP-LEVEL2 and TOP-LEVEL3 are always pushed to the following 8-byte boundary,which might result in unused bytes in front of these items.

Insert Slack Byte Items Menu Item

The plug-in ensures correct placement of SYNC items. It also provides a feature that generates newdata items to occupy the slack bytes between SYNC items.

The Insert slack byte items menu item is available on the Copybook Schema resource:

For an example of how this menu item modifies the copybook body, consider this copybook asdisplayed before the Insert slack byte items menu item is used:01 TOP-LEVEL1. 02 TEXT PIC X. 02 COMP-ITEM PIC S9(10) COMP SYNC

17


The SYNC clause in the COMP-ITEM item adds three slack bytes in front the item. However, you haveno access to those bytes. If you would like to be able to manipulate their values as well as the values ofTEXT and COMP-ITEM, click the Insert slack byte item menu item.

Your copybook then becomes:01 TOP-LEVEL1.02 TEXT PIC X.*** Slack bytes before COMP-ITEM 02 SLACK-BYTES0 PIC X(3).*** 02 COMP-ITEM PIC S9(10) COMP SYNC.

The new layout is fully compatible with the original copybook. The TEXT and COMP-ITEM lines arestill located at the same offsets, but you now have access to the slack bytes that were previouslyinaccessible. However, if you modify PICTURE or USAGE clauses of SLACK-BYTES0, that mightchange the placement of COMP-ITEM.

This feature does not add definitions between top-level items. Doing so would render the layoutincompatible because the new items would be positioned at the 8-byte boundary.

If needed, you can access those slack bytes by adding another top-level item with the REDEFINE clauseand a larger size.

Alignment Compatibility with Previous Releases

Plug-in versions prior to 4.2.0 (and 3.x versions prior to 3.4.0) did not strictly adhere to alignmentspecification of the COBOL compiler. Version 4.2.0 (as well as 3.4.0), while consistent with the compiler,might position items differently than in previous releases, and so cause errors.

The current release of the Plug-in includes a compatibility setting, Alignment processing, use v4.1 andearlier. This check box is available on the Copybook resource. When selected, it preserves the itemplacements as in previous releases. The Insert slack byte items menu item is not enabled in this mode.Instead, SLACK-BYTES are implicitly added to the copybook as they were in earlier releases.

Copybook resources created with previous releases of the Plug-in have Alignment processing, use v4.1and earlier selected by default. Therefore, existing applications do not change their alignment behavior.However, if you prefer the new behavior, de-select this option, save the resource, and re-deploy yourapplication.

Sign Nibbles in Zoned and Packed Decimal ItemsItems that are zoned, such as PIC S999 or packed decimal, such as USAGE PACKED-DECIMAL orCOMP-3, contain a sign nibble which is half a byte.

There is a small difference in processing the items mentioned previously in zOS system and IBM isystem. On zOS system, positive values in signed items such as PIC S999 contain nibble xC, while onIBM i system, such items contain nibble xF.

During parsing, the plug-in recognizes both variations. However, during rendering, you have to specifywhat flavor of behavior is needed. You can use the IBM i Sign Nibbles check box of the Renderactivity. Select this check box to generate IBM i flavor. Clear the check box to generate zOS flavor.

Unsupported Clauses Features Levels and PhrasesCOBOL clauses, levels, and phrases that are not supported by the Plug-in might be ignored or mightresult in an unsupported copybook.

Clause, Feature, Level, or Phrase Notes

Level 66 The Plug-in ignores the data elements defined with the level66 (RENAMES clause).

18


Clause, Feature, Level, or Phrase Notes

Level 88 The Plug-in ignores the data elements defined with the level88 (VALUE or VALUES clause).

Level 78 Level 78, a Micro Focus COBOL Compiler feature withwhich you can define named constants, does not exist in theIBM Enterprise COBOL compiler. Hence, the Plug-in doesnot support Level 78 and generates an error.

BLANK WHEN ZERO The Plug-in ignores this clause.

EXTERNAL

GLOBAL

JUSTIFIED

Nested copybooks The Plug-in does not support copybooks that contain theCOPY directive for other copybooks.

OCCURS clause

● ASCENDING

● DESCENDING

● INDEXED

● KEY

The Plug-in ignores these phrases for the OCCURS clause.

SYNCHRONIZED clause

● LEFT

● RIGHT

The Plug-in ignores these phrases for the SYNCHRONIZEDclause and presumes LEFT.

USAGE clause

● NATIVE

● OBJECT REFERENCE

The Plug-in ignores these phrases for the USAGE clause.

PL/I FeaturesYou can import a file that contains PL/I data definition into a Copybook resource.

The PL/I functionality of the Plug-in has been tested against Enterprise PL/I for z/OS Version 3, Release6 (5655-H31). Other compilers might produce incompatible data layouts.

A PL/I program might contain a mix of DECLARE statements and other language constructs. Eventhough the Plug-in processes DECLARE statements only, the imported file can contain other programelements. In the following example—DECLARE 1 DATA_STRUCT, 2 FLD1 FIXED BINARY(31), 2 FLD2 FIXED BINARY(31);PRINT_DATA:PROCEDURE;

19


PUT SKIP EDIT (' FLD =', DATA_STRUCT.FLD) (A,A);END PRINT_DATA;

—DATA_STRUCT is a data declaration; PRINT_DATA is a procedure. The Plug-in processes DATA_STRUCTand ignores PRINT_DATA.

Declarations and AttributesPL/I DECLARE statements might contain various attributes. Not all are relevant to the processingperformed by the Plug-in. In addition, this release of the Plug-in does not support all PL/I features.

Unsupported Attributes

The Plug-in does not support the following attributes:

AREA HANDLE ORDINAL

ENTRY LABEL PICTURE

FILE LIKE TASK

FORMAT OFFSET

The Plug-in does not support major structures or fields that contain the above attributes. If the Plug-inencounters any of those attributes, it excludes their fields or structures from the XSD schema andgenerates a warning message.

Omission of fields or structures causes a change in the binary layout. Be sure to carefully review thedata definitions.

Ignored Attributes

The following attributes are allowed but have no effect on the operation of the Plug-in:

BASED EXTERNAL and INTERNAL

CONNECTED and NONCONNECTED RESERVED

DEFAULT STATIC

DEFINED TYPE

PL/I allows declaration of variables to without any data attributes and assigns numeric attributes tothose variables.

The Plug-in requires a complete specification of data attributes with one exception: For BINARY orDECIMAL without FLOAT or FIXED specified, the Plug-in applies FIXED.

Data FactoringPL/I supports several flavors of attribute factoring in the DECLARE statement. Factoring enablesgrouping of variable names and attributes.

For example:declare (A,B,C,D) binary fixed (31);declare (E decimal(6,5), F character(10)) static;declare 1 A, 2(B,C,D) (3,2) binary fixed (15);declare ((A,B) fixed(10),C float(5)) external;

20


The Plug-in only supports these two factoring flavors:● The following declares three level 1 variables a, b, and c:

dcl (a, b, c) fixed bin(10);

● Each variable can have a level number, for example:

dcl 1 root,

(2 a, 2 b) fixed bin(31);

The above declares a major structure, root, with level 2 variables a and b.

* NamesPL/I allows * as a structure or field name for items that are not accessed in a PL/I program.

The Plug-in includes those names in the schema as _star1, _star2, and so on. For example, consider thisdeclaration:DECLARE 1 ROOT, 2 TXT_FLD CHAR(10), 2 * CHAR(10), 2 * FIXED BIN(31);

The variables _star1 and _star2 are the same as regularly named variables and you can create mappingswith them. However, a PL/I program cannot access them.

Data ConstructsThe Plug-in can interpret several types of data constructs that are offered by PL/I.

● Structures

● Unions

● Single or multidimensional arrays

Arrays

The Plug-in represents arrays as groups of repeating elements. To improve the readability of XML data,the Plug-in converts an array into a top-level element and a repeating element named Item.

For an array that contains multiple dimensions, the Plug-in depicts each dimension as a nested,repeating Item element.

Unions

The Plug-in presents unions as choice elements, which you manage through the Field Configurationpage.

For details, see Field Configuration Page.

Each union member must have a fixed length. Using REFER in array boundaries or string lengths on anylevel inside a union results in an error.

The REFER Option

In PL/I, you can describe self-defined length variable in string lengths and array boundaries with theREFER option.

The syntax is:

expression REFER (member-variable)

where:

● expression is the expression that defines the actual length of a string or a value of an array bound.

21


● member-variable is a field in the structure before the REFER option. This field, which contains thevalue of the expression, can be used by the PL/I program to access the actual string length or anarray boundary.

In PL/I, expression is not limited to numeric constants and can be any expression that is evaluated bythe PL/I program if the structure is allocated. The Plug-in does not impose any additional requirementsand allows all valid expressions.

In this example, TXT_FIELD is a field of 10 characters and LEN_VAR contains 10:DECLARE 1 ROOT, 2 LEN_VAR FIXED BIN(31), 2 TXT_FLD CHAR(10 REFER(LEN_VAR));

In this example, ARRAY is an array of 10 items and LEN_VAR is set to 10:DECLARE 1 ROOT, 2 LEN_VAR FIXED BIN(31), 2 ARRAY(10 REFER(LEN_VAR)) FIXED BIN(15);

In this example, ARRAY is an array of eight items (ARRAY(3) through ARRAY(10)); LEN_VAR1 contains thevalue 3; and LEN_VAR2 contains the value 10:DECLARE 1 ROOT, 2 LEN_VAR1 FIXED BIN(31), 2 LEN_VAR2 FIXED BIN(31), 2 ARRAY(3 REFER(LEN_VAR1) : 10 REFER(LEN_VAR2)) FIXED BIN(15);

The Plug-in processes the REFER option as follows:

● During parsing:

— For strings, the Plug-in calculates the number of characters according to the member-variablevalue in the binary data.

— For arrays, the Plug-in calculates the number of items according to the values of REFER member-variable specified in array bounds in the binary data.

— member-variable, which is in the XML output of the parse activity, can be used in mappingsalong with the variable-length field itself.

● During rendering—

— The Render activity expects member-variable to be set to a value that is consistent with thereceiving PL/I program.

Be sure not to exceed the actual allocation size of the element that receives data in the PL/I program.

● For strings, the Plug-in calculates the number of characters according to the member-variable valuesupplied through mapping. If the actual value of the string is shorter, member-variable stipulates thatthe string is padded.

● For arrays, the Plug-in calculates the number of items according to the values of the membervariables specified in array bounds and supplied through mapping. If the actual number of items inthe input XML is smaller, the Plug-in adds empty items. If INITIAL is specified, the Plug-ininitializes those items accordingly.

A difference exists in how errors are processed in strings and arrays during rendering. The followingrules apply:● If a string value supplied through mapping is longer than the calculated length, the Plug-in

considers that a runtime error and throws SerializationException.

● The number of array items in the mapping can exceed the number that is calculated on the basis ofthe member variables. In that case, the Plug-in renders only the REFER-based number of items andignores the rest.

22


Data Types

Data Type Notes

FIXED BINARY

(precision, scaling)The Plug-in represents signed fields as elements of XSD type byte, short,int, long, unsignedByte, unsignedShort, unsignedInt or unsignedLongdepending on precision and SIGNED or UNSIGNED attributes.

The Plug-in represents fields with the COMPLEX attribute as base64Binary.For details, see COMPLEX Attribute. If base64Binary is used, the XMLvalues are the unmodified binary content that is not affected by any otherPlug-in settings.

For non-COMPLEX fields, the Big Endian setting of an activity is in effect.

Precision greater than 63 for signed fields and 64 for unsigned variables isnot allowed and causes an error.

Warning: The Plug-in does not support nonzero scaling factor, whichcauses an error.

The endian type is defined by BIGENDIAN or LITTLEENDIAN attribute in thedefinition or, if those attributes are not in the definition, by the activity’s BigEndian setting.

FIXED DECIMAL

(precision, scaling)The Plug-in represents fixed decimal fields as elements of XSD type byte,short, int, long or decimal depending on precision and scaling.

Fields with the COMPLEX attribute as base64Binary. For details, see COMPLEX Attribute.

Warning: The Plug-in does not support negative scaling factor or a scalingfactor that is greater than precision. Hence, the following declarationswould cause an error:DECLARE A FIXED DECIMAL(5, -1);DECLARE A FIXED DECIMAL(5, 6);

23


Data Type Notes

BINARY FLOAT

(precision)BINARY FLOAT fields can be of IEEE or IBM hexadecimal type asdetermined by IEEE or HEXADEC attributes in the data declaration. If youspecify neither of those attributes, the setting of the Floating Point field ofthe Copybook resource is in effect.

Note: Select IEEE for Floating Point when compiling your PL/I programwith the DEFAULT(IEEE) option.

For IEEE fields, the representation is as follows:

● float if the precision is less than or equal to 21.

● double if the precision is less than or equal to 53.

● base64Binary for greater precision values.

For hexadecimal fields, the representation is always base64Binary. ThePlug-in also represents fields with the COMPLEX attribute asbase64Binary. For details, see COMPLEX Attribute. If base64Binary isused, the XML values are the unmodified binary content that is notaffected by any other Plug-in settings.

If float or double is used, the Big Endian setting of an activity is ineffect.

Warning: The Plug-in produces the floating field length consistentlywith Enterprise PL/I for z/OS Version 3, Release 6. Other compilersmight calculate the length differently.

DECIMAL FLOAT

(precision)The Plug-in represents this data type as base64Binary. The XML values arethe unmodified binary content of a field that is not affected by any otherPlug-in settings.

Warning: The Plug-in produces the floating field length consistently withEnterprise PL/I for z/OS Version 3, Release 6. Other compilers mightcalculate the length differently.

CHARACTER(length) The Plug-in represents this data type as string. One character isrepresented by one byte and the character set for conversion between XMLand binary content is determined by an activity’s Character Set setting orthe forceCharacterSet value supplied through input mapping.

GRAPHICS(length) The Plug-in represents this data type as base64Binary, 2 bytes per graphiccharacter.

24


Data Type Notes

WIDECHAR(length) The Plug-in represents this data type as string, with one characterrepresented by two bytes. The encoding for conversion between stringand binary data is defined by the endian type of the fields.

The endian type is defined by BIGENDIAN or LITTLEENDIAN attribute in thedefinition or, if you do not specify those attributes, by the activity’s BigEndian setting.

For Big Endian, the encoding is UTF-16LE; for Little Endian, UTF-16BE.

Note: Binary representation of CHARACTER, GRAPHICS, or WIDECHAR stringswith the VARYING attribute begins with a 2-byte-length prefix. The prefix’sendian type depends on the BIGENDIAN or LITTLEENDIAN attribute in thedefinition or, if you do not specify those attributes, by the activity’s BigEndian setting.

BIT(length) The Plug-in represents this data type as base64Binary. The XML values arethe unmodified binary content of a bit string, where each byte contains 8bits.

Warning: The Plug-in does not support bit strings with a length that is notdivisible by 8. Such a length causes an error.

POINTER This data type is equivalent to UNSIGNED FIXED BINARY(32).

COMPLEX Attribute

Special rules apply for the COMPLEX attribute.

● The Plug-in represents numeric fields that contain COMPLEX in their declarations as base64Binary inthe schema.

● The COMPLEX attribute doubles the storage size of a field.

● The XML values of the fields contain the unmodified binary content and the BIGENDIAN andLITTLEENDIAN attribute settings do not affect those values.

INITIAL Attribute

If you do not specify a mapping, the Plug-in renders the values in the INITIAL attribute, which supplythe initial values for a field. The PL/I compiler does not require that the constant type in INITIALcorrespond to the field type. Instead, a runtime conversion occurs, possibly raising an error.

The Plug-in does not process all combinations of data types and constant types. Although all othercombinations are allowed, they cause the Plug-in to ignore the INITIAL attribute. Only thecombinations described here are processed.

Supported Combinations

Data Type Supported Constant Type in INITIAL Attribute

FIXED BINARY POINTER Decimal fixed point constant: 455, -1Hexadecimal fixed point constant: '100'XU, 'FFFF_FFFF'XN

The Plug-in ignores INITIAL for COMPLEX fields.

25


Data Type Supported Constant Type in INITIAL Attribute

FIXED DECIMAL Decimal fixed point constant: 455.1, -1

The Plug-in ignores INITIAL for COMPLEX fields.

BINARY FLOAT

DECIMAL FLOAT

The Plug-in ignores INITIAL for these types.

CHARACTER Character constant: "ABC", 'xy''z'Hexadecimal character constant: '11FF00'X

GRAPHICS Graphic constant: '011F'GX

WIDECHAR Character constant: "ABC", 'xy''z'Wide character constant: 'C1C1'WXGraphic constant: '011F'GX

BIT Bit constant: "1100_1010"BOctal bit constant: '40'B3Hexadecimal bit constant: '80F1'B4, "01FF"BX

INITIAL Attribute in Arrays

In PL/I, you can initialize arrays with INITIAL, for example:DECLARE A(3) FIXED BINARY(31) INIT(1, 2, 3);

The Plug-in supports this initialization.

Data Alignment

In PL/I, data alignment might introduce gaps of unused space into a binary layout to ensure that all thefields are aligned at boundaries, as required by their type and the ALIGNED attribute.

The Plug-in is aware of these gaps and ensures correct parsing and rendering of aligned fields with oneexception: An item that must be placed at a specific boundary cannot follow an item with the REFERoption. For example, this code—DECLARE 1 ROOT, 2 LEN_VAR FIXED BIN(31), 2 ARRAY(10 REFER(LEN_VAR)) FIXED BIN(15), 2 NUM FIXED BINARY(31);

—would cause an error because the FIXED BINARY field NUM, aligned at 4-byte boundary by default,follows a field with the REFER option.

However, in this example—DECLARE 1 ROOT, 2 LEN_VAR FIXED BIN(31), 2 ARRAY(10 REFER(LEN_VAR)) FIXED BIN(15), 2 NUM FIXED BINARY(31) UNALIGNED;

—NUM is declared as unaligned and is allowed by the Plug-in.

Certain types, such as CHARACTER, do not have a requirement for alignment. In those cases, the ALIGNEDattribute has no effect. For example, the following code does not cause an error even though the field CHcontains the ALIGNED attribute:DECLARE 1 ROOT, 2 LEN_VAR FIXED BIN(31), 2 ARRAY(10 REFER(LEN_VAR)) FIXED BIN(15), 2 CH CHAR ALIGNED;

26


RPG FeaturesYou enable the RPG language by choosing the RPG option in the Copybook Type drop-down menuunder the Setting tab of the Copybook resource.

The Plug-in’s RPG functionality has been tested against Version 5, Release 4, Modification Level 0, ofIBM WebSphere Development Studio for iSeries (5722-WDS), ILE RPG compiler. Other compilers mightproduce incompatible data layouts.

The Plug-in renders and parses RPG data in the same way as it does for the other supported languages.

The Plug-in supports only valid RPG programs that can be compiled with no errors. Parsing andexecuting invalid RPG programs might result in unexpected outcomes or errors.

Supported RPG Features

● Compiler directives /FREE and /END-FREE

● Specification types D, I, and H

● Definition types DS, S, and blank

● Internal data types A, B, C, D, F, G, I, N, P, S, T, U, and Z

● Subfield length in length notation

● Subfield length in absolute (positional) notation for continuous begin and end positions

● The following keywords:

LIKE and LIKEDS CCSID

QUALIFIED DIM

OCCURS PACKEVEN

TIMFMT and DATFMT

Mapping of RPG Internal Data TypesThe Plug-in maps RPG internal data types to simple XML schema types.

RPG Internal Data Type Simple XML Schema Type

Blank If the decimal is blank: string; otherwise, decimal

A string

B If the length is 4 or less, short; otherwise, int

C string

D date

F If the length is 4, float; otherwise, double

Note that these items are presumed to be in the IEEE-754format in the binary data.

27


RPG Internal Data Type Simple XML Schema Type

G string

I If the length is 3, byteIf the length is 5, shortIf the length is 10, intIf the length is 20, longIf the length is blank, int

N string

P decimal

S decimal

T time

U If the length is 3: unsignedByte

If the length is 5: unsignedShort

If the length is 10: unsignedInt

If the length is 20: unsignedLong

If the length is blank, unsignedInt

Z dateTime

Unsupported RPG FeaturesThe Plug-in does not support and ignores some RPG features during parsing.

● All compiler directives, except /FREE and /END-FREE● Specification types C, F, O, and P● Externally described structures and subfields (E)● Definition types C, PR, and PI● Length adjustment for the LIKE keyword● Named and figurative constants● The keywords CONST, INZ, OVERLAY● Keywords not mentioned elsewhereThe Plug-in does not support these RPG features, which cause a parsing error:

● Internal data types O and *● The keywords PREFIX and EXTFLD● Subfield length in absolute (positional) notation for overlapping, nonsequential, and discontinuous

begin and end positions

Handling of Items in Binary FormYou can direct the plug-in to represent elementary items in binary format instead of the default XSDtype.

By default, the Plug-in represents elementary items as an XSD type appropriate to the copybookdefinition. For example, the COBOL PICTURE X(10) item is displayed as a string element with the

28


maximum length of 10 in the schema. To handle an elementary item in binary form instead, selectbase64Binary as an XSD type for an item in the Field Configuration page. Subsequently, the Plug-inrepresents the item as a sequence of bytes with no transformation or validation of the data. You canthen apply custom processing to the binary data. For details, see Field Configuration Page.

Note the following rules:

● During rendering of an item with the base64Binary XSD type:

— The base64Binary value must not contain more bytes than the number of bytes that the itemoccupies. Otherwise, the Render Copybook Data activity throws an exception.

— If your base64Binary value contains less bytes than the number of bytes occupied by the item,the Plug-in pads it. The character used as a filler depends on the copybook specifics and FillerCharacter setting of the Render Copybook Data activity. See description of the Filler Characterfield in Render Copybook Data configuration.

— The COBOL VALUE clause and PL/I INIT attribute are not in effect.

● During parsing, the Parse Copybook Data activity always returns the number of bytes that the itemoccupies.

In COBOL, if you are allocating memory with a PIC X(...) item to store nontextual data, be sure to selectbase64Binary as an XSD type.

Dealing with Invalid XML CharactersXML specification defines certain characters as invalid in an XML document. Even though all XML datais Unicode, some characters are illegal.

The legal ranges are expressed by this condition:(c == 0x9) || (c == 0xA) || (c == 0xD) || ((c >= 0x20) && (c <= 0xD7FF)) || ((c >= 0xE000) && (c <= 0xFFFD)) || ((c >= 0x10000) && (c <= 0x10FFFF))

where c is a Unicode code point.

It is important to be aware that BusinessWorks 6.x adheres to this standard and violations cause variouserrors.

● Parse Copybook Data contains the Check String Values for Invalid XML Characters setting. When,it is selected, the activity applies a validity check to the text data retrieved from the binary input. Ifthe check fails, the activity produces ParseCopybookDataException fault with msgCode TIBCO-BW-PALETTE-DATACONVERSION-500044.

If Ignore Invalid Items is selected, an invalid XML character will not cause an error.Instead, the text item containing the character will be excluded from the output.

In Parse Copybook Data the character validation is only applicable to items represented by XSDtype string. Other items undergo type-specific checks that are more restrictive. These check are notaffected by Check String Values for Invalid XML Characters

● Render Copybook Data contains the Fail on Invalid XML Characters setting. The setting onlyapplies when Render Data as is set to String. If an offending character is detected,RenderActivityData is thrown with msgCode TIBCO-BW-PALETTE-DATACONVERSION-500044.

De-selecting Check String Values for Invalid XML Characters or Fail on Invalid XML Charactersmight result in a small performance gain in scenarios that involve large amount of data. However, de-selecting this setting does not eliminate errors. The errors likely happen later in the application and aremore difficult to track. Only de-select these applications if it is guaranteed not to produce the invalidcharacters.

If your application might produce the invalid characters, you can select XSD Type base64Binary for thecopybook items at risk. However, you cannot use string XPath functions.

29


in Parse Copybook Data, you can reduce the errors by selecting Trim Whitespaces from String Values.The trimming is applied before the character validation check and removes some of the undesirablecharacters at the beginning and the end of the values.

Handling of Zoned Decimal ItemsThe Plug-in presents certain COBOL and RPG items as zoned decimal numbers in the binary data.

● For COBOL, such items are of USAGE DISPLAY, a numeric picture clause, and no SIGN SEPARATEclause.

● For RPG, such items contain S in position 40.

The zoned decimal format represents all decimal digits in text — except for the last byte or, in COBOL,possibly the first byte, depending on whether LEADING or TRAILING is in the SIGN clause. That bytecontains both the decimal value and the sign for the whole value. The sign is specified in the first nibble(half byte) and the decimal digit in the second nibble.

The zoned decimal format is one of three variations: EBCDIC, Strict ASCII, and Modified ASCII. ThePlug-in expects a particular format, which depends on the Character Set setting or forceCharacterSetinput field for the Render Copybook Data or Parse Copybook Data activity. For details on the relatedconfigurations, see Data Conversion Palette.

EBCDIC Character Sets (Such As Cp037)The Parse Copybook Data activity expects EBCDIC-zoned decimal format and fails if it encounters anyof the ASCII format data.

The EBCDIC-zoned decimal format uses EBCDIC codepoints for digits and defines the following signnibbles for the sign byte:

● xC and xA — Sign positive

● xB and xD — Sign negative

The Parse Copybook Data activity accepts positive and negative nibbles for signed items (with S in thePICTURE clause for COBOL) and xF for both signed and unsigned items. Note that signed nibbles arenot valid in an unsigned item.

The Render Copybook Data activity generates the signed nibbles xC and xD for positive and negativesigned data, respectively. For unsigned data, the activity generates xF.

The ASCII Zoned Format dropdown and the input field asciiZonedFormat settings are disregarded.

ASCII Character SetsThe Parse Copybook Data activity accepts both Strict ASCII and Modified ASCII. Both formats useASCII codepoints for decimal digits but represent the sign byte differently. In Strict ASCII, a nibblevalue of x3 denotes a positive value; x7, a negative one.

Strict ASCII and Modified ASCII represent positive signed and unsigned values in the same way.Modified ASCII does not have predefined nibbles. See the table on Modified ASCII Sign Bytes below.

For COBOL copybooks, the Render Copybook activity can generate both strict and modified ASCIIformats. You can specify the desired format in two ways:

● Use ASCII Zoned Format dropdown list on a Render Copybook Data activity to specify a format.

● Pass strict or modified to the input field asciiZonedFormat. This field takes precedence over theASCII Zoned Format dropdown.

For PL/I and RPG copybooks, Strict ASCII is generated.

30


If the input data for the Parse Copybook Data activity does not conform to the expected format, anerror occurs during execution.

In COBOL, if an item contains SIGN SEPARATE, the Plug-in represents the data as text in the selectedcharacter set with the character + or -.

Modified ASCII Sign Bytes

Sign Byte Sign of Entire Value Decimal Digit in Sign Byte

0x7B Positive 0

0x41 Positive 1

0x42 Positive 2

0x43 Positive 3

0x44 Positive 4

0x45 Positive 5

0x46 Positive 6

0x47 Positive 7

0x48 Positive 8

0x49 Positive 9

0x7D Negative 0

0x4A Negative 1

0x4B Negative 2

0x4C Negative 3

0x4D Negative 4

0x4E Negative 5

0x4F Negative 6

0x50 Negative 7

0x51 Negative 8

0x52 Negative 9

31


Handling of Floating Point ItemsYou can configure floating point items to use either the IBM Hexadecimal format or the IEEE 754format. The format is selected in the Copybook resource.

IEEE-754 and IBM Hexadecimal are two distantly different floating point formats. IBM hexadecimal isthe format most commonly used on IBM mainframe computers. IEEE-754 is used by many otherhardware platforms and software systems, including the Java virtual machine. The XML specification isalso geared towards IEEE-754. Additionally, TIBCO ActiveMatrix BusinessWorks uses IEEE-754.

There are inherent differences in the degree of precision and the magnitude of the exponent offered bythese two formats. The differences are:

● IBM float and double formats use a 7 bit exponent value that represents an exponent of base 16.

● IEEE formats use 8 bits for float and 11 bits for double that represents an exponent of base 2.

● The remaining bits in both formats are used for precision so there are commensurate differences inthe degree of precision available.

The plug-in is capable of processing IBM hexadecimal format. This functionality is available for COBOLonly and is enabled using the Floating Point field in the Copybook resource.

PL/I copybooks can also contain IBM hexadecimal items as determined by Floating Point field and IEEEor HEXADEC attributes in the copybook text. However, hexadecimal items are presented asbase64Binary, so the conversion described below is not in effect. For details, see BINARY FLOAT(precision) in Table 8, PL/I Data Types, on page 25.

For PRG copybooks F items are always processed as IEEE-754 and Floating Point field is not shown onthe schema resource.

Conversion Details

When you select IEEE in the FLoating Point field and the copybook type is COBOL, the plug-inassumes that the binary contents of COMP-1 and COMP-2 items are in IBM hexadecimal format.Subsequent Parse activities convert from IBM hexadecimal to IEEE-754, and return these values as XMLfloat or double items. Render activities perform the reverse operation.

Because of the inherent differences between these formats, it is important to keep the following rulesunder consideration:

● If an overflow or underflow occurs when converting the exponent in either direction, the “Not aNumber” or NaN value is returned.

● These special values are mapped between the two formats: POSITIVE_INFINITY,NEGATIVE_INFINITY or NaN.

● When converting the fraction component of a number, precision is lost because some of the rightmost bits might be truncated. This is known as no rounding policy.

● If the loss of precision results in a zero fraction, zero is returned with no exponent value.

● The sign is maintained across all translations.

It is also important note that the above-mentioned losses in precision can be compounded by similarlosses in the conversions between IEEE-754 and XML. Wherever possible, choose a format with ampleprecision for your application. For example, if you are likely to push the limits of the Float format,choose Double where you are able.

32


Latin Normalization in Character Sets

In Unicode, you can express Latin characters, including letters, commas, and so forth, in two valueranges.

● The commonly used Unicode range 0021-007E, called canonical in this guide

● Full-width Latin, which is Unicode range FF01-FF5E

Full-width Latin characters have wider glyphs, which make the characters look more natural when theyare used together with characters in certain Asian languages.

Also, the Unicode space character exists in two forms:

● Space character 0020, called canonical in this guide

● IDEOGRAPHIC SPACE (value 3000), which is a full-width version

Some character sets are available in two forms, for example, CCSID 300 and CCSID 300 with latinnormalization. Those forms apply to character sets that, instead of containing the conventional Latincharacters, have their full-width equivalents.

During rendering, the character set named XXX with latin normalization applies additionalprocessing to the data before obtaining bytes according to the specification for the character set XXX.That is, a conversion from the canonical Latin range to full-width range occurs.

Similarly, during parsing, the character set XXX with latin normalization converts full-width Latincharacters to canonical Latin characters after obtaining the characters from the byte content accordingto the specification for the character set XXX.

Note: The Plug-in also converts the space characters between canonical and full-width versions in thesame manner as it does for Latin characters.

If the character set you intend to use is available in two forms, your choice likely depends on theintended recipient of the data. Here are the considerations:● If you are parsing data that might contain Latin characters, the character set with Latin

normalization lends better interoperability with systems and components that are more suitable forthe canonical Latin data. For instance, some Windows fonts might not have glyphs for full-widthLatin characters and might hence cause the display of full-width Latin characters as blocks.

● If you are preparing data for a legacy program or component that specifically requires full-widthLatin, the character set that does not perform Latin normalization would be a more appropriatechoice.

33


Data Conversion Palette

This section describes the capabilities of the Data Conversion palette.

Copybook ResourceThe Copybook resource is a shared configuration resource that describes the schema that is in effectwhen the Plug-in parses or renders COBOL, PL/I, or RPG data. Through that resource, you can load acopybook file by clicking the Import Copybook button.

Settings PageSome fields under the Settings page apply only to specific languages, as indicated by the COBOL (C),PL/I (P), and RPG (R) columns.

General Section

Field Description

Package The name of a package that contains this resource.

Name The name of the resource label.

Description A short description of the copybook resource.

Settings Section

Field

LiteralValue/ModuleProperty? Description C P R

Copybook Type No The copybook type COBOL, PL/I, or RPG. x x x

File Encoding No The encoding of the copybook content. Thisfield is in effect when you import a copybook(see Import Button) and save its content to afile (see Copybook Page).

x x x

Day/Month Order No The order of the day and month in all the DATEFORMAT XXXX patterns for this copybook.

x

Default Date Format No The DATE FORMAT pattern to apply whenconverting the XML schema date type to aCOBOL copybook’s DATE FORMAT clause.

x

34


Field


Floating Point No For COBOL: floating point format for COMP-1and COMP-2.

For PL/I: The default value for HEXADEC orIEEE floating- point attributes.

Note: The resources containing COBOLcopybooks and created with versions of theplug-in prior to 3.2.0 default to IEEE in orderpreserve existing application behavior.

For details, see Handling of Floating PointItems .

x x

TRUNC(BIN) No When using the TRUNC(BIN) compiler option,all binary (COMP) sending fields are treated aseither halfword, fullword, or doublewordvalues, depending on the PICTURE clause.Code is generated to truncate all binaryreceiving fields to the corresponding halfword,fullword, or doubleword boundary (base 2truncation). The full content of the field issignificant.

x

Alignmentprocessing

No Preserves the alignment processing from Plug-in software releases 4.1 and earlier. This settingaffects the slack bytes added due to SYNCclause and placement of top-level items.

See Alignment Compatibility with PreviousReleases.

x

Advanced Section

Field


Namespace No The namespace to be used in a generatedschema file. For details, see Generated SchemaFiles.

x x x

Generate button No Generates a unique namespace. x x x

Schema File No A read only field indicating the location of thegenerated schema file.

x x x

Open button No Opens the generated schema file in the Eclipseschema editor.

x x x

35


You can modify the copybook content in the Copybook resource. For details, see In-Place CopybookEditing.

Copybook PageThe Copybook page displays the copybook that is loaded into the Copybook resource.

Use the following buttons and drop-down menus, as appropriate, to edit the copybook:

● Import● Compare with the original● Options available in the More menu:

— Revert to the original— Generate from a schema... (COBOL only)

— Insert slack byte items (COBOL only)

— Save to a file...

For details, see In-Place Copybook Editing.

Field


Fixed Format No For COBOL, the field that specifies whetherthe content is in fixed or free format:

● If this field is selected, the data is to be inCOBOL fixed format, that is, columns 0-6are reserved for line numbers. The contentis expected to end at or before column 72.

● If this field is deselected, the data can be inCOBOL free format, that is, the COBOLcode can be within columns 0-6 and canspan beyond column 72.

For PL/I, the field that specifies whether thecontent is in fixed or free format. Note thefollowing conditions:

● If you select this field, the declaration is tobe in columns 1-72. Columns beyond 72 arereserved for line numbers.

● If you deselect this field, the declaration canbe located in any column.

x x

Data Element No The data element to be converted into XMLschema.

x x

36


Import Button

Clicking the Import button on the Copybook page displays a dialog box in which you can specify thecopybook file that contains COBOL, PL/I, or RPG data definitions.

The contents of the copybook are parsed. If the parse fails, the errors button activates. Click the buttonto see error details.

Similarly, if there are warnings, the warnings button activates. Click the button to view the warningmessages. If there are no warnings or errors, an inactive No problems button is displayed.

Generate from an XML Schema

The Generate from a schema... button is active only if you select COBOL in the Copybook Type field.Clicking that button displays a dialog box in which you can select an XML schema file to be convertedto a COBOL copybook and placed under the Copybook tab.

Mapping of XML Schema Types to COBOL

The Plug-in maps XML schema types to the COBOL clauses, as shown here.

In this table xs refers any of the three namespaces:

● http://www.w3.org/2001/XMLSchema

● http://www.w3.org/2000/10/XMLSchema

● http://www.w3.org/1999/XMLSchema

Schema Simple Type COBOL Clause

xs:anyType

xs:anySimpleType

xs:anyURI

PIC X(255)

37


http://www.w3.org/2001/XMLSchema

http://www.w3.org/2000/10/XMLSchema

http://www.w3.org/1999/XMLSchema


xs:base64Binary

xs:ENTITIES

xs:ENTITY

xs:hexBinary

xs:ID

xs:IDREF

xs:IDREFS

xs:language

xs:Name

xs:NCName

xs:NMTOKEN

xs:NMTOKENS

xs:normalizedString

xs:NOTATION

xs:QName

xs:string

xs:token

PIC X(...)

xs:boolean PIC X DISPLAY

xs:byte

xs:int

xs:integer

xs:long

xs:negativeInteger

xs:nonPositiveInteger

xs:short

PIC S9(x) COMP

where xs:totalDigits value="x"

PIC S9(default-x) COMP-5

if xs:totalDigits does not exist

See Schema Simple Types for the default values.

xs:date PIC 9(8) BINARY DATE FORMAT x

where x is one of the following default dateformats:

● YYYYXXXX

● YYYYXXX

● XXXXYYYY

● XXXYYYY

38



xs:dateTime

xs:duration

xs:time

PIC X(32)

xs:decimal PIC S9(x-y)V9(y) COMP-3

where:

● xs:totalDigits value="x"

● xs:fractionDigits value="y"

xs:double USAGE COMP-2

xs:float USAGE COMP-1

xs:gDay PIC 9(2) BINARY DATE FORMAT XX

xs:gMonth PIC 9(2) BINARY DATE FORMAT XX

xs:gMonthDay PIC 9(4) BINARY DATE FORMAT XXXX

xs:gYear PIC 9(4) BINARY DATE FORMAT YYYY

xs:gYearMonth PIC 9(6) BINARY DATE FORMAT YYYYXX

xs:nonNegativeInteger

xs:positiveInteger

xs:unsignedByte

xs:unsignedInt

xs:unsignedLong

xs:unsignedShort

PIC 9(x) COMP-5

where x is defined by the following rules:

● x = the value of xs:totalDigits

● x=default-x if xs:totalDigits is not specified

See Schema Simple Types for the default lengthvalues.

Schema Simple Types

This table shows the schema simple types and their default length values.

Schema Simple Type Default Length

xs:byte

xs:unsignedByte

1

xs:short

xs:unsignedShort

4

xs:int

xs:unsignedInt

9

39


Schema Simple Type Default Length

xs:integer

xs:negativeInteger

xs:nonPositiveInteger

xs:long

xs:nonNegativeInteger

xs:positiveInteger

xs:unsignedLong

18

Notes

● If the number of total digits in an integer exceeds 18 and if the Plug-in encounters an unlimitedmaximum occurrence of an element, warning messages are displayed.

● The Default Date Format field value from the Settings page serves as a pattern during theconversion of the XML schema date type into a COBOL copybook DATE FORMAT clause. The validpatterns are YYYYXXXX, YYYYXXX, XXXXYYYY, and XXXYYYY.

● The Plug-in formats the resultant COBOL copybook source code to comply with the fixed-formatrequirements. In addition, the Plug-in replaces underscores and periods in the XML schema nameswith hyphens in the corresponding COBOL copybook data-item names, which the Plug-in formatsin uppercase.

Insert Slack Byte Items Menu Item

The plug-in ensures correct placement of SYNC items. It also provides a feature that generates newdata items to occupy the slack bytes between SYNC items.

The Insert slack byte items menu item is available on the Copybook Schema resource:

For an example of how this menu item modifies the copybook body, consider this copybook asdisplayed before the Insert slack byte items menu item is used:01 TOP-LEVEL1. 02 TEXT PIC X. 02 COMP-ITEM PIC S9(10) COMP SYNC

The SYNC clause in the COMP-ITEM item adds three slack bytes in front the item. However, you haveno access to those bytes. If you would like to be able to manipulate their values as well as the values ofTEXT and COMP-ITEM, click the Insert slack byte item menu item.

Your copybook then becomes:01 TOP-LEVEL1.02 TEXT PIC X.*** Slack bytes before COMP-ITEM 02 SLACK-BYTES0 PIC X(3).*** 02 COMP-ITEM PIC S9(10) COMP SYNC.

40


The new layout is fully compatible with the original copybook. The TEXT and COMP-ITEM lines arestill located at the same offsets, but you now have access to the slack bytes that were previouslyinaccessible. However, if you modify PICTURE or USAGE clauses of SLACK-BYTES0, that mightchange the placement of COMP-ITEM.

This feature does not add definitions between top-level items. Doing so would render the layoutincompatible because the new items would be positioned at the 8-byte boundary.

If needed, you can access those slack bytes by adding another top-level item with the REDEFINE clauseand a larger size.

Schema Preview PageThe Schema Preview page displays a preview of the XSD schema used for parsing and renderingcopybook data.

Field Configuration PageYou tailor various aspects of the Copybook’s behavior in the Field Configuration page.

The columns in the Field Configuration tab are described here:

Column Description

Name This column shows a tree view of the copybook structure. You expand orcollapse the entire tree by clicking the Expand All or Collapse All buttons.

Highlight redefinegroups

This check box turns on color highlighting of redefine groups.

Filter This field applies to the Name column and you can use it to filter the rowsshown in the tree. Two wildcards are allowed:

● ? denotes a single arbitrary character.

● * denotes an arbitrary sequence of characters.

For example, enter UNIT* to show only rows where the value in the namecolumn begins with UNIT.

Type This column displays language-specific information about an item. ForCOBOL, for example, this column display USAGE and PICTURE clauses.

41


Column Description

XSD Type This column displays the XML schema’s XSD type. The following choices areavailable:

● The default type as selected by the Plug-in, such as string for a PICTURE X(...) COBOL item.

● For COBOL, a numeric type if an item has a numeric-edited PICTUREcategory. See Handling of Numeric-Edited and External Floating-PointItems.

● base64Binary. See Handling of Items in Binary Form.

Default Redefine,Control Field, andControl Values

The COBOL REDEFINES clause or a PL/I UNION attribute enables different data-description entries to be located in the same memory area. Such entries areconverted to a choice element in the XSD schema. These three columnsdetermine which element the Plug-in generates while parsing a REDEFINESgroup or UNION.

Note that these columns do not affect rendering.

Configuration of Data-Description Entries for a REDEFINES group Or Union

You can configure the data-description entries for a REDEFINES group or union.

Procedure

1. Assign a data-description entry from the group as the default by selecting Yes in the DefaultRedefine column. The setting maps the data content of storage area to this default data-descriptionentry at runtime.

2. Optional. Assign a data-description entry (known as control field) to the group by clicking

magnifying glass in the Control Field column. At runtime, the value of this control fielddetermines the data-description entry that maps the content of the redefined storage area.

In assigning a control field, you are required to provide a list of control values for fields in theREDEFINES group or UNION. Subsequently, while checking the control field against those values, theactivity outputs that field into the output XML document if the invoked Parse Copybook Dataactivity detects a match.

If the Parse Copybook Data activity detects no matches, it outputs the field that was assigned as thedefault.

If you do not select a control field, the Parse Copybook Data activity outputs the default field.

When you click on a field that belongs to a REDEFINES group or a UNION, all other fieldsand the control field are highlighted.

A control field must precede any of the fields that belong to a REDEFINES group or aUNION. You can select a preceding field only.

Even if you selected a control field, you are not required to assign control values to everyfield of a REDEFINES group or UNION. If control values are not assigned, such a field isnever be generated unless it is selected as the default redefine of the REDEFINES group orUNION. If you do not assign control values to any of fields, the control field has no effect onparsing.

42


Result

For example, the UNIT-PRICE-CONTROL field determines whether the Plug-in generates the ACTUALor CONVERTED field, as follows:

● If the UNIT-PRICE-CONTROL value is actual or a, the Plug-in generates the ACTUAL field.

● If the UNIT-PRICE-CONTROL value is converted or c, the Plug-in generates the CONVERTEDfield.

● If the UNIT-PRICE-CONTROL value is none of above, the Plug-in generates the ACTUAL fieldbecause ACTUAL is the default in the Default Redefine column.

ACTUAL and CONVERTED Fields on the Field Configuration page

Control Values

You specify the control values in a list and separate them with semicolons.

The Plug-in supports three types of control values:

● Text values: ABC, "ABC"

● Bitmask values: "1001"&

● Hexadecimal values: "1FB4"X

All three types can be specified in the same list:

ABC; "1001"&; "1FB4"X

Text Values

You can use a simple text expression or enclose it in single or double quotes.

When a value is enclosed in quotes, the quotes are not considered a part of the value. If you want toembed a quote into a quoted value be sure to repeat the quote twice unless the quote differs from thoseat the beginning and at the end of the value.

Use unquoted values only when

● a value does not include a semicolon

● does not start or end with a space, leading and trailing spaces are not considered a part of anunquoted value.

43


A few examples are shown here. Note that in the Values column, the boldfaced values, not the commasbetween them, are the actual values.

Examples of Control Values in a List

Value List Values

"abc"; 'a' abc, a

"abcd'abcd'xyz" abcd'abcd'xyz

'abcd''abcd''xyz' abcd'abcd'xyz

a;b;c a, b, c

'abc Invalid value because of no closing single quotes

'abc'' Invalid value because of no closing single quotes

● Matching of control fields applies the Trim Whitespaces from String Values setting of the ParseCopybook Data activity. If you select that setting, the activity removes the leading and trailingwhitespaces from the data and from a control-field value before comparison.

● Text values cannot be used if a control field is configured to have XSD type base64Binary

● For Text values, the matching process is type-aware; for example, if your control field is numeric,variations of string representation of a number are acceptable in a control value.

Bitmask Values

The bitmask control values are quoted sequences of 0 and 1 with an ampersand at the end, for example"1001"&.

You use these values to check if bits specified as 1 are set in the byte value of a control field. Control-value bits specified as 0 are not checked.

Note that these checks operate on the raw byte value of the control field. It's copybook data type orother settings have no effect on this process.

The following rules apply:

● Single or double quotes can be used. For example "1001"& and "1001'& are valid and denote thesame bitmask.

● You can use the repetition factor (n) to make your value compact. (n) repeats the following bit ntimes, for example "1(6)01"& is equivalent to "10000001"&

● Spaces are allowed anywhere within quotes. They are ignored.

● Trailing zeroes are allowed, but are ignored. Leading zeroes are meaningful. For example, '10001'&is equal to '1000100000'&, but not equal to '00010001'&

● A bitmask can be shorter than the raw data of a control field. In that case the mask is checkedstarting at the left most bit of the field. The field data following the mask length is not taken intoaccount.

● If a bitmask is longer than a control field, it never produces a match. For example,

01 ITEM PIC X

is never matched by a control value

'1000100011110111'&

44


Hexadecimal Values

Hexadecimal values are quoted sequences of pairs of hexadecimal digits followed by X. For example"1FB4"X.

You use these values to check if the raw binary value of a control field contains specific bytes. Note thatthe copybook type of the field or other settings have no effect on the matching process.

The following rules apply:

● Each byte is represented by two hexadecimal digits 0-F. Only even number of hex digits is allowed.

● Single or double quotes can be used. For example '1FB4'X and "1FB4"X are valid and denote thesame byte value.

● You can use the repetition factor (n) to make your value compact. (n) repeats the following pair ofhex digits n times, for example "01(3)FF02"X is equivalent to "01FFFFFF02"X.

● You can use spaces anywhere within "quotes" . They are ignored. You can use them to make valuesmore readable, for example "01 FF FF FF 02"X

● A hexadecimal control value can be shorter than the byte data of a control field. In that case thebytes are compared starting at the left most byte of the field. The data following the length of thecontrol value is not taken into account.

● If a control value is longer than the control field, it never produces a match. For example

01 ITEM PIC X.

is never matched by a control value

"01 FF FF FF 02"X

Matching Sequence

Some data values might match more than one control value. For example, a control field with a valuexFF matches values '1'& and 'FF'X. In such cases it is important to be aware of the how the overallchecking sequence operates.

● All control values in the list are checked starting with the first value. Once a match is detected, thematching process stops.

● The control value lists are checked starting from the first field in the redefine group. When a value ismatched successfully the matching process stops.

Exercise care when changing the order of redefined items in a copybook.

Consider this example:

An item A with control value 'FF'X precedes item B with a control value '10000001'&. A control fieldvalue xFF results in the item A.

When B is placed before A, a control value xFF always results in B, because value '10000001'& matches abroader range of data and is checked first.

In-Place Copybook EditingOnce you have imported a copybook, the Plug-in stores a copy of it, preserving the original content.You can modify the copybook content directly on the Copybook page of the Copybook resource, afterwhich the Compare with the original and Revert to the original buttons become active.

● Copybook content is parsed and validated in real time as you type.

● Importing a new copybook discards the original copybook and any modified state of that copybook.

● When creating a new resource, the Plug-in does not save a copy of the original copybook contentuntil you have clicked Save for the first time. That way, instead of importing a file, you can type orpaste the copybook content, which then becomes the original.

45


Fields or Buttons for Editing Copybooks

Field or Button Description

Import Displays a dialog box in which you can specify the copybook file thatcontains COBOL, PL/I, or RPG data definitions. See Import Button.

Compare with the original Opens a window that displays the modifications to the originalcopybook. See Difference Viewer.

Revert to the original Reverts the content of the copybook to the original.

Save to a file… Saves the current copybook content to a file.

Difference Viewer

Clicking the Compare with the original button opens the Difference Viewer, which shows the contentdifferences between the current (modified) copybook and the original one. For example:

You can compare and copy all or individual changes from the original content to the current content.You can also navigate up and down the copybook to highlight each difference and change.

Generated Schema FilesCopybook resource generates XSD files. These files are located in Schema\copybook folder in yourproject.

These schema files are used internally by the Plug-in's activities, but you can also use them like anyother schema file:

● In Input/Output Editor of activities that offer those facilities (including Mapper, JMS activities, andso forth).

● In your own schemas by way of the import attribute.

You can't, however, modify these XSD files manually. Their lifecycle is completely managed by thePlug-in. Any external changes to those files are immediately overwritten by the Plug-in, or moresuperficially, the BussinessWorks Copybook Schema Builder attached to a project.

46


It is not necessary to worry about preserving these schema files during export or source controlcommits. The Plug-in re-generates them.

Do not disable BussinessWorks Copybook Schema Builder in your project. If you do, the schema filesare not kept in sync and no error/warning messages are included in the Problems view.

Namespace Considerations

It is possible for your project to contain multiple schemas that use the same namespace. This mightcause errors in your processes and other undesirable effects. With the Copybook resource, you canspecify a namespace that is used in the corresponding copybook schema file. You can use this feature toreconcile namespace conflicts or to provide a friendlier namespace value.

These fields are present on the Settings page, under Advanced section.

When you change a namespace, the Plug-in offers to update the namespace everywhere in your project.This allows you to avoid damaging existing XPath expressions in your project.

The Plug-in cannot update references if a namespace conflict exists. In that case, you must resolve theconflict manually.

Parse Copybook Data ActivityThe Parse Copybook Data activity parses incoming data into XML according to the schema defined inthe Copybook resource. After parsing is complete, other activities can use the data within a processdefinition.

General TabThe fields under the Parse Copybook Data activity General tab are described here.

Field

LiteralValue/ModuleProperty? Description

Name No The activity’s label name in the process definition.

Copybook Resource No The Copybook Resource that defines the schema for parsingincoming data into XML.

Big Endian Yes The byte order of the incoming data. Check this field to specifythe byte order as Big Endian, for example, for IBM mainframesand certain UNIX platforms. Uncheck this field if the byteorder is Little Endian, for example, for Microsoft Windows andcertain UNIX platforms.

47


Field


Character Set Yes The character-set encoding for the string values in theincoming data except for COBOL items with DISPLAY-1, alsoaffecting the parsing of zoned decimal values. For details, see Handling of Zoned Decimal Items.

You can choose either single-byte or multibyte character setsfrom the selector dialog. Multibyte character sets are markedwith an asterisk for easy identification.

Warning: Multibyte character sets are allowed for COBOLcopybooks only. Although you can choose those sets, choosingone in conjunction with a PL/I or RPG copybook causes anerror.

For details on how character sets work in the Plug-in, see LatinNormalization in Character Sets.

Character Set forDISPLAY-1 Items

Yes The character-set encoding for the string values in theincoming data for COBOL items with USAGE DISPLAY-1. Thisfield is available only if you select a COBOL copybook.

You can choose either single-byte or multibyte character setsfrom the selector dialog. Multibyte character sets are markedwith an asterisk for easy identification.

For details on how character sets work in the Plug-in, see LatinNormalization in Character Sets.

Multiple Records Yes The field that instructs the activity to repeat the copybookparsing until the end of the input data is reached and togenerate multiple output elements.

48


Field


Records Delimiter Yes The field that specifies the delimiter between records in theinput data in case of a checked Multiple Records field. You canspecify the following valid delimiter types:

None — Specifies that a new record begins directly after thelast record ends. No characters separate the records.

New Line — Specifies that a new-line character separates therecords in the input.

Carriage Return — Specifies that a carriage-return characterseparates the records in the input.

Carriage Return/Line Feed (Windows) — Specifies that acarriage-return character followed by a line-feed characterseparates the records in the input.

When specifying this field by Module or Process properties,you can use the following values:

● None: none

● New Line: nl, New Line

● Carriage Return: cret, cr, Carriage Return

● Carriage Return/Line Feed (Windows): crlf, CarriageReturn/Line Feed (Windows)

Note that the previous values are not case sensitive.

Trim Whitespacesfrom String Values

Yes The field that specifies whether to trim white spaces of the text-converted values after parsing. Here are the white-spacecharacters and their descriptions:

\u0009 – Horizontal tabulation\u000A – Line feed\u000B – Vertical tabulation\u000C – Form feed\u000D – Carriage return\u001C – File separator\u001D – Group separator\u001E – Record separator\u001F – Unit separator\u0000 – Null character

Note: Internally, the Plug-in calls a trim() method of the Javaclass String.

This field also affects how the Plug-in matches the REDEFINEcontrol field values. For details, see Configuration of Data-Description Entries for a REDEFINES group Or Union.

49


Field


Empty Nodes Yes The field that specifies whether to preserve empty elements inthe output XML. If you uncheck this field, the Plug-in deletesthe empty elements from the XML data, thus reducing the sizeof the XML output.

Input Type No The field that specifies the type of input for this activity. Thetype can be either of the following:

● A byte array, in which case you must specify abase64Binary value for the bytes input field.

● A file, in which case you must specify the file name andlocation for the fileName input field.

Return RemainingBytes

No Enable returning of the remainder of the input base64Binary. Ifselected, the output of the activity contains a fieldremainingBytes. This field contains the tailing portion of theinput base64Binary that has not been processed by this activity.See Connecting Multiple Parse Activities.

Allow IncompleteRecords

Yes This field specifies whether the activity requires that there theinput contains enough input data for an entire copybooklayout (record) or incomplete layouts are tolerated. This field isonly available for COBOL copybooks.

See Parsing Incomplete Records for more details.

Allow IncompleteText Items

Yes This field specifies that the last text item is allowed to have lessbytes that the copybook implies. This field is only available forCOBOL copybooks and it is enabled only if Allow IncompleteRecords is selected. See Parsing Incomplete Records for moredetails.

Ignore Invalid Items Yes This field turns off errors resulting from invalid content in thebinary data in an elementary item. This field is only availablefor COBOL copybooks.

See Validation of Elementary Items.

50


Field


Check String Valuesfor Invalid XMLCharacters

Yes This field specifies whether, during parsing, the activity checksfor invalid XML characters in XML output. Invalid XMLcharacters can occur depending on binary content andcharacter set selections.

If both the Check String Values for Invalid XMLCharactersfield and the Ignore Invalid Items field are set toYes, an invalid XML character will not cause an activity error,but the character is not included in the activity output.

If only the Check String Values for Invalid XML Charactersfield is set to Yes, and the Ignore Invalid Items field is set toNo, the activity fails.

If the Check String Values for Invalid XML Characters field isnot set to Yes, the activity does not check for invalid XMLcharacters, regardless of the value of the Ignore Invalid Itemsfield. Not checking for invalid characters might causeincremental performance improvements, but this settingshould only be used when data is guaranteed to be XMLcompliant.

See Dealing with Invalid XML Characters.

Description TabA description of the Parse activity.

Input TabThe input fields for the Parse Copybook Data activity are described here.

Input Field Data Type Description

bytes Binary A byte sequence that contains COBOL, PL/I, or RPGdata. This input field is available only if you chooseBytes for the Input Type field under the General tab.

If your COBOL, PL/I, or RPG data is a text string, youmust convert the text to bytes before passing the inputdata to the related activity. Do so by, for example,calling the string-to-base64() XPath function.

fileName String The location and name of the file to read. This inputfield is available only if you choose File from the InputType drop-down menu under the General tab.

The file’s binary content is the input for the activity.

51



forceCharacterSet String A runtime override for the Character Set setting of theParse Copybook Data activity. For details, see thedescription of the field Character Set in the section ParseCopybook Data — Configuration.

If you do not specify a value for forceCharacterSet, theCharacter Set setting under the General tab is in effect.Otherwise, the forceCharacterSet value applies.

Note: Invalid character-set names cause the Plug-in tothrow a ParseCopybookDataException exceptionwhile executing the activity.

forceCharacterSetDisp1 String A runtime override for the Character Set for DISPLAY-1Items setting of the Parse Copybook Data activity. Fordetails, see the description for the Character Set forDISPLAY-1 Items field in Parse Copybook Data —Configuration. This field is available only if select aCOBOL copybook.

If you specify a value for forceCharacterSetDisp1, thatvalue applies. Otherwise, the setting in the Character Setfor DISPLAY-1 Items field under the General tab is ineffect.

Note: Invalid character-set names cause the Plug-in tothrow a ParseCopybookDataException exceptionwhile executing the activity.

noOfRecords Number The number of records to read from the input binarycontent. Specifying no value or specifying -1 as thevalue causes the activity to read all the records in theinput file.

This input field, available only if you choose File for theInput Type field on the General tab, is useful if you readthe input file in parts to minimize memory usage.

For details, see Parsing of a Large Number of Records.

recordDelimiter Binary This is a runtime override for Record Delimiter field.You can supply any base64Binary value to be used as arecord delimiter. This value is only applied whenMultiple Records is selected.

Note that the Plug-in does not validate the actual valueof the delimiter supplied in the binary data but onlyuses the length of the recordDelimiter value to advancethe reading position before parsing another record.

For details on mapping and transforming input data, see the TIBCO ActiveMatrix BusinessWorks ProcessDesign Guide.

52


Output TabThe output of the Parse Copybook Data activity is described here.

Output Item Data Type Description

Output Complex This is the output XML data that is formed according to theselected Copybook Schema resource.

noOfRecords Integer This is the number of records in the parsed XML data.

EOF Boolean This is a flag that—

● If set to true, means that parsing of all the data from theinput file is complete.

● If set to false, means that the input file contains more data.

This output item is available when the Input Type field is setto File. The item is handy for checking if more records are inthe input file while you are reading the input in parts to savememory. For details, see the preceding section, Parsing of aLarge Number of Records.

remainingBytes Binary If you select the Return Remaining Bytes check box in Generaltab, the output of the activity contains the remainingBytes field.This field contains the tailing portion of the input base64Binarythat has not been processed by this activity.

See Connecting Multiple Parse Activities.

copybook* Complex Shows the fields of the copybook that are associated with thisparse activity.

Fault TabWhen Parse Copybook Data encounters an error, it generates ParseCopybookDataException fault.

Field Data Type Description

msg String An error message.

msgCode String Error code. See Error Codes fora list of possible values.

element String The name of a copybookschema element where theerror was detected.

record Integer A zero-based number of arecord where the faultoccurred.

53



offset Integer The offset of the beginning of acopybook element where thefault occurred. The offset iszero-based and relative to thebeginning of the data.

faultBytes Base64Binary Binary data of the item thatcontains the error.

For more details on related corrective actions, see the TIBCO ActiveMatrix BusinessWorks Error Codesmanual.

Parsing Incomplete RecordsA copybook describes a layout where a certain number of bytes is expected for each item. For PL/I andRPG copybook the Parse activity expects enough bytes for the entire copybook layout. If Parseencounters the end of input data before all items have been fully read it throws an exception.

However, the Parse allows additional flexibility for COBOL copybooks. Configuration fields AllowIncomplete Records and Allow Incomplete Text Items are offered.

Allow Incomplete Records

When the Allow Incomplete Records field is not selected, Parse expects that the input data containsenough bytes for the complete copybook layout. When Multiple Records is selected then each recordmust satisfy this requirement.

When the Allow Incomplete Records field is selected, the following applies:

● If, while reading an item, Parse encounters a premature end of data, then the activity stops andreturns the XML containing all items that were read fully. This is considered a normal end of theprocessing as opposed to an error condition when Allow Incomplete Records is not selected.

● Similarly, when Parse is reading an item with OCCURS clause, the premature end of data isconsidered normal even though a required number of occurrences was not read. When AllowIncomplete Records is not selected this results in an error.

When an incomplete item is discarded, the Plug-in is unable to perform any data validitychecks, meaning that a data corruption is less likely to be detected.

Allow Incomplete Text Items

The Allow Incomplete Text Items setting is geared towards copybooks that end with a long PIC X(...)or PIC G(...) item that is unlikely to be fully populated with data. To preserve resources, your programmight choose to only deliver the beginning portion of this field that contains non-blank characters.

Note that this field is selectable only when Allow Incomplete Records is selected.

If Allow Incomplete Text Items is selected, Parse returns the string based on the available data eventhough it might be shorter that what the declared item length. When Allow Incomplete Text Items isnot selected this field would be discarded.

54


Validation of Elementary ItemsBy default, the Parse Copybook Data activity requires the binary data of an elementary item to be in fullcompliance with its definition in a copybook. For example, packed decimal data can only have certainvalues for a sign nibble. Normally, Parse throws an error when a violation is encountered.

For COBOL copybooks, however, this behavior is customizable using the Ignore Invalid Items field on aParse activity. This setting turns off errors resulting from invalid content in the binary data in anelementary item.

When Ignore Invalid Items is selected:

● Any malformed data is ignored and no exception is thrown.

● Resulting XML content have no elements for the invalid items.

For example, this copybook defines an unsigned item:01 ZONED-UNSIGNED PIC 99.

F1E2 (in hexadecimal form) is not valid for this copybook because E is not a valid sign nibble.

If Ignore Invalid Items is not selected, this results in a failure. However, if you select Ignore InvalidItems, then the item is quietly ignored and not included in the resulting XML. Note, however, thatparsing does not stop and any valid items found after an erroneous one are processed and returned inthe XML.

This setting applies to a wide variety of items, including:

● zoned and packed-decimal numbers

● edited numerics

● items with DATE attribute

● external floating point items

Ignore Invalid Items is not a substitute for Allow Incomplete Records. It is applied toitems that have enough bytes in the data. If you want to allow premature end of data thanselect Allow Incomplete Records.

Special Cases

There are several circumstances under which Ignore Invalid Items is not in effect:

● When an invalid item is used as an object of OCCURS DEPENDING ON clause.

For example: 01 COUNT PIC 9. 01 REP PIC X OCCURS 1 TO 10 TIMES DEPENDING ON COUNT.

If COUNT is invalid, the Plug-in cannot determine the number of occurrences of REP to read. In thiscase, parsing fails.

There is an exception from the above. If you selected Allow Incomplete Records and thereare no bytes following COUNT, then Parse completes normally.

● When an invalid item is used as a control field for a REDEFINE group. The Plug-in requires a validcontrol field value to determine how to proceed.

55


There are two cases when the failure does not occur:● When Allow Incomplete Records is selected and the data ends prior to the REDEFINE

group. Is this case Plug-in does not need the control value to be valid.

● If during the control field matching (see Control Values) Parse encounters only '…'Xand '…'& control field values. These values operate directly on the binary content anddo not require validity of a control field. In this case the control field is not included inresulting XML but a member of a REDEFINE group is.

Connecting Multiple Parse ActivitiesIn real world applications, a binary buffer often consists of data whose layouts could be described inmultiple copybooks. Sometimes the decision of which copybook to use next is made based on the datapresent. Control fields in REDEFINE groups offer a form of control but do not cover all patterns.

The most typical pattern is this:

● Two or more copybooks of different byte size are packed into an envelope message.

● Each copybook is preceded with an indicator field that determines which copybook layout follows.

● Layouts are different sizes, which makes it impossible to pack copybooks into a super-copybookwith a REFEDINES clause.

To address this scenario, the Parse Copybook Data activity offers an option to return the remainder ofthe byte data, making it available to the next Parse activity. For example:

In this example, the byte output from the Render activity is processed by the ParseCopybookData1activity. Because the first parse activity has the Return Remaining Bytes option enabled, the data isforwarded to the ParseCopybookData2 activity.

Typically, a small copybook is defined that describes the layout field. A separate Parse activity wouldread it and transition conditionally to a Parse for each respective copybook layout that is expected tofollow.

56


● The Return Remaining Bytes option is not automatically selected. It must be enabled using thecheck box in the General tab. Selecting the Return Remaining Bytes check box results in the additionof the remainingBytes element to the parse output activity.

Enabling this feature for a copybook and returning a base64Binary back into the process incurs aperformance cost. The cost is insignificant with small amounts of data, but large remainders slowsperformance.

● This feature is only available when the Input type specified for the Copybook Parse activity in theGeneral tab is bytes.

● For simplicity, the Return Remaining Bytes check box is always selectable even when MultipleRecords is also selected, and when selected it causes the remainingBytes element to be included inthe parse output activity. However, when Multiple Records is selected, this element is always empty.

Parsing of a Large Number of RecordsWhen reading a large number of records from a file, the Parse Copybook Data activity might consumesignificant machine resources. To minimize memory usage, read the input in parts, parsing andprocessing a small set of records before moving on to the next set.

Note that the term record means the data for the entire copybook. If n records is read, that means theactivity has read the entire copybook n times. If a copybook structure contains repeating items, all ofthem are read during the reading of a single record.

Rules

With the Input Type field set to File, you can specify the value for the noOfRecords input elementunder the Input tab. The following rules apply:

● The Parse Copybook Data activity repeats reading of the copybook data up to the specified numberof times. If more data is available in the file when you next invoke the Parse Copybook Data activity,that activity continues reading the data. Note that this behavior only applies to activities that readthe same file — more specifically, the file whose input element fileName is of the same value.

You can read different files or byte data with other Parse Copybook Data activities. Doing so doesnot affect the current position in this file.

Important: The fileName input element must remain unchanged for subsequent reading to takeplace. For example, Parse Copybook Data reads \data\myfile and myfile separately even if bothpaths point to the same location.

● The output element noOfRecords always contains the number of records read by the activity.

● If you set Input Type to File, the Parse Copybook Data activity contains the output element EOF,whose value is true if all data has been read from the file. That value can serve as an indicator foryou to stop invoking the Parse Copybook Data activity.

● If you set a noOfRecords value but the file contains more data, the file remains open until all datahas been read by subsequent invocations of the Parse Copybook Data activity or until the Plug-inthrows an exception. The file is also closed at the end of the process execution.

● If you do not set Input Type to File or specify a noOfRecords value, reading continues until the endof the input data is reached. At that point, if Input Type is set to File, the Parse Copybook Dataactivity closes the file.

● If you do not specify a value or specify -1 as the value for the noOfRecords field, the activity readsall the records in the input file.

● If you do not select the Multiple Records check box, the Parse Copybook Data activity ignores thevalue of noOfRecords, reads one record, and, subsequently, closes the file.

57


Different operating systems might behave differently with regards to what operations arepermissible on an open file. For example, on Windows a file cannot be deleted until it isclosed, but Sun Solaris permits it.

It is advisable not to design a process that depends on these aspects of a file systembehavior.

Procedure for Reading in a Loop

Procedure

1. Create a Parse Copybook Data activity.

2. Set the appropriate fields under the General tab and choose File from the Input Type drop-downmenu.

3. Select the Parse Copybook Data activity and right-click to create a group that contains the ParseCopybook Data activity.

For details on working with groups, see TIBCO ActiveMatrix BusinessWorks Process Design Guide.

4. SpecifyRepeat as the Group Type and an index name, for example, i.

5. Recommended. Create a loop condition that checks that the EOF output element value is true, forexample:

$ParseCopybookData/EOF=true()

6. Set the noOfRecords input field for the Parse Copybook Data activity to the number of records youwant to process for each execution of the loop.

The loop processes noOfRecords as specified with each iteration until there are no more inputrecords to parse.

Result

The preceding procedure is just a general guideline. You might want to also add other record-processing criteria or to change the XPath expressions to meet your needs. Also, feel free to adopt othermeans of flow control in ActiveMatrix BusinessWorks; just ensure that the fileName input elementvalue stays the same.

Render Copybook Data ActivityWith the Render Copybook Data activity, you can supply XML data according to the schema defined bya copybook resource. Subsequently, the activity renders that data as sequence of bytes that can beconsumed by a COBOL, PL/I, or RPG program.

General TabThe fields under the Render Copybook Data activity General tab are described here.

Field


Name No The activity’s label name in the processdefinition.

58


Field


Copybook Resource No The Copybook Resource that defines theschema for the input XML and the binarylayout of the data.

Big Endian Yes The byte order of the incoming data. Select thisfield to specify the byte order as Big Endian, forexample, for IBM mainframes and certainUNIX platforms. Deselect this field if the byteorder is Little Endian, for example, forMicrosoft Windows and certain UNIXplatforms.

Character Set Yes The character-set encoding for the string valuesin the rendered data except for COBOL itemswith USAGE DISPLAY-1. This encoding alsoaffects the rendering of zoned decimal values.For details, see Handling of Zoned DecimalItems.

You can choose either single-byte or multibytecharacter sets from the drop-down menu.Multibyte character sets are marked with anasterisk for easy identification.

Warning: Multibyte character sets are allowedfor COBOL copybooks only. Although you canchoose those sets, choosing one in conjunctionwith a PL/I or RPG copybook causes an error.

For details on how character sets work in thePlug-in, see Latin Normalization in CharacterSets.

Character Set for DISPLAY-1 Items Yes The character-set encoding for the string valuesin the incoming data for COBOL items withUSAGE DISPLAY-1. This field is available only ifyou select a COBOL copybook.

You can choose either single-byte or multibytecharacter sets from the drop-down menu.Multibyte character sets are marked with anasterisk for easy identification.

For details on how character sets work in thePlug-in, see Latin Normalization in CharacterSets.

59


Field


Multiple Records Yes The field that specifies whether to render onerecord or multiple records.

● If you select this field, the Plug-In rendersall top-level input elements as records,which are separated by the delimiterspecified in the Records Delimiter field.

● If you deselect this field, the Plug-In rendersonly one record, that is, the first top-levelelement from the input XML.

60


Field


Record Delimiter Yes The field that specifies the delimiter betweenrecords in the output data in case of a selectedMultiple Records field. You can specify thefollowing valid delimiter types :

None — Specifies that a new record beginsdirectly after the last record ends. No charactersseparate the records.

New Line — Specifies that a new-line characterseparates the records in the output.

Carriage Return — Specifies that a carriage-return character separates the records in theoutput.

Carriage Return/Line Feed (Windows) —Specifies that a carriage-return characterfollowed by a line- feed character separates therecords in the output.

The above values are for the UNIX andWindows platforms only.

It is good practice not to use Record delimitersif you set the Render As property to String.See the warning below this table.

When specifying this field by Module orProcess properties, you can use the followingvalues:

● None: none

● New Line: nl, New Line

● Carriage Return: cret, cr, CarriageReturn

● Carriage Return/Line Feed (Windows):crlf, Carriage Return/Line Feed(Windows)

Note that the previous values are not casesensitive.

61


Field


Truncate Multi-Byte Strings Yes The field that specifies whether to truncate longstrings, applicable to COBOL copybooks onlyand valid only if you have selected a multibytecharacter set. For DISPLAY items, the binarylength is equal to the number of characters.

If you configure the activity to use a multibytecharacter set, the binary representation of astring might become longer than the allocatedlength. In that case—

● If you select this field, the activity truncatesthe binary representation at the nearestcharacter boundary to ensure that the Plug-in does not throw aSerializationException exception andthat the allocated length is never exceeded.

Warning: Exercise caution when selectingthis field. Even though data truncationoccurs at a character boundary, thetruncation might cause an undesiredcontent change for certain multibytecharacter sets.

● If you deselect this field, the Plug-in throwsa SerializationException exception.

Filler Character Yes The field that specifies the fill character used fortext padding or layout gaps. You can chooseeither NULL (a byte with value zero) or Space asthe fill character; NULL is the default.

When you select Space, the exact byte valuedepends on the Character Set setting of youractivity. See Item Initialization DuringRendering for more information.


● Null: null● Space: space


62


Field


Default Numeric and DATE Itemsto

Yes This field is available for COBOL copybooks. Itspecifies how the binary data is initialized fornumeric or DATE items that are not specified inthe input mapping. Options are:

Type Defaults — Numeric and Date items areinitialized differently:

● Numeric items are initialized with anumeric value 0 and are rendered accordingto the PICTURE and USAGE, and DATEFORMAT clauses, as well as settings of thecopybook resource and Render activity.

● DATE items are initialized with a defaultdate 0001-01-01, which is renderedaccording to the PICTURE, USAGE clauses,as well as settings of the copybook resourceand Render activity.

LOW-VALUES — All numeric and DATEitems are initialized with zero bytes,regardless of the copybook or any othersettings.

See Item Initialization During Rendering formore information.


● Type Defaults: typeDefaults, TypeDefaults

● LOW-VALUES: lowValues, LOW-VALUES


63


Field


ASCII Zoned Format Yes You can use this field to select a specific ASCIIZoned format to be generated.

Use this field when the Character Set field orforceCharacterSet field is set to a character setthat belongs to the ASCII family.

● strict— generate Strict ASCII zoneddecimal format.

● modified— generate Modified ASCII zoneddecimal format.

The input field asciiZonedFormat acts as aruntime override of this field.

See Handling of Zoned Decimal Items.


● Strict: strict● Modified: modified


Render Data as No The field that specifies the output data format.You have two choices:

Bytes — The Plug-in renders the data as a bytesequence.

String —The Plug-in renders the data as astring with the character set encoding asspecified in the Character Set field. See thatfield’s description earlier in this table.

Make your choice with caution. See thewarning below this table.

IBM i Sign Nibbles Yes If it is checked, this field instructs the activity torender the IBM i flavor of zoned and packeddecimal items. If it is not checked, zOS flavor isgenerated.

This field is only available for COBOLcopybooks. See Sign Nibbles in Zoned andPacked Decimal Items for more information.

64


Field


Fail on Invalid XML Characters Yes This field is only applicable when Render Dataas is set to String.

It specifies whether the activity check theoutput string content for presence of charactersthat are not valid in XML documents.Depending on the copybook specifics, there is apossibility that the activity might produce suchcharacters. If checked, the activity fails whensuch characters are detected.

See Dealing with Invalid XML Characters.

Specify the String value for the Render As property with caution. This value instructs the Renderactivity to generate a string for the entire rendering result according to a specific character set.

If either or both of the following conditions are true, it is good practice that you do not specify theString value. Such a specification might cause the Plug-in to convert the binary data to meaninglesscharacters in the output string. Also, you might not be able to recover the binary values from theoutput.● The copybook contains fields with binary representation, such as COBOL fields with BINARY (COMP,

COMP-1, COMP-2, and COMP-3; or zoned decimal fields without SIGN SEPARATE. Refer to the COBOLspecification for details.

● The Plug-in renders multiple records with a record delimiter. The values of the Records Delimiterproperty apply to the UNIX and Windows platforms only and, depending on the character set,might yield unexpected characters.

Description TabA description of the Render activity.

Input TabThe input fields for the Render Copybook Data activity are described here.


Input Complex This is the input XML data that is formed accordingto the selected Copybook Schema resource.

forceCharacterSet String This is a runtime override for the Character Set fieldof the Parse Copybook Data activity. For details, see Character Set.

If you do not specify a value for forceCharacterSet,the Character Set setting under the General tab is ineffect. Otherwise, the forceCharacterSet valueapplies.

Note: Invalid character-set names cause the Plug-in tothrow a DeSerializationException exceptionwhile executing the activity.

65



forceCharacterSetDisp1 String This is a runtime override for the Character Set forDISPLAY-1 Items field of the Parse Copybook Dataactivity. For details, see the description for theCharacter Set for DISPLAY-1 Items field in ParseCopybook Data — General. This field is availableonly if you select a COBOL copybook.

If you specify a value for forceCharacterSetDisp1,that value applies. Otherwise, the Character Set forDISPLAY-1 Items setting under the General tab is ineffect.

Note: Invalid character-set names cause the Plug-in tothrow a DeSerializationException exceptionwhile executing the activity.

recordDelimiter Binary This is a runtime override for Record Delimiter field.You can supply any base64Binary value to be usedas a record delimiter. This value is only applied whenMultiple Records is selected.

asciiZonedFormat String(enumeration)

This is a runtime override for the ASCII ZonedFormat field of the Render activity. It is used to selecta specific flavor of ASCII Zoned Decimal format.

Use this field when the Character Set field orforceCharacterSet field is set to a character set thatbelongs to the ASCII family.

You can use these values:

● strict— generate Strict ASCII zoned decimalformat.

● modified— generate Modified ASCII zoneddecimal format.

See Handling of Zoned Decimal Items.

copybook* Complex The fields of the copybook that are used by thisrender activity.

For details on mapping and transforming input data, see TIBCO ActiveMatrix BusinessWorks ProcessDesign Guide.

Output TabThe output items for the Render Copybook Data activity are described here.

Output Items for Render Copybook Data Activity


noOfRecords Integer The number of records in the output byte stream.

66



bytes Binary A byte sequence that contains COBOL, PL/I, or RPGdata.

Fault TabWhen Render Copybook Data encounters an error it generates a RenderCopybookDataException fault.


msg String An error message.

msgCode String Error code. See Error Codes fora list of possible values.

element String The name of a copybookschema element where theerror was detected.

record Integer A zero-based number of arecord where the faultoccurred.

offset Integer The offset of the beginning of acopybook element where thefault occurred. The offset iszero-based and relative to thebeginning of the data.

For more details on related corrective actions, see the TIBCO ActiveMatrix BusinessWorks Error Codesmanual.

Item Initialization During RenderingIn most cases, you supply values to a Render activity through mapping. However, you are not alwaysrequired to supply a value this way.

When you omit a value, one of two things happens:

● The Plug-in checks for any initial value supplied in a COBOL VALUE clause or PL/I INIT attributeand renders it if it is present.

● Otherwise, the binary data is formed according to the policies described in the following table.

This table also describes any padding that results due to insufficient data length, layout gaps, and soforth.

Render Activities — Initialization Policies

Item Type Action

COBOL text items (PIC X or G)

The Filler setting of the activity is used to initialize missing items orpad shorter strings.

67


Item Type Action

PL/I CHAR, WIDECHAR,GRAPHIC, and BIT itemswith VARYING orVARYINGZ

Padding within a REDEFINEgroup or UNION

The Filler setting is used.

Gaps due to PL/I alignmentor COBOL slack bytes andtop-level item placement(double-word boundary)

Any items with their XSDtype set to base64Binary viathe Field Configuration page,except CHAR, WIDECHAR,GRAPHIC and BIT

The Filler setting is used to initialize missing items or pad shortervalues.

PL/I CHAR items withoutVARYING or VARYINGZ

A space is used as a filler and a padding character. The exact valueof the space depends on a Character Set of the activity.

All RPG text items

PL/I WIDECHAR with noXSD Type base64Binaryselected

A space in UTF-16LE or UTF-16BE character set depending onwhether the Big Endian setting is used.

PL/I CHAR, WIDECHARwith XSD Type base64Binaryselected

The Filler setting of the activity is used to initialize missing items orpad shorter strings. If VARYING or VARYINGZ are specified, theFiller is used for both the variable string data as well as the spacebetween the variable data and the declared length. Note that 2-bytelength prefix for VARYING and zero terminator for VARYINGZ arealways generated.

PL/I GRAPHIC A DBCS space (x4040) is used. Note that 2-byte length prefix forVARYING and zero terminator for VARYINGZ are alwaysgenerated.

PL/I BIT A zero byte is used as a filler. Note that 2-byte length prefix forVARYING and zero terminator for VARYINGZ are alwaysgenerated.

COBOL fields with DATE The setting Default Numeric and DATE Items to is in effect. WhenType Defaults is selected, the default date 0001-01-01 is rendered.Otherwise a zero byte is used as a filler.

COBOL external floatingpoint items

The setting Default Numeric and DATE Items to is in effect. WhenType Defaults is selected, the numeric value 0 is renderedaccording to the copybook specifics and activity settings. Otherwisea zero byte is used as a filler.COBOL Numeric-Edited

items

68


Item Type Action

COBOL zoned and packeddecimal items

COBOL COMP-1 andCOMP-2 items

A zero byte is used as filler.

The cases not described in the previous table always require a value, either through a mapping orVALUE/INIT clauses.

69


Error Codes

The following error codes and messages are returned by the activities that take place in the DataConversion palette in case of errors.

Error codes are available in the msgCode field of ParseCopybookDataException andRenderCopybookDataException. The description is available in msg field of these exceptions.

TIBCO-BW-PALETTE-DATACONVERSION-500000Value of control field {1} specified could not be determined, element {0}

TIBCO-BW-PALETTE-DATACONVERSION-500001Error when processing the control field value for element {0}: {1}

TIBCO-BW-PALETTE-DATACONVERSION-500002High half of byte {0} in packed decimal number does not contain a digit

TIBCO-BW-PALETTE-DATACONVERSION-500003Low half of byte {0} in packed decimal number does not contain a digit

TIBCO-BW-PALETTE-DATACONVERSION-500004Low half of last byte in packed decimal number does not contain a valid sign

TIBCO-BW-PALETTE-DATACONVERSION-500005Value of an unsigned numeric item cannot be negative

TIBCO-BW-PALETTE-DATACONVERSION-500006Invalid sign character: "{0}"

TIBCO-BW-PALETTE-DATACONVERSION-500007National item must be declared with SIGN SEPARATE clause

TIBCO-BW-PALETTE-DATACONVERSION-500008"{0}" is not a valid decimal digit for a zoned decimal value

TIBCO-BW-PALETTE-DATACONVERSION-500009Hex {0} is not a valid sign nibble for a {1} zoned decimal value

TIBCO-BW-PALETTE-DATACONVERSION-500010Hex {0} is not a valid sign byte for a {1} zoned decimal value

TIBCO-BW-PALETTE-DATACONVERSION-500011Value of REFER object "{0}" is not found

TIBCO-BW-PALETTE-DATACONVERSION-500012Value {0} of refer object "{1}" must be a valid integer

TIBCO-BW-PALETTE-DATACONVERSION-500013Value {0} of lower bound refer object "{1}" is greater than value {2} of upper bound refer object "{3}"

TIBCO-BW-PALETTE-DATACONVERSION-500014Value {0} of upper bound refer object "{1}" is less than the lower bound {2}

TIBCO-BW-PALETTE-DATACONVERSION-500015Value {0} of lower bound refer object "{1}" is greater than the upper bound {2}

TIBCO-BW-PALETTE-DATACONVERSION-500016Value of refer object "{0}" is {1}, must be non-negative

TIBCO-BW-PALETTE-DATACONVERSION-500017

70


Value of REFER object "{0}" is not found

TIBCO-BW-PALETTE-DATACONVERSION-500018Terminating zero was not found in VARYINGZ string

TIBCO-BW-PALETTE-DATACONVERSION-500019Length {0} of VARYING string exceeds maximum declared length {1}

TIBCO-BW-PALETTE-DATACONVERSION-500020VARYING BIT string has length {0}, must be divisible by 8

TIBCO-BW-PALETTE-DATACONVERSION-500021Value of DEPENDING ON data element {1} could not be determined, element {0}.

TIBCO-BW-PALETTE-DATACONVERSION-500022Value of a control element {1} is invalid, element {0}

TIBCO-BW-PALETTE-DATACONVERSION-500023Value of DEPENDING ON data element {1} is invalid, element {0}

TIBCO-BW-PALETTE-DATACONVERSION-500024Value {0} of DEPENDING ON data element "{1}" is not a valid integer

TIBCO-BW-PALETTE-DATACONVERSION-500025Date {0} is not valid

TIBCO-BW-PALETTE-DATACONVERSION-500026"{0}" is not a valid external floating point number

TIBCO-BW-PALETTE-DATACONVERSION-500027Error in numeric edited value (actual message describes details of the error)

TIBCO-BW-PALETTE-DATACONVERSION-500028{0} value {1} has too many digits for PICTURE clause {2}

TIBCO-BW-PALETTE-DATACONVERSION-500029Input file is not specified

TIBCO-BW-PALETTE-DATACONVERSION-500030Not enough data bytes

TIBCO-BW-PALETTE-DATACONVERSION-500031Error reading byte contents: {0}

TIBCO-BW-PALETTE-DATACONVERSION-500032Number of bytes {0} of the input base64Binary value exceeds the maximum of {1}

TIBCO-BW-PALETTE-DATACONVERSION-500033Value must be supplied

TIBCO-BW-PALETTE-DATACONVERSION-500034The number of bytes in supplied multi-byte string is {0}, which exceeds the byte size {1} of the item

TIBCO-BW-PALETTE-DATACONVERSION-500035The number of bytes in supplied multi-byte string is {0}, which exceeds the byte size {1} of the item.The value was truncated.

TIBCO-BW-PALETTE-DATACONVERSION-500036base64Binary value contains {0} bytes, must be divisible by {1} for type {2}

TIBCO-BW-PALETTE-DATACONVERSION-500037

71


REFER object value {0} is not divisible by 8

TIBCO-BW-PALETTE-DATACONVERSION-500038String length {0} exceeds the length {1} specified by REFER object

TIBCO-BW-PALETTE-DATACONVERSION-500039base64Binary value contains {0} bits ({1} bytes) which exceeds declared length of {2} bits ({3} bytes).

TIBCO-BW-PALETTE-DATACONVERSION-500040String length {0} exceeds the length {1} specified by REFER object

TIBCO-BW-PALETTE-DATACONVERSION-500041A problem with a character set (the actual message contains the details)

TIBCO-BW-PALETTE-DATACONVERSION-500042Value {2} of depending data element {1} is out of minimum {3} and maximum {4} range for variableoccurring element {0}.

TIBCO-BW-PALETTE-DATACONVERSION-500043Value {0} has to many digits before the decimal point, must be at most {1}

TIBCO-BW-PALETTE-DATACONVERSION-500044Character {0} at pos {1} is not a valid XML character

TIBCO-BW-PALETTE-DATACONVERSION-500045A problem related to scaling factor P (the actual message contains the details)

TIBCO-BW-PALETTE-DATACONVERSION-500046An incorrect field value is specified by Module or Process properties (the actual message contains thedetails)

TIBCO-BW-PALETTE-DATACONVERSION-500047Numeric value {0} is too long to fit in {1} bytes

72


Samples

TIBCO Active Matrix Business Works Plug-in for Data Conversion comes with samples. The samplesare packaged in {TIBCO_HOME}/bw/palettes/bwdcp/{plug-in version}/sample.zip archive.

You might need to make some environment-specific adjustments to the samples before they can runsuccessfully. See each sample for more information.

Prerequisite: Use the following procedure to import the sample projects into Business Works Studio(Studio).

1. Open Studio.

2. Select File > Import in the menu.

3. Select Existing Projects into Workspace.

4. Click Next.

5. Select Select archive file and click Browse.

6. Navigate to {TIBCO_HOME}/bw/palettes/bwdcp/{plug-in version}/samples directory.

7. Select samples.zip.

8. Select the sample projects to import.

9. Click Finish.

Sample Name Description Preparation Steps

simpleCOBOL Sample Demonstrates render-parserountrip for COBOL data.

None

simpleRPG sample Demonstrates render-parserountrip for RPG data.

None

simplePLI sample Demonstrates render-parserountrip for PL/I data.

None

repeatingCobol Sample Demonstrates parsing andrendering of COBOL data withOCCURS clause in thecopybook.

Open the process contained inthe repeatingCOBOL packageand adjust the path to the filerepeating.bin.

redefinesCobol Demonstrates parsing andrendering of COBOL data withREDEFINES clause in thecopybook. The copybookdefines control values that areused during parsing. See theField Configuration tab in theredefines.copybook resourcelocated in the redefinesCOBOLpackage.

Open the process contained inredefinesCOBOL package andadjust the path to the fileredefines.bin.

73


ebcdicToAsciiFileConvert Demonstrates text fileconversion from Cp037 toAscii. This method works bysequentially reading the Cp037encoded text from a file, andappending Asii text to anoutput file. The conversion isachieved using a Parse activityand a COBOL copybook thatcontains one text field.

1. Specify input and outputpath files (including file names)in module propertiesebcdicFile and asciiFile.

2. Run the processebcdictoasciifileconvert/

createTestDataProcess.bwp

to create sample data that isencoded with a Cp037character set and is placed inthe location specified in theebcdicFile module property.

3. To perform the conversionrun theebcdictoasciifileconvert/

convertProcess.bwp process,which will place the Ascii copyof the sample data into the fileyou specified in the asciiFilemodule property.

The advantage of this approachis that the file is converted insmall chunks. This keeps thememory footprint small and afile of any size can beprocessed.

74


mainframe-ems-sample This project demonstrates datatransmission and conversionbetween a BusinessWorksprocess and programs writtenin COBOL, PL/I, and RPG. Thedata is transmitted in binaryform using the TIBCOEnterprise Message Service™

Processes in the mainframe-ems-sample packageimplement the receive-sendflow for all three languages.

This flow is as follows: aprogram sends a binarymessage to the BusinessWorksprocess, which parses themessage, renders a binaryresponse, and returns themessage to the program. Theprogram logs the data found inthe response message.

The corresponding programsand artifacts are available in thesamples.zip file. Look for thetop level directory EMS and thesubdirectories zOS-COBOL,IBMi-RPG, and zOS-PLI. Eachof these directories containsprogram source code,copybooks, and jcl files to runthe programs.

1. Compile and link theprograms.

2. Make sure that an EMSserver is running and accessiblefrom both BusniessWorks andthe sample programs.

3. For COBOL and PL/I, specifyyour Enterprise MessageService server URL in theEMSPDCP1.jcl file on the linethat contains the following:

//

PARM='ems.server.url:<por

t>'

4. Specify your EnterpriseMessage Service server URL inthe module property jms-provider-url of theBusniessWorks project.

Steps to run a sample process:

1. Start a specificBusinessWorks process fromthe mainframe-ems-samplepackage. The process waits foran EMS message.

2. For COBOL and PL/I, submitan EMSPDCP1.jcl job.

3. For PRG, use the followingjob command:

CALL PGM(library_name/

EMSRDCP1) PARM('TCP://

EMS-SERV:nnnn')

where:

- TCP://EMS-SERV:nnnn is theURL of your EnterpriseMessage Service server.

- library_name is yourproduct library name, whichdefaults to TIBEMSLIB.

75


Documents

TIBCO Product Documentation - TIBCO ActiveMatrix ......COBOL, PL/I, and RPG copybook files describe the data structure for the corresponding binary data. You can interpret or create