tibco activematrix businessworks plug-in for data conversion user's guide · 2014. 11. 6. ·...

TIBCO ActiveMatrix BusinessWorks™ Plug-infor Data Conversion User's GuideSoftware Release 4.2November 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Overview of Data Conversion Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Examples Sending and Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Language Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

COBOL Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Supported Usages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Supported Picture Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Supported COBOL Clauses and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

DATE FORMAT Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

OCCURS … DEPENDING ON Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Handling of Computation Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

COMP Versus COMP-5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

COMP-6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

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

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

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

SYNC Clause and Slack Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Insert Slack Byte Items Menu Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Alignment Compatibility with Previous Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

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

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

Declarations and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

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

* Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Data Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

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

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

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

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

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

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

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

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

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

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

3


Handling of Items in Binary Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

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

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

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

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

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

Latin Normalization in Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Data Conversion Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Copybook Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Settings Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Copybook Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Import Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Generate from an XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

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

Schema Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Insert Slack Byte Items Menu Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Schema Preview Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Field Configuration Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

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

Control Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

In-Place Copybook Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Generated Schema Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

Parse Copybook Data Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

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

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

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

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

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

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

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

Validation of Elementary Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Connecting Multiple Parse Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Parsing of a Large Number of Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Procedure for Reading in a Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57

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

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

Description Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Output Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

4


Fault Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Item Initialization During Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

5


Figures

Sending or Receiving COBOL Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Receiving Data from a COBOL Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Sending Data to a COBOL Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

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

6


TIBCO Documentation and Support Services

All TIBCO documentation is available on the TIBCO Documentation site, which can be found here:

https://docs.tibco.com

Product-Specific Documentation

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

TIBCO_HOME/release_notes/TIB__version_docinfo.html

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

● TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion User’s Guide 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

7


https://docs.tibco.comhttp://www.tibco.com/services/supporthttps://support.tibco.comhttp://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 generates an XML Schema Definition (XSD) schema for input and output mappingsfor activities.

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

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

Typically, COBOL, PL/I, or RPG applications communicate with other applications by way of amessaging service, such as IBM MQ Series or Java Messaging Service (JMS). These applications can alsoread data from or write data to a file. ActiveMatrix BusinessWorks can retrieve or send COBOL, PL/I,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.

8


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 Handle Incoming Data subprocess.

Receiving Data from a COBOL Application

Sending Data

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

Sending Data to a COBOL Application

9


Language Features

The Plug-in supports a variety of language features.

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

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

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

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

Supported Usages

Usage Notes

BINARY COMP, COMPUTATIONAL

COMP-4, COMPUTATIONAL-4


See Handling of Computation Items.


PACKED-DECIMAL, COMP-6,

COMPUTATIONAL-6

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

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

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

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

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

INDEX

POINTER

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

10


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 PICXXXBX(3)BX(4)

Numeric-edited PIC 99/99/99 PIC-9(7).99 PIC +,++

+,999.00

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

External Floating Point PIC +99.9999E+99PIC -9.99999E-99

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

Numeric PIC 999 PIC 9(5)PIC S9(8) PIC

S9(5)V99

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

11


Clause Notes

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.

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

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

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

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

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

DATE FORMAT Clause

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

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

COBOL Data Pattern

Java Date Pattern

Day First Month First

XX dd MM

XXYY MMyy MMyy

XXYYYY MMyyyy MMyyyy

XXX DDD DDD

XXXYY DDDyy DDDyy

XXXYYYY DDDyyyy DDDyyyy

XXXX ddMM MMdd

XXXXYY ddMMyy MMddyy

XXXXYYYY ddMMyyyy MMddyyyy

12


COBOL Data Pattern

Java Date Pattern

Day First Month First

YY yy yy

YYXX yyMM yyMM

YYXXX yyDDD yyDDD

YYXXXX yyddMM yyMMdd

YYYY yyyy yyyy

YYYYXX yyyyMM yyyyMM

YYYYXXX yyyyDDD yyyyDDD

YYYYXXXX yyyyddMM yyyyMMdd

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

OCCURS … DEPENDING ON Clause

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

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

OCCURS min TO max TIMES DEENDING ON object

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

