TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion … · 2014-05-30 · TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion User’s Guide Read this manual to

TIBCO ActiveMatrix BusinessWorks™ Plug-infor Data Conversion User's GuideSoftware Release 4.1May 2014

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(OR PROVIDE 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.

This document contains confidential information that is subject to U.S. and international copyright lawsand treaties. No part of this document may be reproduced in any form without the writtenauthorization of TIBCO Software Inc.

TIBCO, Two-Second Advantage, TIBCO Rendezvous, TIBCO Enterprise Message Service, TIBCOAdministrator, and TIBCO ActiveMatrix BusinessWorks are either registered trademarks ortrademarks of TIBCO Software Inc. in the United States and/or other countries.

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, NOTALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASEDAT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWAREVERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR 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.

Copyright © 2004-2014 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

2

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

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Overview of Data Conversion Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Examples Sending and Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Language Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

COBOL Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Supported Usages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Supported Picture Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Supported COBOL Clauses and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

DATE FORMAT Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

OCCURS … DEPENDING ON Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Handling of Computation Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

COMP Versus COMP-5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

COMP 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Handling of Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

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

Handling of Items in Binary Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Unsupported Clauses Features Levels and Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

PL/I Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Declarations and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

Data Factoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

* Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Data Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Unions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

The REFER Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

COMPLEX Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

INITIAL Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Data Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

RPG Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Supported RPG Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Mapping of RPG Internal Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Unsupported RPG Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Handling of Zoned Decimal Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

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

ASCII Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

3


Modified ASCII Sign Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Handling of Floating Point Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Latin Normalization in Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Data Conversion Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Copybook Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

Copybook Resource — Settings Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

Copybook Resource — Copybook Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Copybook Resource — Schema Preview Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Copybook Resource — Field Configuration Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

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

Control Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

In-Place Copybook Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

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

Parse Copybook Data Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Parse Copybook Data — General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Parse Copybook Data — Description Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Parse Copybook Data — Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

Parsing Incomplete Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Allow Incomplete Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Allow Incomplete Text Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Validation of Elementary Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Connecting Multiple Parse Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Parsing of a Large Number of Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Procedure for Reading in a Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Parse Copybook Data — Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Parse Copybook Data — Fault Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

Render Copybook Data Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Render Copybook Data — General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Render Copybook Data — Description Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Render Copybook Data — Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Render Copybook Data — Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Render Copybook Data — Fault Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Item Initialization During Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

4


Figures

Sending or Receiving COBOL Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Receiving Data from a COBOL Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Sending Data to a COBOL Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

ACTUAL and CONVERTED Fields in Customize Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

5


TIBCO Documentation and Support Services

All TIBCO documentation is available in the TIBCO Documentation Library, which can be found here:

https://docs.tibco.com

Product-Specific Documentation

The following documents for this product can be found in the TIBCO Documentation Library:

● TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion User’s Guide Read this manual to gainan understanding of the product and its capabilities.

● TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion Installation Read this manual forinstructions on site preparation and installation.

● TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion Release Notes Read the release notes fora list of new and changed features. This document also contains lists of known issues and closedissues for this release.

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support asfollows:

● For an overview of TIBCO Support, and information about getting started with TIBCO Support,visit this site:

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

● If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you canrequest one.

How to Join TIBCOmmunity

TIBCOmmunity 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. TIBCOmmunity offersforums, blogs, and access to a variety of resources. To register, go to:

http://www.tibcommunity.com

6


https://docs.tibco.com

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

https://support.tibco.com

http://www.tibcommunity.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, ActiveMatrix BusinessWorks must parse itinto XML for access by activities within a process definition.

The Data Conversion palette consists of the following:

● Copybook Resource — This shared configuration resource contains COBOL, PL/I, or RPG datastructure and a corresponding XML Schema Definition (XSD) schema for input and outputmappings for 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,or RPG data by way of a messaging service or the file system.

The figure below illustrates how the Plug-in receives and sends COBOL data to and from a mainframeapplication or a COBOL data file.

7


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 may 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 HandleIncomingData subprocess.

Receiving Data from a COBOL Application

Sending Data

This process recieves data from an incoming HTTP request and then passes it to theHandleIncomingData subprocess. The data is then passed to the RenderCopybookData activity so thatCOBOL data can be created and sent to a COBOL application. The data is then sent to the COBOLapplication by way of a JMS Queue Sender activity.

Sending Data to a COBOL Application

8


Language Features

The Plug-in supports a variety of language features.

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.

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.

9


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 in the Customizedialog box. See Handling of Numeric-Editedand External Floating-Point Items and FieldConfiguration Page.

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 in the Customize dialog box.See Handling of Numeric-Edited and ExternalFloating-Point Items and Field ConfigurationPage.

Numeric PIC 999 PIC 9(5)

PIC S9(8) PIC

S9(5)V99

If a data element’s picture 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.

10


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. The Plug-in supports this clause by adding generated items calledSLACK-BYTES, which maintain the proper alignment.

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 Configuration tab.

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

11


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 throws a SerializationException exception.

12


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, big-endian representation). However, an additional limitation based on thenumber of decimal digits in the 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.

