biztransactions v7.0 application integration with business...

BizTransactions V7.0

Application Integration with Business Objects

Edition: June 2005

Copyright © Fujitsu Siemens Computers GmbH, 2005.All rights reserved. Delivery subject to availability; right of technical modifications reserved.

All hardware and software names used are trademarks of their respective manufacturers.

This manual was produced bycognitas. Gesellschaft für Technik-Dokumentation mbHwww.cognitas.de

http://www.cognitas.de


Contents1 Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.1 Characteristics of the product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.1.1 Product structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.1.2 Host applications currently supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.1.3 Other shipped programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.2 Concept and target group of this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151.3 Further information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.4 Changes since the last version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.5 Notational conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2 Concept of BizTransactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.1 Performance overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.2 Components of the development system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.2.1 BizTransactions Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.2.2 BizTransactions catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292.2.2.1 Catalog Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292.2.2.2 Catalog Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322.2.3 BizTransactions Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352.2.4 BizTransactions Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352.2.5 BizTaConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362.2.6 BizTransactions Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362.3 Components of the runtime system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372.4 Building business objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3 BizTransactions Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.1 Working with BizTransactions Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.1.1 Calling the BizTransactions Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.1.2 Dialog boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.1.3 Additional information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443.1.4 Locked objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443.2 Selecting an existing catalog or creating a new one . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.3 Selecting an existing host application or creating a new one . . . . . . . . . . . . . . . . . . . . . 463.4 Selecting an existing business object or creating a new one . . . . . . . . . . . . . . . . . . . . . 473.5 Selecting an existing method or creating a new one and starting recording . . . . . . . . . 483.6 Recording a dialog and editing a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49


Contents

3.7 Generating a business object and test interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493.8 Testing the business object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4 BizTransactions tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.1 Reading the openUTM application services into the catalog . . . . . . . . . . . . . . . . . . . . . 524.1.1 Converting the openUTM application formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534.1.2 Creating a new UTM application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544.1.3 Importing service data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584.2 Generating a business object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614.2.1 Creating a business object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614.2.2 Defining a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634.2.3 Define method parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654.2.4 Recording a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684.3 Editing a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734.3.1 Editing the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734.3.2 Generating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844.3.2.1 Generating a business object and test interface for Java . . . . . . . . . . . . . . . . . . . . . . . 844.3.2.2 Generating and deploying a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904.3.2.3 Calling a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

5 BizTransactions Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955.1 Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955.2 Working with BizTransactions Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965.2.1 The main window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965.2.2 The catalog window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985.2.3 The Edit window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015.2.4 The status bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035.2.5 The Administration menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045.2.5.1 Check Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045.2.5.2 Compact Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045.2.5.3 Save Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045.2.5.4 Merge Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055.2.5.5 Administering locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055.2.5.6 Administer Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065.2.5.7 Show User Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065.2.5.8 Check Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065.2.5.9 Check Capture Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075.2.6 Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085.3 Creating a catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095.4 Creating a new host application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111


Contents

5.5 Creating a new service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135.5.1 Importing a service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135.5.1.1 Converting openUTM program units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145.5.1.2 Importing service data of UPIC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195.5.1.3 Importing service data of terminal applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205.5.2 Creating your own services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215.6 Declaring business objects and their interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1235.6.1 Creating a business object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1235.6.2 Defining a new property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245.6.3 Defining a new method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245.6.4 Defining a new method parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255.6.5 Internal checking of specified names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265.7 Editing methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1275.8 Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1275.8.1 Generation options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1285.8.2 Generating business object classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315.8.2.1 Generation results for .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325.8.2.2 Results of the Java generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355.8.2.3 Generation results for ActiveX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375.8.3 Generating a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415.8.3.1 Generating and deploying a Java web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415.8.3.2 Generating and deploying .NET web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1435.8.3.3 Activating WSDL generation for Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505.9 Creating report files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

6 Editing the code of a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1536.1 The Edit method window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1536.1.1 The modeling area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556.1.2 The programming area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556.1.3 The code tree structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1566.2 Recording dialogs for UPIC applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576.2.1 The Record Dialog window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576.2.2 Record Dialog with a UPIC application without a formatted presentation . . . . . . . . . . 1596.2.3 Dialog with a UPIC application with formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616.3 Recording dialogs for terminal applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626.3.1 The Record method window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636.3.2 Recording a dialog with a terminal application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1656.3.3 Format recognition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1676.3.3.1 Creating recognition criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686.3.3.2 Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686.3.3.3 Conflicts during format recognition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696.3.4 Recursive formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172


Contents

6.4 Modeling a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776.4.1 Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786.4.2 Inserting a new service node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796.4.3 Deleting service nodes and connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806.4.4 Adapting the layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806.4.5 Displaying and modifying service nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1816.4.6 Modeling unknown formats (BizTaUnknown) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1836.4.7 Modeling a flow without format recognition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856.4.8 Saving the chart and closing the modeling session . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866.5 Editing statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876.5.2 Compatibility checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1936.5.3 Editing statements after capturing a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1966.5.3.1 Tips on editing the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1966.5.3.2 Selecting variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1996.5.3.3 Predefined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2076.5.3.4 Inserting freely programmable statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2166.5.3.5 Functions in the Extras menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196.5.4 Editing statements during method capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2346.5.4.1 Views in the Record method window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2346.5.4.2 Implicitly inserted statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2446.5.4.3 Defining lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2456.5.4.4 Tips on editing code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2496.6 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2516.6.1 Host application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2516.6.2 Creating stateless methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2536.6.3 Creating stateful methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

7 Installing and configuring BizTransactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2617.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2617.1.1 Installation via the user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2637.1.2 Silent installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2657.2 Configuring the development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2677.2.1 Checking the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2687.2.2 Modifying the Hosts file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2687.2.3 Configuring the openUTM host application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2697.2.3.1 Adapting openUTM generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2697.2.3.2 Declaring the client computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2727.3 Configuring the runtime system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2737.4 Performance notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274


Contents

8 Client interface of business objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2758.1 Basic principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2768.1.1 Business object class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2768.1.1.1 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2778.1.1.2 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2798.1.2 Service classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2808.1.3 Class module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2808.1.4 BizTaConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2818.2 Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2858.2.1 Business object class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2858.2.1.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2858.2.1.2 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2888.2.1.3 Methods for arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2958.2.1.4 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2958.2.2 Service classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3008.2.2.1 Property access methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3008.2.2.2 Processing methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3018.2.3 Utility classes of the runtime system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3028.2.3.1 BizTaVariant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3028.2.3.2 BizTaSup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3028.2.4 BizTaConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3038.2.4.1 Access methods for properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3038.2.4.2 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3058.2.4.3 Connection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3078.2.5 BizTaException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3098.3 .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3108.3.1 Business object class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3108.3.1.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3108.3.1.2 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3128.3.1.3 Methods for arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3138.3.1.4 Calling methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3148.3.1.5 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3228.3.2 Service classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3248.3.3 User-defined classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3258.3.4 BizTaConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3278.3.4.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3278.3.4.2 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3288.3.4.3 Connection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3308.3.5 BizTaException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331


Contents

8.4 ActiveX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3338.4.1 Business object class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3338.4.1.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3338.4.1.2 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3358.4.1.3 Methods for arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3358.4.1.4 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3368.4.2 Service classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3388.4.2.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3388.4.2.2 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3388.4.3 BizTaConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3398.4.3.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3398.4.3.2 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3418.4.3.3 Connection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

9 Diagnostic tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3459.1 Business objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3459.1.1 Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3469.1.2 .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3489.1.3 Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3529.2 Host adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3549.3 Return codes of business object methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

10 BizTransactions Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35710.1 Starting Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35810.1.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35910.1.2 Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36010.2 The user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36110.3 Logging settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36210.4 Recording sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36410.5 Viewing the central log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36710.6 Terminating Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

11 Using business objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36911.1 Business objects in Microsoft Visual Studio .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36911.1.1 Transferring business objects to Microsoft Visual Studio .NET . . . . . . . . . . . . . . . . . . 36911.1.2 Configuring properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37011.1.3 XML documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37111.2 Loosely coupled asynchronous web calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37211.2.1 Criteria for generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37511.2.2 Business object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37511.2.3 Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37611.2.3.1 BizTaGetId method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37711.2.3.2 Query_Start method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37711.2.3.3 Query_Read method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378


Contents

11.2.3.4 Query_Clear method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37811.2.3.5 Query_Status method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37811.2.3.6 Query_ReadDataset method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37911.2.3.7 Request status information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37911.2.3.8 Retrieving the (intermediate) results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38011.2.4 Storing (intermediate) results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38311.2.4.1 .NET web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38311.2.4.2 Java web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38411.2.5 Writing intermediate results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38611.3 Office Research web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38711.3.1 Preparations for use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38811.3.2 Calling an Office Research web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

12 Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39112.1 Special applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39112.2 Business objects and threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39512.2.1 Java and .NET destructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39512.2.2 Java, .NET and Visual Basic applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

Eine Dokuschablone von Frank Flacheneckerby f.f. 1992

Application Integration with Business Objects 11

1 PrefaceOver the past few years, more and more IT users have found themselves working in hetero-geneous system and application environments, with mainframes standing next to UNIX and Windows systems and PCs operating alongside terminals. Different hardware, operating systems, networks, databases and applications are operated in parallel. Highly complex, powerful applications are found on mainframe systems, as well as on UNIX and Windows servers. Most of these have been developed with considerable investment costs to obtain optimum support.

These business-critical applications can often only be migrated to standard software at great expense and at the cost of some functionality. This is why the integration of existing heterogeneous applications in a uniform, transparent IT concept is a key requirement for modern information technology. Flexibility, investment protection, and openness to new technologies are thus of crucial importance.

With BizTransactions you can continue using your existing applications and automate them as well. Data can be acquired, transactions can be executed and processes can be supported without changing the business-critical application.

To accomplish this, BizTransactions works with business objects. These are logical units that allow for simple and object-oriented access to the services of existing applications. Business objects consist of properties (e.g. “customer” or “invoice”) and methods (e.g. “modify customer address”). BizTransactions allows you to create business objects from existing applications without the need for any additional programming.

12 Application Integration with Business Objects

Characteristics of the product Preface

1.1 Characteristics of the product

With BizTransactions you can integrate existing host applications into new applications. To do this you create business objects from existing BS2000/OSD (e.g. openUTM, DCAM) and MVS or z/OS dialog applications on the basis of Java, the .NET or ActiveX technology. Each business object represents a logically connected functional unit of a host application. Through their properties and methods, they offer object-oriented access to the host appli-cations.

Existing host applications are accepted as they are. It is not necessary to change the appli-cation logic. The host applications are addressed by BizTransactions via the existing, tried-and-tested interfaces.

You canintegrate the host applications in different environments with the business objects. You can also combine business objects with the following to form an integrated application:

● .NET components

● ActiveX/COM components

● Java objects (J2EE, J2SE)

● Web services (WSDL)

● WebTransactions

This allows you to access the server application from a Windows or Solaris platform.

Integration with BizTransactions offers many advantages - both for developers in IT depart-ments and for IT users:

● Business objects provide a uniform view of different host applications.

● The host applications need not be modified.

● New techniques (.NET, Java, web services) can be combined with proven mainframe applications without any problems. Large-scale investment in mainframe applications is thus protected in the long term.

● Coexistence: the mainframe applications can also continue to be used in parallel through the established interfaces without any consistency problems.

● Productivity is increased in the areas of IT integration and applications development thanks to powerful generators and PC-based development environments.

● The productivity of IT users is increased. Appropriate interfaces can be supplied to the different user groups.


Preface Characteristics of the product

1.1.1 Product structure

BizTransactions is subdivided into a number of components:

● The development environmentThe components of the development environment only run on Windows platforms. The development environment consists of:

– BizTransactions Studio

– BizTransactions Wizard

– BizTransactions Administration

– BizTransactions catalog migration from V2.0 to V3.0 (version V3.0 catalogs are automatically migrated to version V7.0 when you open them in BizTransactions Studio or BizTransactions Wizard.)

The components of the development environment are shipped together as the selectable unit WebTransactions Business Object Builder.

● The environment for the connection of host applications

– The runtime systemThe runtime system contains components for Java, Visual Basic and .NET.

– The host adaptersDepending on the host applications that you want to integrate, you can install one or more of the following host adapters:

– 9750 connection– openUTM(UPIC) connection– 3270 connection

The host adapters and runtime system are shipped with the corresponding selectable unit, WebTransactions for OSD, WebTransactions for openUTM and WebTransactions for MVS (see the WebTransactions manuals “Connection to OSD Applications”, “Connection to openUTM Applications via UPIC” and “Connection to MVS Applica-tions”).


Characteristics of the product Preface

1.1.2 Host applications currently supported

BizTransactions supports the following host application types:

● openUTM applications that exchange data via the UPIC interface

– openUTM applications whose program units use FHS formats to exchange data

– openUTM applications whose program units use different data structures to exchange data (e.g. applications implemented in COBOL or DRIVE)

● BS2000/OSD terminal applications that exchange data via the 9750 terminal interface (e.g. openUTM or DCAM applications)

● MVS terminal applications that exchange data via the 3270 terminal interface

Additional host adapters for host applications can be developed upon request as project-specific BizTransactions direct solutions. You will find more information on this subject athttp://www.fujitsu-siemens.com/openseas.

1.1.3 Other shipped programs

Various software components are shipped as add-ons with BizTransactions. You will find these programs and the associated documentation under AddOns in the BizTransactions installation directory.

The AddOns directory contains programs for

● using business objects in Microsoft Word, Microsoft Excel and Microsoft Access

● testing any required web services

● creating and using business objects in portals:selflets or self-service business objects and portals

There is also a portlet that permits the seamless integration of WebTransactions applications when these are to be used in the Oracle portal or in portals that support the JSR168 portlets. You can download this portlet and the associated documentation from the WebTransactions home page: http://www.Fujitsu-Siemens.com/WebTransactions

http://www.Fujitsu-Siemens.com/WebTransactions

http://www.fujitsu-siemens.com/openseas


Preface Concept and target group of this manual

1.2 Concept and target group of this manual

This manual is intended for anyone who wishes to create business objects for accessing host applications in order to

● provide the services of existing mainframe applications as JavaBeans or .NET compo-nents

● develop graphical interfaces for host applications (e.g. through GUIs created with WebTransactions, Microsoft Visual Studio .NET, Visual Basic, Visual C++, JBuilder, Microfocus NetExpress or Java)

● provide host applications as web services

● integrate interactions with host applications in Microsoft Office products (e.g. integrate the current data of an openUTM mainframe application in Excel tables).

The first part of this manual describes the BizTransactions concept and the development environment.

● Chapter 2 explains the concept behind BizTransactions.

● Chapter 3 presents BizTransactions Wizard.

● Chapter 4 presents a detailed tutorial to help you get to know the basic concepts involved in working with BizTransactions.

● Chapter 5 presents the BizTransactions development environment - BizTransactions-Studio - and describes the most important functions.

● Chapter 6 presents how you can edit the code of a recorded method in BizTransactions Studio.

The second part of the manual is used for reference. It describes:

● in chapter 7 the installation of BizTransactions.

● in chapter 8 the client interface of business objects.

● in chapter 9 the diagnostic capabilities.

● in chapter 10 the administration of BizTransactions.

Chapter 11 of this manual indicates various ways of using business objects.

You do not need any special programming knowledge to read this manual: knowledge of a high-level programming language is recommended but not essential. To analyze host appli-cations and design business objects, you will need some degree of familiarity with the structure and operation of the host applications but do not need to be a “legacy expert”.


Further information Preface

1.3 Further information

In addition to the current manual, you can find further information

● on the software components shipped as add-ons with BizTransactions, in the BizTransactions installation directory under AddOns (see also section “Other shipped programs” on page 14).

● on the tutorials supplied with BizTransactions, in the BizTransactions installation directory under Examples\Documents.

● on the portlets and selflets that are made available free-of-charge with version 7.0, on the WebTransactions home page: http://www.Fujitsu-Siemens.com/WebTransactions.



Preface Changes since the last version

1.4 Changes since the last version

This section provides a general overview of the most important innovations in BizTransactions version 7.0 and indicates where you can find a more detailed description:

Type of new feature Description

Product structure:– The components of the development environment are

shipped as the selectable unit WebTransactions Business Object Builder.

– The host adapters and runtime system are shipped with the corresponding selectable unitWebTransactions for OSD, WebTransactions for openUTM or WebTransactions for MVS.

page 13, page 24, page 37

WebTransactions manuals“Connection to OSD Appli-cations”,“Connection to openUTM Applications via UPIC”,“Connection to MVS Appli-cations”

Installation:– Installation has been converted to the Windows Installer

procedure (msi package).– During installation, you can decide whether or not to

install Sun Microsystems’ Java Web Services Developer Pack (JWSDP).

– During installation, you can select the servlet engine for JWSDP.

page 261

Migration:BizTransactions version V3.0 catalogs are migrated automat-ically when you open them in BizTransactions Studio or BizTransactions Wizard.

page 109

BizTransactions Wizard:– The newly developed BizTransactions Wizard provides a

guided dialog for the quick, easy creation of business objects that communicate with host applications via the 3270 or 9750 emulation protocols.

– BizTransactions Wizard is also integrated in the WebTransactions development environment WebLab.

page 41

WebTransactions manual “Concepts and Functions”


Changes since the last version Preface

Support for .NET:– You can generate the following in BizTransactions Studio:

– .NET business objects and test interfaces– Web services for .NET

– The WSDL generation of .NET web services is per-formed automatically using Microsoft’s .NET Framework. The .NET Framework software must be present before BizTransactions can be installed.

– The business object client interface provides you with the corresponding methods and properties as well as service classes, user-defined classes and the BizTaConnection interface for .NET business objects.

– The Trace class is used in .NET to output diagnostic messages and WriteLog messages.

page 131page 143page 143

page 310

page 348

Support for Java– To generate Java web services, you can use Sun

Microsystems’ Java Web Services Developer Pack V1.3 (JWSDP 1.3) which is shipped with BizTransactions.

– The web service is deployed automatically if you select-ed the corresponding servlet engine when installing JWSDP and the servlet engine is running.

– For Java, the business object client interface also provides you with the event classesBizTaFormatEvent and BizTaIntermediateResult as well as the class BizTaException.

page 141

page 142

page 285

Calling web services:The add-on CallWebServices is supplied withBizTransactions V7.0. You can use this to create a client proxy class for a web service on the basis of a WSDL file and test the web service.

page 14, page 93

Editing a method’s code:In the case of terminal applications, it is usually possible to generate the complete code of a method at recording time. You can:– edit the method’s statements during recording and– model the method directly after recording

page 162

page 234page 177

BizTransactions administration:When you start the administration function, you can specify the configuration directory and port number via which the administration function communicates.

page 358



Preface Changes since the last version

Loosely coupled, asynchronous web service calls:In the case of unstable connections and relatively long queries to the host, a client may start a request that runs independently on the Web server. The client can retrieve the results at any time. Intermediate results can also be retrieved if the business object permits this.

page 372



Notational conventions Preface

1.5 Notational conventions

The following notational conventions are used in this manual:

Notational Convention Meaning

typewriter font Fixed components which are input or output in precisely this form, such as keywords, URLs, file names

italic font Variable components which you must replace with real specifications; also used for menu items

bold font Items shown exactly as displayed on your screen or on the graphical user interface; also used for menu items

[ ] Optional specifications; do not enter the square brackets themselves

{alternative1 | alternative2 } Alternative specifications. You must select one of the expressions inside the braces. The individual expressions are separated from one another by a vertical bar. Do not enter the braces (curly brackets) and vertical bars themselves.

... Optional repetition or multiple repetition of the preceding components

Important notes and further information

Warning

Ê This indicates an action that must be performed.

i

!


2 Concept of BizTransactions

With BizTransactions you can create business objects without any additional programming from existing BS2000/OSD (e.g. openUTM, DCAM) and MVS dialog applications.

Business objects are logical units that allow simple and object-oriented access to the services of existing host applications. Business objects consist of properties (e.g. “Customer Address” or “Invoice Number” ) and methods (e.g. “Change customer address”).

With BizTransactions you can record application sessions from the point of view of a staff member and obtain the methods of the business objects from the recording. The BizTransactions Generators create business objects

● as .NET and ActiveX components that can be combined in any manner with other .NET and ActiveX components and that permit full access to the host applications from a Windows platform.

● as Java classes that are executable in every Java environment and are therefore also permit full access to the host applications from UNIX platforms.

● as web services based on WSDL that permit full access to the host applications when you integrate them into your Web server.

2.1 Performance overview

Most companies today operate a heterogeneous system landscape: applications and data relevant to the business are distributed among PC servers, department hosts or main-frames, depending on the need. Standard software and individual solutions coexist, and there is a number of different operating systems and data storage environments.

In order for the business processes to run smoothly, all applications and data must be available at the location they are needed. Furthermore, you should be able to connect the data and applications as desired to further development and optimize the business processes.

To solve these problems, you need software that runs on your existing systems and with your existing applications (in which you have made a large investment) that is available without any change for various types of clients.


Performance overview Concept of BizTransactions

Figure 1: Integrating host applications

BizTransactions provides a quick, simple, low-risk means of developing and operating integration solutions. Thanks to its modular, open concept, BizTransactions is highly future-proof, thereby guaranteeing your investment in the long term.

Working with BizTransactions is …

fast

There is no need to reorganize your existing IT infrastructure. The host applications are addressed via the existing interfaces. It is not necessary to change the architecture, program structures, or data models.

simple

BizTransactions offers you high-functionality, user-friendly tools for analyzing host applica-tions and modeling business processes. For example, dialog processes can be recorded automatically. The recorded processes can be adapted and combined on the graphical level. This allows you to model new business rules without the need for manual coding.

The modular concept (services, business objects, business process objects) ensures overall clarity, because you work with graphic tools and simple, comprehensible units even on the level of integration beyond application and platform boundaries.

Client

UPIC

ActiveXAppl.

Web Browser

Terminal

Host applications BS2000/OSD, MVS, openUTM

BizTransactions 9750/3270

UPIC/9750/3270

(D)COMWeb-

Java Appl.

Java VM

Server

Web

MSOffice

.NET Appl.

Web Service Client

Transactions Service


Concept of BizTransactions Performance overview

without risk

The availability of your host application is not affected at any time during the development and operation of the integration solution. With BizTransactions, you implement the integration in a separate, independent layer.

The existing user interfaces are retained, and you can even continue to operate them parallel to the integration solution. This means, for example, that some users can use the integrated layer and work with host applications on the business process level, while at the same time other users can continue to access individual host applications directly via the conventional interfaces.

The transition to the integration solution can be a gradual process. In this way, the require-ments of different user groups can be taken into account, and the risk of acceptance problems can thus be avoided.

When the integration solution is running, absolute security and reliability is guaranteed by the transactional infrastructure on which BizTransactions is based.

future-proof

Thanks to its open architecture, BizTransactions is highly future-proof. New applications can be incorporated effortlessly into the integration solution at any time. This applies not only to applications you have developed yourself, but also to ready-made components and standard solutions. BizTransactions supports this feature by providing additional host adapters.

In the openSEAS cluster

BizTransactions supports the openSEAS cluster. The BizTransactions generators provide the business objects as JavaBeans or as web services for WebTransactions.


Components of the development system Concept of BizTransactions

2.2 Components of the development system

The BizTransactions development system consists of the following components:

● BizTranactions Studio, which you use to

– create and maintain BizTransactions catalogs

– analyze the interfaces of host applications

– import the converted service data in the BizTransactions catalog and

– form business objects based on the data in the catalog

● BizTransactions Catalog with its catalog objects and elements that serves as the central database of the BizTransactions development system. You can create several catalogs using the BizTransactions Studio.

● BizTransactions Migration with which you can migrate version V2.0 catalogs to version V3.0 (version V3.0 catalogs are automatically migrated to version V7.0 when you open them in BizTransactions Studio or BizTransactions Wizard.

● BizTransactions Administration with which you administer the business objects at runtime

● BizTransactions Wizard, which provides a quick and simple way of creating business objects that communicate with host applications via the 3270 or 9750 emulation protocols


Concept of BizTransactions Components of the development system

The diagram below shows the tasks performed by BizTransactions Studio and the BizTransactions Catalog during the development phase.

Figure 2: BizTransactions components in the development system

BizTransactions Studio

Record dialog

BizTransactions Catalog

Create/ Use/

Test interfaces

Format recognition

extend

Host ApplicationopenUTM (via UPIC), openUTM (via 9750), BS2000/OSD (9750), MVS (3270)

Automatic

interfaces

maintain generation

BusinessObject

JavaBean

WSDL fileWeb service

importAnalyze/

.NET componentActiveX component



2.2.1 BizTransactions Studio

The BizTransactions Studio provides a graphical development environment for BizTransactions applications and contains all the tools you need to

● create and manage a BizTransactions catalog and

● create business objects.

A catalog must be created before you begin building business objects.

You create an entry (name, access data) in the BizTransactions catalog for each host appli-cation to be integrated. You can then import the service data of the host application into the catalog.

How you import the host applications into the catalog depends on the communication protocol of the host application:

● openUTM applications based on UPICIn the case of host applications that communicate via UPIC and use FHS formats, you can use the IFG2FLD conversion tool. IFG2FLD analyzes the interfaces (FHS formats) and converts them to the XML format. Use the d.xmlprog or d.xmlcopy conversion tools for host applications that do not use screen formats to exchange data but use COBOL data structures instead. These proce-dures analyze the data structures of a COBOL program unit or of a COBOL copy element and convert it to the XML format.Drive Version V3.1 and higher can output the data structures of program units in XML format.

You then import the converted service data. The Studio creates a service in the catalog for each screen format or each data structure of the host application. This service reflects the structure of the screen format, see section “Importing a service” on page 113.

● 9750 or 3270In the case of host applications that communicate via the 9750 or 3270 emulation protocol, but do not (in the case of 9750) use FHS formats, you create the service data when recording the method (see section “Recording dialogs for terminal applications” on page 162).

● Host applications with FHS formats via 9750In the case of FHS applications that communicate via the 9750 emulation protocol, you have two options: analyze and import or capture the methods (see section “Recording dialogs for terminal applications” on page 162).



After that you define the business objects as well as their properties and methods. BizTransactions offers easy to use tools with graphical interfaces for all steps you need to perform to create business objects. Here are some examples:

● You record the methods with the Record Method function. You go through the dialog steps in a model session with the host application. When you do this, the Studio records all dialog steps as intermediate code that is to be executed later when the method is called.

● The processing sequence recorded is then displayed with the Model Method function in a symbolic diagram of the recorded workflow. On this symbolic level, it is possible to modify the processing sequence (e.g. remove superfluous dialog steps, combine repet-itive dialog steps, or add new dialog steps).

● The code recorded during the session can be modified with the Edit Code function. Instead of statements in a specific programming language, this code is in the form of easy-to-follow intermediate code. You do not have to be a programming expert to under-stand the statements, as their meaning is immediately apparent (e.g. FunctionKey: "DUE").

You can use the generators of BizTransactions Studio to create:

● .NET and ActiveX components that can be combined in any manner with other .NET/ActiveX components and that permit full access to the host applications from Windows platforms

● Java classes that are executable in every Java environment and therefore also permit full access to the host applications from UNIX platforms and J2EE application servers

● Web services available on the internet and for which you can create the corresponding clients, for example with WebTransactions



The following figure shows what capabilities are provided by the BizTransactions Studio generators:

Figure 3: Generation results

Test-BusinessObject

ActiveX JavaBeanComponent

JavaSource

VBSource

VBProject

.jar

.dll

Test Environment

Interfaces

BizTransactions Studio

JavaTest

.NETTest

.NETComponent

VB .NETSource

VB .NETProject

.dll

VBTest

WebService

StartProcedure



2.2.2 BizTransactions catalog

During the development phase, the BizTransactions catalog is the central database of BizTransactions. In the catalog you store descriptions of the host applications (name, access data), for example.

The BizTransactions catalog contains all the information on the application interfaces in the form of services. It is immaterial whether this information originates from an analysis/import, or while capturing the methods (see sections “Recording dialogs for UPIC applications” on page 157 and section “Recording dialogs for terminal applications” on page 162).

The BizTransactions catalog also contains all the information defined when creating business objects (e.g. name, type and default value of properties, and the code generated when capturing methods).

When generating a business object class, BizTransactions Studio accesses this data. Together with the business object class, a service class is generated automatically for each service used.

The data in the catalog can be divided into catalog objects and catalog elements.

2.2.2.1 Catalog Objects

The BizTransactions objects, or actually the descriptions of the objects, are stored in the catalog. The following can be catalog objects:

● Host applications

● Services

● Business objects

● Classes

● Functions

You create all these catalog objects with BizTransactions Studio. The catalog objects are described in more detail by their elements and attributes.

Host Application

Dialog applications in BS2000/OSD and MVS as well as transaction applications with openUTM can be integrated.

The host adapter concept of BizTransactions is flexible. If your implementation scenario requires special host adapters that are not yet contained in the product, they can be made available promptly on request.



Service

With BizTransactions, host applications are first broken down into elementary units: the individual services. These units are then used in the BizTransactions Studio to model your business objects.

A service thus corresponds to a dialog step. Depending on the type of host application, it may represent

● a 9750 screen format

● a 3270 screen format

● an openUTM dialog step (in the case of interconnection via UPIC) which is distinguished by

– the FHS format– the data structure of a DRIVE procedure– the data structure of a UPIC message buffer (e.g. the data structures of a COBOL

program)

Business object

Business objects offer a uniform view of the most varied types of host applications. Existing host applications can be represented as a list of business objects. Through its methods, each business object implements a specific, logically connected functional unit. The methods of a business object require input parameters and return a result in one or more output parameters.

A business object often represents only a very small section of the entire functionality of a host application. The procedures required to provide these subfunctions are generally very simple compared to the complexity and variety of options normally provided in a host appli-cation which has grown over the years or which was designed for a large number of users.

The list of business objects need not reflect the entire functionality of the host applications, rather only those parts that are required for the respective business process. When designing business objects, therefore, a complex application can be reduced to a set of simple, clearly defined units.

Business objects

... create stable data and function blocks

... structure existing host applications

... automate dialog processes

... are the interfaces to host applications



Figure 4: Sample business object can’t edit

Classes

In BizTransactions the catalog object class contains only properties thus considering a class also as a user-defined data structure. Access methods for the class properties are added through generation.

A class has a name and a description and can be used by the following catalog elements:

● Properties of business objects

● Properties of other Classes

● Method parameters

● Function parameters

The properties of a class have attributes depending on the data type.

Data transfer and conversionbetween properties and datafields in the data stream

Each methodinitiates a specific sequenceof dialog steps

Business object (BO)

Account

Properties

Methods

Account no.BalanceNameAddress

CreateDeleteCheckDepositWithdrawal

Host application



Function

In BizTransactions, functions are sections of code with a name and parameters. Functions can be called in business object methods using a description of the function interface (or signature).

You use functions to incorporate your own functionality into the integrate BizTransactions application. You create a function in the Visual Basic or Java languages.

2.2.2.2 Catalog Elements

Catalog elements define an object in a catalog in more detail. For example, a service is not only defined by its attributes, but it also contains the buffer element. There are the following catalog elements:

● Properties of business objects or Classes

● Method parameter

● Function parameter

● Buffer

● Record

● Field

Property

Properties define a business object in more detail. They are elements of business objects or classes. Properties can be queried and their values specified. The attributes of a property depend on its data type.

Parameter

Parameters are elements of a method or a function. They specify which values the method or function contains for processing (input parameters) and which values the method or function return (output parameters). The attributes of a parameter depend on its data type.



Buffer

A buffer is the definition of a record that is transferred by a service. The buffer is used to send and receive messages and is an element of a service. A buffer contains records and fields as elements.

A buffer is a memory area that is defined by its length and its location in the memory. The Direction attribute specifies the direction in which the data in the buffer is transferred:

● Data is received by the host (Receive)

● Data is sent to the host (Send)

● The buffer contains data for both directions (Both)

If a service does not contain any buffers, then there aren’t any memory areas either. The service cannot send or receive data in this case. When a service contains one or more buffers with the direction Both, then both the sending and the receiving memory areas exist.

A service can also contain several buffers with the same direction setting. The memory area for this transfer direction is present in this case. It begins at Position 0 and its size is deter-mined by the position and length of all buffers for this direction.

Figure 5: Memory area for several buffers for one direction

If a service description contains buffers with different directions, then separate memory areas are created for sending and receiving. Buffers with the direction Both are created in both the sending and the receiving memory areas. The memory area for a transfer direction always begins at Position 0 and its size is determined by the position and length of all buffers in this direction. The total length of a memory area for a direction can be a maximum of 32,767 bytes.

Send buffer 1 (0-999)



Total send area (0-2000)



Figure 6: Memory areas for several buffers for different directions

In the Send and the Receive statements you can specify whether the data of the entire service or only the data of a specific buffer for the relevant direction is to be transferred.

When there are separate send and receive areas, the send area is always used for write accesses (e.g. a field as the left side of a Move, Call, Concat or Eval statement), while the receive area is always used for read accesses (e.g. a field as part of the right side of a Move, Concat or Eval statement).

Record

A record is the definition of a set of related data which is transferred by a service. It is used for send and receive operations.

Field

A field is the smallest component of a service and element of a record or buffer.


Receive buffer 1 (1200-1800)

Both (800-1500)

Total send area (0-1500)

Both (800-1500)

Receive buffer 2 (0-600)

Total Receive area (0-1800)



2.2.3 BizTransactions Migration

With the BizTransactions migration tool you can migrate catalogs from BizTransactions Version V2.0 to BizTransactions Version V3.0. Version V3.0 catalogs are automatically migrated to Version V7.0 when you open them in BizTransactions Studio or BizTransactions Wizard.

After the first test run with BizTransactions Migration, you are presented with a log in which the following locations are listed:

● those locations where problems may arise and why they may arise

● those locations where you need to prepare the catalog to be migrated.

The preparatory and follow-up work is described in the BizTransactions Migration online help system.

2.2.4 BizTransactions Administration

The Administration tool provides a graphical interface for administering BizTransactions at runtime.

It offers the following functions:

● The administration supports error diagnostics: For example, you can define logging settings and activate/deactivate traces, for example.

● You can display the current log file with it.

● It allows you to configure the recording of emulation sessions and emulation session repeats.

Further information on BizTransactions Administration can be found inchapter “BizTransactions Administration” on page 357.



2.2.5 BizTaConnection

BizTransactions provides the BizTaConnection component for communication with the host applications as a .NET or ActiveX component or as a JavaBean. This class is used inter-nally by BizTransactions during the development phase as well as at runtime. Nevertheless, their program interfaces are open interfaces, thus allowing for considerable flexibility in special applications.

Further information on this topic can be found in chapter “Client interface of business objects” on page 275.

2.2.6 BizTransactions Wizard

In the case of business objects that communicate with host applications via the 3270 or 9750 emulation protocols, BizTransactions provides a guided dialog based on the BizTransactions Wizard.

BizTransactions Wizard contains a number of BizTransactions Studio functions and provides you with an easy way of creating and testing business object functions.

For more detailed information on working with BizTransactions Wizard, see the online help system and chapter “BizTransactions Wizard” on page 41.


Concept of BizTransactions Components of the runtime system

2.3 Components of the runtime system

With BizTransactions you can make the host applications accessible for various clients.

Figure 7: Components of the BizTransactions runtime system

In BizTransactions, each business object is assigned to a specific host application. Cross-application integration can be easily obtained through the clients.

The host adapters are implemented as .NET or ActiveX components and JavaBeans. These ensure smooth-running communication between the classes of the business objects and the server applications.

With BizTransactions Administration you can check and administer the runtime environment of the business objects. Furthermore, you can record sessions.

The runtime components and the host adapters are shipped with the product components WebTransactions for OSD, WebTransactions for openUTM and WebTransactions for MVS (see the WebTransactions manuals “Connection to OSD Applications”, “Connection to openUTM Applications via UPIC” and “Connection to MVS Applications”).

Web ActiveX-App.

WebBrowserTerminal

9750/3270

WebTransactions(D)COM

Servlets

Runtime System

JavaApp.

Java Bean

Browser

(Host adapters for UPIC, 9750, 3270)

JavaBean JSP

BS2000/OSD, MVS, openUTM host applications

Business Objects

.NET-Anw.

ASP.NET

.NET-App.


Building business objects Concept of BizTransactions

2.4 Building business objects

This section describes the individual steps involved in integrating host applications using business objects. Each step refers you to a section in this manual containing further infor-mation. The steps (apart from installing the product) are also explained in the context of a concrete example in the chapter “BizTransactions tutorial” on page 51.

● Install the productObviously, the first step is to install the product. The installation wizard will guide you through the entire installation process. See the chapter “Installing and configuring BizTransactions” on page 261 for more information.

● Create the BizTransactions catalogThe BizTransactions catalog is the central database of the BizTransactions development system. During the development process, BizTransactions enters descriptions of the host applications (name, access data, services) and information on the business objects in this catalog.

● You can create a BizTransactions catalog in the BizTransactions Studio using the File/New Catalog command. Further information on the BizTransactions catalog can be found in section “BizTransactions catalog” on page 29. BizTransactions Studio is described in detail in chapter “BizTransactions Studio” on page 95.

● Enter the host application and its access data in the catalogIn the interface of the BizTransactions Studio, enter the name and access data of the host application to be integrated in the BizTransactions catalog. Further information on the BizTransactions catalog can be found in section “BizTransactions catalog” on page 29. A detailed description of the relevant dialog box can be found in the online Help system.

● Analyze the host application and import the metadataWith the conversion tools provided by BizTransactions Studio you can analyze the inter-faces of the following host applications and convert them to the XML format:

– FHS applications– Cobol applications– Drive applications

After that you import the converted service data into the catalog. The analysis/import procedure is described in section “Converting openUTM program units” on page 114 and in section “Importing service data of UPIC applications” on page 119.


Concept of BizTransactions Building business objects

● Define the business object and its interfacesWhen creating business objects, you begin by defining the business objects and their interfaces (properties and methods). This may involve defining a name, determining the property data types and defining the required parameters for the methods. Further infor-mation can be found in section “Declaring business objects and their interfaces” on page 123.

● Capture the methodsFor each method, you must open a model session with the host application in which you run through the dialog steps that are to be executed when the method is called at runtime. To do this, select the Record Method function in the Edit method window. Further information can be found in the sections “Recording dialogs for UPIC applica-tions” on page 157 and “Recording dialogs for terminal applications” on page 162.

● In the case of terminal applications you can edit the automatically generated code and model the method during the capture procedure (see section “Editing statements during method capture” on page 234). You can also enter the service’s service data (if not already done) during the capture process.

● Model the method In the modeling area in the Edit method window you can graphically post-edit the workflow recorded when capturing the method. This may be necessary, for example, for the correct handling of exceptions correctly during the dialog (e.g. host application error messages). Further information can be found in the section “Modeling a method” on page 177.

● Edit the code You can use graphic tools to modify the statements recorded during method capture as you require. For instance, you can map static input values recorded during the capture procedure to business object variables, thereby “generalizing” the code. Further infor-mation can be found in section “Editing statements” on page 187.

● Generate the business object classWhen you have finished editing the code, start the class generation process using the File/Generate command. BizTransactions Studio generates a business object class with all the methods. See section “Generation” on page 127 for more information on this subject.

Using the File/Generate command you can also trigger the generation for sets of objects, i.e. for several or even all business objects in the catalog.

● When the business object is generated, a test interface in the selected generation language is also generated. In the case of .NET and Java a batch file is generated that you can start by double-clicking on it. In the case of Visual Basic, BizTransactions generates a VB project that you can open in Visual Basic.

i


Building business objects Concept of BizTransactions

● In addition to generating the business object, you can also generate a web service for the business object by choosing Web Service and WSDL file in the Generate Business Objects dialog box. BizTransactions generates a web service which you can make available on the internet and for which you can generate the corresponding clients, for example with WebTransactions. For more detailed information, see the sections “Generating and deploying a Java web service” on page 141 and “Generating and deploying .NET web services” on page 143).

● Create the report filesBizTransactions Studio creates report files containing detailed information on applica-tions, services, and business objects (in HTML format in a hierarchical structure). Further information can be found in section “Creating report files” on page 151.


3 BizTransactions WizardBizTransactions Wizard provides a guided dialog for the fast, easy creation of business objects that communicate with host applications via the 3270 or 9750 emulation protocols.

In many cases, you can use the functions offered by BizTransactions Wizard to create complete business objects and test these. You can create many typical code statements when recording the dialog, i.e. with the current format.

In contrast, more complex functions have to be performed in BizTransactions Studio. Business objects that communicate with host applications via UPIC are also created in BizTransactions Studio (see chapter “BizTransactions Studio” on page 95).

To create and test a business object with BizTransactions Wizard, you must perform the following steps:

● Select an existing catalog or create a new one, see page 45

● Select an existing host application or create a new one, see page 46

● Select an existing business object or create a new one, see page 47

● Select an existing method or create a new one, see page 48

● Record a dialog, see page 49

● Generate the business object together with the test interface, see page 49

● Test the business object, see page 50


Working with BizTransactions Wizard BizTransactions Wizard

3.1 Working with BizTransactions Wizard

This section provides a brief introduction to BizTransactions Wizard. For more detailed infor-mation on the interface, see the online help function.

Before you start working with BizTransactions Wizard, you must call BizTransactions Studio once and enter the temporary directory, the backup directory and the gener-ation options there:You do this with the Options/Edit Options command, see section “Generation options” on page 128.

3.1.1 Calling the BizTransactions Wizard

You can call BizTransactions Wizard via the BizTransactions program group or from WebLab.

Program group Start/Programs/BizTransactions 7.0/BizTransactions Wizard

The BizTransactions Wizard is opened and displays the BizTransactions Wizard dialog box. You start by selecting or creating a catalog (see section “Selecting an existing catalog or creating a new one” on page 45).

WebLab Choose Control/Record Business Object (see the WebTransactions manual “Concepts and Functions”)

Depending on your current session, BizTransactions Wizard is started either with the Host application from catalog or the Business object from host application host application dialog box. You start by selecting or creating a host application or business object (see sections “Selecting an existing host application or creating a new one” on page 46 and “Selecting an existing business object or creating a new one” on page 47).

i


BizTransactions Wizard Working with BizTransactions Wizard

3.1.2 Dialog boxes

When you call BizTransactions Wizard the first dialog box is displayed:

Figure 8: The BizTransactions Wizard dialog boxes

All the BizTransactions Wizard dialog boxes are subdivided from top to bottom as follows

● a title bar indicating the current function

● a short description of the current function

● a work area with input fields and buttons in which you can enter or select the required parameters

● the default buttons >Next, <Back, Cancel and Help (see next section “Default buttons”)

Default buttons

>Next Checks your input (see section “Internal checking of specified names” on page 126) and opens the next dialog box.

A red icon with an exclamation mark ( ) is displayed next to the corresponding input field if an error occurs. Move the cursor to the icon to display the associated error message.

Title bar

Work area

Defaultbuttons

Shortdescription


Working with BizTransactions Wizard BizTransactions Wizard

<Back This has a variety of functions depending on the input field in question (The various possibilities are indicated in the description of the operating steps below.):

– Discard the input and return to the preceding dialog box– Return to the method selection stage– Return to the business object selection stage– Return to the business object generation stage

Cancel Terminates BizTransactions Wizard. If you respondYes to the query Save configuration? then the most recently entered data is stored in the file USERPROFILE\BizTaWizard.xml and is re-used the next time the wizard is called.

Help You see a text explaining the current dialog box.

3.1.3 Additional information

BizTransactions Wizard provides a number of ways of requesting additional information:

● You can click the Help button to obtain a help text on the current dialog box.

● If you position the focus on an input field, you see a tool tip with a short description.

● If you move the focus to an input field and press the F1 key, you will see a help text for the field in question.

● If you move the focus to an error icon (see section “Default buttons”) then the corre-sponding error message is displayed.

3.1.4 Locked objects

If a business object or business object-dependent object (service, class or function) has been locked by another program, you see a corresponding message.

In such cases, you must first release the lock if you want to continue working with the object in BizTransactions Wizard (see section “Administering locks” on page 105). You may have been working with one of the objects in BizTransactions Studio. In this case, you must close the corresponding window there.


BizTransactions Wizard Selecting/creating a catalog

3.2 Selecting an existing catalog or creating a new one

When you call BizTransactions Wizard, the BizTransactions Wizard dialog box is opened.

First of all, you must assign an existing catalog or create a new one. If you have already worked with BizTransactions Wizard then the last catalog you selected is set by default in the Pathname of the catalog field.

To assign an existing catalog,

Ê Enter the absolute pathname of the catalog in the Pathname of the catalog field or click the Select catalog button and select the catalog in the dialog box that now opens.

Catalogs that you created with BizTransactions V3.0 are automatically migrated to the current version. Version 2.0 catalogs are rejected. They must first be migrated to version 3.0 with BizTransactions Migration (see section “BizTransactions Migration” on page 35).

Ê Click the >Next button to assign the catalog and open the next dialog box.

To create a new catalog,

Ê Enter the absolute pathname of the directory in the Directory field or click on Select directory and select the directory in the dialog box that now opens.

Ê Enter the name of the new catalog in the Name of the catalog field.

Ê Click the >Next button to create the catalog and open the next dialog box. The new catalog is created in the specified directory.


Selecting/creating a host application BizTransactions Wizard

3.3 Selecting an existing host application or creating a new one

In the second step, the Host application from catalog dialog box is opened. Here you can select an existing host application or create a new one.

To select an existing host application,

Ê Click on the host application in the list at the top left of the dialog box. The host applica-tion attributes are displayed in the associated fields and cannot be modified.

Ê Click on the >Next button to select the host application and open the next dialog box.

To create a new host application,

Ê Click the New host application button and edit the attributes of the new host applica-tion.

The following attributes must be specified for a host application:

– Name and description of the application– Host on which the application is running– Application name of the host application– Host type– Character set for screen display– Terminal type for the connection to the partner application

Ê Click on the >Next button to create the host application and open the next dialog box. The attributes are entered for the host application in the catalog.

Click on the <Back button if you want to discard your input and return to the catalog selec-tion stage.


BizTransactions Wizard Selecting/creating a business object

3.4 Selecting an existing business object or creating a new one

In the third step, BizTransactions Wizard opens the Business object from host application host application dialog box in which you can select an existing business object or create a new one.

To select an existing business object,

Ê Click on the business object in the list at the top left of the dialog box. The business object’s attributes are displayed in the associated fields and cannot be modified.

Ê Click on the >Next button to select the business object and open the next dialog box.

If the selected business object or an object dependent on it has been locked by another program, you see a corresponding message. In such cases, you must first release the lock if you want to continue working with the business object in BizTransactions Wizard (see section “Administering locks” on page 105).

To create a new business object,

Ê Click on the New business object button and then edit the attributes of the new busi-ness object.

The following attributes must be specified for a business object:

– Name and description of the business object

– Connection: definition of how the host adapter for the business object’s methods is to be declared and instantiated (see section “Connecting to business objects” on page 281).

If you want to use a business object as a web service, select Method here.

Ê Click on the >Next button to create the business object and open the next dialog box. The business object is entered under the host application in the catalog.

Click on the <Back button if you want to discard your input and return to the host selection stage.

i


Selecting/creating a method and starting recording BizTransactions Wizard

3.5 Selecting an existing method or creating a new one and starting recording

In the next step, you select a business object method Business Object method from host application/business object dialog box or create a new method. You start recording for this method in the next step.

To select an existing method,

Ê Click on the method in the list at the top left of the dialog box. The method’s attributes are displayed in the associated fields and cannot be modified.

Ê Click on the >Next button to select the method and open the next dialog box.

To create a new method,

Ê Click the New method button and edit the method’s attributes.

The following methods must be specified for a method:

– Name and description of the method

– Type of method

Update The method modifies data in the host application.

Retrieval The method only retrieves data from the host application.

Unknown The method’s data access mode is unknown.

You cannot enter parameters for the method until you record it, see next section “Recording a dialog and editing a method” on page 49.

Ê Click on the >Next button to create the method and start recording.

Click on the <Back button if you want to discard your input and return to the business object selection stage.


BizTransactions Wizard Recording a dialog and editing a method

3.6 Recording a dialog and editing a method

In the next step, you record the method and generate the runtime code. For a detailed description of the procedure, see section “Recording dialogs for terminal applications” on page 162.

When you have recorded and, if necessary, edited the method, you will see a report on the current business object in the Business Object after recording dialog box.

Ê Click on the >Next button to open the next dialog box and generate the business object.

Click on the <Back button if you want to return to the Business object method from host application/business object dialog box. You can then select or create another method and restart the recording cycle (see section “Selecting an existing method or creating a new one and starting recording” on page 48).

3.7 Generating a business object and test interface

BizTransactions Wizard opens the Generate business object business object dialog box in which you can start generation of the business object and the test interface.

Ê Under Language, select the generation language for the business object.

Ê If required, select the option Generate a web service?.

Ê Click on the >Next button to generate the business object and the test interface.

BizTransactions generates a business object class with all the associated business object methods and the associated test interface (see sections “Generation results for .NET” on page 132 and “Results of the Java generation” on page 135).

You can click on the <Back button if you want to return to the Business object method from host application/business object dialog box. You can then select or create another method or restart the recording cycle (see section “Selecting an existing method or creating a new one and starting recording” on page 48).


Testing the business object BizTransactions Wizard

3.8 Testing the business object

The results of the generation that you started in the previous step are displayed in the Results of the generation dialog box.

Ê Click on the >Next button to start the test program for the business object. The test is performed for Java or for .NET depending on the generation language that you selected in the previous step.

You now see the first dialog box of the test interface Test BizTransactions Business Objects. The dialog boxes in the test interface and the test procedure are described in the corresponding online help system.

BizTransactions Wizard waits until you have terminated the test program and

● Displays a report on the business object in the Test finished dialog box or

● Returns to the Business Object from host application host application dialog box if the business object was opened by another program (BizTransactions Studio or BizTransactions Wizard) during the test (see section “Selecting an existing business object or creating a new one” on page 47).

Ending the test

When you have terminated the test of the business object and the Test finished dialog box is displayed,

Ê Click on the Finished button if you want to exit BizTransactions Wizard.

Ê Click on the <Back button if you have modified the business object during the test. This returns you to the Generate business object busines object dialog box in which you can start generation of the business object and the test interface (see section “Selecting an existing business object or creating a new one” on page 47).


4 BizTransactions tutorialIn this chapter, you will learn about what you can do with BizTransactions, together with a number of basic rules for working with BizTransactions. This tutorial is a step-by-step example intended to illustrate how to integrate a host application into various environments and give it a separate interface without having to perform large amounts of programming.

In this tutorial you will integrate an openUTM application that communicates via the UPIC protocol without format detection into the Java world as a jar archive and into the WWW as a web service.

For information on how to create business objects for other generation languages and, for example, integrate them as .NET components in the Windows world, see chapter “BizTransactions Studio” on page 95.

The openUTM tutorial is implemented as a COBOL program unit. The COBOL program consists of a service with the COBSINL TAC that returns the address and security ID number for the specified company. The sample application is not supplied.

Once you have completely installed BizTransactions, you will find the catalog for this tutorial in the BizTransactions installation directory in the subdirectory Examples\Catalog. You will find a short description in the form of an HTML file in Examples\Documents\En\ExampleUpic.

Prerequisites

You can work through this tutorial if the following software is installed on your computer.

● BizTransactions V7.0

● WebTransactions for openUTMThis contains the host adapter for UPIC which implements communication between the business object and the host application (see the WebTransactions manual“Connection to openUTM Applications via UPIC”)


Reading the openUTM application services into the catalog Tutorial

● For the generation of the business object in Java

– JDK V1.4

– JWSDP V1.3 This is supplied with BizTransactions and can be selected during installation.

– Tomcat as a component of JWSDP This is supplied with BizTransactions and can be selected during installation.

You also need an openUTM application on a host. No such sample application is supplied with BizTransactions.

Please note that all the path specifications assume that BizTransactions has been installed in the predefined directory.

4.1 Reading the openUTM application services into the catalog

In this tutorial you will first use BizTransactions Studio to read the description of an openUTM application into the catalog. You will then create a business object and record a session using this openUTM application as a method. Next, you will edit the interim code of this method. Finally, you will create various classes and test interfaces for the business object on the basis of the interim code.

When this is completed you will have performed all the steps necessary to integrate the openUTM application and you can now create the new interface for the openUTM application in Java, .NET or Visual Basic.

The first part of this tutorial, which is a prerequisite for the subsequent parts, is subdivided into the following steps:

1. Convert the COBOL copy element to XML and transfer it to the PC.

2. Create a new openUTM application in BizTransactions Studio.

3. Import the service data to the catalog.

i


Tutorial Reading the openUTM application services into the catalog

4.1.1 Converting the openUTM application formats

Ê To do this, use FTP to transfer the LMS library BiztaFTP.lib from the subdirectory C:\Programs\BizTransactionsV7\Bs2Files to the host using the user ID under which the COBOL COPY element to be used by the openUTM application is stored.

Ê Sign on to the BS2000 host under this ID and enter the following commands in order to convert the copy element (In this example the COPY element is named nbsinl and is stored in the LMS library demo.lib.boerse):

This command reads the specified COPY element and writes it in the XML format to the file nbsinl.xml.

Ê Transfer the file nbsinl.xml in the text mode to your PC.



4.1.2 Creating a new UTM application

Ê Start BizTransactions Studio using the command sequence Start/Programs/BizTransactions 7.0/BizTransactions Studio. The main window of BizTransactions Studio opens. When you start BizTransactions Studio for the first time, you will see the following message:

Ê Open the Edit Options dialog box with the command Options/Edit Options. In this dialog box you must first assign the relevant directories before you can start working with the Studio.



Ê Select the Directories entry on the left in the tree and enter the Temporary Directory and the Save Directory. You can also search for these directories interactively in a selection box with Find.

Ê Select the Code Generation entry on the left in the tree and enter the required options for the generation in the right-hand side of the dialog box (i.e. the directories for gener-ation and the path for the relevant compiler).

Ê Confirm your settings with OK. The Edit Options dialog box closes and the main window of BizTransactions Studio appears.

Ê Create a new catalog using the command FIle/New Catalog. To do this, enter the name of the new catalog and the directory in which it is to be stored in the New Catalog dialog box.

Ê Confirm your entries with OK. The Catalog window with the new catalog appears in the main window. The new catalog is initially empty.



Ê Select the view of host applications in the Catalog window.

Ê Now create a new openUTM application with the Host Application/Services/New command. The Define new object dialog box appears.

Ê Assign the new host application a name in the Host Application input field (here: MARKET).

Ê Select the type of host application (Upic) from the Type of host application list and confirm your data with OK. The host application is created in the catalog and the Edit window is opened with the attributes of the new host application.



Ê Now enter the communication data for your openUTM application in the text boxes. The modified attributes are marked with a green dot when this is done.

You must enter the following communication data for the new openUTM application:

– description of the application– host on which the openUTM application runs (TestMan)– partner, which is the local application name (COMTA003)– conversion mode (HD)

Ê Confirm your changes with OK. BizTransactions Studio checks the syntax of your data as well as its completeness. If the changes are correct, then the change marker is deleted. If a change is faulty, then the change is marked with a red minus sign.

Ê Save your changes in the catalog with File/Save.



4.1.3 Importing service data

Ê Select the host application: MARKET.

Ê Select the Host Application/Services/Import command. The Import Service dialog box appears on the screen.

Ê Click on the Select file(s) button. A file selection box opens.

Ê In the file selection box, select the file that contains the service data to be imported (nbsinl.xml).

Ê Confirm your selection with OK. The file selection box closes and the selected XML files are added to the list in the Import Service dialog box.

Ê Select COBOL as the Type of XML file and confirm your selection with OK. Since the data is the service data of a COBOL copy element, you need to assign the data struc-ture to a service. The Add buffers to services dialog box opens for this purpose.



The data structures to be imported are in the list on the left.

Ê First enter in the Service field the service name to be assigned to the data structure of the copy element as a buffer (NBSINL).

Ê Now select the data structure to be assigned to the service from the list on the left and transfer it to the Buffer of this service list by clicking on the arrow.

Ê Once all desired data structures have been assigned to this service, select Insert new service. The service is stored temporarily with its new buffer. The Service and Buffer of this service fields are cleared in the dialog box. You can now assign additional data structures to other services.

Ê When you have assigned all data structures to be imported to the corresponding services, then confirm your assignments with Terminate. The services are now entered in the catalog with their new buffers (data structures).

Ê You now see a report in the Import Service dialog box. Confirm this message with OK.



In this example the UPIC application is only assigned one service with one buffer for both directions. The record NB is located in the buffer TSN9NAR. The NB record contains the following records:

– INSTR with the SEARCHS field that contains the input value

– OUTSTR with the RESULT1 and RESULT2 fields for the address and security ID number output values for the desired company

– STATUX with the RETCODE field that contains the return value of the UPIC application

– FEHLERTEXT with the ERRTX field that contains the error text if an error occurs

Ê Enter the TAC with which the UPIC application is to be started for the new NBSINL service (here: COBSINL).

Ê Confirm your changes with OK and choose File/Save to save.

Ê Close the Edit window for the service with File/Close.


Tutorial Generating a business object

4.2 Generating a business object

A business object needs properties and methods. The second stage of this tutorial shows you how to

1. create a business object

2. define a method

3. define the necessary method parameters

4. record a method

4.2.1 Creating a business object

Ê First create a business object for the MARKET application. To do this select the view of the business objects in the Catalog window.

Ê Select the command Business Object/New. The Define new object window appears on the screen.

Ê In this dialog box enter a name for the new business object (here: STOCKINFO) and confirm with OK. The business object is created in the catalog and the Edit window opens with the attributes of the new business object.


Generating a business object Tutorial

Ê Enter a meaningful description for the new business object in the Edit window. Remem-ber that the description will be entered later as the name of the ActiveX component in the Registry database.

If you want to generate the business object as a web service, then you should select the Method value for the Connection attribute.

Ê Confirm your changes with OK and save the business object with File/Close. The business object must remain open in the Edit window for any further actions so that any actions taken thereafter apply to this business object.

i



4.2.2 Defining a method

The methods of a business object contain the actual functionality which connects several services with one another at runtime. Before you can record a run, however, you must create a method.

Ê Select the Edit/Insert New Element command. The Insert element dialog box opens.

Ê Select the Method element type from the list and confirm with OK. The method is entered in the catalog under the selected business object. After that, the Edit window opens with the attributes of the method.



Ê Assign a name (here: readCompanyInfo) and a meaningful description to the method.

Ê Confirm your changes with OK. The modified attributes are checked and errors are highlighted directly.

Ê Save your changes with File/Save. The modified business object is entered in the catalog.



4.2.3 Define method parameters

Ê Define three method parameters for the readCompanyInfo method that will hold the input and output data transferred between the business object and the UPIC application. To do this, select the command Edit/Insert New Element. The Insert element dialog box opens.

Ê Select the desired parameter (of type String here) from the list of element types and confirm your data with OK. The parameter is entered in the catalog under the selected method. After that the Edit window opens with the attributes of the parameter.



Ê Assign a name (here: SearchKey) and add the necessary attributes for the parameter: In the case of this parameter it is an input parameter, and the Parameter Type attribute receives the value In for this reason.

Ê Confirm your changes with OK. The modified attributes are checked, and errors are highlighted directly.

Ê Save your changes with File/Save. The modified business object is entered in the catalog.

Ê Define two more output parameters companyAddress and companyWKN - both with type Out - that will hold the response data of the UPIC application.



Ê If necessary, you can change the order of the parameters on the left in the Edit window so that the input parameters come before the output parameters, for example. To do this mark the input parameter in the tree structure and select the Edit/Shift Upward command until it is directly under the method name.

Ê Save with File/Save.



4.2.4 Recording a method

When recording a method, you run through - in a model session with the host application -the dialog steps that are to be executed by the method when the business object is executed. When this is done BizTransactions automatically creates the corresponding interim code, which you can then edit graphically.

Ê Select in the tree structure of the Edit window the readCompanyInfo method and the command Edit/Edit Method. The Edit method window appears.

You will at first see only the predefined local variables that are available for all methods in the tree structure below the programming area.

Ê Select the Recording/Record Method command in the Edit method window. The Select Start Service dialog box appears in which you can specify the service with which the dialog with the host application will be started (and therefore with which the recording will be started).



Ê Select a service as the start service (NBSINL) from the list under the Number services field and confirm your selection with Continue. The Record Dialog: Upic application partner - Host computer host dialog box is displayed.



In the tree structure on the left you see the data of the data buffer to be sent to the host application. You control the communication with the host application with the buttons on the right.

Ê Select the relevant fields in the tree structure one after the other and enter the required value in the Value input field. In this example only the SEARCHS field is supplied with data since the UPIC application only expects one company name.

Ê You may need to set a function key and a transaction code for the next service. This is not required in this example.

Ê Send the data buffer to the UPIC application using the Send button. In general, the data received by the host application is displayed immediately in the tree structure. A Receive statement is generated for this purpose in the intermediate code.

Ê If the send process terminates correctly, the connection is shut down and you see the message:Connection shut down.

Ê When you select the output fields in the tree structure, you can check if the application has returned the expected results.



Ê Record additional dialog steps if necessary. During the session, each action, every data buffer and all communication with the UPIC application is recorded and stored as inter-mediate code.

Ê Select Stop to finish the recording. The Save recorded code dialog box appears. In it you can specify what should be done with the recording.

Ê Select Replace existing Code. You will see the results of the recording in the tree structure in the Edit method window.



All services in the dialog processes are shown as service nodes in the tree structure. When you expand a service node, all statements to be carried out upon execution are shown below the service node.

In this example, the SEARCHS field is assigned a fixed value before the send operation with a Move statement. After that comes a Send statement used to send the values to the host statement and a Receive statement with the reply from the UPIC application.


Tutorial Editing a method

4.3 Editing a method

In the previous steps you captured the entire dialog with the UPIC application in a method. When you did this, only one service was captured in this example so that modeling is not necessary.

The next steps in editing this method are

1. editing the code

2. generating a project

4.3.1 Editing the code

You recorded this method for a specific situation. In the next step, we want this method to reflect more than this specific dialog sequence: we want to generalize it for all possible situations offered by the UPIC application. This means that the method’s code has to be edited in such a way that the parameters of the method are linked to the application’s records and fields.

Later, a component will be generated from the interim code and the business object’s method will represent part of a client application. You can implement a graphical user interface for each method with the method parameters forming the input and output fields. When the method is run, the fields have to be supplied with the appropriate values.

The sample application exchanges three values with the UPIC application:

– the company name as an input value

– the address and the security ID number returned

The value for the company name is entered by the user. The user can enter different values for the company name. At the present time, the value sent to the UPIC application in the SEARCHS field is precisely the value you entered when capturing the method. However, since there are other values for which the UPIC application can return information, you need to link the SEARCHS field with the SearchKey parameter.

The same applies when information is returned by the UPIC application in the RESULT1 and RESULT2 fields. They should be linked to the companyAddress and companyWKN output parameters. Furthermore, the method must be terminated with an error number and the error message from the host application must be passed on to the client if an error occurs. You can solve this with an If statement.


Editing a method Tutorial

Changing a statement

In this example the user can query the UPIC application to obtain the address and securi-ties ID number for different companies. For this reason, the input parameter SearchKey must be on the right-hand side of the Move statement.

Ê Select the Move statement in the service node NBSINL000 in the tree structure. In the programming area you see buttons that you can use to edit the Move statement.

Many statements are processed page by page, meaning that you need to edit the left-hand and tight-hand sides of the statement separately. The programming area is laid out accordingly. Every button represents one side of the Move statement. The equals sign between the two sides symbolizes the value assignment, which is processed from right to left.

Ê Click on the button on the right labeled “Siemens“. The Move <From> dialog box appears. In this dialog box you can specify from which object the value for the company name is to be read.



Ê Select the Param tab.

Ê Select the parameter SearchKey from the list in the Param tab and confirm your selection with OK. The Move <From> dialog box closes and the name of the parameter is used as the label for the button on the right in the programming area.

Ê Confirm your changes in the programming area with OK. The Move statement is changed in the tree structure.

Inserting new statements

The return values for the address and securities ID number for the company specified are not output yet in the recording. In order for the client to be able to output these values later on, you must assign the values from the fields of the data buffer to the output parameters of the method. The Move statement is suited to this purpose.

Statements are edited one line at a time in the Edit method window, and a Move statement, for example, requires one line. You need to insert at least two lines for an IF statement, one for the condition and one for the statement that depends on the fulfillment of the condition.

Ê Select the last statement (the Receive statement) in the NBSINL000 service node in the tree structure to insert the Move statements for the output parameters below it.

Ê Select the command Manipulate Data/Move/Assignment. An “empty” Move statement is inserted and selected in the tree structure. In the programming area you will see buttons that you can use to edit the Move statement.

Ê Click on the left button. The Move <To> dialog box appears. In this dialog box you specify the destination for the assignment.



Ê Select the Param tab.

Ê Select the parameter companyWKN from the list in the tab Param and confirm your selection with OK. The Move <To> dialog box closes and the name of the parameter is used as the label for the left-hand button in the programming area.



Ê Click on the right button. The Move <From> dialog box appears. In this dialog box you specify from which object the value for the Move statement is to be read.

Ê Select the Fields tab.

Ê Select the RESULT1 field from the tree structure in the Fields tab and confirm your selection with OK. The Move <From> dialog box closes and the name of the field is used as the label for the right-hand button in the programming area.

Ê Confirm your changes in the programming area with OK. The Move statement is modified in the tree structure

Ê Proceed in the same manner to assign the second return value from the host application to the companyAddress output parameter.



If the user of the client enters an invalid company name that, is not entered in the host application, for example, then the host application returns an error message. Since this error message may be of interest to the user, it should be displayed to the user. At the same time, the execution of the method should be aborted if an error occurs.

The host application in this example returns a value in the Retcode field that provides infor-mation on the status of the query: an error has occurred for all values not equal to “OK”. The corresponding error message can then be found in the ErrTxt field.

An If statement is inserted in the query in this example: if no error occurs, then the return value is to be displayed. If an error occurs, then the error message is displayed and the execution of the method terminates.

Ê To do this select the Receive statement again in the NBSINL000 service node in the tree structure to insert the If statement after the Receive statement and before the Move statement for the output parameter.

Ê Select the Structured Code/If-Then-Else-Block command. An “empty” If-Then-Else statement is inserted in the tree structure after the Receive statement. In the program-ming area you will see buttons that you can use to edit the condition for the If statement. The condition itself is also separated into a right and left side.



Ê Click in the programming area on the left button. The <Expression> dialog box appears in which you can select the object whose value is to be used in the comparison of the condition.




Ê Select the RETCODE field from the tree structure in the Fields tab and confirm your selection with OK. The <Expression> dialog box closes and the name of the field is used as the label for the left button in the programming area.

Ê Select the equals sign (=) from the list between the two buttons in the programming area.

Ê Then click on the right button. The <Expression> dialog box appears in which you can select the object whose value must be equal to the value on the left side.



Ê Select the Literals tab.

Ê Select the String option in the Literals tab and enter the value OK in the input field String.

Ê Confirm you entry with OK. The <Expression> dialog box closes and the literal is used as the label for the right button in the programming area.

Ê Confirm your changes in the programming area with OK. The first line of the If state-ment, the condition, is modified in the tree structure.

Ê Then select the two Move statements for the output parameters in the tree structure and move them into the Then branch of the If statement with the Edit/Shift Upward command. You have now defined the output of the results for a regular (error-free) execution of the method.

Ê In order to define the procedure when an error occurs, select in the Else branch of the If statement the tree structure.

Ê Select the Structured Code/Exit Method command. An “empty” ExitMethod statement is inserted behind the Else statement in the tree structure and is also selected. In the programming area you will see a button and an RC input field.



Ê Click on the button in the programming area. The ExitMethod:<Message> dialog box appears in which you can select the object where the error message is located.


Ê Select the ERRTX field from the tree structure in the Fields tab and then select the Begin button on the right next to the Work Area to transfer the ERRTX field to the work area.

Ê Confirm your selection with OK. The ExitMethod:<Message> dialog box closes and the contents of the Work Area are used as the label for the button in the programming area.



Ê Enter a value for the error number in the programming area in the RC input field, in this case 1001.

Ê Confirm your changes in the programming area with OK. The ExitMethod statement is modified in the tree structure. If an error occurs, the execution of the method is aborted and the error message is output for the client in the RETCODE field.

You have now made all changes to the method.

Ê Select the File/Exit command to close the Edit method window.

Ê Respond to the following question with Save. All changes to the method are stored in the catalog.



4.3.2 Generating

It is recommended that you test the result of your editing activities before you continue editing the business object. To this end, BizTransactions generates a test interface for the selected generation language.

4.3.2.1 Generating a business object and test interface for Java

In this example, you generate a business object and the associated test interface for Java. For you to be able to work through this step, JDK V1.4 or higher must be installed on your computer. For information on creating business objects for other generation languages, see chapter “BizTransactions Studio” on page 95.

Ê Select the command File/Generate in the main window of BizTransactions Studio. The Generate Business Objects dialog box appears.

Ê Select the Classes (Business Objects) and Test interface option in the Generate Business Objects dialog box.

Ê Specify any generation options that are only relevant to the current generation and that differ from the general settings with Options. The Edit Options dialog box appears.



Ê In this window you can specify the directory for the generated class modules and the Programming Language in which the business object and test interface are to be generated as well as the compiler path. You can also choose the directories interactively in a file selection box using the Find button.

In this case, you should choose Java in the Programming Language field.

Ê Confirm your changes with OK. The Edit Options dialog box closes and the Generate Business Objects dialog box appears again.

Ê If you have changed the options for this generation run, then select the option Replace generation options with local generation options?



Ê Confirm your settings with OK. The generation of the business object (class) and test interface is started. The Java compiler is started in a DOS window.

A report of the results of the generation is output at the end of the generation.

Ê Confirm the report with OK. If errors occurred during the generation, then they are listed in the results report so that they can be easily found and then eliminated.

Ê Terminate BizTransactions Studio with File/Exit.

Ê In the Explorer switch to the following directory:class directory\MARKET\STOCKINFO\JavaGUI



Ê Start the compilation and execution of the test interface by double-clicking on the batch file BoTestSTOCKINFO.bat. The Java compiler shows the progress of the compilation in a command window. After that you will see the first dialog box of the Java test interface, Test BizTransactions Business Objects.

In the upper section under Properties you see the connection attributes of the business object that it inherited from the UPIC application. The Methods area contains a list of the methods of the corresponding business object, in this example this is the method readCompanyInfo.

Ê Select the method. A form appears with the name of method as its title. All input param-eters of the method are listed in this form.



You can use the Select Events button if you want to intercept and react to business object events. In the Catch BizTransactions Events dialog box, you can select the events on which control is to return to the test program.

Ê For the purposes of this example, select only the input parameter. The Set value(s) form appears in which all attributes of the parameter are displayed.

Ê Enter a value in the Value input field of the parameter and confirm with OK.



Ê Start the method with Start. The connection to the UPIC application is established and the statements of the method are processed. If everything runs without any errors, then you will receive the return value, otherwise you will see an error message of the UPIC application, as defined.

Ê When an error occurs, you can display the log for the statements and the contents of the send and receive buffers with Statement Log and Service Log, and you can then look for the error there. With Comm Trace you can also view the communication trace if you enabled this trace function earlier in BizTransactions Administration.

By following these steps, you have now generated all the components necessary for an executable Java program. You can now use these program and class modules to control the UPIC application from your PC. However, the results program is still unfinished: it controls data transfer and communication with the openUTM application but it does not control quantity-related or company-specific presentation.



4.3.2.2 Generating and deploying a web service

In this example, the JWSDP program is used to generate a Java web service. JWSDP V1.3 is supplied with BizTransactions and is proposed as an option during installation (see chapter “Installing and configuring BizTransactions” on page 261).

In this example, it is assumed that Tomcat was selected as the servlet engine during JWSDP installation. The web service can then be deployed automatically.

Ê Choose the Start Tomcat command in the JWSDP start menu to start the Tomcat web server.

Ê Select the command File/Generate in the main window of BizTransactions Studio. The Generate Business Objects dialog box appears.

Ê Select the Classes (Business Objects) and test interface and Web Service and WSDL file options.

Ê Specify any generation options that are only relevant to the current generation and that differ from the general settings with Options. The Edit Options dialog box appears.

In the Edit Options dialog box, you can specify the directory for the generated class modules and the Programming Language in which the business object and test interface are to be generated as well as the compiler path. You can also choose the directories interactively in a file selection box using the Find button.

Ê In this example, choose Java in the Programming Language field.



Ê Confirm your changes with OK. The Edit Options dialog box closes and the Generate dialog box appears again.

Ê If you have changed the options for this generation run, then select the option Replace generation options with local generation options?

Ê Confirm your settings with OK. The generation of the business object web service is started.

A report of the results of the generation is output when the business object has been generated and deployed.

Ê Confirm the report with OK. If errors occurred during the generation, then they are listed in the results report so that they can be easily found and eliminated.

The web service is now ready for testing.

The following files, which represent the web service, are generated under MARKET\STOCKINFO\Java in the class directory that you specified during generation:

– STOCKINFO_portable.jar– STOCKINFO.war– STOCKINFO.wsdl– CallWebService.cmd



4.3.2.3 Calling a web service

There are two ways of testing the generated web service

Calling in the browser

You can use a browser to switch to the Tomcat web server on your own system and call the business object. The web service is available under the following URL:

Tomcat Root URL/STOCKINFO/STOCKINFO

For example, if you entered http://localhost:8080 in the Tomcat Root URL field during instal-lation, the URL will be as follows: http://localhost:8080/STOCKINFO/STOCKINFO

If you click on the link to WSDL, you can save the XML description of the web service after-wards. For a description of how to incorporate the WSDL file in your web server using WebTransactions, see the WebTransactions manual “Access to Dynamic Web Contents”.



Calling with CallWebServices

The add-on CallWebServices is supplied with BizTransactions. This allows you to generate a client proxy class for a web service on the basis of a WSDL file and test the web service.

After you have generated the web service, you will find the file CallWebService.cmd in the class directory under MARKET\STOCKINFO\Java.

Ê Double-click on the file CallWebService.cmd to start the test program with the web service. CallWebServices is called with the associated WSDL file STOCKINFO.wsdl.

Ê Click on Generate Proxy Class.

The top half of the dialog box that now appears displays all the web methods. When you click on a method, the method parameters are output in the bottom half of the dialog box.

Ê Click on a parameter and enter the associated values.

Ê Click on Start Method. The method is started.

The results of the web service method are output in the dialog box that now opens.


5 BizTransactions StudioThe BizTransactions Studio is the development environment of BizTransactions. You can create business objects and record and edit methods with the Studio.

In addition the Studio provides an import/export interface to XML that you can use to import or export services, for example.

5.1 Functionality

BizTransactions Studio offers the following functionality (in additional to other functions) to make it easier for you to integrate the host application and to create business objects:

● Fast yet simple integration of the existing host applications:

– with conversion tools for FHS and COBOL programs

– by recording methods

– by graphically modeling the dialog processes and

– by generating a test interface

● Simple editing of methods due to:

– support when inputting and changing the statements of a method via dialog boxes for entering the parameters. This ensures syntactically correct statements even if you do not know the exact syntax. Existing statements can also be edited as well. The same dialog box opens for this purpose as for inputting the statement, but the text boxes contain the current values of their parameters.

– direct access to the variables and fields of a statement: in the dialog boxes, the necessary statements can be dragged directly from tab windows into input fields. You do not need to type in names (for fields coming from the host application, for example).

– support when editing large quantities of text, for example when replacing all literals (when recording input values) by variables or fields.


Working with BizTransactions Studio BizTransactions Studio

● Consistent data during the development phase using a lock manager

● Support when testing a BizTransactions application from

– a simple test interface for the generated business objects in .NET, Visual Basic and Java

– detailed logging when the business object is executed, see section “Business ob-jects” on page 345

5.2 Working with BizTransactions Studio

This section provides you with a short introduction to the BizTransactions Studio. You will find detailed information on the Studio interface in the online Help system.

5.2.1 The main window

When you call BizTransactions Studio with the command Start/Programs/BizTransactions V 7.0/BizTransactions Studio, the main window appears on the screen.


BizTransactions Studio Working with BizTransactions Studio

Figure 9: The main window of BizTransactions Studio

The main window, when viewed from top to bottom, consists of

– a title bar with the current catalog– a menu bar – a toolbar– the work area with the Catalog and Edit windows– the status bar

When you start BizTransactions Studio for the first time, you will see the Directories tab in the work area. You will need to set the paths for the backup and temporary directories here first. You can only work with BizTransactions Studio after you have done this. See also section “Generation options” on page 128 for more information.

The Catalog and Edit windows appear in the work area.

Toolbar

Title barMenu bar

Catalog

Status bar

window

Edit window

Tabs for the Edit window

i



5.2.2 The catalog window

The catalog is the central database for BizTransactions during the development phase. If you have not selected a catalog yet, the catalog window is empty. You can use File/Open Catalog to assign a BizTransactions catalog. When the Studio is next started, the catalog that was last edited is automatically selected. If you want to generate a new catalog, select File/New Catalog.

The catalog window is on the left side of the main window and shows you which objects are present in the catalog. The objects are displayed in a tree structure like the one displayed in the Explorer. If no corresponding object is defined, then the window is empty.The view displayed in the catalog window determines which object you are able to open in the Edit window. You specify which view is displayed via

● the tabs in the catalog window

● the View menu

The different views of the catalog are distributed among four tab windows:

Different objects within a view (e.g. applications or business objects) are displayed using different icons. The catalog window is empty if you have not defined any objects yet.

Host applications

Business objects

Classes

Functions



Figure 10: The Catalog window with a view of the host applications

Handling is also the same as in the Windows Explorer: you can open and close the various hierarchy levels. To select an object simply click on it. It will then appear on the tab in the work area on the right.

If you select an object in the tree structure and press the right-hand mouse button, a context menu with commands concerning the current situation is opened.

You can mark the various uses of the objects using colors, e.g. for objects that are:

– locked internally, i.e. you yourself are currently using the object– locked externally, i.e. someone else is currently using the object– used by other business objects

You specify the colors and other settings used with the Options/Edit Options/Catalog Window command. You can make the catalog window larger or smaller using the scroll bar on the bottom edge.

Services

Tab for views of the catalog

Scroll bar

Application



Editing catalog objects

All catalog objects can be edited in the Catalog window. Select the object you want to edit from the tree structure. You can

● open this object in the Edit window for editing with the command Object/Open

● insert a new object below the current object with the command Object/New

● duplicate this object

Ê Select the command Object/Duplicate. The Duplicate Object dialog box appears.

Ê Enter a name for the new object here and confirm your entry with OK.

Ê The new object is created as a copy of the original object but with a new name.

● rename this object with the command Object/Rename and

● delete this object with the command Object/Delete.



5.2.3 The Edit window

The Edit window appears in the work area when you

● double-click on a catalog object in the catalog window

● select the Object/Open command

Figure 11: The Edit window

A maximum of six Edit windows can be open. An Edit window consists of

● the Element view as a tree structure that shows which elements make up a catalog object

● a dialog box in which you can edit the element or object selected

● a tab above the work area with which you can switch between various Edit windows. The window bar with the tabs can be shown or hidden with the View/Show Window Bar command.

Element view asa tree structure

Dialog box with the attributes of the selected object or element

Buttons fordialog boxes



When you edit the attributes of a catalog object or element, the object or element is marked as changed by a green dot. When you confirm your changes with OK, BizTransactions Studio checks the modified attribute values. If the value is correct, then the corresponding attribute is marked with a plus sign “+”. If it is not correct, the corresponding attribute is marked with a minus sign “-”.

The modified attribute values of an object or element are stored in the catalog with File/Save.

Editing catalog elements

All catalog elements can be edited in the Edit window. Select the element you want to edit from the tree structure on the left-hand side of the Edit window. You can perform the following tasks:

● Delete this element with the command Edit/Delete Element.

● Insert a new element after the current element with the command Edit/Insert New Element

● Move this element

Ê Select the command Edit/Shift Upward or Edit/Shift Downward.

or

Ê Drag the object or element with the mouse to its new position. .

● Copy this element

Ê Select the element and copy it to the clipboard with the command Edit/Copy.

Ê Then select element after which the element from the clipboard is to be inserted.

Ê Select the command Edit/Paste.

or via the keyboard

Ê Select the element and copy it to the clipboard with the key combination [Ctrl] [C].

Ê Then select element after which the element from the clipboard is to be inserted.

Ê Insert the element or object with the key combination [Ctrl] [V].



or with the mouse if the destination is in another edit window

Ê Use the mouse to drag the object or element to the new position.

When you copy an element, it is assigned a predefined name. You can edit this name and other attributes in the Edit window on the right.

If you want to copy a method to a business object of the same host application, then BizTransactions Studio creates an exact copy of the intermediate code and generates the properties that did not exist until now in the business object. If you want to copy a method to a business object of another host application, then BizTransactions Studio only generates the method and parameters, but does not copy the intermediate code.

● Edit all attributes of this element type

Ê To do this select the command Edit/Edit Elements. You can edit all elements of the selected type in a table in the Edit element element dialog box.

5.2.4 The status bar

The status bar is located on the bottom edge of the main window. It contains error messages from BizTransactions Studio as well as information on the currently selected catalog objects and commands. The error messages can also be output in a dialog box. To do this, select Options/Edit Options/Catalog Window.

The following commands can output their results in the status bar:

– Edit/Delete Element

– Object/Find & Mark

– Object/Used By

– Object/Delete Object

Each result is displayed in a own tab. You can page through the tab windows using the tabs. The Status tab contains error messages and information on the currently selected catalog object.

You can make the status bar larger or smaller using the slide on the right-hand side. In the status area there can be up to five tabs opened in addition to the Status tab.

i



5.2.5 The Administration menu

The Administration menu provides you with a variety of functions for the administration of catalogs, locks and messages issued by BizTransactions Studio. This section provides you with a brief introduction to the functions. More detailed information can be found in the online help system.

5.2.5.1 Check Catalog

The Check Catalog command performs an asynchronous check of the current catalog for

● Locks

● All classes of reference

● Internal and external references for all business objects

BizTransactions writes the results of the individual checks to a log file. This file is located under the path you set with Options/Edit Options/Directories for the backup (save) directory (see section “Creating a new UTM application” on page 54). BizTransactions saves the result of the complete check as a user-specific message.

You can then use the command Administration/Show User Messages to view the user-specific messages.

5.2.5.2 Compact Catalog

You use the Compact Catalog command to compress and reorganize the current catalog.

It is advisable to reorganize the current catalog if you have been working with it for an extended period. When you reorganize the catalog, any storage space that is no longer required is freed and the result is displayed in the status bar.

5.2.5.3 Save Catalog

The Save Catalog command checks, compresses and backs up the current catalog asynchronously. When doing this, BizTransactions resets all locks. Files that are being shared locally are ignored. You specify the path of the verification protocol and the catalog backup with the command Options/Edit Options/Directories (see section “Creating a new UTM application” on page 54). BizTransactions saves the result of the backup as a user-specific message.

You can then use the command Administration/Show User Messages to view the user-specific messages.



5.2.5.4 Merge Catalogs

This command opens the Merge Catalogs dialog box in which you can copy a host application from a source catalog to a target catalog.

When you copy the host application, all the dependent objects (business objects, services, classes and functions) are also copied.

5.2.5.5 Administering locks

To ensure that the data stock remains consistent, BizTransactions Studio locks a catalog object when it is

● currently being edited

● stored locally

This means that you cannot edit a locked object or element.BizTransactions Studio resets the lock on an object when it is

● not loaded any more in the edit window

● stored in the catalog again

You can reset locks. When you reset a lock explicitly, you must note the following:

● If more than one person edit an object, then only the last version stored is located in the catalog.

● Objects stored locally are not taken into account any more. The Studio reads the object from the catalog again. This is useful when you want to reject changes made locally.

Proceed as follows to explicitly reset a lock:

Ê Open the Edit locks dialog box with Administration/Edit Locks.

Ê Set the required view of the locked objects with an option and Show.

Ê Mark the objects whose locks you want to reset in the Remove column by clicking on them.

Ê Confirm your selection with OK. The locks for the selected objects are reset.



5.2.5.6 Administer Messages

The command opens the Administer Messages dialog box in which you can configure the scope and destination of BizTransactions Studio messages. The message server gather the messages from all BizTransactions and logs them either locally or for multiple components in the BizTransactions temporary directory.

You define the temporary directory with the commandOptions/Edit Options/Directories (see section “Creating a new UTM application” on page 54).

BizTransactions Studio supplies log information in the event of errors, e.g.

● on object import

● on method recording

● on a catalog check

● on a configuration check

5.2.5.7 Show User Messages

The command opens the Show User Messages dialog box in which you can display or delete the messages output by the following commands:

● Check Catalog, see page 104

● Save Catalog, see page 104

● Check Configuration, see below

The messages are not saved in a log file but directly in the catalog.

5.2.5.8 Check Configuration

The Check Configuration command performs an asynchronous check of whether the dll, ocx and exe files on your computer correspond to the version required for BizTransactions. The other files that are output are required for diagnostic purposes in the event of an error.

BizTransactions writes the result of this check to the file BizTaConfig.htm in the directory for temporary files that you specified with the command Options/Edit Options/Directories for the backup directory (see section “Creating a new UTM application” on page 54).

BizTransactions also writes an entry to the user-specific message log. You can then view the user-specific messages with the command Administration/Show User Messages.



5.2.5.9 Check Capture Criteria

The command opens the Checking of capture criteria dialog box in which you can start a check of the criteria for a selected or for all terminals.

If a capture criterion is also present in the labels (fixed texts) of another screen, BizTransactions tries to generate a different capture criterion. The result of this check is output in a separate window. For more detailed information, see section “Format recog-nition” on page 167.



5.2.6 Procedure

The following procedure is required to integrate a host application:

● Create a catalog or open an existing catalog. See the section “Creating a catalog” on page 109 for more information on this subject.

● Create the host application. See the section “Creating a new host application” on page 111 for more information on this subject.

● In the case of a terminal application, analyze the services of a host application and import into the BizTransactions catalog. See the section “Creating a new service” on page 113 for more information on this subject.

● Declare business objects and their interfaces (properties and methods). See section “Declaring business objects and their interfaces” on page 123 for more information on this subject.

● Record methods using model sessions with the host application. See the sections “Recording dialogs for UPIC applications” on page 157” and “Recording dialogs for terminal applications” on page 162 for more information on this subject.

● Model the recorded workflow graphically, e.g. remove any superfluous screens, combine screens often repeated or add new screens. See the section “Modeling a method” on page 177 for more information on this subject.

● Individually customize the automatically generated code (on a visual level). See the section “Editing statements” on page 187 for more information on this subject.

● Generate the business object depending on the selection– as a software component– with a web service, see the section “Generation” on page 127 for more information

on this subject

In the case of business objects that communicate with host applications via the 3270 or 9750 emulation protocols, you can also perform the steps listed here in a guided dialog with BizTransactions Wizard (see chapter “BizTransactions Wizard” on page 41).

All the operating steps that you perform with BizTransactions Studio are described in the following sections.

The sections also describe how you can create HTML reports on all objects of the current BizTransactions catalog. See the section “Creating report files” on page 151 for more infor-mation on this subject.

i


BizTransactions Studio Creating a catalog

5.3 Creating a catalog

Once you have installed and configured BizTransactions, you must create a new BizTransactions catalog and enter the new host applications to be integrated (name, access data) into this catalog.

The next steps depend on the type of host application:

● openUTM-UPICFor host applications that communicate via UPIC you use the BizTransactions conversion tool to obtain an analysis of the interface. After that you import the XML files created during the analysis:

● 9750/3270The service data for host applications that communicate via an emulation (9750/3270) is generally not analyzed and imported with the conversion tool, but is entered in the catalog while capturing the method with the capturing procedure.

For FHS applications that are reached via 9750 you can use both capabilities: analyze and import the service data with the BizTransactions Studio or create the service data while recording the method.

Proceed as follows to create a new catalog:

Ê Select the command File/New Catalog. The New Catalog dialog box appears.

Ê Select the drive and directory in which you want to create the new catalog.

Ê Enter the name of the new catalog.

Ê Confirm your entries. The new catalog is created in the specified directory.


Creating a catalog BizTransactions Studio

Reusing catalogs created with earlier versions

If you have used earlier versions of BizTransactions then you can reuse the catalogs created using these versions.

● Catalogs belonging to BizTransactions version V3.0 are migrated automatically when you open them in BizTransactions Studio.

● Catalogs created in earlier versions must be migrated first. To do this, choose the command Start/Programs/BizTransactions 7.0/BizTransactions Migration.

You must migrate catalogs from version V1.1 first to version V2.0 and then to version V3.0.

You can also migrate first on a trial basis with BizTransactions Migration. After the migration is complete, you will see all locations where problems may arise during migration in a detailed log file. These problem locations must be eliminated in the version V2.0 catalog first before you finally migrate the catalog to version V7.0.


BizTransactions Studio Creating a new host application

5.4 Creating a new host application

Before you create a new host application, select a BizTransactions catalog or generate a new one. The catalog is shown in the Catalog window.

Proceed as follows to create a new host application:

Ê Select the view for host applications in the catalog window.

Ê Select the command Host Application/New. The Define new object dialog box appears.

Ê Assign the host application a name in the Host Application field.

Ê Select the type of host application from the Type of host application list and confirm your entry with OK. The host application is created in the catalog and the Edit window is opened with the attributes of the new host application. You can create the following types of host applications:

– UPIC applications– 9750 applications– 3270 applications

openUTM applications can communicate via the UPIC protocol as well as via the 9750 terminal interface. In BizTransactions terminology, the expression “UPIC application” means the openUTM application that is addressed via UPIC. openUTM applications that communicate via the 9750 emulation are called terminal applications.

Ê Edit the attributes of the new host application.

A UPIC application must be supplied with the following attributes:

– Name and description of the application – Host on which the UPIC application runs– Partner: Name of the UPIC application (BCAMAPPL)– Conversion mode:

HD Automatic conversion from EBCDIC to ASCIISD Automatic conversion from EBCDIC to ASCII is carried out internally by

BizTransactions BOI and not by UPIC. We recommend this setting for appli-cations using the + formats, since attribute fields are excluded from the conversion.

SN Automatic conversion is suppressed. (This setting is required for UNIX host applications which use ASCII, as Windows does also.)

i


Creating a new host application BizTransactions Studio

You can also supply the following optional parameters with values:

– User – Password – Station name (local name of the client application)– Port number of the UPIC application

The following attributes must be supplied with values for a 9750 application:

– Name and description of the application – Name of the host on which the application runs– Name of the partner used to address an application when a connection is estab-

lished – Language for the capture criteria– Language for the presentation data

Optional attribute: station name

The following attributes must be supplied with values for a 3270 application:

– Name and description of the application – Name of the host on which the application runs (for documentation purposes only)

Optional attributes:

– LUname– Name of the partner as connection name

This attribute is optional for 3270 applications. However, it is used for recording and playing back sessions (see section “Recording sessions” on page 364).

Ê Confirm your data with OK. The modified attributes are checked, errors are immediately marked.

Ê Select File/Exit to close the Edit window or save your changes in the catalog with File/Save. The attributes for the host application are entered in the catalog.


BizTransactions Studio Creating a new service

5.5 Creating a new service

You generally create a new service by importing the service data of a host application. You can also create a new service directly; see section “Creating your own services” on page 121.

5.5.1 Importing a service

You can import the description of various types of applications into the BizTransactions catalog. The import method is dependent on the communication protocol used.

openUTM applications can communicate via the UPIC protocol as well as via the terminal interface. Depending on the communication protocol, there are various ways to import the service data of an openUTM application (FHS).

Communication via UPIC

In order to import the service data you convert the services of the openUTM application using a conversion tool and thus generate the service data which you import into the catalog. The various conversion tools are described in the following sections on page 114.

Application type Connection protocol

Acquiring service data

UTM-FHS UPIC Conversion and import

UTM-COBOL UPIC Conversion and import

UTM-DRIVE UPIC Import

FHS 9750 Capture mechanismConversion and import

BS2000/OSD 9750 Capture mechanism

MVS 3270 Capture mechanism

Acquiring service data depending on the protocol

i


Creating a new service BizTransactions Studio

Communication via 9750/3270 emulation

The service data are imported using the capture procedure. The capture procedure is described in section “Format recognition” on page 167.

You have two possibilities for FHS applications that are reached via 9750:

● Capture the service data during recording (see section “Format recognition” on page 167)

● Convert and import the service data with BizTransactions Studio:First, the service data is converted in BS2000 and transferred to the PC.Following that, open the Import Service dialog box where you can select the files to be imported using the command Host Application/Service/Import. See also the section “Importing service data of UPIC applications” on page 119.

5.5.1.1 Converting openUTM program units

You can generate service data from the following openUTM program units:

● program units with FHS formats (UPIC or 9750)

● COBOL program units (UPIC)

To make this possible, BizTransactions is supplied together with programs which you will find in the BS2Files subdirectory of the installation directory. This subdirectory contains the LMS libraries BiztaFTP.lib and BiztaOFT.lib.

Depending on the file transfer program you are using, you transfer one of these BS2000 LMS libraries to the ID of the BS2000 computer on which the openUTM applications are located. The library contains the following elements:

● The BS2000 load module IFG2FLD which is used to convert existing formats of an FHS program unit to the XML format.

● The BS2000 phase COB2XML and the procedures d.xmlprog and d.xmlcopy with which you convert data structures from COBOL programs and COPY elements to the XML format.

Library Use

BiztaFTP.lib To transfer the library with the FTP command.

BiztaOFT.lib To transfer the library with openFT.

Meaning of the libraries supplied



Converting FHS formats

You must perform the following steps if you want to convert the service data of an FHS format:

Ê Transfer the LMS library to the host

Ê Convert the service data from the formats of the IFG library to XML using the integration tool IFG2FLD

Ê Transfer the service data to the PC

The file name on the PC must be assigned the file extension .xml because BizTransactions Studio expects this extension and checks the format.

Ê Import the service data (see section “Importing service data of UPIC applications” on page 119).

IFG2FLD is an OSD program, so you have to transfer the library to an OSD user ID. Now you can start IFG2FLD from the transferred library using the this command:

/START-PROGRAM FROM-FILE=*PHASE(LIBRARY=Bibliothek,ELEMENT=IFG2FLD)

IFG2FLD is started with the START-PROGRAM command, and the output is written to SYSLST. IFG2FLD accepts the following parameters:

Parameter Description

MAPFILE IFG-library assigns an IFG library to be processed.

PROFILE user-profile assigns a user profile for conversion. Each IFG library contains at least one user profile for processing a format. A user profile is a set of default values for handling IFG, for the format properties, for the field properties of a format and for the properties concerning programming.

XML specifies that the service data was written in the XML format.

CONVERT format-name [/version] converts the specified IFG format. Optionally, you can also specify a format version.If you do not specify the format version, the format with the most recent version will be included.

CONVERT *ALL [/version] converts all IFG formats in the IFG library. Optionally, you can specify the format versions, in which case only the specified format versions will be included.If you do not specify the format version, the latest versions will be included in the list of formats.

END generates the list of formats and ends IFG2FLD.

i



Specifically, you must enter the following commands under BS2000:

/ ASSIGN-SYSLST output file/ START-PROGRAM FROM-FILE=*PHASE(LIB=BizTaFTP.LIB, ELEM=IFG2FLD) MAPFILE IFG-format-library PROFILE user-profileXML

CONVERT format1 CONVERT format2 ... END/ ASSIGN-SYSLST *P

Instead of entering the format names individually, you can also specify *ALL to include all the formats in the service data conversion operation in one go.

Once IFG2FLD has been run, the service data is present in the file which you assigned to SYSLST as output-file.

Rules for lists for 9750 applications

● A Record is created for each list where the Number property is assigned the number of lines in the list. The list name is used for Name.

● Fields that do not belong to a list are combined to form one or more record(s) with the predefined name Tablen (n is a sequential number of the format 0000, 0001, etc.). Otherwise, the fields and lists (records) are given the names assigned in IFG/FHS.

● The length of a line in the list (i.e. the structure that is repeated) has to be a multiple integer of the length of a format line.

● Lists where a list line is shorter or longer than a format line, are combined to form a record, but not as a true list, i.e. the record has the repeat factor (Number) 1 and the list fields appear n times in the record. In order to obtain unique field names, the position within the record is appended to the original field name for each repetition.



Converting COBOL program units

The following steps must be performed to convert the service data from COBOL programs or COPY elements:

Ê Transfer the LMS library to the host.

Ê Convert the service data from COBOL programs using the d.xmlprog procedure and convert COPY elements to XML using the d.xmlcopy procedure.

Ê Transfer the service data to the PC.

The file name on the PC must be assigned the file extension .xml because BizTransactions Studio expects this extension and checks the format.

Ê Import the service data (see section “Importing service data of UPIC applications” on page 119).

COB2XML is an OSD program, which is why you need to transfer the corresponding library to an OSD user ID. You can then start the procedures d.xmlprog and d.xmlcopy from the transferred library using the following command (xxx here stands for FTP or OFT):

/CALL-PROC FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=BIZTAxxx.LIB,ELEMENT=D.XMLCOPY)

You start d.xmlprog with the command CALL-PROCEDURE. The following parameters are accepted by d.xmlprog:


SRC (FILE|LIB) Specifies where the COBOL program is located

FILE The COBOL program is in a BS2000 file whose name is in the TSTNAM parameter.

LIB The COBOL program is an element of an LMS library whose name is in LIB.

LIB Name of the LMS library that contains the COBOL program

TSTNAM Name of the file or LMS element that contains the COBOL program.

XMLOUT Name of the file in which the service data is written in the XML format.

COBRUN Compiler options as strings that can be up to 121 characters long. You separate more than one option with commas.

i



You must specify the following command to convert COBOL programs (xxx here stands for FTP or OFT):

/CALL-PROC FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=BIZTAxxx.LIB,ELEM=D.XMLPROG) -/ ,PROCEDURE-PARAMETER=(SRC=LIB, LIB=cobollib, TSTNAM=cobolprogram -/ ,XMLOUT=output-file.xml)

You start d.xmlcopy with the command CALL-PROCEDURE. The following parameters are accepted by d.xmlcopy:

You must specify the following command to convert COPY elements (xxx here stands for FTP or OFT):

/CALL-PROC FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=BIZTAxxx.LIB,ELEM=D.XMLCOPY) -/ ,PROCEDURE-PARAMETER=(LIB=cobollib ,ELEM=cobolcopy, XMLOUT=output-file.xml)

The output from d.xmlprog and d.xmlcopy is found in the file that you

● assigned the link name XMLLINK earlier with the ADD-FILE-LINK command

● assigned the S variable SYSIOL-XMLLINK earlier

● specified in the XMLOUT parameter

If you do not use any of these options, then the output of d.xmlprog and d.xmlcopy is found in the file XMLFIL.COBOL.progID.XML, where progID stands for the current program ID.


LIB LMS library that contains the COBOL source program.

ELEM Name of the LMS element that contains the COBOL source code.

XMLOUT Name of the file in which the service data is written in the XML format.

COBRUN Compiler options as strings that can be up to 121 characters long. You separate more than one option with commas.



Converting DRIVE program units

You create the XML file of a DRIVE program for the import into the BizTransactions catalog with DRIVE V3.1. To do this, proceed as follows:

Ê Log in to the BS2000 host using the user ID under which the library with the DRIVE program unit is stored.

Ê Call the DRIVE interpreter.

Ê Assign the library that contains the program unit to be converted:

PAR DYN LIB=bibliothek

Ê Then enter the following command:

COMPILE program OPTION XML=ON

Ê The service data is located after that in a file named after the program and with the extension .xml: program.xml.

Ê Transfer the file program.xml in the text mode to your PC since the service data is available in a text file.

5.5.1.2 Importing service data of UPIC applications

After converting the service data as XML files and transferring the XML files in the text mode to your PC, you can import them into the BizTransactions catalog. Proceed as follows to import service data for a server application:

Ê Start BizTransactions Studio and select the catalog to which the service data is to be imported. The catalog window opens.

Ê Select the host applications view in the catalog window.

Ê If necessary create a new application or select an existing application from the catalog window.

Ê Select the Host Application/Service/Import command. The Import service dialog box appears on the screen.

Ê Click on the Select file(s) button. A file selection box opens.

Ê Select the directory and the files that you want to import as services into the catalog from the file selection box.



Ê Select the Type of XML file. You can select from the following options:

Ê Confirm your data with OK.

In the case of converted COBOL program units, you must assign the data structure as a buffer to a service. The Add buffers to services dialog box opens to allow you to do this.

In the case of all other converted program units, the services are entered in the catalog immediately.

Ê If necessary, assign all the data structures for import to the corresponding services in the Add buffers to services dialog box and click Terminate to confirm.

The service data is stored as services of the selected application in the current catalog. All services are assigned a buffer with the send direction set to Both that starts at posi-tion 1 and whose size is determined as follows:

FHS The FormatLength attribute is evaluated for the size

COBOL The size is calculated from the length of the elements contained. If the memory area does not start at position 1, then you must correct the Position attribute of this buffer manually.

Drive Send and receive buffers are create at the position and of the size supplied by the Drive program.

5.5.1.3 Importing service data of terminal applications

The service data for terminal applications is generally entered in the catalog during method capture (see section “Recording dialogs for terminal applications” on page 162).

For FHS applications you can also convert the data structures of the FHS formats with IFG2FLD. The precise procedure is described in section “Converting FHS formats” on page 115.

The procedure for importing the converted FHS formats is the same as for UPIC applica-tions. You can find a description in section “Importing service data of UPIC applications” on page 119.

BizTaService BizTransactions service that you exported or converted UTM Drive program

IFG Format An FHS format converted with IFG2FLD

COBOL A COBOL program converted with the d.xml.prog procedure or a copy element converted with the d.xml.copy procedure



5.5.2 Creating your own services

Should you need a service which cannot be read into the catalog via a service data import, you can create your own service. As a rule, this will be one of the following two service types:

● Start service to start an openUTM process for UPIC applications.

● BizTaUnknown which can process unexpected formats. See section “Modeling unknown formats (BizTaUnknown)” on page 183 for further details.

Proceed as follows to create a service:

Ê Select the Host Application view in the Catalog window.

Ê Select the host application.

Ê Select the command Host Application/Service/New. The Define new object dialog box appears.

Ê Enter the name of the new service in the Service input field.

Ê If the application is a UPIC application, then you can select the type of service from the Type of service list:

Ê Confirm the data you have entered with OK. The service is created in the catalog, and the Edit window opens with the attributes of the new service.

Ê Enter the TAC for the new service with which the UPIC application is to be started.

Ê Confirm your change with OK and close the Edit window for the service with FIle/Exit.

Service Type Meaning

Drive The new service describes a Drive program

UpicFormat The new service describes a FHS format

Upic TP The new service describes a UPIC program unit such as a COBOL program



In the BizTransactions Studio you only create the BizTaUnknown service with or without a buffer. You integrate the BizTaUnknown service into the program using the graphical editor.

Include all relevant record and field definitions to make sure that all fields of the host appli-cation that you need when running the business object method are represented in the BizTaUnknown service.


BizTransactions Studio Declaring business objects and their interfaces

5.6 Declaring business objects and their interfaces

When creating business objects, you begin by declaring the business objects and their interfaces (properties and methods). This may involve defining a name, determining the property data types, and specifying which parameters are to be used for the methods.

The following sections describe how to create new business objects, properties, methods and their parameters. It is also possible to modify, copy and delete existing declarations using the appropriate menu commands at any time.

5.6.1 Creating a business object

To create a new business object, proceed as follows:

Ê Select the Business Objects view in the catalog window and select a host application.

Ê Select the Business Object/New command. The Define new object dialog box opens.

Ê Assign the business object a name (max. 30 characters) in the Business Object field and confirm with OK. The business object is entered in the catalog under the selected host application. After that the edit window opens with the business object.

Ê Add the required attributes for the business object.

If you want to generate the business object as a Web service, then you should select the value Method for the Connection attribute.

Visual Basic only: Please note that the description will be entered in the registry later on as the name of the ActiveX component.

If you want to generate the business object later on as an ActiveX object, then you should choose a short name since project and class names are formed from the name of the business object and together they may only be 39 characters long. During generation, the name BOboname is formed for the project, and the name BOboname.boname is formed for the business object.

If ActiveX objects are generated, the names of business objects are to be unique even across applications. Otherwise an error dialog boy is opened during the generation in which you are requested to enter a unique name.

Ê Confirm your changes with OK.

Ê Select File/Close to close the Edit window or File/Save to save your changes to the catalog.

i


Declaring business objects and their interfaces BizTransactions Studio

5.6.2 Defining a new property

To define a new property, proceed as follows:

Ê Select the Business Objects view in the catalog window and open the business object that you want to add a new property to in the Edit window.


Ê Select the desired element from the list of element types and specify where the element is to be inserted in the object: Below selected element.

Ê Confirm your data with OK. The property is entered in the tree structure. After that a new edit window opens with the property.

Ê Assign a name and add the required attributes for the property.


Ê Select File/Close to close the Edit window or File/Save to save your changes. The changed business object is written in the catalog.

5.6.3 Defining a new method

To define a new method, proceed as follows:

Ê Select the Business Objects view in the catalog window and open the business object that you want to add a new method to in the edit window.


Ê Select the method element type from the list and specify where the element is to be inserted in the business object: Below selected element.

Ê Confirm your data with OK. The method is entered in the tree structure. After that a new Edit window opens with the method.

Ê Assign a name and add the required attributes for the function.


Ê Select File/Close to close the Edit window or File/Save to save your changes. The changed business object is written in the catalog.


BizTransactions Studio Declaring business objects and their interfaces

5.6.4 Defining a new method parameter

Proceed as follows to create a new property:

Ê Select the Business Objects view in the catalog window and open the business object in the edit window.

Ê Select the method you want to add a new parameter to in the tree structure on the left in the Edit window.


Ê Select the desired parameter from the list of element types and specify where the element is to be inserted in the object: Below selected element.

Ê Confirm your data with OK. The parameter entered in the tree structure. After that a new Edit window opens with the parameter.

Ê Assign a name and add the required attributes for the parameter.


Ê Select File/Close to close the Edit window or File/Save to save your changes. The changed business object is written to the catalog.

Visual Basic only: The number of method parameters is restricted by the maximum number of continuation lines permitted in Visual Basic. When generating BO classes, therefore, the method parameters are distributed throughout the continu-ation lines in order to save space:

– number of method parameters <= 40: 4 parameters per code line

– number of method parameters > 40: 10 parameters per code line

This results in a "dynamic" maximum of approximately 100 method parameters.

i


Declaring business objects and their interfaces BizTransactions Studio

5.6.5 Internal checking of specified names

When you declare a business object, a property, a method or a service, BizTransactions checks whether:

● the name was entered with the correct syntax

● the name has already been assigned or reserved

If the specified name is found to be invalid, an error message explaining the error is issued. No distinction is made between uppercase and lowercase.

The following points are checked: the name

● must be at least one character in length

● may only contain the characters 'A..Z', '0..9' and '_'

● must not begin with the '_' character or with a digit

● must not contain '__'

● must not end with '_'

● must not be longer than the maximum number of characters

● must not be a reserved name from BizTransactions, Visual Basic or Java

● must not begin with the prefix “BizTa“

Exception

Only the method namesBizTa_SignOnBizTa_SignOffBizTa_CleanUp

the service nameBizTaUnknkown

and the property nameBizTa_ResultOfUpdate.are allowed.

In all other cases, the prefix BizTa is not allowed.

Within a BizTransactions application, the name

● may not already have been assigned to another service

● may not already have been assigned to another business object


BizTransactions Studio Editing methods

Within a business object, the name

● may not already been assigned to another method

● may not already been assigned to another property

5.7 Editing methods

After you have created a new method you can

● record the flow of the method

● model the method

● edit the code of the method

● insert statements in the method

● edit existing statements

All these functions are described in the chapter “Editing the code of a method” on page 153.

5.8 Generation

Before you generate the business objects you should set the options for the generation. You specify the language, the compiler and the directory in which the business objects will be generated as well as other items with these options.

After that you can specify what you want to generate in the Generate Business Objects dialog box:

● business object class including test interface

● WSDL file or web service


Generation BizTransactions Studio

5.8.1 Generation options

You use the Options/Edit Options command to open the Edit Options dialog box. In the tree structure, you should choose the Code Generation tab in which you can set the following options.

Class directoryDirectory in which the business object classes are stored; During generation, subdirec-tories are created, if required, in the class directory. The subdirectories contain the following files:

VariantSpecifies, which variant of the component is generated.

Subdirectory Contents

\host application\boname\GEN Business object-specific generation options

\host application\boname\Java Java classes, modules and batch file as well as generation results for the Java web service

\host application\boname\JavaGUI Generation results of the test interface for Java

\host application\boname\NET Business object source files and Visual Studio project file

\host application\boname\NetGUI Generation results of test interface for .NET

\host application\boname\NetWebService

Generation results of the .NET web service

\host application\boname\VB Generation results for WSDL and Visual Basic classes, modules and project file

\host application\boname\VBGUI Generation results of the test interface for Visual Basic

\host application\boname\VB\Ref Reference component for the compatible creation of a COM component

Debug When the component is run for test purposes, the following information is written to the log file. See also section “Business objects” on page 345.

– all calls of methods and service nodes– all statements of the intermediate code– error information within the catch block

Release only the messages you have assigned with the Writelog statement are logged


BizTransactions Studio Generation

Logging is only activates when you have specified the logging file beforehand in the business object class (see section “Business objects” on page 345). The log file is automatically set in the test interface for the component (default setting: class directory/languageGui/TestStmnt*.txt).

After successful testing generate the component with the option Variant= Release.

Programming LanguageProgramming language in which the business object classes are generated

Java CompilerPath under which BizTransactions Studio will find the Java compiler (javac.exe) for generating the business object classes.

VB CompilerPath under which BizTransactions Studio will find the Visual Basic compiler (vb6.exe) for generating the business object classes.

NET CompilerPath under which BizTransactions Studio will find the .NET compiler for the genera-tion of the business object classes (vbc.exe)

Project TypeVB only: Type of component to be generated

AutoVersionVB only: Specifies if the version numbers of the new business object classes are to be incremented automatically.

COMDLL Studio generates the Visual Basic classes, a dynamic library and a Visual Basic project with the ProgrammaticId BusinessObjectName. The library is registered

COMEXE Studio generates the Visual Basic classes, an executable Visual Basic program and a Visual Basic project with the ProgrammaticId BusinessObjectName. The program is registered.

Classes Studio generates the Visual Basic classes and a Visual Basic project without values for compatibility and with the ProgrammaticId *Classes*.

i



CompanyVisualBasic: Defines the copyright note in the project fileJava: First part of the package nameNET: First part of the namespace

CompatibilityVB only: Specifies the response when an incompatibility with existing components is detected:

YES Studio generates the business object classes so that they are compatible (default setting).

NO Studio tries to generate the business object classes so that they are compatible. When an incompatibility is detected, the old component is deregistered and generated incompatibly.

QueryWebServiceJava and .NET only: Specifies whether a query web service is to be generated (see section “Web service” on page 376).

OfficeResearch.NET only: Specifies whether an OfficeResearch web service is to be generated (see section “Office Research web services” on page 387).

JavaPortletJava only: Specifies whether files for a portlet are to be generated.

General purpose portlet solutions, for example the connection to portals that support JSR168, are available free-of-charge with version 7.0. You can download this software and the associated documentation from the WebTransactions home page: http://www.Fujitsu-Siemens.com/WebTransactions.




5.8.2 Generating business object classes

The BizTransactions Studio creates a business object class with all the methods and properties. When the business object is generated, the test interface is also created in the selected generation language.

Proceed as follows to generate a business object class and the test interface:

Ê Mark the business object that you want to generate classes for in the catalog window.

Ê Select the command File/Generate.

Ê Select the option Classes (Business Objects) and Test interface in theGenerate Business Objects dialog box.

Ê If you want to modify the options for the current generation (e.g. the generation language), open the Edit Options/Code Generation dialog box with Options. You can set the options for the current generation here.

Ê If you have changed the options and have generated the business object before then select the option Replace generation options with local generation options? Several cases arise depending on whether you have generated a component for the actual business object before.

The currently used generation language is output to the right of the business object name.

Ê Confirm your settings with OK to start the generation. BizTransactions Studio generates the business object classes in the programming language specified in the directory you set with Options/Edit Options/Code Generation. Subdirectories are created in the class directory during generation if needed.

Component Option Effect

already generated set The components are generated with the options set locally.

already generated not set The components are generated with the options of the previous generation.

not generated set The components are generated with the options set locally.

not generated not set The components are generated with the options that you set with Options/Edit Options/Code Generation.



5.8.2.1 Generation results for .NET

You will find the following files under class-directory\host-application\business-object:

Directory File1

1 Company: Value of the Company option in the Edit Options dialog boxBO: Business Object, metalabel for the current valueHA: Host Application, metalabel for the current value

Description

Gen Options.xml Options from the last generation

NET AssemblyInfo.vb Assembly information on the business object

BizTAClasses.vb All user-defined classes

BizTAFunctions.vb All user-defined functions

BizTAServices.vb All services of the business object

CompileBusinessObject.BAT

Batch file for compiling the business object

BO.vb Source of the business object

BO.vbproj Visual Studio project file for the business object

NET\Bin Company.HA.BO.dll Business object class as dynamic link library

Company.HA.BO.pdb Debug database

Company.HA.BO.xml XML documentation for the business object

NET\DOC BO.ndoc XML parameter field for NDocIf you have installed NDoc (Code Documentation Gener-ator for .NET) then you can double-click on this file to create documentation for the business object (see page 133).



XML documentation

When a .NET business object is generated, the file business-object.ndoc is created in the directory class-directory\host-application\business-object\NET\DOC.

If you have installed the program NDoc (Code Documentation Generator for .NET, see http://ndoc.sourceforge.net/), you can create XML documentation for the business object.

Figure 12: Creating XML documentation for .NET business objects

Ê To do this, double-click on the file business-object.ndoc. Ndoc generates the business object documentation from the files business-object.dll and business-object.xml. All the descriptive texts that you have created in the catalog are taken over into the documen-tation.

http://ndoc.sourceforge.net/



Test interface

A batch file that starts the test program is created in the directory host-application\business-object\NetGui. You double-click on this batch file in the Explorer to start the test interface.


Directory File1

1 Company: Value of the Company option in the Edit Options dialog boxBO: Business Object, metalabel for the current valueHA: Host Application, metalabel for the current value

Description

NetGui BizTaCallBO.vbproj Visual Studio project file

BizTaTestBo.vb Source generated by BizTransactions Studio for calling the business object methods

CallTestGUI.bat Batch file to start the test interface

CompileTestGUI.bat Batch file to compile the test interface

Net-Gui\Bin

BizTaCallBO.dll Assembly generated by BizTransactions Studio for calling the business object methods. The call sequences for all the methods are located here.

BizTaCallBO.pdb Debug database for the Test Helper Assembly

net.fsc.BizTransactions.BusinessObjectEvents.dll

Assembly for supplying events between business object test interfaces2

2 These files are copied to the directory if you work with Visual Studio since a HintPath points to the corresponding file during compilation (a “local copy” is generated). When generating the web service, BizTransactions uses the file CompileTestGUI.bat. This points directly to the business object in class-directory\Net\Bin.

Company.HA.BO.dll Business object to be tested

Company.HA.BO.pdb Debug database2

Company.HA.BO.xml XML documentation for the business object2



5.8.2.2 Results of the Java generation


Test interface

A batch file is generated to compile and start the Java program in the subdirectory host-application/business-object/JavaGui. You start the test interface by double-clicking on the batch file in the Explorer.


Directory1

1 Company: Value of the Company option in the Edit Options dialog boxclass, service, method: Metalabel for the current valueBO: Business Object, Metalabel for the current valueHA: Host Application, Metalabel for the current value

File1 Description


Java BizTaFunctions.java Class with the user-defined functions

class.java Java class for each user-defined class class

manifest.txt Metainformation for the files in the Jar archive

BO.bat Batch file for compiling and starting the Java program

BO.jar Jar archive with the executable Java classes for business object and services

BOSrc.jar Jar archive with the Java source programs for business object and services

Java\Company\HA\BO

c_method_ret.java Return class for method

service.java Service class for individual service

BO.java Business object class

BOWSIF.java Interface class for business object

Directory File1

1 BO: Business Object, Metalabel for the current value

Description

JavaGui BizTaData.java Business object-specific variables

BizTaJavaGui.java Business object class for test interface

BOTestBO.bat Batch file for compiling and starting the Java program

BizTaTestBO.java Business object class



Testing the interface under Solaris

Proceed as follows to test the test interface on a Solaris host:

Ê Start the compilation of the test interface by double-clicking on the batch file class-directory\host-application\Java\business-object.bat in order to create the JAR archive for the test program.

Ê Transfer the following archives in binary form from WIndows to Solaris

– class-directory\host-application\Java\business-object.jar– class-directory\host-application\JavaGui\BoTestbusiness-objectJavaGui.jar– BizTransactions-installation-directory\Templates\Java\BOTest.jar

Ê Set the environment variables LD_LIBRARY_PATH and CLASSPATH according to your host environment, e.g.:

setenv LD_LIBRARY_PATH /opt/BizTrans/7.0/lib

setenv CLASSPATH /opt/BizTrans/7.0/lib/bizta.jar:./_ BoTestbusiness-objectJavaGui.jar:./business-object.jar:./BoTest.jar

Ê Now start the test interface in the directory in which the archive is located with the following command:

java BizTaJavaGui



5.8.2.3 Generation results for ActiveX


Checking business object names for uniqueness

When an ActiveX business object is generated, a check is made to see if the name already exists in the Registry database. If yes, then the generation is cancelled under certain circumstances and the following dialog box appears:

Directory File1

1 class, service: Metalabel for the current valueBO: Business Object, Metalabel for the current value

Description


VB BizTaSup.bas Global variables in BizTaSup

BizTaFunctions.bas Class with user-defined functions

class.cls Visual Basic class for each user-defined class

service.cls Service class for individual service

BO.cls Business object class

BO.dll Business object class as dynamic link library

BO.exe Business object class as executable program

BO.vbp VB project for business object class



The generation can be cancelled for one of the following reasons:

This dialog box is not displayed when

– the component has not been registered yet– a component that has already been registered is a BizTransactions business ob-

ject and is located in the current output directory

Notes

If you have already generated a business object component for Visual Basic and the component is already in the correct directory, note the following:

1. If you have not changed the interface of the business object:

The notation of the methods remains the same, and you have not changed the properties. In this case, BizTransactions Studio uses the compatible mode for the generation process. All callers (clients) can work with your business object without any changes. Explicit deregistration is not necessary.

To ensure compatibility, BizTransactions copies the component to the \Ref subdirectory and changes the version compatibility in the project to binary compatibility. If the subdi-rectory does not yet exist, it is created.

Cause Action

The component is already registered. The corresponding file for this component is not present, however, meaning it was deleted without deregistering it.

There are two ways to do this:

Ê Stop the generation with Cancel, remove the entry with RegClean from the Registry database and then restart the generation.

Ê Assign the component to be created a different Name and resume the generation with OK.

The registered component is a BizTransactions business object. However, this object is not in the current output directory.

If you want to resume the generation, you can do so in one of the following two ways:

Ê Assign the component, and therefore the project, a different name and a different description.

Ê Deregister the component using the Deregister button. The old component is deleted from the Registry database and you can then generate the new component.

i



2. If you have changed the interface of the business object:

BizTransactions Studio tries to generate the component so that it is compatible. If that is not possible and you have selected Yes for Compatibility under the Generation Options, the generation process is terminated with an error for the current business object and generation continues with the next business object, if applicable.

If you have selected No for Compatibility under Generation Options, the existing component is deregistered and the business object component is created so that it is not compatible (project-compatible).

If the component is referenced with early binding, all the callers (clients) must delete the old reference and set a new reference. If the component is referenced with late binding, callers do not have to change anything.

3. You have changed the project type of the component to be generated (from ActiveX DLL to ActiveX Exe) under Generation Options.

If the old component is still registered and you have selected Yes for Compatibility under Generation Options, the generation process is terminated with an error for the current business object.

If you have selected No for Compatibility under Generation Options, the business object component is created so that it is not compatible (project-compatible). However, this leaves you with two entries in the Registry database, one for the DLL component and one for the Exe component. You can change the programmatic ID, which defines the name of the reference, for a component.

To ensure compatibility, BizTransactions copies the new component to the \Ref subdi-rectory and changes the version compatibility in the project to binary compatibility. If the subdirectory does not yet exist, it is created.

If compatibility problems occur in this generation process, you should deregister the old component manually, delete the project file and generate the component again.



Changing the programmaticID of an ActiveX component

If you have generated two different components for Visual Basic (DLL and Exe), you can change the programmatic ID of one of the components in order to differentiate between them better. The programmatic ID specifies the name of the reference for clients.

To change the programmatic ID in the Visual Basic project, proceed as follows:

Ê Open the command prompt in Windows, and deregister the component by means of one of the following commands.

For the Exe component: boname.exe /unregserver

For the DLL component: regsvr32 /u boname.dll

Ê Open the component (the project) in Visual Basic, and choose the Project/Properties command.

Ê In the Properties dialog box, change the Project Name and Project Description properties, and then click OK to confirm.

Ê Create the component again in Visual Basic by choosing File/Create projectname. In subsequent generation runs in Visual Basic, the existing project name is read from the project file.

Test interface

A VB project is generated in the server-application/business-object/VBGui subdirectory. The generated project file can be opened in Visual Basic. The project can be used immediately: You can start it right away via the Visual Basic menu command Execute/Start.

You will find the following files in the VBGui subdirectory of class-directory\host-application\business-object:

Directory File Description

VBGui BizTaData.bas Global variables

BizTaTestBO.cls Business object class for test interface

BizTaVBGui.vbp VB project to test the business object



5.8.3 Generating a web service

By using a WSDL file, you can

● integrate your business objects in WebTransactions

● make them available on the web directly as web services

Before you can generate a WSDL file for your business object, you must have generated a business object class (generation option Classes (Business Objects) and Test interface, see section “Generating business object classes” on page 131).

5.8.3.1 Generating and deploying a Java web service

To generate a web service for the business object, BizTransactions uses the Java Web Services Developer Pack V1.3 (JWSDP 1.3) developed by Sun Microsystems. JWSDP is supplied with BizTransactions (see chapter “Installing and configuring BizTransactions” on page 261).

To generate a web service for the business object, proceed as follows:

Ê In the Catalog window, select the business object for which you want to generate a web service.

Ê Choose File/Generate. The Generate Business Objects dialog box opens.

Ê Choose the option Web Service and WSDL file and confirm with OK.

Result of generation

The Java subdirectory of class-directory\host-application\business-object contains the following files:

File Description

Business Object.war WAR archive of the web service

Business Object.ear OC4J only: EAR archive of the web service

Business Object.wsdl Java-based WSDL file of the web service

CallWebService.cmd Script for testing the web service using the add-onCallWebServices



Deploying web services

If web service deployment is to be performed automatically,

● you must have selected one of the following servlet engines when installing JWSDP (see chapter “Installing and configuring BizTransactions” on page 261):

– Tomcat as a component of JWSDP (V5.0)– Tomcat installed independently of BizTransactions (V4.1 or higher)– Locally installed stand-alone Oracle OC4J Server

● the servlet engine must be started. You can, for example, start the Tomcat engine supplied with JWSDP via the program group that was set up during BizTransactions installation: Start/Programs/Java(TM) Web Services Developer Pack 1.3/Start Tomcat.

After deployment, the web service is available for testing.

Calling web services

The web service is available under the following URL:

● In the case of Tomcat, under the URL Tomcat Root URL/business-object/business-object

Example

If you entered http://localhost:8080 in the Tomcat Root URL field during installation then the URL for the business object MyBo ishttp://localhost:8080/myBO/myBO

● In the case of a local stand-alone OC4J Server, under the URL http://localhost:port/BizTA/business-object

Example

If OC4J Server uses port 8888 then the URL for the business object MyBo ishttp://localhost:8888/BizTa/myBO

You can also test the web service using the add-on CallWebServices. CallWebServices is supplied with BizTransactions.

Ê To do this, double-click on the file CallWebServices.cmd which is generated in the directory class-directory\host-application\business-object\Java.

CallWebServices is then called with the associated WSDL file business-object.wsdl.



5.8.3.2 Generating and deploying .NET web services

WSDL generation for .NET is performed using Microsoft’s .NET Framework. When BizTransactions is installed, a check is performed to determine whether the Framework is installed on your system (see chapter “Installing and configuring BizTransactions” on page 261).

Microsoft’s Internet Information Services (IIS) must also be installed and started alongside the .NET Framework.

To generate a web service for the business object, proceed as follows:

Ê In the Catalog window, select the business object for which you want to generate a web service.

Ê Choose File/Generate. The Generate Business Objects dialog box opens.

Ê Choose the option Web Service and WSDL file and confirm with OK.

Result of generation

All the web service files must be located in a “virtual” directory. BizTransactions generates all the web service files in the directoryclass-directory\host-application\business-object\NetWebService and defines this directory as a virtual directory at generation time.

i




Directory File1

1 BO: Business ObjectHA: Host ApplicationCompany: Value of the Company option in the Edit Options dialog box

Description

NetWebService BO.asmx asmx file for the web service. This file con-tains the web service directive and is used as the entry point for the web service.

BO.asmx.resx Resource file for the web service

BO.asmx.vb Implementation of the web service

HA.BO.sln Visual Studio solution file for the web service

HA.BO.vbproj Visual Studio project file for the web service

HA.BO.vbproj.webinfo Visual Studio web info file for the web service

HA.BO.vsdisco Visual Studio: XML file for the dynamic dis-covery of web services

HA.BO.wsdl WSDL file for the web service

CallWebservice.bat Batch file for testing the web service

CompileWebService.bat Batch file for compiling the web service

Web.config Configuration file for the web service

NetWebService\Bin Company.WS.HA.BO.dll DLL for the web service

Company.WS.HA.BO.pdb Debug database for the web service

Company.HA.BO.dll DLL for the business object2

2 These files are copied to the directory if you work with Visual Studio since a HintPath points to the corresponding file during compilation (a “local copy” is generated). When generating the web service, BizTransactions uses the file CompileTestGUI.bat. This points directly to the business object in class-directory\Net\Bin.

Company.HA.BO.pdb Debug database for the business object2

Company.HA.BO.xml XML documentation for the business object



BizTransactions also generates a client proxy with which the web service can be called from a client application.

When the client proxy is generated in Visual Studio (indirectly with wsdl.exe), the properties of the user-defined classes are replaced by “simple” public fields. The files in NetWebService\ClientProxy eliminate this problem. Properties are generated instead of public fields of classes (see also section “Dynamic assignment of the URL in the .NET client” on page 147).


Directory File1

1 Company: Value of the Company option in the Edit Options dialog boxBO: Business ObjectHA: Host Application

Description

NetWebService\ClientProxy

Company.CallWS.HA.BO.dll Client proxy DLL

Company.CallWS.HA.BO.vb Source of the client proxy

Company.CallWS.HA.BO.xml XML documentation for the client proxy

Company.CallWS.HA.BO.txt Temporary file for generating the proxy source

NetWebService\Client-Proxy\Doc

Company.CallWS.HA.BO.ndoc XML parameter file for NDocIf you have installed NDoc (Code Docu-mentation Generator for .NET) then you can double-click on this file to create the client proxy documentation.



Calling web services

There are various ways of calling a web service generated with BizTransactions:

● With Internet Explorer:You can call simple web service methods with Internet Explorer.

Ê Enter the URL of the file business-object.asmx in Internet Explorer.

The web service is displayed and you can now select methods, enter parameters, start a method and view the result in XML notation.

This procedure is only possible in the case of simple input data because

– HTTPGET/POST links do not provide any method for sending and receiving header information.

– the coding of in/out or out parameters in the message returned by the client as the result of an HTTPGET/POST request is not supported.

● With the add-on CallWebServicesCallWebServices is supplied with BizTransactions. You can use this program to create a client proxy class for a web service on the basis of the generated WSDL file and test the web service.

Ê For test purposes, double-click on the file CallWebServices.bat which was gener-ated in the directory class-directory\host-application\business-object\NetWebService.

CallWebServices is then called with the associated WSDL file business-object.wsdl.



Testing web services

BizTransactions generates trace statements whenever you perform generation with the Debug variant, (see section “Generation options” on page 128). You can, for example, use the following tools to diagnose problems that occur during the exchange of SOAP messages between the client and the web service:

● Application trace with Trace.axd

In this case, you must edit the web service’s Web.config file accordingly (see section “Result of generation” on page 143):

<compilation defaultLanguage="vb" debug="true" /><trace enabled="true" requestLimit="10" pageOutput="false" traceMode="SortByTime" localOnly="true"/>

You will then find the application trace in Internet Explorer under the following URL:http://myhost/myWebService/Trace.axd

● Monitor message transfer with MsSoapT3.exe

You can use the tool MsSoapT3.exe to monitor the message traffic between the client and the web service. This tool is present in Microsoft’s SoapToolKit.

● With the add-on CallWebServices

With CallWebServices, you can display both the trace and the message traffic after calling web service methods.

Dynamic assignment of the URL in the .NET client

Moving the web service to another location renders the URL in the client invalid. The proxy class’s URL property must be set to the new value in the client.

Example

Me.Url = "http://myServer/ApulsPULS/PULS.asmx"

However, you can also create the proxy class in such a way that the URL is read from the client’s configuration file and overwrites the default value. In this case, it is not necessary to modify the client.



The procedure depends on the the way the proxy class was generated:

● Microsoft Visual Studio: add a web referenceThe assigned URL is hard-coded in the constructor of the proxy class generated by Visual Studio.

Example

Public Sub New()MyBase.NewMe.Url = "http://localhost/ApulsPULS/PULS.asmx"

End Sub

You can change the URL_Behavior attribute from Static to Dynamic in the properties of the web service reference. The constructor is modified accordingly.

Example

Public Sub New()MyBase.NewDim urlSetting As String =

System.Configuration.ConfigurationSettings.AppSettings("MyKey")If (Not (urlSetting) Is Nothing) Then

Me.Url = String.Concat(urlSetting, "")Else

Me.Url = "http://localhost/ApulsPULS/PULS.asmx"End If

End Sub

Example in a configuration file (extract from the file App.Config)

<configuration><appSettings>

<add key="MyKey" value="http://myServer/ApulsPULS/PULS.asmx"/></appSettings>

</configuration>

If MyKey was set in the configuration file, then the value is taken from the configuration file. Otherwise the default value applies.

For further information, see the Microsoft Visual Studio online help system.

● Generate a proxy class with WSDL.EXEYou can use the .NET tool WSDL.EXE to generate a proxy class manually. You use the switch /appsettingurlkey to modify the class constructor in such a way that the URL is read from the configuration file.

For further information, see the .NET Framework online help system.



● BizTransactions proxy classBizTransactions generates a proxy class (see section “Result of generation” on page 143). This class also contains a modified default constructor.

Example

Public Sub New()MyBase.NewDim sURL = System.Configuration.ConfigurationSettings.AppSettings("URL")If sURL Is Nothing OrElse sURL.Length = 0 Then

Me.URL = "http://localhost/ApulsPULS/PULS.asmx" ' not specified, take default

ElseMe.URL = sURL ' explicit URL

End If

If an URL has been set in the configuration file then this is used. Otherwise the default value is used.

In addition, all the public fields in user-defined classes are replaced by properties. This means that you can use Data Binding in the client.

Example

Instead of Public Product As String = "" the following code is generated

Private _Product As String = ""

Public Property Product() As StringGet ' Public field changed to property!

Return _ProductEnd GetSet(ByVal Value As String)

_Product = ValueEnd Set

End Property

You can make this proxy known to your client via the command References/Add Reference.

You will find a detailed example in the tutorial Using BOs.doc that is supplied with BizTransactions. You will find this file in the BizTransactions installation directory underExamples\Documents\En\ExampleUPIC\Tutorial Using BOs.doc.



Deploying web services on another host

The following conditions must be fulfilled before you can deploy a web service on another host:

● The BizTransactions runtime system must be installed (see the WebTransactions manuals for the host adapters).

● Microsoft’s Internet Information Services (IIS) must be installed and started.

● You must have created a virtual directory and saved the following files there:

– the file Business Objekt.asmx – the full NetWebService\Bin directory– the file Web.Config

5.8.3.3 Activating WSDL generation for Visual Basic

If you want to generate a WSDL file from Visual Basic objects, you must first install the Microsoft Soap Toolkit that is currently available in Version V3.0. After the installation, the Toolkit is registered.

After the first WSDL file is generated the program call can be found in the Registry in the key HKEY_CURRENT_USER/Software/VB and VBA Program Settings/BizTa-Studio/ClassGenOptions/GenWSDL4VB. This allows BizTransactions Studio to find the Toolkit automatically.

When you install a newer version of the Toolkit and the automatic detection does not work any more, store the name of the program (e.g. wsdlgen31.exe) in this key.


BizTransactions Studio Creating report files

5.9 Creating report files

BizTransactions Studio allows you to generate information on individual business objects or on all objects in the current catalog:

● Host applications

● Services

● Business objects

● Classes

● Functions

The report files show the values of the attributes of the catalog objects and subordinate catalog elements. This information is output in HTML files that can be displayed immedi-ately. If you want to redisplay the report files, you should use a browser (landscape format is generally required for printing).

The report files are stored in the directory that you assigned in the Output to field of the Create Report Files dialog box.

Proceed as follows to create report files:

Ê Select the view of the objects for which you want to create reports in the Catalog window.

Ê In this view, select the catalog objects, e.g. all services of a host application.

Ê Select the command File/Create Report Files. The Create Report Files dialog box appears.

Ê If necessary, change the Output to.

Ê Confirm your selection with OK. The report files are generated in the output directory specified and are displayed on the screen in the HTML browser.

An HTML file is created for each catalog object. The structure of each file depends on the type of object it was created for. For the business objects .bmp files are also created that contain the graphical representation of the method. When the object is locked, you will be shown information regarding why the object is locked.

Host application

The report file contains a list of all attributes of the host application and their values in a table.


Creating report files BizTransactions Studio

Services

The report file contains the following tables

● All attributes of the service and their values

● All buffers and their attributes

● All records and fields in the buffer and their attributes

● All business objects and their methods that use this service

Business objects


● All attributes of the business object and their values

● All properties and their attributes

● All methods, the corresponding method parameters and their attributes

● The flow chart, the local variables and their intermediate code for each method

● An overview of all services, classes and functions used by this business object

Classes


● All attributes of the class and their values

● All class properties and their attributes

● An overview of all business objects, classes and functions that use this class

Functions


● All attributes of the function and their values

● All function parameters and their attributes

● The code of the function

● An overview of all business objects that use this function


6 Editing the code of a methodAfter creating a new method, you can

● Record dialogs, see sections “Recording dialogs for UPIC applications” on page 157 and “Recording dialogs for terminal applications” on page 162.

● Model the method, see section “Modeling a method” on page 177.

● Edit the method’s code, see section “Editing statements” on page 187.

You use all these functions in the Edit method window.

The section “Example” on page 251 at the end of this chapter provides a detailed example of how to structure the flows in a business object.

6.1 The Edit method window

You open the Edit method window in the main window of BizTransactions Studio by

● selecting the Edit/Edit Method command for a selected method.

● double-clicking on a method or a lower-level element of the method in the Edit window.


The Edit method window Editing the code of a method

Figure 13: The Edit method window

The following areas appear in the Edit method window:

● Title bar with the name of the current business object and of the method

● Menu bar

● Toolbar

● the modeling area (not visible when the window is opened)

● the programming area

● the code tree structure with the service nodes and statements.

Toolbar

Title barMenu bar

Tree structure

Programmingarea

Modeling area


Editing the code of a method The Edit method window

6.1.1 The modeling area

The modeling area is located directly below the menu bar in the Edit method window. You use the View/Show Service Graph command to display the modeling area. The individual service nodes of the method appear in the modeling area symbolically in the form of a flow chart that represents the flow of the method. You can edit this flow, see section “Modeling a method” on page 177.

You can

● insert icons for new service nodes (Communication/Insert Service Node)

● edit attributes of the service node

● change the order of the services (by changing the connections)

● create, modify or delete new connections

● create any number of branches

When you select a service node in the modeling area, it will also be selected in the code tree structure.

The chart of the service nodes in the modeling area is changed with the commands in the Modeller menu.

6.1.2 The programming area

In the programming area you edit

● the attributes of the services nodes from the modeling area

● the statements from the code tree structure

As soon as you have selected a service node or statement in the modeling area or in the code tree structure, the display in the programming area changes. You will see one or more buttons that open dialog boxes in which you can further edit the service node or statement. A detailed description of the statements and their processing can be found in the BizTransactions Studio online help system.

As soon as you edit the service node or statement, the OK, Cancel and Help buttons appear with which you can confirm or cancel editing.

The changes are only accepted in the code tree structure after you have confirmed your changes with OK.


The Edit method window Editing the code of a method

6.1.3 The code tree structure

The code tree structure contains the existing code of the method. After the root node, the method name, you see

● the local variables of the method

● each service node that the method calls and executes

● the statements in the service nodes to be processed


Editing the code of a method Recording dialogs for UPIC applications

6.2 Recording dialogs for UPIC applications

When capturing a method, you open a model session with the host application in which you run through the dialog steps to be executed when the method is called at runtime.

During the process, BizTransactions automatically generates the corresponding code, which can then be edited later on in the Edit method window. This code is accessed by the BizTransactions Studio when generating the business object classes.

6.2.1 The Record Dialog window

The Record Dialog window opens when you select the Recording/Record Method command in the Edit method window for a selected method.

From top to bottom, the Record Dialog window consists of

● Title bar with the name of the current format of the server application

● Menu bar

● Toolbar

● Work area

In the work area, you see the screens of the host application, if you have imported the formats into the catalog as XML files during communications via UPIC. For more information, see also section “Importing service data of UPIC applications” on page 119.

If no formatted presentation is possible during communications via UPIC, the dialog box Record Dialog: UPIC application opens. The dialog box is opened if

● communications are performed via data buffers

● a catalog migrated from BizTransactions V2.0 is present In BizTransactions V2.0, no presentation data was recorded in the catalog. For this reason, no formatted presentation is possible in the case of such old migrated catalogs.


Recording dialogs for UPIC applications Editing the code of a method

Figure 14: The Record Dialog window

On the left you see a tree structure with the records and fields of the current data buffer. On the right in the dialog box you see the buttons you use to edit the data and control the recording of the dialog.

If you communicate via UPIC, you first need to select the service that starts the dialog with the host application in the dialog box Select Start Service.

Title barMenu barToolbar

Work area

i



6.2.2 Record Dialog with a UPIC application without a formatted presentation

Communication with a UPIC application is performed via a data buffer when

● the UPIC application does not supply any formats for the presentation

● you have already imported the formats in version 2.0 of BizTransactions or earlier

Proceed as follows to record the dialog with a UPIC application without a formatted presen-tation:

Ê Select the business objects view in the catalog window and open the business object whose procedure you want to record as a method in the Edit window.

Ê Select the method in the tree structure of the edit window and choose the commandEdit/Edit Method. The Edit method window opens.

Ê Select Recording/Record Method in the Edit method window. The Select Start Service dialog box opens in which you select the service that the recording will start with.

Ê Select a start service and then click on the Continue button.

Ê The Record Dialog: UPIC application window opens. In the tree structure on the left you see the data of the current data buffer, and with the buttons on the right you control the communication with the UPIC application.

Ê Select the relevant fields one after the other in the tree structure and enter the required values in Value.

Ê Set a function key and a transaction code for the next service if necessary.

Ê Send the data buffer to the UPIC application with Send. Usually the data received from the server application is displayed immediately in the tree structure thus you can continue with the last step.

Ê If BizTransactions Studio cannot assign the data received from the server application to a service automatically (e.g. no format recognition available) then you must assign the data to a service. To assign the data select the appropriate service from the list and select Show received data to display the data buffer received in the tree structure.

Ê Repeat the last three steps until the entire dialog is recorded.

Ê To complete the recording, select Stop. BizTransactions Studio automatically creates code corresponding to the recording and displays it in the code tree structure in the Edit method window.


Recording dialogs for UPIC applications Editing the code of a method

Recording partial formats and message segments

For openUTM applications that communicate via UPIC, the Change Recording Options dialog box contains the option Work with partial formats. If you select this option, you can also capture partial formats and message segments without format identifiers.

This option must be switched on before receiving partial formats or message segments. The appropriate service (=partial format) must be selected before sending the partial formats to the host application. You must naturally put them in the order expected by the host application.

Proceed as follows to receive partial formats and message segments:

Ê Select the command Options/Recording Options command in the Record Dialog dialog box. The Change Recording Options dialog box appears.

Ê Select the Work with partial formats option in this dialog box and confirm with OK. The dialog box closes and you can now capture partial formats and message segments as well.

Ê Click on Send to send the selected service to the host application.

Ê Click on Get Next to receive and display the first message.

Ê Click on Get Next until all the message segments have been received. If there are no more message segments available, then the Get Next button is grayed out so that you cannot select it any more. The Select a send service list is activated at the same time.

Ê Select the service whose data you want to send to the host application from the Select a send service list and then click on Send.

Ê Repeat the last three steps until all required data has been sent.

Ê Continue with the third step to capture additional partial formats and message segments.



6.2.3 Dialog with a UPIC application with formats

The formats of a UPIC application are displayed when recording a dialog once you have converted the formats of a UPIC application to XML and imported them in the catalog.

Proceed as follows to record a dialog with a UPIC application with format identifiers:

Ê Select the business objects view in the catalog window and open the business object whose procedure you want to record as a method in the Edit window.

Ê Select the method in the tree structure of the edit window and choose the command Edit/Edit Method. The Edit method window opens.

Ê Select Recording/Record Method in the Edit method window. The Select Start Service dialog box appears and you can select the service that the recording will start with.

Ê Select a start service and then click on the Continue button to confirm. The Record Dialog window with the first format of the host application opens.

Ê When you have provided all input fields of the format with the necessary data, set another function key if necessary and use the command File/Send to send the format to the host application.

Ê Repeat the last step until the entire dialog is recorded.

Ê To complete the recording, select an Exit command in the File menu. BizTransactions Studio automatically creates code corresponding to the recording and displays it in the code tree structure in the Edit method window.

If you want to capture partial formats or message segments, proceed as described in section “Recording partial formats and message segments” on page 160.

What is the next step?

If you wish to modify the captured dialog (e.g. remove superfluous screens, combine repet-itive screens, or add new screens), select Model Method (see section “Modeling a method” on page 177).

If you do not wish to make any changes to the dialog and the recording does not contain any scrolling screens, skip the “Model Method” step and select “Edit Code” next in order to adapt the automatically generated code (see section “Editing statements” on page 187).

i


Recording dialogs for terminal applications Editing the code of a method

6.3 Recording dialogs for terminal applications

In the same way as when recording a method for a UPIC application, when conducting a model terminal application session with the host application, you work through all the dialog steps that are to be executed when the method is called at runtime. When you do this, BizTransactions automatically generates the corresponding code which you can then subse-quently edit in the Edit method window. BizTransactions Studio accesses this code when generating the business object classes.

Unlike when recording a method for a UPIC application, it is usually possible to generate the complete code for use at runtime when working with a terminal application. Subsequent editing of the code using the functions provided by BizTransactions Studio is only necessary in exceptional cases.

BizTransactions provides the following functions for editing terminal applications:

● Inputs:For each format, you can decide which inputs you want to parameterize. For example, you can enter a special login name during recording. However, at the same time, you can specify during recording that this login name is to be taken over from a method parameter at runtime.

● Output fields:For each format, you can assign the format’s output fields to a method parameter or property. Alongside simple output fields that are taken over as they are, you can also assign internally structured output fields to individual method parameters or properties. For example, if a line in a format contains an address, you can assign the individual components such as the ZIP code or street to the specific output parameters “ZIP Code” and “Street”.

● Tabular data:Tabular data can be assigned to user-specific classes. The automatically generated code transfers the tabular formats to user-defined classes. If the format is worked through a number of times in succession, the data is continuously appended.

● BizTransactions data types:There are method parameters and properties for all BizTransactions data types - including user-defined classes.

● Modeling of methods:A flow chart containing service accounts is created during recording. This represents the control flow of the services or formats that have been processed. You can model this chart at the end of the recording process.


Editing the code of a method Recording dialogs for terminal applications

6.3.1 The Record method window

The Record method window is opened when you select the Recording/Record Method command for a selected method in the Edit method window.

Figure 15: The Record method window

From top to bottom, the Record method window consists of

● a title bar with the name of the business object, the name of the current method and the name of the current format

● a menu bar

● the work area

When you call the window, the catalog, the host application, the host computer and the BCAM application name of the host application are displayed in the work area together with the business object and the method.

When you start recording (Start recording button), the first format of the host application is displayed in the work area.

Menu bar

Work area

Title bar



You now see the four tabs for the various views in the work area (see section “Views in the Record method window” on page 234):

Emulation The current format is displayed in the same way as it would be displayed in an emulation.

Grid The current format is output in a grid. Each character in the format is displayed in a cell.

Code The method’s parameter, the properties and local variables, the current format and the current code are output in a tree.

All Services All the services of the host application that are recorded in the catalog are output in a list.



6.3.2 Recording a dialog with a terminal application

To record a dialog wit a terminal application, proceed as follows:

Ê Select the business objects view in the catalog window and open the business object whose procedure you want to record as a method in the edit window.

Ê Select the method in the tree structure of the edit window and the Edit/Edit Method command. The Edit method window opens.

Ê Choose the command Recording/Record Method in the Edit method window. The Record method window opens with a description of the method.

Ê Start recording by clicking the Start recording button in the Record method window.

The Record method window opens with the first screen of the host application. If the screen is already known, you see the name of the screen in the title bar and can continue with the next step but one. Otherwise, the Record method window opens in Grid view in which you can define the recognition criteria for the screen.

Ê In Grid view, enter the recognition criteria using the functions in the Screen recognition menu (see section “Format recognition” on page 167).

Ê Enter the necessary data in the input fields and, if required, specify the parameters from which the value should be taken at runtime.

Ê If necessary, assign output data to the required output parameters.

Ê If necessary, edit the method’s code, see section “Editing statements during method capture” on page 234.

Ê When all the required data has been entered for all the screen’s fields and, if necessary, the code has been modified appropriately, send the screen to the host application with File/Send or File/Send with function key.

Ê Repeat the above steps for each screen until the complete dialog has been recorded.

Ê Now choose one of the Terminate commands in the File menu. BizTransactions opens the Modeller window.

Ê If necessary, modify the sequence of dialog steps (see section “Modeling a method” on page 177).

Ê To terminate recording, close the Modeller window with OK. BizTransactions automatically generates a code corresponding to the captured record and displays this in the code tree structure in the Edit method window.



What is the next step?

If you want to use the recorded, modified code without further changes, choose one of the Save commands in the File menu. The Edit method window closes and your changes are permanently saved.

If you want to further process the code, choose “Edit code” and adapt the code that was automatically generated during recording to your individual requirements (see section “Editing statements after capturing a method” on page 196).



6.3.3 Format recognition

In the case of terminal applications you can record the service data (records, fields) while capturing (recording) the method. BizTransactions uses the recognition criteria later to identify the formats received and to determine the appropriate format description in the services.

During recording, the structure information of the new format, i.e. the fields and records, is captured automatically. BizTransactions creates a buffer for each screen during the capture procedure with the send direction set to Both. The buffer starts at position 1, and its size is calculated from the size of the screen format: lines x columns. An extra line is added to 9750 formats for the status line.

The format description and recognition criteria are stored in the service.

Explanation

During communication between business objects and host applications, only net data is transferred, i.e. pure user data without structure information.

When executing methods, therefore, the screen formats received by the host application must be identified internally in order to assign the appropriate services.

When communicating via the UPIC protocol, this is not a problem as the format names are also transferred via this interface. However, this is not the case when communicating on the basis of the 9750 and 3270 emulation protocols. In order to identify the individual screen formats when communicating via emulations, therefore, BizTransactions accesses the format recognition data.



6.3.3.1 Creating recognition criteria

If an unknown screen format is received during the recording of a method, you must first define a recognition criterion for this format.

To do this, it is not necessary to interrupt the recording of the method:

Ê To define recognition criteria for individual screen formats, use the left mouse button to select an area in the Grid view.

Ê Choose Define screen recognition and then, if no further areas are required for screen recognition, End screen recognition in the Screen recognition menu. You can find a detailed description of the commands and functions in the online help system.

You can use the following characters for format recognition:

● a - z

● A - Z

● 0 - 9

● - " " % & \ ( ) = + ' ; , : . < >

6.3.3.2 Scenarios

When a format has been read from the host application, the corresponding format is searched for in the recognition criteria. The following cases may arise:

● The format is not found.

This is clearly a new format. By default, the format is output in the Grid view. You must define the recognition criteria here. A unique service name is automatically formed on the basis of this data.

You can also switch to the All Services view. Here you can assign the service BizTaUnknown as a placeholder.

● A service corresponding to the format is found.

By default, the format is output in the Emulation view. Here, you can enter values and send the format.

You can also switch to the All Services view. Here you can assign the service BizTaUnknown as a placeholder or create a new service.



● Multiple services whose recognition criteria correspond to the current format are found.

In the next dialog box, you are asked to specify the service with which you want to continue (see next section “Conflicts during format recognition”). You can then continue to work with an existing service or create a new one.

6.3.3.3 Conflicts during format recognition

If the recognition criteria are not unique it is possible that multiple formats whose recognition criteria match the current format will be found when a format is read from the host appli-cation.

You should therefore always try to describe formats using the most specific recog-nition criteria possible.

You should always use fixed texts for the recognition criteria and never variable texts such as date and time.

Working with BizTaUnknown

To avoid ambiguities, you can assign the service BizTaUnknown for a format (see section “Modeling unknown formats (BizTaUnknown)” on page 183).The service BizTaUnknown is created by default on recording if it does not already exist.

Time of format recognition

The time that format recognition occurs is of decisive importance for the prevention of conflicts:

● Format recognition during captureAll the formats of the host application are taken into account for format recognition.

● Format recognition while a business object is runningOnly those formats that are used in the business object are taken into account for format recognition.

During instantiation of the business object, the screen recognition data of all the formats that are used is made available to the host adapter after being read in. The host adapter can thus identify the format. This reduces the likelihood of conflicts.

You edit the recognition criteria used during method capture in the All Services view (see section “All Services” on page 241).

i



Examples of conflicts during format recognition

The recognition criteria in the two examples below are ambiguous. In both cases, the examples show how you can avoid or resolve the conflict.

Example 1

Screen number Indicates the sequence in which the recognition criteria are searched through and compared with the content of the format that is currently present. The screen number is assigned when the recognition criteria are entered.

Position Forms part of the recognition criterion. In this case: at position 1, the string AB is present at F1 and the string ABC is present at F2.

Format F1 “hides” format F2, since F1 has a lower screen number and is less specific that the recognition criterion for format F2. You have the following options:

● You can enter more precise recognition criteria for F1:

If, for example, an additional fixed text is present in F1 (in this case the character D), then you can take this text over into the recognition criteria.

● You can swap the screen numbers in the All Services view:

Swapping the screen numbers should only ever be the last recourse.

Format Screen number Position Recognition criterion

F1 10 1 AB

F2 20 1 ABC


F1 10 1 AB D

F2 20 1 ABC


F2 10 1 ABC

F1 20 1 AB

i



Example 2

At first sight, these recognition criteria do not reveal any conflict. Format F1 is recognized if the content AB is present as of position 1 in the read data of the current format and F3 is recognized if the content CD is present as of position 13.

A conflict occurs if you are expecting the format F3 but the content AB is present as of position 1 and the content CD as of position 13 in the read data. SInce the recognition criterion for format F1 (position =1, content =AB) has the lower screen number (in this example 10), the format F1 is recognized. F1 therefore “hides” F3.

Here again, you can resolve the conflict by specifying more precise recognition criteria. In the example, the fixed text XYZ, which does not occur in F3, has been added:


F1 10 1 AB

F3 20 13 CD


F1 10 1 AB XYZ

F3 20 13 CD



6.3.4 Recursive formats

During the method capture process, BizTransactions recognizes cases where a format is read a number of times in succession (see also section “Different types of service node” on page 181). In this case, the following dialog message is output:

The format XYZ is the same as the former format. Would you like a recursive service node or should the current format to be attached as a normal service node?

Yes Create a recursive service nodeNo Normal service node

Scenarios with recursive formats

Recursive formats may occur in various scenarios:

● Scrolling screen

Data is output in a format. This data is displayed once or more depending on the data volume.

Ê RespondYes Create a recursive service node

This inserts the entire intermediate code found in a recursive service node:

ReceiveAll the statements that you have generated during captureSend

Even though the format is worked through three times, for example, the Receive and Send statements are only generated once. On subsequent execution, the format is repeatedly worked through until another format is read.



● Input/output format

After reading the format, you may, for example, enter recognition criteria and send the format. The host application then supplies the same format - but with results.

Ê Respond:No Normal service node

This enters two service nodes:

Format XYZ-1 ReceiveMove Field (selection criteria)Send

Format XYZ-2 ReceiveMove Param (field information)Send

At runtime, the following sequence is strictly adhered to:...->Format XYZ-1 ->Format XYZ-2 ->...

● Combination of input/output format and scrolling screen

After reading the format, you may, for example, enter recognition criteria and send the format. The host application then supplies the same format multiple times - but with results.

Format XYZ-1 ReceiveMove Field (selection criteria)Send

Ê RespondNo Normal service node

Format XYZ-2 ReceiveMove Param (field information)Send

Ê RespondYes Create a recursive service node

On subsequent execution, a sequence is accepted as correct if the format XYZ occurs at least twice in succession in it: once for the input of the selection criteria (format XYZ-1) and at least once with results (format XYZ-2).

This combination gives you a new recursive format.



Recording recursive formats

The following rules apply to the recording of recursive formats:

● In the case of recursive formats, only the first Receive statement is recorded.

● All Send statements except the last are ignored.

● All FunctionKey statements except the last are ignored.Exception: if you have specified a FunctionKey statement in an If-Then-Else block then no function keys are implicitly recorded. An If-Then-Else block can be inserted during capture in the Code view (see section “Editing statements during method capture” on page 234).

Example: Recursive format without function keys

In this example, the format REK is output repeatedly.

● As long as data is still present, a plus sign (+) is displayed in the Browse Mode field.

● When the end is reached, the text “- or EXIT” is output in the Browse Mode field. To exit this loop, the host application requires a send operation with the content EXIT.

● All the formats are sent with the DUE function key.

Figure 16: Recording a recursive format without a function key

Format REK

+

Format REK

+

Format REK

- or EXIT

Receive

Move statementsFunctionKey = DUESend Delete FunctionKey and Send

If Browse Mode = "-" ThenBrowse Mode = "EXIT"

End IfFunctionKey = DUESend Delete FunctionKey and Send

Move statementsFunctionKey = DUESend



This results in the following intermediate code for the service node REK:

ReceiveMove statements..If Browse Mode = "-" ThenBrowse Mode = "EXIT" <--exit loop

End IfFunction Key=DUESend

Example: Recursive format with function keys

In this example, the format REK is output repeatedly.

● As long as data is still present, the Browse Mode field displays: Continue with F2. The format must then be sent with F2.

● When the end is reached, the Browse Mode field displays: Terminate F12.

● To exit this loop, the host application requires a send operation with the F12 key.

Figure 17: Recording a recursive format with a function key

Format REK

Continue with F2

Format REK Format REK

Terminate F12

Receive

Move statementsFunctionKey = F2Send

Delete FunctionKey and Send

If Browse Mode = "Continue" Then

FunctionKey = F2Else

FunctionKey = F12End IfSend Delete FunctionKey and Send

Move statementsSend

Continue with F2



This results in the following intermediate code for the service node REK:

ReceiveMove statement..If Browse Mode = "Continue" Then Function Key=F2Else Function Key=F12 <--exit loopEnd IfMove statements..Send

Because a FunctionKey statement is present in an If-Then-Else block, no further implicit FunctionKey statements are generated for this service node.


Editing the code of a method Modeling a method

6.4 Modeling a method

This function allows you to graphically edit the dialog recorded while capturing a method (see also “Example” on page 183).

● In the case of UPIC applications, you can modify the recorded sequence of dialog steps after capturing the method. To do this, choose the View/Show Service Graph command to open the modeling area in the Edit method window.

● In the case of terminal applications, you have two possibilities:

– Immediately after capturing the method and, if necessary, editing the code during this step, you can modify the sequence of dialog steps. BizTransactions automati-cally opens the Modeller window for you to do this.

– At the end of the complete capture process, you can modify the recorded sequence of dialog steps in the Edit method window. To do this, choose the View/Show Service Graph command to open the modeling area in the Edit method window.

CAUTION!The modeling reflects the workflows in the host application. During modeling, you should therefore adhere to the real workflows in the host application.

!


Modeling a method Editing the code of a method

6.4.1 Procedure

To model a method graphically, proceed as follows:

After capturing the method

Ê In the edit window, double-click on the method or a lower-level icon corresponding to the method that you want to edit

or

Ê Choose the Edit Method command in the method’s context window.

The Edit method window opens.

Ê Choose the View/Show Service Graph command to open the modeling area. The captured method is displayed in a flowchart in this area of the Edit method window.

Ê Make the desired modifications. For instance, you may wish to remove superfluous service nodes, combine repetitive service nodes, or add new ones. The necessary functions are available in the menus of the Edit method window as well as in the modeling area’s context menu.

Ê If you want to terminate modeling, choose the View/Show Service Graph command again. The modeling area is now hidden. Choose the File/Save command to save your changes.

During method capture

When you choose one of the Terminate commands in the Record method window, BizTransactions opens the Modeller window. The captured method is displayed in graphical form in a flowchart. If you click on a service node, the corresponding format is output in the lower window area.

Ê Make the desired modifications. For instance, you may wish to remove superfluous service nodes or combine repetitive service nodes. The necessary commands are available in the flowchart’s context menu.

Ê To terminate modeling, close the Modeller window with OK.



6.4.2 Inserting a new service node

If you model the sequence of dialog steps after capture, you can add new service nodes to existing methods. There are various ways of doing this.

● You insert a service node with Communication/Insert Service Node and fill it in manually with statements. The new service node is inserted in the modeling area and in the code tree structure. You can connect the service node then in the modeling area to another service node. The flow of methods of automatically modified by BizTransactions Studio.

Please note that new services inserted from the tree structure do not contain any statements. Add the desired statements (see section “Editing statements” on page 187). You can use the code of captured services as a guide. Note that the typical order of statements is different for terminal and openUTM-UPIC appli-cations. There are differences, for example, in the start service and in the handling of partial formats.

● You import a service node with its statements from another method with View/Import Code of Service Node. The new service node is inserted in the modeling area and in the code tree structure. You can connect the service node then in the modeling area to another service node. The flow of methods of automatically modified by BizTransactions Studio.

● You capture additional service nodes with Recording/Record Method and append the intermediate code recorded to the existing intermediate code.

New service nodes are always inserted at the very bottom of the code’s tree display. However, the modeling always determines the dialog sequence at runtime.

i

i



6.4.3 Deleting service nodes and connections

Service nodes and connections can be deleted from the flow chart by marking the desired object and pressing the [Ctrl] [Del] key combination. When a service node is deleted, its incoming and outgoing connections are also deleted and the flow of methods is modified accordingly.

You delete individual connections in the chart with the [Del] key.

6.4.4 Adapting the layout

When modeling methods, BizTransactions offers numerous layout functions. For example, you can

● change the size of service nodes

● align service nodes

● distribute service nodes evenly

● arrange service nodes automatically

All layout functions are described in detail in the online Help system.



6.4.5 Displaying and modifying service nodes

You can display and edit the attributes of a service node.

● In the Edit method window, choose a service node displayed in the chart. In the programming area, you will see a button with the name of the service node. Clicking on this button opens the Service node dialog box in which you can edit the service node’s attributes.

● In the Modeller window, click on a service node and choose the Edit Service Node command in the context menu. The Edit Service Node dialog box is opened.

You can edit the following service node attributes:

● Name: Unique identifier of the service node. You can assign any name you want, but the name must be unique within this method.

● Service: Name of the service assigned to this node

● Service Type: Determines the type of the service (see the next section “Different types of service node”). You can change this property.

● Max. Calls: Specifies how often the service node is allowed to be executed in the method. If the value set here is exceeded, then BizTransactions aborts when the method is executing with an BizTaBoRecursionError exception.

Different types of service node

There are two types of service nodes, each of which is represented by a different icon in the chart:

There is also the start service node that is not marked in the chart. A dialog sequence starts at this service node. The start service node is characterized in that there is no connecting line connected to its left input. Only one start service node is allowed in a chart.

Normal service nodeNormal service node while the method executes.

Recursive service nodeA service node that may be repeated several times when executing a method, e.g. a list of information that can only be output over several screens.



Example: Using the service type “Recursive”

Let us assume that you have a host application which displays a list of addresses on the basis of certain selection criteria. When the method was captured, this list was output over two formats (List1 and List2). After the list has been output, the format SelectFunction appears as the follow-up format.

The fact that two formats were required for outputting the list when the method was captured is mere coincidence. Depending on the selection criteria and the amount of data available, you may actually require more or less formats when the method is executed.

Based on your selection criteria, the list of addresses can be output in 1-n formats (List1 to Listn), i.e. you must inform the method that one of the service nodes for the service List may appear more than once (1-n). To do this, proceed as follows:

Ê In the modeling area, delete all the service nodes from List2 to Listn. In this example, only the service node List2 is deleted.

Ê Reconnect the service nodes (List1 -> SelectFunction).

Ê Select the service node List1 in the modeling area.

Ê Open the Service node dialog box in the programming area.

Ê Select the Recursive attribute for ServiceType and confirm your selection with OK.

This could result in the following display:



6.4.6 Modeling unknown formats (BizTaUnknown)

For each BizTransactions application, you can create a service called BizTaUnknown in the BizTransactions Studio. It has the same attributes as a “normal” service and is designed for situations where a BizTransactions application

● contains formats that do not contain a unique or that contain an unknown identification,

● a number of formats is expected that can all be acknowledged without further processing.

When a method is being modeled, BizTaUnknown can be inserted into an application at any point. You then define how the service node is to react in a specific situation through its attributes.

● You enter a service node with the name BizTAUnknown in the Edit method window (see section “Inserting a new service node” on page 179). You then select the button labelled BizTaUnknown in the programming area.

● In the Modeller window’s context menu, choose the command Insert unknown format handling.

Example

You insert the service node BizTaUnknown at points at which an unknown format may occur.

In this example, the format KDCSIGN was output after the format SelectFunction1 following capture. However, under certain circumstances, an information screen (bulletin) may be output after the format KDCSIGN. As a result, the method was modeled in such a way that the format SelectFunction or an “unknown” format followed by SelectFunction is expected after KDCSIGN.



If in the above example, the information screen (bulletin) can be output no times, once, or multiple times, you should change the BizTAUnknown service node to Recursive.



6.4.7 Modeling a flow without format recognition

Even if a server application communicates without format recognition (UPIC), you can still model the dialog flow in the modeling area. When you define more than one successor for a service node you must define the corresponding successor in the code.

You can use the predefined local variable BizTAsServiceNode to do this. It contains the name of the next service node. BizTAsServiceNode must be set correspondingly in the previous node. Only one of the service nodes that you modeled in the chart as the successor may be specified in BizTAsServiceNode.

Example

In service node A0006 the Selection field determines with which service node the dialog will be resumed (B0002, C0003 or D0004). In this case the corresponding statements in service node A0006 must appear as follows:

SelectCase SelectionFieldCase "B" BizTAsServiceNode="B0002"Case "C" BizTAsServiceNode="C0003"Case "D" BizTAsServiceNode="D0004"CaseElse exitmethod RC='1001' "Unexpected value in the selection field"

The corresponding chart in the modeling area appears as follows:



6.4.8 Saving the chart and closing the modeling session

You save the flow chart using the File/Save command in the Edit method window.

If the Studio detects unsaved changes when closing the Edit method window, you will be asked to confirm whether or not you wish to save your changes.

During the save process, the chart is automatically checked for compliance with the following rules:

● Each chart may only have one start node, i.e. there should only be one service node without anything connected to its input.

● A BizTaUnknown node may not follow another BizTaUnknown node.


Editing the code of a method Editing statements

6.5 Editing statements

When capturing a method, the Studio automatically generates corresponding code state-ments. Instead of statements in a specific programming language, this code is in the form of easy-to-follow meta-code. You do not have to be a programming expert to understand the statements, as their meaning is immediately apparent (e.g. FunctionKey: "DUE").

BizTransactions Studio provides a range of statements for individual adaptations to the automatically generated code. All of these statements are available in graphical form. This is not only convenient, but also excludes the possibility of syntax errors.

Depending on your host application, you may adapt the code at different times:

● In the case of UPIC applications, you can edit the code after method capture. To do this, use the commands in the menus in the Edit method window. For a description, see section “Editing statements after capturing a method” on page 196.

● In the case of terminal applications, you have two possibilities:

– You can edit the code during method capture. To do this, use the buttons and menus in the Record method window. For a description, see section “Editing statements during method capture” on page 234.

– You can edit the code after method capture. To do this, you use the commands in the Edit method window in the same way as for a UPIC application. For a description, see section “Editing statements after capturing a method” on page 196.

6.5.1 Overview

The following table provides you with an overview of the statements that you can insert in the code and edit. For a detailed description of the statements and the way they are processed before and after capture, see the BizTransactions Studio online help system.


Editing statements Editing the code of a method

Statement Description Processing after capture Processing during capture

ArrayInit Initializes an array CommandExtras/Array Functions/Tab ArrayInit

Begin Groups a sequence of state-ments. An End statement is inserted automatically.

Command Manipulate Data/Begin-Block

Case Inserts a Case branch in a SelectCase block. The expres-sion in the Case branch is compared with the value of the SelectCase expression. If they are the same then all the fol-lowing statements are execut-ed up to the next Case branch. Processing continues after EndSelect.See also SelectCase

Command Structured Code/Case-Block

CheckKey Searches for a value in a table.This statement checks wheth-er a value (property, local variable or literal) is present in a table belonging to a format. The result of this check is the table index that contains the searched for value. This is assigned to a local variable (Long). If the searched value is not found in the table, the local variable is assigned the value -1.

Command Manipulate Data/Look For Value in Tabular Data

Concat Concatenates strings Command Manipulate Data/Concat Strings

Code view:Buttons Insert -Concat

Eval Calculates values and assigns the result to a numerical prop-erty, a numerical parameter, a local variable of data type String or a field belonging to the current service.

Command Manipulate Data/Evaluate Expression

Code view:Buttons Insert - Eval

ExitMethod Terminates execution of the method with a return code and message.

Command Structured Code/Exit Method

Code view:Buttons Insert - ExitMethod



FormatAttribute Sets an attribute for a field in the send buffer (e.g. selects the field). For information on the available attributes, see the BizTransactions Studio online help system.

Command Communication/Set Format Attribute

Emulation view:Command in the context menuMark field

FunctionKey Sets the function key that is to be transferred to the host appli-cation with the next Send statement.

Command Communication/Set Function Key

Is inserted implicitly.

Code view:Buttons Insert - FunctionKey

getSize Queries the size of an array CommandExtras/Array Functions/Tab getSize

IfBreak Condition resulting in the inter-ruption of a loop. Two values are compared with each other:If the condition of the IfBreak statement returns True then the loop is interrupted and execution continues with the statements after the loop. If the condition returns False then the statements in the loop continue to be executed.See also While, Repeat-Until

Command Structured Code/Break Loop

If-Then-Else If condition in which two values are compared with each other. If the condition returns True at runtime then the statements in the Then branch are executed. If the condition returns False, then the statements in the Else- branch are executed.

Command Structured Code/If-Then-Else-Block

Code view:Buttons Insert - If




Move Assigns a value Command Manipulate Data/Move/Assignment


Code view:Buttons Insert - Move

Code, Emulation, Gridview: Commands in the context menu– Move format field into

parameter– Move parameter to

format field

Grid view: commands – Edit/Move format field

into parameter– Edit/Move parameter to

format field

Move Arrays Transfers an array to another array

CommandExtras/Array Functions/Tab Move Arrays

OutputList Outputs data in a list.A service’s tabular data is assigned to a variable of data type String. The values are comma-separated.

Command Manipulate Data/Data in Tabular Form

Receive Receives the data of the current service from the host application.

Command Communication/Receive Data

Is inserted implicitly

Rem Inserts a comment. Command Manipulate Data/Comment




Repeat-Until Loop condition in a RepeatUntil loop in which two values are compared with each other.The statements in the Repeat block are executed once. The condition is then checked. If the condition returns True then the statements in the block are executed again. As soon as the condition returns False, execution continues with the statements after the loop.See alsoIfBreak

Command Structured Code/Repeat-Until-Loop

ResetSendBuffer Initializes the send buffer of the current service node

Command Communication/Initialize Send Buffer

SelectCase Checks whether a field or variable contains a specific fixed value.If the value of the SelectCase variable matches the value of a Case branch then the following statements are executed. If the specified value does not match the value of the SelectCase variable in any Case branch then the statements that follow CaseElse are executed.See also Case

Command Structured Code/Select-Case-Block

Send Sends the data of the current service to the host application.

Command Communication/Send Data


setSize Sets the size of an array. CommandExtras/Array Functions/Tab setSize

Statement Creates any statement,see also section “Inserting freely programmable state-ments” on page 216

Command Manipulate Data/Freely Programmable Statement




TAC Defines the transaction code with which the application is to be continued (at start of meth-od or if an openUTM program unit has terminated with PEND FI).

Command Communication/Set TAC

Try-Catch After the Try statement, an attempt is made to execute the following statements. If excep-tions occur then these are processed with the statements in the Catch block. The state-ments in the Finally block are always executed. The method is then continued with the statements after EndTry.The Catch, Finally and EndTry statements are automatically inserted after the Try state-ment. You can only delete them together with the Try statement.

While Loop condition in a While loop in which two values are compared with each other. As long as the condition returns True, the statements in the block are executed. As soon as the condition returns False, execution continues with the statements at the end of the loop.See also IfBreak

Command Structured Code/While Loop

WriteLog Outputs a message to the log file

Command Manipulate Data/Write Logging Information

Code view:Buttons Insert - WriteLog




In addition to the statements listed here, you can edit the code using the commands in the Extras menu after capturing the method. You can

● Replace literals, see page 219

● Generate value assignments, see page 221

● Generate corresponding value assignments, see page 223

● Import freely programmable statements, see page 225

● Call an external function, see page 225

● Write intermediate results, see page 386

6.5.2 Compatibility checks

With the following statements you can compare different data types or map them onto each other.

● If block

● While loop

● Repeat Until loop

● SelectCase block

● Break Loop (IfBreak)

● Assign values (Move)

When a statement is generated, it is checked whether the data types used are all compatible with one another. If they are not, an error message to that effect is issued. The following tables supply an overview of the data types which are compatible with one another and those which are not.



Compatibility of the statements If, While, RepeatUntil, SelectCase, IfBreak

Legend:

Boolean Long Double Date String Variant

Boolean = B B - B V

Long B = + - L V

Double B + = - L V

Date - - - = toDate D

String B L L toDate = S

Variant V V V D S =

Character Meaning

B Boolean variables or literals are– converted to 0 or 1 before a comparison with a number (0=False, 1=True).– converted to the character string “true" or "false“ before a comparison with a

String.

D The data types are compatible. The Variant variable, however, has to be initialized with a Date value, otherwise a runtime error might occur.

L Before the comparison, the variable or the literal of the type String is converted to the relevant numeric data type.If the string is a number, there is no problem. If not, a runtime error might occur.

V The data types are compatible. The Variant variable, however, has to be initialized with a numeric value, otherwise a runtime error might occur.

toDate A comparison is only possible with the toDate function.

S The content of the Variant variable is converted to a string.

= Same data type. However, the Variant variable must be initialized with a value of the same data type as otherwise a runtime error may occur.

+ The data types are compatible. The data type is automatically converted to the larger data type. The functions format or NumbertoField can be used to compare the Long or Double data types with the String data type.

- The data types are not compatible.



Compatibility for the function Move

Legend:

Target of the Move statement

Boolean Long Double Date String Variant

Source of the Move state-ment

Boolean = B B - B =

Long X = + - + =

Double X N = - + =

Date - - - = Format =

String X L L toDate = =

Variant V V V D V =

Character Meaning

B If the receive field is expecting a numeric value, the Boolean True is converted to 1 and False is converted to 0.If the receive field is expecting a String, the Boolean True is converted to the character string "true" and False is converted to "false".

D The data types are compatible. The Variant variable, however, has to be initialized with a Date value, otherwise a runtime error might occur.

L Before the allocation, the variable or the literal of the type String is converted to the relevant numeric data type.If the String is a number, there is no problem. If not, a runtime error might occur.

N Limited conversion. An overflow might cause a runtime error and in the case of decimals, there might be rounding errors.

V The data types are compatible. The Variant variable, however, has to be initialized with a numeric value, otherwise a runtime error might occur.

X Any numeric value not equal to = 0 is converted to the character string "true" and 0 is converted to the character string "false".A String with the value "true" is converted to the Boolean True, other values are converted to False.

toDate A comparison is only possible with the toDate function.

format A comparison is only possible with the format function.

= Same data type

+ The data types are compatible. The data type is automatically converted to the larger data type. The data type is automatically converted to the larger data type. The functions format or NumbertoField can be used to compare the Long or Double data types with the String data type

- The data types are not compatible.



6.5.3 Editing statements after capturing a method

To edit the code, proceed as follows:

Ê Click in the Edit window on the method or on an underlying symbol of the method whose code you want to edit.

Ê Select Edit/Edit Method or double-click on the method or lower-level icon to open the Edit method window. The individual code statements are displayed in a tree structure in this window.

Ê Click in this tree structure on the lines of code you want to change or below which you want to insert a new statement.

Ê If you want to insert a new line of code, select the desired statement from the toolbar or menu bar. The programming area then displays buttons that you can use to edit the parameters of the statement.

Ê If you want to change a line of code, mark the line. The programming area also displays buttons in this case that you can use to edit the parameters of the statement.

Ê Repeat the last three steps until you have finished making all your changes, and then select File/Exit. The Close dialog box opens and you are asked what is to be done to the changed objects.

Ê Choose wether you want to save or discard your changes. The Edit method window closes and your changes are saved persistently or are discarded.

6.5.3.1 Tips on editing the code

Click on a node or a code line to select it for further processing. The programming area then contains buttons for editing. You edit service nodes with the same commands as for state-ments. New statements are inserted after a marked node or statement.



Cut a statement

Ê Choose the Edit/Cut command. The current statement or the current Begin, SelectCase, If, Do, TryCatch or While block is copied to the clipboard and marked yellow in the code tree structure. The statement is deleted when you paste the code at the desired position with Edit/Paste.

Copy a statement

Ê Select the command Edit/Copy to copy the current statement or the current Begin, SelectCase, If, Do, TryCatch or While block to the clipboard

Ê Select Edit/Paste to insert the statement on the clipboard at the desired position. Begin, SelectCase, If, or While blocks cannot be copied or moved “within themselves”.

Move a statement

Ê Right-click and hold down the mouse button to drag the statement you want to move to the desired location.

Ê If you want to copy the statement, press the [Ctrl] key when you are moving the statement with the mouse.

You cannot cut, copy or move the following statements:– CaseElse– Catch– End– Else– End If– EndSelect– EndTry– Finally– Loop– RepeatUntil

You only can delete the entire statement block.

You can only move or copy statements that access fields of a service to another service node if the service node is based on the same service.

i



Insert a statement

Ê Select the code line in the tree structure after which you wish to insert a new line.

Ê Select the corresponding command from the menu bar or toolbar or the Edit/Paste command to insert a statement or a Begin, SelectCase, If, TryCatch, Do or While block from the clipboard after the marked statement.

To insert a statement after an existing If-Then-Else block, you must select its End If state-ment.

If the same service is being used, you can insert

● individual statements and

● statement blocks (Begin, SelectCase, If, or While blocks) in other service nodes

Delete a statement

Ê Select the Edit/Delete Statement command to delete the marked line of code from the intermediate code.

Save all changes

Ê Select the File/Save command.

Undo a series of changes:

Ê Select the Edit/Undo Several Steps command. In the Undo Several Steps dialog box, you can undo all changes you have made since the last save.



6.5.3.2 Selecting variables

When editing most statements, you open dialog boxes in which you can select variable data with the buttons in the programming area.

In the statement the data entered is characterized by a prefix:

" " Literals are placed in quotation marks

Prop Property of a business object

Par Parameters of a method

SendReceiveBuffer.Table000.rec1(0),Field1 Field of a service is completely qualified

All variable data can be found on the left-hand side of the dialog box in tab windows that you can use for the current statement:

Parameters

Shows all parameters of the method in a tree structure:



The parameter you select in the tree structure is shown at the bottom of the dialog box in an output field. You confirm the use of the selected parameter in the programming area with OK.

If you want to create a new parameter, select the Extras/New Method Parameter command in the Edit method window. Enter a name and a description, and then select the desired data type.

Properties

Shows all properties of the business object in a tree structure.

The property you select in the tree structure is shown at the bottom of the dialog box in an output field. You confirm the use of the selected property in the programming area with OK.

If you want to create a new property, select the Extras/New Property command in the Edit method window. Enter a name and a description and select the desired data type.



Fields

Shows the records and fields of the current service in a tree structure.

The field you select in the tree structure is shown at the bottom of the dialog box in an output field. You confirm the use of the selected field in the programming area with OK.



Local variables

Shows all local variables of the method in a tree structure.

The local variable you select in the tree structure is displayed at the bottom of the dialog box in an output field. You transfer the selected local variable into the programming area with OK.

If you want to create a new local variable, select the Extras/New Local Variable command in the Edit method window. Assign the variable a name and a description.

A local variable only exists within a method and can be of one of the following data types:

– String– Long– Double – Variant



Each business object method receives the following predefined local variables by default:

Within the methods, BizTAsStatus supplies you with the following values:

in terminal applications:

in openUTM UPIC applications:

Variable Data type Remark

BizTaReceive-Length

Long Number of characters read after a successful receive

BizTAsFormat String Current format name (UPIC) or service name (EM3270, EM9750)

BizTAsStatus String Communication status, can only be reasonably evaluated for UPICStart Initial status, no connection opened as yet Reset There are no open services, the conversation is

clearedSend The next call should send data; follow-up status is

StartReceive The next call should read data with ReceiveNoData The host application is not sending any more data

BizTAsService String Current service

BizTAsServiceN-ode

String UPIC only: Successor node to the current service node in the modeling area

BizTaCursor String Current cursor position

"" (i.e. empty) before the first Receive call

"Receive" after the Send calls

"Send" after the Receive calls

"" (i.e. empty) before the first Send in a method

"Send" as long as the openUTM process is open

"Receive" after the openUTM process is terminated



Literals

In some statements, literals can be specified as values.

The literal you enter is shown at the bottom of the dialog box in an output field. You transfer the literal to the programming area with OK. In this display, the predefined functions that are permitted in the current context are listed on the right-hand side of the dialog box (see section “Predefined Functions” on page 207).

For a description of the individual types of literals and their uses, see the BizTransactions Studio online help system.



Statements consisting of multiple variables or fields

You can combine multiple variables in the following statements

● Evaluate Expression (Eval)

● Freely Programmable Statement

● Exit Method with Return Code (ExitMethod)

● Write Logging Information (WriteLog)

● Concat Strings (Concat)

You can combine multiple fields in the following statements:

● Output Data in List (OutputList)

● Look For Value In Tabular Data (CheckKey)

To do this you will see an extended work area below in the dialog box. You can edit the working area with the buttons on the right.



The buttons here have the following meanings

Button Meaning

Begin Inserts the variable or literal at the beginning of the list.

End Inserts the variable or literal at the end of the list.

Before Inserts the variable or literal before the element you selected in the work area.

After Inserts the variable or literal after the element you selected in the work area.

Replace Replace the variable or literal you selected in the work area.

Deletes the variable or literal you selected in the work area.

Delete all Deletes the entire work area.

Moves the selected variable or literal in the work area up one element.

Moves the selected variable or literal in the work area down one element.



6.5.3.3 Predefined Functions

The following functions are predefined for the purpose of editing code. Only those functions that are allowed in the current context appear in the dialog box.

Asc(string)Returns the ASCII code of the first character of a string variable as a long value. You may not use this function on an empty string.

Example: ASC("A")

Result: 65

Chr(number)Returns the ASCII code for a character. The value of the ASCII code must be between 0 and 255.

Example: Chr(0)

Result: X'00'

FieldLength(Field)

Returns the length of the passed field.

Example: lLen = FieldLength(myBuffer.myField(i))

FieldPosition(Field)Returns the position of the passed field.

Example: lPos = FieldPosition(myBuffer.myField(i))

FieldToNumber("string", ",")Formats a string in a number and determines the decimal separator regardless of the current country setting of the operating system, see also sections “FieldToNumber and NumberToField” on page 215.

Example: FieldtoNumber("1234,56",".")

Result: 1234.56

Format(number, format expression)Formats a number and returns a string. The decimal separator depends on the country setting of the operating system, see also section “Formatting numbers” on page 210.



Format(date, format expression)Formats a date and returns a string, see also section “Formatting a date” on page 212.

InStr(Pos, string, "Find")Returns the position of the first occurrence of a string (Find) within another string as a long value. The start position (Pos) can be entered directly or selected as a local variable. The position of the first character is 1. The string searched for must be placed in quotes.

Example: InStr(1,"Peter","te")

Result: 3

LCase(string)Converts a string to lowercase letters.

Left(string, number)Returns a certain number of characters starting at the first (left-most) character of a string. The number can be entered directly or selected as a local variable.

Example: Left("Peter",2)

Result: Pe

Len(string)Returns the number of characters in a string as a long value.

LTrim(string)Removes all spaces at the beginning of a string.

Mid(string, pos, len)Returns a specific number of characters in a string. The start position (pos) and length (len) can be entered directly or selected as a local variable. The position of the first character is 1.

Example: Mid("Peter",2,3)

Result: ete

NoneNo function is executed.



NumberToField(number, format expression)Formats a number in a string and determines the decimal separator regardless of the current country setting of the operating system, see also section “FieldToNumber and NumberToField” on page 215.

Example: NumberToField("1234.56","#00000.000", ",")

Result: 01234,560

Replace(string, find, replace)Replaces a search term (find) in a string by a new string (replace).

Example: Replace("Peter", "et","XY")

Result: PXYer

Right(string, number)Returns a certain number of characters starting from the right (the end) of a string. The number can be entered directly or selected as a local variable.

Example: Right("Peter",2)

Result: er

RTrim(string)Removes all spaces at the end of a string.

toDate(date, format expression)Converts a string to a date, see also section “toDate” on page 214.

Trim(string)Removes space characters at the beginning and end of a string.

UCase(string)Converts a string to uppercase letters.



Formatting numbers

The Format function formats a number using the format specified in the FormatExpression and returns a formatted string. The decimal character (period) and thousands character (comma) are converted to the country-specific character. In Germany, for instance, a comma is used as a decimal character and a period as a thousands separator. In other countries the characters are used the other way around.

StringString returned by the function

numberThe number to be formatted

FormatExpressionSpecifies a pattern for the format. The pattern can be a literal or stored in a local variable and is passed to

.NET and Visual Basic the Format function

Java the applyPattern method of the DecimalFormat class. The number is then formatted with the DecimalFormat.format method.

string = format(number, FormatExpression)



In FormatExpression you can specify the following characters:

Character Description for .NET and Visual Basic Description for Java

0 Placeholder for digitsA leading or trailing zero will be output here, if necessary.

Stands for a mandatory digit in a processing pattern, and in a display pattern, it specifies that leading zeros are displayed.

# Placeholder for digitsNo leading or trailing zero are output.

Stands for an optional digit in a processing pattern, and in a display pattern, it specifies that leading zeros are not displayed.

. Placeholder for decimal character.This character is not necessarily identical to the displayed separator defined through your country code.

, Placeholder for thousands separator Placeholder for thousands separator. Indicates the grouping to be used.

The character is not necessarily identical with the displayed thousands character defined through your country code.

+ This character (plus) is displayed precisely in the way it was entered in the format character sequence.

This character (plus) is displayed precisely in the way it was entered in the format character sequence.

- This character (minus) is displayed precisely in the way it was entered in the format character sequence.

This character (minus) is displayed precisely in the way it was entered in the format character sequence.



Formatting a date

The Format function formats a date or a local variable with the data type Variant using the format specified in the FormatExpression and returns a formatted string.

stringString returned by the function

dateDate value in a parameter, property or field of data type Date or in a local variable of data type Variant to be formatted.

FormatExpressionSpecifies a pattern for the format. The pattern can be a literal or stored in a local variable and is passed to

.NET and Visual Basic the Format function

Java the applyPattern method of the DecimalFormat class. The date is then formatted with the DecimalFormat.format method.

The individual parts of a date can appear in any order and they can be separated by an optional combination of separator characters or by none at all.

You can use the following characters for the date and time in the FormatExpression:

string = format(date, FormatExpression)

y yy or yyyy2-digit or 4-digit year

M M or MM1-digit or 2-digit month

d d or dd1-digit or 2-digit day

H H or HH1-digit or 2-digit hour (24-hour system)

h h or hh1-digit or 2-digit hour (12-hour system)

m m or mm1-digit or 2-digit minutes

s s or ss1-digit or 2-digit seconds



The following seven characters can be used as separators:

/ + - ( ) . blank

Typical example: yyyy/MM/dd HH:mm:ss.

Note the following:

– The year has to be in two-digit or four-digit format, all other parts of the date must be in one-digit or two-digit format.

– In Visual Basic, the pattern character “/“ has the effect if “/“ or “.“, depending on the country settings.

– “Exotic“ pattern combinations may lead to unexpected results in Visual Basic.

You will find further information on the format function in the documentation on Visual Basic and in the Java reference.

i



toDate

This function extracts from an input string DateString containing parts of a date and optionally the time elements specified in the FormatExpression and returns a Date. Errors are displayed in an output window.

DateDate returned by the function

DateStringLiteral, parameter, property field or local variable with the time and date. The time is optional.

FormatExpressionLiteral or local variable with the formatting for the time and date.

The following data is optional:

Example

Date = toDate(DateString, FormatExpression)

yy 2-digit yearif yy > 30, then 19yy, otherwise 20yy

yyyy 4-digit year

M 1-digit month

MM 2-digit month

d 1-digit day

dd 2-digit day

h 1-digit hour

hh 2-digit hour

m 1-digit minute

mm 2-digit minute

s 1-digit second

ss 2-digit second

- insignificant character

DateString xxx2000x09x27xx17x33x55x

FormatExpression: ---yyyy-MM-dd--hh-mm-ss



FieldToNumber and NumberToField

The settings for the decimal and thousands separators (period and comma) may be different on your PC and on the host on which your host application is running. You define which character is to be used as a decimal separator in the current statement using the functions FieldToNumber and NumberToField.

In order to avoid runtime errors, you should always use the function FieldToNumber or NumberToField when using a Move statement to transfer the contents of a field into a numeric variable or when supplying a field with the contents of a numeric variable.

You also specify the format in which the number is stored in the field in the NumberToField function. To do so, you can use the same formatting elements as supplied by the Format function (see “Formatting numbers” on page 210).

In contrast to the function Format, the effect of NumberToField is independent of the country code set on your PC at the time the business object runs. Which characters (period or comma) are used as placeholders is determined solely by the decimal character specified.



6.5.3.4 Inserting freely programmable statements

If you want to create statements that cannot be implemented using the menu commands available in the Edit method window then you should use the commandManipulate Data/Freely Programmable Statement. You can create as many statements as you want with this command.

During the planning stage, you should consider whether you can implement the required functionality better by means of freely programmable statements or by calling an external function (see also section “Call Extern Function” on page 225).

When you create freely programmable statements, you see a button and a list in which you can select the programming language.

The button opens the Statement dialog box in which you can combine variables and literals to form statements as you require, see also section “Statements consisting of multiple variables or fields” on page 205. The required operators are specified as literals.

LanguageList of the programming languages in which the business object can be generated.

When generating the classes, you specify the language in which the business object is to be generated. Only those freely programmable statements are considered for which you set the same language. You can support several languages by generating a freely programmable statement for each language you want to support.

Example

Increment the PropNum property by 1

Ê Select the Properties tab in the Statement dialog box.

Ê Then select the PropNum property and click on the Begin button.


Ê Enter the equals sign in the String input field and click on the After button.

Ê Select the Properties tab.

Ê Then select the PropNum property and click on the After button.


i

i



Ê Enter +1 in the String input field and click on the After button.

Ê Close the dialog box with OK.

This example serves only as an illustration. It is better if you use the Eval statement for this task.

Freely programmable statements for Java

When constructing a freely programmable statement for Java and using a local variable of the type Variant, the local variable must also be supplied with the desired BizTaVariant method.

A variable of the type Variant is mapped on a variable of the type BizTaVariant in Java. To do this, BizTransactions provides you with the following methods in the BizTaVariant class:

Method Meaning

locvar.getVar(variable) Returns the contents of the local variable locvar, variable is used to determine the data type of the return value. The following data types are possible: boolean, byte, short, int, long, float, double, String, BizTaVariant and GregorianCalendar.

locvar.setVar(variable) Specifies the contents of the local variable locvar, variable is used to determine the data type of the set value. The following data types are possible: boolean, byte, short, int, long, float, double, String, BizTaVariant and GregorianCalendar.

locvar.equals(variable) Compares the local variable locvar (of type BizTaVariant) with a variable of data type boolean, Double, String or BizTaVariant.

locvar.compareTo(BizTaVariant variable, String Op)

Compares the local variable locvar (of type BizTaVariant) with a variable of data type BizTaVariant. In Op you specify the compare operator. Possible values for the compare operator are:== != < > <= >=



Examples

You want to read the contents of the local variable locvar (type BizTaVariant) into an integer i. This is what your Java code must look like:

i = locvar.getVar(i);

Similarly, you can supply the contents of the local variable locvar with an integer i:

locvar.setVar(i);

You want to compare the content of the local variable locvar (type BizTaVariant) with an integer i.

boolean b = locvar.equals(i);

You want to compare the two local variables locvar1 and locvar2 ( both of type BizTaVariant) These variables have previously been supplied with a numeric value and you want to find out whether the content of locvar1 is smaller than or equal to the content of locvar2:

locvar1.compareTo (locvar2, "<=");



6.5.3.5 Functions in the Extras menu

With the functions in the Extras menu in the Edit method window, you can insert several statements in a dialog step, among other things.

You can use the following functions:

● Replace Literals, see next section

● Create Move Statements, see page 221

● Corresponding Move Statements, see page 223

● Import Freely Programmable Statements, see page 225

● Call Extern Functions, see page 225

● Array Functions, see page 227

● Write intermediate resultThis function is only of interest in connection with loosely coupled asynchronous web service calls. For a detailed description, see section “Writing intermediate results” on page 386.

Replace Literals

When recording a method, you run through a dialog with the host application. When this is done you enter specific input that BizTransactions Studio uses as Move statements in the generated code.

However, no fixed, static input values are usually desired for the business object method. Variable, dynamic values are usually desired instead. With the function Replace Literals you can comfortably map static input values originating from the recording to properties, parameters or local variables and generalize the code in this manner.

You can create some properties and parameters first to do this.



New property/paramOpens the New Method Parameter dialog box in which you can define the variable type.

You see all Move statements in which a literal (Source) was assigned in the table in the dialog box.

TargetVariable that is assigned a value. When you click on Target, a button appears. The button opens the Move to dialog box in which you can change the target.

SourceAssigned value. When you click on Source, a button appears. The button opens the Move from dialog box in which you can change the source.

OK Replaces all modified Move statements.



Create Move Statements

In this dialog box you can create several assignments (Move statements) to the right of the current cursor position in the tree structure. To do this you see the variable types on the various tabs on the left in the dialog box. You can use these variable types for the Move statements as the Source and as the Target. In the table below you see all assignments (Move statements) you have currently created in the dialog box.

TargetVariable that is assigned a value. You select the variable from the tab window and drag it onto the input field or you create it with New property/param (target).

SourceValue assigned to a variable that you have – selected from the tab windows and dragged into the input field or – created with New property/param (source).

ApplyTransfers the new assignment in the table with its source and target.



In the table in the dialog box you see all Move statements you have created in the dialog box.



OKCreates all Move statements from the table in the code tree structure at the current cursor position in a Begin block.



Corresponding Move Statements

In this dialog box you can create several Move statements (value assignments) for class properties and fields with the same name. The statements are inserted to the right of the current cursor position in the tree structure. When this is done, BizTransactions Studio automatically creates the move statements for the class properties of the same name as soon as you have selected the classes or records for the Source and Target and have clicked on Apply.

To do this you see the variable types on the various tabs on the left in the dialog box. You can use these variable types for the Move statements as the Source and as the Target. In the table below you see all Move statements created for the class properties of the same name in this dialog box.

TargetRecord or class whose class properties or (record) fields are assigned a value. You select the element from the tab windows and drag it to the input field.

IndexIf the Target is an array, then you can specify the array element directly via the Index.



SourceAssigned value in a record or class that you select from the tab windows and drag on to the input field.

IndexIf the Source is an array, then you can specify the array element directly via the Index

ApplyInserts a new Move statement in the table for every matching pair of class property names or (record) fields in the Source and Target.

You see all Move statements created in the table in the dialog box.



OKCreates all Move statements from the table in the code tree structure at the current cursor position in a Begin block.



Import Freely Programmable Statements

Up to 50 statements can be generated directly in the Edit area or existing statements can imported from a file using this command. The statements are stored in a Begin Block in the interim code, a separate statement being included in the Begin Block for each line.

During the planning stage, you should consider whether you can implement the required functionality better by means of freely programmable statements or by calling an external function (see also section “Call Extern Function” below).

Two methods are available for editing the statements:

● creating statements directly

Enter the statements line by line directly in the Edit area.

● importing statements from a file

In the File input field, enter the name of the file or click on the Find button to select the desired file in a dialog box. The name of the file is displayed. Click on the Open button to import the contents of the file into the Edit area where it can be edited.

Next select the Language in which the statements were written.

If you only want to import a part of the statements displayed in the Edit area into the interim code, mark the relevant statements. If none of the statements are marked, all statements displayed will be imported into the interim code.

A maximum of 50 lines is imported into the interim code.

A line may not be longer than 240 characters.

Binary characters may not be used. The characters have to be removed from a line before the import.

Every line you import must contain a complete statement. No statements that extend past one line are permitted.

Call Extern Function

In this dialog box you can specify and edit the function to be called for the Call statements. To do this you will see a list on the left side of the dialog box containing all functions defined in the current host application. You can only inorporate functions in the code defined for the current host application.

If there is no code for this function in the selected programming language at the time of generation, then the generation is aborted with an error.

i

i

i



ApplyOpens the Return code dialog box in which you can select a variable for the return value of the function.

In the table below you see all parameters that belong to the function. In the Variable column you can assign every parameter a value that matches its data type.The columns of the table have the following meanings:

ParamName of the function parameter

VariableVariable with a value for the function parameter. When you click on a variable, you see a button. The button opens the dialog box in which you can select a variable as a parameter.

Data typeData type of the parameter

DescriptionShort description of the parameter



Array functions

In the Array Functions dialog box you can edit all arrays that are accessible in the current method. To do this you will see the various elements that are arrays on the left side of the dialog box in tab windows. You can perform the following operations on the arrays with the tab on the right in the dialog box

● Initialize

● Query the size

● Set the size

● Move one array to another array

It depends on the type of variable which array function you can use, see section “Functions for array elements” on page 232.

Left tab windows

ParamOnly method parameters of type Array are displayed.

PropertiesOnly properties of the business object of type Array are displayed.

FieldsOnly fields in records of the current service node are displayed if the value of their Number attribute is greater than 1.



Initialize array

Select the array which is to be initialized with a default value in the ArrayInit tab. The size of the array is not changed. Drag the required parameters, properties or fields into the list from the tabs on the left of the Array Functions dialog box. You defined the default value when the array was defined (Content attribute for fields or properties).

If you have not defined a default value for the array, then numerical arrays are initialized to "0" and string arrays to an empty string "". If the array to be initialized is contained in another array (nested arrays), this redimensions these arrays according to the specifications in Index.

If an output parameter of a method has not yet been allocated, an array is generated with one element.

IndexNested arrays only: Opens the Select Index dialog box where you can specify more precisely which elements of a nested array are to be initialized

Get the size of an array

Select the array for which the number of allocated elements is to be determined at runtime from the getSize tab. Drag the required parameter, property or field into the list getSize from the tabs on the left of the Array Functions dialog box.

The size determined (number of array elements) is then returned in a numeric variable. If the array has not yet been initialized, an exception is triggered. You can catch this exception in a Try-Catch block and respond appropriately.

Example

In this example, the size of the array DocumentsP is stored in the variable DocumentsJ in a TryCatch block. If the array is not already initialized, then this is done with setSize. Finally, the array LongArray2 is copied into the array LongArray1.

| Try| | DocumentsJ = getSize(Par:DocumentsP())| | Eval DocumentsJ = DocumentsJ - 1| Catch| | Move: DocumentsJ = 1| | setSize(Par:DocumentsP()) = DocumentsJ| Finally| | Move Arrays: Par:LongArray1()<i1>=Par:LongArray2()<i2>| EndTry



Local variableList of local variables. The determined size of the array (the number of elements) is then subsequently stored in the selected local variable.

getSize()Array whose size is to be determined.

IndexNested arrays only. Opens the Select index dialog box in which you can specify more precisely the element of a nested array for which you wish to determine the size.



Set the size of an array

Select the array for which the number of elements is to be reset at runtime in the setSize tab. Drag the required parameter, property or field into the list setSize from the tabs on the left of the Array Functions dialog box. The size to which they are to be set (number of array elements) is in a numeric variable.

If the array is enlarged, the additional elements are preset with default values. If its size is reduced, the values are lost in the excess elements. If the array whose size is to be reset is itself contained in another array (nested arrays), then these arrays are resized according to the specifications in index.

You must not use this array function for input parameters of a method. If an output parameter of a method has not yet been allocated an SetSize is not used, an array is generated with one element.

setSize()Array whose size is to be set.

Local variableList of local variables. You must previously have entered the assigned local variable together with the required size. You enter the number of array elements here.

IndexNested arrays only. Opens the Select index dialog box in which you can specify more precisely the element of a nested array for which you wish to determine the size.



Moving an array

Select the array which is to be transferred to another array in the MoveArrays tab. Drag the required parameter, property or field into the lists Target and Source from the tabs on the left of the Array Functions dialog box. Both arrays must have the same data type.

TargetArray into which another array is to be transferred. If it is an output parameter of a method which has not yet been allocated, an array is generated with an element.

If the array which is to be moved into another array is itself contained in another array (nested arrays), this redimensions these arrays according to the specifications in Index.

Local variableList of variables that contains the index value of an element. This is the start position at which the array elements are written to the target array.

The local variable is used as a counter in the Move loop and its value therefore changes.

IndexNested arrays only. Opens the Select index dialog box in which you can specify more precisely the element of a nested array into which another array is to be moved.

SourceArray that is to be transferred.

i



Local variableList of variables that contains the index value of the element as of which the array elements are read from the source array.

The local variable is used as a counter in the Move loop and its value therefore changes.

IndexNested arrays only. Opens the Select index dialog box in which you can specify more precisely the element of a nested array which is to be moved to another array.

Functions for array elements

The array functions which you can use depend on the type of variable. In the following table + stands for available, - for not available:

Variable type initArray getSize setSize MoveArray

Automatic redimensioning

Parameter check

Property Both

+ + + + + -

Property get + + + + + -

Property let + + + + + -

Parameter InOut

+ + + + + + 1

1 Arrays as input parameters (In, InOut) are checked at the beginning of a method with the function checkArray ReadOnly:=True. All array elements are subsequently determined and checked with the function checkSyntax.

Parameter Out

+ + + + + -

Parameter In

+ 2

2 Initializing or changing the size has no effect on input parameters. This case is not trapped by the BizTransactions Studio.

+ + 2 + - + 1

Field Array - + - + - -

i



Automatic redimensioning

When you write properties or method parameters of the type Out and InOut, BizTransactions automatically redimensions arrays. You can specify the maximum permitted number of array elements when defining a property or a method parameter.

If you continuously describe an array of this type in a loop, you should dimension the output array appropriately at the beginning of the loop with setSize, since in this case the automatic redimensioning does not perform well.

BizTransactions executes the following actions when redimensioning:

Variable Actions executed when redimensioning

Property as array The array is extended to the specified size.

Property as array of a class The array is dimensioned to the specified size. The array is then dimensioned to the specified size in each nested class.

Parameter as array The array is extended to the specified size.

Parameter as array of a class An inline code block is generated first. This creates an instance for the class array in a For loop. The array is then dimensioned to the specified size in each nested class.



6.5.4 Editing statements during method capture

Proceed as follows if you want to edit code while capturing a method:

Ê Click the Start recording button in the Record method window to start capture.

The Record method window opens with the first screen of the host application. If the screen is already known, you will see the name of the screen in the title bar and can move on to the next step. Otherwise, the Record method window opens in Grid view in which you can define the recognition criteria for the screen.

Ê If necessary, specify the recognition criteria in Grid view using the functions in the Screen recognition window (see section “Format recognition” on page 167).

Ê Switch to the appropriate view in the Record method window depending on the state-ment that you want to insert (see section “Views in the Record method window” below).

Ê Select the statement via the buttons or menus.

Ê Additional dialog boxes or a programming area in which you can edit the statement’s parameter will be displayed depending on your selection.

Ê Repeat the above steps until you have completed the required adaptations.

Ê Send the screen to the host application with File/Send or File/Send with function key.

6.5.4.1 Views in the Record method window

The Record method window provides you with various views in which you can edit meth-ods.

When you have started capture (Start recording button), you will see four tabs in the work area. You can use these tabs to display the views. In the case of known screens, the Emulation view is displayed first. Otherwise, you see the Grid view in which you can define the recognition criteria for the screen.



Emulation view

The Emulation view is displayed by default if a format is recognized when you start capture.

The current format is displayed as it would be if it were displayed in the emulation. Successive output fields (protected fields) are depicted in two alternating colors. Input fields (unprotected fields) possess a black border. You can define the colors used to display fields in the Options dialog box (Options/Recorder options command).

Figure 18: Emulation view in the Record method window

Title barMenu barTabs

Input field

Outputfields



In Emulation view you can

● enter data in input fields (see also section “Entering data and setting data entry param-eters” on page 249).

● transfer field contents to a parameter using the commandMove format field into parameter in the context menu (see also section “Outputting a format’s data in a parameter” on page 250).

● transfer parameter contents to a field using the commandMove parameter to format field in the context menu.

● select a field and display it in Grid view using the commandShow in grid in the context menu.

● select a field using the command Mark field in the context menu. The field is then flagged as selected by means of a field attribute and sent to the host application as such.

● send the format with: – File/Send or File/Send with function key.– the keys F2 to F16 or the Return key.



Grid view

Grid view is displayed by default if the format is not recognized when capture starts.

The current format is displayed in a table. Each character in the format is mapped to a cell in the table. Input and output fields are depicted in the same color as in the Emulation view. The fields that represent the recognition criteria are displayed in color. You can define these colors in the Options dialog box (Options/Recorder options).

Figure 19: Grid view in the Record method window


Input field

Outputfields

Recognition criterion



In Grid view you can

● select areas with the left mouse button and then perform actions on the selected data.

● define or extend the recognition criteria for the format (see section “Format recognition” on page 167) using the ... screen recognition commands in the Screen recognition menu or in the context menu.

● define or edit lists using the list commands in the List menu or in the context menu (see also section“Defining lists” on page 245).



● send the format with: – File/Send or File/Send with function key.– the keys F2 to F16 or the Return key.



Code view

In Code view, you see the method in a tree structure. The tree structure contains

● the method’s parameters

● the properties

● the local variables

● the current format

● the current code

Figure 20: Code view in the Record method window


Treestructure

Buttons



If you have selected a node in the tree structure,



● select a field and display it in Grid view using the commandShow in grid in the context menu.

● modify the name and description of the node with the Edit command in the context menu. You can modify the content of input fields here. It is not possible to modify recog-nition criteria.

If you have selected a method parameter, a property or a local variable in the tree structure, the Insert button on the right-hand side of the window is active.

You use the Insert button to define a new method parameter, a property or a local variable.

If you have selected the node belonging to a statement in the tree structure, then the Insert and Delete buttons are activated.

● When you click on Insert, you also activate the buttons for the insertion of further state-ments.

A programmming area is also displayed for each statement. You can edit the statement’s parameters here. For a detailed description of the statements and the associated programming areas, see the online help system.

● Click the Delete button if you want to delete the selected statement.



All Services

The All Services view outputs a list of the services in the current host application. The services are output in ascending order sorted on screen number. Click on a column header in the table to sort on the corresponding column.

The services are displayed in different colors depending on the associated recognition criteria:

The following data is displayed in the columns:

Service Name of the service

State Status of the service

– Unused: the service is not used in the current method.– Used: the service is used in the current method and has not been changed.– Modified: the service is used in the current method and has been changed during

the current capture operation.– New: the service was recognized for the first time during the current capture

operation.

Nb Screen number. The screen number specifies the sequence in which the recog-nition criteria are searched and compared with the contents of the current format. It is assigned when the recognition criteria are entered.

Pos Position of the first screen recognition data entry starting at 0.

Screen recognition data Screen recognition data for the service. If multiple entries exist, these are filled with the wildcard character “?”.

Background color Step color Meaning

White Black Normal service

Blue Black Conflicts in recognition criteria

White red The service has no recognition criteria



Figure 21: All Services view in the Record method window

For each line in the list, you can

● display the service and its recognition criteria in Grid format by means of the Show format and screen recognition data command in the context menu.

● display the service and its recognition criteria in a dialog box by means of the Modify screen recognition data command in the context menu. You can edit the recognition criteria in this dialog box.

● modify the service’s screen number by means of the Change screen number command in the context menu.

● output a report for the service by means of the Show service report command in the context menu. The report displays all the service data and the business objects that use this service. This action is not possible for new services.

● assign the BizTaUnknown service by means of the Assign BizTaUnknown command in the context menu.


Services



● create a new service by means of the Define a new service command in the context menu.

CAUTION!If you use the Assign BizTaUnknown or Define a new service commands then the following changes to any previously selected service are lost:– Move statements– Lists– Recognition criteria

Newly defined classes, parameters and properties are retained.

You should therefore perform these two actions immediately after reading a format.

!



6.5.4.2 Implicitly inserted statements

During method capture, a number of statements are automatically inserted in the method. This is only possible if you have selected the Record option.

Ê To do this, choose Options/Recorder options in the Record method window.

Ê Check that the option Record is set to True in the dialog box.

The following methods are inserted implicitly:

FunctionKey This is inserted if you choose the File/Send or File/Send with function key command in the Record method window or if you send the screen with the keys F2 to F16 or the Return key. In the case of recursive formats, only one FunctionKey statement is generated before the Send statement.

Move This is inserted if you enter text in an input field in Emulation or Grid view. If you have already explicitly inserted a Move statement that addresses this field, no additional Move statement is generated.

Receive This is inserted after a format has been received. In the case of recursive formats (see page 172), only one Receive statement is generated at the beginning of the format.

Send This is inserted if you choose the File/Send or File/Send with function key command in the Record method window or if you send the screen with the keys F2 to F16 or the Return key. In the case of recursive formats, only one Send statement is generated.



6.5.4.3 Defining lists

To define a list, proceed as follows:

1. Switch to Grid view.

2. Select an area that covers the entire list.

3. Choose the Define a list command in the List menu or context menu.

4. Complete the Name of the service list and Description fields in the Define a new list dialog box.

5. Under Parameters using classes, choose the parameter that you want to assign or define a new parameter.

6. If necessary, enter the name, description and usage of the new parameter in the Define new property (class) dialog box and close the dialog box with OK.

7. If necessary, choose the corresponding property under Properties using classes or define a new property.

8. If necessary, enter the name, description and usage of the new property in the Define new property (class) dialog box and close the dialog box with OK.

9. The value of Number of rows per list entry is set to 1 by default.If an entry in a list spans several lines, enter the corresponding number of lines here.

10. Close the Define a new list dialog box with OK.

11. In the first list element of each column, select an area from the first to the last character of the column.In the case of a multi-row column, this area covers the corresponding number of columns.

12. Choose the Add a column command in the List menu or context menu.

13. Complete the Name of the field and Description fields in the Define a list column in class class dialog box.

14. Under Define new variable in class, choose the variable that you want to assign or define a new variable.

15. Close the dialog box with OK.

16. Repeat steps 11 to 15 for each column.

17. Choose the End of list command in the List menu or in the context menu.

For a detailed description of list creation and the associated dialog boxes, see the BizTransactions Studio online help function.



Multi-line lists

A list entry may extend over several lines or even an entire format and a list may extend over several “instances” of a format.

Example

The customer-data format contains all a customer’s details. It is called several times when a method is executed and is therefore “recursive”.

● When you capture the method, you create a list in which all the relevant lines are selected the first time the customer-data format occurs.

● You define the customer-list class under Name of the service list in the Define a new list dialog box

● If, for example, the customer data comprises 17 lines, you enter 17 for Number of rows per list entry.

● You now select the Name field and choose the Add a column command in the List menu or the context menu.

● You now do the same for Street, ZIP and City.

● To exit, choose End of list.

Whenever the customer-data format is processed in the future, a list entry with Name, Street, ZIP and City will be written to the customer-list output list.

Name Street

ZIP City

customer-data

Trailer



BizTransactions objects

During list generation, the following BizTransactions objects are generated with the default names:

Example for the generated intermediate code

In this example, the content of the list is assigned to a parameter.

BizTransactions object1

1 List: name of listColumnN: name of column

Description

Service buffer: T_List Buffer that describes the list

Service record: List Record in this buffer

Service field: ColumnN A field is entered in the record for each column in the table

Parameter or propertyListP

Parameter or property that uses the user-defined class List

User-defined classList

Class describing the output class

Property of user-defined classColumnN

Corresponds to the field of the same name in the list buffer

Local variable ListI Index for the current format

Local variable ListJ Index in the output list

Intermediate code Description

Begin: Two local variables are defined automaticallyListI: Index for the current formatListJ: Index in the output list

|Move: ListI =0 The index for the current format is initialized to 0. Processing starts with the first line in the list.

|Try Coverage for the case, that the list is not initialized yet.

||ListJ = getSize(Par:ListClassP()) Retrieves the size of the output list and saves it in ListJ.

||Eval ListJ = ListJ - 1 If the output list is allocated, 1 is subtracted from the number of entries.This indicates the first index to be written in the output list.

|Catch If an error occurs: The output list is not allocated.



||Move: ListJ = 0 The list index is set to 0.

|Finally

|EndTry

|While ListI < 13 The list in this format consists of 13 list lines. These are now processed in a While loop.

|IfBreak T_List.List(ListI).SColumn1 = "EndOfList"

A break condition is checked here. If thecondition is true, then the loop is exited. This statement is optional.

||Move: Par:ListClassP(ListJ). Column1 = T_List.List(ListI). SColumn1

A Move is now performed for each column. The list column in the format (indexed by the index in the current format) is moved to the output list (indexed by the index in the output list). In this example, the name of the property in the user-defined class is Column1. The field also has the name Column1.

||Move: Par:ListClassP(ListJ). Column2 = T_List.List(ListI). Column2

This is the second column. With the exception of the variable names, the code corresponds to that to the first column.

||Eval ListI = ListI + 1 The index for the list in the format is incre-mented by 1. The next line in the format is processed.

||Eval ListJ = ListJ + 1 The index for the output list is incremented by 1.

|Loop

End

Intermediate code Description



6.5.4.4 Tips on editing code

The figure below indicates the default procedure after a format has been read:

Figure 22: Reading a format when capturing a method

You can change between the views in the Record method window as you wish.

Entering data and setting data entry parameters

Ê Choose Emulation view.

Ê Enter the required content in the input field.

Ê If you want to parameterize the input, choose the Move parameter to format field command in the context menu in the Record method window.

Format is read

Format known?

Conflict?

Grid viewDefine

recognition criteria

Emulation viewEnter data

Send format

Assign serviceNew service

Service from list

Yes

No

No

Yes



Outputting a format’s data in a parameter

Behavior in this case depends on how the output field is defined.

● The output field corresponds to the output field in Emulation view.

Ê In Emulation view, choose the Move parameter to format field command in the context menu.

● The output field is internally structured. It therefore consists of individual items of infor-mation that you want to move to specific targets. Example: a field in Emulation view consists of a ZIP code, a city and a street.

Ê Select Grid view.

Ê Select the relevant cells, for example the ZIP code

Ê Choose the Move format field into parameter command in the Edit menu or the context menu.

● In the case of table data.

Ê Choose Grid view and select the relevant cells.

Ê Use the Define a list command to define a corresponding list (see section “Defining lists” on page 245).

● The output field was defined in the service using BizTransactions Studio, has a complex structure and does not correspond to an output field in Emulation view.

Ê Switch to Code view.

Ê Click on the required field.

Ê Choose the Move format field into parameter command in the context menu.

Show in grid command

The Show in grid command exists in Emulation and Code view. It automatically switches the display to Grid view. The input/output field in Emulation view or the selected node in Code view is displayed in a color that you can define (Options/Recorder options command). This simplifies navigation in complex formats. In the case of arrays, only the first element is displayed.


Editing the code of a method Example

6.6 Example

The section below provides an example of how to structure workflows in a business object. The example indicates the optimum way of distributing the sequences that were generated when you recorded the dialogs.

6.6.1 Host application

The figure below illustrates a fictitious host application that communicates via the 9750 emulation protocol.

Figure 23: Host application that communicates via 9750. The boxes in the figure correspond to formats

KDCSIGN Bulletin KDCOFF

Query List

QuitSelectFunction

NewOrder

SelectFunction Quit


Example Editing the code of a method

Formats in the example host application

The table below describes the formats present in the fictitious host application:

Service node Description

KDCSIGN Data such as user ID and password are usually entered in this sign-in format.

Bulletin This format tells the user about new events. It may occur never or one or more times. The service BizTaUnknown is usually used for this service node.

SelectFunction In this format, the user is able to select a specific function. The following functions are present in the example application:Query Entry of selection criteria. The results are output in the format

List.NewOrder Entry of a new order in the format NewOrder.Quit Terminate the application: Formats Quit -> KDCOFF.

Query The user can enter selection criteria here. The results are output in the format List.

List The results of the search are displayed as a table here. This format may be output a number of times depending on the number of hits. A recursive service is generally the best choice for this format.If you enter END in this format then processing branches to SelectFunction for selection of a function.

NewOrder After data entry, the host application returns to the format SelectFunction.

Quit If QUIT is entered in function selection (SelectFunction) then the host applica-tion branches to this format.

KDCOFF The dialog with the application is terminated.



6.6.2 Creating stateless methods

Read_List method

The first step is to create a Read_List method in a business object. The method’s Connection attribute is set to Method (see section “Declaring business objects and their interfaces” on page 123).

The following sequence is worked through when the dialogs are recorded (see section “Recording dialogs for terminal applications” on page 162):

Figure 24: Read_List method after capture

● If the Bulletin format is output during capture, choose the Assign BizTaUnknown command in the context menu in the host application’s All Services view (see section “Views in the Record method window” on page 234).

The placeholder BizTaUnknown, which can stand for any format, is now inserted instead of the Bulletin format until the format SelectFunction is recognized.

● If the Bulletin format is not output in the current capture operation, you can, directly after capture and after editing any code as appropriate, choose the KDCSIGN format in the Modeller window and then select the command Insert unknown format handling in the context menu to insert a BizTaUnknown node.

KDCSIGNBulletin

SelectFunction Query

List KDCOFFSelectFunction Quit



Following the Query format, the hits are output in the List format. You can define a list here.

● If the format is output again, respond Yes to the query Create recursive format.

● If the format is only output once because the number of hits is currently too small, you should subsequently select the List format in the Modeller window, select the Edit Service Node command in the context menu and set the service type to Recursive.

You have now created a Read_List method which signs on to the host application as state-less and returns a hitlist in the form of a class array on the basis of the selection data (which you defined in the form of method parameters).

Figure 25: The Read_List method with BizTaUnknown

InsertOrder method

The second step is to create an InsertOrder method in the business object. This method has a simpler structure than Read_List. InsertOrder has the following sequence:

Figure 26: InsertOrder method

KDCSIGN BizTaUnknown SelectFunction Query

List KDCOFFSelectFunction Quit

KDCSIGN BizTaUnknown SelectFunction

NewOrder KDCOFFQuitSelectFunction



Code in the client

The code in the client could be structured as follows:

TryMyBO = New BusinessObject // Instantiate business objectMyBO.InsertOrder(InPar1, InPar2) // Call the InsertOrder methodMyBO.Read_List(InParX, ArrayOfList) // Call the Read_List method

CatchWriteMessage("Ooops") // Evaluate & output exception

FinallyMyBO.Dispose // in .NET OrBizTaConnection cObj; // in JAVAcObj = objBO.getCommunicationServer();cObj.stopCommunication();

End Try

6.6.3 Creating stateful methods

Unlike stateless methods, the term “stateful” here refers to methods which expect the business object to have a specific state when they are called or which leave the business object in a specific state. When using such methods, it is important to pay attention to the call sequence in the client.

To use multiple stateful methods instead of a stateless method, proceed as follows:

The first step is to set the business object’s Connection attribute to Business Object (see section “Declaring business objects and their interfaces” on page 123).

If you create the business object with BizTransactions Wizard (see section “Selecting an existing business object or creating a new one” on page 47) then the methods BizTa_SignOn, BizTA_SignOff and BizTA_CleanUp are inserted automatically. However, at this stage they do not contain any code.

Subdivision of host application functions

The table displays a possible subdivision of the host application functions to the following methods:



Method Description

BizTa_SignOn This method combines all the formats required to sign on to the host appli-cation. At the end of the method, the host application is in the formatSelectFunction.

Read_List The method starts in the format SelectFunction. When the Query function is entered, the Query and List formats are worked through. At the end of the method, the host application is in the format SelectFunction.

InsertOrder The method starts in the format SelectFunction. When the NewOrder function is entered, the NewOrder format is called. At the end of the method, the host application is in the formatSelectFunction.

BizTa_SignOff The user signs off from the host application with this method. The method starts in the format SelectFunction. When the QUIT function is entered, the Quit and KDCOFF formats are worked through. At the end of the method, the connection to the host application is terminated.

BizTaCleanUp This method is intended to solve the following problem:If the host application executes an unexpected error dialog, for example because of an invalid input parameter, then the current method is terminated with an error (Unexpected format / sequence error) if the format was not included in the capture process. The host application is now in an undefined state. If you call another method, for example InsertOrder, this will also terminate with an error because the current format is not SelectFunction.

Here, you can create a method that contains a BizTaUnknown service as its first format. In this service node, you can analyze the content of the current format and navigate the host application to a defined state. In this example, this would be the format SelectFunction.

ExampleReceive // Read current formatSelect Case MyFormatID // Unique format identifier

Case "NewOrder" Move myCmd, "EXIT" // Return to SelectFunction FunctionKey "DUE"

Case Else FunctionKey "K3" // return to SelectFunction

End SelectSend // Send data



Recording dialogs

You have the following possibilities when recording dialogs:

● You can capture the Read_List and InsertOrder methods and duplicate Read_List to BizTa_SignOn and BizTa_SignOff.

In BizTransactions Studio, you then modify the methods in the Edit method window by deleting the superfluous service node in each of them.

● During capture, you can control whether or not code is generated for a service node (Record method window, command Options/Recorder options, option Recorder).

– For example, to capture the Read_List method, you should first set the Record option to False.

– Before the SelectFunction format, set the Record option to True. This records the sequenceSelectFunction -> Query -> List -> List -> ... SelectFunction.

– After the SelectFunction format, set the Record option to False again.

– You then remove any superfluous code sections in the last service nodeSelectFunction.

You must always code the BizTa_CleanUp method yourself.



After capture and any necessary editing, the sequence should be as follows:

Figure 27: Sequence with functions subdivided

* The SelectFunction service nodes at the end of the methods BizTa_SignOn, Read_List, InsertOrder and BizTa_CleanUp must not contain any code!

These service nodes are merely placeholders. The actual code for this format is present in the SelectFunction service nodes at the start of the Read_List, InsertOrder and BizTa_SignOff methods.

BizTaUnknown

KDCOFF

SelectFunction

KDCSIGNBizTa_SignOn

Read_List

BizTa_SignOff

InserOrder

BizTa_CleanUp

SelectFunction

SelectFunction Query List SelectFunction

SelectFunction NewOrder SelectFunction

SelectFunction Quit

BizTaUnknown

*

*

*

*



Code in the client

In your client, you can first call the method BizTa_SignOn. The host application is in a defined state: SelectFunction.

You can now call the Read_List and InsertOrder methods in any order and as often as you want.

If a call fails, call the BizTa_CleanUp method. This method returns the host application to the SelectFunction state.

Finally, you call the method BizTa_SignOff.


7 Installing and configuring BizTransactions

The BizTransactions installation files can be downloaded from the web.

You will find detailed information on the hardware and software requirements in the release notes supplied with the product.

7.1 Installation

The delivery comprises the following products:

● BizTransactions development environment

● JWSDP (Java Web Services Developer Pack) from Sun Microsystems for supporting web services, with Apache Tomcat

After download, the product is available as a Windows installer package (msi file) named BizTransactions70.msi.

Notes

● You can install BizTransactions V7.0 next to previous versions on a computer. If you want to operate a previous version parallel to the new version, then you must install BizTransactions V7.0 in a different directory.

● If you want to replace the previous version, then deinstall the old version first. Do not delete any product directories since proper deinstallation of the software, including the removal of all entries from the registry, cannot be guaranteed in that case!

Registry entries

BizTransactions uses HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\BizTransactions\3.1\CurrentVersion as the basic node for all registry entries.

i


Installation Installing and configuring BizTransactions

Installing host adapters and the runtime system

When you install BizTransactions, the development system components are also installed on your computer.

The host adapters for the connection of host applications are supplied with the selectable units WebTransactions for OSD, WebTransactions for openUTM and WebTransactions for MVS (see the WebTransactions manuals “Connection to OSD Applications”, “Connection to openUTM Applications via UPIC” and “Connection to MVS Applications”).

The BizTransactions runtime system is also supplied with each of these product compo-nents. If you simply install one or more host adapters without the development system then you can use the corresponding system as the runtime machine for BizTransactions (see section “Configuring the runtime system” on page 273).


Installing and configuring BizTransactions Installation

7.1.1 Installation via the user interface

You can start installation in a variety of ways:

● Via the Settings/Control Panel command in the Start menu.

● Via Windows Explorer.Double click the BizTransactions70.msi file or right-click on this file and then select the Install command in the context menu.

You require Windows administrator rights to perform installation.

Installing JWSDP

When you start BizTransactions70.msi, you see a series of dialog boxes in which you can make the required settings.

The first step is to specify whether or not JWSDP is to be installed in the Java Web Services Developer Pack 1.3 dialog box.

● JWSDP is to be both installed and used:In this case, select the option Install Java WSDP 1.3 and specify the installation directory of Java 2 or the installation directory for JWSDP.

● JWSDP is to be neither installed not used:Do not select the option Install Java WSDP 1.3.

● JWSDP is not to be installed and, instead, an existing JWSDP is to be used:Do not select the option Install Java WSDP 1.3 and specify the installation directory of the already installed JWSDP.

Selecting the servlet engine

In the next step, you specify the servlet engine for JWSDP in the Servlet Engine dialog box.

● If you do not ant to use a servlet engine, i.e. you do not want to use any web services:the parameters in this dialog box are irrelevant.

● If you want to use Tomcat as a component of JWSDP:Select TOMCAT as the servlet engine and enter the following values:– the administrator ID– the password corresponding to the administrator ID– the root URL– the installation directory for JWSDP is taken over from the preceding dialog box



● If you want to use Tomcat installed independently of BizTransactions:Select TOMCAT as the servlet engine and enter the following values:– the administrator ID– the password corresponding to the administrator ID– the Tomcat installation directory– the root URL

● If you want to use an Oracle OC4J server installed independently of BizTransactions:Select OC4J as the servlet engine and enter the following values:– the administrator ID– the password corresponding to the administrator ID– the OC4J installation directory– the server and associated port

When you have set the options, installation starts by asking you to specify the installation directory for the BizTransactions development environment.


Installing and configuring BizTransactions Installation

7.1.2 Silent installation

To perform silent installation, you use the Windows Installer Msiexec.exe. You can find a detailed description of this command in the Windows online help system. You need Windows administrator rights if you want to perform installation with Msiexec.exe.

You use the Msiexec.exe command with the following syntax:

Msiexec.exe /i "package" /q[INSTALLDIR="install-dir"][JWSDPCHECK="jwsdpcheck"][INSTALLDIR1="jwsdp-dir"][INSTALLDIR2="java-dir"][SERVLETENGINE="servlet-engine"][SLXHOME="servlet-engine-home"][SLXUSER="servlet-engine-user"][SLXPASSWD="servlet-engine-password"][SLXSERVER="servlet-engine-url"][SLXSERVEROC4J="servlet-engine-host"][SLXPORT="servlet-engine-port"]

The parameters have the following meanings:

package Path of the package that is to be installed (e.g. C:\tmp\BizTransactions70.msi).

install-dir The BizTransactions installation directoryDefault value: C:\Program Files\BizTransactions70

jwsdpcheck Specifies whether JWSDP is to be installed.Possible values: Yes | NoDefault value: Yes

If you enter Yes here, Java 2 SDK V1.4.1 or higher must already be installed on your computer.

You only need to specify the following parameters if you have set JWSDPCHECK="Yes".

jwsdp-dir The JWSDP installation directory.Default value: C:\Program Files\jwsdp-1.3

java-dir The Java 2 SDK installation directory.

i



servlet-engine Servlet engine for JWSDP.Possible values: Tomcat | OC4JDefault value: Tomcat

servlet-engine-home Home directory of the specified servlet engine.Default value: C:\Program Files\jwsdp-1.3

servlet-engine-user User ID of the specified servlet engine.Default value: admin

servlet-engine-password Password corresponding to the user ID of the specified servlet engine.Default value: admin

servlet-engine-url URL, for Tomcat only:Default value: http://localhost:8080

servlet-engine-host Host, for OC4J only:Default value: localhost

servlet-engine-port Port, for OC4J only:Default value: 8888

Example

Msiexec.exe /I "C:\tmp\BizTransactionsAS40070.msi" /q INSTALLDIR="C:\Program Files\BizTransactions70"JWSDPCHECK="No"INSTALLDIR2="C:\Program Files\java"


Installing and configuring BizTransactions Configuring the development environment

7.2 Configuring the development environment

BizTransactions is the interface between host applications and the various clients. BizTransactions either uses the UPIC (Universal Programming Interface for Communica-tions) client/server communication protocol or the 9750 terminal protocol (for BS2000/OSD) or 3270 terminal protocol (for MVS) to communicate with the host application:

● UPIC is a complex communication protocol which offers far more than pure data exchange. A connection via UPIC allows BizTransactions to use the openUTM user concept and openUTM’s automatic restart functions, for instance. Since information on format names and openUTM function keys can also be exchanged through the UPIC protocol (as of openUTM V4.0), no modifications need to be made to the openUTM program units for integration with the Windows world.

● The 9750 protocol is the communication protocol with which any host application in BS2000/OSD can transfer input/output from and to the terminal. Contrary to the UPIC protocol, however, only data buffers containing the format data are transferred with the 9750 protocol (no format names).

● The 3270 protocol is the communication protocol with which any host application in MVS can transfer input/output from and to the terminal. Here too, as with the 9750 protocol, only data buffers containing the format data are transferred.

You do not need to do anything else to configure the communication data. You only need to intervene if

● there is no name service (such as DNS) configured. In this case you need to create entries for the partner computer in the Hosts file by hand (see the section “Modifying the Hosts file” on page 268)

● you work with an openUTM application (see section “Configuring the openUTM host application” on page 269)


Configuring the development environment Installing and configuring BizTransactions

7.2.1 Checking the environment

BizTransactions Studio helps you check your configuration. When you select the Administration/Check Configuration command, the Studio asynchronously checks if the status of the dll, ocx and exe files on your computer meets the BizTransactions requirements. The extra data output is used for diagnostic purposes when an error occurs.

BizTransactions Studio writes the results of this check to the BizTaConfig.htm file in the directory for temporary files you set using the Options/Edit options/Directories command.

Furthermore, BizTransactions Studio writes an entry to the user-specific message log. You can view the user-specific messages with the Administration/Show User Messages command.

7.2.2 Modifying the Hosts file

You only need to modify the Hosts file if you are not using DNS or if the communi-cation partner (host) is not declared to DNS.

The Hosts file contains all computers with which your PC can communicate along with their Internet addresses, their administration names and frequently also with a comment in the following format:

InternetAddress AdministrationName #Comment

If the Hosts file does not contain the Internet address of the computers you wish to commu-nicate with, then add them.

Example

139.34.64.123 BS2HOSTX #Host for UTM application XYZ

i



7.2.3 Configuring the openUTM host application

Client computers and client applications must be declared at the host computer on which the openUTM application runs. This is achieved by means of KDCDEF control statements on openUTM generation.

7.2.3.1 Adapting openUTM generation

BCAMAPPL statement

The BCAMAPPL statement defines the local name of the openUTM host application.

utmappl Local name of the openUTM host application. This name is the name that BizTransactions Studio expects in the Partner attribute of a UPIC application.

Separate access points using PTERM/LTERM statements

The local name of the BizTransactions applications are made known during the KDCDEF generation using the following KDCDEF control statements.

You define an access point for a host adapter by means of a PTERM/LTERM statement pair. You must therefore specify a separate PTERM/LTERM pair for each parallel connection.

● PTERM statement

upic_client Name of the client.

lterm_name Name of the LTERM partner (see LTERM statement).

utmappl Local name of the openUTM host application. This name is the name that BizTransactions Studio expects in the Partner attribute of a UPIC application.

client_processor Symbolic name of the client computer. The symbolic name is mapped to the Internet address (e.g. via the Domain Name Service, DNS). The PRONAM operand is always obligatory in the case of BS2000/OSD.

Using the PTYPE operand, the openUTM host application can tell if it is a UPIC client or a terminal (T9750, T9755, T9763) that communicates via the 9750 protocol.

BCAMAPPL utmappl, T-PROT=ISO

PTERM upic_client, PTYPE=UPIC-R, LTERM=lterm_name, BCAMAPPL=utmappl, PRONAM=client_processor, ...



Example

PTERM statement for UPIC client

PTERM upic_client, PTYPE=UPIC-R, LTERM=lterm_name, BCAMAPPL=utmappl,PRONAM=client_processor...

PTERM statement for terminal

PTERM em9750_client, PTYPE=T9750, LTERM=lterm_name, PRONAM=client_processor...

● LTERM statement

lterm_name Name of an LTERM partner (=logical openUTM application access point). You can define any lterm_name. openUTM needs this symbolic name for internal administration purposes.

[operands] However, you can specify properties for this access point by using other optional operands in the LTERM statement. You can, for example, set specific access rights.

Example

BCAMAPPL UTMAPPL1, T-PROT=ISOPTERM CLIENT1, PTYPE=UPIC-R, LTERM=lterm_name1,

BCAMAPPL=UTMAPPL1, PRONAM=HOST002, ...LTERM lterm_name1 [operands]PTERM CLIENT2, PTYPE=UPIC-R, LTERM=lterm_name2,

BCAMAPPL=UTMAPPL1, PRONAM=HOST002, ...LTERM lterm_name2 [operands]PTERM upic_client, PTYPE=UPIC-R, LTERM=lterm_name, BCAMAPPL=utmapp1,

PRONAM=client_processor, ...LTERM lterm_name, [operands]

LTERM lterm_name, [operands]



Access point pool using the TPOOL statement

Instead of using multiple PTERM and LTERM statements, you can use a single TPOOL statement to define a limited set of access points. In this case, there is no fixed name correspondence between the entries made at KDCDEF generation time and the clients.

The operand LTERM=prefix defines a prefix from which openUTM internally generates LTERM names for the individual access points in the pool in order to differentiate between the instances (BizTaConnection) which make parallel access attempts. The internally generated LTERM name is a maximum of eight characters in length and consists of the specified prefix followed by a serial number (e.g. UPIC0001, UPIC0002,....). You specify the CONNECT-MODE=MULTI operand if you want to permit multiple connections.

Using the PTYPE operand, the openUTM host application can tell if it is a UPIC client or a terminal (T9750, T9755, T9763) that communicates via the 9750 protocol. If the terminal type is unknown, then you can specify *ANY as well.

Example

TPOOL statement for UPIC clients

TPOOL BCAMAPPL=UTMAPPL1, LTERM=CLNT, NUMBER=1000, CONNECT-MODE=MULTI PTYPE=UPIC-R,PRONAM=*ANY

– The BCAMAPPL operand is optional for UNIX and Windows systems. It is obligatory, however, for BS2000/OSD. The specified name must be defined in a BCAMAPPL statement.

– LTERM and NUMBER generate legal LTERM names in the form CLNT0001,CLNT0002, ...

– CONNECT-MODE=MULTI permits multiple connections

– PTYPE=UPIC-R: the physical partner is a UPIC client (in UNIX systems you can also specify UPIC-L here)

– PRONAM=*ANY: any computer to which the partner name has been declared (UTMAPPL1) can communicate with this application via UPIC.

TPOOL statement for terminals

TPOOL LTERM=CLNT1, NUMBER=1001, CONNECT-MODE=MULTI PTYPE=T9750,PRONAM=*ANY

TPOOL BCAMAPPL=utmappl, PTYPE=UPIC-R, LTERM=prefix, CONNECT-MODE=MULTI NUMBER=1000, PRONAM=*ANY



7.2.3.2 Declaring the client computer

The client and host computers must be declared to one another. There are two ways of doing this:

● Both computers are configured for the DNS (Domain Name Service). In this case, no further entries are necessary.

● Otherwise, the client computer on which BizTransactions is running must be entered at the host computer together with its Internet address:

In the case of a BS2000/OSD host, the symbolic name of the client computer must be entered either statically in the BCAM-RDF (resource definition file) or dynamically via BCIN.

Example for BCIN

/BCIN HOST002, INI=ALL, ACTIVE=ALL, IPA=(123,4,5,6), PROT=(TCP,IP)

The comma-separated Internet address of the client computer is specified by the IPA parameter.


Installing and configuring BizTransactions Configuring the runtime system

7.3 Configuring the runtime system

If you only install one or more host adapters without BizTransactions on a computer, you can use the machine in question as the runtime system for BizTransactions (see the WebTransactions manuals “Connection to OSD Applications”, “Connection to openUTM Applications via UPIC” and “Connection to MVS Applications”).

When you have installed the runtime system, you need to do the following depending on the operating system and the programming language of the business object:

Ê Transfer the business object to the runtime host. BizTransactions does not have any further requirements, you can store the business object wherever you want.

Windows host

Java Extend the environment variable Classpath – by the jar archive of the BizTransactions runtime system:

Common Files\FujitsuSiemensComputers\BizTransactions70\bin\bizta.jar

– and by the jar archive of the business object that you previously transferred to the runtime host (see above): Path\BusinessObject.jar

.NET No further action required.

ActiveX Register the business object with the following command

ActiveX DLL: regsvr32 /si bo.dllActiveX- EXE: with a double-click

Solaris host

Ê Extend the environment variable LD_LIBRARY_PATH by adding the directory/opt/BizTrans/7.0/lib.

Ê Extend the environment variable Classpath – by the jar archive of the BizTransactions runtime system:

/opt/BizTrans/7.0/lib/bizta.jar) – and by the jar archive of the business object that you previously transferred to the

runtime host (see above): Path\BusinessObject.jar


Performance notes Installing and configuring BizTransactions

7.4 Performance notes

MultioTimeout - timer for communication using terminal protocols

Each host adapter for terminal applications contains the MultioTimeout property which specifies the waiting time for message segments in seconds. This is the time the system waits after each Receive() for possible further message segments which might complete the screen contents.

BizTransactions maintains the wait time set for 9750 terminal applications only if there are really still message segments in the queue. This allows long wait times to be set for 9750 connections without any problem. The only time the host will wait is when it is actually necessary.

In the case of emulation connections, the agreed timeout value is only adhered to if the completeness of the screen data cannot be determined on the basis of other criteria.

The default setting for the property MultioTimeout is two seconds, but when the service classes are initialized, the business objects generated with BizTransactions always set the value to

● 20 seconds for 9750 emulation and

● 2 seconds for 3270 emulation.

The value can also be set to 0, i.e. there is no waiting time after a Receive call and the response from the application has to be transferred in one message.

However, for some applications the value 0 or 1 may be too short. Select a higher value for the MultioTimeout property in the BizTransactions Studio for the Receive statement in such cases. However, to avoid adverse effects on performance, you should only increase the waiting time for the screen formats that truly need a higher value when connecting via 3270.

The wait time required, however, not only depends on the host application but also on the throughput of the transport network used and therefore cannot always be measured exactly.

i


8 Client interface of business objectsBizTransactions is software with which you can integrate host applications in the Windows or Java environment. You do not need to make any changes to the host applications.

You create host applications and business objects with BizTransactions Studio and develop methods for the various dialog flows. The catalog is the starting point for integrating host applications via business objects. You generate your own business object classes from your host application’s business objects that are stored in the catalog as object descriptions using the Generate function in BizTransactions Studio.

Figure 28: Generating business object classes

These business object classes are present in the following forms depending on the programming language:

● Java classesYou can integrate the Java classes into any Java development environment.

● .NET and ActiveX componentsYou can integrate these components into the Microsoft Office world and access the server applications from there using macros that you develop yourself, and you can also integrate them into .NET/ActiveX-capable development environments and develop complex applications there that communicate with the host application.

BizTransactionsCatalog

ServiceClasses

Bu

sin

ess

Ob

ject

Cla

ss

Studio


Basic principles Client interface of business objects

A business object class is generated for each business object in a host application in the form of a Visual Basic.NET, Visual Basic or Java class module. Additionally, a Service class is generated for each service that is referenced. BizTransactions uses Visual Basic .NET, Visual Basic 6.0 or the Java compiler to compile .NET or ActiveX components or Java programs from the generated classes.

BizTransactions enables you to develop multi-tier applications with the .NET and ActiveX components and JavaBeans it provides. The various startable components are located on different computers.

This chapter describes the interfaces of the .NET and ActiveX components and Java classes of BizTransactions that you need to develop your own clients for the business objects. In addition, it describes the interfaces of the BizTaConnection component which the business object classes use during communication with BizTaConnection.

The general description in section “Basic principles” applies equally to .NET and ActiveX components (Visual Basic) and Java classes.

8.1 Basic principles

This section provides you with a brief description of the client interface concept. For more detailed information on business object classes, methods and properties, see the following sections:

● “Java” on page 285

● “.NET” on page 310

● “ActiveX” on page 333

8.1.1 Business object class

A business object class represents a kind of “snapshot” of the object description in the catalog. The entire data contained in the business object is also contained in the class. If you modify the business object in the catalog and in the host application after you have generated the business object class, then these modifications will not be contained in the class. In order for communication to function, you will have to regenerate the class.

The business object classes and service classes contain a series of additional properties and methods used internally by BizTransactions. These interfaces will only be of interest to you if the standard BizTransactions solution does not fully meet your requirements. They are described here in order to allow you greater flexibility whenever specific needs arise.


Client interface of business objects Basic principles

The illustration below provides an idea of what a generated business object class looks like:

Figure 29: Generation of business object classes

8.1.1.1 Structure

The generated business object classes have the following structure which is defined in the templates:

● Private instance variable: local variable and the properties defined in the business object , e.g. communication data (TAC, user, host, ..)

● Constructor: initializes the instance variables on the basis of the catalog data

● Destructor: releases the business object

● Access functions for properties (e.g. communication data such as TAC, user, host)

● Access to the service data through the relevant service class, symbolic access to data in the send/receive buffer

● Conversion and check functions for each business object.

● Methods: the methods defined in the business object as public methods.

Generated code with properties and methods

Properties Methods

Service Classes



Templates

The layout of the business object classes is controlled by templates. You will find the templates in the BizTransactions installation directory

● in the case of Java, in the subdirectory Templates\Java

● in the case of .NET, in the subdirectory Templates\Net

● in the case of Visual Basic, in the subdirectory Templates\VisualBasic

There you will find the file Templates.txt that contains the templates for the generation of the business objects.

The beginning of a template is indicated in Templates.txt by <<<+Templatename+>>>, and the end of a template by <<<-Templatename->>>. Lines that start with two colons are considered to be comments and are ignored.

Variables that are to be replaced by current values from the catalog during generation have the format &variable& and a corresponding name or the name &ObjectType.Attribute&, where ObjectType stands for the object to be used for the replacement and Attribute for an attribute of this object.

You can modify these templates at any time to implement project-specific exten-sions (e.g. syntax checks). i



8.1.1.2 Methods

You create the methods during the development phase in the BizTransactions Studio. Each method contains the following local variables

Variable Data type Remark

BizTaReceive-Length

Long Number of characters read after a successful receive

BizTAsFormat String Current format name (UPIC) or service name (EM3270, EM9750)

BizTAsService String Communication status, can only be reasonably evaluated for UPICStart Initial status, no connection opened as yet Reset There are no open services, the conversation is

clearedSend The next call should send data; follow-up status is

StartReceive The next call should read data with ReceiveNoData The host application is not sending any more data

BizTAsServiceNode String Current service node

BizTAsStatus String UPIC only: Successor node to the current service node in the modeling area

BizTaCursor String Current cursor position



8.1.2 Service classes

A separate service class is generated for each service used in a business object’s method.

For a description of the service classes, see

● Java: page 300

● .NET: page 324

● ActiveX: page 338

8.1.3 Class module

For every class you have created in BizTransactions Studio, a class module with the same name is generated.

Every class module contains

● a constructor without any parameters that initializes the properties of the class,

● access methods for the class properties and

● the checkArray method that extends the array when an attempt is made to write to an element whose index is greater than the number of elements actually present.

Java The class module is named class.java and is added to the business object class package. Furthermore, a class module named classArrayHolder.java is generated for the output parameters. This class module has the same structure as the predefined Holder classes (see also section “Passing parameters” on page 290).

.NET All the classes are located in the file BiztaClasses.vb.

ActiveX The class module is named class.cls and is added to the generated ActiveX component.




During execution, a host adapter forms the actual interface between the business objects and the host applications. You communicate with the clients (Office products or client programs) via .NET, ActiveX or Java and with the host applications using the protocol expected by the host application (UPIC, 9750 or 3270).

The BizTaConnection class for communicating with your host application is supplied with BizTransactions. BizTaConnection uses the following protocols:

● UPIC

● 9750

● 3270

If your host application communicates using a different protocol, then you can have your own host adapter created and integrated into BizTransactions. The BizTransactions devel-opers will be happy to help you accomplish this.

Connecting to business objects

A method of a business object or the business object proper initializes a communication request by creating a new adapter object and associating it with a business object. This connection initializes the communication process. The adapter object takes control of communication and establishes the connection to the host application. These lines of code are created automatically when a business object is generated.

When a business object is generated, you can also control whether a host adapter is to be instantiated for the entire business object or a separate host adapter is to be instantiated for each individual method, thus scaling your program extremely finely. The adapter object is included in the project as a DLL or JavaBean and runs in the same address area as the other objects of the project. You can choose the following (in each case in the Connection attribute)

Method The host adapter is declared separately in each method and is instantiated at the start of the method. The host adapter is released again at the end of the method.

Business Object The host adapter is created in the business object’s constructor, is instantiated, and is then released again on the destruction of the business object (destructor) or on Dispose. The methods BizTa_SignOn, BizTA_SignOff and BizTA_CleanUp are, inserted automatically. However, at this point they do not contain any code.



External The host adapter is declared and instantiated outside of the business object. After the business object has been instantiated and before the method executes, you must assign the host adapter using the method SetCommunicationServer.

The following illustrations indicate the different ways of assigning the methods of a business object to adapter objects. For a detailed example of how to structure workflows in a business object, see section “Example” on page 251.

One adapter object for each method

At the bottom of the illustration you see a business object with several methods. Each method signs on to the host application itself, carries out the relevant service and then signs off again.

To obtain this response, you should select the Method value in BizTransactions Studio for the Connection attribute of a business object. As in this illustration. In this case, an adapter object will then be generated within each method, instantiated and released again at the end of the method.

You should use this setting whenever you generate a web service for this business object since web service methods are usually stateless.

M3

Business objectswith severalmethods

Adapter objects

M1 M2



One adapter object for each business object

At the bottom of this illustration you see a business object with several methods. The first method (BizTa_SignOn) signs on to the host application, the second method (Worker) carries out the actual function an optional number of times, and finally, the third method (BizTa_SignOff) signs off from the host application.

To obtain this response, you should select the Business Object value in BizTransactions Studio for the Connection attribute of a business object. In this case, the adapter object is generated, as shown in the illustration, in the business object’s constructor, is instantiated and is only released when the business object is destroyed.

Worker

Adapter object

Business objectwith several methods

Sign On Sign Off

BizTa_SignOn BizTa_SignOff



One adapter object for several business objects

At the bottom of the illustration you see several business objects. Each method has a separate function: the method (M SignOn) of the first business object signs on to the host application, the methods of the second business object perform the actual function an optional number of times, and finally, the method (M SignOff) of the third business object signs off from the host application. Signing on to and off from the host application take place outside of the business object which carries out the actual function.

To obtain this response, you should select the External value in BizTransactions Studio for the Connection attribute of a business object. The adapter object will be instantiated outside the business objects. When the first business object has been instantiated you must assign the adapter object using the SetCommunicationServer method before the SignOn method is started. When the method has been completed the business object can be destroyed. The same applies to the second business object.

The third business object (SignOff) closes down the connection to the host application. You have to assign the adapter object using the SetCommunicationServer method after instantiating the business object, before the SignOff method is started. When the connection is closed down this business object can also be destroyed, but the adapter object remains intact and can be used for other jobs. It has to be destructed explicitly.

M1M2

Adapter object

M3

Sign On Sign Off

M SignOn M SignOff

Severalbusiness objects


Client interface of business objects Java

8.2 Java


At generation time, a package with the path name company.host-application.business-object-name and containing the business object class and the corresponding service classes is generated for each business object. The business object class is based on the higher-level class BizTaBusinessObject that defines the properties and methods common to all business object classes. The service classes are also based on the higher-level class BizTaService.

8.2.1.1 Properties

A private variable with the prefix “m_” is generated for each business object property. As regards the communication data, the business object also inherits further properties of the higher-level class BizTaBusinessObject as well as additional properties for handling events and diagnosing errors.

The values of the properties are read by BizTransactions Studio from the catalog or are supplied by BizTransactions Studio with default values at generation time. Read and write functions (Get / Let for Visual Basic and get / set for Java) are generated for the properties of the business objects in accordance with the access type set.

Access methods for Java properties

Access methods for all business object classes:

Read and/or write method Description

public java.lang.String getErrorMessage()

Error message from the last method call.

public java.lang.String getGenVersion()

Returns a version string with information on date, time, catalog, name of host application, protocol (openUTM, EM9750,...)

public java.lang.String getPartner()

public void setPartner(String partner)

Returns or sets the name of the host application. The name can be up to 8 characters long.For UPIC applications it corresponds to the APPLINAME specified for KDCDEF or the BCAMAPPL name. For 3270 applications it is not relevant.

public long getReceiveTimer()

public void setReceiveTimer(long receiveTimer)

Returns or sets the receive timer value in secondsDefault: 120 seconds

public int getReturnCode() Return value of the last method call


Java Client interface of business objects

Access methods for business object classes that communicate via the UPIC protocol:

public void setLogFilename(String filename)

public java.lang.String getLogFilename()

Returns or specifies the log file to be used by writeLog . filename is the name of the log file. The process ID (pid) and the thread ID (tid) are appended to the filename, resulting in a path of the form path-pid-tid.TXTname.If you specify the value BizTaBusines-sObject.LOG_EVENT for filename, then the log infor-mation is written to the file you have specified as the central log file in the Administration function.

public static String getErrorText (int BizTaRc)

Returns a string with a corresponding message using a return code of type int for the values defined in BizTaBusinessObject.


public java.lang.String getHost()

public void setHost(String host)

Returns or sets the name of the computer on which the host application runs. The name can be up to 100 characters long.

public java.lang.String getLocalName()

public void setLocalName(String localName)

Returns or sets the local application name.Default = " "

public java.lang.String getPass()

public void setPass(String pass)

Returns or sets the sign-on password.

public long getPortNumber()

public void setPortNumber(long PortNumber)

Returns or sets the port number for the connection to the partner application, range of values: 0 - 32,767Default: 102

public java.lang.String getUser()

public void setUser(String user)

Returns or sets the application name.




Access methods for business object classes that communicate via 9750 emulation:

Access methods for business object classes that communicate via 3270 emulation:


public java.lang.String getHost()

public void setHost(String host)

Returns or sets the name of the computer on which the host application runs. The name can be up to 100 characters long.

public java.lang.String getLocalName()


Returns or sets the local application name.Default = " "

public int getTerminalType() Returns the terminal type: BizTATerm9750 or BizTaTerm9763.


public java.lang.String getLUName()

public void setLUName(String localName)

Returns or sets the LU name.Default = " "



8.2.1.2 Methods

A public method (public) with a return value of type void that triggers a BizTaException exception when an error occurs is generated for every method you have created in BizTransactions Studio. The name of each method and the corresponding parameters are the same as those you assigned in the Studio. Since Java does not allow you to pass parameters by reference for return parameters, special classes are generated for return parameters (see section “Passing parameters” on page 290). The method interface defined is copied 1:1.

In addition, BizTransactions generates another public method for every method with parameters that contains all return values in one class. This method is named Methodname_jb and returns an object of the return class. This kind of method interface is necessary if you want to use the business object via RMI (in a J2EE environment, for example, see section “RMI-capable method interfaces” on page 292).

The following methods can be used by the business object class for data exchange via BizTaConnection:

Method Description

public java.lang.String getCommunicationProperties()

Reads the current communication properties and passes them as a string in the form param=value; param=value (see section “Connection properties” on page 307)

public BizTaConnection getCommunicationServer()

Returns a reference to the host adapter.

public void releaseCommunicationServer()throws BizTAException

If the host adapter is defined outside the business object, the connection between the business object and the host adapter can be released with this method.

public public void setCommunicationServer(BizTaConnection commSvr)throws BizTAException

Associates a business object class with the host adapter if the host adapter is defined outside the business object.An exception is triggered if a host adapter is already associated with the business object.



Methods for event handling and logging

The business object inherits the following methods for event handling and logging from its higher-level class BizTaBusinessObject:

Method Description

public void addBizTaEventListener(BizTaEventListener listener)

public void addBizTaEventListener(BizTaFormatEventListener listener)

public void addBizTaEventListener(BizTaInterMediateResultListener listener)

In each case, registers a function for handling events of class BizTaEvent, BizTaFormatEvent or BizTaIntermediateResult.

public void removeBizTaEventListener(BizTaEventListener listener)

public void removeBizTaEventListener(BizTaFormatEventListener listener)

public void removeBizTaEventListener(BizTaIntermediateResultListener listener)

Removes a function for handling events of class BizTaEvent, BizTaFormatEvent or BizTaIntermediateResult.

public void fireEvent(BizTaEvent event)

public void fireEvent(BizTaFormatEvent event)

public void fireEvent(BizTaIntermediateResult event)

Only required for business object-internal func-tions.

public void initLog() Initialized the log file that was defined using the method setLogFilename.

public void writeLog(String line) Writes an entry to the log file that was defined using the method setLogFilename. If no log file has been defined then the call is ignored.



Passing parameters

The parameters are represented differently depending on their usage: in, out and inout.

in parameters correspond to the “call-by-value“ semantics and are mapped to normal Java function parameters. A function’s parameter always contains the same instance of the relevant object or type after a call.

In the case of out and inout parameters, however, the calling function receives a new value from the parameter (with inout, a value can already be transferred at the time of the call). In many languages this can be achieved by using “call-by-reference“ semantic construc-tions, however, Java does not offer this option. The holder classes that are provided or that are automatically generated for each type and each class are used instead. They are used as containers, so to speak, for the value to be passed. This also applies to arrays.

Here is an example for mapping a function:

Java Code

package de.siemens.bizta.PaymentTransactions; public class PaymentTransactions extends BizTaBusinessObject { ... public void Deposit (String AccountNumber, double Amount, DoubleHolder NewBalance) throws BizTAException { ... } ... }

The actual holder classes have a simple structure. They are public final classes named after the type they are allocated to with “Holder” appended to them, e.g. LongHolder. They have a variable called value that contains the value of the allocated type. Additionally, there are two constructors, one empty and one containing an initial value.

This is what the holder for the type Long looks like:

public final class LongHolder implements java.io.Serializable {public long value;public LongHolder() {}public LongHolder(long initial) {

value = initial;}

}



Overview of the Holder classes used by BizTransactions

The following holder classes are contained in the de.siemens.bizta.runtime package in the archive bizta.jar archive.

The corresponding ArrayHolder classes are generated for arrays that are properties of a user-defined class. These holder classes are stored in the archive of the business object (BusinessObject.jar).

The generated classes contain the relevant import statements. The JAR archives that are needed have to be contained in CLASSPATH for the compilation and during execution.

BizTransactions data type Holder class

Boolean BooleanHolder

BooleanArray BooleanArrayHolder

Double DoubleHolder

DoubleArray DoubleArrayHolder

GregorianCalenderArray GregorianCalenderArrayHolder

Long LongHolder

LongArray LongArrayHolder

String StringHolder

StringArray StringArrayHolder



A client application can use the business object as follows:

import de.siemens.bizta.runtime.*;import de.siemens.bizta.beans.PaymentTransactions;...

PaymentTransactions objBO = new PaymentTransactions();String account;double amount;DoubleHolder newvalue = new DoubleHolder();

// AccountNumber from the text input:account = accountTf.getText();// Amount from the text input:amount = Double.parseDouble(amountTf.getText());

// Call method:try {

objBO.Deposit (account, amount, newvalue);

// If all went smoothly (no exception),// output new balance in the text field:saldoTf.setText (Double.toString(newvalue.value));

} catch (Exception e) {System.out.println(e.getMessage());e.printStackTrace();

}

RMI-capable method interfaces

When a business object has method parameters, an RMI-capable method named Methodname_jb is generated in the business object class after the original method. The return parameters of this method are collected in a separate Java class named c_MethodName_ret.

When an error occurs, the Methodname_jb method also triggers a RemoteException exception. In addition, a BusinessObjektWSIF Interface is declared that contains the RMI-capable methods and is implemented by the business object class.

Example

The readCompanyInfo method from the sample session has the following parameters in BizTransactions Studio:

Input parameter searchkey as String

Output parameters companyAddress as String

companyWKN as String



The following Java method is generated first:

public void readCompanyInfo (String searchKey, StringHolder companyAddress, StringHolder companyWKN) throws BizTAException {

...}

The following is also generated for the RMI-capable method interface:

1. The return class c_readCompanyInfo_ret:

public class c_readCompanyInfo_ret implements java.io.Serializable { // return class for out- and inout-parameter of method readCompanyInfo private String companyAddress; private String companyWKN;/** * Get the value for companyAddress: */ public String getcompanyAddress() { return this.companyAddress; } /** * Set the value for companyAddress: */ public void setcompanyAdress(String pcompanyAddress) { this.companyAdress = pcompanyAddress; }

/** * Get the value for companyWKN: */ public String getcompanyWKN() { return this.companyWKN; } /** * Set the value for companyWKN: */ public void setcompanyWKN(String pcompanyWKN) { this.companyWKN = pcompanyWKN; }...}



2. The RMI-capable method readCompanyInfo_jb:

public c_readCompanyInfo_ret readCompanyInfo_jb (String searchKey) throws RemoteException { // method to be used with EJBs and for Web Services c_readCompanyInfo_ret rc; // return class // preparations for calling original method readCompanyInfo StringHolder bizTa_companyAddress = new StringHolder(); StringHolder bizTa_companyWKN = new StringHolder(); // call original method readCompanyInfo try { readCompanyInfo (searchKey, bizTa_companyAddress, bizTa_companyWKN); // put output parameters into the return class rc = new c_readCompanyInfo_ret(); rc.setcompanyAddress(bizTa_companyAddress.value); rc.setcompanyWKN(bizTa_companyWKN.value); } catch (Exception e) { throw new RemoteException("error calling original method readCompanyInfo" + e.toString()); } return rc; }



8.2.1.3 Methods for arrays

The following methods are generated for the automatic resizing and property checks. XXX always stands for the name of the array:

8.2.1.4 Events

Business objects generate events that can be processed by a client application using the business object. In event handling, the business object can be manipulated or the business object method currently being executed can be canceled with an error number (event handling return code) and an error message.

The BizTransactions runtime system contains the following event classes.

● BizTaEvent

● BizTaFormatEvent

● BizTaIntermediateResult

together with the associated interfaces

● BizTaEventListener

● BizTaFormatEventListener

● BizTaIntermediateResultListener

Method Description

public int bizTaGetSizeXXX() Returns the number of array elements.

public void bizTaSetSizeXXX(int index)

The array is dimensioned to the size of index.

public DataType getXXX(int index) Returns the value of the array element defined by index. DataType is the type of the array element.

public void setXXX(int Index,DataType Value)

Sets the value of the array element defined by index.



BizTaEvent

The constructor of the BizTaEvent class created a new event object with which all regis-tered EventListener’s can be called via BizTaBusinessObject.FireEvent.

public BizTaEvent(Object Service, int Type)

Service Event trigger:

– Service object (BizTaService) for the BizTaEvent.BeforeSend and BizTaEvent.DataReceived event types

– Name of the follow-up format (String) for the BizTaEvent.NextFormat event type

Type Event type. You can choose from the following types: BizTaEvent.BeforeSend, BizTaEvent.DataReceived or BizTaEvent.NextFormat

The corresponding event listener must implement the BizTaEventListener interface:

Event Description

public int beforeSend(BizTaEvent event)

Triggered before the next service is sent to the host appli-cation.event.getSource() supplies a reference to the service object whose data is to be transferred.You can, e.g. modify the send data or cancel the method with an error number (event handler return code) and a message (event.setMessage()).

public int dataReceived(BizTaEvent event)

Triggered when data has been received from a service.event.getSource() supplies a reference to the service object whose data was received.You can modify the receive data or cancel the method with an error number (event handler return code) and a message (event.setMessage()).

public int nextFormat(BizTaEvent event)

Triggered when a format has been received.event.getSource() supplies the StringHolder object class with the format name that was previously read with getNextFormat().You can modify the format name or cancel the method with an error number (event handler return code) and a message (event.setMessage()). You can intercept unexpected formats (e.g. following an openUTM restart) with this event and map them to a dummy service.



Example

In the example the method M1 of the business object BoB1 is started. Its status is continu-ously logged while it is being performed:

● The name of the current service is output before the data is read.

● After data has been read, the name of the current service and the data are output.

● When the follow-up format has been read its name is also output.

try {objBO = new BoB1(); System.out.println ("BO created...");

// Define and register event processing:objBO.addBizTaEventListener (new BizTaEventListener() {

public int beforeSend (BizTaEvent e) {System.out.println ("before send " +

((BizTaService)(e.getSource())).getServiceName());return BizTaBusinessObject.NO_ERROR;

}public int dataReceived (BizTaEvent e) {

System.out.println ("data received for " +((BizTaService)(e.getSource())).getServiceName());

System.out.println (((BizTaService)(e.getSource())).getReceiveBuffer());

if (<Fehler>) {e.setMessage (new String ("Test stopped!"));return BizTaBusinessObject.FIRST_USER_ERROR;

} elsereturn BizTaBusinessObject.NO_ERROR;

}public int nextFormat (BizTaEvent e) {

System.out.println ("next format: " +((StringHolder)(e.getSource())).value);

return BizTaBusinessObject.NO_ERROR;}

});

objBO.M1(); // Method callSystem.out.println ("BO after method call, rc = " + objBO.getReturnCode()

+ ", message = " + objBO.getErrorMessage());} catch (Exception e) {

System.out.println(e.getMessage());e.printStackTrace();

}



BizTaFormatEvent

BizTaFormatEvent is derived from BizTaEvent and, in addition to the properties

public int getType ()public String getMessage ()

it also possesses the property

public String getExpectedFormats ()

This property returns a comma-separated list of the names of the formats that are expected if the event occurs.

The corresponding event listener must implement the BizTaFormatEventListener interface which is derived from BizTaEventListener in addition to the methods of the BizTaEventListener interface (see page 296), i.e. the following methods:

Event Description

public int nextFormat(BizTaFormatEvent event)

Triggered when a format has been received.event.getSource() supplies an object of class StringHolder with the format name that was previously read with getNextFormat().You can modify the format name or cancel the business object method that is currently executing with an error number (event handler return code) and an error message (event.setMessage()). You can intercept unexpected formats (e.g. following an openUTM restart) with this event and map them to a dummy service.

public int sequenceError( BizTaFormatEvent event)

Triggered when an invalid format is received.event.getSource() supplies an object of class StringHolder with the format name that was previously read with getNextFormat().You can modify the format name or cancel the business object method that is currently executing with an error code (event handler return code) and an error message (event.setMessage()). You can intercept unexpected formats (e.g. following an openUTM restart) with this event and map them to a dummy service.



BizTaIntermediateResult

This event is used during the implementation of loosely coupled, asynchronous web services (see section “Loosely coupled asynchronous web calls” on page 372).

The BizTaIntermediateResult event has the following properties

public int getCurIndex() Highest currently valid index in RetValues

public Object[] getRetValues() Previous results

The corresponding event listener must implement the BizTaIntermediateResultListener interface:

Event Description

public void intermediateResult(BizTaIntermediateResult event)

Can be triggered in the intermediate code by a statement to indicate that intermediate results are present.





Generally, Java service classes are only needed when handling the events BizTaEvent.BeforeSend and BizTaEvent.DataReceived. They are derived form the higher-level class BizTaService which defines the access methods described below.

8.2.2.1 Property access methods

All properties only have read access, their values cannot be changed:

Method Description

public abstract java.lang.String getServiceName()

Returns the service name

public abstract java.lang.String getFormatName()

FHS services only: Returns the name of the associated FHS format.

public abstract int getSendLength() Returns the length of the send buffer.

public abstract int getReceiveLength() Returns the length of the receive buffer.

public abstract byte[] getSendBuffer() Returns the contents of the send buffer.

public abstract byte[] getReceiveBuffer()

Returns the contents of the receive buffer.



8.2.2.2 Processing methods

The processing methods of a service class are used to access the send and receive buffers and to send and receive the service data.

Method Description

public void setFieldValue(int FPos,int FLen,String FValueboolean Convert)

Writes a string to the send buffer.

FPos Relative position of the field in the buffer

FLen Field length

FValue New value for the field

Convert Specifies if the contents of the field are to be converted:

true: Conversion from ASCII to EBCDIC

false: No conversion

public void setFieldValue(int FPos,int FLen,long FValue,boolean Convert)

public void setFieldValue(int FPos, int FLen, double FValue, boolean Convert)

public java.lang.String getFieldValue(int FPos,int FLen)

Reads data from the receive buffer and returns it as a string

FPos Relative position of the field in the buffer

FLen Field length

public void send() Sends the current contents of the send buffer to the host application.

public void receive() Receives data from the host application and stores it in the receive buffer.



8.2.3 Utility classes of the runtime system

8.2.3.1 BizTaVariant

This class maps the functionality of the Visual Basic variant data type to Java methods. It is used internally by BizTransactions. The Java methods are described in the section “Freely programmable statements for Java” on page 217.

8.2.3.2 BizTaSup

BizTaSup is a module that contains service functions such as check and conversion routines for business objects. It is a class of the runtime system (de.siemens.bizta.runtime package).

BizTaSup is called from the business object class for internal purposes. All methods are class methods, and no objects of this class therefore need to be instantiated.




The BizTaConnection adapter is the Java class for communicating via the UPIC, 9750 and 3270 protocols. This section is only relevant if you want to develop a new adapter.

8.2.4.1 Access methods for properties

Method Description

public String getCallerType()

public void setCallerType(String callerType)

Identifies the calling program

public short getCommStatus() Returns the status of the connection as a constant. Possible values:BizTaConnection.ST_STARTBizTaConnection.ST_INITBizTaConnection.ST_SENDBizTaConnection.ST_RECEIVEBizTaConnection.ST_NO_DATABizTaConnection.ST_RESET

public String getComputerName()

public void setComputerName(String computerName)

Host with the calling program

public String getConnectionLocalName() Returns the station name automatically generated with setLocalName.

public BizTaAdapter getConnectionID() Returns an object that implements the adapter interface for low level communication

public String getConnectionType() Returns the protocol type for Trace and Adminis-tration. Possible values: OpenUTM, Em9750, EM3270, Unknown

public String getFormatName()

public void setFormatName(String formatName)

Format name

public getHost() Returns the name of the server host for Trace and Administration.

public String getLocalName()


Local application name. If you do not specify anything, then BizTransactions dynamically generates a station name.

public String getPartner() Returns the partner name of the connection for Trace and Administration.



public int getReceiveLength()

public void setReceiveLength(int newlen)

Length of the receive buffer

public ScreenCapture getScreenCapture()

public void setScreenCapture(ScreenCapture scrc)

Object for format detection. The generated class must create and set this object when format detection is to be used because the base communication does not provide format detection, for example.

public String getServiceName()

public void setServiceName(String serviceName)

Name of the Service, maximum of 32 characters

public String getStatusString() Describes the status of the connection. Possible values:Start Service is not signed on to the

hostInitialize Connection successfully estab-

lishedReset Connection terminatedSend Data can be sent to the serviceReceive Data can be received from the

service NoData No more data available from the

service

public String getUserName()

public void setUserName(String userName)

Name of the caller (Windows name)

public int getCommunicationTraceLevel()

public void setCommunicationTraceLevel(int newlev)

Volume of the communication trace. The follow-ing constants are possible:

BizTaTraceAll Log everything

BizTaTraceBuffer Log only sent and received data

BizTaTraceUnchanged Use the value from the fileBizTaV3.properties

BizTaTraceNone No logging

public String getPropertiesFile() Pathname of the BizTransactions configuration file BizTaV3.properties (see chapter “BizTransactions Administration” on page 357)

Method Description



8.2.4.2 Methods

Method Description

public boolean checkConnection() throws BizTaException

Checks the status of the connection, in particular to see if the server host has terminated the connection. If the connection exists, then the method returns True, otherwise it returns False.

public String getAdapterLib(int contype)

Returns the path name for the protocol library used as a string. You can query the following protocols: BizTaEm9750, BizTaEm3270, BizTaUTMV3. BizTaUTMV4, BizTaUTMV5

public String getCommunicationProperty(String optname)

Returns the value of the optname connection property as a string. See also section “Connection properties” on page 343.

public String getNextFormat()throws BizTaException

Returns the name of the next format when – the underlying communication method returns

format names– the format was able to be identified by the format

detection. The net data is then returned during the next Receive() call.

public byte[] receive(byte[] receiveBuffer,int receiveBufferPos,int receiveBufferLen)throws BizTaException

Reads a maximum of receiveBufferLen bytes from the host and writes them to the receiveBuffer starting at position receiveBufferPos.

public void send(byte[] sendBuffer,int sendBufferPos,int sendBufferLen)throws BizTaException

The calling program (generated class) passes the data to be sent of length sendBufferLen in the sendBuffer starting at position sendBufferPo.

public void setCommunicationProperties( String values)

Performant setting of the connection properties. The calling program (generated class) passes a compact string of the form Param=value;Param=value to BizTaConnection.This string is taken apart and the individual values are stored in the corresponding instance variables.values Connection properties of the calling

program, see section “Connection properties” on page 343.

public voidsetCommunicationProperty(String optname,String optValue)

Sets the value of the optname connection property, see section “Connection properties” on page 343.



public void stopCommunication()throws BizTaException

Terminates the connection.

public java.lang.String toASCII(String source)

Only for communication with openUTM applications: Converts the data received. You should only use this method when no automatic conversion takes place. See also section “Conversion table for the ToASCII and ToEBCDIC functions” on page 394.

public java.lang.String toEBCDIC(String source)

Only for communication with openUTM applications: Converts the data to be sent. You should only use this method when no automatic conversion takes place. See also section “Conversion table for the ToASCII and ToEBCDIC functions” on page 394.

public boolean useAdapterClass(String className)

Sets the host adapter as a Java component.You enter the class name without path specification in className.

public boolean useAdapterLibrary(int conType,String libPath,String initFctName)

Sets the host adapter as a DLL.conType contains the necessary protocol, You can specify the following values: BizTaEm9750, BizTaEm3270, BizTaUTMV3. BizTaUTMV4, BizTaUTMV5, BizTaServiceOther.You can specify a host adapter other than BizTaConnection with BizTaServiceOther. If you specify BizTaOther, then you must specify the path name of the initialization function of the new host adapter in libPath and its name in initFctName. This parameter is ignored for all other protocols.

public void writeLog(String message,String serviceName)

public void writeLog(String message,String component,String serviceName)

Writes a line to the log file of the business object.

Method Description



8.2.4.3 Connection properties

The names and values of the connection properties that you can specify when calling the GetCommunicationProperty, SetCommunicationProperty and SetCommunicationProperties methods depend on the host adapter used and the protocol.

Connection properties for the 9750 and 3270 protocols:

Property Access 1

1 O: Set only before opening connectionR: ReadW: Write

Description

CursorPos R/W Position of the input cursor. The position is calculated from the distance to the start of the screen, e.g. 163 for the second line, third column for a screen that is 80 columns wide.

FunctionKey R/W Send type of a format. Possible values for TerminalType 9750 and 9763: "DUE", "DUE2", "K1" through "K14", "F1" through "F24", "PKEY1" through "PKEY20"Possible values for TerminalType 3270 :"ENTER", "PF1" through "PF24", "PA1" through "PA3", "RESET", "ATTN", "CLEAR", "SYSREQ"

Host O Name or IP address of the host computer

LocalName O Station name (possibly generated automatically) or the LU name (3270 emulation).

MultioTimeout W Wait period for message segments in seconds, default setting: 2s

Partner O TerminalType 9750 or 9763: Name of the terminal applicationTerminalType 3270 : not relevant.

ReceiveTimer W Maximum wait time for the reception of data in seconds, default setting: 120s

RecordFile R/O File name for the recording of a session. Recording of the session is started as soon as this property is set.

ReplayFile R/O File name the replaying of a session. Replaying of the session is started as soon as this property is set.

ScreenSize R Returns the current screen size in the column x rows format, e.g. "80x25".

TerminalType O Terminal or connection typeYou can specify the following values:"9750": 9750 emulation without 8-bit support (default)"9763": 9750 emulation with 8-bit support"3270": 3270 emulation



Connection properties for the Upic protocol:

Property Access1

1 O: Set only before opening the connectionR: ReadW: Write

Description

Conv R/W Conversion: Possible values"HD": Automatic conversion (default) "SD": No conversion "SN": No conversion (UNIX systems)

CState R Current connection status: Possible values CON_RESET Connection reset by host CON_SEND Send() expected / permittedCON_RECEIVE Receive() expected / permitted

FormatName R/W FHS only: Format name

FormatType R/W FHS only: Format type: Possible values: BizTaFormatTypeNone No format BizTaFormatTypeNb # format BizTaFormatTypePlus + format BizTaFormatTypeStar * format

FunctionKey R/W FHS only: Format send typePossible values: "DUE", "DUE2", "K1" through "K14", "F1" through "F24".

Host R/O Name or IP address of the server host

LocalName R/O Local application name (must be defined with the PTERM or TPOOL statement in openUTM), maximum of 8 characters. If you do not specify anything, then a local application name is automatically created.

Partner R/O Name of the openUTM application (corresponds to the value of the openUTM statement MAX APPLINAME).

Pass R/O openUTM password (optional, maximum of 8 characters)

PortNumber R/W Port number of the partner application; range of values 0-32767Default: 102

ReceiveTimer R/W Maximum wait time for the reception of data in seconds, default setting: 120 seconds

TAC R/W Name of the openUTM transaction code

User R/O openUTM user ID (optional, maximum of 8 characters)

Version R/O Defines the version of the openUTM or DRIVE program. You can specify the following values: BizTaUTMV3 UTM program unit V3.4BizTaUTMV4 UTM program unit > V3.4BizTaUTMV5 UTM program unit > V5.0



8.2.5 BizTaException

The BizTransactions runtime system contains the class BizTaException. This exception is thrown by the business object methods if an error occurs. BizTaException is derived from the class ComTAException.

Constructors

public BizTaException (String message, int BizTaRc, String BizTaFunction, String BizTaServiceNode, String BizTaParam, String BizTaMessage)

public BizTaException (String message, int BizTaRc, String BizTaFunction, String BizTaServiceNode, String BizTaParam, String BizTaMessage Exception e)

For information on the return codes, see section “Return codes of business object methods” on page 356.

Properties

The class BizTaException exclusively possesses read-only properties:

Property Description

public String getMessage() Method inherited from the higher-level class ComTAException: error message

public int getBizTaRc() Return code of type int, contains a return code as defined in BizTaBusinessObject (see section “Return codes of business object methods” on page 356)

public String getBizTaFunction()

Name of the defective function

public String getBizTaServiceNode()

Name of the defective service node

public String getBizTaParam() Name of the defective parameter

public String getBizTaMessage()

More detailed error message


.NET Client interface of business objects

8.3 .NET


.NET business objects are generated in Visual Basic .NET. The business object class is derived from Component. A class derived from Component can be used by clients in other application domains, whether these take the form of other applications in the client process, or application domains in other processes or on other hosts. As a result, BizTransactions .NET business objects are also suitable for distribution over multiple hosts (remoting).

8.3.1.1 Properties

A private variable with the prefix m_ is generated for each business object property. The following properties are generated alongside those that you define yourself.

Properties for all business object classes:

Property Type Access1 Description

CommunicationTraceLevel

Enum R/W Scope of the communication trace. The following constants are possible:

All Log everythingBuffer

Log only the sent and received dataUnchanged

Use the value from the fileBizTaV3.properties

None No logging

GenVersion String R Information about the class date, time, catalog

Host String R/W System on which the host application is running.

Partner String R/W Application name; for openUTM applications, this corresponds to the APPLINAME or BCAMAPPL name defined in KDCDEF; in the case of 3270 applications it is not relevant.

ReceiveTimer Long R/W Receive Timer in seconds;default value: 120 seconds


Client interface of business objects .NET

Properties for business object classes that communicate via openUTM:

Properties for business object classes that communicate via the 9750 emulation:

Properties for business object classes that communicate via the 3270 emulation:

Examples

Write and read access to a property:

myBusinessObject.myProperty = "one String"myStringVar = myBusinessObject.myProperty

In this example, an array of strings is assigned to the property myStringArray. The proper-ty’s data is then transferred to the variable myStrings.

myBusinessObject.myStringArray = New String() {"A", "BB", "CCC"}Dim myStrings() As String = myBusinessObject.myStringArray


LocalName String R/W Local application name, default setting=" "

Pass String R/W openUTM: log-in password

Port Integer R/W Port number used

TAC String R/W Transaction code for establishing a connection (Start TAC)

User String R/W openUTM: log-in name


LocalName String R/W Local application name, default setting=" "

Property Type Access1

1 R: ReadW: Write

Description

LUName String R/W LU name, default setting=" "



8.3.1.2 Methods

The following methods are available in the business object class for data exchange via BizTaConnection:

Method Description

Function GetCommunicationProperties() As String

Reads all the current communication properties and transfers them as a string in the form param=value;param=value (see section “Connection properties” on page 330).

Function GetCommunicationServer() As BizTaConnection

Supplies a reference to the host adapter.

Sub New() Constructor with no parameters

Sub Dispose() Call this method if you no longer need the business object. All the resources used by the business object are released.

Sub ReleaseCommunicationServer()

If the host adapter is defined outside of the business object then you can use this method to terminate the connection between the business object and the host adapter.

Sub SetCommunicationServer(objRef As BizTaConnection)

Links the business object class to the host adapt-er if it is defined outside of the business object.




The following methods are generated for the automatic redimensioning and checking of the business object’s properties as well as the properties of user-defined classes. XXX stands for the name of the array.

Method Description

Public Function bizTaGetSizeXXX() As Integer

Returns the number of array elements.

Public Sub bizTaSetSizeXXX(ByVal Index As Integer)

The array is dimensioned to the size of Index.



8.3.1.4 Calling methods

In BizTransactions there are a number of different ways of calling a business object’s meth-ods:

● Conventional call

– You generate an instance of the business object.

– You define the method’s input/output parameters.

– You assign values to the input parameters.

– You call the method.

– You edit the method’s output parameters.

– You call the Dispose method for structured termination of communication with the host application.

● Asynchronous call with BeginInvoke / EndInvoke (see below)

● Asynchronous or synchronous call using a Helper class (see page 316)

The last two calls are embedded in the source of the generated business object in a sepa-rate Region directly before the method itself.

You should use asynchronous calls in order to execute method calls efficiently without the application being blocked by the execution of potentially disproportion-ately long network calls. If you address multiple business objects in an application then the runtimes of the method calls are additive. Using asynchronous calls keeps your application free for other activities such as reacting to user inputs or feedback concerning the current status. The total runtime therefore corresponds only to that of the slowest method.

Asynchronous call with BeginInvoke / EndInvoke

You use the pair of methods BeginInvoke/EndInvoke to call business objects asynchro-nously. The two methods and the associated Delegate are generated by BizTransactions.

The Begin method has the following signature:

Public Function BeginMethod(Method-params, _ByVal CallBack As System.AsyncCallBack, _ByVal AsyncState As Object) As IAsyncResult

Method Name of the method.

Method-params Complete signature of the method parameters.

i



CallBack Delegate: mechanism used to declare a function pointer in the administered code. In this case, the function is called when the method call is concluded and you have received a response.

AsyncState Parameter declared as the object type. All the entries that you want to use to trace the call are possible here. In the case of multiple asynchronous calls, you can determine which method call has just been concluded on the basis of this parameter.

IAsyncResult Interface pointer with which you can obtain information about the status of the asynchronous method call and retrieve the results with EndMethod.

The End method has the following signature:

Public Sub EndMethod(InOutMethod-params|OutMethod-params, AsyncResult As IAsyncResult)

IAsyncResult contains the following (and other) parameters:


AsyncState Data which you entered in the last parameter in BeginMethod.

AsyncWaitHandle You can use this WaitHandle object to block the current thread until the method is concluded.

Exampleresult.AsyncWaitHandle.WaitOne() The methods WaitOne, WaitAll and WaitAny accept a timeout as parameter. In this way, you can check how long you have to wait until the method terminates. If a timeout occurs, these methods return False.

IsCompleted Indicates whether the method has already been completed.



Example for the use of the Callback parameter

This utilization of Callback is well suited to initiating processing immediately after conclusion of a method.

The method has terminated:

Private Sub MethodCallback(ByVal result As IAsyncResult)Dim response As StringobjBo.EndMethod(response,result)Label1.Invoke(New myDelegate(AddressOf Me.DisplayResponse), _

New Object() {response})End Sub

Refresh the window:

Private Sub DisplayResponse(ByVal response As String)Label1.Text = response

End Sub

When the method terminates, the MethodCallback procedure is called. Here, the results of the method are retrieved with EndMethod. This procedure does not run in the Windows appli-cation thread but in the asynchronous Worker thread. In Windows, it is not permitted to access “windows” that were not generated in the same thread. Consequently, you must refresh the “window” Label1 in the Windows application thread. To do this, you call Label1‘s Invoke method via a delegate.

Calling using a Helper class

Using a Helper class has the following advantages:

● All the input/output parameters are already declared in this class. You simply have to enter the parameters and then fetch the results at the end. You can do this in the main message thread, You therefore do not need any control.Invoke method.

● There are three start modes available for starting the method (Run). You simply need to change one parameter in order to perform an asynchronous method call instead of a synchronous one (see section “Start mode in a Helper class” on page 318).

● An information function (IsCompleted) is available for asynchronous calls.

● You can cancel asynchronous calls (Abort).

For every business object method, a Helper class is also generated in which all the method parameters are available as Public variables. This class also contains the methods Run, Join, IsCompleted and Abort.



Example

The figure below presents an example to illustrate how a method named MethodX and a series of parameters are packed in a Helper class. The name of the Helper class consists of the prefix Par followed by the method name.

If you are using a Helper class, you can call a business object’s methods as follows:

Ê Generate an instance of the business object.

Ê Generate an instance of the Helper class and choose how the method is to be started (see section “Start mode in a Helper class” on page 318).

Ê Assign values to the input parameters in the Helper class.

Ê Call the Helper class’s Run method.

Ê Call the helper class’s Join method to wait for the results.

Ê Process the method’s output parameters.

Ê Call the Dispose method for the business object in order to perform a structure termi-nation of communication with the host application.

MethodX (ParIn1, ParIn2, ParOut1, ParOut2, ParOut3)

Class ParMethodX

Public_ParIn1Public_ParIn2Public_ParOut1Public_ParOut2Public_ParOut3

Run(RunMode)

Join()

IsCompleted()

Abort()

Access to method parameters (public variable in the Help-er class)

Start method

Wait for end of method

Has method terminated?

Cancel method

RunMode- Synchronous- AsynUseThreadPool- AsynUseThread



Methods in a Helper class

Start mode in a Helper class

Method Description

Public Sub Run(ByVal RunMode As RunMode)

Starts the business object method in the required start mode.

Public Sub Join() Waits for termination of the business object method.

Public Function IsCompleted() As Boolean

If the method completes correctly, True is returned here, otherwise False.

Public Sub Abort() Cancels the method.

Start mode Description

Synchronous The method is started synchronously. – IsCompleted always returns True. – Abort has no effect.

AsynUseThreadPool The method is started asynchronously. – IsCompleted returns the method’s state. – Abort cancels an active method. – The thread is removed from the thread pool. The number of

threads is limited and depends on a variety of circumstances (e.g. number of processors). For single processor machines, this means that approximately 25 threads are available. If not enough free threads are available then the method call waits for a thread to become free in the thread pool.

AsynUseThread The method is started asynchronously. – IsCompleted returns the method’s state. – Abort cancels an active method. – The method is started with an explicitly generated background

thread (IsBackground=True). Method start is therefore inde-pendent of the number of asynchronous jobs that have already been started. However, excessive use of this feature can lower overall throughput.



Instantiating a Helper class

You can instantiate a Helper class with, for example, the following call:

myHelperClass = myBo._ReadAccounts()

myHelperClass Method-specific Helper class. The name of the class has the formBusiness_Object_Name.ParMethod_Name (see “Example” on page 320).

myBo Business object possessing a ReadAccounts() method.

_ReadAccounts Method-specific property generated by the Helper class. The name of this property is the name of the method with a prefix _.



Example

In this example, a business object named BankExample possesses a ReadAccounts method with 3 parameters:

The first step is to define all the required variables. This is followed by the method Normal which issues a synchronous call of the business object method ReadAccounts. The busi-ness object method ReadAccounts is then called asynchronously in the Begin method. The method BeginReadAccounts returns immediately to the caller. You can now, for example, start an additional business object method. The result of the Begin method is expected in the Ende method.

Private myAccounts() As AccountListClass ' Output: array AccountListClassPrivate myCallBack As System.AsyncCallback ' CallBackPrivate myAsyncState As String = "HI" ' Content for identificationPrivate mAsyncResult As IAsyncResult ' for Begin/End<METHOD>Private myPar As BankExample.ParReadAccounts ' Helper class

Private Sub Normal()' Normal synchronous call of the method ReadAccountsMe.BankExample1.ReadAccounts(KdcsignPar:="KDCSIGN USER1", BankPar:=

"BANK 201", AccountListClassP:=myAccounts)ShowResults(myAccounts)

End Sub

Private Sub Begin()' Asynchronous call with Begin<METHOD>mAsyncResult = Me.BankExample1.BeginReadAccounts(KdcsignPar:=

"KDCSIGN USER2", BankPar:="BANK 201", _AccountListClassP:=myAccounts, _CallBack:=myCallBack, AsyncState:=myAsyncState)

' we have time to do other things... "

End Sub

Private Sub Ende()' Wait until the end of the Begin<METHOD>. Retrieve the results withEnd<METHOD>Me.BankExample1.EndReadAccounts(AccountListClassP:=myAccounts,

AsyncResult:=mAsyncResult) ShowResults(myAccounts)

End Sub


KdcsignPar Input parameter

BankPar Input parameter

AccountListClassP Output parameter of type Array in class AccountListClass



There now follow two methods that demonstrate method calls with the Helper class:

● The business object method is started in StartHelper. The start mode is passed in the parameter RunModeParam. The call syntax is the same for all 3 variants with the exception of the Run method’s RunMode parameter.

● The result of the StartHelper method is expected in EndHelper.

Private Sub StartHelper(ByVal RunModeParam As String)' Calls the method via the Helper classmyPar = BankExample1._ReadAccounts() ' Retrieve Helper classWith myPar ' Enter input parameters

.KdcsignPar = "KDCSIGN USER3" ' present in the Helper class

.BankPar = "BANK 201"Select Case RunModeParam ' Start mode?

Case "AsynUseThreadPool" ' - Thread pool?.Run(BankExample.RunMode.AsynUseThreadPool)' we have time to do other things ... "

Case "AsynUseThread" ' - Own thread?.Run(BankExample.RunMode.AsynUseThread)' we have time to do other things ... "

Case Else ' - otherwise synchronous.Run(BankExample.RunMode.Synchronous)

End SelectEnd With

End Sub

Private Sub EndHelper()' Retrieve the results (not necessary for synchronous calls).myPar.Join()ShowResults(myPar._AccountListClassP)

End Sub

Private Sub ShowResults(ByVal myAccounts() As AccountListClass)' Display results...

End Sub



8.3.1.5 Events

Business objects generate events that can be processed by a client application that uses a business object. In event handling, you can manipulate the business object or terminate the business object method that is currently being processed with an error number (return value of event handling) and a message text.

You can write event handlers for the business object events in order to

● Output diagnostic information (e.g.. what data has been received from the host appli-cation, what data is sent to the host application)

● manipulate data before it is sent

● Intercept sequence errors and take over format control yourself

● Process intermediate results of business object methods that execute over an extended period and possess exactly one output parameter of type Array of SimpleClass

Event handlers can be

● Retrieved with WithEvents

● Assigned with AddHandler and removed again with RemoveHandler

Example

AddHandler MyBO.BeforeSend, AddressOf BizTaBoBeforeSendRemoveHandler MyBO.BeforeSend, AddressOf BizTaBoBeforeSend

Private Sub BizTaBoBeforeSend(ByVal ServiceObject As IBizTaService, _ByRef Returncode As Integer, ByRef ReturnMessage As String) ' Before Send

End Sub

A detailed example of the interception of intermediate results can be found in the tutorial Using BOs.doc that is supplied with BizTransactions. You will find this file in the BizTransactions installation directory underExamples\Documents\En\ExampleUPIC\Tutorial Using BOs.doc.



Event Description

Public Event BeforeSend(ServiceObject As IBiztaService, ByRef ReturnCode As Integer, ByRef ReturnMessage As String)

Triggered before the next service is sent to the host application.ServiceObject contains a reference to the service object whose data is subsequently to be sent.You can, for example, modify the send data or cancel the method with an error number (ReturnCode) and message text (ReturnMessage).

Public Event DataReceived(ServiceObject As IBizTaService, ByRef ReturnCode As Integer, ByRef ReturnMessage As String)

Triggered when data is received from a service.ServiceObject contains a reference to the service object whose data is to be received.You can, for example, modify the received data or cancel the method with an error number (ReturnCode) and message text (ReturnMessage).

Public Event NextFormat(ByVal ExpectedFormats As String, ByRef FormatName As String, ByRef Returncode As Integer, ByRef ReturnMessage As String)

Triggered when a format is received.FormatName contains the format name previously read with GetNextFormat(). You can modify the format name or cancel the method with an error number (ReturnCode) and message text (ReturnMessage). This event allows you to intercept unexpected formats (e.g.. after an openUTM restart) and map them to a “dummy service”.

Public Event SequenceError(ByVal ExpectedFormats As String, ByRef FormatName As String, ByRef Returncode As Integer, ByRef ReturnMessage As String)

Triggered when an invalid format is received. The expected formats are passed in ExpectedFormats. You can modify the format name FormatName or cancel the method with an error number (ReturnCode) and message text (ReturnMessage).

Public Event IntermediateResult (ByVal ID As String, _ ByVal CurrIndex As Integer, _ByVal RetArray() As <SimpleClass>)

Can be triggered by an intermediate code statement to indicate that intermediate results are present. ID contains the job ID, CurrIndex the highest currently valid index in RetArray, and RetArray the previous results.




A separate service class Friend NotInheritable is generated in the file BizTaServices.vb for each service used in a business object’s method.

The following methods are available for programming with the BizTransactions events BeforeSend, DataReceived, SequenceError and NextFormat:

Method Description

Function GetFieldValue(ByVal FPos As IntegerByVal FLen As IntegerByVal Convert As Boolean)As String

Reads data from the receive buffer and returns it as a string.

FPos Position of the field relative to the buffer

FLen Field length

Convert Specifies whether the content of the field is converted:

TRUE: Conversion from ASCII to EBCDIC

FALSE: No conversion

Function ReceiveBufferToString()As String

Passes the content of the receive buffer as a string.

Function SendBufferToString() As String

Passes the send buffer as a string.

Sub SetFieldValue(ByVal FPos As IntegerByVal FLen As IntegerByVal FValue As StringByVal Convert As Boolean)


FPos Position of the field relative to the buffer

FLen Field length

FValue New value for the field

Convert Specifies whether the content of the field is converted:





8.3.3 User-defined classes

User-defined classes in .NET are constructed using the following rules:

● All classes can be serialized:

<Serializable()> Public NotInheritable Class myClass

● Alongside the default constructor, classes also have a constructor for all member variables.

Example

Public Sub New(bool1 As Boolean, boolAr() As Boolean, long1 As Long, longAr() As Long, dbl1 As Double, dblAr() As Double, str1 As String, strAr() As String, date1 As Date, dateAr() As Date)

Me.bool1 = bool1..End Sub

● In addition, two ToString methods are generated for each class:

Public Overloads Function ToString() As String Return ToString(Indent:=Integer.MinValue,Offset:=0)End Function

Public Overloads Function ToString(ByVal Indent As Integer, ByVal Offset As Integer) As String ' Indent: Start value for indent level on output ' Offset: Offset for nested classesEnd Function



Example

In the case of complex nested classes, you can use the ToString method with the Indent parameter.

Debug.WriteLine(usec1.Tostring(Indent:=0,Offset:=1))<<< Class = c1>>>C1bool1=TrueC1useC2==<<< Class = c2>>>|C2Long=55555|C2useC3===<<< Class = c3>>>||C3Double=1E+41||C3useC4====<<< Class = c4>>>|||C4String=a_1|||C4useC5=====<<< Class = c5>>>||||C5Date=09.10.2002 00:00:00||||C5useC6======<<< Class = c6>>>|||||C6Bool=True|||||C6Long=55555||||C5DateArrray[0]=03.05.2002 00:00:00||||C5DateArrray[1]=03.05.2005 00:00:00|||C4StringArray[0]=strArray||C3dblAr[0]=8,88888888888889E+48|C2longAr[0]=77777C1boolAr[0]=True




BizTaConnection is the shared host adapter interface to the business objects. BizTaConnection is the .NET component for communication via the protocols UPIC, 9750 and 3270.

8.3.4.1 Properties

Property Access Description

CommunicationTraceLevel R/W Scope of the communication trace. The permitted values for this property are defined by the Enum type AdapterTraceLevel which can have the following values:

All Log everythingBuffer

Only log the sent and received dataUnchanged

Use the value from the fileBizTaV3.properties

None No logging

ServiceID R/W Name of the current service node

ConnectionID R Returns an object that implements the adapter interface for low-level communication (IBizTaAdapter interface)

FormatIdObj R/W Object for format recognition

FormatName R Current format name (only 9750 and 3270)

ReceivedData R Content of receive buffer

ReceiveLength R Length of receive buffer



8.3.4.2 Methods

Method Description

Public Overloads Sub Dispose() Implements IDisposable.Dispose

If the adapter is no longer required, the Dispose method should be called in all cases. This method is responsible for releasing all the employed resources.

Public Function CheckConnection() As Boolean

Checks the status of the connection, in particular to see if the server host has terminated the connection. If the connection exists, then the method returns True, otherwise it returns False.

Function GetAdapterLib(ByRef contype As net.fsc.BizTransactions.Connection.BizTaConnection.BizTaServiceVersion) As String

Returns the path name for the protocol library used as a string. You can query the following protocols: BizTaEm9750, BizTaEm3270, BizTaUTMV3, BizTaUTMV4, BizTaUTMV5

Public Function GetCommunicationProperty(ByRef optname As String) As String

Returns the value of the optname connection property as a string. (See also section “Connection properties” on page 330).

Public Function GetNextFormat(ByRef NextFormat As String, ByRef message As String,ByRef Status As String)As Boolean

Returns the name of the next format when – the underlying communication method returns format

names– the format was able to be identified by the format

detection. The net data is then returned during the next Receive() call.NextFormat Name of the following formatmessage Messages issued by this methodStatus Status of the connection

Public Function Receive(ByRef ReceiveBuffer() As Byte,ByVal ReceiveBufferPos As Integer,ByRef ReceiveBufferLen As Integer,ByRef message As String,ByRef CommStatus As String)As Boolean

Reads a maximum of receiveBufferLen bytes from the host and writes them to the receiveBuffer starting at position receiveBufferPos. The calling program receives all the accrued messages in the message parameter and the status of the connection is returned in CommStatus.

Public Function Send(ByRef SendBuffer() As Byte,ByVal SendBufferPos As Integer,ByVal SendBufferLen As Integer,ByRef message As String,ByRef CommStatus As String)As Boolean

The calling program (generated class) passes the data to be sent of length sendBufferLen in the sendBuffer starting at position sendBufferPo. It receives all the accrued messages in the message parameter and the status of the connection is returned in CommStatus.



Public SubSetCommunicationProperty( ByVal optname As String, ByVal optValue As String)

Sets the value of the optname connection property(see section “Connection properties” on page 330).

Public Function SetCommunicationProperties(ByValvalues As String) As Boolean

Performant setting of the connection properties. The calling program passes a compact string of the form Param=value;Param=value to BizTaConnection.This string is decomposed and the individual values are stored in the corresponding instance variables.values Connection properties of the calling program (see

section “Connection properties” on page 330).

Public Function ToASCII(Source As String)As String


Public Function ToEBCDIC(Source As String)As String

Only for communication with openUTM applications: Converts the data to be sent. You should only use this method when no automatic conversion takes place. See also section “Conversion table for the ToASCII and ToEBCDIC functions” on page 394.

Public Function ToString() As String

Outputs diagnostic data (status of the connection as well as format recognition for 9750 and 3270).

Public Function UseAdapterClass(className As String) As Boolean

Sets the host adapter as a .NET component.You specify the class name in className.

Public Function UseAdapterLibrary(conType As net.fsc.BizTransactions.Connection.BizTaConnection.BizTaServiceVersion, libPath As String, ByRefinitFctName As String)As Boolean

Sets the host adapter as a DLL.conType contains the necessary protocol, You can specify the following values: BizTaEm9750, BizTaEm3270, BizTaUTMV3. BizTaUTMV4, BizTaUTMV5, BizTaServiceOther.You can specify another host adapter with BizTaServiceOther. If you specify BizTaOther, then you must specify the path name of the initialization function of the new host adapter in libPath and its name in initFctName. These parameters are ignored for all other protocol libraries.

Method Description





The table of connection properties for the 9750 and 3270 protocols can be found on page 307, and the connection properties for the UPIC protocol on page 308.



8.3.5 BizTaException

The BizTransactions runtime system contains the class BizTaException. This exception is thrown by the business object methods when an error occurs.

The BizTaException class is derived from BaseApplicationException in the Microsoft Exception Management Application Block (see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnbda/html/emab-rm.asp).

This component provides you with an extensive framework in which you can react precisely to errors by making simple changes in the configuration file without having to modify the business object. An example configuration file with standard configuration data can be found in section “Example: configuration file for a program (.exe)” on page 350.

You can, for example, log error messages in a database or file , send e-mails or trigger WMI events (Windows Message Instrumentation).

If you do not make any entries in the configuration file then all the errors are recorded in the event log.

Properties

The BizTaException class has the following properties:

To prevent logging in the event log, set the attribute mode="off" in the configuration file’s ExceptionManagement element.


BizTaRc Return code of type BizTaBoErrors

BizTaFunction() Name of the defective function

BizTaServiceNode() Name of the defective service node

BizTaParam() Name of the incorrect function

BizTaMessage() Detailed error message

BizTaLocVars Content of the local variables of the defective method

DataReceived Last data read from the host application

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnbda/html/emab-rm.asp



Example

<?xml version="1.0" encoding="utf-8" ?><configuration>

<configSections><section name="exceptionManagement"

type="Net.fsc.BizTransactions.ExceptionManagement.ExceptionManagerSectionHandler,Net.fsc.BizTransactions.ExceptionManagement" />

</configSections><exceptionManagement mode="off"/><system.diagnostics>

<switches><add name="BizTaTrace" value="4"/>

</switches></system.diagnostics>

</configuration>


Client interface of business objects ActiveX

8.4 ActiveX


8.4.1.1 Properties

A private variable with the prefix “m_” is generated for each business object property. For the communication data in Visual Basic additional properties are generated.

The values of the properties are read by BizTransactions Studio from the catalog or are supplied by BizTransactions Studio with default values at generation time. Read and write functions (Get / Let) are generated for the properties of the business objects in accordance with the access type set.

Properties for all business object classes:


BizTaReturnCode BizTa-BoErrors

R Return value of the last method call

ErrorMessage String R Error message from last method call

ExtendedErrorMessage String R Extended error message

GenVersion String R Class information: date, time, catalog

LogFilename String R/W Specifies the path of the log file. You can set this variable to one of the following values:

BizTaConnection.LogEvent All messages are written to the Windows Event Log. However, this only works when the business object was generated as an ActiveX component.

"" (empty string) Logging is suppressed

pathname All messages are written to the specified file. The process ID and the thread ID are appended to the name specified:pathname-pid-tid.TXT.

Partner String R/W Application name. For openUTM applications it corresponds to the APPLINAME specified for KDCDEF or the BCAMAPPL name. For 3270 appli-cations it is not relevant.

ReceiveTimer Long R/W Receive timer in seconds;Default: 120 seconds


ActiveX Client interface of business objects

Properties for business objects that communicate via UPIC:

Properties for business objects that communicate via the 9750 emulation:

Properties for business objects that communicate via the 3270 emulation:


Host String R/W Computer on which the host application runs

LocalName String R/W Local application name, default = " "

Pass String R/W Password for sign-on

Portnumber Long R/W Port number for the connection to the partner application, range of values: 0 - 32,767Default: 102

User String R/W Application name


Host String R/W Computer on which the host application runs

LocalName String R/W Local application name, default = " "

TerminalType Long R Emulation: BizTaTerm9750, BizTaTerm9763

Property Type Access1

1 R: ReadW: Write

Description

LUName String R/W LU name, default = " "



8.4.1.2 Methods

A public method (public Sub) without a return value that triggers an exception when an error occurs is generated for every method you have created in BizTransactions Studio. The following methods can be used by the business object class for data exchange via BizTaConnection:


The following methods are generated for the automatic resizing and property checks. XXX always stands for the name of the array:

Method Description

Function GetCommunicationProperties() As String

Reads the current communication properties and passes them as a string in the form param=value; param=value (see section “Connection properties” on page 343).

Function GetCommunicationServer() As BizTaConnection

Returns a reference to the host adapter

Sub ReleaseCommunicationServer()

If the adapter is defined outside the business object, the connection between the business object and the host adapter can be released with this method.

Sub SetCommunicationServer(objRef As BizTaConnection)

Associates a business object class with the host adapter if the host adapter is to run outside the business object.

Method Description

bizTaGetSizeXXX()As Long

Returns the number of array elements.

bizTaSetSizeXXX(index as Long)

The size of the array is set to the size of the index.

getXXX(index As Long) As DataType

Returns the value of the array element defined by index. DataType is the type of the array element.

setXXX(index As Long,value As DataType)

Sets the value of the array element specified by index.



8.4.1.4 Events

Business objects generate events that can be processed by a client application using the business object. In event handling, the business object can be manipulated or the business object method currently being executed can be canceled with an error number (event handling return code) and an error text.

In order to process events, you must declare, in Visual Basic, the variable assigned to the business object using the keyword WithEvents. Note the following Visual Basic restrictions in this regard (see Visual Basic manual and Visual Basic on-line help for further information on programming with events):

● A WithEvents variable cannot be a general object variable, i.e. it cannot be declared with As Object. You must specify the class name in the declaration.

● A WithEvents variable cannot be declared with As New. The event source object has to be explicitly generated and assigned to the WithEvents variable.

● WithEvents variables cannot be declared in a standard module. They can only be declared in class modules, form modules and other modules that define classes.

● WithEvents variables cannot be data fields.

Event Description

Public Event BeforeSend(serviceObject As Object, ByRef returnCode As Long, ByRef returnMessage As String)

Activated before the next service is sent to the host application.serviceObject contains a reference to the service object whose data is to be transferred.You can, e.g. modify the send data or cancel the method with an error number (returnCode) and a message (returnMessage).

Public Event DataReceived(serviceObject As Object, ByRef returnCode As Long, ByRef returnMessage As String)

Activated when data has been received from a service.serviceObject contains a reference to the service object whose data was received.You can modify the receive data or cancel the method with an error number (returnCode) and a message (returnMessage).

Public Event NextFormat(ByRef formatName As String, ByRef returnCode As Long, ByRef returnMessage As String)

Activated when a format has been received.formatName contains the format name previously read with GetNextFormat().You can modify the format name or cancel the method with an error number (returnCode) and a message (returnMessage). You can intercept unexpected formats (e.g. following an openUTM restart) with this event and map them to a dummy service.



Example

In this example, the business object BoB1’s method M1 is started. The business object is defined as a form-global variable objX with WithEvents.

The objC host adapter is located externally in this example (i.e. it is neither method-related nor business object-related). This has no effect on the BizTransactions events.

● After data has been read, the data and the current communication properties are output.

● When the follow-up format has been read its name is also output.

Dim objC As BizTaConnection ' External host adapterDim WithEvents objX As Bob1 ' Business object with eventsPrivate Sub Form_Load() Set objC = New BizTaConnection ' Instantiate host adapterEnd SubPrivate Sub Command1_Click()Set objX = New Bob1 ' Instantiate business object with events! objX.LogFilename= App.Path+"\MyLog.txt" ' Specify logging medium objX.SetCommunicationServer objC ' Link host adapter to BOobjX.M1()End SubPrivate Sub objX_DataReceived(ServiceObject As Object,Returncode As Long, ReturnMessage As String) Debug.Print ServiceObject.ReceiveBufferToString Debug.Print ServiceObject.GetCommunicationPropertiesEnd SubPrivate Sub objX_NextFormat(FormatName As String, Returncode As Long, ReturnMessage As String) Debug.Print FormatName ' Output name of follow-up formatEnd Sub





8.4.2.1 Properties

The service classes have the following properties. The properties can be read but not written:

8.4.2.2 Methods

To improve performance some of the properties and methods are generated as Friend. This allows the business object class to access these methods with higher performance. Access from “outside” is not possible, however.

The following methods are Public (and can therefore be accessed from outside) for programming with the BizTransactions events BeforeSend, DataReceive and NextFormat:

Property Access Meaning

FormatName R FHS only. Name of the assigned FHS format

ReceiveLength R Number of characters transferred to the receive buffer

SendLength R Length of the send buffer

ServiceName R Name of the service

Method Description

Function GetFieldValue(ByVal fPos As IntegerByVal fLen As Integer) As String

Reads data from the receive buffer and returns the data as a string.

fPos Relative position of the field in the buffer

fLen Field length

Function ReceiveBufferTostring()As String

Passes the contents of the buffer as a string.

Function SendBufferToString() As String

Passes the send buffer contents as a string.




BizTaConnection is the common host adapter interface to the business objects. BizTaConnection is the ActiveX component for communication via the UPIC, 9750 and 3270 protocols.

8.4.3.1 Properties

Sub SetFieldValue(ByVal fPos As IntegerByVal fLen As IntegerByVal fValue As StringByVal convert As Boolean)


fPos Relative position of the field in the buffer

fLen Field length

fValue New value for the field

convert Specifies if the contents of the field are to be converted:



Property Access1 Meaning

CallerType R/W Identifies the calling program

Class R Name of the class: BizTaConnection

CommStatus R Describes the connection status. This property can assume the following values:CommStart Service is not signed on to the hostCommInitialize Connection was successfully establishedCommReset Connection terminatedCommSend Data can be sent to the serviceCommReceive Data can be received from the service CommNoData There is no more data available from the service

ComputerName R/W Computer with the calling program

ConnectionID R Returns an object that implements the adapter interface for low level communication

Format R/W Format name

Method Description



FormatIdObj R/W Object for format detection; the generated class must create and set this object if format detection is to be used

LocalName R/W BizTransactions dynamically generates a station name if you do not specify anything.

ReceiveLength R/W Length of the receive buffer

ServiceName R/W Name of the Service, maximum of 32 characters

UserName R/W Name of the caller (Windows name)

1 R: ReadW: Write

Property Access1 Meaning



8.4.3.2 Methods

Method Description

Function CheckConnection() As Boolean

Checks the status of the connection, in particular to see if the server host has terminated the connection. If the connection still exists, then the method returns True, otherwise it returns False.

Function GetAdapterLib(contype As BizTaServiceVersion)As String

Returns the path name for the protocol library used as a string. You can query the following protocols: BizTaEm9750, BizTaEm3270, BizTaUTMV3, BizTaUTMV4, BizTaUTMV5

Function GetCommunicationProperty(optname As String) As String

Returns the value of the optname connection property as a string. See also section “Connection properties” on page 343.

Function GetNextFormat(ByRef nextFormat As String, ByRef message As String[,status])As Boolean

Returns the name of the next format when – the base communication method returns format

names– the format was able to be identified by the format

detection. The net data is then returned during the next Receive() call.nextFormat Name of the follow-up formatmessage Messages of this methodstatus Status of the connection

Sub InitLog(ByVal logFileName As String)

Starts recording log information in the file logFileName.

Function Receive(ByRef receiveBuffer() As Byte,ByVal receiveBufferPos As Long,ByRef receiveBufferLen As Long,ByRef message As String,ByRef commStatus As String)As Boolean

Reads a maximum of receiveBufferLen bytes from the host and writes them in the receiveBuffer starting at position receiveBufferPos. The calling program (generated class) receives all incoming messages in the message parameter and the status of the connection in commStatus.

Function Send(ByRef sendBuffer() As Byte,ByVal sendBufferPos As Long,ByVal sendBufferLen As Long,ByRef message As String,ByRef commStatus As String)As Boolean

The calling program (generated class) passes the data of length sendBufferLen to be sent in the sendBuffer starting at position sendBufferPo. All incoming messages are returned to the calling program in the message parameter as well as the status of the connection in commStatus.



SubSetCommunicationProperties( ByVal values As String) As Boolean

Performant setting of the connection properties. The calling program (generated class) passes a compact string of the form Param=value;Param=value to BizTaConnection.This string is taken apart and the individual values are stored in the corresponding instance variables.values Connection properties of the calling

program, see section “Connection properties” on page 343

Function SetCommunicationProperty(optname As String,optValue As String)

Sets the value of the optname connection property, see section “Connection properties” on page 343.

Sub Sleep(milliseconds As Long)

Waits for the specified number of milliseconds.

Function StopCommunication(ByRef message As String,ByRef commStatus As String)As Boolean

Terminates the connection. A message is returned to the calling program (generated class) in the message parameter and the new status of the connection is returned in the commStatus parameter.

Function ToASCII(source As String)As String


Function ToEBCDIC(source As String)As String

Only for communication with openUTM applications: Converts the data to be sent. You should only use this method when no automatic conversion takes place. See also section“Conversion table for the ToASCII and ToEBCDIC functions” on page 394.

Function UseAdapterClass(className As String)As Boolean

Sets the host adapter as an ActiveX component.You enter the class name without path specification in className.

Function UseAdapterLibrary(conType As BizTaServiceVersion,libPath As String,initFctName As String)As Boolean

Sets the host adapter as a DLL.conType contains the required protocol. You can specify the following values: BizTaEm9750, BizTaEm3270, BizTaUTMV3. BizTaUTMV4, BizTaUTMV5, BizTaServiceOther.You can specify another host adapter with BizTaServiceOther. If you specify BizTaOther, then you must specify the path name of the initialization function of the new host adapter in libPath and its name in initFctName. These parameters are ignored for other protocols.

Method Description





The table of connection properties for the 9750 and 3270 protocols can be found on page 307, and the connection properties for the UPIC protocol on page 308.

Sub WriteLog(line As String)

Writes a line to the log file of the business object.

Method Description


9 Diagnostic toolsBizTransactions offers detailed logging methods for supporting error diagnosis when errors occur.

The following components record information for diagnostic purposes when a BizTransactions application is running:

● the business object

● the host adapter

9.1 Business objects

If you set the Variant option to Debug when you generate a business object (see section “Generation options” on page 128), then the following information is logged when the busi-ness object runs:

● All method and service node calls

● All intermediate code statements

● Error information in the Catch block

In addition to the business object information, you can also write your own information to the central log. You do this using the WriteLog statement which allows you to compile the information yourself. You can insert the WriteLog statement with BizTransactions Studio. In BizTransactions Studio, you can enter statements in the code in order to write a text of your choice to the log file (see section “Editing statements” on page 187).

If you set Variant to Release when you generate a business object, only the explicit WriteLog calls are logged at runtime.

The scope and destination of logging can be set differently depending on the generated language. The details are presented in the following sections.


Business objects Diagnostic tools

9.1.1 Java

Java business objects can write logging information while running if they were generated as debug variants or contain WriteLog explicit calls. The destination and extent for logging is specified in the LogFilename property of the business object. You can assign the following values to LogFilename:

"" Logging is disabled (default).

"path" Logging information is written to the specified file. id.TXT is automatically appended

to the passed path name without suffix where id is a unique generated number which ensures that instance-specific log files are created.

If you specify a file without a path, the log files are written to the directory for trace and log files (see also section “Logging settings” on page 362). If the log is to be written to another directory, you must specify the path explicitly in LogFilename.

BizTaConnection.LogEvent Records logging information to the central log file of the BizTransactions runtime system that you have specified with BizTransactions Administration, see section “Logging settings” on page 362.

Example of the contents of a logging file

Loggingfile created: 15-May-02 15:56:31 for BizTaConnection(03.00.01)•••••••••••••••••••• ProcessId= 116|ThreadId= 162116|162 15:56:31 |Start format116|162 15:56:32 |Supply SignOn/KDCSGNO input data

Logging methods

Java business objects inherit the the following logging methods from the higher-level class BizTaBusinessObject:

● initLog() - Start logging

The initLog() method starts logging in the file that you specified with the LogFilename property.

public void initLog()


Diagnostic tools Business objects

● get/setLogFilename() - Set or query the name of the logging file

The getLogFilename() method returns the name of the logging file, the setLogFilename() and the setLogFilename() method sets the file name for logging.

● writeLog() - Write special messages directly to the logging file

The writeLog() method writes a message to the log file that you specified with the logFilename property.

Line optional character string

public String getLogFilename()

public void setLogFilename (String filename)

public void writeLog (String Line)



9.1.2 .NET

The Trace class is used in .NET business objects to output diagnostic messages and WriteLog messages. The Trace class routes all messages to the trace listeners in the .NET Framework. These listeners decide how a method is to be further processed.

The .NET Framework provides three traces listeners as standard:

● DefaultTraceListener routes messages to the debugger

● EventLogTraceListener writes messages to the system event log

● TextWriterTraceListener writes messages to a file

Controlling output

You use the system class TraceSwitch to control output. TraceSwitch specifies the trace level and can assume the following values:

If you set the Variant option to Release when generating the business object (see section “Generation options” on page 128), then the class generator only generates trace output for WriteLog calls and syntax errors, array errors and exceptions captured in a catch block.

TraceSwitch No. Description

Off 0 WriteLog calls

Error 1 – WriteLog calls– All syntax errors, array errors and captured exceptions in a

Catch block

Info 3 – WriteLog calls– All syntax errors, array errors and captured exceptions in a

Catch block– Information about the start of a method, a service node

and potential successors in GetNext if Variant = Debug is set.

Verbose 4 – WriteLog calls– All syntax errors, array errors and captured exceptions in a

Catch block– Information about the start of a method, a service node

and potential successors in GetNext if Variant = Debug is set.

– All statements if Variant = Debug is set



You specify whether, where, how and at what level traces are to be output via the configu-ration file. Here you can assign BizTaTrace a value between 0 and 4.

Example

<add name="BizTaTrace" value="1"/>

In this example, the trace level for BizTaTrace is set to 1 (i.e. Error).

Configuration file for programs

In the case of programs, the configuration file is expected to be present in the \Bin subdi-rectory under the name Programname.exe.Config.

If you work with Microsoft Visual Studio then the configuration file is present in the source directory under the name App.Config. When run in Visual Studio, this file is copied to the \Bin subdirectory under the name Programname.exe.Config. Any changes that may have been made are then overwritten.

You will find an example configuration file in the BizTransactions installation directory under \Bin\BizTaNetGui\Bin\BizTaNetGUI.exe.config.

Example: configuration file for a program (.exe)


<configSections><section name="exceptionManagement" type="Net.fsc.BizTransactions.ExceptionManagement.

ExceptionManagerSectionHandler,Net.fsc.BizTransactions.ExceptionManagement" />

</configSections><exceptionManagement>

<publisher assembly="Net.fsc.BizTransactions.ExceptionManagement"type="Net.fsc.BizTransactions.ExceptionManagement.DefaultPublisher"logName="MyApp Exception Log" applicationName="My Application" />

</exceptionManagement><system.diagnostics>

<switches><add name="BizTaTrace" value="4"/>

</switches></system.diagnostics>

</configuration>

In this example, the trace level for BizTaTrace has been set to 4 (i.e. Verbose). No listener is connected since the lines have been commented out. This means that although a lot of information is stored in the trace (trace level 4), nothing is output because no listener is present. To output the information, it is necessary to assign a corresponding listener.

At the top of the example (configSections and exceptionManagement elements), you can see the default configuration for the Microsoft Exception Management Application Block (see section “BizTaException” on page 331).

Configuration file for web applications

In web applications, the configuration file has the name Web.Config. After configuration, it is searched for in the following order

1. Machine.config (example: C:\WIN\Microsoft.NET\Framework\v1.1.4322\CONFIG)

2. \inetpub\wwwroot\Web.Config

3. virtual directory of the web application\Web.Config

Example: configuration file for a web application


<configSections><section name="exceptionManagement"

type="net.fsc.BizTransactions.ExceptionManagement.ExceptionManagerSectionHandler,

net.fsc.BizTransactions.ExceptionManagement" /></configSections><exceptionManagement>

<add key="mode" value="off"/></exceptionManagement><system.web>

<compilation defaultLanguage="vb" debug="true" /><customErrors mode="RemoteOnly" /><authentication mode="Windows" /> <authorization>

<allow users="*" /> </authorization><trace enabled="true" requestLimit="10" pageOutput="false"

traceMode="SortByTime" localOnly="true" /><sessionState

mode="InProc"stateConnectionString="tcpip=127.0.0.1:42424"sqlConnectionString="data source=127.0.0.1;user id=sa;password="cookieless="false" timeout="25"

/><globalization requestEncoding="utf-8" responseEncoding="utf-8" />

</system.web><system.diagnostics>

<switches><add name="BizTaTrace" value="4"/>

</switches></system.diagnostics>

</configuration>



9.1.3 Visual Basic

ActiveX business objects can write logging information while running if they were generated as debug variants or contain explicit WriteLog calls. The destination and extent for logging is specified in the LogFilename property of the business object. You can assign the following values to LogFilename:

"" Logging is disabled (default).

"path" Logging information is written to the specified file. -pid-tid.TXT is automatically

appended to the passed path name (without a suffix) where pid is the current process ID and tid is the current thread ID

If you specify a file without a path, the log files are written to the directory for trace and log files (see also section “Logging settings” on page 362). If the log is to be written to another directory, you must specify the path explicitly in LogFilename.

BizTaConnection.LogEvent Writes logging information to Windows event log. In Visual Basic, it is necessary to create an instance of BizTaConnection.

Example of the contents of a log file

Loggingfile created: 15-May-02 15:56:31 for BizTaConnection(03.00.01)•••••••••••••••••••• ProcessId= 116|ThreadId= 162116|162 15:56:31 |Start format116|162 15:56:32 |Supply SignOn/KDCSGNO input data



Controlling logging in the program

When executing business objects, the ActiveX component BizTaConnection is accessed internally. BizTaConnection is an ActiveX component that can also be programmed directly (see also section “BizTaConnection” on page 281 for more information) which means that it can be used to control logging:

● InitLog - start logging

This function starts the logging process. The loggingFileName parameter can be assigned the same values as the LogFilename property:

● WriteLog - write specific messages directly to the logging file

This function allows you to write specific messages to the logging file specified in InitLog.

line Any character string.

BizTaConnection.InitLog(ByVal loggingFileName As String)

BizTaConnection.WriteLog (line As String)


Host adapters Diagnostic tools

9.2 Host adapters

Logging for the host adapters can be very extensive depending on the logging settings. For example, you can log all messages exchanged and all communication calls (Communication Trace option set to All), although you should only use this setting if there are problems communicating with host applications because it significantly reduces the performance.

The scope and destination of the log is controlled with the BizTransactions Administration in the Settings tab via the following options:

● Communication Trace

● Trace and Log Directory

The host adapter records logging information in the file CTCommPpidTtid.trc. pid stands for the current process ID and tid stands for the current thread ID.

You can specify the directory for the trace files in BizTransactions Administration under Settings/Trace and Log Directory. The default setting for this directory is the directory currently set as the TEMP directory on the computer.

Communication with UPIC applications

If you have specified the value All in the Administration in the Settings tab for the Communication Trace option, then the BizTransactions runtime system records the UPIC trace in the files UPICTtid.upt and UPICUtid.upt in addition to the communication trace in CTCommPpidTtid.trc.

The following files are relevant for diagnosing UPIC communication problems:

● Communication trace

● UPIC trace

● Information on the caller (class, ...), i.e. information on the application

Communication with terminal applications at runtime

The following files are relevant for diagnosing emulation communication problems:

● Communication trace

● Session trace file that you have created with BizTransactions Administration, see the section “Recording sessions” on page 364

● Information on the callers (class, ...), i.e. information on the application


Diagnostic tools Host adapters

Troubleshooting

Proceed as follows when problems arise during communication with the host application:

Ê Switch on the Communication Trace in the Settings tab in BizTransactions Administra-tion. You should note that an UPIC trace is only written if you set Communication Trace to All.

Ê Check the communication data of your host application, for example the host and partner names.

Ê Check the communication files on the PC and enter any missing data in the Hosts file.


Return codes of business object methods Diagnostic tools

9.3 Return codes of business object methods

You can terminate methods with return codes you have defined using the ExitMethod statement (see the section “Editing statements” on page 187). Use values greater than the value of BizTaBoFirstUserError for the return codes (i.e. values > 1000) because BizTransactions reserves the following return codes:

.NET/ActiveX return code Java return code Value Description

BizTaBoNoError NO_ERROR 0 No error, OK

BizTaBoFatalError FATAL_ERROR 901 Runtime error

BizTaBoSendError SEND_ERROR 902 Send error

BizTaBoReceiveError RECEIVE_ERROR 903 Receive error

BizTaBoGetNextError GETNEXT_ERROR 904 Error in GetNextFormat

BizTaBoSequenceError SEQUENCE_ERROR 905 Incorrect / unexpected format

BizTaBoStopCommunicationError STOP_COMMUNICATION_ERROR 906 Error in StopCommunication

BizTaBoConnectionLost CONNECTION_LOST 907 Connection lost

BizTaBoConnectionLostRight-AfterSignon

CONNECTION_LOST_RIGHT_AFTER_SIGNON

908 Connection lost directly after calling the BizTa_SignOn method before another method is called

BizTaBoSyntaxError SYNTAX_ERROR 909 Error during syntax check

BizTaBoRecursionError RECURSION_ERROR 910 Specified maximum for the counter of a service was exceeded

BizTaBoArrayIndexError ARRAY_INDEX_ERROR 911 Array index out of bounds

BizTaBoCommunicationServer-AlreadySet

COMMUNICATION_SERVER_ALREADY_SET

912 Host adapter is already assigned

BizTaBoNoCommunicationServer NO_COMMUNICATION_SERVER 913 Host adapter is not assigned yet

BizTaBoInvalidFieldLength INVALID_FIELD_LENGTH 914 Invalid field length

BizTaBoLogError LOG_ERROR 915 Error during logging

BizTaBoConnectionInitError CONNECTION_INIT_ERROR 916 Error while opening connection

BizTaAlreadyDisposed 917 Only for .NETThe business object has already been released, i.e. the Dispose method has already been called. All resources have been released

BizTaBoFirstUserError FIRST_USER_ERROR 1000 First user-defined error


10 BizTransactions AdministrationWith BizTransactions Administration you can administer and monitor the elements needed when working with business objects (see section “Business object class” on page 276). You can

● set the type and the scope of the BizTransactions runtime system logging, see page 362

● control the recording and replaying of sessions, see page 364

● display, filter and sort messages from all or from selected Java business objects, see page 367

The administration functions are executed by a server running in the background. When you close the command window, you also terminate BizTransactions Administration

BizTransactions Administration provides an HTML user interface which is displayed by the standard browser configured in the Windows system.


Starting Administration BizTransactions Administration

10.1 Starting Administration

BizTransactions can process the following parameters when the administration server is started:

port-number Specifies the port via which BizTransactions Administration communicates.

Internally, BizTransactions Administration uses two ports: one for outbound requests and the other for inbound requests. The second port number is the first port number +1.Default setting: port numbers 8181 and 8182.

If you want to run multiple BizTransactions Administration instances in parallel, make sure that the port number values differ by at least 2.

configuration-directory The set values are saved in this directory. Under all operating systems, the BizTransactions runtime system uses the user’s HOME directory for this purpose. When BizTransactions Administration is started, it is possible to specify another directory by means of this parameter with the result that the settings can be modified for IDs other than the local login ID.

The set configuration directory is displayed for verification purposes in the BizTransactions Administration HTML pages.Default setting: the user’s home directory.

i


BizTransactions Administration Starting Administration

10.1.1 Windows

Under Windows, you can start the administration server for BizTransactions Administration:

● Using the commandStart/Programs/BizTransactions 7.0/BizTransactions Administration

BizTransactions Administration is automatically displayed in the browser.

● Via the command startadm.bat

Proceed as follows:

Ê Open the Windows command prompt.

Ê In the general installation directory, change to the directoryCommon Files\FujitsuSiemensComputers\BizTransactions70\bin

Ê Call the file startadm.bat with the required port and a configuration directory:

startadm.bat [port-number [configuration-directory]]

Since the browser usually starts up faster than the server, you may need to refresh the HTML page.i


Starting Administration BizTransactions Administration

10.1.2 Solaris

Under Solaris, you start the administration server for BizTransactions Administration with the command:

java -native -classpath /opt/BizTrans/7.0/lib/bizta.jar de.siemens.bizta.admin.Server [-p port-number [-d configuration-directory]]

You can then display the BizTransactions Administration start page in a web browser by specifying the following URL:http://host-name:port-number/settings.html

Here, host-name is the name of the host on which the administration server is running. If the browser and administration server are running on the same host, host-name will have to be replaced, for example, by localhost.

If you specified a port other than the default when starting BizTransactions Administration then you must also specify it here.

If you do not specify any port number then the default is also used here:http://host-name:8181/settings.html


BizTransactions Administration The user interface

10.2 The user interface

The BizTransactions Administration user interface consists of several HTML pages that are displayed by a browser. All the pages all have the following layout:

Figure 30: BizTransactions Administration

The menu on the left-hand side of the screen provides an overview of the functions provided by BizTransactions Administration. The highlighting (arrow) shows you which menu you have just selected.

To the right of the menus is the work area in which you can edit the settings. The Settings menu is opened when you start BizTransactions Administration and is displayed on the right-hand side of the screen.

Work area

ActiveMenu


Logging settings BizTransactions Administration

10.3 Logging settings

The Settings menu is the first page displayed when BizTransactions Administration is started. Here you can

● set the type and scope of the information to be logged and

● select the language in which Administration is displayed (German or English)

Figure 31: BizTransactions Administration - Settings

The value that is currently set for each setting is shown under Current Value. You can enter new values in the fields below Change To.

The values become effective after you click on the Apply Changes button.

When you use the business objects within the Internet Information Servers (IIS), they run under the user ID Internet Guest (IUSR). This means that you must set the rights for the directories and files you assign here to IUSR.

Central Log File The name of the central log file for Java business objects. If you specify a path, then the log file will be stored in the directory entered for Trace and Log Directory. Java business objects write to this file if you have set the LogFilename to the value BizTaConnection.LogEvent (see also section “Business objects” on page 345 for more information).

i


BizTransactions Administration Logging settings

Communication Trace Specifies what will be logged. You can select from the following values:

The communication trace is stored under the name CTCommPpidTtid.trc. pid stands for the current process ID, and tid stands for the current thread ID.

CTCommPpidTtid.trc will be written to for as long as the corresponding thread is active. When the file becomes larger than 10 MB, then it is renamed to CTCommPpidTtida.trc and a new file named CTCommPpidTtid.trc is created.

Trace and Log Directory Directory for the communication trace. If you have entered only a file name without a path in the Central Log File text box, then the central log file is also saved in this directory.Default: the system’s TEMP folder.

Admin Language Sets the language for BizTransactions Administration:– English– German

Screen Data Contents of the data buffer sent and received, and the UPIC trace as well for UPIC business objects.

All Contents of the data buffer sent and received and all communi-cation calls, and the UPIC trace as well for UPIC business objects.

Off Error messages


Recording sessions BizTransactions Administration

10.4 Recording sessions

In the Record and Replay Sessions menu you can control how sessions are recorded and replayed.

You can record the data exchange with a host application with which you are communi-cating through an emulation session in a file. This recording can be replayed at a later time, even if there is no connection to the host application. This can be very useful for error diagnosis, for example.

Communication with a host application can also be replayed from one file and recorded in another at the same time. Make sure that two different files are used for replaying and recording the information in this case.

When a business object that accesses a host application through an emulation is subse-quently started at runtime, a check is carried out when the connection is established as to whether the communication with the host application is to be recorded or replayed:

● If the communication is to be recorded, then it is stored in the record file that you specified for the host application in question. Just one session with the specified host application is recorded in the file, starting when the connection is established and ending when it is closed down again. When a new connection is established, the record file is overwritten.

● When you want to replay a session, the communication with the host application that was saved in the record file is replayed, but no connection to the host application is established.


BizTransactions Administration Recording sessions

Figure 32: BizTransactions Administration - Record and Replay Session

Record sessions for the following host applications Shows the host applications for which recording is currently activated. The file in which the session is recorded is shown next to the application name under Record sessions to the following files.

Change recording for the following host applications You specify with the options in the list what is to happen with the corresponding host applications:

Add Adds another host application to be recorded in the session. Enter the name of the host application in the relevant input field. Specify the file name in the Use the following record file field.

As the name of the host application, you should enter the value that you specified under Partner in BizTransactions Studio. This value is also used for 3270 applications (see section “Creating a new host application” on page 111).

Remove Removes the selected host application from the list of applications to be recorded. Enter the name of the host application whose session is no longer to be recorded in the relevant input field.

Clear all Removes all applications from the list of applications to be recorded. No further entries need to be made.


Recording sessions BizTransactions Administration

The procedure is similar for replaying sessions.

Replay sessions for the following host applications Shows for which host applications the replay function is currently activated. The file from which the session is to be replayed is next to the application name under Replay sessions for the following files.

Change replay for the following host application With the options in the list you specify what is to happen with the corresponding host applications:

Add Adds another host application for replay. Enter the name of the host appli-cation in the relevant input field. Enter the file name in the Use the following record file field.

As the name of the host application, you should enter the value that you specified under Partner in BizTransactions Studio. This value is also used for 3270 applications (see section “Creating a new host application” on page 111).

Remove Removes the selected host application from the list of applications to be replayed. Enter the name of the host application whose session is no longer to be replayed in the relevant input field.

Clear all Removes all applications from the list of applications to be replayed. No further entries need to be made.

The changes only take effect when you click on the Apply Changes button.


BizTransactions Administration Viewing the central log file

10.5 Viewing the central log file

The Java business objects whose LogFilename property has the value BizTaBusinessObject.LogEvent store their log information in the central log file. When you select the View Central Log menu item, the contents of this file are displayed. You can select criteria to filter or sort the messages.

The information displayed depends on the file. If the log file is empty or if it does not exist, then nothing is displayed.

Figure 33: BizTransactions Administration - displaying messages

The following sort and filter criteria are provided for message output:

Date The chronological order in which the messages are displayed. You can select – Latest first or– Oldest first

Component Business objects whose messages are to be displayed. You can select:– individual business objects or – all business objects.

Count Defines how many messages are displayed. You can choose between 10, 100 or 500.

The messages are resorted or filtered when you click on Filter.


Terminating Administration BizTransactions Administration

The table contains the following information:

Date Date on which the message was generated

Time Time at which the message was generated

Component Name of the business object that generated the message

Host Computer on which the host application runs, the business object communicates with.

Service Service that caused the message

Message Message text

10.6 Terminating Administration

Selecting Exit Admin terminates BizTransactions Administration.

This does not automatically close the browser, but if you want to make further settings for the BizTransactions runtime system you have to restart the administration program.


11 Using business objects

11.1 Business objects in Microsoft Visual Studio .NET

This section describes the easiest way of integrating business objects into Microsoft Visual Studio .NET.

The more precisely you have described your business object in BizTransactions Studio (name and description of properties, methods and method parameters, see section “Declaring business objects and their interfaces” on page 123), the better the support you will receive at design time in Microsoft Visual Studio.

11.1.1 Transferring business objects to Microsoft Visual Studio .NET

To transfer a business object to the Microsoft Visual Studio .NET Toolbox:

Ê Choose the Extras menu and select the commandAdd/Remove Toolbox Items

or

Ê Choose the command Add Tab and drag and drop the filebusiness object.dll from the Windows Explorer into the new tab.

The business object can then be used as a component.

Ê Drag and drop the business object from the Toolbox into the required project.

i


Business objects in Microsoft Visual Studio .NET Using business objects

Ê If necessary, edit the business object’s properties.

In the properties dialog, you can edit the properties visually at design time. The properties are checked as at runtime.

You can edit the properties of a class or of a class array. The code corresponding to the language in question is generated automatically.

Properties that are defined as WriteOnly or as ReadOnly are not displayed and cannot be edited.

11.1.2 Configuring properties

You can configure a business object’s properties in such a way that their values are taken from the configuration file.

Ê To do this, choose Advanced under Dynamic Properties.

If you are working with Microsoft Visual Studio .NET, the configuration file is located in the source directory under the name App.Config. When run in Visual Studio, this file is copied to the project’s \Bin subdirectory under the default name program-name.EXE.Config.

When this copy operation is performed, any changes that have already been made are overwritten.

Example for generated code

Friend WithEvents BankBoAccounts1 As BankBoAccounts.BankBoAccounts<System.Diagnostics.DebuggerStepThrough()> Private Sub InitializeComponent()Dim configurationAppSettings As System.Configuration.AppSettingsReader = New System.Configuration.AppSettingsReader()Me.BankBoAccounts1 = New BankBoAccounts.BankBoAccounts()

'BankBoAccounts1Me.BankBoAccounts1.GotoBank = "201"Me.BankBoAccounts1.Host = CType(configurationAppSettings.GetValue("BankBoAccounts1.Host",

GetType(System.String)), String)Me.BankBoAccounts1.Kdcsign =

CType(configurationAppSettings.GetValue("BankBoAccounts1.Kdcsign", GetType(System.String)), String)

Me.BankBoAccounts1.LocalName =CType(configurationAppSettings.GetValue("BankBoAccounts1.LocalName", GetType(System.String)), String)

Me.BankBoAccounts1.Partner = ""Me.BankBoAccounts1.ReceiveTimer = 120

i

i


Using business objects Business objects in Microsoft Visual Studio .NET

With this configuration file, you can supply the values for the properties in the example above.

<?xml version="1.0" encoding="Windows-1252"?><configuration>

<appSettings><add key="BankBoAccounts1.Host" value="system1" /><add key="BankBoAccounts1.Kdcsign" value="HANS" /><add key="BankBoAccounts1.LocalName" value="(None)" />

</appSettings></configuration>

11.1.3 XML documentation

When you generate a business object in BizTransactions Studio, the file Business Object.xml is generated in the directory class-directory\host-application\business object\NET\Bin (see section “Generation results for .NET” on page 132).

This file contains the XML documentation for the business object. It contains XML comments on all the built-in methods and properties as well as on the methods and properties that you have defined.

If you incorporate a reference to the business object in a project in Microsoft Visual Studio .NET, then this XML file is automatically copied to the project’s \Bin subdirectory alongside the business object DLL.

If you then view the business object in the object browser, all the method and parameter comments that you have specified in BizTransactions Studio are displayed. You also receive additional assistance on methods and parameters during coding.


Loosely coupled asynchronous web calls Using business objects

11.2 Loosely coupled asynchronous web calls

In the case of short-lived connections with relatively long-running requests to the host appli-cation, the request/reply model from the mobile client to the back-end host is no longer possible if the processing of the request at the host application takes longer than the fault-free connection time. A business object must also operate the host application indepen-dently during periods of interruption and transfer as many results as have accrued to that point during the short connection time available.

The BizTransactions concept described below fulfills these requirements: in a loose cou-pling, a request is submitted and the results are retrieved later.

Advantages of loosely coupled asynchronous requests

● Faster responses if the caller does not need the result immediately. If the client submits multiple requests, the total runtime is equal to only that of the slowest method.

● Low web server load because the actual business object method runs offline, thus reducing the load placed on the web server. Load distribution in a web farm is possible.

● Error tolerance on server failure: since no permanent connection is required between the client and the web server (store and forward), the request can survive a temporary failure of the connection to the server, i.e. an offline mode is possible.

● Request submission and result retrieval (including on different platforms) can be performed with different programs. This means that a mixture of Java and .NET is possible. Mobile clients that access a Java web service can, for example, be developed with the .NET Compact Framework.

● This solution can be used both in fat (or smart) clients (e.g. Windows programs in Microsoft Office) and in web applications (e.g. WebTransactions).

● It is also possible to process intermediate results.

● This solution constitutes an important element in workflow scenarios.


Using business objects Loosely coupled asynchronous web calls

Problems with loosely coupled asychronous requests

● No automatic notification is possible when data becomes available.

● Under certain circumstances, the results of a request may never be retrieved (obsolete results).

How loosely coupled asynchronous requests run

The figure below illustrates a mobile client which calls a business object method with a relatively extensive runtime via a web service. The connection is interrupted during the method call. As a result of this interruption, the client does not receive any data.

Figure 34: Interruption of connection during the method call

This problem can be avoided if the submission of the request is separated from the transfer of the result. This solution is presented in the figure below:

Figure 35: Request submission separate from transfer of result

In the first step, the request is started. This request runs in the web server as a “one-way web method”. This means that as soon as the web server has deserialized the input message, but before the XML web service method is called, the server returns an HTTP 202 status code (Accepted). The client receives no confirmation as to whether the web server has successfully processed the message. No return values or Out parameters can be assigned to unidirectional methods.



This web method contains only input parameters (In). The business object is instantiated in the web service and the required method is called.

In the business object, intermediate results may be written to the container (e.g. a cache object or message queue), for example when a recursive format is worked through. At the end of the method, the final results are written to the container (see section “Storing (inter-mediate) results” on page 383).

The client then retrieves the results. This web method contains the output parameter (Out). It returns an intermediate result or the final result. This method can be called repeatedly until either the final result is present or the call is rejected with an error.

Making host application data available to multiple clients

The technique described in section “How loosely coupled asynchronous requests run” on page 373 can also be used, for example, to make the data from a host application available to multiple clients:

Figure 36: Multiple clients retrieve the results and further process these

In the first step, the request is started. The business object continuously queries data from the host application and stores the (intermediate) results in the web server.

Any number of clients can retrieve the current results and then further process them. In this case, all the participants must use the same request ID.

This scenario could be used, for example, to give multiple clients read access to a host application’s data.



11.2.1 Criteria for generation

Loosely coupled asynchronous web service calls are generated for JAVA and .NET if

● a method with the name Query has been defined in the business object and this method has the following signature:

– The name of the method is Query.

– Any number of input parameters (In) may be present. These input parameters may be of type Boolean, Long, Double, Date and String. Arrays are not permitted.

– There must be precisely one output parameter (Out) of type Class. This output parameter must be defined as an array and must be the last parameter in the Query method’s parameter list.

– The output parameter’s class may contain properties of type Boolean, Long, Double, Date and String provided that these are not arrays.

● the option QueryWebService was active when the business object was generated (see section “Generation options” on page 128).

11.2.2 Business object

If a “write intermediate results” statement has been created in the code of a business object’s Query method and if this method fulfills the corresponding criteria, then the business object generates an IntermediateResult event at this point (see section “Criteria for generation” on page 375).

This event is processed in the associated web service and the intermediate result is stored so that it can be called there (see section “Writing intermediate results” on page 386).

The developer of the business object must insert the “write intermediate results” statement at an appropriate position in the Query method’s code.



11.2.3 Web service

When a web service is generated, the associated methods BizTaGetID, Query_Start, Query_Read, Query_Status and Query_Clear are inserted if a business object method with the name Query exists and this method fulfills the corresponding criteria (see section “Criteria for generation” on page 375).

In Java, an additional class Business ObjectQueryManager is generated. This is made available as a web service under the URL Business Object URLQueryManager.

● In Tomcat:

The BusinessObjectURL isTomcat Root URL/Business Object/Business Object

The URL for the Query web service is thereforeTomcat Root URL/Business Object/Business ObjectQueryManager

Example

If you entered http://localhost:8080 in the field Tomcat Root URL during installation, then the URL will behttp://localhost:8080/myBO/myBOQueryManager

● In the case of a local stand-alone OC4J server:

The BusinessObjectURL ishttp://localhost:port/BizTA/Business Object

The URL for the Query web service is thereforehttp://localhost:port/BizTA/Business ObjectQueryManager

Example

If the OC4J server uses port 8888, the URL ishttp://localhost:8888/BizTa/myBOQueryManager

This web service possesses the methods described below.



11.2.3.1 BizTaGetId method

Java

public String BizTaGetID() throws RemoteException;

.NET

Public Function BizTaGetID() As String

This method returns a unique request ID. The method call is optional. You can also use your own unique request ID.

You must use this request ID when you start the request with Query_Start and when you retrieve the results with Query_Read. It is also possible that multiple clients may retrieve data with the same request ID.

11.2.3.2 Query_Start method

Java

public void Query_Start (String ID, datatype inparam1, ... , datatype inparamn) throws RemoteException;

.NET

Public Sub Query_Start(ByVal ID As String, ByVal inparam1 As datatype[.., ByVal inparam-n As datatype])

This request runs in the web server as a “one-way web method”. The request therefore runs asychronously: it is simply accepted and started. However, the caller can immediately continue processing immediately without waiting for a result. This method contains only the request ID and the input parameters (In) of the Query method. The business object is instantiated and the Query method called in the web service.

In the business object, intermediate results may be written to the container (e.g. a cache object or a message queue), for example when a recursive format is worked through.

At the end of the method, the final results are written to the container.



11.2.3.3 Query_Read method

Java

public QueryResult Query_Read (String ID, resultClass rc) throws RemoteException;

.NET

Public Function Query_Read(ByVal ID As String, ByRef myTable() As table) As RC

This web method receives the request ID and the data structure used for the results of the Query method, i.e. the Query method’s output parameter (Out).

The value passed in the 2nd parameter is only needed for the recognition of the data structure that is returned in the request status in the output table.

The method returns request status information (see section “Request status information” on page 379) which, among other things, contains an intermediate result or the final result of the specified request’s Query method. It can be called repeatedly until either the final result is present or the call is rejected with Status = Error.

11.2.3.4 Query_Clear method

Java

public void Query_Clear (String ID) throws RemoteException;

.NET

Public Sub Query_Clear(ByVal ID As String)

This web method deletes the buffered intermediate results of the specified request.

11.2.3.5 Query_Status method

Java

public QueryResult Query_Status (String ID) throws RemoteException;

.NET

Public Function Query_Status(ByVal ID As String) As RC

This web method returns request status information (see section “Request status infor-mation” on page 379) for the specified request but without intermediate results (the corre-sponding component of the request status information is void).



11.2.3.6 Query_ReadDataset method

For .NET only

Public Function Query_ReadDataset(ByVal ID AsString [,ByVal In1 As x ...], _ByRef RetDataset As DataSet) As RC

The functionality of this method corresponds to that of the Query_Read method (see page 378). However, instead of the class array RetClassArray, it returns a DataSet object. The data is only returned in RetDataSet. ClassArray in RC is Nothing. This method call is only of use for .NET clients.

11.2.3.7 Request status information

In Java, the request status information is administered in the classde.siemens.bizta.runtime.QueryResult and in .NET it is administered in a structure.

Java

Field Description

public int returnCode QueryResult.rcIntermediateResult An intermediate result is present

QueryResult.rcFinalResult A final result is present

QueryResult.rcNoResult The request has been started but no (intermedi-ate) result is present as yet

QueryResult.rcErrorNoResult The request has been cancelled with an error. See errorMsg

public String errorMsg Only relevant if return code = rcErrorNoResult

public int numRows1

1 The values for numRows and lastArrIndex may differ if you explicitly specify the size of the output table in the business object but have not yet written the whole table.

Number of rows in the result table

public int numIntResults Number of intermediate results

public lastArrIndex1 Last valid row in the result table (see numRows)

public GregorianCalendar timeStamp

Creation time of the (intermediate) result: date / time

public Object retValues[]2

2 At runtime, the array retValues always contains instances of a subclass of Object, namely the business object-specific class of the output parameter. This is the class whose name was abstractly specified as resultClass in the Query_Read method.

Output table



.NET

11.2.3.8 Retrieving the (intermediate) results

In Visual Basic .NET, you can assign results with WithEvents or AddHandler or remove them again with RemoveHandler. You can use the IntermediateResult event to query the inter-mediate results of a business object’s or web service’s Query method.

You will find a detailed example in the tutorial Using BOs.doc, which is supplied with BizTransactions. The file can be found in the BizTransactions installation directory under Examples\Documents\En\ExampleUPIC\Tutorial Using BOs.doc.

Field Description

ReturnCode As ReturnCodes IntermediateResult An intermediate result is present

EndResult A final result is present

NoResult The request has been started but no (intermedi-ate) result is present as yet

ErrorNoResult The request has been cancelled with an error. See errorMsg

ErrorMessage As String Only relevant if return code = ErrorNoResult

NbOfRows As Integer1

1 The values for NbOfRows and LastArrayIndex may differ if you explicitly specify the size of the output table in the business object but have not yet written the whole table.

Number of rows in the result table

IntermediateResultNb As Integer Number of intermediate results

LastArrayIndex As Integer1 Last valid row in the result table (see NbOfRows)

CurrDate As Date Creation time of the (intermediate) result: date / time

ClassArray() As SimpleClass Output table



Time sequence and dynamic behavior of the call

The diagram below illustrates the time sequence and dynamic behavior of a call to the one-way web method Query_Start.

Figure 37: Sequence and behavior of Query_Start calls

Caller Web service Web service (one-way)

Business object

BizTaGetID=BizTaGetID()

ID

Query_Start(ID, InputParam1, InputParamN)Instantiate BO

Query_Read Retrieve (intermediate) result

RC: No result yet

Query_Read

RC: Intermediate result

Query_Read

RC: Final result

Intermediate result

Final result

The web method Query_Start is a one-way method,i.e. it returns directly to the caller.

Writing intermediate resultsis optional.



The sequence of messages and the duration of the triggered actions can be explained in terms of a vertical time axis:

● The caller fetches a request ID from the web service. The web service is instantiated, the method BizTaGetID is executed and the request ID is returned.

● The caller then starts the one-way web method Query_Start. The web service is instantiated and the method is called. This instantiates the business object and calls the business object method Query. This call takes some time. However, the web method immediately returns control to the caller. In the meantime, the business object method supplies intermediate results which the web service stores in a container (e.g. a cache object or message queue).

● After calling the one-way web method Query_Start, the caller regains control.The caller therefore does not wait for the end of the method call but instead attempts to retrieve a result. Since no result is as yet present, the return code initially contains the value NoResult.

● On the second attempt, an intermediate result is supplied(return code = IntermediateResult) and the final result is supplied on the last call.



11.2.4 Storing (intermediate) results

11.2.4.1 .NET web services

In the case of .NET web services, you have two ways of storing the intermediate results:

ASP.NET cache The ASP.NET cache is very fast but cannot survive a server crash and is unsuitable for use in web farms. On such calls, you can specify in TimeoutInSeconds how long a cache object is to “remain alive” after the last write access. The cache object is deleted when this period elapses.

Message queue Message queues are slower. However, the messages survive a server crash. This approach is also suitable for web farms. A “local” queue is used. The parameter TimeoutInSeconds is not used here. The maximum length of a message in the message queue is 4 MB. Here, a private message queue with the name .\private$\BizTa is used (This queue is only available on the local host on which MSMQ is installed. It is not published in the Message Queue Information Service Database (MQIS). It cannot be addressed by other applications unless the full name is used).

You specify which of the two approaches is to be used in the fileBizTransactions-installation-directory\Templates\Query.txt (see section “Generating and deploying .NET web services” on page 143). If necessary, you can edit the following constants:

Constant Value Description

USE_ASPNET_CACHE True True Use the ASP.NET cache object to store the (intermediate) results from the Query method.

False Use a message queue

TIMEOUT_IN_SECONDS 6000 This value allows you to control how long the ASP.NET cache object is to “remain alive” (for further information, see the .NET documenta-tion on the cache object).



11.2.4.2 Java web services

In the case of Java web services, you have two ways of saving the intermediate results:

Servlet Context Servlet Context is very fast but cannot survive a server crash.

JMS message queue Message queues are slower. The messages may be able to survive a server crash depending on how the message queue was created.

However, if you want to use JMS, the associated application server on which the web service is running, as well as the BizTransactions generation, must be configured appropriately (see next section “Configuration for the use of JMS message queues”).

Configuration for the use of JMS message queues

Although JMS itself is a vendor-independent standard, the configuration of certain compo-nents nevertheless depends on the employed product. The required steps are therefore described only in general terms below.

A prerequisite for the use of JMS is that the web services are deployed in an application server that implements JMS. For example, if the web services are deployed in Tomcat, JMS cannot be used.

● First of all, you must configure a queue and a connection factory that the web service is to use to store the intermediate results.

In the case of an Oracle Application Server, configuration can be performed, for example, by means of entries in the configuration file jms.xml or with the Application Server Manager.

Example entries in the jms.xml file of Oracle Application Server 10g

<queuename="Sample Queue"location="jms/sampleQueue"persistence-file="sampleQueue"><description>A sample queue</description>

</queue><connection-factory location="jms/sampleConnectionFactory"/>

This configures a queue and a connection factory that can be found in a context lookup under the names jms/sampleQueue or jms/sampleConnectionFactory.



● In addition, you must adapt the template that BizTransactions uses to generate the web service to the employed application server and the configured queue and connection factory.

Example for Oracle Application Server 10g

public class &BO.N&QueryManager implements &BO.N&QueryManagerIF {private QueryManager qm;private boolean useJMS = true; // switch for JMS usage

public &BO.N&QueryManager() {if (useJMS) {

// environment object for initial contextHashtable env = new Hashtable();

// set the environment properties for OC4Jenv.put(javax.naming.Context.INITIAL_CONTEXT_FACTORY,

com.evermind.server.rmi.RMIInitialContextFactory");env.put(javax.naming.Context.PROVIDER_URL,

"ormi://localhost:23791");env.put(javax.naming.Context.SECURITY_PRINCIPAL, "admin");env.put(javax.naming.Context.SECURITY_CREDENTIALS, "welcome");env.put("JMS_QueueName", "jms/sampleQueue");env.put("JMS_ConnectionFactory", "jms/sampleConnectionFactory");

qm = new QueryManagerJMS(env);} else

qm = new QueryManager();}

The use of JMS or ServletContext is controlled by means of the variable useJMS. The configuration data for JMS is passed in a hash table, with some keys from javax.naming.Context being used together with the keys JMS_QueueName and jms/sampleConnectionFactory for the transfer of the names of the configured queue and connection factory.

This example was elaborated with an Oracle Application Server 10g. Other JMS imple-mentations may need a different environment in order to generate an InititialContext for message queue access.



11.2.5 Writing intermediate results

In BizTransactions Studio (Edit method window, Extras menu), the function Write intermediate result is proposed for Query methods. The method must possess the signature described in section “Criteria for generation” on page 375.

The Parameter field displays the Query method’s output parameter. Select a local variable that possesses the current index in the result table.

● For .NET, an IntermediateResult event call is generated.

● For Java, a BizTaIntermediateResult event call is generated.

● For VisualBasic 6, the comment TODO NOT SUPPORTED IN VISUAL BASIC 6 is generated.

If the signature of the Query method does not fulfill the described requirements, the following comment is generated:

TODO Query Method: invalid params. WriteIntermediateResult ignored!

If you have explicitly set the size of the output table in the business object, you should reset the table to the “correct” size before termination of the Query method, (SetSize statement, see section “Methods for arrays” on page 295 for Java and section “Methods for arrays” on page 313 for .NET).

i


Using business objects Office Research web services

11.3 Office Research web services

With Word, Excel, Powerpoint and Publisher, Microsoft Office 2003 makes it possible to call, from the task pane, simple web services whose results are output in the output area. This web services must possess methods with a specific signature.

BizTransactions generates this type of web service for .NET in the NetOfficeResearch directory if

● the business object comprises a method with the name OfficeResearch which in turn possesses exactly one scalar parameter of type String followed by an output parameter,

● the option OfficeResearch was enabled when the business object was generated, and

● .NET has been selected as the language (see section “Generation options” on page 128).

The following web service methods are generated:

A detailed example of an Office Research web service can be found in the tutorial Using BOs.doc which is supplied with BizTransactions. You can find this file in the BizTransactions installation directory under Examples\Documents\En\ExampleUPIC\Tutorial Using BOs.doc.

More detailed information on the Microsoft Office Research Service Software Development Kit can be found athttp://msdn.microsoft.com/library/default.asp?url=/library/en-us/rssdk/html/rsconAboutRSSDK.as

Method Description

Public Function Registration(ByVal registrationXml As String) As String

An Office client can register with this method. The input and output data are XML documents.

Public Function Query(ByVal queryXml As String) As String

With this method, an Office client can search for something and obtain the required hits from the meth-od.The input and output data are XML documents.

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rssdk/html/rsconAboutRSSDK.as


Office Research web services Using business objects

11.3.1 Preparations for use

On many machines, the Microsoft Office Research Services are disabled. If new research services are to be used, the following options must be set with the specified values in the key HKEY_LOCAL_MACHINE\Software\Microsoft\Office\11.0\Common\Research\Options

For more detailed information, see “Administrative Option Settings” in http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rssdk/html/rsregAdministrativeOptions.asp.

When you have made any necessary changes to the registry values,

Ê Choose, in Microsoft Word 2003 for example, the View menu followed by thecommand Task Pane. The task pane is now displayed.

Ê In the selection list displayed here, select Research. Click on Research Options.

Ê Under Address in the Add Services dialog box, enter the URL of the Office Research web service.

Key Value

NoAdd False (0)

NoDiscovery False (0)

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rssdk/html/rsregAdministrativeOptions.asp


Using business objects Office Research web services

Ê In the following registry dialog, click on Install. The Office Research web service is available immediately.

11.3.2 Calling an Office Research web service

To call an Office Research web service ,

Ê Choose, in Microsoft Word 2003 for example, the View menu followed by thecommand Task Pane. The task pane is now displayed.

Ê Choose Research in the selection list at the top of the screen.

Ê Under Search for, search for the search term, in this case, the input parameter of the Office Research method.

Ê In the selection list, select the required Office Research method.

The result, i.e. the output method of the Office Research method, is output.

The output parameter is output with the ToString method. You can edit the generated source and program special formats.

For further information, see “Customizing the Microsoft Office 2003 Research Task Pane” at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dno2k3ta/html/odc_customizingtheresearchpane.asp

i

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dno2k3ta/html/odc_customizingtheresearchpane.asp


12 Appendix

12.1 Special applications

Particularities when connecting via UPIC

For +Formats the attribute field of the Set FormatAttribut code statement is set to 0 or to the total length. The value you set depends on the FHS start parameter EFFLEN of the openUTM application and on the response of the openUTM program unit.

It is not possible with BizTransactions to use the same format when the service is started and also use it within the service: openUTM cuts off the first 8 bytes (transaction code) for *formats and the first 10 bytes (attribute field + transaction code) for +formats.

If you need such a structure for your specific application, it is recommended that you obtain support from the manufacturer.

Marking fields

If the application to be integrated shows a match in the format due to the way the field is displayed (e.g. it is blinking), the match cannot be evaluated by BizTransactions at the present time.

Cursor position

The cursor can be queried. It is not possible to set the cursor.

The following function returns the position of the passed field:

lPos = FieldPosition(myBuffer.myField(i)) ' If this field is the cursor field ...If BizTaCursor = lPos Then

' Write to the field addressed with BizTaCursor ..myBuffer.myField(BizTaCursor) = "Here is the cursor!"

End If

i


Special applications Appendix

RESTART response of the UTM user ID

It is recommended to define the UTM user ID in the openUTM configuration with RESTART=NO.

For user IDs with RESTART=Y openUTM will execute a user-specific restart if necessary. In such cases a warm start is executed after the user has signed on, and the dialog is continued at the point where it was aborted. The format that generally appears after signing on will therefore not appear because BizTransactions would receive an unexpected format in this case and return an error. If you want to work with RESTART=Y, you must trap this error using the service BizTaUnknown (see section “Modeling unknown formats (BizTaUnknown)” on page 183) or the event handling functions (see chapter “Diagnostic tools” on page 345). It is recommended that you obtain support from the manufacturer for such solutions.

Closing a connection

As a rule, connections to a host application are automatically closed by the BizTransactions runtime system and releases the relevant administration data is released. This is the case, for example, after a logoff screen has been sent or when the communication object is released.

In some cases, however, it is necessary to close a connection explicitly at a certain point in the program.

● In Visual Basic and Java, the communication objects, i.e. the objects of the class BizTaConnection, provide the method stopCommunication() for this and it can be called as follows:

– In Visual Basic:

Communication object method:

Public Function StopCommunication (ByRef message As String, ByRef CommStatus As String) As Boolean

The parameters are output parameters. When the function is returned, they contain the current connection status (status) and an error message (msg), where appro-priate.

The method is called as follows:(objBO is the instance of a business object)

Dim cObj as BizTaConnection, msg as String, status as Stringset cObj=objBO.getCommunicationServer()cObj.StopCommunication msg, status


Appendix Special applications

– In Java:

Communication object method:

public void stopCommunication()

The method is called as follows:(objBO is the instance of a business object)

BizTaConnection cObj;cObj = objBO.getCommunicationServer();cObj.stopCommunication();

● In .NET, the communication objects, i.e. the objects of class BizTaConnection, possess the Dispose method.

The Dispose method is called as follows:(where objBO is a business object instance)

Dim myConnection As BizTaConnectionobjBO.GetCommunicationServer().Dispose()


Special applications Appendix

Conversion table for the ToASCII and ToEBCDIC functions

The conversion methods ToASCII() and ToEBCDIC() use the BizTaConv.tab conversion table which is stored in:

Windows the SystemRoot directorySolaris the HOME directory

If BizTaConv.tab is not present, then a predefined table is used. You can edit and/or replace the BizTaConv.tab conversion table.

The conversion table must contain 16 pairs of rows, each separated by an empty row. The first row of such a pair starts with the keyword ASCII followed by a tab character. After that come 16 hexadecimal ASCII codes in ascending order and separated by tab characters.

The second row of such a pair starts with the keyword EBCDIC followed by a tab character. After that come16 hexadecimal EBCDIC codes in ascending order and separated by tab characters that are to be associated with the ASCII codes in the first line.

Example

You will find an example of a conversion table in the Templates\Convert subdirectory of the BizTransactions installation directory.

If you want to edit the conversion table, edit only the lines beginning with EBCDIC. Leave the lines beginning with ASCII unchanged.

ASCII 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f

EBCDIC 00 01 02 03 37 2d 2e 2f 16 05 15 0b 0c 0d 0e 0f

ASCII 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f

EBCDIC 10 11 12 13 3c 3d 16 17 18 19 1a 1b 1c 1d 1e 1f

i


Appendix Business objects and threads

12.2 Business objects and threads

Only one connection can be established per thread in conjunction with openUTM. This still applies. The may lead to problems in the situations described below.

12.2.1 Java and .NET destructor

openUTM Disable (CMDISA) is called in the destructor of the openUTM communication object. The destructor is called at a later point by the Java or .NET VM Garbage Collection. The Garbage Collector also runs in its own thread. This causes two problems:

1. The connection is closed down completely with considerable delay. Until this is done, no new connection can be established in the thread.

2. Connection close-down fails because it is called in a different thread to the connection set-up, in which the other communication calls are performed.

In this case, CMDISA returns error code 25 = CM_PROGRAM_STATE_CHECK. You can then close the connection with the StopCommunication() method, see also section “Closing a connection” on page 392 for more information.

.NET

You call the business object’s Dispose method when you no longer require the business object.

If you develop the client in C# or program in Visual Basic in the .NET-Framework 2.0 then you use the Using statement. In this case, Dispose is called automatically when the Using block is exited.


Business objects and threads Appendix

12.2.2 Java, .NET and Visual Basic applications

Regardless of the business object class, only one business object that communicates with the host application via openUTM can be used within one thread.

This problem can currently only be solved on the application level. Solution models for Java, .NET and Visual Basic are described below.

Java

The application generates a separate thread for each business object instance. The business object is generated in that thread and all required method calls are performed there.

class BoThread extends Thread {

public void run () { /* test BO */ <BOclass> objBO;BizTaConnection objIO;

try { objBO = new <BOclass>(); … objBO.<method1> (…); … objBO.<method2> (…); … /* the following code avoids the error in the CMDISA: */ objIO = (objBO.getCommunicationServer(); objIO.stopCommunication(); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } }}

Several business object instances can then be generated as follows:

BoThread objBO1 = new BoThread(); objBO1.start(); BoThread objBO2 = new BoThread(); objBO2.start();


Appendix Business objects and threads

.NET

Start the method in a separate thread (see section “Calling methods” on page 314).

Visual Basic

In Visual Basic

● two different business objects are to run in parallel.

● When the business objects are generated, they are generated as ActiveX EXEs.

● several instances of the same business object are to run in parallel.

When the business object is generated, it are generated as an ActiveX EXE.

When the business objects are generated in BizTransactions Studio as ActiveX DLL then as ActiveX EXE, then you need to set the Compatibility generation option to No when switching from ActiveX DLL to ActiveX EXE.

Both ActiveX objects (DLL and EXE) are then registered with the same name. The DLL should either be deregistered (regsvr32 /u <dll>) or different names should be assigned to the .DLL and the .EXE when the business object is generated, so that the ActiveX EXE can be selected specifically.

The application can then use the business object just as an ActiveX DLL, but the perfor-mance must be expected to be less advantageous.

Note

This problem does not occur in with business objects that communicate with a host appli-cation via emulation. The the described application structure for Java and for Visual Basic would also function with an emulation business object should this appear be an option for other reasons.


GlossaryA term in ->italic font means that it is explained somewhere else in the glossary.

active dialogIn the case of active dialogs, WebTransactions actively intervenes in the control of the dialog sequence, i.e. the next ->template to be processed is determined by the template programming. You can use the ->WTML language tools, for example, to combine multiple ->host formats in a single ->HTML page. In this case, when a host ->dialog step is terminated, no output is sent to the ->browser and the next step is immediately started. Equally, multiple interactions between the Web ->browser and WebTransactions are possible within one and the same host dialog step.

array->Data type which can contain a finite set of values of one data type. This data type can be:– ->scalar – a ->class – an arrayThe values in the array are addressed via a numerical index, starting at 0.

asynchronous messageIn WebTransactions, an asynchronous message is one sent to the terminal with-out having been explicitly requested by the user, i.e. without the user having pressed a key or clicked on an interface element.

attributeAttributes define the properties of ->objects.

● In WebTransactions, an attribute may be, for example, the color, size or position of an object or it can itself be an object. Attributes are also interpret-ed as ->variables and their values can be queried or modified.

● In BizTransactions, an attribute may be a ->property of a ->catalog object or ->catalog element.


Glossary

Automask templateA WebTransactions ->template created by WebLab either implicitly when generating a base directory or explicitly with the command Generate Automask. It is used whenever no format-specific template can be identified. An Automask template contains the statements required for dynamically mapping formats and for communication. Different variants of the Automask template can be generated and selected using the system object attribute AUTOMASK.

base directoryThe base directory is located on the WebTransactions server and forms the basis for a ->WebTransactions application. The base directory contains the ->templates and all the files and program references (links) which are necessary in order to run a WebTransactions application.

BCAM application nameCorresponds to the openUTM generation parameter BCAMAPPL and is the name of the −>openUTM application through which −>UPIC establishes the connec-tion.

BizTransactions applicationApplication, which integrates -> host applications for COM or Java access. A BizTransactions application consists of:– ->host adapters– ->business objects– a ->client, which addresses the business objects

BizTransactions catalogCentral database used and processed by the BizTransactions Studio during the development phase. For instance, the BizTransactions catalog contains a description of the ->host applications and of the messages (->services) exchanged with the host application.

browserProgram which is required to call and display ->HTML pages. Familiar browsers include, for example, Netscape Navigator or Microsoft Internet Explorer.

browser display printThe WebTransactions browser display print prints the information displayed in the ->browser.

browser platformOperating system of the host on which a ->browser runs as a client for WebTransactions.


Glossary

bufferDefinition of a record, which is transmitted from a ->service. The buffer is used for transmitting and receiving messages. In addition there is a specific buffer for storing the ->recognition criteria and for data for the representation on the screen.

business object (BO)Object-oriented view of a ->host application: Business Objects in BizTransactions combine a number of ->services of an application to form a logical object. A description of each business object is stored in the ->BizTransactions catalog. This description then forms the basis for generating an ActiveX component, .NET component or ->JavaBean which then represents the business object.

business object classJava, .NET or Visual Basic class generated by the BizTransactions Studio on the basis of a business object stored in the ->BizTransactions catalog.

capturingTo enable WebTransactions to identify the received ->formats at runtime, you can open a ->session in ->WebLab and select a specific area for each format and name the format. The format name and ->recognition criteria are stored in the ->capture database. A ->template of the same name is generated for the format. Capturing forms the basis for the processing of format-specific templates for the WebTransactions for OSD, MVS, As400 and UNIX product variants.

capture databaseThe WebTransactions capture database contains all the format names and the associated ->recognition criteria generated using the ->capturing technique. You can use ->WebLab to edit the sequence and recognition criteria of the formats.

catalog elementSubordinate ->catalog objects in BizTransactions, such as ->buffers, ->records or ->fields. The ->properties of catalog elements are ->attributes.

catalog objectDescriptions saved in the ->BizTransactions catalog for– ->Host applications– ->Services – ->Business objects – ->Classes – ->Functions ->Catalog-elements are subordinate to the catalog-objects. The ->properties of catalog objects and elements are ->attributes. A separate ->XML schema is assigned to each catalog object.


Glossary

CGI(Common Gateway Interface)Standardized interface for program calls on ->Web servers. In contrast to the static output of a previously defined->HTML page, this interface permits the dynamic construction of HTML pages.

classContains definitions of the ->properties and ->methods of an ->object. It provides the model for instantiating objects and defines their interfaces.

In BizTransactions the ->catalog object of the type class contains only properties which means that a class is also considered as a user-defined data structure. Access methods for the class properties are added through generation. A class can be used by the following catalog elements:– Properties of ->business objects– Properties of other classes– ->Method parameters– ->Function parameters

class directoryA directory in BizTransactions which contains the generated ->business object classes and ->service classes.

class templateIn WebTransactions, a class template contains valid, recurring statements for the entire object class (e.g. input or output fields). Class templates are processed when the ->evaluation operator or the toString method is applied to a ->host data object.

clientRequestors and users of services in a network. A BizTransactions client accesses ->business objects within a ->client application.

clusterSet of identical ->WebTransactions applications on different servers which are interconnected to form a load-sharing network.

COMComponent Object Model.The COM defines a standard governing the way in which software components can access the services or data provided by other software components.


Glossary

communication objectThis controls the connection to an ->host application and contains information about the current status of the connection, the last data to be received etc.

conversion toolsUtilities supplied with WebTransactions and BizTransactions. These tools are used to analyze the data structures of ->openUTM applications and store the information in files. These files can then be imported in the form of an object description into the ->BizTransactions catalog or used in WebLab as ->format description sources in order to generate WTML templates and ->FLD files.COBOL data structures or IFG format libraries form the basis for the conversion tools. The conversion tool for DRIVE programs is supplied with the product DRIVE.

daemon Name of a process type in UNIX/POSIX systems which runs in the background and performs no I/O operations at terminals.

data access controlMonitoring of the accesses to data and ->objects of an application.

data typeDefinition of the way in which the contents of a storage location are to be inter-preted. Each data type has a name, a set of permitted values (value range), and a defined number of operations which interpret and manipulate the values of that data type.

DCOMDistributed Component Object ModelThis is based on the ->COM standard and defines the way in which COM objects can provide their services or data outside system boundaries.


Glossary

dialog

● In WebTransactions, a dialog describes the entire communication between browser, WebTransactions and ->host application. It will usually comprise multiple ->dialog cycles. WebTransactions supports a number of different types of dialog.

– ->passive dialog– ->active dialog– ->synchronized dialog– ->non-synchronized dialog

● In BizTransactions a dialog is defined as a series of ->dialog steps. A method of a ->Business Object is the same as a dialog with the ->host application.

dialog cycleCycle that comprises the following steps when a ->WebTransactions application is executed:– construct an ->HTML page and send it to the ->browser – wait for a response from the browser– evaluate the response fields and possibly send them to the->host application

for further processingA number of dialog cycles are passed through while a ->WebTransactions appli-cation is executing.

dialog stepIn BizTransactions, a dialog step begins by sending a dialog message to the ->host application, and ends with a response from the host application.

distinguished nameThe Distinguished Name (DN) in ->LDAP is hierarchically organized and consists of a number of different components (e.g. “country, and below country: organization, and below organization: organizational unit, followed by: usual name”). Together, these components provide a unique identification of an object in the directory tree.Thanks to this hierarchy, the unique identification of objects is a simple matter even in a worldwide directory tree: – The DN "Country=DE/Name=Emil Person" reduces the problem of achiev-

ing a unique identification to the country DE (=Germany).– The DN "Organization=FSC/Name=Emil Person" reduces it to the organiza-

tion FSC.– The DN "Country=DE/Organization=FSC/Name=Emil Person" reduces it to

the organization FSC located in Germany (DE).


Glossary

document directory->Web server directory containing the documents that can be accessed via the network. WebTransactions stores files for download in this directory, e.g. the WebLab client or general start pages.

Domain Name Service (DNS) Procedure for the symbolic addressing of computers in networks. Certain computers in the network, the DNS or name server, maintain a database containing all the known host names and IP numbers in their environment.

dynamic dataIn WebTransactions, dynamic data is mapped using the WebTransactions object model, e.g. as a ->system object, host object or user input at the browser.

EHLLAPIEnhanced High-Level Language APIProgram interface, e.g. of terminal emulations for communication with the SNA world. Communication between the transit client and SNA computer, which is handled via the TRANSIT product, is based on this interface.

EJB (Enterprise JavaBean)This is a Java-based industry standard which makes it possible to use in-house or commercially available server components for the creation of distributed program systems within a distributed, object-oriented environment.

entry pageThe entry page is an ->HTML page which is required in order to start a ->WebTransactions application This page contains the call which starts WebTransactions with the first ->template, the so-called start template.

evaluation operator In WebTransactions the evaluation operator replaces the addressed ->expressions with their result (object attribute evaluation). The evaluation oper-ator is specified in the form ##expression#.

expressionA combination of ->literals, ->variables, operators and expressions which return a specific result when evaluated.

FHSFormat Handling SystemFormatting system for BS2000/OSD applications.


Glossary

fieldA field is the smallest component of a service and element of a ->record or ->buffer.

field file (*.fld file)In WebTransactions, this contains the structure of a ->format record (metadata).

filterProgram or program unit (e.g. a library) for converting a given ->format into another format (e.g. XML documents to ->WTScript data structures).

formatOptical presentation on alphanumeric screens (sometimes also referred to as screen form or mask).

In WebTransactions each format is represented by a ->field file and a ->template.

format type(only relevant in the case of ->FHS applications and communication via ->UPIC)Specifies the type of format: #format, +format, -format or *format.

format description sourcesDescription of multiple ->formats in one or more files which were generated from a format library (FHS/IFG) or are available directly at the ->host for the use of “expressive” names in formats.

functionA function is a user-defined code unit with a name and ->parameters. Functions can be called in ->methods by means of a description of the function interface (or signature).

holder task A process, a task or a thread in WebTransactions depending on the operating system platform being used. The number of tasks corresponds to the number of users. The task is terminated when the user logs off or when a time-out occurs. A holder task is identical to a ->WebTransactions session.

hostThe computer on which the- >host application is running.


Glossary

host adapterHost adapters are used to connect existing ->host applications to WebTransactions and BizTransactions. At runtime, for example, they have the task of establishing and terminating connections and converting all the exchanged data.

host applicationApplication that is integrated with WebTransactions or BizTransactions.

host control objectIn WebTransactions, host control objects contain information which relates not to individual fields but to the entire ->format. This includes, for example, the field in which the cursor is located, the current function key or global format attributes.

host data objectIn WebTransactions, this refers to an ->object of the data interface to the ->host application. It represents a field with all its field attributes. It is created by WebTransactions after the reception of host application data and exists until the next data is received or until termination of the ->session.

host data printDuring WebTransactions host data print, information is printed that was edited and sent by the ->host application, e.g. printout of host files.

host platformOperating system of the host on which the ->host applications runs.

HTML(Hypertext Markup Language) See ->Hypertext Markup Language

HTTP(Hypertext Transfer Protocol)This is the protocol used to transfer ->HTML pages and data.

HTTPS(Hypertext Transfer Protocol Secure)This is the protocol used for the secure transfer of ->HTML pages and data.

hypertextDocument with links to other locations in the same or another document. Users click the links to jump to these new locations.


Glossary

Hypertext Markup Language (Hypertext Markup Language) Standardized markup language for documents on the Web.

Java BeanJava programs (or ->classes) with precisely defined conventions for interfaces that allow them to be reused in different applications.

KDCDEFopenUTM tool for generating ->openUTM applications.

LDAP(Lightweight Directory Access Protocol)The X.500 standard defines DAP (Directory Access Protocol) as the access protocol. However, the Internet standard “LDAP” has proved successful specif-ically for accessing X.500 directory services from a PC. LDAP is a simplified DAP protocol that does not support all the options available with DAP and is not compatible with DAP. Practically all X.500 directory services support both DAP and LDAP. In practice, interpretation problems may arise since there are various dialects of LDAP. The differences between the dialects are generally small.

literalCharacter sequence that represents a fixed value. Literals are used in source programs to specify constant values (“literal” values).

master templateWebTransactions template used to generate the Automask and the format-specific templates.

message queuing (MQ)A form of communication in which messages are not exchanged directly, rather via intermediate queues. The sender and receiver can work at separate times and locations. Message transmission is guaranteed regardless of whether or not a network connection currently exists.

methodObject-oriented term for a ->function. A method is applied to the ->object in which it is defined.

In BizTransactions, the method of a ->business object conducts a ->dialog with the associated ->host application.


Glossary

module templateIn WebTransactions, a module template is used to define ->classes, ->functions and constants globally for a complete ->session. A module template is loaded using the import() function.

MT tag(Master Template tag)Special tags used in the dynamic sections of ->master templates.

multitier architectureAll client/server architectures are based on a subdivision into individual soft-ware components which are also known as layers or tiers. We speak of 1-tier, 2-tier, 3-tier and multitier models. This subdivision can be considered at the physical or logical level:– We speak of logical software tiers when the software is subdivided into

modular components with clear interfaces. – Physical tiers occur when the (logical) software components are distributed

across different computers in the network.

With WebTransactions and a host connection in BizTransactions, multitier models are possible both at the physical and logical level.

name/value pairIn the data sent by the ->browser, the combination, for example, of an ->HTML input field name and its value.

non-synchronized dialogNon-synchronized dialogs in WebTransactions permit the temporary deactiva-tion of the checking mechanism implemented in ->synchronized dialogs. In this way, ->dialogs that do not form part of the synchronized dialog and have no effect on the logical state of the ->host application can be incorporated. In this way, for example, you can display a button in an ->HTML page that allows users to call help information from the current host application and display it in a separate window.


Glossary

objectElementary unit in an object-oriented software system. Every object possesses a name via which it can be addressed, ->attributes, which define its status together with the ->methods that can be applied to the object.

In BizTransactions objects only exist as instances of ->classes during run time. However, for simplicity’s sake, the object definitions created during development are also referred to as objects. Thus, we speak of, for example, ->business objects stored in the ->BizTransactions catalog although these are actually only definitions. These definitions are used by BizTransactions to generate ->business object classes which serve to instantiate the “actual” business objects at runtime.

openUTM(Universal Transaction Monitor)Transaction monitor from Fujitsu Siemens Computers, which is available for BS2000/OSD and a variety of UNIX and Windows platforms.

openUTM applicationA ->host application which provides services that process jobs submitted by ->clients or other ->host applications. openUTM responsibilities include transac-tion management and the management of communication and system resources. Technically speaking, the UTM application is a group of processes which form a logical unit at runtime.

openUTM applications can communicate both via the client/server protocol ->UPIC and via the emulation interface (9750).

openUTM-Client (UPIC)The openUTM-Client (UPIC) is a product used to create client programs for openUTM. openUTM-Client (UPIC) is available, for example, for UNIX, BS2000/OSD and Windows platforms.

openUTM program unitThe services of an ->openUTM application are implemented by one or more openUTM program units. These can be addressed using transaction codes and contain special openUTM function calls (e.g. KDCS calls).

parameterData which is passed to a ->function or a ->method for processing (input param-eter) or data which is returned as a result of a function or method (output param-eter).


Glossary

passive dialogIn the case of passive dialogs in WebTransactions, the dialog sequence is controlled by the ->host application, i.e. the host application determines the next ->template which is to be processed. Users who access the host application via WebTransactions pass through the same dialog steps as if they were accessing it from a terminal. WebTransactions uses passive dialog control for the automatic conversion of the host application or when each host application format corre-sponds to precisely one individual template.

passwordString entered for a ->user id in an application which is used for user authenti-cation (->system access control).

pollingCyclical querying of a given event.

poolIn WebTransactions, this term refers to a shared directory in which WebLab can create and maintain ->base directories. You control access to this directory with the administration program.

postTo send data.

posted object (wt_Posted)List of the data returned by the ->browser. This ->object is created by WebTransactions and exists for the duration of a ->dialog cycle.

processThe term “process” is used as a generic term for process (in Solaris, Linux and Windows) and task (in BS2000/OSD).

projectIn the WebTransactions development environment, a project contains various settings for a ->WebTransactions application. These are saved in a project file (suffix .wtp). You should create a project for each WebTransactions application you develop, and always open this project for editing.

propertyProperties define the nature of an ->object, e.g. the object “Customer” could have a customer name and number as its properties. These properties can be set, queried, and modified within the program.


Glossary

protocolAgreements on the procedural rules and formats governing communications between remote partners of the same logical level.

protocol file

● BizTransactions: Messages about specific program status conditions are written during the program execution into a log file.

● openUTM-Client: File into which the openUTM error messages as are written in the case of abnormal termination of a conversation.

● In WebTransactions, protocol files are called trace files.

roaming session->WebTransactions sessions which are invoked simultaneously or one after another by different ->clients.

recordA record is the definition of a set of related data which is transferred to a ->buffer. It describes a part of the buffer which may occur one or more times.

recognition criteriaRecognition criteria are used to identify ->formats of a ->terminal application and can access the data of the format. The recognition criteria selected should be one or more areas of the format which uniquely identify the content of the format.

scalar->variable made up of a single value, unlike a ->class, an ->array or another complex data structure.


Glossary

service

In BizTransactions, services are messages exchanged with the ->host application. In the case of access via the terminal interface (9750/3270), they are ->formats. In program-to-program communication, they correspond to message structures. Services are created using the BizTransactions Studio. They are automatically entered in the ->BizTransactions catalog and can be used by the (COM) ->clients. Depending on the type of server application, a service may represent:

● a 9750 emulation screen

● a 3270 emulation screen

● an openUTM ->dialog step (in the case of interconnection via UPIC) which is distinguished by:

– the FHS format

– the data structure of a DRIVE procedure

– the data structure of a COBOL program (structure of the UPIC message buffer)

● a message sent or received by the ->host adapter

service (openUTM)In ->openUTM, this is the processing of a request using an ->openUTM applica-tion. There are dialog services and asynchronous services. The services are assigned their own storage areas by openUTM. A service is made up of one or more ->transactions.

service application->WebTransactions session which can be called by various different users in turn.

service datadescription of a ->service in the BizTransactions catalog. The service data contain a description of the structure of the service and either– a ->recognition criterion or– data for the presentation of the service while recording a ->dialog

service nodeInstance of a ->service. During development and runtime of a ->method a service can be instantiated several times. During modelling and code editing those instances are named service nodes.


Glossary

sessionWhen an end user starts to work with a ->WebTransactions application this opens a WebTransactions session for that user on the WebTransactions server. This session contains all the connections open for this user to the ->browsers, special ->clients and ->hosts.A session can be started as follows:– Input of a WebTransactions URL in the browser.– Using the START_SESSION method of the WT_REMOTE client/server interface.A session is terminated as follows:– The user makes the corresponding input in the output area of this

->WebTransactions application (not via the standard browser buttons).– Whenever the configured time that WebTransactions waits for a response

from the ->host application or from the ->browser is exceeded.– Termination from WebTransactions administration.– Using the EXIT_SESSION method of the WT_REMOTE client/server interface.A WebTransactions session is unique and is defined by a ->WebTransactions application and a session ID. During the life cycle of a session there is one ->holder task for each WebTransactions session on the WebTransactions server.

SOAP(originally Simple Object Access Protocol)The ->XML based SOAP protocol provides a simple, transparent mechanism for exchanging structured and typecast information between computers in a decentralized, distributed environment. SOAP provides a modular package model together with mechanisms for data encryption within modules. This enables the uncomplicated description of the internal interfaces of a ->Web-Service.

styleIn WebTransactions this produces a different layout for a ->template, e.g. with more or less graphic elements for different->browsers. The style can be changed at any time during a ->session.

synchronized dialogIn the case of synchronized dialogs (normal case), WebTransactions automati-cally checks whether the data received from the web browser is genuinely a response to the last ->HTML page to be sent to the ->browser. For example, if the user at the web browser uses the Back button or the History function to return to an “earlier” HTML page of the current ->session and then returns this, WebTransactions recognizes that the data does not correspond to the current ->dialog cycle and reacts with an error message. The last page to have been sent to the browser is then automatically sent to it again.


Glossary

system access controlCheck to establish whether a user under a particular ->user ID is authorized to work with the application.

system object (wt_System)The WebTransactions system object contains ->variables which continue to exist for the duration of an entire ->session and are not cleared until the end of the session or until they are explicitly deleted. The system object is always visible and is identical for all name spaces.

TACSee ->transaction code

tag->HTML, ->XML and ->WTML documents are all made up of tags and actual content. The tags are used to mark up the documents e.g. with header formats, text highlighting formats (bold, italics) or to give source information for graphics files.

TCP/IP (Transport Control Protocol/Internet Protocol)Collective name for a protocol family in computer networks used, for example, in the Internet.


Glossary

templateA template is used to generate specific code. A template contains fixed informa-tion parts which are adopted unchanged during generation, as well as variable information parts that can be replaced by the appropriate values during gener-ation.

● In WebTransactions, a ->WTML file is a file with special tags for controlling the dynamic generation of a ->HTML page and for the processing of the values entered at the ->browser. It is possible to maintain multiple template sets in parallel. These then represent different ->styles (e.g. many/few graphics, use of Java, etc.).

WebTransactions uses different types of template:– ->Automask templates for the automatic conversion of the ->formats of

AS400, MVS, OSD and UNIX applications.– Custom templates, written by the programmer, for example, to control

an ->active dialog. – Format-specific templates which are generated for subsequent post-

processing. – Include templates which are inserted in other templates.– ->Class templates– ->Master templates to ensure the uniform layout of fixed areas on the

generation of the Automask and format-specific templates.– Start template, this is the first template to be processed in a

WebTransactions application.

● In BizTransactions, templates are supplied files which contain code sections that can be used as patterns for the generation functions of BizTransactions.

template object->Variables are used to buffer values for a ->dialog cycle in WebTransactions.

terminal applicationApplication on a ->host computer which is accessed via a 9750 or 3270 inter-face.

terminal hardcopy printA terminal hardcopy print in WebTransactions prints the alphanumeric represen-tation of the ->format as displayed by a terminal or a terminal emulation.

transactionProcessing step between two synchronization points (in the current operation) which is characterized by the ACID conditions (Atomicity, Consistency, Isolation and Durability). The intentional changes to user information made within a transaction are accepted either in their entirety or not at all (all-or-nothing rule).


Glossary

transaction code/TACName under which an openUTM service or ->openUTM program unit can be called. The transaction code is assigned to the openUTM program unit during configuration. A program unit can be assigned several transaction codes.

UDDI(Universal Description, Discovery and Integration)Refers to directories containing descriptions of ->Web services. This information is available to web users in general.

UPIC(Universal Programming Interface for Communication)Carrier system for openUTM clients which uses the X/Open interface, which permity CPI-C client/server communication between a CPI-C-Client application and the openUTM application.

URI(Uniform Resource Identifier)Blanket term for all the names and addresses that reference objects on the Internet. The generally used URIs are->URLs.

URL (Uniform Resource Locator)Description of the location and access type of a resource in the ->Internet.

user exitFunctions implemented in C/C++ which the programmer calls from a ->template.

user IDUser identification which can be assigned a password (->system access control) and special access rights (->data access control).

UTMSee ->openUTM

variableMemory location for variable values which requires a name and a ->data type.

visibility of variables->Objects and ->variables of different dialog types are managed by WebTransactions in different address spaces. This means that variables belong-ing to a ->synchronized dialog are not visible and therefore not accessible in a ->asynchronous dialog or in a dialog with a remote application.


Glossary

web serverComputer and software for the provision of ->HTML pages and dynamic data via ->HTTP.

web serviceService provided on the Internet, for example a currency conversion program. The SOAP protocol can be used to access such a service. The interface of a web service is described in ->WSDL.

WebTransactions applicationThis is an application that is integrated with ->host applications for internet/intranet access. A WebTransactions application consists of: – a ->base directory– a start template – the ->templates that control conversion between the ->host and the

->browser.– protocol-specific configuration files.

WebTransactions platformOperating system of the host on which WebTransactions runs.

WebTransactions serverComputer on which WebTransactions runs.

WebTransactions sessionSee ->session

WSDL(Web Service Definition Language)Provides ->XML language rules for the description of ->web services. In this case, the web service is defined by means of the port selection.

WTBeanIn WebTransactions ->WTML components with a self-descriptive interface are referred to as WTBeans. A distinction is made between inline and standalone WTBeans:– An inline WTBean corresponds to a part of a WTML document– A standalone WTBean is an autonomous WTML document

A number of WTBeans are included in of the WebTransactions product, addition-al WTBeans can be downloaded from the WebTransactions homepage(www.Fujitsu-Siemens.com/WebTransactions).

www.Fujitsu-Siemens.com/WebTransactions


Glossary

WTML(WebTransactions Markup Language)Markup and programming language for WebTransactions ->templates. WTML uses additional ->WTML tags to extend ->HTML and the server programming language ->WTScript, e.g. for data exchange with ->host applications. WTML tags are executed by WebTransactions and not by the ->browser (serverside scripting).

WTML tag(WebTransactions Markup Language-Tag)Special WebTransactions tags for the generation of the dynamic sections of an ->HTML page using data from the->host application.

WTScriptServerside programming language of WebTransactions. WTScripts are similiar to client-side Java scripts in that they are contained in sections that are intro-duced and terminated with special tags. Instead of using ->HTML-SCRIPT tags you use ->WTML-Tags: wtOnCreateScript and wtOnReceiveScript. This indicates that these scripts are to be implemented by WebTransactions and not by the ->browser and also indicates the time of execution. OnCreate scripts are executed before the page is sent to the browser. OnReceive scripts are executed when the response has been received from the browser.

XML(eXtensible Markup Language)Defines a language for the logical structuring of documents with the aim of making these easy to exchange between various applications.

XML schemaAn XML schema basically defines the permissible elements and attributes of an XML description. XML schemas can have a range of different formats, e.g. DTD (Document Type Definition), XML Schema (W3C standard) or XDR (XML Data Reduced).

In BizTransactions, an XDR schema defines the permitted elements and attributes of a catalog object.


AbbreviationsASCII American Standard Code for Information Interchange

BCAM Basic Communication Access Method

BCAM-RDF Basic Communication Access Method Resource Definition File

BO Business Object

CIW CPI-C Implementor’s Workshop

COM Component Object Model

CPI-C Common Programming Interface for Communication

DCOM Distributed Component Object Model

DLL Dynamic Link Library

DTD Document Type Definition

EXE Executable

EBCDIC Extended Binary-Coded Decimal Interchange Code

FHS Format Handling System

IFG Interactive Format Generator

ISO International Standardization Organization

IT Information Technology

JAR Java Archive

JDK Java Development Kit

JWSDP Java Web Services Developer Pack

KDCDEF Kompatible DatencommunikationsDefinition (compatible data communica-tion definition)

KDCS Kompatible Datencommunikationsschnittstelle (compatible data communi-cation interface)

MDAC Microsoft Data Access Components

MQ Message Queuing

OSD Open Systems Direction

RMI Remote Method Interface


Abbreviations

SGML Standard Generalized Markup Language

SOAP Simple Object Access Protocol

TAC Transaction Code

TP Transaction Processing

UPIC Universal Programming Interface for Communication

UTM Universal Transaction Monitor

VB Visual Basic

WMI Windows Message Instrumentation

WSDL Web Services Description Language

XDR XML Data Reduced

XHCS eXtended Host Code Support

XML eXtensible Markup Language

ZSI Zentralstelle für Sicherheit in der Informationstechnik (Center for Security in Information Technology)


Related publicationsYou can download all the WebTransactions manuals from the following Web address http://manuals.Fujitsu-Siemens.com/servers/man/man_us/appi_man/webta_hb.htm.

[1] WebTransactions Concepts and FunctionsIntroduction

Target groupUsers who want information on the functional scope and performance of WebTransactions.ContentsThe manual contains a general description of the concepts behind the product, as well as information on the object concept and the dynamic session procedure.

[2] WebTransactions Template LanguageReference Manual

Target groupUsers who wish to actively create WebTransactions applications. ContentsThe manual contains a description of all the language resources in the template language WTML. When you integrate host applications into the Web, this language allows you to adapt the results of automatic conversion to suit your requirements.

http://manuals.Fujitsu-Siemens.com/servers/man/man_us/appi_man/webta_hb.htm


Related publications

[3] WebTransactions Client APIs for WebTransactionsUser Guide

Target groupUsers who wish to implement Clients for WebTransactions.ContentsThe manual describes all the interfaces WebTransactions provides developing client pro-grams. You can develop not only your own Java clients with the suppiled classes, but alsoclients in any programming language which communicate with WebTransactions via the cli-ent protocol. WebTransactions itself can function as a client of a WebTransactions application.

[4] WebTransactions Connection to openUTM Applications via UPICUser Guide

Target groupUsers who wish to use WebTransactions to connect openUTM dialog applications to the Web.ContentsThe manual describes all the steps required for connecting openUTM dialog applications to the Web. It supplements the introductory manual “Concepts and Functions“ and the Refe-rence Manual “Template Language“ by providing all the information relating to openUTM.

[5] WebTransactions Connection to MVS ApplicationsUser Guide

Target groupUsers who wish to use WebTransactions to connect MVS dialog applications to the Web.ContentsThe manual describes all the steps required for connecting MVS dialog applications to the Web. It supplements the introductory manual “Concepts and Functions“ and the Reference Manual “Template Language“ by providing all the information relating to MVS.

[6] WebTransactions Connection to OSD ApplicationsUser Guide

Target groupUsers who wish to use WebTransactions to connect OSD dialog applications to the Web.ContentsThe manual describes all the steps required for connecting OSD dialog applications to the Web. It supplements the introductory manual “Concepts and Functions“ and the Reference Manual “Template Language“ by providing all the information relating to OSD.



[7] WebTransactions Connection to AS400 ApplicationsUser Guide

Target groupUsers who wish to use WebTransactions to connect AS400 dialog applications to the Web.ContentsThe manual describes all the steps required for connecting AS400 dialog applications to the Web via the 5250 protocol. This manual supplements the introductory manual "Concepts and Functions" and the reference manual "Template Language" and provides all the information relating to AS400.

[8] WebTransactions Connection to UNIX ApplicationsUser Guide

Target groupUsers who wish to use WebTransactions to connect UNIX dialog applications to the Web.ContentsThe manual describes all the steps required for connecting UNIX-dialog applications to the Web via Telnet or the rlogin protocol. This manual supplements the introductory manual "Concepts and Functions" and the reference manual "Template Language" and provides all the information relating to UNIX.

[9] WebTransactionsAccess to Dynamic Web ContentsUser Guide

Target groupUsers who wish to use WebTransactions to access dynamic Web contents.ContentsThe manual describes all the steps required for accessing dynamic web contents via the HTTP protocol. It supplements the introductory manual “Concepts and Functions“ and the Reference Manual “Template Language“ by providing all the information relating to HTTP.



[10] WebTransactions Web Frontend for Web Services and Business ObjectsUser Guide

Target groupUsers who wish to use WebTransactions in conjunction with Web services and business objects.ContentsThis manual describes– the concept of Web frontends for object-oriented backend systems.– the generation of templates for connecting business objects and general Web services

to WebTransactions.– the testing and further development of the Web frontend for business objects and gene-

ral Web services.


Index

.NETBizTaConnection connection properties 330BizTaConnection methods 328BizTaException 331business object class 310business objects in Microsoft Visual

Studio 369calling a web service 146calling methods 314closing a connection 393deploying a web service 143destructor 395generating a web service 143generating a WSDL file 143logging 348methods of the business object class 312properties of the business object class 310service class 324testing a web service 147trace 348user-defined class 325

.NET Compiler 129

.NET component 275

3270 applicationcreating in catalog 111

9750 applicationcreating in catalog 111

Aactivate

WSDL generation (ActiveX) 150active dialog 399, 404

ActiveXactivating WSDL generation 150changing the programmaticID 140closing a connection 392connection properties of

BizTaConnection 343methods of BizTaConnection 341uniqueness of names 137

ActiveX component 275adapt openUTM generation 269adapter concept 29adapter object

service life 281administration 24, 35

locks 105Administration (BizTransactions) 357

main window 361setting language 363settings 362starting 358

All Services view 241analyze

COBOL program units 117openUTM program units 114

array 399automatic redimensioning 233functions for elements 232getting size 228holder class for Java 290index 228initializing 188, 228moving 231querying size 189setting size 191, 230transferring 190


Index

array functions 227ArrayInit 188, 228Asc (predefined function) 207ASCII code

determining for character 207determining for number 207

asynchronous call 372asynchronous message 399attribute 399

setting 189automask template 400automatic redimensioning 233AutoVersion (generation option) 129

Bbase data type 399base directory 400BaseApplicationException 331BCAM application name 400BCAMAPPL 400BCAMAPPL statement 269Begin 188BeginInvoke 314BizTaBusinessObject 285BizTaConnection 327

access methods for Java properties 303connection properties (.NET) 330connection properties (ActiveX) 343connection properties (Java) 307methods in .NET 328methods in ActiveX 341methods in Java 305properties in .NET 327properties in ActiveX 339

BizTaConv.tab (conversion table) 394BizTaCursor (local variable) 203, 279BizTaEvent 296BizTaException 309, 331BizTaFormatEvent 298BizTaGetId 377BizTaIntermediateResult 299BizTaReceiveLength (local variable) 203, 279BizTAsFormat (local variable) 203, 279BizTAsService (local variable) 203, 279

BizTAsServiceNode (local variable) 185, 203, 279

BizTAsStatus (local variable) 203, 279BizTaSup 302BizTaUnknown 169

creating 121BizTaVariant 302BizTransactions

adapter concept 29administration 24, 35business object 30catalog 29, 98concept 21development environment 13entry in registry 261host adapters 13host applications 14installation 261migrating catalogs 110migration 24, 35performance overview 21product structure 13runtime system 13, 37service 30

BizTransactions Administration 357BizTransactions application 400BizTransactions catalog 400

9750/3270 109creating 109importing service data 113, 119openUTM-UPIC 109reusing 110

BizTransactions runtime systemconfiguring 273

BizTransactions Studio 26calling 96checking the environment 268configuring 267main window 97setting options 54


Index

BizTransactions Wizard 36, 41calling 42creating a business object 47creating a catalog 45creating a host application 46creating a method 48generating a business object 49locked object 44recording a dialog 49

BO see business objectbrowser 400browser display print 400browser platform 400buffer 33, 401

adding to services 58catalog element 33defining on import 120length 33size on import 120

business object 30, 401catalog object 30checking name 137creating 47, 123creating (example) 61creating (procedure) 38creating report file 151defining method 124defining method (example) 63defining property 124generating 49, 131in Microsoft Visual Studio 369logging at runtime 348methods 279name check 126properties 285, 310, 333report 152retrieving intermediate results 380selecting 47testing 50threads 395

business object class 276, 401.NET 310access methods for Java properties 285BizTaSup 302events 322generating 131Java 285local variables 279methods for .NET 312methods for Java 288methods for Visual Basic 288structure 277template 278

business object methodreturn codes 356

Ccall

external function 225method for .NET 314web service asynchronous 372

capture database 401capture method, reading formats 249capture procedure (BizTransactions)

see format recognitioncapturing 401Case 188catalog 98

creating 45, 109creating 3270 application 111creating 9750 application 111creating service 121creating UPIC application 111element 32migrating 110object 29selecting 45

catalog element 401buffer 33editing 102field 34parameter 32property 32record 34


Index

catalog object 401business object 30class 31editing 100function 32host application 29service 30

catalog window 98central log file 363CGI (Common Gateway Interface) 402change, statement in the intermediate code 74character as ASCII code 207CheckKey 188Chr (predefined function) 207class 402

BaseApplicationException 331BizTaException 331BizTaFormatEvent 298BizTaIntermediateResult 299business object 401catalog object 31directory 402report 152templates 402Trace 348TraceSwitch 348user-defined 325

Class directory (generation option) 128client 402client computer, declaring 272cluster 402COB2XML 114COBOL

analyze COBOL program units 117converting program to XML 117

code tree structureEdit method window 154, 156

Code view 164, 239colors for locked objects 99COM 402communication 37

BizTaConnection 36runtime 37via data buffers (UPIC) 157

communication object 403communication trace 354Company (generation option) 130compatibility

of data types 193Compatibility (generation option) 130Concat 188concatenate strings 188condition

If statement 189RepeatUntil loop 191While loop 192

configurationBizTransactions runtime system 273BizTransactions Studio 267openUTM application 269record 35

connectionclosing (.NET) 393closing (ActiveX) 392closing (Java) 393deleting 180

conversion table 394conversion tools 403convert

COBOL program to XML 117DRIVE program unit to XML 119FHS format (example) 53FHS formats to XML 115openUTM program unit 114string to date 214

create3270 application in catalog 1119750 application in catalog 111BizTaUnknown service 121business object 123business object (example) 61catalog 109method (example) 63openUTM application (tutorial) 54own service 121start service 121UPIC application in catalog 111


Index

Dd.xmlcopy

converting copy element to XML 118d.xmlprog

converting COBOL program to XML 117daemon 403data

dynamic 405outputting in list 190receiving 190sending 191

data access control 403data type 403

compatibility 193local variable 202

dateformatting 208

DCOM 403define

method 124method (example) 63method parameter (example) 65property (business object) 124

deleteservice nodes 180

deployment.NET web service 143Java web service 142

development environment 13diagnostic tools 345dialog 404

active 404non-synchronized 404, 409passive 404, 411recording 49recording with terminal application 165recording with UPIC application 159, 161synchronized 404, 414types 404

dialog cycle 404dialog step 68, 404

directoryfor generation (class directory) 128specifying (example) 54template files 85, 90trace and log files 354

distinguished name 404document directory 405Domain Name Service (DNS) 405DRIVE program unit

converting to XML 119

Eedit

attributes 102catalog element 102catalog object 100statements in intermediate code 187

edit code 187calling external function 225entering data/parameterizing input 249example 73freely programmable statement 216freely programmable statement for Java 217generating corresponding value

assignments 223generating value assignments 221getting size of array 228importing freely programmable

statements 225initializing arrays 228inserting statements implicitly 244lists 245moving arrays 231outputting data 250replacing literals 219selecting variables 199setting size of array 230show in grid 250tips 196, 249

Edit method (window) 153


Index

Edit method windowcode tree structure 156menu bar 154modeling area 155programming area 155title bar 154toolbar 154

EHLLAPI 405EJB 405element

array 232catalog 32

emulation sessionrecord 35

emulation traceenabling and disabling 363

Emulation view 164, 235EndInvoke 314entry page 405environment check 268Eval 188evaluation operator 405event 295, 322, 336

event class 295event handling 295, 322, 336

Java methods 289exit condition 189ExitMethod 188, 356expression 405external function

calling 225

FFHS 405field 406

catalog element 34combining in list 205selecting 236selecting a variable 201

field file 406FieldLength (predefined function) 207FieldPosition (predefined function) 207FieldToNumber (predefined function) 207, 215filter 406

fld file 406format 406

#format 406*format 406+format 406analyzing of an openUTM application

(example) 53date 208-format 406formatting a date 212formatting numbers 210modeling a flow without format

recognition 185number 207number in string 209recursive 172string 207toDate 214

Format (predefined function) 207, 208format description source 406format recognition

BizTaUnknown 169conflicts 169known format 168new format 168permitted characters 168recognition criterion 168

format type 406FormatAttribute 189freely programmable statement 216

importing 225function 406

catalog object 32for arrays 227predefined 207report 152return code 226

function keysetting 189

FunctionKey 189, 244


Index

Ggenerate

.NET web service 143business object 49, 131corresponding value assignments 223JAR archive 127Java web service 141multiple value assignments 221test interface 49web service 141WSDL file 141

generation option.NET Compiler 129AutoVersion 129Class directory 128Company 130Compatibility 130Java Compiler 129JavaPortlet 130OfficeResearch 130Programming Language 129Project Type 129QueryWebService 130Variant 128VB Compiler 129

getLogFilename 347getSize 189, 228Grid view 164, 237group statements 188

HHelper class 316

instantiating 319methods 318start mode 318

holder class 290holder task 406host 406host adapter 13, 407

logging 354host application 407

analyzing (example) 53catalog object 29creating 46

integrating (operating step) 38report 151selecting 46supported 14

host control object 407host data object 407host data print 407host platform 407Hosts file

modifying 268HTML 408HTTP 407HTTPS 407hypertext 407Hypertext Markup Language (HTML) 408

IIfBreak 189IFG2FLD 114, 115If-Then-Else 189implicitly inserted statements 244import

freely programmable statements 225service data 113service data (example) 58terminal application into catalog 120XML files (example) 58

indexarray 228

initializearray 228

InitLog 353inline WTBean 418input parameter 32input/output format 173insert

Case branch 188comment 190local variable 202property (business object) 200service node 179statement in the intermediate code 75


Index

installation 261host adapters 262JWSDP 263runtime system 262servlet engine 263silent 265via user interface 263

InStr (predefined function) 208intermediate code

calling functions 225changing statements 74editing statements 187freely programmable statement 217generalizing 219inserting statement 75

JJava

access methods for BizTaConnection 303access methods for properties of a business

object class 285BizTaException 309business object class 285calling a web service 142classes 275closing a connection 393connection properties of

BizTaConnection 307deploying a web service 142destructor 395freely programmable statement 217generating a web service 141generating a WSDL file 141methods for event handling 289methods of BizTaConnection 305methods of business object class 288passing parameter in methods 290RMI-capable method 292service classes 285setting log file name 347

Java Bean 408Java Compiler (generation option) 129JavaPortlet (generation option) 130JDK 52

JWSDP 90installing 263

KKDCDEF 408

Llayout

modeling method 180LCase (predefined function) 208LDAP 408Left (predefined function) 208Len (predefined function) 208length

buffer 33list

combining fields 205combining variables 205creating 238editing 238work area 205

list processing 245IFG tables 116

listenerBizTaEvent 296BizTaFormatEvent 298BizTaIntermediateResult 299

literals 408selecting a variable 204

local variableBizTACursor 203, 279BizTaReceiveLength 203, 279BizTasFormat 203, 279BizTAsService 203, 279BizTAsServiceNode 185, 203, 279BizTAsStatus 203, 279data type 202for methods of a business object class 279inserting 202selecting 202

locksadministration 105color for object 99resetting 105


Index

logwriting (.NET) 348writing (ActiveX) 353writing (Java) 347

logfilesetting (Java) 347

logging 345host adapters 354specifying file 362starting (.NET) 349starting (ActiveX) 353starting (Java) 346

LTrim (predefined function) 208

Mmain window (BizTransactions

Administration) 361main window (BizTransactions Studio)

catalog window 98edit window 101menu bar 97status bar 97, 103title bar 97toolbar 97work area 97

master template 408, 416tag 409

menu barEdit method window 154main window 97Record Dialog window 157Record method window 163

messagespecifying logfile 362

message queuing 408method 408

asynchronous call 314, 316call with Helper class 316calling for .NET 314creating 48defining 124defining (example) 63editing code (example) 73exiting 188

global variable 200local variable 202recording 49, 68selecting 48storing intermediate results 386synchronous call 316

method captureAll Services view 241Code view 239Emulation view 235Grid view 237

method parameterdefining 65defining (example) 65

Mid (predefined function) 208migration 24, 35, 110model method 177

adapting layout 180adding service 179closing session 186deleting service nodes 180editing service nodes 181flow without format recognition 185inserting service node 179saving chart 186unknown formats 183

modeling areadeleting service node 180Edit method window 154, 155

modifyHosts file 268

module template 409Move 190, 244move

array 231move format field into parameter 236, 238, 240Move statement

generating multiple 221MoveArrays 190, 231MT tag 409MultioTimeout (system object attribute) 274multitier architecture 409


Index

Nname/value pair 409names

internal check 126non-synchronized dialog 404, 409number

ASCII code 207formatting 207formatting in string 209

NumberToField 215NumberToField (predefined function) 209

Oobject 410

catalog 29color for lock 99locked 44

Office Research web service 387calling 389preparing for use 388

OfficeResearch (generation option) 130one-way web method 373openSEAS 23openUTM 410

adapting generation 269application 410Client 410configuring 269program unit 410RESTART response of user IDs 392service 413

openUTM applicationcreating (tutorial) 54format conversion (example) 53importing service data 113logging 354Record Dialog window 157

openUTM program unit 114operations 403options

BizTransactions Studio 54output parameter 32OutputList 190

Pparameter 410

catalog element 32holder class (Java) 290moving to format field 236, 238, 240selecting variable 199

passive dialog 404, 411password 411performance 274polling 411pool 411posted object 411posting 411predefined function 207

Asc 207Chr 207FieldLength 207FieldPosition 207FieldToNumber 207Format 207, 208InStr 208LCase 208Left 208Len 208LTrim 208Mid 208NumberToField 209Replace 209Right 209RTrim 209toDate 209Trim 209UCase 209

process 411product structure 13programmatic ID 140programming area 74

Edit method window 154, 155Programming Language (generation option) 129project 411Project Type (generation option) 129


Index

property 411business object 285, 310, 333catalog element 32defining (business object) 124inserting (business object) 200LogFilename 346, 352selecting variable 200service class 300, 338

protocol 412protocol file 412provide

metadata from COBOL programs 117PTERM/LTERM statements 269

Qquery

array size 228Query_Clear 378Query_Read 378Query_ReadDataset 379Query_Start 377Query_Status 378QueryWebService (generation option) 130

RReceive 190, 244receive buffer 33recognition criteria 167, 412

ambiguous 169creating 168, 238editing 238permitted characters 168

record 412buffer 33catalog element 34configuring 35dialog with a UPIC application, with

formats 161dialog with a UPIC application, without

formats 159dialog with terminal application 165method (example) 68partial formats and message segments 160

session 364stop 71UPIC application 69

Record Dialog window 157menu bar 157openUTM application 157title bar 157toolbar 157UPIC application 157work area 157

Record method window 163All Services 164Code view 164Emulation view 164Grid view 164menu bar 163terminal application 163title bar 163views 234work area 163

record partial format 160record partial message 160record structure 406recursive format 172

input/output format 173recording 174scrolling screen 172, 173with function key 175without function keys 174

recursive service node 181registry

entry for BizTransactions 261Rem 190Repeat-Until 191Replace (predefined function) 209replace literals 219report file

creating 151ResetSendBuffer 191RESTART response 392return code 226

business object method 356Right (predefined function) 209RTrim (predefined function) 209


Index

runtimebusiness object logging 348communication 37

runtime system 13BizTransactions 37configuration 273installing 262

Ssave

chart 186scalar 412screen number 242scrolling screen 172, 173select

start service (dialog box) 68SelectCase 191Send 191, 244send buffer 33

initializing 191service 30, 413

assign buffer (example) 58BizTaUnknown 121catalog object 30creating own 121displaying formats 242editing recognition criteria 242importing 113reading (examplel) 52report 152screen number 242tree structure (example) 72

service (openUTM) 413service class 276, 280, 300, 324

.NET 324ActiveX 338Java 285, 300properties 300, 338

service data 413from FHS formats 115importing (example) 58provide from COBOL programs 117

service lifeadapter object 281

service node 413deleting 180displaying method 181Edit method window 154inserting 179recursive 181

service report 242servletengine

selecting 263session 414

capturing 364playing back 364recording 364replaying 364WebTransactions 414

setsize of array 230

setLogFilename 347setSize 191, 230Show in grid 236, 240silent installation 265size

getting size of array 228setting size of array 230

SOAP 414Solaris

test interface 136standalone WTBean 418start

BizTransactions Administration 358BizTransactions Wizard 42logging (.NET) 349logging (ActiveX) 353logging (Java) 346

start mode 318start service

creating 121select (dialog box) 68

start template 416Statement 191


Index

statement 216any 191changing 74copying 197cutting 197deleting 198, 240editing 187grouping 188implicitly inserted 244inserting 75, 198, 240moving 197

status barmain window 97, 103

stopmodeling method 186recording 71

stringconverting to date 209, 214converting to lowercase 208converting to uppercase 209determining length 208finding 208formatting 207removing spaces 208replacing 209truncating at left 209truncating at right 208

structurebusiness object class 277

style 414synchronized dialog 404, 414system access control 415system object 415

Ttab

ArrayInit 228setSize 230Status 103

TAC 192, 417tag 415TCP/IP 415

template 416business object class 278class 402master 416object 416start 416

terminal application 416format recognition 167importing metadata into catalog 120logging 354Record method window 163recording a dialog 165

terminal hardcopy printing 416test interface

generating 49testing under Solaris 136

Thread 406thread 395title bar

Edit method window 154main window 97Record Dialog window 157Record method window 163

ToASCII 394toDate (predefined function) 209, 214ToEBCDIC 394toolbar

Edit method window 154main window 97Record Dialog window 157

TPOOL statement 271Trace 348trace

level 363trace and log files 354TraceSwitch 348transaction 416transaction code/TAC 417tree structure

context menu 99Trim (predefined function) 209Try-Catch 192


Index

UUCase (predefined function) 209UDDI 417UPIC 417

communication via data buffers 157particularities when connecting 391

UPIC applicationcreating in catalog 111Record Dialog window 157recording 69recording dialogs with formats 161recording dialogs without formats 159

URI 417URL 417user exits 417user ID 417user-defined class 325UTM see openUTM

Vvalue

calculating 188searching in table 188

value assignment 190generating corresponding 223generating multiple 221

value range of a data type 403variable 417

combining in list 205field 201global 200literals 204local 202method parameter 199property 200selecting 199

Variant (generation option) 128VB Compiler (generation option) 129visibility 417

Wweb server 418web service 21, 418

.NET 143asynchronous call 372calling 142, 146deploying on another host 150deployment (Java) 142generating 141Java 141Office Research 387storing intermediate results 383testing 147

WebTransactions 12, 23session 414

WebTransactions application 418WebTransactions platform 418WebTransactions server 418While 192window

Edit method 153Record Dialog 157Record method 163

Wizard see BizTransactions Wizardwork area

catalog window 98edit window 101for lists 205main window 97Record Dialog window 157Record method window 163

WriteLog 192, 345, 347, 353WSDL 418

activating for ActiveX 150WSDL file

generating 141WTBean 418WTML 419WTML tag 419WTScript 419WWW browser 400WWW server 418


Index

XXML 419

from COBOL program 117from DRIVE program unit 119from FHS formats 115

XML filesimporting 58

XML schema 419

Comments on BizTransactions V7.0Application Integration with Business Objects


Fujitsu Siemens Computers GmbHUser Documentation81730 MunichGermany

Fax: (++49) 700 / 372 00001

e-mail: [email protected]://manuals.fujitsu-siemens.com

CommentsSuggestionsCorrections

✁

Submitted by

mailto:[email protected]

http://manuals.fujitsu-siemens.com

Information on this document On April 1, 2009, Fujitsu became the sole owner of Fujitsu Siemens Compu-ters. This new subsidiary of Fujitsu has been renamed Fujitsu Technology So-lutions.

This document from the document archive refers to a product version which was released a considerable time ago or which is no longer marketed.

Please note that all company references and copyrights in this document have been legally transferred to Fujitsu Technology Solutions.

Contact and support addresses will now be offered by Fujitsu Technology So-lutions and have the format …@ts.fujitsu.com.

The Internet pages of Fujitsu Technology Solutions are available at http://ts.fujitsu.com/... and the user documentation at http://manuals.ts.fujitsu.com.

Copyright Fujitsu Technology Solutions, 2009

Hinweise zum vorliegenden Dokument Zum 1. April 2009 ist Fujitsu Siemens Computers in den alleinigen Besitz von Fujitsu übergegangen. Diese neue Tochtergesellschaft von Fujitsu trägt seit-dem den Namen Fujitsu Technology Solutions.

Das vorliegende Dokument aus dem Dokumentenarchiv bezieht sich auf eine bereits vor längerer Zeit freigegebene oder nicht mehr im Vertrieb befindliche Produktversion.

Bitte beachten Sie, dass alle Firmenbezüge und Copyrights im vorliegenden Dokument rechtlich auf Fujitsu Technology Solutions übergegangen sind.

Kontakt- und Supportadressen werden nun von Fujitsu Technology Solutions angeboten und haben die Form …@ts.fujitsu.com.

Die Internetseiten von Fujitsu Technology Solutions finden Sie unter http://de.ts.fujitsu.com/..., und unter http://manuals.ts.fujitsu.com finden Sie die Benutzerdokumentation.

Copyright Fujitsu Technology Solutions, 2009