Rendering

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

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

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

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

Parsing

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

13


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

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

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

Handling of Computation Items

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

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

COMP Versus COMP-5

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

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

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

For more details, see the COBOL documentation.

COMP-6

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

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

14


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 Field Configuration Page.

15


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

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

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

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

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

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

Specifically:

● The Parse Copybook activity adds zeroes to the output values and returns an algebraic value.● The Render Copybook Data activity accepts an algebraic value and removes zeroes at P positions.

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

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

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

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

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

Insert Slack Byte Items Menu Item

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

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

16


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

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

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

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

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

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

Alignment Compatibility with Previous Releases

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

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

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

17


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

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.

18


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

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

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

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

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

Unsupported Attributes

The Plug-in does not support the following attributes:

AREA HANDLE ORDINAL

ENTRY LABEL PICTURE

FILE LIKE TASK

FORMAT OFFSET

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

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

Ignored Attributes

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

BASED EXTERNAL and INTERNAL

CONNECTED and NONCONNECTED RESERVED

DEFAULT STATIC

DEFINED TYPE

19


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;

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.

20


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 length variable in string lengths and array boundaries with theREFER option.

The syntax is:

expression REFER (member-variable)

where:

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

● 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);

21


The Plug-in processes the REFER option as follows:

● During parsing:

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

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

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

● During rendering—

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

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

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

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

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

considers that a runtime error and throws SerializationException.

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

22


Data Types

Data Type Notes

FIXED BINARY

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

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

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

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

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

The endian type is defined by BIGENDIAN or LITTLEENDIAN attribute in thedefinition or, if those attributes are not in the definition, by the activity’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);

23


Data Type Notes

BINARY FLOAT

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

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

For IEEE fields, the representation is as follows:

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

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

● base64Binary for greater precision values.

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

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

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

DECIMAL FLOAT

(precision)The Plug-in represents this data type as base64Binary. The XML 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.

24


Data Type Notes

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

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

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

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

BIT(length) The Plug-in represents this data type as base64Binary. The XML 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.

25


Data Type Supported Constant Type in INITIAL Attribute

FIXED DECIMAL Decimal fixed point constant: 455.1, -1

The Plug-in ignores INITIAL for COMPLEX fields.

BINARY FLOAT

DECIMAL FLOAT

The Plug-in ignores INITIAL for these types.

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

GRAPHICS Graphic constant: '011F'GX

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

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

INITIAL Attribute in Arrays

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

The Plug-in supports this initialization.

Data Alignment

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

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

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

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

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

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

26


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

RPG FeaturesYou 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’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.

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

27


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

28


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

By default, the Plug-in represents elementary items as an XSD type appropriate to the copybookdefinition. For example, the COBOL PICTURE X(10) item appears as a string element with themaximum length of 10 in the schema. To handle an elementary item in binary form instead, selectbase64Binary as an XSD type for an item in the Field Configuration page. Subsequently, the Plug-inrepresents the item as a sequence of bytes with no transformation or validation of the data. You canthen apply custom processing to the binary data. For details, see Field Configuration Page.

Note the following rules:

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

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

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

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

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

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

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

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

De-selecting Fail on Invalid XML Characters may result in a small performance gain in scenarios thatinvolve large amount of data. However, de-selecting this setting does not eliminate errors. The errorsare likely happen later in the application and will be more difficult to track. Only de-select Fail onInvalid XML Characters if your application is guaranteed not to produce the invalid characters.

If your application may produce the invalid characters, you can select XSD Type base64Binary for thecopybook items at risk. However, you will not be able to use string XPath functions.

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

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

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

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

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

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

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

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

● xC and xA — Sign positive

● xB and xD — Sign negative

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

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

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

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

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

30


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

● Use ASCII Zoned Format dropdown list on a Render Copybook Data activity to specify a format.● Pass strict or modified to the input field asciiZonedFormat. This field takes precedence over the

ASCII Zoned Format dropdown.

For PL/I and RPG copybooks, Strict ASCII 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 -.

Modified ASCII Sign Bytes