13


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, since 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 will generate unique XSDnames by 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 will be ITEM, but the second item will be named ITEM-0.● The Plug-in allows unnamed items. In this case, the XSD name is NO-NAME. If many unnamed

items are present at the same group level (or at the top the level) the names will be 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 default

for 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 Customize dialog box. See Field Configuration Page.

14


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

Handling of Items in Binary FormBy default, the Plug-in represents COBOL elementary items as an XSD type appropriate to the PICTUREand USAGE clauses. For example, PICTURE X(10) appears as a string element with the maximum lengthof 10 in the schema.

To handle an elementary item in binary form instead, select base64Binary as an XSD type for an itemin the Field Configuration page. Subsequently, the Plug-in represents the item as a sequence of byteswith no transformation or validation of the data. You can then apply custom processing to the binarydata. For details, see Field Configuration Page.

Note these 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 with a filler character according to the Filler Character setting of the ParseCopybook Data activity. See description of the Filler Character field in Render Copybook Data— Configuration.

— The VALUE clause is not in effect.

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

If you are allocating memory with a PIC X(...) item to store nontextual data, be sure toselect base64Binary as an XSD type.

Exercise caution when changing an item’s XSD type, such as from string tobase64Binary. Since base64Binary is text-based, a base64Binary element can remainmapped to a string element and vice versa with no XPath errors or warnings.Consequently, data corruption might be difficult to track. For example, a text element canreceive base64 content and no errors would occur.

A good tip is to supplement the XSD type change to base64Binary with a call to theXPath function tib:base64-to-string() in the mapping.

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

Clause, Feature, Level, or Phrase Notes

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

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

15


Clause, Feature, Level, or Phrase Notes

Level 78 Level 78, a Micro Focus COBOL Compiler feature thatenables you to 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 FeaturesThe 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.

You can import a file that contains PL/I data definition into a Copybook resource. A PL/I programmight contain a mix of DECLARE statements and other language constructs. Even though the Plug-inprocesses DECLARE statements only, the imported file can contain other program elements. In thefollowing example—DECLARE 1 DATA_STRUCT, 2 FLD1 FIXED BINARY(31), 2 FLD2 FIXED BINARY(31);PRINT_DATA:PROCEDURE; PUT SKIP EDIT (' FLD =', DATA_STRUCT.FLD) (A,A);END PRINT_DATA;

16


—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 Plug-in’s operation:

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;

17


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 onany level inside a union results in an error.

The REFER Option

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

The syntax is:

expression REFER (member-variable)

18


where:

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

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

19


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.

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’sBig Endian 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);

20


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 valuesare the 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.

21


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 valuesare the unmodified binary content of a bit string, where each byte contains8 bits.

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

22


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),

23


2 ARRAY(10 REFER(LEN_VAR)) FIXED BIN(15), 2 CH CHAR ALIGNED;

RPG FeaturesThe 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 compilersmight produce incompatible data layouts.

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

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

24


RPG Internal Data Type Simple XML Schema Type

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.

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

25


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 Modified ASCII Sign Bytes.

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 Copybook Schema Resource to specify a format.● Pass strict or modified to the input field asciiZonedFormat. This field takes precedence over the

ASCII Zoned Format dropdown.

By default, Strict ASCII is generated.

26


Modified ASCII Sign Bytes

By default the Render Copybook Data activity generates Strict ASCII format. For RPG copybooks, StrictASCII format is generated.

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

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

27


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 in

the 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 may 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.

28


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 0021-007E

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.

29


Data Conversion Palette

This chapter 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.

Copybook Resource — 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

Data Element No The data element to be converted into XMLschema

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

30


Field

LiteralValue/ModuleProperty? Description C P R

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

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:

● 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 declarationcan reside in any column.

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.

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

31


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

Click the following buttons, as appropriate, when editing the copybook:

● Import● Compare with the original● Revert to the original● Save to a file

For details, see In-Place Copybook Editing.

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

Copybook Resource — Field Configuration PageYou tailor various aspects of the Copybook’s behavior in the Field Configuration page. Fieldconfiguration is not applicable for RPG copybooks, and the Field Configuration page is empty in thiscase.

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.

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

32


Column Description

XSD Type This column displays the XML schema’s XSD type. You can modify thiscolumn for COBOL copybooks, but not for PL/I ones. For COBOL, thefollowing choices are available:

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

● A numeric type if an item has a numeric-edited PICTURE category. See Handling of Numeric-Edited and External Floating-Point Items .

● 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 reside 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 clickingmagnifying 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 should provide a list of control values for fields in the REDEFINESgroup or UNION. Subsequently, while checking the control field against those values, the activityoutputs that field into the output XML document if the invoked Parse Copybook Data activitydetects 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 do not need to assign control values to every fieldof a REDEFINES group or UNION. If control values are not assigned, such a field is never begenerated unless it is selected as the default redefine of the REDEFINES group or UNION. Ifyou do not assign control values to any of fields, the control field will have no effect onparsing.

33


Result

For example, the UNIT-PRICE-CONTROL field determines whether the Plug-in generates theACTUAL or 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 in Customize Dialog Box

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 wish 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 an

unquoted value.

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

34


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 checked

starting 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 will never produce a match. For example,

01 ITEM PIC X

will never be matched by a control value

'1000100011110111'&

Hexadecimal Values

35


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 the

same byte value.● You can use the repetition factor (n) to make your value compact. (n) repeats the following pair of

hex digits n times, for example "01(3)FF02"X is equivalent to "01FFFFFF02"X.● Spaces are allowed anywhere within quotes. They are ignored. You can use them to make values

more 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 the

bytes 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 will never produce a match. For example

01 ITEM PIC X.

will never be matched by a control value

"01 FF FF FF 02"X

Matching Sequence

Some data values may match more than one control value. For example, a control field with a value xFFwill match 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 will always result in B, because value '10000001'&matches a broader 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 content

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

36


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.

Import ButtonClicking 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. Subsequently, the Plug-in parses thedata definitions and you can view the XSD schema by clicking the XML Schema tab.

The contents of the copybook are parsed in real-time. If the parse fails, the errors button activates. Clickthe button to see error details.

37


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.

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.

Parse Copybook Data — 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 No 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.

38


Field


Character Set No 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

No The character-set encoding for the string values in theincoming data for COBOL items with USAGE DISPLAY-1.This field 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 No The field that instructs the activity to repeat the copybookparsing until the end of the input data is reached and togenerate multiple output elements.

Records Delimiter No The field that specifies the delimiter between records in theinput data in case of a checked Multiple Records field.Following are the valid delimiter types you can specify:

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.

39


Field


Trim Whitespacesfrom String Values

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

Empty Nodes No 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 will contain 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

No This field specifies whether the activity should require thatthere the input contains enough input data for an entirecopybook layout (record) or incomplete layouts are tolerated.This field is only available for COBOL copybooks.

See Parsing Incomplete Records for more details.

40


Field


Allow IncompleteText Items

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

Parse Copybook Data — Description TabA short description of the Parse activity.

Parse Copybook Data — 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 Configurationtab.

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 Configuration tab.

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

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 Configuration tab is ineffect. Otherwise, the forceCharacterSet value applies.

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

41



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 CharacterSet for DISPLAY-1 Items field under the Configurationtab is in effect.

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 Configuration tab, is useful ifyou read the input file in parts to minimize memoryusage.

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.

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.

42


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, than the activity will stop andreturn the XML containing all items that were read fully. This will be considered a normal end ofthe processing 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 will beconsidered 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. In order to preserve resources, yourprogram may choose to only deliver the beginning portion of this field that contains non-blankcharacters.

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

If Allow Incomplete Text Items is selected, Parse will return the string based on the available dataeven though it may be shorter that what the declared item length. When Allow Incomplete Text Itemsis not selected this field would be discarded.

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 ona Parse 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