Sign Byte Sign of Entire Value Decimal Digit in Sign Byte

0x7B Positive 0

0x41 Positive 1

0x42 Positive 2

0x43 Positive 3

0x44 Positive 4

0x45 Positive 5

0x46 Positive 6

0x47 Positive 7

0x48 Positive 8

0x49 Positive 9

0x7D Negative 0

0x4A Negative 1

0x4B Negative 2

0x4C Negative 3

0x4D Negative 4

0x4E Negative 5

0x4F Negative 6

0x50 Negative 7

31


Sign Byte Sign of Entire Value Decimal Digit in Sign Byte

0x51 Negative 8

0x52 Negative 9

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 ample

32


precision for your application. For example, if you are likely to push the limits of the Float format,choose Double where you are able.

33


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.

34


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.

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

General Section

Field Description

Package The name of a package that contains this resource.

Name The name of the resource label.

Description A short description of the copybook resource.

Settings Section

Field

LiteralValue/ModuleProperty? Description C P R

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

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

x x x

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

x

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

x

35


Field


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

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

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

For details, see Handling of Floating PointItems .

x x

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

x

Alignmentprocessing

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

See Alignment Compatibility with PreviousReleases.

x

Advanced Section

Field


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

x x x

Generate button No Generates a unique namespace. x x x

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

x x x

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

x x x

36


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

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

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

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

— Revert to the original— Generate from a schema... (COBOL only)— Insert slack byte items (COBOL only)— Save to a file...

For details, see In-Place Copybook Editing.

Field


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

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

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

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

● 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

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

x x

37


Import Button

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

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

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

Generate from an XML Schema

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

Mapping of XML Schema Types to COBOL

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

In this table xs refers any of the three namespaces:

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

Schema Simple Type COBOL Clause

xs:anyType

xs:anySimpleType

xs:anyURI

PIC X(255)

38


http://www.w3.org/2001/XMLSchemahttp://www.w3.org/2000/10/XMLSchemahttp://www.w3.org/1999/XMLSchema


xs:base64Binary

xs:ENTITIES

xs:ENTITY

xs:hexBinary

xs:ID

xs:IDREF

xs:IDREFS

xs:language

xs:Name

xs:NCName

xs:NMTOKEN

xs:NMTOKENS

xs:normalizedString

xs:NOTATION

xs:QName

xs:string

xs:token

PIC X(...)

xs:boolean PIC X DISPLAY

xs:byte

xs:int

xs:integer

xs:long

xs:negativeInteger

xs:nonPositiveInteger

xs:short

PIC S9(x) COMP

where xs:totalDigits value="x"

PIC S9(default-x) COMP-5

if xs:totalDigits does not exist

See Schema Simple Types for the default values.

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

where x is one of the following default dateformats:

● YYYYXXXX

● YYYYXXX

● XXXXYYYY

● XXXYYYY

39



xs:dateTime

xs:duration

xs:time

PIC X(32)

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

where:

● xs:totalDigits value="x"

● xs:fractionDigits value="y"

xs:double USAGE COMP-2

xs:float USAGE COMP-1

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

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

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

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

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

xs:nonNegativeInteger

xs:positiveInteger

xs:unsignedByte

xs:unsignedInt

xs:unsignedLong

xs:unsignedShort

PIC 9(x) COMP-5

where x is defined by the following rules:

● x = the value of xs:totalDigits

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

See Schema Simple Types for the default lengthvalues.

Schema Simple Types

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

Schema Simple Type Default Length

xs:byte

xs:unsignedByte

1

xs:short

xs:unsignedShort

4

40


Schema Simple Type Default Length

xs:int

xs:unsignedInt

9

xs:integer

xs:negativeInteger

xs:nonPositiveInteger

xs:long

xs:nonNegativeInteger

xs:positiveInteger

xs:unsignedLong

18

Notes

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

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

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

Insert Slack Byte Items Menu Item

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

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

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

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

41


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

The new layout is fully compatible with the original copybook.

tibco activematrix businessworks plug-in for data conversion user's guide · 2014. 11. 6. ·...

Documents