43


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

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 '…'X

and '…'& 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 will not beincluded in resulting XML but a member of a REDEFINE group will.

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-copybook

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

44


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.

● The Return Remaining Bytes option is not automatically selected. It must be enabled using thecheckbox in the General tab. Selecting the Return Remaining Bytes checkbox 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 willslow performance.

● 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 checkbox is always selectable even when MultipleRecords is also selected, and when selected will cause the remainingBytes element to be includedin the parse output activity. However, when Multiple Records is selected this element will alwaysbe 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.

45


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 Dataactivity, that activity continues reading the data. Note that this behavior only applies to activitiesthat read the same file — more specifically, the file whose input element fileName is of the samevalue.

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 checkbox, the Parse Copybook Data activity ignores thevalue of noOfRecords, reads one record, and, subsequently, closes the file.

Different operating systems may 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 Configuration tab and choose File from the Input Type drop-down menu.

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.

46


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

Parse Copybook Data — 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.

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

Parse Copybook Data — Fault TabUnder the Fault tab are listed the exceptions that can be thrown by this activity. In case of errors whiledeserializing incoming data, the Plug-in throws only one exception: ParseCopybookDataException.

For details on related corrective actions, see the TIBCO ActiveMatrix BusinessWorks Error Codes manual.

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

47


Render Copybook Data — 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.

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

Big Endian No 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 No 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.

48


Field


Character Set for DISPLAY-1Items

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

Multiple Records No 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.

Record Delimiter No The field that specifies the delimiter betweenrecords in the output data in case of a selectedMultiple Records field. Following are the validdelimiter types you can specify:

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.

Record delimiters are not recommended if youset the Render As property to String. See thewarning below this table.

49


Field


Truncate Multi-Byte Strings No 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 No The field that specifies the fill character usedfor text 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.

50


Field


Default Numeric and DATE Itemsto

No This field is available for COBOL copybooks. Itspecifies how the binary data should beinitialized for numeric or DATE items that arenot specified in the input mapping. Optionsare:

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.

ASCII Zoned Format No This field allows you 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.

51


Field


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.

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, we strongly recommend that you do not specifythe String value. Such a specification will likely cause the Plug-in to convert the binary data tomeaningless characters in the output string. Also, you might not be able to recover the binary valuesfrom the output.● 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 theCOBOL specification 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.

Render Copybook Data — Description TabA short description of the Render activity.

Render Copybook Data — 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.

52



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 Configuration tabis in effect. Otherwise, the forceCharacterSet valueapplies.

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

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 Configuration tabis in effect.

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.

These values are allowed:

● 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 the TIBCO ActiveMatrix BusinessWorksProcess Design Guide.

53


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

Output Items for Render Copybook Data Activity

Output Item Data Type Description

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

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

Render Copybook Data — Fault TabUnder the Fault tab are listed the exceptions that can be thrown by this activity. In case of errors whileparsing incoming data, the Plug-in throws only one exception: RenderCopybookDataException.

For related corrective actions, see the TIBCO ActiveMatrix BusinessWorks Error Codes manual.

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

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.

PL/I CHAR items withVARYING or VARYINGZ

Padding within a REDEFINEgroup or UNION

The Filler setting is used.

Gaps due to PL/I alignmentor COBOL slack bytes

Any items with their XSDtype set to base64Binary viaCustomize dialog

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

Note that PL/I requires a binary value to be supplied and be theexact size of the item defined in the copybook.

54


Item Type Action

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

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

COBOL zoned and packeddecimal items

COBOL COMP-1 andCOMP-2 items

A zero byte is used as filler.

The cases not described above always require a value, either through a mapping or VALUE/INITclauses.

55


Error Codes

The following are the error codes and messages that are returned by the activities that take place in theData Conversion 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

56


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"Or:Value {2} of depending data element {1} is out of minimum {3} and maximum {4} range for variableoccurring element {0}.

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

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 or invalid encoding

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 expected length 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-500036

57


base64Binary value contains {0} bytes, must be divisible by {1} for type {2}

TIBCO-BW-PALETTE-DATACONVERSION-500037REFER 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

58


Documents

TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion … · 2014-05-30 · TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion User’s Guide Read this manual to