Академический Документы
Профессиональный Документы
Культура Документы
March 2008
AIS User Guide and Reference, Version 5.1 AIS5100 Copyright March, 2008, Attunity Ltd. All rights reserved. Primary Authors: David Goldman, Andre Liss, Jeanne Wiegelmann
Contributors: Yishai Hadas, Dror Harari, Tzachi Nissim, Adeeb Massad, Costi Zaboura, Sami Zeitoun, Gadi Farhat, Arie Kremer The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited. The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose. If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Attunit license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer SoftwareRestricted Rights (June 1987). Attunity Ltd., 70 jBlanchard Road, Burlington, MA 01803 The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs. Attunity is a registered trademark of Attunity Ltd and/or its affiliates. Other names may be trademarks of their respective owners. The Programs may provide links to Web sites and access to content, products, and services from third parties. Attunity is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Attunity is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Attunity is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.
Contents
Send Us Your Comments ......................................................................................................................... li Preface ................................................................................................................................................................ liii
Audience...................................................................................................................................................... Organization ............................................................................................................................................... Related Documentation ............................................................................................................................. Conventions ................................................................................................................................................ liii liv liv liv
Part I 1
Binding Configuration
Binding Configuration Overview ......................................................................................................... 3-1 Server Binding .................................................................................................................................... 3-1 Client Binding..................................................................................................................................... 3-2 Setting up Bindings in Attunity Studio............................................................................................... 3-2 Adding Bindings ................................................................................................................................ 3-2 Editing Bindings................................................................................................................................. 3-3 Setting the Binding Environment in Attunity Studio............................................................ 3-3 Defining Remote Machines in a Binding................................................................................. 3-4 Binding Syntax.......................................................................................................................................... 3-6 <remoteMachines> Statement.......................................................................................................... 3-7 <remoteMachine> Statement ........................................................................................................... 3-7 <adapters> Statement........................................................................................................................ 3-8 <adapter> Statement ......................................................................................................................... 3-8 <config> Statement ..................................................................................................................... 3-8 <datasources> Statement .................................................................................................................. 3-9 <datasource> Statement.................................................................................................................... 3-9 <config> Statement .................................................................................................................. 3-11 Sample Binding ..................................................................................................................................... 3-11 Environment Properties ....................................................................................................................... 3-12 Debug................................................................................................................................................ 3-13 General.............................................................................................................................................. 3-14 Language .......................................................................................................................................... 3-15 Modeling .......................................................................................................................................... 3-16 ODBC ................................................................................................................................................ 3-17 OLE DB ............................................................................................................................................. 3-17 Optimizer ......................................................................................................................................... 3-18 Parallel Processing .......................................................................................................................... 3-20 Query Processor .............................................................................................................................. 3-20 Temp Features ................................................................................................................................. 3-22 Transaction....................................................................................................................................... 3-23 Tuning............................................................................................................................................... 3-23 XML................................................................................................................................................... 3-24 Languages ........................................................................................................................................ 3-25 ARA (Arabic) ............................................................................................................................ 3-25 ENG (English)........................................................................................................................... 3-26
vi
FR (French)................................................................................................................................ GER (German) .......................................................................................................................... GREEK (Greek)......................................................................................................................... HEB (Hebrew) .......................................................................................................................... JPN (Japanese) .......................................................................................................................... KOR (Korean) ........................................................................................................................... SCHI (Simple Chinese)............................................................................................................ SPA (Spanish) ........................................................................................................................... TCHI (Traditional Chinese).................................................................................................... TUR (Turkish)........................................................................................................................... Sample Environment Properties ...................................................................................................
3-26 3-26 3-26 3-26 3-26 3-26 3-26 3-27 3-27 3-27 3-27
Setting up Daemons
Daemons..................................................................................................................................................... 4-1 Defining Daemons at Design Time ...................................................................................................... 4-1 Adding a Daemon.............................................................................................................................. 4-2 Editing a Daemon............................................................................................................................... 4-3 Control .......................................................................................................................................... 4-3 Logging......................................................................................................................................... 4-5 Security ......................................................................................................................................... 4-8 Administering Selected User Only Lists.................................................................................. 4-9 Reloading Daemon Configurations at Runtime ............................................................................. 4-10 Editing Daemon Configurations................................................................................................... 4-10 Checking the Daemon Status.............................................................................................................. 4-10 Checking the Daemon Status with Attunity Studio................................................................... 4-10 Starting and Stopping Daemons ........................................................................................................ 4-11 Starting a Daemon in Attunity Studio ......................................................................................... 4-11 Shutting Down a Daemon in Attunity Studio ............................................................................ 4-11 Sample Daemon Configuration.......................................................................................................... 4-11 Adding and Editing Workspaces........................................................................................................ 4-12 Adding a Workspace ...................................................................................................................... 4-12 Editing a Workspace....................................................................................................................... 4-15 General....................................................................................................................................... 4-16 Server Mode.............................................................................................................................. 4-19 Security ...................................................................................................................................... 4-22 Selecting a Binding Configuration................................................................................................ 4-24 Disabling a Workspace................................................................................................................... 4-25 Setting Workspace Authorization ................................................................................................ 4-25
Managing Metadata
Data Source Metadata Overview........................................................................................................... Importing Metadata ................................................................................................................................. Importing Metadata Using an Attunity Studio Import Wizard.................................................. Importing Metadata Using a Standalone Utility ........................................................................... Managing Metadata ................................................................................................................................. Using Attunity Metadata with AIS Supported Data Sources.......................................................... 5-1 5-2 5-2 5-3 5-3 5-4
vii
Extended Native Data Source Metadata......................................................................................... 5-4 Native Metadata Caching ................................................................................................................. 5-4 Procedure Metadata Overview .............................................................................................................. 5-5 Importing Procedure Metadata Using the Import Wizard ............................................................... 5-5 Procedure Metadata Statements ............................................................................................................ 5-6 The <procedure> Statement ............................................................................................................. 5-6 Syntax ........................................................................................................................................... 5-6 <procedure> Attributes ............................................................................................................. 5-7 The <parameters> Statement............................................................................................................ 5-8 Syntax ........................................................................................................................................... 5-8 The <dbCommand> Statement ........................................................................................................ 5-8 Syntax ........................................................................................................................................... 5-8 The <fields> Statement...................................................................................................................... 5-9 Syntax ........................................................................................................................................... 5-9 The <field> Statement ....................................................................................................................... 5-9 Syntax ........................................................................................................................................... 5-9 <field> Attributes..................................................................................................................... 5-10 The <group> Statement.................................................................................................................. 5-10 Syntax ........................................................................................................................................ 5-10 <group> Attributes.................................................................................................................. 5-11 The <variant> Statement................................................................................................................ 5-11 Variant without selector.......................................................................................................... 5-11 Variant with selector................................................................................................................ 5-12 ADD Syntax .............................................................................................................................. 5-13 Usage Notes .............................................................................................................................. 5-13 Resolving Variants in Attunity Studio.................................................................................. 5-13 The <case> Statement ..................................................................................................................... 5-14 Syntax ........................................................................................................................................ 5-14 <case> Attributes ..................................................................................................................... 5-14 ADD Supported Data Types ............................................................................................................... 5-15 ADD Syntax............................................................................................................................................ 5-23 The <table> Statement.................................................................................................................... 5-24 Syntax ........................................................................................................................................ 5-24 Table Attributes........................................................................................................................ 5-25 The <dbCommand> Statement ..................................................................................................... 5-29 Syntax ........................................................................................................................................ 5-29 Examples ................................................................................................................................... 5-29 The <fields> Statement................................................................................................................... 5-29 Syntax ........................................................................................................................................ 5-30 The <field> Statement .................................................................................................................... 5-30 Syntax ........................................................................................................................................ 5-30 Example ..................................................................................................................................... 5-30 Field Attributes......................................................................................................................... 5-30 The <group> Statement.................................................................................................................. 5-35 Syntax ........................................................................................................................................ 5-35 Example ..................................................................................................................................... 5-35 Group Attributes...................................................................................................................... 5-35
viii
The <variant> Statement................................................................................................................ Variant without selector.......................................................................................................... Variant with selector................................................................................................................ Usage Notes .............................................................................................................................. Resolving Variants in Attunity Studio.................................................................................. Variant Attributes .................................................................................................................... The <case> Statement ..................................................................................................................... Syntax ........................................................................................................................................ Case Attributes ......................................................................................................................... The <keys> Statement .................................................................................................................... Syntax ........................................................................................................................................ Example ..................................................................................................................................... The <key> Statement ...................................................................................................................... Syntax ........................................................................................................................................ Key Attributes .......................................................................................................................... The <segments> Statement............................................................................................................ Syntax ........................................................................................................................................ The <segment> Statement.............................................................................................................. Syntax ........................................................................................................................................ Segment Attributes .................................................................................................................. The <foreignKeys> Statement ....................................................................................................... Syntax ........................................................................................................................................ The <foreignKey> Statement......................................................................................................... Syntax ........................................................................................................................................ Example ..................................................................................................................................... foreignKey Attributes.............................................................................................................. The <primaryKey> Statement ....................................................................................................... Syntax ........................................................................................................................................ The <pKeySegments> Statement .................................................................................................. Syntax ........................................................................................................................................ Example ..................................................................................................................................... pKeySegment Attributes.........................................................................................................
5-38 5-38 5-39 5-40 5-40 5-40 5-41 5-41 5-41 5-42 5-42 5-43 5-43 5-43 5-43 5-46 5-46 5-46 5-46 5-46 5-47 5-47 5-47 5-48 5-48 5-48 5-49 5-49 5-49 5-49 5-49 5-50
ix
Update Button .......................................................................................................................... Modelling Tab.................................................................................................................................. Importing Data Source Metadata with the Attunity Import Wizard .......................................... Starting the Import Process............................................................................................................ Selecting the Input Files ................................................................................................................. Applying Filters............................................................................................................................... Selecting Tables ............................................................................................................................... Import Manipulation ...................................................................................................................... Import Manipulation Screen .................................................................................................. Field Manipulation Screen...................................................................................................... Metadata Model Selection.............................................................................................................. Import the Metadata ....................................................................................................................... Working with Application Adapter Metadata................................................................................. Adapter Metadata General Properties ......................................................................................... Adapter Metadata Schema Records ............................................................................................. Editing an Existing Schema Definition ................................................................................. Adapter Metadata Interactions ..................................................................................................... Editing an Existing Interaction .............................................................................................. Interaction Advanced Tab ...................................................................................................... Working with Procedure Metadata .................................................................................................... Manually Creating Procedure Metadata ..................................................................................... Managing Procedure Metadata..................................................................................................... Importing Procedure Metadata.....................................................................................................
6-11 6-12 6-14 6-14 6-15 6-17 6-19 6-19 6-20 6-21 6-27 6-29 6-30 6-31 6-32 6-34 6-34 6-35 6-36 6-36 6-37 6-37 6-37
Handling Arrays
Overview of Handling Arrays ............................................................................................................... 7-1 Representing Metadata ........................................................................................................................... 7-1 Methods of Handling Arrays ................................................................................................................. 7-5 Columnwise Normalization ............................................................................................................. 7-5 Virtual Tables...................................................................................................................................... 7-7 Virtual Views ................................................................................................................................... 7-10 Sequential Flattening (Bulk Load of Array Data)....................................................................... 7-11 ADO/OLE DB Chapters ................................................................................................................ 7-14 Chapter Handling in Query and Database Adapters ......................................................... 7-16 XML................................................................................................................................................... 7-17
Using SQL
Overview of Using SQL .......................................................................................................................... Batching SQL Statements ....................................................................................................................... Hierarchical Queries ................................................................................................................................ Generating Hierarchical Results Using SQL .................................................................................. Accessing Hierarchical Data Using SQL......................................................................................... Examples ...................................................................................................................................... Flattening Hierarchical Data Using SQL ........................................................................................ Using an Alias ............................................................................................................................. Examples ...................................................................................................................................... Using Virtual Tables to Represent Hierarchical Data................................................................... 8-1 8-1 8-2 8-3 8-4 8-4 8-5 8-6 8-6 8-9
Creating Virtual Tables ........................................................................................................... Hierarchical Queries From an Application ................................................................................. Drill-down Operations in an ADO Application.................................................................. Drill-down Operations in an ODBC Application................................................................ ODBC Drill-down Operations Using RDO .......................................................................... ODBC Drill-down Operations Using C ................................................................................ Drill-down Operations in a Java Application...................................................................... Copying Data From One Table to Another ...................................................................................... Passthru SQL.......................................................................................................................................... For a Specific SQL Statement......................................................................................................... Via ADO .................................................................................................................................... Via RDO and DAO .................................................................................................................. For all SQL During a Session......................................................................................................... Via ADO/OLE DB ................................................................................................................... Via ODBC .................................................................................................................................. Passthru Queries as Part of an SQL Statement ........................................................................... Writing Queries Using SQL ................................................................................................................ Writing Efficient SQL ..................................................................................................................... Locking Considerations ....................................................................................................................... Locking Modes ................................................................................................................................ Optimistic Locking .................................................................................................................. Pessimistic Locking.................................................................................................................. No Locking................................................................................................................................ ODBC Locking Considerations ..................................................................................................... ADO Locking Considerations ....................................................................................................... Managing the Execution of Queries over Large Tables ................................................................. Optimizing Outer Joins........................................................................................................................ Limitations ....................................................................................................................................... Query Optimization........................................................................................................................ Property ............................................................................................................................................ Changing the Property............................................................................................................
8-10 8-10 8-11 8-11 8-12 8-14 8-16 8-17 8-17 8-18 8-18 8-19 8-20 8-20 8-20 8-21 8-22 8-22 8-23 8-23 8-23 8-23 8-23 8-23 8-24 8-24 8-25 8-26 8-26 8-26 8-26
xi
Logging Web Service Activities.......................................................................................................... Changing the Log File Location .................................................................................................... Changing the Error Message Level .............................................................................................. Changing the Error Message Format ...........................................................................................
Part II 10
Attunity Connect
11
xii
12
13
14
xiii
15
16
Setting Up Adapters
Setting up Adapters Overview ........................................................................................................... Working with Adapters........................................................................................................................ Adding Application Adapters....................................................................................................... Configuring Application Adapters .............................................................................................. Testing Application Adapters ....................................................................................................... 16-1 16-1 16-1 16-2 16-3
17
Part III 18
Attunity Stream
xiv
19
20
xv
Production Metadata Change Procedure .................................................................................. 20-21 Migration from XML-based CDC .................................................................................................... 20-21
21
Part IV 22
Attunity Federate
23
xvi
Metadata Considerations ..................................................................................................................... Defining Tables ..................................................................................................................................... Creating Synonyms............................................................................................................................... Defining Stored Procedures ................................................................................................................ Creating Views....................................................................................................................................... Using a Virtual Database .....................................................................................................................
24
Part V 25
Attunity Studio
xvii
Part VI 26
27
xviii
28
Managing Security
Overview of Attunity Security ........................................................................................................... Managing Design Time Security........................................................................................................ Local Access to AIS Design-Time Resources .............................................................................. Remote Access to AIS Design-Time Resources .......................................................................... Design Roles ............................................................................................................................. Assigning Design Roles .......................................................................................................... Password Handling in Attunity Studio ....................................................................................... Setting Up the Password Caching Policy in Attunity Studio............................................ Assigning Authorization Rights to a Workspace................................................................ Setting Up a Master Password for a User............................................................................. Managing Runtime Security ............................................................................................................... User Profiles ..................................................................................................................................... Setting a Master Password for a User Profile ...................................................................... Using a Client User Password................................................................................................ Using a Server User Profile..................................................................................................... Managing a User Profile in Attunity Studio ............................................................................... Adding a User .......................................................................................................................... Add Authenticators ............................................................................................................... Add Encryption Keys ............................................................................................................ Editing a User Profile ............................................................................................................ Remove an Authenticator or Encryption key .................................................................... Client Authentication ................................................................................................................... Client Authentication for Thin Clients ............................................................................... Client Authentication for Fat Clients .................................................................................. Client Authorization and Access Restriction ............................................................................ Restricting Access to a User by Login User Name............................................................ Restricting Access to Data with a Virtual Database.......................................................... Transport Encryption ................................................................................................................... Encrypting Network Communications...................................................................................... Setting a Client Encryption Protocol ................................................................................... Configuring Encrypted Communication............................................................................ Configuring the Encryption Key on the Server Machine................................................. Firewall Support............................................................................................................................ Accessing a Server through a Firewall....................................................................................... Selecting a Port Range for Workspace Servers .................................................................. Accessing a Server Using Fixed NAT ................................................................................. Dynamic Credentials .................................................................................................................... Providing Credentials in the Connection String ............................................................... Interactively Prompting for Credentials............................................................................. Setting Up Impersonation............................................................................................................ Setting Up Impersonation for DB2 ...................................................................................... Granting Daemon Administration Rights to Users ................................................................. Granting Workspace Administration Rights to Users............................................................. 28-1 28-1 28-1 28-2 28-2 28-2 28-3 28-3 28-4 28-4 28-5 28-6 28-6 28-7 28-7 28-9 28-9 28-11 28-12 28-13 28-14 28-14 28-15 28-15 28-15 28-15 28-17 28-17 28-18 28-18 28-19 28-20 28-22 28-23 28-24 28-24 28-25 28-25 28-26 28-26 28-28 28-28 28-30
xix
29
Backing Up AIS
Overview of the AIS Backup Process................................................................................................ Backing Up and Restoring AIS Server Installation........................................................................ Backing Up and Restoring AIS Server Metadata............................................................................ Backing Up and Restoring AIS Server Scripts ................................................................................ Backing Up and Restoring AIS Server Data .................................................................................... Backing Up and Restoring AIS Studio Metadata ........................................................................... 29-1 29-1 29-2 29-3 29-3 29-3
30
Transaction Support
Overview................................................................................................................................................. Using Attunity Connect as a Stand-alone Transaction Coordinator ........................................... Attunity Connect Data Source Driver Capabilities........................................................................ Data Sources That Do Not Support Transactions....................................................................... Data Sources with One-Phase Commit Capability .................................................................... Data Sources with Two-Phase Commit Capability.................................................................... Relational Database Procedures.................................................................................................... Distributed Transactions...................................................................................................................... Transaction Log File........................................................................................................................ CommitConfirm Table ................................................................................................................... Recovery .................................................................................................................................................. Recovery Utility Toolbar ................................................................................................................ Platform Specific Information ............................................................................................................ 30-1 30-2 30-3 30-3 30-3 30-4 30-4 30-4 30-5 30-6 30-7 30-9 30-9
31
Troubleshooting in AIS
Troubleshooting Overview.................................................................................................................. Product Flow Maps ............................................................................................................................... Local Data Access Scenario............................................................................................................ Remote Data Access Scenario........................................................................................................ Using the Product Flow Maps for Troubleshooting ....................................................................... SQL Application/SQL API Issues (A1, B1) ................................................................................. ADO/OLEDB ........................................................................................................................... JDBC........................................................................................................................................... SQL API Issues/Query Processor Issues (A2, B2F) ................................................................... Troubleshooting Methods ................................................................................................................... Using the NAV_UTIL CHECK SERVER Utility ......................................................................... Using the NAV_UTIL CHECK DATASOURCE Utility ............................................................ Using Trace Log Files ..................................................................................................................... Log Traces ................................................................................................................................. Using Extended Logging Options ................................................................................................ New Log Entries.............................................................................................................................. Identifying Nodes ......................................................................................................................... Configuring the Optimizer Trace File................................................................................. Reading the Log............................................................................................................................. Configuring the Extended Logging Option ....................................................................... Configuring Advanced Environment Parameters ................................................................... Common Errors and Solutions ......................................................................................................... 31-1 31-1 31-2 31-3 31-5 31-5 31-5 31-6 31-6 31-6 31-6 31-7 31-8 31-8 31-9 31-9 31-10 31-10 31-11 31-11 31-12 31-13
xx
Part VII 32
Utilities
33
34
xxi
36
37
xxii
Executing SQL Statements.................................................................................................... NavSQL Commands.............................................................................................................. EXPORT.......................................................................................................................................... GEN_ARRAY_TABLES................................................................................................................ IMPORT.......................................................................................................................................... IRPCDCMD.................................................................................................................................... LOCAL_COPY............................................................................................................................... PASSWORD ................................................................................................................................... PROTOGEN ................................................................................................................................... REGISTER ...................................................................................................................................... SERVICE ......................................................................................................................................... SVC.................................................................................................................................................. TEST ................................................................................................................................................ UPDATE ......................................................................................................................................... Removing Metadata Statistics .............................................................................................. UPD_DS.......................................................................................................................................... UPD_SEC........................................................................................................................................ VERSION........................................................................................................................................ VERSION_HISTORY .................................................................................................................... VIEW ............................................................................................................................................... XML................................................................................................................................................. XML Samples..........................................................................................................................
37-14 37-15 37-16 37-19 37-20 37-21 37-21 37-22 37-22 37-22 37-22 37-23 37-23 37-23 37-23 37-25 37-25 37-26 37-26 37-26 37-28 37-29
38
Part VIII 39
xxiii
Transaction Support.............................................................................................................................. Security.................................................................................................................................................... Data Types .............................................................................................................................................. Configuration Properties ................................................................................................................... Platform-specific Information .......................................................................................................... UNIX Platforms ............................................................................................................................. Verifying Environment Variables........................................................................................ Relinking to the Adabas Driver on UNIX Platforms ........................................................ Accessing 64 Bit Adabas ....................................................................................................... z/OS Platforms.............................................................................................................................. Specifying the Adabas SVC .................................................................................................. Configuring AIS to Run in multiClient Mode ................................................................... Defining an Adabas Data Source..................................................................................................... Defining the Adabas Data Source Connection ......................................................................... Configuring the Adabas Data Source Properties ..................................................................... Setting Up Adabas Data Source Metadata (Using the Import Manager) ................................. Selecting the DDM Declaration files .......................................................................................... Applying Filters............................................................................................................................. Selecting Tables ............................................................................................................................. Import Manipulation .................................................................................................................... Import Manipulation Screen ................................................................................................ Field Manipulation Screen.................................................................................................... Metadata Model Selection............................................................................................................ Import the Metadata ..................................................................................................................... Setting Up Adabas Data Source Metadata (Traditional Method) .............................................. Importing Attunity Metadata from DDM Files ........................................................................ Exporting Predict Metadata into Adabas ADD........................................................................ Testing the Adabas Data Source.......................................................................................................
39-8 39-8 39-8 39-10 39-12 39-12 39-12 39-13 39-13 39-13 39-13 39-13 39-17 39-17 39-18 39-19 39-19 39-22 39-23 39-23 39-24 39-25 39-31 39-33 39-34 39-34 39-35 39-35
40
xxiv
z/OS .................................................................................................................................................. Defining an ODBCINI file ...................................................................................................... Defining the Data Source Connection................................................................................... Configuring the Data Source................................................................................................ OS/400 ............................................................................................................................................ Defining the Data Source Connection................................................................................. Configuring the Data Source................................................................................................ UNIX and Windows ..................................................................................................................... Defining the Data Source Connection................................................................................. Configuring the Data Source................................................................................................
40-8 40-8 40-9 40-10 40-11 40-11 40-11 40-13 40-13 40-13
41
42
xxv
43
44
45
xxvi
Selecting a PCB......................................................................................................................... DLI Samples.............................................................................................................................. Configuration Properties ..................................................................................................................... IMS/DB DLI Configuration Properties ....................................................................................... IMS/DB DBCTL Configuration Properties ................................................................................. IMS/DB DBDC Configuration Properties................................................................................... Configuring Advanced Data Source Properties ......................................................................... Transaction Support.............................................................................................................................. Using Attunity Connect with One-phase Commit..................................................................... Hospital Database Example ................................................................................................................ Defining the IMS/DB DLI Data Source ......................................................................................... Defining the IMS/DB DLI Data Source Connection................................................................ Configuring the IMS/DB DLI Data Source............................................................................... Setting Up the Daemon Workspace ........................................................................................... Defining the IMS/DB DBCTL Data Source .................................................................................. Defining the IMS/DB DBCTL Data Source Connection ......................................................... Configuring the IMS/DB DBCTL Data Source......................................................................... Accessing IMS/DB Data under CICS......................................................................................... Defining the IMS/DB DBDC Data Source .................................................................................... Defining the IMS/DB DBDC Data Source Connection ........................................................... Configuring the IMS/DB DBDC Data Source .......................................................................... Accessing IMS/DB Data under IMS/TM.................................................................................. Setting Up IMS/DB Metadata ........................................................................................................... Selecting the Input Files ............................................................................................................... Applying Filters............................................................................................................................. Selecting Tables ............................................................................................................................. Matching DBD to COBOL............................................................................................................ Import Manipulation .................................................................................................................... Import Manipulation Screen ................................................................................................ Field Manipulation Screen.................................................................................................... Metadata Model Selection............................................................................................................ Import the Metadata .....................................................................................................................
45-6 45-6 45-7 45-7 45-7 45-8 45-8 45-8 45-9 45-9 45-11 45-11 45-12 45-12 45-13 45-13 45-14 45-15 45-16 45-16 45-16 45-17 45-18 45-19 45-20 45-22 45-22 45-23 45-23 45-25 45-31 45-33
46
xxvii
Locking Levels ................................................................................................................................. Isolation Levels ................................................................................................................................ Security.................................................................................................................................................... Data Types .............................................................................................................................................. Defining an Informix Data Source .................................................................................................... Defining the Informix Data Source Connection ......................................................................... Configuring the Informix Data Source Properties ................................................................... Testing the Informix Data Source .................................................................................................... Sample Log File Explained ..........................................................................................................
47
48
xxviii
49
50
51
xxix
Security.................................................................................................................................................. Data Types ............................................................................................................................................ Platform-Specific Information.......................................................................................................... UNIX Platforms ............................................................................................................................. Verifying Environment Variables on UNIX Platforms .................................................... Linking to Oracle Libraries on UNIX Platforms................................................................ OpenVMS Platform....................................................................................................................... Verifying Environment Variables on OpenVMS Platforms ............................................ Linking to Oracle Libraries on OpenVMS Platforms ....................................................... Defining the Oracle Data Source ..................................................................................................... Defining the Oracle Data Source Connection ........................................................................... Configuring the Oracle Data Source Properties ....................................................................... Configuring Table and Column Names to be Case Sensitive................................................. Checking Oracle Environment Variables .................................................................................. Testing the Oracle Data Source......................................................................................................... Sample Log File .............................................................................................................................
51-11 51-11 51-13 51-13 51-13 51-13 51-13 51-13 51-14 51-14 51-14 51-15 51-16 51-17 51-17 51-18
52
53
xxx
Data Types .............................................................................................................................................. Defining the RMS Data Source .......................................................................................................... Defining the RMS Data Source Connection ................................................................................ Configuring the RMS Data Source ............................................................................................... Setting Up the RMS Data Source Metadata with the Import Manager...................................... Selecting the Input Files ................................................................................................................. Applying Filters............................................................................................................................... Selecting Tables ............................................................................................................................... Import Manipulation .................................................................................................................... Import Manipulation Screen ................................................................................................ Field Manipulation Screen.................................................................................................... Metadata Model Selection............................................................................................................ Import the Metadata ..................................................................................................................... Importing Attunity Metadata Using the RMS_CDD Import Utility ........................................
53-3 53-3 53-3 53-4 53-5 53-6 53-8 53-9 53-10 53-10 53-12 53-17 53-19 53-20
54
55
56
xxxi
Configuration Properties ..................................................................................................................... Transaction Support.............................................................................................................................. Data Types .............................................................................................................................................. Platform-Specific Information............................................................................................................ Verifying Environment Variables on UNIX Platforms.............................................................. Defining the Sybase Data Source ...................................................................................................... Defining the Sybase Data Source Connection............................................................................. Configuring the Sybase Data Source Properties......................................................................... Checking Sybase Environment Variables....................................................................................
57
58
59
xxxii
Defining a VSAM Data Source .......................................................................................................... Defining the VSAM Data Source Connection ............................................................................. Defining the VSAM (CICS) Data Source Connection ................................................................ Configuring the VSAM Data Source Properties ......................................................................... Configuring the VSAM (CICS) Data Source Properties .......................................................... Setting Up the VSAM Data Source Metadata................................................................................ Selecting the COBOL files ............................................................................................................ Applying Filters............................................................................................................................. Selecting Tables ............................................................................................................................. Import Manipulation .................................................................................................................... Import Manipulation Screen ................................................................................................ Field Manipulation Screen.................................................................................................... Create VSAM Indexes................................................................................................................... Assigning File Names................................................................................................................... Assigning Index File Names........................................................................................................ Metadata Model Selection............................................................................................................ Importing the Metadata ...............................................................................................................
59-6 59-6 59-7 59-9 59-10 59-11 59-12 59-14 59-16 59-16 59-17 59-18 59-24 59-25 59-26 59-27 59-29
Part IX 60
61
xxxiii
Parameter Descriptions .................................................................................................................. Transaction Support.............................................................................................................................. Security.................................................................................................................................................... Data Types .............................................................................................................................................. Platform-specific Information ............................................................................................................ Windows Platforms and AIS Procedures (ADO Considerations) ........................................... HP NonStop Platforms and Attunity Connect Procedures ...................................................... Load Modules and DLLs on MVS ................................................................................................ Descriptors on OpenVMS ............................................................................................................ OS/400 Issues ................................................................................................................................ Defining the Procedure Data Source............................................................................................... Defining the Procedure Data Source Connection..................................................................... Configuring the Procedure Data Source.................................................................................... Setting Up Procedure Data Source Metadata................................................................................. Defining Return Values................................................................................................................ Defining Input and Output Arguments .................................................................................... Testing the Procedure Data Source .................................................................................................. Executing a Procedure ........................................................................................................................
61-3 61-7 61-7 61-7 61-7 61-7 61-8 61-9 61-10 61-10 61-10 61-10 61-10 61-11 61-12 61-13 61-16 61-16
62
Part X
Adapters Reference
xxxiv
63
64
65
66
xxxv
Setting Up Legacy Application Metadata......................................................................................... Importing Attunity Metadata from PCML Files ........................................................................ Defining Interactions and Records ............................................................................................... Defining Interaction Properties.............................................................................................. Defining Schema Records ....................................................................................................... Configuring a Trigger for the Legacy Plug Adapter................................................................
67
68
Part XI 69
Database Adapter
Overview................................................................................................................................................. Supported Versions and Platforms .............................................................................................. Supported Features ......................................................................................................................... Configuration Properties ..................................................................................................................... Metadata.................................................................................................................................................. 69-1 69-1 69-1 69-2 69-2
xxxvi
Security.................................................................................................................................................... SQL Interaction Types .......................................................................................................................... Database Query Interaction ........................................................................................................... Database Modification Interaction ............................................................................................... Stored Procedure Call Interaction................................................................................................. Transaction Support.............................................................................................................................. Interaction Parameters.......................................................................................................................... Defining the Database Adapter.......................................................................................................... Defining the Database Adapter Connection ............................................................................... Configuring the Database Adapter .............................................................................................. Configuring Database Adapter Interactions.................................................................................... Automatically Creating Interactions ............................................................................................ Manually Creating Interactions .................................................................................................... Specifying Parameters ........................................................................................................... Testing Database Adapter Interactions ........................................................................................... Creating SQL Queries ........................................................................................................................
69-2 69-2 69-2 69-3 69-3 69-4 69-4 69-4 69-5 69-5 69-5 69-6 69-8 69-20 69-21 69-21
70
Query Adapter
Overview................................................................................................................................................. Supported Versions and Platforms .............................................................................................. Features Highlights......................................................................................................................... Metadata.................................................................................................................................................. Security.................................................................................................................................................... Transaction Support.............................................................................................................................. Predefined Interactions........................................................................................................................ callProcedure Interaction ............................................................................................................... Input Record ............................................................................................................................. Output Record .......................................................................................................................... ddl Interaction ................................................................................................................................. Input Record ............................................................................................................................. Output Record .......................................................................................................................... getSchema Interaction .................................................................................................................... Input Record ............................................................................................................................. query Interaction ............................................................................................................................. Input Record ............................................................................................................................. Output Record .......................................................................................................................... Output Data Formats............................................................................................................... setErrorAction Interaction ........................................................................................................... Input Record ........................................................................................................................... update Interaction ......................................................................................................................... Input Record ........................................................................................................................... Output Record ........................................................................................................................ Interactions for Internal Use ........................................................................................................ Using the Query Adapter................................................................................................................... 70-1 70-1 70-1 70-1 70-2 70-2 70-2 70-2 70-2 70-3 70-4 70-4 70-5 70-6 70-6 70-8 70-8 70-9 70-9 70-13 70-13 70-13 70-13 70-14 70-15 70-16
xxxvii
71
Part XII 72
73
74
xxxviii
Transaction Support.............................................................................................................................. Data Types .............................................................................................................................................. Security.................................................................................................................................................... Platform Specific Information ............................................................................................................ Configuring the Adabas CDC............................................................................................................. Identifying the Adabas CDC in the Adabas System.................................................................. Defining Adabas CDC in Attunity Studio....................................................................................... Configuring the Data Source ......................................................................................................... Configuring the CDC Service........................................................................................................
75
76
77
xxxix
Change Metadata................................................................................................................................... Transaction Support.............................................................................................................................. Data Types .............................................................................................................................................. Security.................................................................................................................................................... Platform-specific Information ............................................................................................................ Setting Up Enscribe to use the Attunity Enscribe CDC Agent .................................................... Adding the Enscribe Agent to Attunity Studio............................................................................... Configuring the Data Source ......................................................................................................... Configuring the CDC Service........................................................................................................
78
79
xl
User Defined Data Types (UDT)................................................................................................... Security.................................................................................................................................................... Platform Specific Information ............................................................................................................ Setting up the SQL Server CDC in Attunity Studio ...................................................................... Enabling MS SQL Replication ......................................................................................................... MS SQL Server 2000 Replication................................................................................................. MS SQL Server 2005 Replication................................................................................................. Configuring Security Properties ...................................................................................................... Setting up Log On Information ........................................................................................................ Setting up the Database ..................................................................................................................... MS SQL Server 2000 Settings....................................................................................................... MS SQL Server 2005 Settings....................................................................................................... Setting Up the TLOG Miner (LGR) ................................................................................................. Call the LGR Service Interface..................................................................................................... Configuring the Template Input File ......................................................................................... Registering the TLOG Miner (LGR) Service.............................................................................. Setting the Recovery Policy ......................................................................................................... Testing Attunitys Microsoft SQL Server CDC Solution............................................................. Handling Metadata Changes ............................................................................................................ Environment Verification .................................................................................................................. Verify the MS SQL Server Version ............................................................................................. Ensure that the Service is Registered ......................................................................................... Verify that the LGR Service is Running ..................................................................................... Viewing the Service Greetings .................................................................................................... Check the Output Files .................................................................................................................
79-7 79-8 79-8 79-8 79-11 79-11 79-11 79-12 79-12 79-13 79-13 79-14 79-14 79-14 79-15 79-18 79-18 79-19 79-19 79-20 79-20 79-21 79-22 79-23 79-23
80
81
xli
82
83
84
xlii
Configuring the Logger........................................................................................................................ Creating the Logstream.................................................................................................................. Managing the MVS Logstream .............................................................................................. Creating the CDC$PARM Data Set .............................................................................................. Updating Jobs and Scripts ............................................................................................................. Updating Jobs for Activating CDC JRNAD ......................................................................... Updating Jobs for Using the Logical Transaction Manager .............................................. Update the REXX Scripts ........................................................................................................ Setting up the VSAM Batch Agent in Attunity Studio.................................................................. Configuring the Data Source ......................................................................................................... Configuring the CDC Service........................................................................................................
84-5 84-5 84-5 84-6 84-6 84-6 84-6 84-7 84-7 84-7 84-7
Part XIII 85
Interface Reference
xliii
Calling the Transaction ................................................................................................................ Transaction Output ....................................................................................................................... CICS Connection Pooling under CICS ........................................................................................... Using Connection Pooling under CICS ..................................................................................... CICS Connection Pool Flow ........................................................................................................ Control Operations Flow ...................................................................................................... 3GL Operations Flow ............................................................................................................ ATTCALL Program Interface...................................................................................................... COMMAREA.......................................................................................................................... Control Protocol ..................................................................................................................... 3GL Protocol ........................................................................................................................... ATTCNTRL Program ................................................................................................................... ATTCNTRL Parameters........................................................................................................ Setting up 3GL under CICS ......................................................................................................... Create a Log File..................................................................................................................... CICS Definitions..................................................................................................................... IMS/TM as a Client Invoking an Application Adapter (z/OS Only) ..................................... Setting Up the IBM z/OS Machine............................................................................................. Setting Up a Call to the Transaction........................................................................................... Calling the Transaction ................................................................................................................ C Call ....................................................................................................................................... COBOL Call ............................................................................................................................ The Transaction Output ...............................................................................................................
85-25 85-25 85-26 85-26 85-26 85-27 85-28 85-28 85-28 85-29 85-30 85-31 85-32 85-33 85-33 85-33 85-33 85-34 85-34 85-35 85-36 85-36 85-37
86
87
xliv
JDBC API Conformance....................................................................................................................... Supported Interfaces....................................................................................................................... Supported Classes ......................................................................................................................... DataSource Properties .................................................................................................................. ConnectionPool Data Source and XADatasource Interface Properties................................. Connection Pooling Properties ................................................................................................... JDBC Client Interface......................................................................................................................... JDBC Sample Program .......................................................................................................................
88
89
xlv
OLE DB Data Types ............................................................................................................................ Mapping SQL Data Types to OLE DB Data Types .................................................................. ADO Conformance Level .................................................................................................................. OLE DB Interfaces and Methods ................................................................................................ OLE DB Properties ........................................................................................................................ Initialization Properties......................................................................................................... Data Source Properties .......................................................................................................... Data Source Information Properties.................................................................................... Session Properties .................................................................................................................. Rowset Properties .................................................................................................................. Specific Properties..................................................................................................................
89-10 89-12 89-12 89-13 89-15 89-15 89-15 89-16 89-17 89-17 89-19
90
Part XIV
Appendixes
xlvi
xlvii
CREATE INDEX Statement ........................................................................................................... Keywords and Options .................................................................................................................. VIEW Statements................................................................................................................................... CREATE VIEW Statement ............................................................................................................. Keywords and Options .................................................................................................................. DROP VIEW Statement .................................................................................................................. Keywords and Options .................................................................................................................. Stored Procedure Statements .............................................................................................................. CREATE PROCEDURE Statement ............................................................................................... Keywords and Options .................................................................................................................. DROP PROCEDURE Statement.................................................................................................... Keywords and Options .................................................................................................................. CALL Statement .............................................................................................................................. Keywords and Options .................................................................................................................. Synonym Statements ............................................................................................................................ CREATE SYNONYM Statement ................................................................................................... Keywords and Options .................................................................................................................. DROP SYNONYM Statement........................................................................................................ Keywords and Options .................................................................................................................. GRANT Statement ................................................................................................................................ Keywords and Options .................................................................................................................. Transaction Statements......................................................................................................................... BEGIN Statement ............................................................................................................................ COMMIT Statement........................................................................................................................ ROLLBACK Statement ................................................................................................................... Constant Formats ............................................................................................................................ Expressions....................................................................................................................................... Operator Precedence ............................................................................................................... SIngle Quotation Marks in String Expressions.................................................................... Functions................................................................................................................................................. Aggregate Functions....................................................................................................................... Additional Information........................................................................................................... Conditional Functions .................................................................................................................... Data Type Conversion Functions ................................................................................................. Date and Time Functions ............................................................................................................... Date Format .............................................................................................................................. Time Format.............................................................................................................................. Timestamp Format................................................................................................................... Date Comparison Semantics .................................................................................................. Numeric Functions and Arithmetic Operators........................................................................... String Functions............................................................................................................................... Parameters............................................................................................................................................... Search Conditions and Comparison Operators............................................................................... Keywords and Options .................................................................................................................. Passthru Query Statements (bypassing Query Processing) .......................................................... Keywords and Options .................................................................................................................. Reserved Keywords ..............................................................................................................................
B-31 B-31 B-32 B-32 B-33 B-34 B-34 B-34 B-34 B-35 B-37 B-37 B-37 B-37 B-39 B-39 B-39 B-40 B-40 B-41 B-41 B-41 B-41 B-42 B-42 B-42 B-42 B-43 B-43 B-43 B-44 B-44 B-45 B-46 B-47 B-47 B-47 B-47 B-49 B-49 B-50 B-52 B-52 B-53 B-56 B-57 B-58
xlviii
D E
COBOL Data Types to Attunity Data Types Editing XML Files in Attunity Studio
Preparing to Edit XML Files in Attunity Studio ............................................................................... Making Changes to the XML File ........................................................................................................ Remove Objects ................................................................................................................................. Add DTD Information...................................................................................................................... Edit Namespaces ............................................................................................................................... Add Elements and Attributes.......................................................................................................... Replace an Element ........................................................................................................................... E-1 E-2 E-2 E-2 E-3 E-5 E-5
Index
xlix
Attunity welcomes your comments and suggestions on the quality and usefulness of this publication. Your input is an important part of the information used for revision.
Did you find any errors? Is the information clearly presented? Do you need more information? If so, where? Are the examples correct? Do you need more examples? What features did you like most about this manual?
If you find any errors or have any other suggestions for improvement, please indicate the title and part number of the documentation and the chapter, section, and page number (if available). You can send comments to us in the following ways:
Electronic mail: support@attunity.com FAX: (781) 213-5240. Attn: Documentation and Training Manager Postal service:
Attunity Incorporated Documentation and Training Manager 70 Blanchard Road Burlington, MA 01803 USA If you would like a reply, please give your name, address, telephone number, and electronic mail address (optional). If you have problems with the software, please contact your local Attunity Support Services.
li
lii
Preface
This guide is the primary source of user and reference information on AIS (Attunity Integration Suite), which enables integration of data across platforms and formats. This document applies to the IBM z/OS Series, OS/400, OpenVMS, UNIX, and Windows platforms. This preface covers the following topics:
Audience
This manual is intended for Attunity integration administrators who perform the following tasks:
Installing and configuring the Attunity Integration Suite Diagnosing errors Using AIS to access data
Note:
You should understand the fundamentals of data base use and Microsoft screens operating system before using this guide to install or administer the Attunity Integration Suite (AIS).
liii
Organization
This document contains: Part I, "Getting Started with AIS" Part II, "Attunity Connect" Part III, "Attunity Stream" Part IV, "Attunity Federate" Part V, "Attunity Studio" Part VI, "Operation and Maintenance" Part VII, "Utilities" Part VIII, "Data Source Reference" Part IX, "Procedure Data Source Reference" Part X, "Adapters Reference" Part XI, "Non-Application Adapters Reference" Part XII, "CDC Agents Reference" Part XIII, "Interface Reference" Part XIV, "Appendixes"
Related Documentation
Printed documentation is available for at the Attunity Web site:
http://www.attunity.com/
You can download release notes, installation documentation, white papers, or other types of documentation. You must register online before downloading any documents.
Conventions
This section describes the conventions used in the text and code examples of this documentation set. It describes:
Conventions in Text Conventions in Code Examples Conventions for screens Operating Systems
liv
Conventions in Text
We use various conventions in text to help you more quickly identify special terms. The following table describes those conventions and provides examples of their use.
Convention Bold Meaning Example
When you specify this clause, you create an Bold typeface indicates terms that are defined in the text or terms that appear in index-organized table. a glossary, or both. Italic typeface indicates book titles or emphasis. Oracle Database Concepts Ensure that the recovery catalog and target database do not reside on the same disk. You can specify this clause only for a NUMBER column. You can back up the database by using the BACKUP command. Query the TABLE_NAME column in the USER_ TABLES data dictionary view. Use the DBMS_STATS.GENERATE_STATS procedure. Enter sqlplus to open SQL*Plus. The password is specified in the orapwd file. The department_id, department_name, and location_id columns are in the hr.departments table. Set the QUERY_REWRITE_ENABLED initialization parameter to true. Connect as oe user.
Italics
Uppercase monospace typeface indicates elements supplied by the system. Such elements include parameters, privileges, datatypes, RMAN keywords, SQL keywords, SQL*Plus or utility commands, packages and methods, as well as system-supplied column names, database objects and structures, usernames, and roles. Lowercase monospace typeface indicates executables, filenames, directory names, and sample user-supplied elements. Such elements include computer and database names, net service names, and connect identifiers, as well as user-supplied database objects and structures, column names, packages and classes, usernames and roles, program units, and parameter values.
Note: Some programmatic elements use a The JRepUtil class implements these mixture of UPPERCASE and lowercase. methods. Enter these elements as shown. Lowercase italic monospace font lowercase represents placeholders or variables. italic monospace (fixed-width) font You can specify the parallel_clause. Run Uold_release.SQL where old_ release refers to the release you installed prior to upgrading.
The following table describes typographic conventions used in code examples and provides examples of their use.
Convention [ ] { } Meaning Brackets enclose one or more optional items. Do not enter the brackets. Example DECIMAL (digits [ , precision ])
Braces enclose two or more items, one of {ENABLE | DISABLE} which is required. Do not enter the braces.
lv
Convention |
Meaning
Example
A vertical bar represents a choice of two {ENABLE | DISABLE} or more options within brackets or braces. [COMPRESS | NOCOMPRESS] Enter one of the options. Do not enter the vertical bar. Horizontal ellipsis points indicate either:
...
That we have omitted parts of the code that are not directly related to the example That you can repeat a portion of the code
CREATE TABLE ... AS subquery; SELECT col1, col2, ... , coln FROM employees;
. . .
Vertical ellipsis points indicate that we have omitted several lines of code not directly related to the example.
SQL> SELECT NAME FROM V$DATAFILE; NAME -----------------------------------/fsl/dbs/tbs_01.dbf /fs1/dbs/tbs_02.dbf . . . /fsl/dbs/tbs_09.dbf 9 rows selected.
Other notation
You must enter symbols other than acctbal NUMBER(11,2); brackets, braces, vertical bars, and ellipsis acct CONSTANT NUMBER(4) := 3; points as shown. Italicized text indicates placeholders or variables for which you must supply particular values. Uppercase typeface indicates elements supplied by the system. We show these terms in uppercase in order to distinguish them from terms you define. Unless terms appear in brackets, enter them in the order and with the spelling shown. However, because these terms are not case sensitive, you can enter them in lowercase. Lowercase typeface indicates programmatic elements that you supply. For example, lowercase indicates names of tables, columns, or files. Note: Some programmatic elements use a mixture of UPPERCASE and lowercase. Enter these elements as shown. CONNECT SYSTEM/system_password DB_NAME = database_name SELECT last_name, employee_id FROM employees; SELECT * FROM USER_TABLES; DROP TABLE hr.employees;
Italics
UPPERCASE
lowercase
SELECT last_name, employee_id FROM employees; sqlplus hr/hr CREATE USER mjones IDENTIFIED BY ty3MU9;
lvi
Convention
Meaning
Example
c:\winnt"\"system32 is the same as File and directory File and directory names are not case names sensitive. The following special characters C:\WINNT\SYSTEM32 are not allowed: left angle bracket (<), right angle bracket (>), colon (:), double quotation marks ("), slash (/), pipe (|), and dash (-). The special character backslash (\) is treated as an element separator, even when it appears in quotes. If the file name begins with \\, then screens assumes it uses the Universal Naming Convention. C:\> Represents the screens command prompt C:\attunity\NACV_UTIL> of the current hard disk drive. The escape character in a command prompt is the caret (^). Your prompt reflects the subdirectory in which you are working. Referred to as the command prompt in this manual. C:\>exp scott/tiger TABLES=emp QUERY=\"WHERE job='SALESMAN' and sal<1600\" C:\>imp SYSTEM/password FROMUSER=scott TABLES=(emp, dept)
Special characters The backslash (\) special character is sometimes required as an escape character for the double quotation mark (") special character at the screens command prompt. Parentheses and the single quotation mark (') do not require an escape character. Refer to your screens operating system documentation for more information on escape and special characters.
lvii
lviii
Whats New
AIS, the Attunity Integration Suite, Version 5.1 introduces significant enhancements, support commitments and bug fixes, and continued improvements for ease of use.
Continuous CDC
Beginning with version 5.1, Attunity Stream can provide ETL tools or programs to use standard SQL to query for data changes by continuously feeding change records for processing, effectively working in real-time. This provides an alternative approach to traditional ETL processing that works by executing jobs periodically (for example, every 15 minutes), which adds latency between each pass. This provides a solution for data integration scenarios that require very low latency (near real-time). This ability is executed by a simple SQL statement. See Reading Change Tables Continuously.
Generic Attunity Connect features, including the Procedure Driver, LegacyPlug, Database Adapter, and Query Adapter SQL Server 2005 Driver Oracle Driver Oracle CDC Agent
Note: The installation of the new 64-bit Attunity Server kits for Windows include the 32-bit Server components. This addresses the various options on the Microsoft
lix
platform, where some applications still require 32-bit functionality although running on 64-bit systems. See the installation guide for the operating system you are working with for more information.
Note: Windows 64-bit clients have an installation utility that also installs a new ODBC setup wizard. All other thin clients are distributed as Zip files.
Support for ADO.NET 2.0 APIs including the extended API set, providing richer capabilities to developers and supporting applications that use these APIs. The ADO.NET client is now merged with NETACX capabilities. This allows the ADO.NET client to interact with Application Adapters and exchange hierarchical XML documents with back-end systems. The ADO.NET client now supports design-time integration with Visual Studio 2005. Users can work with the Visual Studio Server Explorer component and use the standard Data Connections option to add a connection to an AIS data source using an integrated Add Connection dialog box. In this way, users can define datasets in the integrated Visual Studio environment and define the Attunity Connect metadata definitions.
lx
Version 5.1 improves the accuracy and performance of the Attunity Connect Update Statistics utility. Using a new algorithm, the Update Statistics utility can now estimate statistics on very large tables more accurately, and much faster.
lxi
lxii
Part I
Getting Started with AIS
This part contains the following topics:
Introducing the Attunity Integration Suite Setting up Attunity Connect, Stream, and Federate Binding Configuration Setting up Daemons Managing Metadata Working with Metadata in Attunity Studio Handling Arrays Using SQL Working with Web Services
1
Introducing the Attunity Integration Suite
This section describes the Attunity Integration Suite (AIS) and its benefits. It contains the following topics:
AIS Overview
The Attunity Integration Suite (AIS) is a comprehensive integration platform for on-demand access and integration of enterprise data sources and legacy applications. AIS runs on many platforms, such as Windows, UNIX, OS/400, and mainframes and provides the many integration possibilities. The suites integration services under the banner are provided in the following programs:
Attunity Connect: Universal, Standard Data Access to enterprise data sources. Attunity Federate: Virtual Data Federation (EII), integrating data on the fly from heterogeneous sources. Attunity Stream: Change data capture, allowing efficient and real-time data movement and processing.
The following diagram provides an overview of AIS and how they can be used to solve many integration needs for each enterprise platform. It also includes the Attunity Studio, a GUI-based tool that lets you configure the Attunity Servers in your system.
Figure 11 AIS Overview
The Attunity Integration Suite (AIS) provides a modular solution that allows organizations to address different tactical requirements quickly, while relying on a comprehensive platform that allows reusability and addresses many needs. The following section provides some examples on the uses for AIS and its benefits.
AIS Use
The Attunity Integration Suite provides many integration possibilities. This section describes some uses, related applications, or projects, and how AIS simplifies the access and integration. The following are some of the common uses for AIS:
SQL Connectivity
SQL is known skill set for application developers and a common interface that applications know and use in order to retrieve data. While relational databases provide SQL connectivity out of the box, legacy data sources and file systems do not. Attunity Connect can help in this area by making older non-relational data sources appear relational and providing access to them using standard SQL. Typical applications that require SQL connectivity include:
Reporting tools: for designing and providing reports to business users J2EE or .NET applications ETL tools: for bulk loading of source data
Some typical scenarios that use Attunity Connect for SQL Connectivity include connecting to Adabas, VSAM, IMS/DB, RMS, Enscribe, and ISAM data sources.
Application Connectivity
XML is now a standard interface for applications, by using standard APIs or Web Services. Many newer applications offer open interfaces, however legacy applications do not and interfacing with their embedded business logic is difficult. Attunity Connect defines virtual services on top of these legacy applications that provide seamless interoperability. Applications that require Service/XML-based application connectivity include:
EAI tools: for invoking business logic as part of an automated process J2EE or .NET applications: that need to reuse existing business logic Legacy Applications: that need to be extended and call off-platform services
Some typical scenarios that use Attunity Connect for application connectivity include CICS, IMS/TM, Tuxedo, COBOL, and RPG.
Adapters
Many enterprise application integration (EAI), enterprise service buses (ESB), and business process manager (BPM) tools need to integrate with existing applications and data sources. Attunity Connect removes the barrier to integrating with legacy applications and data sources by providing standard adapter interfaces and plug-ins to leading adapter frameworks. Adapters include inbound and outbound capabilities, that allow you to send messages to the adapter or receive messages from the adapters. Typical applications that require adapters include:
Integration Brokers: such as BizTalk Server, Oracle BPEL, BEA WLI, etc. ESB and BPM platforms
Typical usage scenarios employing Attunity Connect include application connectivity to CICS, IMS/TM, Tuxedo, COBOL, and RPG, as well as to enterprise data sources.
ETL - for Data Warehousing and complex data movement Data Replication - for rehosting data (for example, to enable reporting) Data Synchronization - for maintaining integrity between systems
Typical tools that are used include IBM WebSphere DataStage, Microsoft SQL Server Integration Services (SSIS), Oracle Warehouse Builder, Business Objects Data Integrator, and Sunopsis.
Operating Systems
OS Supported versions
Windows x86 (32-bit) Windows 2000, XP, Vista, and Windows Server 2003 Windows x64 (64-bit) Windows XP, and Windows Server 2003 Windows IA64 (Itanium) Linux RedHat Windows XP, Windows Server 2003 AS 3.0 through 5.0.
OS AIX Solaris HP UX
Supported versions Versions 5.2, 5.3 Version 2.8-2.10 11.11 (11i v1) and above only. Itanium systems are now supported by most Attuniy data sources. For HP UX on Itanium supported versions are 11.23, 11.31
OpenVMS (Alpha) OpenVMS (Itanium) NonStop (Himalaya) NonStop (Itanium) OS/400 z/OS
Versions 6.2-8.3 Versions 8.2-1 to 8.3 G06.08 to G06.26 H-Series Versions 5.1 to 5.3 Versions 1.1 through 1.8. Beginning with version 5.1.
Interfaces
Interface ADO.NET Supported versions .NET 2.0
Supported versions Version 2.0 Version 2.5 Version 2.5 Versions 1.0, 1.5
2
Setting up Attunity Connect, Stream, and Federate
This section contains the following topics:
Overview Setting up Machines Administration Authorization License Management Importing and Exporting XML in Attunity Studio
Overview
Attunity Studio is used to configure and manage access to applications, data, and events on all machines running AIS. You make configurations in the Design Perspective. This perspective has tabs for configuration and metadata. These tabs enable the following configuration:
Setting up access to machines running AIS. Configuring the daemon, which manages communication between AIS machines. Setting up the access to the application, data or event on these machines. Configuring metadata: To manage Attunity Metadata (ADD) for data sources that do not have metadata (such as DISAM), or have metadata that cannot be used by AIS. To view relational metadata. To extend metadata in ADD for relational data sources that require additional information not supplied by the native metadata (such as statistics for various relational data sources). To manage a snapshot of relational metadata converted to ADD. This is also called local copy metadata. To manage Application Adapter definitions (adapter metadata). To manage event definitions (event metadata).
You manage Attunity products in the Attunity Studio Runtime Manager perspective. Management includes the following:
2-1
A perspective consists of views and an editor area. Views are used to navigate and manage resources. The editor area is used to carry out the main tasks.
Figure 21 Studio Main Screen
Note:
You can use the properties that are displayed in the editor to find a machine where a data source or adapter is located, especially when several data sources or adapters on different machines have similar names. Identifying the location is useful when working on the Metadata tab of the Design Perspective.
To switch between the Design time and Runtime Manager perspectives, click Perspective (at the top right of the workbench) and select the required perspective from the list. For a list of buttons, see Workbench Icons.
Special Note:
To work with solutions in Attunity Studio, when using Turkish, add the following switches to the Target path in the Attunity Studio shortcut properties: -nl en
For example: "C:\Program Files\Attunity\Studio1\studio.exe -nl en" When you open Attunity Studio for the first time, the Welcome Screen is displayed.
Setting up Machines
You use the Design perspective Configuration view to configure AIS Machines, and the applications, data, and events on those machines. To add a machine 1. Open Attunity Studio.
2.
In the Design perspective Configuration view, right-click the Machines folder and select Add Machines. The Add machine screen opens.
Host name/IP address: Enter the name of the machine on the network or click Browse to browse all the machines running a daemon listener on the specified port currently accessible over the network. Port: Enter the number of the port where the daemon is running. The default port is 2551. Display name: Enter an alias used to identify the machine if it is different from the host name (optional).
2-3
You indicate the machines administrator when the machine is installed or by using ADD_ADMIN operation in the NAV_UTIL utility.
Password: Enter the password of the machines administrator. This is the password for the user entered in the User name field. If no password is necessary to access this machine, leave this field empty. Connect via NAT with fixed IP address: Select this if the machine uses the NAT (Network Address Translation) firewall protocol, with a fixed configuration, mapping each external IP to one internal IP, regardless of the port specified. For more information, see Firewall Support.
1. 2.
To edit a machine In Attunity Studio, in the Configuration view of the Design perspective, expand the Machine folder. Right-click the machine you want to edit and select Open. The Machine editor with the information for the existing binding opens in the editor area. You can make the following changes:
Connect via NAT with fixed IP address: Select this if the machine uses the NAT (Network Address Translation) firewall protocol, with a fixed configuration, mapping each external IP to one internal IP, regardless of the port specified. Anonymous login: Select this if users can access the machine without password authentication. When this is selected the User name and Password fields are not available. User name: Enter the machine administrators user name. Password: Enter the machine administrators password. This is the password for the user entered in the User name field.
After you add a machine, it is displayed in the Configuration view under the Machine folder. You can edit the machines login information, or configure bindings, daemons, and users for each machine. For more information, see:
Setting up Data Sources and Events with Attunity Studio Setting up Daemons User Profiles and Managing a User Profile in Attunity Studio
To define an offline machine 1. In the Configuration view of the Design perspective, right-click the Machines folder and select Add Offline Design Machine. The Add offline design machine screen opens.
2. 3.
You can define all available resources on this machine. You can also set up metadata using a metadata import utility. Every resource is available on the design machine, no matter on which platform the resource needs to exist. For example, both HP NonStop data sources and z/OS data sources are available, even though on completion, you can only drag and drop the NonStop definitions (such as an Enscribe data source) to an HP NonStop machine.
Administration Authorization
You can provide access to Attunity Studio for:
Administrators: People granted access as administrators can add and edit resources in all areas of AIS. Designers: People granted access as designers can add adapters, data sources, and CDC agents and create and edit definitions for them. Users: People granted access as users have read-only access to all resources in AIS.
1. 2.
To grant administrative authorization in Attunity Studio In Attunity Studio, in the Configuration view of the Design perspective, expand the Machines folder. Right-click the machine you want to grant privileges to and select Administrative Authorization. The Administrative Authorization editor opens in the editor area. The name of the machine that you are granting access privileges to is shown on the tab at the top of the editor.
2-5
3. 4.
Click the Everyone checkbox at the top of the Administrator, Designer, or User sections to allow all people who use AIS access as the selected type of user. Clear the check box at the top of one or more of the sections to grant specific people access to that area. For more information, see Granting Access to Specific Users and Groups.
Granting Access to Specific Users and Groups To grant a User or group access rights, add them to the list for the type of rights you want to grant them. For example, you can grant user1 administrator rights by adding user1 to the list in the administrator section. To grant rights to all users and groups, select the Everybody check box for any of the three sections. To add users or groups From the Administrators, Designers, or Users sections in the Administration Authorization editor, click Add user and enter the name of a valid user in the Add user screen. Make sure that the name entered matches a valid user account. To add groups to the list, click Add group and enter the name of a valid group in the Add group screen. Make sure that the name entered matches a valid group account.
2.
1.
Click OK to close the screen. The name of the user or group is added to the field.
To rename a user or group 1. From the Administrators, Designers, or Users sections in the Administration Authorization editor, select the user or group you want to rename and click Rename.
2. 3.
Change the name entered in the Rename user or Rename group screen to the name you want to use. Click OK to close the screen. The changes are entered in the field.
1. 2.
To remove a user or group From the Administrators, Designers, or Users sections in the Administration Authorization editor, select the use or group that you want to remove. Click Remove. The user or group is removed from the field.
License Management
Before you can work with any product in AIS, you must register the product. You can register the product with a valid license file. The following sections describe how you can use license management.
Registering a Product
You need to register the software before you can access data sources on a machine. Your Attunity vendor should provide you with a text file called license.pak.The PAK file contains details such as the product expiration date (if any), the maximum number of concurrent sessions allowed, which drivers you are authorized to use, and other information. After you make sure that the PAK file is installed on your machine, you must register it before you can use the product.
Notes:
Make sure you are connected to the Internet before carrying out the following procedure. When you register a product, the new license will overwrite the old license. If you want to register a new product and continue using any previously registered products, then request a single license for all of the products you are using.
To register a product 1. In Attunity Studio, in the Configuration view of the Design perspective, Expand the Machine folder.
2-7
2.
Right-click the machine with the license you want to register, point to License management, and select Register product. The Register Product screen opens.
3.
Click Browse and browse to find the license (PAK) file. It is usually located in the directory where AIS is installed. The XML content of the license file is displayed in the screen.
4.
Click Register. Attunity Studio contacts the Attunity registration server. A message is displayed stating whether the registration was successful. Contact your Attunity vendor if there is a problem with the registration or if you do not have a license file.
2.
Right-click the machine with the license you want to register, point to License management, and select View license information. The View License Registration screen opens.
3.
Click Save as to create a new license file. You can also read the license information in this screen.
In some cases exporting XML data using Attunity Studio does not export all of the data. If this happens, you can use the IMPORT and EXPORT operations in the NAV_UTIL utility.
To import XML 1. In Attunity Studio, in the Configuration view of the Design perspective, right-click one of the following:
2-9
Machines (folder) Any specific machine Data Sources (folder) Bindings (folders) Any specific binding Adapters (folder) Any specific adapter Daemons (folder)
2. 3. 4. 5.
Select Import XML definitions. The Import XML Definitions window opens. Click Browse to open the Import XML Definitions dialog box and browse to the file with the XML data you want to import. Click OK. The data opens at the bottom of the Import XML Definitions screen. Click Finish to close the screen and save the data.
1.
To export XML definitions In Attunity Studio, in the Configuration view of the Design perspective, right-click one of the following:
Machines (folder) Any specific machine Data Sources (folder) Any specific data source Bindings (folders) Any specific binding Adapters (folder) Any specific adapter Daemons (folder) Any specific daemon
2. 3. 4.
Select Export XML definitions. The Export XML Definitions window opens. Click Browse to browse to the location where you want to save the XML data. Click OK to save the data.
When you import or export definitions, the XML data for the level you are using is transferred, including the data for all the sublevels. For example, if you export data for a daemon, the data for the binding and all of its data sources, adapters, and events is transferred. However, if you export the data for an adapter, only the data for that adapter is transferred.
3
Binding Configuration
This section contains the following topics:
Binding Configuration Overview Setting up Bindings in Attunity Studio Binding Syntax Sample Binding Environment Properties
Server Binding
A Binding configuration on a server includes the following:
Definitions for data sources that are accessed using Attunity Integration Suite (AIS). Shortcuts to data sources on other server machines that can be accessed from the current Machine. Application Adapter definitions for applications that can be accessed using AIS, including application-specific properties. Event queue definitions for event queues that are managed using AIS, including event-specific properties. Environment properties that apply to all the data sources, adapters, and machines listed in the binding configuration. For more information, see Environment Properties.
Client Binding
A Binding configuration on a client includes the following:
Shortcuts to data sources on other Server Machines that can be accessed from the current machine. Environment properties that apply to all the data sources, adapters, and Machines listed in the binding configuration. For details, see Environment Properties.
You use Attunity Studio for Adding Bindings and binding configurations or for Editing Bindings that are already in use. NAV is the default binding configuration. You can use this configuration to define all the data sources and adapters you want to access via AIS.
The configuration supplied with the product installation includes the NAV binding. This configuration is used if a specific binding is not defined to access an application, data source, or event queue.
Use Attunity Studio to configure one or more bindings, each with a set of application adapters, data sources, and events. Each binding configuration has its own environment that defines the binding (such as cache sizes for storing information in memory during a session). The following sections describe the required tasks to define a binding:
Adding Bindings
You can set up a number of different bindings. Each binding may be for a different set of applications, data sources or events. You can also create different binding configurations for the same application adapters, data sources or events, with each having a different set of requirements. For example, you can set up separate configurations that allow different users access to specific resources. To add a new binding 1. Open Attunity Studio.
2. 3.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine where you want to add the binding.
Note:
You can add a new binding configuration in a design machine in the offline design mode and later drag and drop the binding to this machine. For more information, see Using an Offline Design Machine to Create Attunity Definitions.
4. 5.
Right-click the Bindings folder and select New Binding. Enter a name for the binding in the New Binding window.
Note: Attunity Studio does not support renaming a binding. Changing the binding name can cause problems with the data sources, adapters, and events for that binding.
In the event that you want to change the binding name, you must create a new binding and copy the data sources, adapters, and events to the new binding.
6.
Click Finish. The new binding editor opens. See Editing Bindings for information on entering information in the binding editor.
Editing Bindings
The binding editor is used to set the binding environment and to define remote machines for a binding. The following sections describe how to edit the binding:
Setting the Binding Environment in Attunity Studio Defining Remote Machines in a Binding
In the Design perspective Configuration view, expand the Bindings folder. Right-click the binding you want to edit and select Open. The binding editor with the information for the existing binding opens in the editor area. Make any changes you want to the binding properties.
2.
On the Environment tab, you can do any of the following to work with the binding environment.
Select the Use NAV environment check box. When this is selected, the NAV environment is used for all of the Environment Properties. The property values are set to the NAV values at runtime. The editing controls for each property are disabled. If you want to change any of the Environment Properties, clear the check box. Click Copy NAV environment to use the default settings, which are the original settings for the NAV binding. This automatically sets all of the environment properties to the NAV values and it allows you to edit individual properties as needed. The property values are created as NAV values during design time. Click Restore default values to automatically restore the environment settings that were defined in the development environment. This means that the values will revert to the values as they were when the AIS solution was first deployed. All values that were changed in the current session or any previous session (including values changed with NAV_UTIL or Attunity Studio) will return to their original value. In addition, each section in the Environment Properties editor has its own Restore default values button. Click this button to restore the default values for the properties in that section only.
3.
Edit any of the environment properties displayed on the Environment tab. For an explanation of the properties, see Environment Properties.
To set up access to a remote machine 1. Right-click the binding you want to edit and select Open. The binding editor opens in the editor area.
2.
3.
4.
Host name/IP address: Enter the name of the machine on the network or click Browse, to browse all the machines running a daemon listener on the specified port currently accessible over the network. Port: Enter the port number where the daemon is running. The default port is 2551. Display name: Enter an alias used to identify the machine if it is different from the host name (optional). User name: Enter the machine administrators user name.
Note:
Define the machine administrator when the machine is installed using Attunity Studio or by using the ADD_ADMIN operation in NAV_UTIL.
Password: Enter the machine administrators password. This is the password for the user entered in the User name field. If no password is necessary to access this machine, leave this field blank. Connect via NAT with fixed IP address: Select this if the machine uses the NAT (Network Address Translation) firewall protocol, with a fixed configuration, mapping each external IP to one internal IP, regardless of the port specified. For more information, see Firewall Support.
5.
Click OK. If the users with access to the remote machines are known, you can set the user profile for the machine by clicking Security on the Machines tab. If the users are not known, you can define them later from the Users folder in the Configuration view. For more information, see Managing a User Profile in Attunity Studio.
Binding Syntax
The Binding settings in XML format include the following statements:
A <remoteMachines> Statement, specifying the remote machines that can be accessed from the current machine by using <remoteMachine> statements. A <datasources> Statement, specifying the data sources that can be accessed by using <datasource> statements. This statement specifies the following: A name to identify the data source The data source type General information <config> statements, specifying specific properties for the data source driver
An <environment> statement, specifying the properties for the specific binding. For details, see Environment Properties. An <adapters> Statement specifying the Application Adapters that can be accessed using the <adapter> statement. This statement specifies the following: <adapter> Statement, specifying a name to identify the Application and the application type.
<remoteMachines> Statement
The <remoteMachines> statement lists the names of the accessible servers, using <remoteMachine> statements. These statements are only necessary when you connect to data sources through a shortcut on the client machine. In other cases (such as accessing an application, or a data source using JDBC), the location is specified as part of the Connect String.
<remoteMachine> Statement
The <remoteMachine> statement lists names and IP addresses of the remote machines with data sources and are accessed using data source shortcuts on the current machine. The names are used as aliases for the IP addresses in the <datasource> statements. This enables you to redefine the location of a group of data sources (on a given machine) by changing the IP address associated with this alias. The format is:
<remoteMachine name="alias" address="address" port="port_number" workspace="workspace" encryptionProtocol="RC4|DES3" firewallProtocol="none|nat|fixednat"/>
Where:
name: The name of the remote machine that is recognized by AIS. The names maximum length is 32 characters, and it must start with a character. This name cannot be the name of a data source specified in a <datasources> statement.
Note:
The name does not need to relate to the name of the machine on the network.
address: The IP address of the remote machine. port: The port on the remote machine where the AIS Daemon is running. If you do not specify a port number, the system allocates the default server port, 2551. workspace: The specific working configuration specified for this binding by the daemon. A Workspace must be defined in the daemon configuration on the remote machine. encryptionProtocol: The protocol used to encrypt network communications. AIS currently supports the RC4 and DES3 protocols. firewallProtocol: The firewall protocol used. Valid values are none, nat, or fixednat. The default is none. NAT (Network Address Translation) is a firewall protocol where internal IP addresses are hidden. It enables a network to use one set of IP addresses for internal traffic and a second set of addresses for external traffic. NAT translates all necessary IP addresses. However, using NAT requires every access by every client to go through the daemon port, even after a specific server process has been assigned to handle the client. Specifying fixednat for this parameter sets AIS to access this remote machine through a firewall using NAT with a fixed IP address. When the server address is returned to the client and
the client sees that the IP is not the IP of the daemon, it ignores the IP and uses the daemon's IP instead. It is recommended to use fixednat to access data via a firewall. For more information, see Firewall Support.
Example 31 <remoteMachines> statement <remoteMachines> <remoteMachine name="ALPHA_ACME_COM" address="alpha.acme.com" /> <remoteMachine name="SUN_ACME_COM" address="sun.acme.com port="8888" workspace="PROD" /> </remoteMachines>
<adapters> Statement
This statement lists the accessible application adapters using the <adapter> statement.
<adapter> Statement
An <adapter> statement specifies the name and properties of an AIS application adapter. The basic format is as follows:
<adapter name="name" type="type" definition="definition_name"> <config .../> </adapter>
Where:
name: The name of the adapter. The maximum length is 32 characters. type: The type of the application adapter to be accessed. This value is different for each application adapter. Refer to a specific application adapter for the value of this parameter. definition: The name of the adapter metadata used to describe the adapter. If the value here is the same as the adapter name, it can be omitted.
Note:
Some adapters have an internal definition, and a value here must be omitted.
<config> Statement
A <config> statement specifies the configuration properties of an application adapter. The configuration information is specific to each adapter type. The basic format is as follows:
<adapter name="name" type="type"> <config attribute="value" attribute="value" ... /> </adapter>
Where:
3-8 AIS User Guide and Reference
attribute: The name of the configuration property. Attributes are adapter-dependent. For example, the preloaded attribute is set with an event router adapter or event to initiate the adapter as soon as the Daemon is started.
Note:
The pre-loaded attribute can also be set when the adapter definition is large, so that the time allocated to a server when the User opens a connection is shortened since the definition has been pre-loaded.
<datasources> Statement
This statement lists the accessible data sources using the <datasource> statement.
<datasource> Statement
A <datasource> statement specifies the name and type of the data source and the information required to connect to the data source. The basic format is as follows:
<datasource name="name" type="type" attribute="value"> <config .../> </datasource>
Where:
name: The name of the data source that is recognized by AIS. The maximum length is 32 characters. The name cannot include hyphens (-). It can include underscores (_). This name cannot be the name of a machine specified in a <remoteMachines> statement. type: The type of the data source to be accessed. This value is different for each data source driver. Refer to a specific data source driver for the value of this parameter. The value of this field when you define a data source shortcut (where the data source resides on another machine) is REMOTE. attribute: General data source attributes, such as read only. These attributes are set in Attunity Studio on the Advanced tab for the data source.
Note:
The localCopy and noExtendedMetadata attributes are set automatically on the Metadata tab of the Design perspective when changes are made to native metadata. For more details, see Native Metadata Caching and Extended Native Data Source Metadata.
Table 31 (Cont.) Data Source Supported Attributes AIS Studio Data source Advanced Tab Syntax name For further details about this field, see Using the Attunity Connect Syntax File (NAV.SYN). Attribute syntaxName="value" Description A section name in the NAV.SYN file that describes SQL syntax variations. The default syntax file contains the following predefined sections:
OLESQL driver and the SQL Server 7 OLE DB provider (SQLOLEDB): syntaxName="OLESQL_SQLOLEDB" OLESQL driver and JOLT: syntaxName="OLESQL_JOLT" Rdb driver and Rdb version: syntaxName="RDBS_SYNTAX" ODBC driver and EXCEL data: syntaxName="excel_data" ODBC driver and SQL/MX data: syntaxName="SQLMX_SYNTAX" ODBC driver and SYBASE SQL AnyWhere data: syntaxName="SQLANYS_SYNTAX" Oracle driver and Oracle case sensitive data: syntaxName="ORACLE8_SYNTAX" or, syntaxName="ORACLE_SYNTAX" For case sensitive table and column names in Oracle, use quotes (") to delimit the names. Specify the case sensitivity precisely.
The name of the table owner that is used if an owner is not indicated in the SQL. true: The data source is in read-only mode. All update and data definition language (DDL) operations are blocked. Indicates the location of a repository for a data source. The name of a repository for a specific data source. The name is defined as a data source in the binding configuration with a type of Virtual and is used to store AIS views and stored procedures specific to the data source, when this is wanted in preference to the default SYS data.
Example 32 <datasources> statement <datasources name="NAV"> <datasource name="ADABAS" type="ADABAS"> <config dbNumber="3" predictFileNumber="7"/> <datasource name="DB2" type="DB2"> <config dbname="person2"/> </datasource> <datasource name="DEMO" type="ADD-DISAM"> <config newFileLocation="/users/nav/dis"/> </datasource> <datasource name="DISAM" type="ADD-DISAM"> 3-10 AIS User Guide and Reference
<config newFileLocation="/users/nav/dis"/> </datasource> <datasource name="SYBASE" type="SYBASE"> <config server="SYB11_HP" dbName="personnel"/> </datasource> </datasources>
Note:
On the HP NonStop platform, the Repository Information objectStoreDir and objectStoreName attributes do not affect Alternate Key Files for the following data sources: Enscribe SQL/MP if a local copy or extended metadata is used.
These are always created in the NAVROOT subvolume with uniquely generated filenames.
<config> Statement
This statement specifies configuration properties of a data source. The configuration information is specific to each adapter type. The basic format is as follows:
<datasource name="name" type="type"> <config attribute="value" attribute="value" ... /> </datasource>
Where:
attribute: The name of the configuration property. value: The value of the configuration property.
Example 33 <config> statement <datasources> <datasource name="DEMO" type="ADD-DISAM"> <config newFileLocation="/users/nav/dis"/> </datasource> </datasources>
Sample Binding
This section shows a sample XML binding in XML format. You can also view the binding.bnd XML file in the XML editor. To open this file in the editor:
Right-click on the binding you want to view and select Open as XML.
This displays a graphical interface where you can define the various aspects of a solution. This interface lets you make changes easily without having to manually edit the XML file. For more information, see Editing XML Files in Attunity Studio. If you want to view the XML in its original format, click the Source tab after you open the binding in XML.
The following Binding configuration provides information for the NAVDEMO sample data source and for a local data source (an ORA_EXT Oracle database), one remote data source, and one adapter ( "MathLegacy", which uses the AIS Legacy Plug adapter):
<?xml version="1.0" encoding="ISO-8859-1"?> <navobj version="..."> <bindings> <binding name="NAV"> <remoteMachines> <remoteMachine name="SUN_ACME_COM" address="sun.acme.com" workspace="PROD"/> </remoteMachines> <environment name="NAV"> <debug generalTrace="true"/> <misc/> <queryProcessor/> <optimizer goal="none" preferredSite="server"/> <transactions/> <odbc/> <oledb/> <tuning/> </environment> <datasources name="NAV"> <datasource name="NAVDEMO" type="ADD-DISAM"> <config newFileLocation="$NAVDEMO"/> </datasource> <datasource name="ORA_EXT" type="ORACLE8" connect="@ora8_ntdb"/> <datasource name="ORA" type="remote" connect="sun_acme_com"/> </datasources> <adapters name="NAV"> <adapter name="MathLegacy" type="LegacyPlug"> <config dllName="c:\legacy\prc_samples.dll"/> </adapter> </adapters> </binding> </bindings> </navobj>
Environment Properties
Each Binding configuration includes its own environment, specified in the environment properties.
Note:
When using an ADO front-end application, the environment used is the environment of the first binding configuration used in the program, even if the binding configuration used is changed during the program.
To display environment properties for the binding configuration in Attunity Studio, right-click the binding configuration and select Open. The environment properties are listed in the Environment tab. The following sections describe each category in the Environment Properties editor.
Debug General Language Modeling ODBC OLE DB Optimizer Query Processor Temp Features Transaction Tuning XML
Debug
This following list shows the debug properties. The debug properties control what information is reported for debugging purposes.
ACX trace: Select this to write the input XML sent to the adapter and the output XML returned by the adapter to the log file. GDB trace: Select this to write the driver transactions created using the AIS SDK to the log. For details refer to Attunity Developer SDK. General trace: Select this to write the general trace information used by to the log. The default writes only error messages to the log. Note: Changing the default setting can degrade AIS performance.
Query warnings: Select this to generate a log file of Query Processor warnings. Add timestamp to traced events: Select this to add a timestamp on each event row in the log. Trigger trace: Select this to log trigger information each time that a database executes a trigger. Adapter trace: Control trace: Query processor trace: Performance trace:
Binary XML log level: Select the binary XML log level from the list. The following logging levels are available:
Log file: Enter the full path and filename of the log file for messages. The default log file (NAV.LOG) is located in the TMP directory under the directory where AIS Server is installed. To send log messages to the console, instead of a file, set logFile to a minus, "-", character. The following message types of are written to the log:
Error messages. Trace information about the query optimization strategy (when General trace is selected).
For HP NonStop, the default AIS log file is called NAVLOG and it is located in the subvolume where the AIS Server is installed. If the log file is location is described by a UNIX type path (such as /G/d0117/ac3300/navlog), then the log file can be viewed from other processes (while it is open). Otherwise, the log is not readable while it is open. To view the file use the following:
FUP COPY filename,, SHARE
For z/OS, the default AIS log file is NAVROOT.DEF.NAVLOG, where NAVROOT is the high level qualifier specified when AIS Server is installed.
Trace directory: Enter the directory where AIS writes the log generated by the optimizer files (with a PLN extension). The optimizer files include details of the optimization strategy used by AIS. By default, these files are written to the same directory as the log file (see Log file). Transaction log file: Enter the full path and filename of the log file that logs transaction activity. This log file is used during recovery operations. On Windows platforms, the default log file (TRLOG.TLF) is written to the same directory as the NAV.LOG file (which is defined by the debug logFile parameter). It is recommended to use the default log file and perform recovery from a PC. Transaction trace: Select this to write 2PC and XA transactions-related events to the log. Optimizer trace: Select this to write trace information and information about the Query Optimizer strategy to the log file. If this property is selected, the following properties are also enabled. Full trace: Select this to enable all optimizer traces. Trace groups: If using Full trace, you can select this to enable generated groups optimizer traces. Trace groups is unavailable if Full trace is not selected.
Transaction extended logging: Select this for the transaction manager to write additional information about transactions to the log.
General
The following list shows the general properties. The general properties control general configuration properties for the binding.
Compress object store: Select this to allow compressing objects in the repository if they use more than 2K storage. This property is automatically selected for a bindings created for a CDC Agent with a Staging Area.
Read V3 definition: Select this if you are upgrading AIS from version 3.xx. This property is selected by default. If you do not need to use this behavior, clear the check box. Temporary directory: Enter the path to the directory where temporary files are written, including the temporary files created for use by hash joins and for sorting files. The default is the current directory. The following describes how to determine where your temporary directory should reside:
1.
Select a directory that contains temporary files only. You can then easily remove these files if necessary (for example, if the process stopped in the middle). Select a directory on a disk that has a significant amount of free disk space.
2.
Year 2000 policy: This property defines how two-digit years are converted into four-digit years. Enter a numeric value in this field. Two policies can be used:
Fixed Base Year: If this property is set to a value greater than, or equal to 1900, the Fixed Base Year policy is used. In this case, the property value is the first four-digit year after 1900 that can be represented by a two-digits. For example, if the value is set to 1905, the years 2000->2004 will be represented by 00->04. All other two digits will map to 19xx. Sliding Base Year: If this property is set to a positive value less than 100, the Sliding Base Year policy is used. In this case, the property value is the number of years ahead of the current year that can be represented by a two-digit number. With each passing year the earliest year that can be represented by a two-digit number changes to a year later. When the parameter is not set, or when it is set to a value outside the range of values defined for the above policies, the default value of 5 and the Sliding Base Year policy is used.
NAV_UTIL editor: Enter the text editor to use when you use NAV_UTIL EDIT. The default is the native text editor for the operating system. Journal file name: Enter the full path to the journal file (including the file name) for use with CDC on DISAM. The default journal file is located in the DEF directory of the AIS installation. Cache buffer size: Enter the number of bytes to be used for a memory buffer on a client machine, which is used by the AIS client/server to store read-ahead data. The default is 200000.
Language
The Language section lets you set the default language for applications in the binding. To set the default language for the binding From the Language list, select the National Language Support (NLS) supported language to use in this binding. Valid values are:
GREEK (Greek) HEB (Hebrew) JPN (Japanese) KOR (Korean) SCHI (Simple Chinese) SPA (Spanish) TCHI (Traditional Chinese) TUR (Turkish)
From the Codepage list, select the codepage that you want to use with this language. The code pages available are determined by the Language that is selected. If you have additional code pages available, you can manually enter them in this field. Note: If you change the language, the code page will also change. Check to be sure that you want to use the selected code page with the language you selected. If no codepage is selected, the default codepage for the selected language is used.
From the NLS string list, select the NLS string for this language and code page. The NLS strings available are determined by the code page that is selected. If you have additional NLS strings available, you can manually enter them in this field. The codepage is used by a field with a data type defined as nlsString. This parameter is used for a field with a codepage that is different than the machines codepage. This property includes the following values:
The name of the codepage. Whether the character set reads from right to left (as in middle-eastern character sets).
Modeling
The modeling section lets you define how to handle nonrelational data and arrays. For more information, see Handling Arrays.
Array metadata model: Select the virtual array flattening model for the binding. You can select one of the models below: virtualarrayTables: In this model, a virtual table is generated for every array in the parent record, with specially generated virtual fields that connect the parent and the virtual table. This is the default for all cases except CDC. virtualarrayViews: In this model, the parent field is replaced with a unique key. Virtual views use the same metadata as virtual tables. This is the default model for CDC.
Reduce sequential flattening: Select this for sequentially flattened tables to not return a row that lists only the parent record, without the values of the child array columns. This option is available only if you select virtualarrayViews as your Array metadata model.
Reduce virtual views: Select this for virtual views to not return a row that lists only the parent record, without the values of the child array columns. By default the property is selected. Clear the check box to return the row. This option is available only if you select virtualarrayViews as your Array metadata model.
Generate unique index names: Select this to generate a unique name for every index on a table that is defined in a non-relational system. When this is selected, the names of all indexes on non-relational tables are exposed in the following format: table_name_KEYkey_number. For example, if a table is called X, the name of the first index would be X_KEY0.
ODBC
The following list shows the properties for ODBC. The ODBC properties set the parameters used when using ODBC to work with AIS.
Maximum active connections: Enter the maximum number of connections that an ODBC or OLE DB application can make through AIS. The default is 0. The greater the number of connections possible, the faster the application can run. However, other applications will run slower and each connection is counted as a license, restricting the total number of Users who can access data through AIS concurrently. For example, this is true when using MS Access as a front-end, because MS Access allocates more than one connection whenever possible.
Maximum active statements: Enter the value returned for the InfoType of the ODBC SQLGetInfo API. The default (0) means that there is no limit on the number of active statements. Force qualify tables: Select this to report the catalog and table name together as a single string (in this format: DS:table_name).
OLE DB
The following list shows the properties for OLE DB. The OLE DB properties set the parameters used when using OLE DB to work with AIS.
Trace: Select this to write the trace information used when working with OLE DB providers to the log. If not selected, only error messages are written to the log. Note: Changing the default setting can degrade AIS performance.
Suppress chapters: Select this to suppress chapters in ODBC. In this case, Chapters are exposed as regular columns. Use this property to prevent an SQL server error for a bad datatype. Maximum row handles: Enter the maximum number of hrows (row handles) that can reside in memory at one time under OLE DB. This property is related to the ADO CacheSize property. Set both of these properties to the same value. If the two properties are different, the smaller value is used and the other is ignored. OLE threads: Enter the number of open threads allowed when working with OLE transactions. These threads are used for operations received from the MSDTC. The minimum value is 5. the optimum value is 15. The maximum value is 25.
Optimizer
This following list shows the optimizer properties. The optimizer properties control how the query optimizer works in the binding.
Avoid scan: Select this to force the optimizer not to choose the scan strategy, if a different strategy can be used. Disable multi-index: Select this to disable the multi-index storage. For Adabas only. Disable cache without index: Select this to disable non-index caches. Disable flattener: Select this to instruct the query optimizer not to flatten queries including nested queries. Disable hash join: Select this to disable hash join optimization. When hash joins are enabled, a significant amount of disk space is required (see Hash maximum disk space). If the system does not have available disk space, use this option to disable hash join optimization. Disable index cache: Select this to disable index caching. Disable lookup cache: Select this to disable the lookup cache. Encourage lookup cache: Select this to define the optimizer to ignore the cache buffer size restriction (hashBufferSize) on a group consisting of a single table.
Disable pass thru: Select this to force the optimizer to execute a full optimization for the query even if it can be delegated to the relational backend database as is. Disable Tdp union: Select this to define the optimizer to handle separate Data sources as if they are on a different backend even if they are part of the same database or remote machine. Disable subquery cache: Select this to disable the cache for subqueries. Analyzer query plan: Select this to write the Query Optimizer plan to a plan file for analysis using the AIS Query Analyzer. Optimization goal: Select the optimization policy to use from the list. The following policies are available:
none: All row optimization is used. This is the default value. first: First row optimization is performed based on the assumption that the results produced by the query are used as the rows are retrieved. The query optimizer uses a strategy that retrieves the first rows as fast as possible, which might result in a slower overall time to retrieve all the rows. all: Optimization is performed based on the assumption that the results produced by the query are used after all the rows have been retrieved. The query optimizer uses a strategy that retrieves all the rows as fast as possible, which might result in a slower time to retrieve the first few rows.
Note: Aggregate queries automatically use all row optimization, regardless of the value of this parameter.
Hash maximum disk space: Enter the maximum amount of disk space (in MBs) that a query can use for hash joins. The default is -1 (which indicates unlimited, all the free space on the allocated disk). If a query requires more space than allocated via this parameter, the query execution will stop. The minimum value for this parameter is 20 MB.
Note: Temporary files are written per query. Therefore, if several users can execute queries at the same time, adjust the amount of space available, so that the total that can be allocated at any one time does not exceed the available space. HP NonStop: If AIS files reduced to disk are larger than 500 MB, use this parameter to enlarge the default size of the file that AIS opens. The default for this parameter on HP NonStop machines is 478.3MB, which consists of a primary extent size of 20K, a secondary extent size of 1000, and a maximum of 500 extents.
Preferred site: Select the machine where you want to process the query. Normally the query is processed as close to the data source as possible (either using the query processing of the data source, or if this is not available, the Query Processor on the same machine as the data source). If a situation arises in which it is more efficient to process the query on the Client Machine (for example, when the remote machine is heavily overloaded), you can tune AIS to process all or part of the query locally. The extent that performance is improved by processing all or some of the query locally can be determined only on a trial and error basis. Consider the following points when processing the query locally:
Before adjusting this parameter, check the log to see if other tuning is more appropriate. The options are:
server (the default): The query is processed on the server. nearServer: The query is processed mostly on the server with parts of the query processed on the client (determined by the specific query). nearClient: The query is processed mostly on the client with parts of the query processed on the server (determined by the specific query). client: The query is processed on the client.
Maximum tables in group: Default row cardinality: Enter the default row cardinality. If you want to set to a value other than 0, this value is used by the Optimizer as the default rows number for pass-through queries and for tables that have no statistical information. Maximum groups for reorder: No LOJ delegation: Select this if you do not want to delegate LEFT OUTER JOIN queries to the relation backend database. AIS will attempt to suppress LOJ queries. If not selected, every query can be delegated as is. Use recursive LOJ allocation: Select this to allow recursive optimization to queries including. By default, this is selected. If you want to disable the recursive LOJ delegation, clear the check box. LOJ recursive optimization limit: Value only if using the log allocation to true.
Disable semi-join: Select this to disable semi-join optimization. Semi-join in values factor: Enter the number of parameters that a semi-join strategy sends to an RDBMS.
Disable order -by-index strategy: Select to disable the order-by-index strategy. In this strategy the order of the results is achieved by accessing the table by the index that contains its segments in the ORDER BY clause so that QP does not sort the results. If not selected, this strategy is not used and sorting is done by QP. Note
Binding Configuration 3-19
that this strategy is rarely selected and using this property affects only queries with an ORDER BY and with no WHERE clause on indexes. All other cases will use the same strategies as they do when this property is not selected.
Parallel Processing
This following list shows the parallel processing properties. The parallel processing properties control how parallel processes are handled in the binding.
Disable threads: Select this to disable multi-threading. If this is selected, the following properties are disabled. Disable threaded read ahead (QP): Select this to disable read-ahead functionality. Disable query read ahead (QP): Select this to disable read-ahead functionality for components using Query Processor services. ODBC async execution property to enable ODBC asynchronous execution Disable QP parallel execution: Select this to disable parallel processing for query execution. This option is available only if both Disable threaded read ahead (QP) and Disable query ready ahead (QP) are not selected. Hash parallelism: Select this to read both sides of hash joins at the same time. By default, this property is selected. If you do not want this behavior, clear the check box.
Query Processor
This following list shows the query processor properties. The query processor properties control how the query processor processes requests in the binding.
Disable command reuse: Select this to disable Query Processor caching the executed state of a query for reuse. Disable DS property cache: Select this to disable caching data source properties. Disable insert parameterization: Select this to disable parameterization constants in INSERT statements. Disable metadata caching: Select this to disable caching object metadata. If this is selected, the object metadata is taken from the from the original data source instead of the cache. Disable query parameterization: Select this to not convert constants into parameters when accessing data sources. Disable row mark field fetch: Select this for OLE DB getRows errors to be marked and reshown on every getRows, if the rowset is active. Compile after load: Select this to always compiles an AIS procedure or view after it is read. Ignore segments bind failure: This property determines how AIS responds when the execution of one of the segments of a segmented data source fails:
Select this to Log a message and continue execution. This is the default setting. Clear the check box to Log a message and stop execution. By default, this property is selected. If you want to stop execution after sending a message, clear this check box.
Prompt database-user password: Select this to configure AIS to prompt the user for security information when accessing a data source. Use alternate qualifier: Select this to use the @ symbol instead of a colon (:) when connecting to multiple data sources. Note: You should use this value when building an application using PowerBuilder from Sybase Inc. or Genio from Hummingbird Ltd.
Use table filter expression: Select this to enable the use of tables that have filter expressions specified in their metadata. For details of filters in ADD, see The <table> Statement for information on the filter property or see the Metadata General Tab for information on using the Filter expression in Attunity Studio. Write empty string as null: Select this to replace empty strings in a SET clause of an UPDATE statement or in a VALUES list of an INSERT statement with null values. Optimistic for update: Select this to use optimistic locking as the default locking behavior on queries with a FOR UPDATE clause. Disable compilation cache: Select this to disable saving successfully compiled statements in the cache. Maximum SQL cache: Enter the maximum number of SQL queries that can be stored in cache memory. This propertys value is ignored if Disable compilation cache is selected. The default is 3. First tree extensions: Enter the maximum size allowed for an SQL query after compilation. The default is 150. Maximum columns in parsing: Enter the maximum number of columns that a query can reference. The default is 500. Maximum segmented database threads: Enter the maximum number of open threads allowed, when working with segmented databases. Minimum number of parameters allocated: Enter the minimum number of parameters that can be used in a query. Continuous query retry interval: Enter the number of seconds that the query processor waits before executing a query again, when no records are returned. The default is 2. Continuous query timeout: Enter the number of seconds that the query processor will continue to issue queries, when no records are returned. The default is 3600 (one hour), which indicates that after an hour without new messages the continuous query will end. Enter 0 to indicate that there is no timeout and the continuos query will not end automatically. Continuous query prefix: Enter a prefix to replace the $$ prefix that is used to identify the continuous query special columns. For example, if you enter ##, then the continuous query alias is ##StreamPosition and the control command alias is ##ControlCommand. Arithmetic fixed precision: Enter an integer determine the precision scale factor for floating decimal position. The default is 0, which indicates that the exact arithmetic function is not used. When the value is set to a small positive integer, the special precise floating point arithmetic is used in the query processor. The value determines the precision scale factor (for example, a value of 2 indicates two digits decimal precision). Setting this parameter can be done at a workspace level and it affects all queries running
at that workspace with no change to the query or to the underlying data source. The query processor ADD(), SUBTRACT() and SUM() functions that currently use double arithmetic for both floating and decimal types will use this logic. When the value is set to the default, 0, the exact arithmetic function is not used. This property is used to set the Exact Arithmetic function. The qpArithmeticFixedPrecision property is an integer value that determines the fixed precision the AIS query processor uses for precise floating point arithmetic. It is used to create an accurate result when using the SUM function. Because floating point datatypes are not accurate their results over time does not correspond to the expected arithmetic sum. In other words, in the floating point representation, values such as 0.7 cannot be represented precisely. If there are eight precision digits, there is usually imprecision in the least significant digit so the number is actually approximately 0.699999995. The qpArithmeticFixedPrecision property corrects this imprecision by using an exact floating point.
Parser depth: Enter the maximum depth of the expression tree. The default is 500. Token size: Enter the maximum length of a string in an SQL query. The minimum value is 64. the default is 350. Insert from select commit rate: Enter the commit rate to use when executing an INSERT-FROM-SELECT operation. If a value more than 0 is entered, a commit is performed automatically after inserting the indicated number of rows. For example, if the value is 5,a commit is performed every time 5 rows are inserted. Disable SQS cache: Select this to always read compiled AIS procedures and views from a disk. In this case, they are not saved in the cache. Procedures cache size: Enter the number of AIS stored queries created with a CREATE PROCEDURE statement that can be kept in cache memory. This propertys value is ignored if Disable SQS cache size is selected. Expose XML fields: Select this to display data returned for a query as XML, representing the true structure of the result. This is useful when querying a data source table that contains arrays or variants. For additional information, see the SELECT XML Statement. XML field name: Enter the name used in a query to indicate that the data is returned as XML, instead of the keyword XML. This is available only if Expose XML fields is selected.
Temp Features
The temp features section lets you add temporary properties to the binding. These properties may be defined in the AIS documentation or release notes, or you can define any additional property. The temporary property is added to the binding.bnd file, which defines the binding environment. To set a temporary feature Enter an ID for the feature. This is the name given to the Environmental property that configures the feature.
Transaction
This following list shows the transaction properties. The transaction properties control how transactions are handled in the binding.
Commit on destroy: Select this to commit all single-phase commit transactions opened for a data source, if a connection closes while the transaction is still open. Disable 2PC: Select this to disable Two-phase Commit capabilities, even in drivers that support two-phase commit. User commit confirm table: Select this to use the commit-confirm table for data sources that support single-phase commit. Recovery delay: Enter the number of minutes from the start of a transaction before any recovery operation on that transaction can be attempted. The default is 15. Time limit: Enter the time to wait for a transaction to complete before an error is returned. This parameter is also used when executing a RECOVERY, and it then indicates the number of minutes from the last transaction activity to wait before a forced activity can be executed.
Conversions: You can select one of the following: No conversion: Select this if you want all transactions to remain as sent. This is selected by default. Convert all to distributed: Select this to convert all simple Transaction Managers into distributed transactions. Convert all to simple: Select this to convert all distributed transactions into simple transactions.
Tuning
This following list shows the tuning properties. The tuning properties are set to increase system efficiency in the binding.
Dsm maximum buffer size: Enter the maximum size of a cache memory. This cache is used when memory is required on a temporary basis (as when AIS sorts data for a query output, for a subquery, or for aggregate queries). This cache size is not used for hash joins and lookup joins (see also, Hash buffer size). The default is 1000000. Dsm maximum hash file size: Dsm maximum sort buffer size: Enter the maximum size of the sort buffers. Use this parameter instead of Dsm maximum buffer size for sorts only. The default is 1000000. Dsm middle buffer size: Enter the maximum number of bytes for the index cache. This cache is not used for hash joins and lookup joins. The default is 1000000. File pool size: Enter the maximum number of files that can be opened in the file pool. The default is 10. File pool size per file: Enter the size of the file in the pool. The default is 3. File close on transaction: Select this if you want the File Pool to close when a transaction is committed. Use global file pool: Select this to use a global file pool is. When the workspace server mode parameter is set to multiClient or reusable, this parameter also
Binding Configuration 3-23
indicates whether the file pool closes upon the client disconnection. See Server Mode.
Hash buffer size: Enter the number of bytes of cache memory that is available for each hash join or lookup join. The default is 1000000. Hash max open files: Enter the maximum number of files that a query can open at one time for use when performing hash joins. The number assigned to this parameter must not exceed the system maximum. The default is 90. Note: The hash join optimization strategy results in a number of files being opened to perform the join. The larger the table size, the more files are opened. By adjusting this parameter you can disable hash joins on very large tables, while allowing hash joins for small tables. (See Disable hash join, for information on disabling hash optimization for all table joins).
Hash primary extent size: Enter the primary extent size (MVS and Tandem only). Hash secondary extent size: Enter the secondary extent size (MVS and Tandem only). Hash max extents: Enter the maximum extent size (Tandem only). Hash enable RO: Select this for the QP to store the first hash bucket in memory instead of a sequential file. Hash refresh EoF: Select this to refresh EoF requests (Tandem only).
XML
This following list shows the XML properties. The XML properties control how XML files are handled in the binding.
COM maximum XML in memory: The maximum size, in bytes, for an XML document held in memory. The default is 524288. COM maximum XML size: The maximum size of an XML document passed to another machine. The default is 524288. Note: When you increase this value for this property, you may need to increase the value for the maxXmlSize property in the daemon. For more information on daemons, see Setting up Daemons.
COM XML transport buffer size: Enter the maximum size of the internal communications buffer. The default value (-1) indicates there is no size limit. XML date format: Enter the date format to use for XML. The options are:
ISO (the default): The date format is: YY-MM-DDThh:mm:ss[.ss..] ODBC: The date format is: YYYY-MM-DD HH:MM:SS[.NNN...]
Replace invalid XML characters: Select this to replace invalid XML characters with a ?. It is used for diagnostic and troubleshooting purposes. XML trim character columns: Select this to enable padded spaces to be trimmed from XML string columns when the record format of is fixed. By default this is selected, and padded spaces are trimmed for fixed size character columns. If you do not want this behavior, clear this check box.
Parameter Name
adminTrace basedDate This property is used to customize the based_date data type having the form: basedDate="yyyymmdd[/dttype[/dtl en[/multiplier]]]" where:
yyyymmdd: Start date dttype: The name of the data type (int4 is the default). dtlen: The number of digits in the data type (if not atomic). multiplier: The number of increments per day.
Example: 19700101/int4//24 indicates the number of hours since January 1, 1970. basedDateNullability true If true, when the based_date value is 0 it is considered Null. If false, the type is not nullable.
Languages
This section provides additional, detailed information regarding each language supported. The languages supported are:
ARA (Arabic) ENG (English) FR (French) GER (German) GREEK (Greek) HEB (Hebrew) JPN (Japanese) KOR (Korean) SCHI (Simple Chinese) SPA (Spanish) TCHI (Traditional Chinese) TUR (Turkish)
ARA (Arabic)
If the codepage parameter is blank, the default codepage on all supported platforms is AR8ISO8859P6, with the exception of HP NonStop platforms, where the default codepage is ARCII. The Windows codepage is 1256.
ENG (English)
The default. If the codepage parameter is blank, the default codepage on all supported platforms is ASCII, with the exception of IBM OS/400 and z/OS platforms, where the default codepage is EBCDIC. The Windows codepage is 1252.
FR (French)
If the codepage parameter is blank, the default codepage on all supported platforms is WE8ISO8859P1, with the exception of IBM OS/400 and z/OS platforms, where the default codepage is F8EBCDIC297. The Windows codepage is 1252.
GER (German)
If the codepage parameter is blank, the default codepage on all supported platforms is WE8ISO8859P1, with the exception of IBM OS/400 and z/OS platforms, where the default codepage is F8EBCDIC297. The Windows codepage is 1252.
GREEK (Greek)
If the codepage parameter is blank, the default codepage on all supported platforms is WEISO8859P7, with the exception of IBM OS/400 and z/OS platforms, where the default codepage is F8EBCDIC875. The Windows codepage is 1253.
HEB (Hebrew)
If the codepage parameter is blank, the default codepage on all supported platforms is IW8ISO8859P8, with the exception of IBM OS/400 and z/OS platforms, where the default codepage is IW8EBCDIC424. The Windows codepage is 1255.
JPN (Japanese)
If the codepage parameter is blank, the following are the default codepages on the supported platforms:
Platform HP NonStop IBM z/OS IBM OS/400 OpenVMS UNIX, excluding Sun Solaris UNIX Sun Solaris Windows Default Japanese Codepage JA16SJIS JA16DBCS JA16DBCS JA16VMS JA16SJIS JA16EUC JA16SJIS
KOR (Korean)
If the codepage parameter is blank, the default codepage on all supported platforms is KO16OSC5601, with the exception Windows platforms, where the default codepage is KO16MS949 (949) and IBM OS/400 and z/OS platforms, where the default codepage is KO16DBCS.
SPA (Spanish)
If the codepage parameter is blank, the default codepage on all supported platforms is WE8ISO8859P1 (or the alias ASCII), with the exception of IBM OS/400 and z/OS platforms, where the default codepage is WE8EBCDICLATIN. The Windows codepage is 1252.
TUR (Turkish)
If the codepage parameter is blank, the default codepage on all supported platforms is WE8ISO8859P9 (or the alias ASCII), with the exception of IBM OS/400 and z/OS platforms, where the default codepage is WE8EBCDIC1026. The Windows codepage is 1254.
Note:
The XML representation of the environment properties are displayed in Attunity Studio in the XML editor. To view the XML, right-click the binding you are working with and select Open as XML.
4
Setting up Daemons
This section contains the following topics:
Daemons Defining Daemons at Design Time Reloading Daemon Configurations at Runtime Checking the Daemon Status Starting and Stopping Daemons Adding and Editing Workspaces
Daemons
Daemons manage communication between machines running AIS. The daemon is responsible for allocating Attunity server processes to clients. A daemon runs on every machine running AIS. The daemon authenticates clients, authorizes requests for a server process within a certain server workspace, and provides the clients with the required servers. When a client requests a connection, the daemon allocates a server process to handle this connection, and refers the client to the allocated process.
Note:
The configuration supplied with the product installation includes the default IRPCD daemon. This configuration is used when no other daemon is configured to access the machine that is requested by a client machine.
For more information, see AIS Runtime Tasks from the Command Line.
Setting up Daemons
4-1
Adding a Daemon
The following describes how to add a new daemon to your system using Attunity Studio. When you want to add a new daemon in the Design perspective, you use standard configuration information or copy the configuration information from another daemon. When you edit the Daemon, you can make custom changes to its configuration. To add a new daemon Open Attunity Studio. In the Design Perspective, Configuration view, expand the Machines folder and then expand the machine where you want to add the daemon. Right-click the Daemons folder and select New Daemon. The New Daemon dialog box opens.
1. 2. 3.
4. 5.
Enter a name for the new daemon. Select one of the following:
Create empty daemon with default values Copy Properties from another daemon If you choose to copy the properties of an existing daemon, click browse and select the daemon where you want to copy the properties.
6.
Click Finish. The Daemon editor opens on the right of the workbench. This editor contains three tabs, which are described in the Editing a Daemon section below.
Notes:
A machine can have a more than one daemon running at the same time, each on its own port. You can add a new daemon configuration in offline design mode, in a design machine and later drag-and-drop the daemon configuration to this machine. For more information, see Using an Offline Design Machine to Create Attunity Definitions. The daemon editor may contain four additional tabs for workspace information. To display both the daemon and workspace configuration, right-click a workspace under the daemon and select Edit Workspace For a description of these tabs, see Adding and Editing Workspaces.
Editing a Daemon
You can edit the information in the following Daemon editor tabs:
Control: In this tab you enter general details about the server timeout parameters and monitoring rules. Logging: In this tab you enter the logging details such as, the log file format and location, and the parameters to log and trace. Security: In this tab you enter the daemons administrative privileges and access privileges.
To open the daemon editor 1. In the Design Perspective Configuration view expand the Machines folder and then expand the machine where you want to add the daemon.
2. 3.
Expand the daemon folder. Right-click the daemon you want to edit and select Open. The Daemon editor opens on the right of the workbench. Click each tab to edit the information. The tab fields are described below.
Note:
Changes made to the daemon configuration are only implemented after the configuration is reloaded using the Reload Configuration option in the Runtime Manager perspective. See Runtime Explorer Tasks.
Control
The Control tab for the daemon lets you define general daemon control properties. The following figure shows the Daemon control tab:
Setting up Daemons
4-3
From: Enter the highest numbered port in the range To: Enter the lowest numbered port in the range
The daemon restarts automatically if it fails for any reason (any error that causes the daemon process to terminate, such as network process lost or the CPU running the daemon crashes and the backup daemon is defined on another CPU). All available and unconnected servers are terminated and any connected servers are marked and terminated on release. Also the backup starts a backup for itself. The backup appends a new log file to the log of the original daemon, adding a line indicating that a backup daemon was started. The language that the daemon supports. This setting is used when working with a client with a codepage different from the server codepage. See Basic NLS Settings.
Default language
Table 41 (Cont.) Daemon Control tab Field Maximum XML request size Maximum XML in memory Timeout Parameters Call timeout The timeout period for short calls for all daemons. The definition of a short call is a call that should be completed in a few seconds. For example, most calls to a database such as DESCRIBE should be completed in a few seconds as opposed to call like a GETROWS call, which can take a long time. In heavily loaded or otherwise slow systems, even short calls such as calls to open a file, may take a significant amount of time. If a short call takes more than the specified time to complete, then the connection is stopped. The default value for this parameter is 60 seconds. Values of less than 60 seconds are considered to be 60 seconds. Note: Specifying the timeout in a workspace overrides the value set in this field for the daemon configuration/workspace. Connect timeout The time the client waits for a daemon server to start. If the daemon server does not start within this period, then the client is notified that the server did not respond. The value specified for this parameter serves as the default timeout for all the workspaces listed in the daemon configuration. The default value for this parameter is 60 seconds. Notes:
Description The maximum number of bytes that the daemon handles for an XML document. The maximum amount of space reserved for the XML in memory.
Entering the timeout in a workspace overrides the value set in this field for that workspace. Even if the XML source does not list this parameter in the workspace section, the workspace gets it using the default value. If you want to prevent a workspace from using the default value, you must enter a value of zero for this parameter in the workspace section.
The maximum amount of time any daemon client may be idle before the connection with the server is closed. Note: Entering the timeout in a Workspace overrides this setting for that workspace.
Logging
You can set up daemon logging for the following:
The daemon log records daemon operations, such as RPC calls and error messages. You can select the type of information you want included in the log file
Note:
This section does not apply to z/OS platforms, where logging information is written directly to the process.
Setting up Daemons
4-5
In this tab, define the daemon log file settings, the log file structure and the location where the log is saved in the Daemon Logging tab. You can also define the data that is logged and traced in the file.
Note:
Changes made to the daemon configuration are only implemented after the configuration is reloaded using the Reload Configuration option in the Runtime Manager perspective. See Runtime Explorer Tasks.
The following table describes the fields in the Daemon Logging tab.
Table 42 Field Logging options Daemon log file location Enter how the daemon produces its log data. The full path must be specified. You can use wildcards as part of this file to indicate specific information. Daemon Logging Tab Description
Table 42 (Cont.) Daemon Logging Tab Field Server log filename format Description Defines the name and location of the server log file. The field must specify the full path name. If no directory information is provided for the log file, then it will be located in the login directory of the account running an AIS workstation. You can enter the following wildcards in this field to generate the following information:
%A: workspace name %D: date (yymmdd) %I: instance number of the given workspace server %L: server account's login directory %P: server's process ID %T: time (hhmmss) %U: server's account name (username)
Daemon operations Trace and debug options Daemon RPC function calls Log ACX Extended RPC trace
Select this if you want to log all daemon RPC function calls. Select this if you want to log requests and processes. Generates a verbose message in the server log file for each low-level RPC function called. This is useful for troubleshooting the server. Generates system-specific tracing of various operations. Generates a timestamp for every entry to the server log file. Generates a message in the server log file for each socket operation. Select this if you want to log low-level RPC operations. Disables the standard RPC timeouts, setting them to a long duration (approximately an hour) to facilitate debugging. Generates a message in the server log file for each RPC function called. This is useful for troubleshooting the server. Enables debugging messages on the server. Sets the binary XML log level. Your options are:
System trace Timing Sockets Trace information No timeout Call trace RPC trace Binary XML log level
Setting up Daemons
4-7
Notes:
AIS supports a subset of UNIX commands that enables file manipulation using standard UNIX commands for the AS/400. Log files are stored under the UNIX file system section of the AS/400 machine. The following types of files are stored under the native OS/400 file system:
When manipulating configuration files or log files, wrap the path/filename in single quotes (), to ensure that the slash (/) used in the UNIX file system syntax is handled correctly. (The slash is an OS/400 special character.)
Security
The Security tab for daemons is used to:
Grant administration rights for the daemon. Determine access to the computer.
Note:
Changes made to the daemon configuration are only implemented after the configuration is reloaded using the Reload Configuration option in the Runtime Manager perspective. See Runtime Explorer Tasks.
The following table describes the fields in the Daemon Security tab:
Table 43 Field Administrators privileges All users Daemon Security Tab Description Identifies the users (accounts) allowed to perform administrative tasks (tasks that require administrative login). Enables all users to access the daemon and change the settings. When this is selected, add the names of users (accounts) and groups that can be workspace administrators. See Administering Selected User Only Lists for information on adding users and groups to the field. If no user is not in the list, any user who has logged on to the daemon can administer the workspace Selected users only Identifies the names of users (accounts) and groups that can be administrators.1 If a user is not specified, the account from which the daemon was started is the administrator account. The daemon does not require the user to log in to the account on the system, but to log in to the daemon using the account name and password. Machine access Allow anonymous login Manages access to the computer. Indicates whether workspaces allow anonymous logins (without user name/password entries). For the optimal level of security, do not select this option and define a username for the Daemon Administrators parameter. If unchecked, then no workspace can have an anonymous client. If checked, then a particular workspace allows anonymous clients. Enables login passwords to be cached. This enhances performance by reducing login times for future connections from the same client in a session. Indicates the encryption method used to send information across the network. The default is an asterisk (*), meaning that all methods are acceptable. If an encryption method is specified, it must be used. Currently, AIS supports the RC4 and DES3 protocols. Enter the authentication domain name.
The name is prefixed with@, to utilize the operating system GROUP feature.
Click Add user and enter the name of a valid user in the Add user dialog box. Make sure that the name entered matches a valid user account.
Setting up Daemons 4-9
To add groups to the list, click Add group and enter the name of a valid group in the Add group dialog box. Make sure that the name entered matches a valid group account.
3.
Click OK. The name of the user or group is added to the field.
1. 2. 3.
To rename a user or group Select the user or group you want to rename and click Rename. Change the name entered in the Rename user or Rename group dialog box to the name you want to use. Click OK. The changes are entered in the field.
1. 2.
To remove a user or group Select the use or group that you want to remove. Click Remove. The user or group is removed from the field.
2.
Right click the daemon and select Status. A dialog box with the daemon status is displayed. The daemon status contains the following information:
Daemon platform IRPCD process ID IRPCD log file IRPCD configuration Logging detail Number of logins Number of active daemon clients Number of active client sessions Max. number of concurrent client sessions
In the Runtime Explorer view, expand the Daemon folder. Right-click the daemon you want to shut down and select Shutdown Daemon.
serverMode="reusable" serverLogFile="%l.xxx%i" reuseLimit="20" nAvailableServers="10" minNAvailableServers="4" anonymousClientAllowed="false" administrator="*" /> <workspace name="ACMEReportingServer" workspaceAccount="report" startupScript="machine_dependent"1 serverMode="singleClient" serverLogFile="%l.xxx%i" nAvailableServers="3" minNAvailableServers="1" anonymousClientAllowed="false" administrator="*" /> </workspaces> <control "ServerLogfile=/users/nav/%A%U%P.log" /> <security anonymousClientAllowed="false" administrator="sysadmin" /> <logging logFile="irpcd.log" logClientDomain="0" detail="errors" /> </daemon> </daemons>
Note:
The daemon configuration is displayed in Attunity Studio by editing the daemon, in the Source tab.
Adding a Workspace
When you define a new Workspace, you can copy the values of an existing workspace on the same Daemon or have AIS set its default values. To add a new workspace 1. Open Attunity Studio.
2. 3. 4.
In Design Perspective Configuration view, expand the Machine folder and then expand the machine with the daemon where you want to add the workspace. Expand the daemon folder. Right-click the daemon where you want to add the workspace and select New Workspace.
The startupScript values in these examples is machine dependent. For example, for z/OS the startup script might be startupScript=ATTSRVR.AB, for OpenVMS startupScript="dka0:[user.orders]NAV_SERVER.COM" and for Windows startupScript="nav_util svc"
Note:
You can add a new daemon configuration in offline design mode, in a design machine and later drag-and-drop the daemon configuration to this machine. For more information, see Using an Offline Design Machine to Create Attunity Definitions.
5.
Name: The name used to identify the workspace. The workspace name is made up of letters, digits, underscores (_) or hyphens (-)
Note:
On machines running HP NonStop or z/OS, limit the name of a workspace to five characters so that the system environment file, workspaceDEF, does not exceed eight characters. Workspace names greater than five characters are truncated to five character and the default workspace, Navigator, will look for a system environment called NavigDEF.
6.
Create empty workspace with default values Copy properties from another workspace If you copy the properties from another workspace, the fields below the selection become active. You must indicate the workspace from where you want to copy the properties. Enter the following information:
<name of the workspace> in <name of the daemon where the workspace is located> on <name of machine where the daemon is located>. or you can click the browse button and browse to select the workspace you want to use. The above information is added automatically.
7.
Click Next to open the Select Scenario window. Select the type of applications the daemon works with from the following options:
Application server using connection pooling. Stand-alone applications that connect and disconnect frequently. Applications that require long connections, such as reporting programs and bulk extractors. Custom (configure manually). If you select this option, the Workspace editor opens. See
8.
Click Next to open the next window. Select one of the following. The options available depend on the scenario selected:
The minimum number of server instances available at any time: This is the minimum number of connections that are available at any time. If the number of available connections drops below this number, the system will create new connections. (Available if you select Stand-alone applications that connect and disconnect frequently). The maximum number of server instances available at any time: This is the maximum number of connections that are available at any time. If the number of connections used reaches this number, no additional server connections can be made. (Available if you select Stand-alone applications that connect and disconnect frequently). The average number of expected concurrent connections: This lets the system know how much the average load will be and helps to distribute the resources correctly. (Available if you select Application server using connection pooling. or Stand-alone applications that connect and disconnect frequently). The maximum number of connections: This is the most connections that will be available. If the number of requests exceeds this number, an error message is displayed that informs the user to try again when a connection becomes available. (Available if you select Application server using connection pooling. or Stand-alone applications that connect and disconnect frequently). How many connections you want to run concurrently. This sets the number of connections that will run at the same time. (Available if you select Applications that require long connections, such as reporting programs and bulk extractors).
9.
Click Next and enter the amount of wait time for the following parameters. If your system is not too overloaded, you can leave the default times.
How long to wait for a new connection: Enter the amount of time (in seconds) to wait for a connection to be established before the system times out. For example if you want a wait time of one minute enter 60 (the default). If you enter 0, the time is unlimited. How long to wait for a response that is usually fast: Enter the time (in seconds) to wait for a response from the system before the system times out. For example if you want to wait for one minute, enter 60. The default is 0, which indicates unlimited wait time.
10. Click Next to open and enter the workspace security information in this window.
You can determine which users or groups can access the workspace you are defining. For more information, see <xref to Managing Security>.
11. Click Next to open the summary window. Review the summary to be sure that all
the information entered is correct. If you need to make any changes, click Back to go back to previous steps and change the information.
12. Click Finish to close the wizard and add the new workspace to the Configuration
view.
Editing a Workspace
After you add a Workspace, you can make changes to the workspaces configuration. You can edit the information in the following workspace editor tabs:
General: Specifies general information including the server type, the command procedure used to start the workspace, the binding configuration associated with this workspace (which dictates the data sources and applications that can be accessed) the timeout parameters, and logging information. Server Mode: Contains the workspace server information including features that control the operation of the servers started up by the workspace and allocated to clients. Security: Contains administration privileges, user access, ports available for access to the workspace and workspace account specifications.
1. 2. 3. 4. 5.
To edit a workspace Open Attunity Studio. In the Design Perspective Configuration view, expand the Machines folder and then expand the machine where you want to edit the workspace. Expand the daemon folder. Expand the daemon with the workspace you want to edit. Right-click the workspace you want to edit and select one of the following:
Workspace Setup Wizard: Opens the wizard that was used to add a new workspace (see Adding a Workspace). Make any required changes to the wizard settings to change the workspace definition. Open: Opens the editor. The editor includes the information that was entered in the New Workspace wizard. Click the following tabs to edit the information: General Server Mode Security
Note:
The default daemon configuration supplied with AIS includes the default Navigator Workspace. This workspace is automatically used if no workspace is selected.
General
You enter general information about the Workspace operations in the General tab. This information includes the server type, the command procedure used to start the workspace and the binding configuration associated with this workspace. The following figure shows the General tab:
Figure 46 The General Tab
Notes:
You can also change daemon settings using the Configuration view, by selecting a computer and scrolling the list to the required daemon. Right-click the daemon and select Edit Daemon. Changes made to the daemon configuration are not implemented immediately. They are only implemented after the configuration is reloaded using the Reload Configuration option in the Runtime Manager. For z/OS logging, the default is to write the log entries to the job only
Workspace name
The name used to identify the workspace. Note: The default configuration includes the default Navigator workspace. This workspace is automatically used if a workspace is not specified as part of the connection settings.
A description of the workspace. The full path name of the script that starts the workspace server processes. The script specified here must always activate the nav_ login procedure and then run the server program (svc). If you do not specify the directory, the startup procedure is taken from the directory where the daemon resides. AIS includes a default startup script, which it is recommended. Enter the script name only because the server is activated as a started task. The workspace server type:
Server type
The name of a specific binding configuration on the server machine that you want to use with this workspace. Notes:
For HP NonStop the name of the binding must be five characters or less. For z/OS the name of the binding must be five characters or less and the name must be surrounded by single quotes. If the high-level qualifier is not specified here, NAVROOT.DEF is assumed, where NAVROOT is the high-level qualifier specified when Attunity Server is installed.
Enter a name of a virtual database that this workspace accesses if applicable. A virtual database presents a limited view of the available data because only selected tables from either one or more data sources are available, as if from a single data source. For more information, see Using a Virtual Database. If a value is entered in this field, only the virtual database can be accessed using this workspace. Note: Entering a value in this field restricts access from a JDBC Client Interface, ODBC Client Interface or OLE DB (ADO) Client Interface during runtime.
Timeout parameters
The following properties define the time the client waits for the workspace server to start. If the workspace server does not start within this period, then the client is notified that the server did not respond. Entering a timeout value for these properties overrides the default setting entered in the Control tab. The maximum amount of time a workspace client can be idle before the connection with the server is closed. The time the client waits for a workspace server to start. If the workspace server does not start within this period, then the client is notified that the server did not respond.
Table 44 (Cont.) General Tab Field Call timeout Description The timeout period for short calls for all workspaces. The definition of a short call is a call that should be completed in a few seconds. For example, most calls to a database such as DESCRIBE should be completed in a few seconds as opposed to call like a GETROWS call, which can take a long time. In heavily loaded or otherwise slow systems, even short calls such as calls to open a file, may take a significant amount of time. If a short call takes more than the specified time to complete, then the connection is stopped. The default value for this parameter is 60 seconds. Values of less than 60 seconds are considered to be 60 seconds. Note: Specifying the timeout in a workspace overrides the value set in Call timeout field for the daemon configuration. Logging and Trace Options Specific log file format Defines the name and location of the server log file if you want the data written to a file instead of SYSOUT for the server process. The parameter must specify the name and the high level qualifier. You can enter the following wildcards in this field to generate the following information:
%A: workspace name %D: date (yymmdd) %I: instance number of the given workspace server %L: server account's login directory %P: server's process ID %T: time (hhmmss) %U: server's account name (username)
Logging
Specifies the type of tracing. The following tracing options are available:
No timeout: Select this to disable the standard RPC timeouts, setting them to a long duration (approximately an hour) to facilitate debugging. Call trace: Select this to generate a message in the server log file for each RPC function called. This is useful for troubleshooting the server. RPC trace: Select this to enable debugging messages on the server. Sockets: Select this to generate a message in the server log file for each socket operation. This is useful for troubleshooting client/server communication by providing a detailed trace of every client/server communication. Extended RPC trace: Select this to generate a more detailed message in the server log file for each low-level RPC function called. This is useful for troubleshooting the server. System trace: Select this to generate operating system-specific tracing. Timing: Select this to generate a timestamp for every entry to the server log file.
Query governing restrictions Max Number of Rows in a Table That Can Be Read Select the maximum number of table rows that are read in a query. When the number of rows read from a table exceeds the number stated, the query returns an error.
Table 44 (Cont.) General Tab Field Max Number of Rows Allowed in a Table Before Scan is Rejected Description Select the maximum number of table rows that can be scanned. This parameter has different behavior for query optimization and execution.
For query optimization, the value set is compared to the table cardinality. If the cardinality is greater than the value, the scan strategy is ignored as a possible strategy (unless it is the only available strategy). For query execution, a scan is limited to the value set. When the number of rows scanned exceeds the number entered, the query returns an error.
Server Mode
You enter the features that control the operation of the servers started up by the workspace and allocated to clients in the Server Mode tab. For example, you can configure the Workspace to use connection pooling and to start up a number of servers for future use, prior to any client request, instead of starting each server when a request is received from a client.
Figure 47 The Server Mode Tab
Notes:
You can also change Daemon settings using the Configuration view, by selecting a computer and scrolling the list to the required daemon. Right-click the daemon and select Edit Daemon. Changes made to the daemon configuration are not implemented immediately. They are only implemented after the configuration is reloaded using the Reload Configuration option in the Runtime Manager.
The table below describes the fields in the Server Mode tab:
Table 45 Field Workspace server mode Server Mode Tab Description Specifies the type of new server processes that the daemon starts up. The daemon supports the following server modes:
singleClient: Each client receives a dedicated server process. The account in which a server process runs is determined either by the client login information or by the specific server workspace. This mode enables servers to run under a particular user account and isolates clients from each other, as each receives its own process. However, this server mode incurs a high overhead due to process startup times and can use a lot of server resources as it requires as many server processes as concurrent clients.
multiClient: Clients share a server process and are processed serially. This mode has low overhead because the server processes are already initialized. However, because clients share the same process, they can impact one another, especially if they issue lengthy queries. The number of clients that share a process is determined by the Clients per server limit field. Notes: This mode is not available on HP NonStop machines. Do not use this property when accessing a database that supports two-phase commit through XA.
multiThreaded (Windows only): Clients are allocated a dedicated thread in a shared server process. This mode has low overhead since the servers are already initialized. However, because clients share the same process, they may impact one another, especially if the underlying database is not multi-threaded. The number of multi-threaded clients that share a process is set in the Clients per server limit field (the maximum number of concurrent clients a server process for the current workspace accepts) in the Attunity Studio Design perspective configuration tab. This value is set in the daemon configuration settings maxNClientsPerServer parameter. Notes: Multiple multi-client and multi-threaded servers can be started at the same time for optimal performance. Do not use this property when accessing a database that supports two-phase commit through XA.
reusable: An extension of single-client mode. Once the client processing finishes, the server process does not die and can be used by another client, reducing startup times and application startup overhead. This mode does not have the high overhead of single-client mode because the servers are already initialized. However, this server mode can use a lot of server resources as it requires as many server processes as concurrent clients. Do not use this mode with a database that supports two-phase commit through XA. In this case, define a new workspace for the data source, so that all the other data sources you are accessing use reusable servers. The other modes can be set so that the server processes are reusable. The number of times a process can be reused is controlled by the Reuse limit field value in Attunity Studio (the maximum number of times a server process can be reused or how many clients it can server before it finishes). Reuse of servers enhances performance since it eliminates the need to repeat initializations. However, reuse runs a risk or using more memory over time. The default for the Reuse Limit field value is 0, which means that there is no limit.
Port range
Select the range for specific firewall ports through which you access the workspace. Determines the range of ports available for this workspace when starting server processes. Use this option when you want to control the port number, so that Attunity Connect can be accessed through a firewall. Enter the port range in the following fields:
From: Enter the highest numbered port in the range To: Enter the lowest numbered port in the range
Select this to use the port range that is defined in the daemon. This is defined in the Port range for servers field in the daemon Control tab.
Maximum number of Enter the maximum number of server processes that can run at the server processes same time. Limit server reuse Select this if you want to limit the number of servers that can be reused. If this is selected, the Reuse limit parameter is available. If Limit server reuse is selected, in the field next to the check box, enter the maximum number of times a server can be reused. Select the maximum of clients accepted in a server process. A one-client server can be reused after its (single) client has disconnected. Reuse of servers enhances startup performance because it avoids the need to repeat initialization. This parameter is not available if the Limit server reuse parameter is not selected. This parameter is not available if the server mode value is singleClient. Limit concurrent clients per server Select this to limit the number of clients that a server can accept for the current workspace process. If this is not selected, the number of clients is unlimited.
Table 45 (Cont.) Server Mode Tab Field Description If Limit concurrent clients per server is selected, in the field next to the check box, enter the maximum number of clients that a server process for the current workspace accepts. The default for this field is None, indicating that the number of clients for each server is unlimited. This field is available if the server mode value is multiClient or multiThreaded. Specify Server Priority Set the priority for servers. For example, a workspace for applications with online transaction processing can be assigned a higher priority than a workspace that requires only query processing. The lower the number, the higher the priority. For example, workspaces with a priority of 1 are given a higher priority than workspaces with a priority of 2. Note: This is unavailable if Use default server priority is selected. Use default server priority Keep when daemon ends Sets the priority to 0. There is no specific priority for this workspace. Clear this check box to set a priority in the Specify Server Priority parameter. Select this to kill all servers started by that daemon when a daemon is shutdown, even if they are active. Select this if you want the servers for the workspace to remain active, even after the daemon has been shut down. If selected, it is the responsibility of the system operator or manager to ensure that the servers are eventually killed. This must be done at the system level.
Server Provisioning Number of prestarted Initial number of servers: The number of server processes that are servers in pool prestarted for this workspace when the daemon starts up. When the number of available server processes drops lower than the value specified in the Minimum number field, the daemon again starts server processes until this number of available server processes is reached. The default for this field is 0. Number of spare servers The minimum number of server processes in the prestarted pool before the daemon resumes creating new server processes (to the value specified in the Initial number of servers field). If this field is set to a value higher than the Initial number of servers field, the daemon uses the value specified in the Initial number of servers field. The default for this field is 0. The maximum number of available server processes. Once this number is reached, no new nonactive server processes are created for the particular workspace. For example, if a number of server processes are released at the same time, so that there are more available server processes than specified by this field, the additional server processes higher than this value are terminated. The default for this field is zero, meaning that there is no maximum.
Security
Configure the security level for a workspace in the Workspace editor Security tab. This lets you set the security options for the workspace only. To set security on the daemon level, see Security. The Security tab is used:
To grant administration rights for the workspace To determine access to the workspace by a client
Table 46 (Cont.) Security Tab Field Authorized Workspace users Description Indicate which users have permission to use the workspace. Select one of the following
All users: Any user who has logged on to the daemon may use the workspace Selected users only: Select this to allow only users (or accounts) with specific permission to use the workspace. When this is selected, add the names of users (or accounts) and groups that can be use the workspace in the field below. See Administering Selected User Only Lists for information on adding users and groups to the field. Note: If no user is specified, any user who has logged on to the daemon may use the workspace.
Authorized Administrators
Identifies the users (accounts) with administrator privileges. Select one of the following:
All users: Indicates that anyone can access the workspace and change the settings. Selected users only: Select this to allow only users (or accounts) with specific permission to be administrators. When this is selected, add the names of users (or accounts) and groups that can be workspace administrators. See Administering Selected User Only Lists for information on adding users and groups to the field. If no user is specified, any user who has logged on to the daemon may administrator this workspace.
Note:
You can also use the Allow Listing parameter. Select this if you
To set this parameter you must use the XML view. Right-click the daemon with the workspace you are working with and select Open as XML. Find this parameter in the XML editor to change it. For more information, see Editing XML Files in Attunity Studio.
You can have more than one workspace, each with different binding configurations. If you want to use a binding other than the default binding, on UNIX and OpenVMS platforms you can select the binding as part of the startup script for the workspace.
Disabling a Workspace
Workspaces can be disabled. When you disable a workspace, server processes are not started and a client requesting the disabled workspace receives an error. To disable a workspace in Attunity Studio 1. In the Design perspective Configuration view, right-click the workspace you want to disable.
2.
Select Disable.
Enter the User name and Password for the user with authorization rights for this workspace. For more information about setting rights and security privileges, see Security.
5
Managing Metadata
This chapter includes the following sections:
Data Source Metadata Overview Importing Metadata Managing Metadata Using Attunity Metadata with AIS Supported Data Sources Procedure Metadata Overview Importing Procedure Metadata Using the Import Wizard Procedure Metadata Statements ADD Supported Data Types ADD Syntax
CISAM /DISAM Data Source DBMS Data Source (OpenVMS Only) Enscribe Data Source (HP NonStop Only) Flat File Data Source IMS/DB Data Sources (z/OS Only) RMS Data Source (OpenVMS Only)
Text Delimited File Data Source VSAM Data Source (z/OS) (VSAM Under CICS and VSAM Drivers (z/OS Only)) OLEDB-FS (Flat File System) Data Source
An Adabas C Data Source is available if the Adabas Predict metadata is not available (or efficient). Metadata can be imported, saved and managed in the Attunity Studio Design perspectives Metadata tab.
Importing Metadata
You can use the Attunity Studio Import wizards or standalone import utilities to generate metadata. If an import wizard or standalone utility is not available, you can create the metadata manually.
Enscribe Data Source (HP NonStop Only) IMS/DB Data Sources RMS Data Source (OpenVMS Only) VSAM Batch CDC (z/OS Platforms) (VSAM Under CICS and VSAM Drivers (z/OS Only))
For other data source drivers, if a COBOL copybook is available, metadata can be generated from the COBOL in Attunity Studio. Otherwise, the metadata has to be manually defined in the Attunity Studio Design perspective Metadata tab. If COBOL copybooks describing the data source records are available, you can import the metadata by running the metadata import in the Attunity Studio Design perspective Metadata tab. If the metadata is provided in a number of COBOL copybooks, with different filter settings (such as whether the first 6 columns are ignored or not), you import the metadata from copybooks with the same settings and later import the metadata from the other copybooks. You can save an import procedure and use it again.
Note:
Attunity metadata is independent of its origin. Therefore, any changes made to the source metadata (for example, the COBOL copybook) are not made to the Attunity metadata
Each data source has different import requirements. Some may have different amount steps than others and require different information. Each wizard guides you through the import. The input files for each import (such as COBOL copybooks) are needed during the import to define the input and output structures used by the application adapter. These files are sent to the machine running Attunity Studio using the FTP protocol, as part of the import procedure. For additional information on importing metadata, refer to the specific data source.
Adabas DDM import (DDM_ADL): This utility produces Attunity metadata from non-Predict metadata (nsd files) BASIC mapfiles import (BAS_ADL): This utility produces Attunity metadata from BASIC mapfiles. DBMS Import (DBMS_ADL): produces Attunity metadata from a DBMS database. HP NonStop Enscribe Import (ADDIMP): This utility produces Attunity metadata for HP NonStop Enscribe data from a DDL subvolume and/or COBOL copybooks. You can generate the metadata from COBOL copybooks in Attunity Studio. HP NonStop Enscribe Import (TALIMP): This utility produces Attunity metadata for HP NonStop Enscribe data sources from TAL datafiles and a DDL subvolume. MS CDD Import (CDD_ADL): This utility extracts the information stored in an RMS CDD directory into ADD metadata. You can generate the metadata from COBOL copybooks in Attunity Studio.
Managing Metadata
You manage metadata in Attunity Studio. Click the Metadata tab in the Design perspective to view and modify Attunity Metadata for Data Sources. To view and modify metadata for data sources In the Design perspective Configuration view, right-click the data source for which you want to manage the metadata. Select Edit metadata from the shortcut menu. The Metadata tab opens with the selected data source displayed in the tree.
Note:
1. 2.
You can also open the Metadata tab and right-click the Data sources folder in the Metadata view to add the data source that you want to import metadata for to the tree.
3.
Right-click the resource (such as the data source table) in the Metadata view and select Edit.
Data source tables are edited using the following tabs, which are at the bottom of the screen:
General Tab: Defines general information about the table, such as the table name and the way the table is organized, and the location of the table. Columns Tab: Specifies the table columns and their properties. For example, the column data type, size and scale. Indexes Tab: Enables you to specify the indexes of a table. The indexes are described by the order of the rows they retrieve and the data source commands used and the index type. Statistics Tab: Enables you to specify statistics for the table, including the number of rows and blocks of the table.
Note:
Attunity Connect provides a relational model for all data sources defined to it. Thus, relational terminology is used, even when referring to non-relational data sources. For example, the metadata for an RMS record is referred to as the metadata for an RMS table.
Change the relevant values for the table to be extended in the Statistics tab. The table symbol in the tree is marked with an asterisk to show that the metadata has been extended.
Note:
The information in other tabs are for reference only and cannot be edited. The noExtendedMetadata property in the data source definition in the binding configuration is set to false.
You can sometimes improve performance using Attunity metadata instead of the native metadata. In this case, you can export a snapshot of the native metadata to Attunity Connect and use this local copy of the native metadata when accessing the data source.
Examples of when this is beneficial include when native metadata is not up to date or information, such as statistics, are not available. You can see a snapshot of the metadata in Attunity Studio. To make a copy of data source metadata 1. Display the metadata for the data source in the Design perspective Metadata tab of Attunity Studio.
2. 3. 4.
Right-click the data source and select Manage Cached Metadata from the popup menu. Select the tables that you want to use a local copy and move them to the right pane. Click Finish. The tables are displayed under the data source.
Note::
The table symbol changes from the relational data source symbol to a data source symbol that requires Attunity metadata. The localCopy property in the data source definition in the binding configuration is set to true.
Only the tables that have cached metadata are displayed in the tree. To revert back to using non-cached metadata, you can either right-click individual tables and choose Delete Cached Table from the popup menu or, for all the tables, right-click the data source and choose Set Metadata followed by Native Metadata from the popup menu.
Note:
If the native metadata change, then from using a snapshot of the native metadata is not recommended.
For other procedures, the metadata is created manually, as described in Manually Creating Procedure Metadata. If COBOL copybooks describing the procedure input and output structures are available, you can import the Metadata by running the metadata import in the Attunity Studio Design perspective Metadata tab. If the metadata is provided in a number of COBOL copybooks, with different filter settings (such as whether the first 6 columns are ignored or not), you import the metadata from copybooks with the same settings and later import the metadata from the other copybooks. You can also save an import procedure for reuse.
Note:
Imported metadata is independent of its origin. Changes made to the source metadata after the import, are not made to the Attunity metadata.
The input files for the import (such as COBOL copybooks) to define the input and output structures used by the Application Adapter These files are copied to the machine running Attunity Studio as part of the import procedure. The names of the applications (such as the IMS/TM transaction or CICS program) to be executed via the procedure.
The <procedure> Statement The <parameters> Statement The <dbCommand> Statement The <dbCommand> Statement The <fields> Statement
An attribute list. Input parameters for procedures A <field> statement which includes the fields list.
Syntax
<procedure name="proc_name" attribute="value" ...> <dbCommand>...</dbCommand>
<fields> <field name="field_name" attribute="value" .../> ... </fields> <parameters> <field name="param" attribute="value" ... /> ... </parameters> </procedure>
The proc_name entry must conform to standard ANSI 92 SQL naming conventions. You must include a <field> statement. Use a <parameters> statement to specify input parameters.
Example 51 <procedure> statement <procedure name="math_simple" filename="prc_samples"> <dbCommand>LANGUAGE=C</dbCommand> <fields> <field name="sum1" datatype="int4"> <dbCommand>order=1</dbCommand> </field> <field name="subtract" datatype="int4"> <dbCommand>order=2</dbCommand> </field> <field name="multiply" datatype="int4"> <dbCommand>order=3</dbCommand> </field> <field name="divide" datatype="int4"> <dbCommand>order=4</dbCommand> </field> </fields> <parameters> <field name="oper1" datatype="int4"> <dbCommand>mechanism=value; order=5</dbCommand> </field> <field name="oper2" datatype="int4"> <dbCommand>mechanism=value; order=5</dbCommand> </field> </parameters> </procedure>
<procedure> Attributes
The attributes are listed in the following table:
Table 51 Attribute Name alias <procedure> Attributes Syntax alias="name" Description Replaces the procedure name with a logical procedure name. Names greater than 39 characters are truncated from the left.
Table 51 (Cont.) <procedure> Attributes Attribute Name description Syntax description="optional_ user_supplied_ description" Description Specifies an optional textual description.
filename
filename="full_filename" Specifies the full name and location of the file. where full_filename includes the full path to the file.
name
name="name"
Syntax
<parameters> <field name="param" attribute="value" ...> <dbCommand>...</dbCommand> </field> <field name="param" attribute="value" .../> ... </parameters>
Example 52 <parameters> statement <parameters> <field name="oper1" datatype="int4"> <dbCommand>mechanism=value; order=5</dbCommand> </field> <field name="oper2" datatype="int4"> <dbCommand>mechanism=value; order=5</dbCommand> </field> </parameters>
Syntax
<dbCommand>text</dbCommand>
Syntax
<fields> <field name="field_name" attribute="value" ...> <dbCommand>...</dbCommand> </field> <group name="field_name" attribute="value" ...> <fields> <field name="field_name" attribute="value" ... /> </fields> </group> <variant name="field_name" attribute="value" ...> <case name="field_name" attribute="value" ...> <fields> <field name="field_name" attribute="value" ... /> </fields> </case> ... </variant> ... </fields>
For details of the specific syntax requirements for a procedure, see the specific procedure.
Syntax
<field name="field_name" attribute="value" ...> <dbCommand>...</dbCommand> </field>
The following code defines one field (N_NAME) and its two attributes (data type and size):
<field name="n_name" datatype="string" size="25" />
<field> Attributes
The attributes are listed in the following table:
Table 52 Attribute Name datatype <field> Attributes Syntax datatype="datatype" Description Specifies the data type of a field. For the supported data types, see ADD Supported Data Types. scale scale="n" Specifies the number of characters or digits. For example: <field name="SALARY" datatype="numstr_s" size="10" scale="2" /> size size="n" where n is the number of characters or digits. The digit must be greater than 0. name name="name" Specifies the name of the field. This attribute must be specified. For example: <field name="EMP_ID" datatype="int4" /> Specifies the size of the field.
Syntax
group name="field_name" attribute="value" ...> <dbCommand>...</dbCommand> <fields> <field name="field_name" attribute="value" ... /> </fields> </group>
A <group> statement is handled as an array. Each of the array elements contains all of the subordinate fields defined in the <group> statement. The size of the array is the size of a single array element multiplied by the dimension.
Example 55 <group> statement <procedure name='math_all_structs' filename='prc_samples'> <dbCommand>LANGUAGE=C</dbCommand> <fields> <group name='MATH_STRUCT'> <dbCommand>ORDER=1</dbCommand> <fields> <field name='SUM1' datatype='int4'/> <field name='SUBTRACT' datatype='int4'/> <field name='MULTIPLY' datatype='int4'/> <field name='DIVIDE' datatype='int4'/> </fields> </group> </fields> <parameters> <group name='MATH_IN_STRUCT' > 5-10 AIS User Guide and Reference
<dbCommand>ORDER=2</dbCommand> <fields> <field name='OPER1' datatype='int4'/> <field name='OPER2' datatype='int4'/> </fields> </group> </parameters> </procedure>
<group> Attributes
The attribute is listed in the following table:
Table 53 Attribute Name name <group> Attributes Syntax name="name" Description Specifies the name of the field. This attribute must be specified. For example: <group name="CHILDREN" alias="EMP_CHLDRN" dimension1="4" counterName="CHILD_COUNTER"> <fields>...</fields> </group>
Different nuances of the same data. Different usage of the same physical area in the buffer.
This section describes the common use cases of variants and how they are represented in the variant syntax. There are two types of variants:
Managing Metadata
5-11
In this example one case includes a PARTNUM field of 10 characters while the other case, PARTCD, maps the same part number to a 2 character DEPTCODE, a 3 character SUPPLYCODE and a 5 character PARTCODE. The two variant cases are just different ways of viewing the same item of data. In Attunity Studio, the Import Manipulation screen enables you to replace any variant with the fields of a single case. The metadata generated following a metadata import, appears as follows:
<variant name="VAR_0"> <case name="UNNAMED_CASE_1"> <fields> <field name="PARTNUM" datatype="string" size="10"/> </fields> </case> <case name="PARTCD"> <fields> <field name="DEPTCODE" datatype="string" size="2"/> <field name="SUPPLYCODE" datatype="string" size="3"/> <field name="PARTCODE" datatype="string" size="5"/> </fields> </case> </variant>
In this example each of the records is either an order header record or an order item record, depending on the value of the RECTYPE field. This construct can be mapped as a variant with a selector, where the RECTYPE field is the selector. During a metadata import from COBOL, all variants are assumed to be variants without selectors. The COBOL syntax doesnt distinguish between different types of variants or REDEFINEs. In COBOL, only the program logic includes this distinction.
This is true, unless a selector is specified in the import manipulation screen. Refer to Attunity Studio Guide and Reference for additional information.
ADD Syntax
The following is the ADD syntax to use for setting variants:
<variant name="variant_name"> <case name="case_name" value="val" ...> <fields> <field name="field_name" ... /> </fields> </case> <case ... </case> </variant>
The metadata generated by Attunity Studio following a metadata import appears as follows:
<filed name="RECTYPE" datatype="string" size="1"/> <variant name="VAR_1" selector="RECTYPE"> <case name="ORDER_HEADER" value="H"> <fields> <field name="ORDER_DATE" datatype="numstr_u" size="8"/> <field name="CUST_ID" datatype="numstr_u" size="9" </fields> </case <case name="ORDER_DETAILS" value="D" <fields <field name="PART_NO" datatype="numstr_u" size "9"/> <field name="QUANTITY" datatype="uint4" size="4"/> </fields </case> </variant>
Usage Notes
From an SQL consumer, none of the <variant> or <case> fields are visible. Only the simple fields are accessible. For a variant with a selector, all fields are reported as nullable regardless of their backend definition. For every record instance, only the relevant case will show values the rest of the cases will contain NULLs. When updating or inserting both types of variants, it is up to the User to ensure that only a single case is given values. Attempting to set fields from two or more cases will result in unpredictable behavior.
Managing Metadata
5-13
Note:
2.
Right-click the required variant and select Structures, and then select Mark selector. The Select Selector screen opens.
3. 4.
Select the selector for the variant from the list of available selectors in the COBOL copybook, and then click OK. Repeat for all the required variants, and then click OK.
Syntax
<case name="field_name" attribute="value" ...> <fields> <field name="field_name" attribute="value" ... /> </fields> </case>
Example 58 <case> statement <variant name='VAR_DIVIDE_DATATYPE' selector='DIVIDE_DATATYPE'> <dbCommand>ORDER=5</dbCommand> <case name='CASE_1_1' value='L'> <fields> <field name='DIVIDE_LONG' datatype='int4'/> </fields> </case> <case name='CASE_1_2' value='F'> <fields> <field name='DIVIDE_FLOAT' datatype='single'/> </fields> </case> <case name='CASE_1_3' value='D'> <fields> <field name='DIVIDE_DOUBLE' datatype='double'/> </fields> </case> </variant>
<case> Attributes
The attribute is listed in the following table:
<case> Attributes Syntax name="name" Description Specifies the name of the case. Note: When a selector attribute is not specified in the <variant> statement, a name attribute must be specified here.
value
value="value"
Specifies the value for a variant definition that is used in the current record (row) for the field specified in the <variant> statement via the selector attribute. Note: When a selector attribute is specified in the <variant> statement, a value attribute must be specified here.
Platform and data source-dependent data types run only on their respective platforms.
ADD Supported Data Types ODBC Type SQL_ TIMESTAMP SQL_NUMERIC SQL_NUMERIC SQL_ TIMESTAMP SQL_DATE JDBC Type Details ADABAS date format z/OS ADABAS packed decimal z/OS ADABAS numeric string ADABAS timestamp format Date packed into a 4 character string. Format: DMYY Example: 23-July-1998 is represented by four bytes, 19, 98, 7, and 23
apt_time
DBTYPE_TIMESTAMP
SQL_ TIMESTAMP
Managing Metadata
5-15
Table 55 (Cont.) ADD Supported Data Types ADD Type based_date OLE DB Type DBTYPE_ DBTIMESTAMP ODBC Type SQL_ TIMESTAMP JDBC Type Details Customize this data type by defining an environment variable (UNIX) or logical (OpenVMS) having the form: NVDT_ BASEDDATE=yyyymmdd[/dttyp e[/dtlen[/multiplier]]] where:
yyyymmdd: start date dttype: the name of the data type (int4 is the default). dtlen: the number of digits in the data type (if not atomic). multiplier: the number of increments per day.
Example: 19700101/int4//24 specifies the number of hours since Jan 1 1970. binary bit DBTYPE_BYTES DBTYPE_I1 SQL_BINARY SQL_TINYINT Unknown data type, string type, length must be specified A single bit within a byte. Size: 1 byte Format: datatype="bit" onBit="n", where n specifies which bit (within a byte) the field uses. If more than one bit is defined, the additional bits may be defined sequentially within the same byte (or bytes, if the number of bits requires this much space)
Table 55 (Cont.) ADD Supported Data Types ADD Type bits OLE DB Type DBTYPE_I4 ODBC Type SQL_TINYINT JDBC Type Details A signed number of bits within a byte. Size: 1 bit to 1 byte Format: <field name="name" datatype="bits" onBit="n" size="m"/> where:
n: specifies which bit (within a byte) to start from. m: the number of bits. If n is not specified then n defaults to 1 for the first occurrence of the field and is contiguous thereafter.
The maximum number of bits you can map is 32. cstring DBTYPE_STR SQL_VARCHAR A null-terminated string of alphanumeric characters; maximum length must be specified. An extra byte is required for the null flag. A CorVision date-time format. ODBC date format. Date in a string having the form YYMMDD. Date in a string having the form YYYYMMDD. DB2 UDB date format (OS/400 machine) DB2 UDB date-time format (OS/400 machine). DB2 UDB time format (OS/400 machine). Packed decimal. Maximum number of digits: 31 Maximum fractions: 11 Length: int (number of digits/2) + 1 bytes dfloat DBTYPE_R8 SQL_DOUBLE Double floating point number (D_FLOAT). Size: 8 bytes Range: 0.29E-38 to 1.7E38 Precision: 16 digits
SQL_ TIMESTAMP SQL_DATE SQL_DATE SQL_DATE SQL_ TIMESTAMP SQL_ TIMESTAMP SQL_ TIMESTAMP SQL_NUMERIC
Managing Metadata
5-17
Table 55 (Cont.) ADD Supported Data Types ADD Type double OLE DB Type DBTYPE_R8 ODBC Type SQL_DOUBLE JDBC Type Details Double floating point number (G_FLOAT). Size: 8 bytes Range: 0.56E-308 to 0.90E308 Precision: 15 digits filler DBTYPE_BYTES SQL_BINARY Allocation for future use, string type; length must be specified. A fixed null-terminated string of numeric characters; length must be specified. An extra byte is required for the null flag IEEE double floating point number. IEEE single floating point number. Binary image (BLOB). Date in a four byte integer. Format: YYMMDD or YYYYMMDD Example: 23-Jul-1998 has the form: 980723 or 19980723. int1 DBTYPE_I4 SQL_TINYINT Signed byte integer. Size: 1 byte Range: -128 to +127 int2 DBTYPE_I2 SQL_SMALLINT Signed word integer. Size: 2 bytes Range: -32768 to +32767 int3 DBTYPE_I4 SQL_INTEGER Signed integer. Size: 3 bytes int4 DBTYPE_I4 SQL_INTEGER Signed long integer. Size: 4 bytes Range: -2147483648 to +2147483647 int6 DBTYPE_NUMERIC SQL_INTEGER Signed integer. Size: 6 bytes int8 DBTYPE_NUMERIC SQL_NUMERIC Signed quadword. Size: 8 bytes Range: -9,223,372,036,854,775,808 to +9,223,372,036,854,775,807 isam_decimal DBTYPE_NUMERIC SQL_NUMERIC CISAM and DISAM packed decimal.
fixed_cstring
DBTYPE_NUMERIC
SQL_NUMERIC
Table 55 (Cont.) ADD Supported Data Types ADD Type jdate OLE DB Type DBTYPE_DBDATE ODBC Type SQL_Date JDBC Type Details Julian date. Size: 2 bytes
logical
DBTYPE_I4
SQL_INTEGER
Signed long integer. Values: 1 or true (not case sensitive) are inserted as 1. Any other value is false, and inserted as 0.
Magic PC date format. Magic PC time format. z/OS date format. z/OS date-time format. z/OS time format. String based on language and driven by table. A null-terminated string of numeric characters; maximum length must be specified. An extra byte is required for the null flag. Signed numeric string. Sign is the first character of the string. Maximum number of digits: 31 Maximum fractions: 11 Note: the number of fractions includes the decimal point.
numstr_bdn
DBTYPE_NUMERIC
SQL_NUMERIC
numstr_lse
DBTYPE_NUMERIC
SQL_NUMERIC
HP NonStop signed numeric string. A left overpunched sign is implemented. Maximum number of digits: 31 Maximum fractions: 11
numstr_nl
DBTYPE_NUMERIC
SQL_NUMERIC
Signed numeric string. Sign is the first character of the string. Maximum number of digits: 31 Maximum fractions: 11
Managing Metadata
5-19
Table 55 (Cont.) ADD Supported Data Types ADD Type numstr_nlo OLE DB Type DBTYPE_NUMERIC ODBC Type SQL_NUMERIC JDBC Type Details Signed numeric string. A left overpunched sign is implemented. Maximum number of digits: 31 Maximum fractions: 11 numstr_nr DBTYPE_NUMERIC SQL_NUMERIC Signed numeric string. Sign is the last character of the string. Maximum number of digits: 31 Maximum fractions: 11 numstr_s DBTYPE_NUMERIC SQL_NUMERIC Signed numeric string. A right overpunched sign is implemented. Maximum number of digits: 31 Maximum fractions: 11 The number must be right justified (for example, " 1234N" is -12345). The number can be left padded by either spaces or zeros. If a scale is provided, it is a fixed positional scale; no decimal point is provided in the data (for example, a value of "1234E" with scale 2 is interpreted as "123.45"). numstr_tse DBTYPE_NUMERIC SQL_NUMERIC HP NonStop signed numeric string. A right overpunched sign is implemented. Maximum number of digits: 31 Maximum fractions: 11 numstr_u DBTYPE_NUMERIC SQL_NUMERIC Unsigned numeric string. Maximum number of digits: 31 Maximum fractions: 11 numstr_zoned DBTYPE_NUMERIC SQL_NUMERIC Signed numeric string. Maximum number of digits: 31 Maximum fractions: 11 ole_date ole_decimal ole_numeric ora_time DBTYPE_DBDATE DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_ DBTIMESTAMP SQL_DATE SQL_NUMERIC SQL_NUMERIC SQL_ TIMESTAMP OLE DB date format. OLE DB packed decimal. OLE DB numeric string. Oracle time format.
Table 55 (Cont.) ADD Supported Data Types ADD Type oracle time padded_str_ date padded_str_ datetime padded_str_ time phdate OLE DB Type DBTYPE_ DBTIMESTAMP DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_DBDATE ODBC Type SQL_ TIMESTAMP SQL_CHAR SQL_CHAR SQL_CHAR SQL_Date JDBC Type Details Oracle time format. Padded date format. Not null terminated. Padded date format. Not null terminated. Padded date format. Not null terminated. Size: 2 bytes
Bits 0-6: (non-century) year Bits 7-10: number of month Bits 11-15: day of month
scaled_int1
DBTYPE_NUMERIC
SQL_NUMERIC
scaled_int2
DBTYPE_NUMERIC
SQL_NUMERIC
scaled_int3
DBTYPE_NUMERIC
SQL_NUMERIC
scaled_int4
DBTYPE_NUMERIC
SQL_NUMERIC
scaled_int6
DBTYPE_NUMERIC
SQL_NUMERIC
scaled_int8
DBTYPE_NUMERIC
SQL_NUMERIC
scaled_uint1
DBTYPE_NUMERIC
SQL_DOUBLE
Managing Metadata
5-21
Table 55 (Cont.) ADD Supported Data Types ADD Type scaled_uint2 OLE DB Type DBTYPE_NUMERIC ODBC Type SQL_ NUMERIC(5) JDBC Type Details Unsigned word integer. Size: 2 bytes Range: 0 to 65534 Maximum: 5 scaled_uint4 DBTYPE_NUMERIC SQL_ NUMERIC(10) Unsigned long integer. Size: 4 bytes Range: 0 to 4,294,967,294 Maximum: 10 single DBTYPE_R4 SQL_REAL Single floating point number (F_FLOAT). Size: 4 bytes Range: 0.29E-38 to 1.7 E38 Precision: 6 digits str_date DBTYPE_STR SQL_CHAR Atomic date string. Size: 10 characters Format: YYYY-MM-DD str_datetime DBTYPE_STR SQL_CHAR Atomic date-time string. Size: 23 characters Format: YYYY-MM-DD HH:MM:SS.FFF str_time DBTYPE_STR SQL_CHAR Atomic time string. Size: 8 characters Format: HH:MM:SS string DBTYPE_STR SQL_CHAR String of alphanumeric characters; length must be specified. Date in a string. Format: YYYY-MM-DD tandem_ datetime DBTYPE_DBTIME SQL_TIME Date and time in a string. Format: YYYY-MM-DD:HH:MM:SS.FF FFFF DBTYPE_TIMESTAMP SQL_ TIMESTAMP SQL_CHAR SQL_ TIMESTAMP SQL_ TIMESTAMP Date and time in a string. Format: HH:MM:SS Text data (BLOB). ODBC time format. ODBC date-time format.
tandem_date
DBTYPE_DBDATE
SQL_DATE
tandem_time
Table 55 (Cont.) ADD Supported Data Types ADD Type ubits OLE DB Type DBTYPE_I4 ODBC Type SQL_TINYINT JDBC Type Details An unsigned number of bits within a byte. Size: 1 bit to 1 byte Format: <field name="name" datatype="bits" onBit="n" size="m"/> where:
n: specifies which bit (within a byte) to start from. m: the number of bits. If n is not specified then n defaults to 1 for the first occurrence of the field and is contiguous thereafter.
The maximum number of bits you can map is 31. uint1 DBTYPE_UI1 SQL_TINYINT Unsigned byte integer. Size: 1 byte Range: 0 to +254 uint2 DBTYPE_I4 SQL_INTEGER Unsigned word integer. Size: 2 bytes Range: 0 to +65534 uint4 DBTYPE_NUMERIC SQL_ NUMERIC(11) Unsigned long integer. Size: 4 bytes Range: 0 to +4,294,967,294 uint6 DBTYPE_NUMERIC SQL_NUMERIC Unsigned integer. Size: 6 bytes unicode DBTYPE_WSTR SQL_VARCHAR A null-terminated alphanumeric unicode string; maximum length must be specified 16-bit count, followed by a string. 32-bit count, followed by a string OpenVMS date-time format
ADD Syntax
This section describes the Attunity Connect Data Dictionary. The following statements are described:
Managing Metadata
5-23
The <fields> Statement The <field> Statement The <group> Statement The <variant> Statement The <case> Statement The <keys> Statement The <key> Statement The <segments> Statement The <segment> Statement The <foreignKeys> Statement The <foreignKey> Statement The <primaryKey> Statement The <pKeySegments> Statement
Syntax
<table name="table_name" attribute="value" ...> <fields> <field name="field_name" attribute="value" ... > <dbCommand>...</dbCommand> </field> ... </fields> <keys> <key name="param"> attribute="value" ...> <segments> <segment name="param" attribute="value" ... /> ... </segments> </key> ... </keys> </table>
where table_name is the record/table name. It can be made of a maximum of 40 characters. The <table> statement consists of the following components:
Table Attributes The <fields> Statement. This statement includes the fields list. Optionally, The <keys> Statement, which contains a list of keys.
Notes:
The table_name entry must conform to standard ANSI 92 SQL naming conventions. When you define the structure of a table for a non-relational data source, you must include a <fields> statement. When both <keys> and <fields> statements are present, the <keys> statement must come after the <fields> statement.
Example 59 <table> statement syntax <table name="nation" organization="index" filename="d:\demo\nation" datasource="DEMO"> <fields> <field name="n_nationkey" datatype="int4" /> <field name="n_name" datatype="string" size="25" /> <field name="n_regionkey" datatype="int4" /> <field name="n_comment" datatype="cstring" size="152" /> </fields> </table>
Table Attributes
A table can have the following attributes:
alias: Replaces the table name with a logical name. Names greater than 39 characters are truncated from the left. Syntax:
alias="name"
basedOn: Specifies the table (or virtual table) on which the current table is based. This attribute is generated automatically when an array in a record is generated as a virtual table. Syntax:
basedOn="table_name::array_name"
where: * * table_name: The name of the table which contains the array. If the array is nested in another array, this value is the name of the parent array. array_name: The name of the array in the table.
Example:
<table name="EMP_CHLDRN" organization="index" basedOn="EMPLOYEE::CHILDREN" datasource="DEMO" />
datasource: Specifies the data source name as specified in the binding configuration. The repository for this data source is used to store the ADD information. This attribute must be specified. Syntax:
Managing Metadata
5-25
datasource="datasource_name"
Example:
<table name="nation" filename="d:\demo\nation" organization="index" datasource="DEMO" />
delimited: Specifies the character that delimits fields. In order to get the delimiter character into the data you must have the entire field quoted. See quoteChar further in this section. If you do not specify this attribute, ADD assumes that a comma (,) functions as the delimiting character. Syntax:
delimited="character"
Example:
<table name="nation" filename="d:\demo\nation" organization="index" delimited="/" datasource="DEMO" />
filename: The filename attribute specifies the full name and location of the file. Syntax:
filename="full_filename"
Data source drivers require the file suffix, except for the CISAM and DISAM drivers, where the suffix must not be specified.
Flat files and text delimited on z/OS Platforms When defining metadata for a flat file or text delimited file, use the following syntax: filename="high_level_qualifier.filename" For example: filename="SYS1.AAA.AC.DATATEMP"
Example (RMS):
filename="DISK$2:[DB]NATION.DAT"
Example (DISAM):
filename="d:\demo\nation"
filter: Adds a WHERE clause to every query accessed using this table or procedure. This attribute is useful when more than one logical table is stored in the same physical file. If a query relates to data with a filter attribute defined, then the Attunity Connect Query Processor handles the query including the WHERE clause and will return an error if the query is invalid because of the added WHERE clause. To use the filter attribute, you must set the useTableFilterExpressions environment property to true. You specify this parameter in the queryProcessor node of the environment properties for the relevant binding configuration, in Attunity Studio Design perspective Configuration view. Syntax:
filter="sql_expression"
where sql_expression is a valid SQL expression combining one or more constants, literals and column names connected by operators. Column names must be prefixed with $$$ and the column must exist in the current table. Example:
<table name="nation" filename="d:\demo\nation" organization="index" filter="$$$.RECORD_TYPE = 80" datasource="DEMO" />
nBlocks: Specifies the approximate number of blocks in the table. It is used by Attunity Connect to optimize query execution.
Note: The nRows attribute must be specified if the nBlocks attribute is specified. If neither nRows nor nBlocks is specified for a table, queries over the table might be executed in a non-optimal manner.
Syntax:
nRows="numeral"
organization: Specifies the organization of a file system data provider. The organization can be one of the following: indexed, sequential, relative, or unstructured. The default is sequential. Syntax:
organization="index" | "sequential" | "relative" | "unstructured"
Example:
<table name="nation" filename="d:\demo\nation" organization="index" datasource="DEMO" />
Note:
Attunitys test-delimited and the flat file drivers, both support a sequential organization.
Managing Metadata
5-27
Use unstructured for unstructured Enscribe files that are not indexed. Note that you must include a filler field, of size one, when having an odd record size in an even unstructured Enscribe file. Access to a specific record number of a relative file is performed by using a pseudo column to specify the record position. The hash symbol (#) is used to specify a pseudo column. For example:
SELECT * FROM colleges WHERE # = 6 INSERT INTO colleges(coll_id,coll_name,coll_status,#) VALUES(111,New collage,2,5) DELETE FROM colleges WHERE # = 15
quoteChar: Specifies the character that quotes a string field. In order to quote a field the entire field must be quoted (leading and trailing white space before and after the start and end quote characters, respectively, are allowed). In particular you cannot start or end quoting data in the middle of a field since the quote characters will be interpreted as part of the data. In order to have a quote character in a quoted field you must escape it by preceding it with a backslash. Syntax:
quoteChar="character"
Example:
<table name="nation" filename="d:\demo\nation" organization="index" quoteChar="" datasource="DEMO" />
recordFormat: Used only with RMS data, to identify the underlying RMS record format. This attribute is for information purposes only. Within Attunity Connect, all records are treated as fixed length. Syntax:
recordFormat="undefined" | "fixed" | "variable"
Example:
<table name="nation" datasource="RMS" filename="DKA100:[USER.NAV.RMSDEMO]nation.INX" recordFormat="fixed" organization="index" />
size: Specifies the maximum size, in bytes, of a record. This attribute is useful when you only want to use part of the record. This attribute is generated automatically for RMS, Enscribe, DISAM, and CISAM data. For these data sources, do not specify a size attribute. This attribute is not supported by the flat files driver. Syntax:
size="n"
Example:
<table name="nation" filename="d:\demo\nation" organization="index" size="500" datasource="DEMO" />
tableId: The record number within a DBMS user work area. The BASIC_ADL utility (see DBMS Data Source (OpenVMS Only)) generates ADD metadata from DBMS and automatically creates a tableId attribute.
Note:
Syntax:
tableId="record_number"
Syntax
<dbCommand>text</dbCommand>
Examples
<dbCommand>CMD=^PAK(K1,1)</dbCommand>
The BASIC_ADL utility for generating ADD metadata from DBMS metadata creates a dbCommand statement. For example, for a field, the dbCommand has the following form:
<dbCommand> field-type/set-name/record-name-of-paired-table/ realm-of-paired-table/ insertion-mode/retention-mode </dbCommand>
Managing Metadata
5-29
Syntax
<fields> <field name="field_name" attribute="value" ...> <dbCommand>...</dbCommand> </field> <group name="field_name" attribute="value" ...> <fields> <field name="field_name" attribute="value" ... /> </fields> </group> <variant name="field_name" attribute="value" ...> <case name="field_name" attribute="value" ...> <fields> <field name="field_name" attribute="value" ... /> </fields> </case> ... </variant> ... </fields>
Syntax
<field name="field_name" attribute="value" ...> <dbCommand>...</dbCommand> </field>
Example
The following code defines one field (n_NAME) and its two attributes (datatype and size):
<field name="n_name" datatype="string" size="25" />
Field Attributes
A field can have the following attributes:
autoIncrement: When set to true, specifies that this field is updated automatically by the data source during an INSERT statement and shouldnt be explicitly specified in the INSERT statement. The INSERT statement should include an explicit list of values. This attribute is used for fields such as an order number field whose value is incremented each time a new order is entered to the data source. Syntax:
autoIncrement="true|false"
Example:
<field name="ORDER_NUM" datatype="string" size="6" autoIncrement="true" />
chapterOf: Used for DBMS metadata and specifies that the set member field is a chapter of an owner table. This attribute must be included when accessing a set member as a chapter in an ADO application. The BASIC_ADL utility (see DBMS Data Source (OpenVMS Only) generates ADD metadata from DBMS and automatically creates this attribute. Syntax:
chapterOf="owner_table"
Example:
<field name="_M_CLASS_PART" datatype="string" size="29" chapterOf="CLASS" nullable="true"/
compressedArray: When set to true, any array that has a counter can be marked with the attribute compressedArray. Compressed arrays can be groups or single fields and they store only the members that have a value. Thus, a compressed array with a maximum of 100 elements that has only 5 elements in a particular record will include only the 5 elements in the physical file. Records are compressed and decompressed for READ and WRITE operations.
Note:
Syntax:
compressedArray="true|false"
emptyValue: Specifies the value for the field during an insert operation, when a value is not specified. Syntax:
emptyValue="value"
Example:
<field name="RECORD_TYPE" emptyValue="80" datatype="int4" />
explicitSelect: When set to true, specifies that this field is not returned when you execute a "SELECT * FROM..." statement. To return this field, you must explicitly ask for it (in a query such as "SELECT NATION_ID, SYSKEY FROM NATION" where SYSKEY is a field defined with explicitSelect). Syntax:
Managing Metadata 5-31
explicitSelect="true|false"
Example:
<field name="_M_CLASS_PART" datatype="string" size="29" explicitSelect="true" nullable="true" />
Note:
You can disable this attribute by specifying the disableExplicitSelect attribute for the data source in the binding.
hidden: When set to true, specifies that the field is hidden from users. The field is not displayed when a DESCRIBE statement is executed on the table. Syntax:
hidden="true|false"
Example:
<field name="CURRENT_SALARY" hidden="true" datatype="decimal" size="9" />
name: Specifies the name of the field. This attribute must be specified. Syntax:
name="name"
Example:
<field name="EMP_ID" datatype="int4" />
nonSelectable: When set to true, specifies that the field is never returned when you execute an SQL statement. The field is displayed when a DESCRIBE statement is executed on the table. Syntax:
nonSelectable="true|false"
Example:
<field name="EMP_ID" description="EMPLOYEE ID" datatype="int4" nonSelectable="true" />
nonUpdateable: When set to true, specifies that the field cannot be updated (the default is false). Syntax:
nonUpdateable="true|false"
Example:
<field name="EMP_ID" description="EMPLOYEE ID" datatype="int4" nonupdateable="true" />
nRows: Specifies the approximate count of distinct column values in the table. It is used by Attunity Connect to optimize the query execution.
Syntax:
nRows="numeral"
nullable: When set to true, specifies that the field can contain NULL values. Syntax:
nullable="true|false"
Example:
<field name="_M_CLASS_PART" datatype="string" size="29" explicitSelect="true" nullable="true" />
nullSuppressed: When set to true, causes the query optimizer to ignore strategies that use a key or segment that includes a field defined as null-suppressed (that is, when rows whose value for this field is NULL do not appear in the key). For example, normally the query optimizer would use a key for a query including an ORDER BY attribute on this field. If nullSuppressed is not specified, then the query may return incomplete results when the key is used in the optimization plan. If nullSuppressed is set to true, the key is not used. To retrieve rows in a table for a field with the nullSuppressed attribute specified and that have a NULL value, specify NULL in the WHERE clause and not a value. That is, specify:
WHERE field= NULL
Syntax:
nullSuppressed="true|false"
Example:
<field name="AGE" nullSuppressed="true" datatype="int4" />
nullValue: Specifies the null value for the field where the data source does not support null values, thereby providing a means of assigning a "null" value. A select statement returns the value as NULL. Syntax:
nullValue="value"
Managing Metadata
5-33
offset: Specifies an absolute offset for the field in a record. When used with a field whose data type is BIT, the offset can be stated for the first BIT data type. All following BIT data types refers to the same offset if possible. When the last mapped bit is the 8th bit, the next bit is mapped to the first bit in the next byte. Syntax:
offset="n"
Example:
<field name="EMP_ID" offset="3" datatype="int1"/> <field name="CHECK_DIGIT1" offset="3" datatype="bit" onBit="1" /> <field name="CHECK_DIGIT2" datatype="bit"/>
onBit: Specifies the position of the bit in a field with data type BIT or the starting position in a field with data type BITS. Syntax:
onBit="n"
where: * * For the BIT data type: Specifies which bit the field uses. For the BITS data type: Specifies which bit (within a byte) to start from. If n is not specified then n defaults to 1 for the first occurrence of the field and is contiguous thereafter.
where: * For decimal and numeric data types: The number of digits that are fractions. The number of fractions must not be greater than the number of digits. The default value is 0. For scaled data types: The number of digits. The number must be negative.
Example:
<field name="SALARY" datatype="numstr_s" size="10" scale="2" />
where n is the number of characters or digits. The digit must be greater than 0. For the BITS data type, n specifies the number of used bits, starting from the value specified in the onBits attribute.
subfieldOf: The value for this attribute is generated automatically when you generate ADD metadata from ADABAS data that includes a superdescriptor based on a subfield. A field is created to base this index on, and set to the offset specified as the value of the subfieldStart attribute.
If a subfieldStart attribute is not specified, then the subfield is set by default to an offset of 1. Syntax:
subfieldOf="parent_field"
subfieldStart: The offset within the parent field where a subfield starts. If a subfieldStart attribute is not specified, then the subfield is set by default to an offset of 1. Syntax:
subfieldStart="offset_number"
Syntax
<group name="field_name" attribute="value" ...> <dbCommand>...</dbCommand> <fields> <field name="field_name" attribute="value" ... /> </fields> </group>
A <group> statement is handled as an array. Each of the array elements contains all of the subordinate fields defined in the <group> statement. The size of the array is the size of a single array element multiplied by the dimension.
Example
An array containing information about an employees children can be defined as follows:
<group name="CHILDREN" dimension1="4" > <fields> <field name="DATE_OF_BIRTH" datatype="vms_date" /> <field name="NAME" datatype="string" size="16" /> </fields> </group>
The CHILDREN structure has 4 occurrences numbered from 0 to 3. Each occurrence consists of two fields, DATE_OF_BIRTH and CHILD_NAME. The size of the single structure occurrence is 20 (4 bytes for DATE_OF_BIRTH and 16 bytes for CHILD_ NAME), and the total size of the CHILDREN array is therefore 80.
Group Attributes
A group can have the following attributes:
alias: Used to replace the default virtual table name automatically generated for an array. Virtual table names are generated by appending the array name to the parent name (either the record name or a parent array name). Thus, when an array includes another array the name of the nested array is the name of the record and the parent array and the nested array.
Managing Metadata
5-35
When the default generated virtual table name is too long to be usable or over 39 characters, specify an alias to replace the long name. Names greater than 39 characters are truncated from the left. Syntax:
alias="name"
Example:
<group name="CHILDREN" alias="EMP_CHLDRN" dimension1="4" counterName="CHILD_COUNTER"> ... </group>
counterName: Specifies the name of a field that counts the number of the elements stored in an array. Syntax:
counterName="field_name"
where field_name is the name of a field that counts the number of elements stored in the array. The counterName attribute cannot be used with an Attunity Connect procedure.
Note:
For an ADABAS database, you dont need to define a counter field since one is created automatically with the name C-arrayname, where arrayname is the multiple value field name or periodic group field name in ADABAS.
Example: An array containing information about an employee and the employees children can be defined as follows:
<table name="EMPLOYEE" organization="index" nRows="4" filename="d:\ddescription: isam\EMPLOYEE" datasource="DISAMDEMO"> <fields> <field name="EMP_ID" description="EMPLOYEE ID" datatype="int4" /> <field name="CHILD_COUNTER" datatype="int4" /> <group name="CHILDREN" alias="EMP_CHLDRN" dimension1="4" counterName="CHILD_COUNTER"> <fields> <field name="AGE" description="AGE" datatype="int4" /> ... </fields> </group> ... </fields> </table>
Syntax:
dimension1="n"
where n indicates the number of elements in the array. The dimension1 attribute cannot be used with an Attunity Connect procedure.
Note:
This syntax is for a one-dimensional array. For a two-dimensional array, you specify dimension2="n".
Example: An array containing information about an employee and the employees children can be defined as follows:
<table name="EMPLOYEE" organization="index" nRows="4" filename="d:\disam\EMPLOYEE" datasource="DISAMDEMO"> <fields> <field name="EMP_ID" description="EMPLOYEE ID" datatype="int4" /> <field name="CHILD_COUNTER" datatype="int4" /> <group name="CHILDREN" alias="EMP_CHLDRN" dimension1="4" counterName="CHILD_COUNTER"> <fields> <field name="AGE" description="AGE" datatype="int4" /> ... </fields> </group> ... </fields> </table>
To create the EMP_CHLDRN child table, import the table metadata to the Attunity Connect repository (by right-clicking the data source in Attunity Studio Design perspective Metadata view and selecting Import XML definitions).
name: Specifies the name of the field. This attribute must be specified. Syntax:
name="name"
Example:
<group name="CHILDREN" alias="EMP_CHLDRN" dimension1="4" counterName="CHILD_COUNTER"> <fields> ... </fields> </group>
Managing Metadata
5-37
Different nuances of the same data. Different usage of the same physical area in the buffer.
This section describes the common use cases of variants and how they are represented in the variant syntax. The following variant types are available:
COBOL Example:
20 PARTNUM PIC X(10). 20 PARTCD REDEFINES PARTNUM. 30 DEPTCODE PIC X(2). 30 SUPPLYCODE PIC X(3). 30 PARTCODE PIC X(5).
In this example one case includes a PARTNUM field of 10 characters while the other case, PARTCD, maps the same part number to a 2 character DEPTCODE, a 3 character SUPPLYCODE and a 5 character PARTCODE. The two variant cases are just different ways of viewing the same item of data. In Attunity Studio, the Import Manipulation Panel enables replacing any variant with the fields of a single case. The metadata generated by Studio following a Metadata import appears as follows:
<variant name="VAR_0"> <case name="UNNAMED_CASE_1"> <fields> <field name="PARTNUM" datatype="string" size="10"/> </fields> </case> <case name="PARTCD"> <fields> <field name="DEPTCODE" datatype="string" size="2"/> <field name="SUPPLYCODE" datatype="string" size="3"/> <field name="PARTCODE" datatype="string" size="5"/> </fields> </case> </variant> 5-38 AIS User Guide and Reference
COBOL Example:
10 ORDER. 20 RECTYPE PIC X. 88 ORD-HEADER VALUE H. 88 ORD-DETAILS VALUE D. 20 ORDER-HEADER. 30 ORDER-DATE PIC 9(8). 30 CUST-ID PIC 9(9). 20 ORDER-DETAILS REDEFINES ORDER-HEADER. 30 PART-NO PIC 9(9). 30 QUANTITY PIC 9(9) COMP.
In this example each of the records is either an order header record or an order item record, depending on the value of the RECTYPE field. This construct can be mapped as a variant with a selector, where the RECTYPE field is the selector. During a metadata import from COBOL, all variants are assumed to be variants without selectors. The COBOL syntax doesnt distinguish between different types of variants or REDEFINEs. In COBOL, only the program logic includes this distinction. This is true, unless a selector is specified in the import manipulation panel. See Working with Metadata in Attunity Studio for additional information.
ADD Syntax: The following is the ADD syntax used for setting variants:
<variant name="variant_name"> <case name="case_name" value="val" ...> <fields> <field name="field_name" ... /> </fields> </case> <case ... </case> </variant>
The metadata generated by Attunity Studio following a metadata import appears as follows:
<field name="RECTYPE" datatype="string" size="1"/> <variant name="VAR_1" selector="RECTYPE"> <case name="ORDER_HEADER" value="H"> <fields> <field name="ORDER_DATE" datatype="numstr_u" size="8"/> <field name="CUST_ID" datatype="numstr_u" size="9"/> </fields>
Managing Metadata
5-39
</case> <case name="ORDER_DETAILS" value="D"> <fields> <field name="PART_NO" datatype="numstr_u" size="9"/> <field name="QUANTITY" datatype="uint4" size="4"/> </fields> </case> </variant>
Usage Notes
From an SQL consumer, none of the <variant> or <case> fields are visible. Only the simple fields are accessible. For a variant with a selector, all fields are reported as nullable regardless of their backend definition. For every record instance, only the relevant case will show values the rest of the cases will contain NULLs. When updating or inserting both types of variants, it is up to the user to ensure that only a single case is given values. Attempting to set fields from two or more cases will result in unpredictable behavior.
Right-click the variant and select Structures, and then Mark selector. The Select Selector Field screen opens.
3. 4. 5. 6.
Select the selector for the variant from the list of selectors in the COBOL copybook. Click OK. Repeat as needed to set variants with selectors. Click OK.
Variant Attributes
A variant can have the following attributes:
name: Specifies the name of the variant. This attribute must be specified. Syntax:
name="name"
Example:
<variant name="VAR_SEX" selector="SEX"> <case name="CASE_1_1" value="M"> <fields> <field name="M_SCHOOL" datatype="string" size="20" /> </fields>
</case> <case name="CASE_1_2" value="F"> <fields> <field name="F_SCHOOL" datatype="string" size="20" /> </fields> </case> </variant>
selector: Specifies the name of a field whose value determines which of the alternate variant definitions is used in the current record (row). When a selector attribute is specified, a value attribute must be specified in the <case> statement. Syntax:
selector="field_name"
Example:
<field name="SEX" datatype="string" size="1" /> <variant name="VAR_SEX" selector="SEX"> <case name="CASE_1_1" value="M"> <fields> <field name="M_SCHOOL" datatype="string" size="20" /> </fields> </case> <case name="CASE_1_2" value="F"> <fields> <field name="F_SCHOOL" datatype="string" size="20" /> </fields> </case> </variant>
Syntax
<case name="field_name" attribute="value" ...> <fields> <field name="field_name" attribute="value" ... /> </fields> </case>
Case Attributes
A case can have the following attributes:
Managing Metadata
5-41
name: Specifies a name for the case. When a selector attribute is not specified in the <variant> statement, a name attribute must be specified here. Syntax:
name="name"
Example:
<variant name="VAR_SEX" selector="SEX"> <case name="CASE_1_1" value="M"> <fields> <field name="M_SCHOOL" datatype="string" size="20" /> </fields> </case> <case name="CASE_1_2" value="F"> <fields> <field name="F_SCHOOL" datatype="string" size="20" /> </fields> </case> </variant>
value: Specifies the value for a variant definition that is used in the current record (row) for the field specified in the <variant> statement via the selector attribute. When a selector attribute is specified in the <variant> statement, a value attribute must be specified here. Syntax:
value="value"
Example:
<case name="CASE_1_1" value="M"> <fields> <field name="M_SCHL" datatype="string" size="20" /> </fields> </case> <case name="CASE_1_2" value="F"> <fields> <field name="F_SCHL" datatype="string" size="20" /> </fields> </case>
Syntax
<keys> <key name="key_name" attribute="value" ...> <segments> 5-42 AIS User Guide and Reference
<segment name="segment_name" attribute="value" ... /> ... </segments> </key> <key name="key_name" ...> <segments> <segment name="segment_name" ... /> ... </segments> </key> </keys>
Example
<keys> <key name="nindex" unique="true"> <segments> <segment name="n_nationkey" /> </segments> </key> </keys>
Syntax
<key name="key_name" attribute="value" ...> <dbCommand>...</dbCommand> <segments> <segment name="segment_name" attribute="value" ... /> ... </segments> </key>
Key Attributes
A key can have the following attributes:
bestUnique: When set to true, specifies that the query optimization chooses an optimization strategy that uses this key in preference to any other strategy. Use this attribute on keys containing a field which represents a bookmark of the record (and consequently retrieval is assumed to be faster than with other keys). Fields that represent a bookmark include ROWID in Oracle, DBKEY in DBMS and ISN in ADABAS. Syntax:
bestUnique="true|false"
Example:
<key unique="true" bestUnique="true" hashed="true"> <segments>
Managing Metadata
5-43
clustered: When set to true, indicates that this key reflects the physical organization of the table and is used to determine the query optimization strategy used by Attunity Connect. Syntax:
clustered="true|false"
Example:
<key clustered="true"> <segments> <segment name="DBKEY" /> </segments> </key>
descending: When set to true, specifies whether the order of the current key is descending. If this attribute is not specified for the key, it can be specified per segment of the key. The default is ASCENDING. Syntax:
descending="true|false"
Example:
<key unique="true" descending="true" nRows="30"> <segments> <segment name="EMPLOYEE_ID" /> </segments> </key>
hashed: When set to true, indicates that this is a hash key and is used to determine the query optimization strategy used by Attunity Connect. Syntax:
hashed="true|false"
Example:
<key unique="true" bestUnique="true" hashed="true"> <segments> <segment name="ISN" /> </segments> </key>
hierarchical: When set to true, specifies that the query optimization chooses an optimization strategy that uses this key in preference to any other strategy. Use this attribute for DBMS databases, on keys containing a DBKEY field which represents a bookmark of the record (and consequently retrieval is assumed to be faster than with other keys). Syntax:
hierarchical="true|false"
Example:
<key unique="true" hierarchical="true" > <segments> <segment name="DBKEY" /> </segments> </key>
indexId: Identifies the physical key for the record. You can use this attribute only with the key and not with a segment. The use of the field is data source dependent. Syntax:
indexId="previously_defined_key"
For an Enscribe alternate key, the indexId attribute is the ASCII value corresponding to the 2 bytes of the key specifier surrounded by quotes. For details, see Enscribe Data Source (HP NonStop Only).
nRows: Specifies the approximate count of distinct key values in the key. It is used by Attunity Connect to optimize query execution. For a unique key, the nRows value must be equal to the nRows value for the record (that is, the number of distinct key values is the same as the number of rows). Syntax:
nRows="numeral"
nullSuppressed: When set to true, causes the query optimizer to ignore strategies that use a key that includes a field defined as null-suppressed (that is, when rows whose value for this field is NULL do not appear in the key). For example, normally the query optimizer would use a key for a query including an ORDER BY attribute on this field. If nullSuppressed is not specified, the query may return incomplete results when the key is used in the optimization plan. If nullSuppressed is specified, the key is not used. To retrieve rows in a table for a field with the nullSuppressed attribute specified and that have a NULL value, specify NULL in the WHERE clause and not a value. That is, specify:
WHERE field=NULL
unique: When set to true, indicates that each key entry uniquely identifies one row and is used to determine the query optimization strategy used by Attunity Connect. Syntax:
unique="true|false"
Example:
Managing Metadata 5-45
Syntax
<segments> <segment name="segment_name" attribute="value" .../> ... </segments>
Syntax
<segment name="segment_name" attribute="value" ... <dbCommand>...</dbCommand> </segment>
Segment Attributes
Each segment can have the following attributes:
descending: When set to true, specifies the order of the current segment is descending. The default is ASCENDING. Syntax:
descending="true|false"
Example:
<key unique="true" nRows="30"> <segments> <segment name="EMPLOYEE_ID" descending="true" /> </segments> </key>
name: Specifies the name of the segment. This attribute must be specified. Syntax:
name="name"
Example:
<key unique="true" nRows="30"> <segments>
nRows: Specifies the approximate count of distinct segment values in the key. It is used by Attunity Connect to optimize query execution. Syntax:
nRows="numeral"
nullsLast: When set to true, causes value comparison operations to treat nulls as the greater of the values being compared. Syntax:
nullLast="true|false"
nullSuppressed: When set to true, causes the query optimizer to ignore strategies that use a segment that includes a field defined as null-suppressed (that is, when rows whose value for this field is NULL do not appear in the key). Syntax:
nullSuppressed="true|false"
The <foreignKeys> statement is not available in the Attunity Studio Design perspective Metadata view.
Syntax
<foreignKeys> <foreignKey name="key_name" attribute="value" ...> <fkeySegments> <fkeySegment attribute="value" ... /> </fkeySegments> </foreignKey> </foreignKeys>
The name of the foreign key. The external table reference by the foreign key. The primary key of the referencing table. The segments of the foreign key. The referential integrity rule to be implemented when the primary key field in the referencing table is either updated or deleted.
Managing Metadata 5-47
Note:
The <foreignKey> statement is not available in the Attunity Studio Design perspective Metadata view.
Syntax
<foreignKey name="key_name" referencingTable="external_table" referencingPKey="external_table_ primary_key" updateRule="cascade|restrict|setNull"> deleteRule="cascade|restrict|setNull"> <fkeySegments> <fkeySegment fname="local_table_field" pName="referenced_table_field"/> ... </fkeySegments> </foreignKey>
Example
<foreignKeys> <foreignKey name="fkey1" referencingTable="table2" referencingPKey="table2_pkey" updateRule="cascade" deleteRule="setNull"> <fKeySegments> <fKeySegment fName="col2" pName="table2_col3" /> <fKeySegment fName="col5" pName="table2_col2" /> </fKeySegments> </foreign_key> <foreignKey name="fkey2" referencingTable="table3" referencingPKey="table3_pkey" updateRule="restrict" deleteRule="restrict"> <fKeySegments> <fKeySegment fName="col1" pName="table3_col1" /> </fKeySegments> </foreignKey> </foreignKeys>
foreignKey Attributes
Each foreignKey can have the following attributes:
name: The name of the foreign key. referencingTable: The name of the external table referenced by the foreign key. referencingKey: The primary key of the external referencing table. updateRule: The referential integrity rule for the foreign key when the primary key of the referenced table is updated. The specific option is determined by the application accessing the data: cascade restrict setNull
deleteRule: The referential integrity rule for the foreign key when the primary row of the referenced table is deleted. The specific option is determined by the application accessing the data: cascade restrict setNull
fName: The name of the external field referenced in this foreign key segment. pName: The name of the local field referenced in this foreign key segment.
The <primaryKeys> statement is not available in the Attunity Studio Design perspective Metadata view.
Syntax
<primaryKey name="name"> <pKeySegments> <pKeySegment segment="name"/> ... </pKeySegments> </primaryKey>
The <pKeySegment> statement is not available in the Attunity Studio Design perspective Metadata view.
Syntax
<pKeySegments> <pKeySegment segment="name"/> ... </pKeySegments>
Example
<primaryKey name="pk"> <pKeySegments> <pKeySegment segment="col1"> <pKeySegment segment="col2"> </pKeySegments> </primaryKey>
Managing Metadata
5-49
pKeySegment Attributes
The pKeySegment statement can have the segment attribute, which specifies the name of a segment constituting the primary key of a table.
6
Working with Metadata in Attunity Studio
This chapter includes the following sections:
Overview Managing Data Source Metadata Importing Data Source Metadata with the Attunity Import Wizard Working with Application Adapter Metadata
Overview
AIS uses metadata to access and read a data source. AIS can use the native metadata for many data sources, such as Relational Data Sources or Adabas. However, some data sources require Attunitys own metadata (ADD). Metadata can be imported, saved, and managed in the Attunity Studio Design perspective, on the Metadata tab. The following data sources require Attunity metadata:
CISAM /DISAM Data Source DBMS Data Source (OpenVMS Only) Enscribe Data Source (HP NonStop Only) Flat File Data Source IMS/DB Data Sources RMS Data Source (OpenVMS Only) Text Delimited File Data Source VSAM Data Source (z/OS) OLEDB-FS (Flat File System) Data Source
6-1
To view and edit data source metadata 1. In the Design perspective Configuration view, expand the Machines folder and then expand the machine where you want to add the data source.
2. 3. 4.
Expand the Bindings folder and then expand the binding with the data source metadata you are working with. Expand the Data Source folder. Right-click the data source for which you want to manage the metadata and select Show Metadata View. The Metadata tab opens with the selected data source displayed in the Configuration view.
5.
Right-click the resource (such as the data source table) in the Metadata view and select Edit.
Data source tables are edited using the following tabs, which are at the bottom of the editor screen:
General Tab: Enter general information about the table, such as the table name and the way the table is organized, and the location of the table. Columns Tab: Edit information about the table columns and their properties. For example, the column data type, size, and scale. Indexes Tab: Edit information about the indexes of a table. The indexes are described by the order of the rows they retrieve, the data source commands used, and the index type. Statistics Tab: Enter the statistics for the table, including the number of rows and blocks in the table. Source Tab: View the metadata in its XML representation.
Note:
Attunity Connect provides a relational model for all data sources defined to it. Thus, relational terminology is used, even when referring to non-relational data sources (File-system Data Source). For example, the metadata for an RMS record is referred to as the metadata for an RMS table.
General Tab
The General tab lets you maintain information about the table, such as the table name and the way the table is organized.
Note:
Index: Select this if the source data has an index column. All searches are according to the index column. Sequential: Select this if the source does not have a key and all requests search the table columns sequentially. Relative: Access to a specific record number of a relative file is performed by using a pseudo column to specify the record position. The (#) symbol indicates a pseudo column.
6-3
Table 61 (Cont.) Metadata General Tab Field name Maximum record length Description The maximum size of the record in bytes. The value for this field is generated automatically for RMS, Enscribe, DISAM, and CISAM data. For these data sources, leave this field empty. Delimited Quote Character Record Format Enter a character to act as a delimiter in the metadata. If nothing is entered, a comma (,) is used as the delimiter. The character that quotes a string field. Select how the record is formatted according to its size.
Undefined: There is no set definition for the record size. Fixed: The record length is fixed. Variable: The record length varies.
Enter special commands for the data source you are working with. You can create a filter by entering a WHERE clause. You should use a filter when more than one logical table is stored in the same physical file. To enter a filer, click Set filter expression and enter an expression in the field below. The following is an example of the WHERE clause syntax: "$$$.expression" Note: To use a filter, you must select use Table Filter Expressions in the Query Processorsection of the Environment Properties in Attunity Studio.
Columns Tab
The Columns tab lets you specify ADD metadata that describes the table columns. This tab is divided into the following:
Size Scale
6-5
Table 62 (Cont.) Metadata Column Tab Definitions Field name Dimension Description The maximum number of occurrences of a group of columns that make up an array. The (+) to the left of a column indicates a group field. This type of field will have a Dimension value. Click (+) to display the group members. Offset Fixed offset An absolute offset for the field in a record. This column lets you determine whether to calculate the offset. There are two options:
Calc offset: If you clear this check box, the absolute offset for each of the columns is calculated. Fixed offset: When you select this check box, you will have a fixed offset. The offset of a field is usually calculated dynamically by the server at runtime according the offset and size of the proceeding column. Select the check box in this column to override this calculation and specify a fixed offset at design time. This can happen if there is a part of the buffer that you want to skip. By selecting the check box, or by editing the offset value you pin the offset for that column. The indicated value is used at runtime for the column instead of a calculated value. Note that the offset of following columns that do not have a fixed offset are calculated from this fixed position.
Primary Key
The buttons on the right side of the tab are used to manipulate the data in this section of the tab. The following table describes how you can move around in this section.
Table 63 Button Insert Up Down Rename Delete Find Definition Section Buttons Description Inserts a column to the table. You can insert a new column. If the table has arrays, you can add a new child column. Moves your selection to the column directly above where the currently selected column. Moves your selection to the column directly below where the currently selected column Lets you rename the selected column. Deletes the selected column. Click this button to open a list of all columns in the database. Select a column and click OK to select it in the table.
Column Properties
You can change the property value by clicking in the Value column. Follow these steps for displaying the column properties. To display the column properties Select a column from the Column Definition (top) section. The properties for the column are displayed at the bottom of the tab.
The following table shows some of the properties available for selected columns.
Table 64 Property Alias Metadata Properties Description A name used to replace the default virtual table name for an array. Virtual table names are created by adding the array name to the record name. When an array includes another array the name of the nested array is the name of the record and the parent array and the nested array. When the default generated virtual table name is too long, use an Alias to replace the long name. The current field is updated automatically by the data source during an INSERT statement and is not explicitly defined in the INSERT statement. The INSERT statement should include an explicit list of values. This attribute is used for fields such as an order number field whose value is incremental each time a new order is entered to the data source. A short note or description about the column. Click the button to enter data source-specific commands for the column. The value for the field in an insert operation, when a value is not specified. When true, the current field is not returned when you execute a SELECT * FROM... statement. To return this field, you must explicitly ask for it in a query, for example, SELECT NATION_ ID, SYSKEY FROM NATION where SYSKEY is a field defined with explicitSelect. You cannot use an asterisk (*) in a query where you want to retrieve a field defined with the explicitSelect value. You can disable this value by entering the disableExplicitSelect value in the data source bindings Environment Properties. Hidden Non Selectable The current field is hidden from users. The field is not displayed when a DESCRIBE statement is executed on the table. When true, the current field is never returned when you execute an SQL statement. The field is displayed when a DESCRIBE statement is executed on the table. If true, the current field cannot be updated. This value allows the current field to contain NULL values. The null value for the field during an insert operation, when a value is not specified. This property shows that the set member field is a chapter of an owner field. A value for this property must be used when accessing a set member as a chapter in an ADO application. This property is used for DBMS metadata OnBit Subfield of The position of the bit in a BIT field and the starting bit in a BITS field. The value is generated automatically when you generate ADD metadata from Adabas data that includes a superdescriptor based on a subfield. A field is created to base this index on, set to the offset specified as the value of the Subfield start field. If no value is entered in the Subfield start field, the subfield is set by default to an offset of 1.
Autoincrement
6-7
Table 64 (Cont.) Metadata Properties Property Subfield start Description The offset within the parent field where a subfield starts.
Indexes Tab
The Indexes tab lets you indicate ADD metadata describing the table indexes.
Note: This tab contains information only if the Organization field in the General tab is set to Index.
Figure 63 Data Source Metadata Indexes Tab
This tab has two sections. The first section lets you define the index keys for the columns in the table. The bottom of the tab lists the properties for each of the columns at the top.
Table Information
The following table describes the fields for the top part of the tab, which defines the indexes used for the table.
Table 65 Field Name Order Index Definitions Fields Description The name of the column used as an index for the current table. The row order that the index gets back.
Table 65 (Cont.) Index Definitions Fields Field DB Command Description Data source-specific commands for the index.
The buttons on the right side of the tab are used to manipulate the data in this section of the tab. The following table describes how you can move around in this section.
Table 66 Button Insert Rename Index Delete Index Definition Buttons Description Inserts an index to the table. Lets you rename the selected index. Deletes the selected index.
Properties
You can index properties for each index column. Follow these steps for displaying the properties for each index. To display the index properties Select a column from the Index Definitions (top) section. The properties for the column are displayed at the bottom of the tab. This properties displayed at the bottom of the tab describe the index or segment. The properties available depend on the data source.
Statistics Tab
The Statistics tab lets you specify metadata statistics for a table. Statistics can be updated with the Update Statistics utility.
6-9
Table
Enter the statistical information for the table in this section.
Rows: Enter or use the arrows to select the approximate number of rows in the table. If the value is -1, the number of rows in the table is unknown (no value was supplied and the update statistics utility was not run to update the value). A value of 0 indicates that this table is empty. Blocks: Enter or use the arrow to select the approximate number of blocks in the table.
Note:
If no value is entered for the number of rows or the number of blocks, queries over the table may not be executed effectively.
Columns
Enter the cardinality for each of the columns in the table in this section.
Column Name: The columns in the table. Cardinality: The number of distinct values for the column. If the value is -1, the number of distinct values for the column is unknown (a value was not supplied
and the update statistics utility was not run to update the value). A value of 0 indicates that there are no distinct values for the column.
Indexes
Enter the cardinality for the columns in each of the tables indexes in this section.
Indexes and Segments: The indexes and segments in the table. Cardinality: The number of distinct key values in the index. If the value is -1, the number of distinct key values in the index is unknown (no value was supplied and the update statistics utility was not run to update the value). A value of 0 indicates that there are no distinct key values in the index.
Update Button
Update: Opens the Update Statistics window. AIS collects information about tables, indexes, and column cardinalities. These statistics can be used to optimize a query using the Query Optimizer, which finds the most efficient way to perform a query across multiple machines. This is done using the metadata statistics.
Figure 65 Metadata Statistic Update Window
where:
Type: The type of statistic information being added. Estimated: An estimation of the amount of statistical information returned. Estimated with Rows: An estimation of the amount of statistical information returned. Including an estimation of the number of rows in the table. Specify the number in the text box. This number is used to shorten the time to produce the statistics, assuming that the value specified here is the correct value, or close to the correct value.
Note:
When the number of rows in the table is not provided, the number of rows used is determined as the maximum value between the value specified in the tuning DsmMaxBufferSize environment property and the value set in the nRows attribute (specified as part of the metadata for the data source)
Exact: The exact statistical information returned. Note that this can be a lengthy task and can lead to disk space problems with large tables.
Resolution: The level of the statistical information returned. Default: Only information about the table and indexes is collected. Information for partial indexes and columns is not collected. All Columns and Indexes: Information about the table, indexes, partial indexes and columns is collected. Select Columns and Indexes: Lets you select the columns and indexes you want to collect statistics for. In the enabled list of columns and/or indexes left click those columns you want included (you can use shift-click and control-click to select a number of columns and/or indexes).
The statistics are updated on the server, enabling work to continue in Attunity Studio. A message is displayed in Attunity Studio when the statistics on the server have been updated.
Modelling Tab
The Modelling tab lets you enter information about the virtual view policy for arrays. These parameters are valid only if you are using virtual array views. You configure virtual array views in the Modeling section of the binding Environment Properties.
The configurations made in this editor are for the selected table, only. The same parameters are configured on the data source level in the data source editor.
Figure 66 Data Source Metadata Advanced Tab
Generate sequential view: Select this to map non-relational files to a single table. Generate virtual views: Select this to have individual tables created for each array in the non-relational file. Include row number column: Select one of the following: true: Select true, to include a column that specifies the row number in the virtual or sequential view. This is true for this table only, even in the data source is not configured to include the row number column. false: Select false, to not include a column that specifies the row number in the virtual or sequential view for this table even if the data source is configured to include the row number column. default: Select default to use the default data source behavior for this parameter.
For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties.
Inherit all parent columns: Select one of the following: true: Select true, for virtual views to include all the columns in the parent record. This is true for this table only, even in the data source is not configured to include all of the parent record columns.
false: Select false, so virtual views do not include the columns in the parent record for this table even if the data source is configured to include all of the parent record columns. default: Select default to use the default data source behavior for this parameter.
For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties.
Adabas C Data Source Enscribe Data Source (HP NonStop Only) Flat File Data Source IMS/DB Data Sources RMS Data Source (OpenVMS Only) VSAM Data Source (z/OS)
For Importing Procedure Metadata, an import wizard is available for these procedure data sources:
Attunity metadata is independent of its origin. Therefore, any changes made to the source metadata (for example, the COBOL copybook) are not made to the Attunity metadata
In the Design perspective Configuration view, expand the Machines folder and then expand the machine with the data source where you are importing the metadata. Expand the Bindings folder and expand the binding with the data source metadata you are working with.
3.
4. 5.
Expand the Data Source folder and. Right-click the data source that you are working with and select Show Metadata View. The Metadata view opens with the selected data source displayed.
6.
Right-click Imports under the data source and select New Import. The New Import dialog box is displayed, as shown in the following figure:
7. 8. 9.
Enter a name for the import. The name can contain letters, numbers and the underscore character. Select the Import type from the list. The import types in the list depend on the data source you are working with. Click Finish. The Metadata import wizard opens with the Get Input Files screen, as described in the Selecting the Input Files step.
2. 3.
If the files are on another machine, then right-click My FTP Sites and select Add. Set the FTP data connection by entering the server name where the COBOL copybooks reside and, if not using anonymous access, enter a valid username and password to access the Machine. To browse and transfer files required to generate the metadata, access the machine using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory.
4.
5.
Select the files to import and click Finish to start the transfer. The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns together with a COBOL copybook that ignores the first six columns. In this type of case, repeat the import process. You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks. The selected files are displayed in the Get Input Files screen of the wizard, as shown in the following figure.
6.
To manipulate table information or the fields in the table, right-click the table and select the option you want. The following options are available:
Fields manipulation: Access the Fields Manipulation screen to customize the field definitions. Rename: Rename a table name. This option is used especially when more than one table is generated from the COBOL with the same name. Set data location: Set the physical location of the data file for the table. Set table attributes: Set table attributes. The table attributes are described in Table Attributes. XSL manipulation location: Specify an XSL transformation or JDOM document that is used to transform the table definition.
7.
Applying Filters
This section describes the steps required to apply filters on the COBOL Copybook files used to generate the Metadata. It continues the Selecting the Input Files step. To apply filters 1. Click Next, the Apply Filters step is displayed in the editor.
2.
Apply filters to the copybooks, as needed. The following COBOL filters are available:
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type. Compiler source: The compiler vendor. Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Prefix nested column: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity metadata, is replaced with an underscore. Case sensitive: Specifies whether to consider case sensitivity or not. Find: Searches for the specified value. Replace with: Replaces the value specified for in the Find field with the value specified here.
3.
Selecting Tables
This section describes the steps required to select the tables from the COBOL Copybooks. The following procedure continues the Applying Filters step.
1.
From the Select Tables screen, select the tables that you want to access. To select all tables, click Select All. To clear all the selected tables, click Unselect All. The following figure shows the Select Tables screen.
The import manager identifies the names of the records in the COBOL copybooks that will be imported as tables.
2.
Select the tables that you want to access (that require Attunity metadata) and then click Next to go to the Import Manipulation step.
Import Manipulation
This section describes the operations available for manipulating the imported records (tables). It continues the Selecting Tables procedure. The import manager identifies the names of the records in the DDM Declaration files that will be imported as tables. You can manipulate the general table data in the Import Manipulation Screen. To manipulate the table metadata 1. From the Import Manipulation screen (see Import Manipulation Screen figure), right-click the table record marked with a validation error, and select the relevant operation. See the table, Table Manipulation Options for the available operations.
2.
Repeat step 1 for all table records marked with a validation error. You resolve the issues in the Import Manipulation Screen. Once all the validation error issues have been resolved, the Import Manipulation screen is displayed with no error indicators.
3.
The upper area of the screen lists the DDM Declaration files and their validation status. The metadata source and location are also listed. The Validation tab at the lower area of the screen displays information about what needs to be resolved in order to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location). The following operations are available in the Import Manipulation screen:
Resolving table names, where tables with the same name are generated from different files during the import. Selecting the physical location for the data. Selecting table attributes. Manipulating the fields generated from the COBOL, as follows: Merging sequential fields into one (for simple fields). Resolving variants by either marking a selector field or specifying that only one case of the variant is relevant.
Adding, deleting, hiding, or renaming fields. Changing a data type. Setting the field size and scale. Changing the order of the fields. Setting a field as nullable. Selecting a counter field for array for fields with dimensions (arrays). You can select the array counter field from a list of potential fields. Setting column-wise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension. Creating arrays and setting the array dimension.
The following table lists and describes the available operations when you right-click a table entry:
Table 67 Option Fields Manipulation Table Manipulation Options Description Customizes the field definitions, using the Field Manipulation screen. You can also access this screen by double-clicking the required table record. Renames a table. This option is used especially when more than one table with the same name is generated from the COBOL. Sets the physical location of the data file for the table. Sets the table attributes. Specifies an XSL transformation or JDOM document that is used to transform the table definitions. Removes the table record.
Rename Set data location Set table attributes XSL manipulation Remove
You can manipulate the data in the table fields in the Field Manipulation Screen. Double-click a line in the Import Manipulation Screen to open the Field Manipulation Screen.
You can carry out all of the available tasks in this screen through the menu or toolbar. You can also right click anywhere in the screen and select any of the options available in the main menus from a shortcut menu. The following table describes the tasks that are done in this screen. If a toolbar button is available for a task, it is pictured in the table.
Table 68 Command General menu Undo Click to undo the last change made in the Field Manipulation screen. Field Manipulation Screen Commands Description
The offset of a field is usually calculated dynamically by the server at runtime according the offset and size of the proceeding column. Select this option to override this calculation and specify a fixed offset at design time. This can happen if there is a part of the buffer that you want to skip. When you select a fixed offset you pin the offset for that column. The indicated value is used at runtime for the column instead of a calculated value. Note that the offset of following columns that do not have a fixed offset are calculated from this fixed position.
Table 68 (Cont.) Field Manipulation Screen Commands Command Test import tables Description Select this table to create an SQL statement to test the import table. You can base the statement on the Full table or Selected columns. When you select this option, the following screen opens with an SQL statement based on the table or column entered at the bottom of the screen.
Data file name: Enter the name of the file that contains the data you want to query. Limit query results: Select this if you want to limit the results to a specified number of rows. Enter the amount of rows you want returned in the following field. 100 is the default value. Define Where Clause: Click Add to select a column to use in a Where clause. In the table below, you can add the operator, value and other information. Click on the columns to make the selections. To remove a Where Clause, select the row with the Where Clause you want t remove and then click Remove.
The resulting SQL statement with any Where Clauses that you added are displayed at the bottom of the screen. Click OK to send the query and test the table. Attribute menu Change data type Select Change data type from the Attribute menu to activate the Type column, or click on the Type column and select a new data type from the drop-down list.
Table 68 (Cont.) Field Manipulation Screen Commands Command Create array Description This command allows you to add an array dimension to the field. Select this command to open the Create Array screen.
Enter a number in the Array Dimension field and click OK to create the array for the column. Hide/Reveal field Select a row from the Field manipulation screen and select Hide field to hide the selected field from that row. If the field is hidden, you can select Reveal field. Select this to change or set a dimension for a field that has an array. Select Set dimension to open the Set Dimension screen. Edit the entry in the Array Dimension field and click OK to set the dimension for the selected array. Set field attribute Select a row to set or edit the attributes for the field in the row. Select Set field attribute to open the Field Attribute screen.
Set dimension
Click in the Value column for any of the properties listed and enter a new value or select a value from a drop-down list. Nullable/Not nullable Select Nullable to activate the Nullable column in the Field Manipulation screen. You can also click in the column. Select the check box to make the field Nullable. Clear the check box to make the field Not Nullable. Set scale Select this to activate the Scale column or click in the column and enter the number of places to display after the decimal point in a data type. Select this to activate the Size column or click in the column and enter the number of total number of characters for a data type.
Set size
Table 68 (Cont.) Field Manipulation Screen Commands Command Field menu Add Select this command or use the button to add a field to the table. If you select a row with a field (not a child of a field), you can add a child to that field. Select Add Field or Add Child to open the following screen: Description
Enter the name of the field or child, and click OK to add the field or child to the table. Delete field Select a row and then select Delete Field or click the Delete Field button to delete the field in the selected row.
Move up or down
Select a row and use the arrows to move it up or down in the list.
Select the Rename field to make the Name field active. Change the name and then click outside of the field.
Select Columnwise Normalization to create new fields instead of the array field where the number of generated fields will be determined by the array dimension.
Table 68 (Cont.) Field Manipulation Screen Commands Command Combining sequential fields Description Select Combining sequential fields to combine two or more sequential fields into one simple field. The following dialog box opens:
First field name: Select the first field in the table to include in the combined field End field name: Select the last field to be included in the combined field. Make sure that the fields are sequential. Enter field name: Enter a name for the new combined field.
Flatten group
Select Flatten Group to flatten a field that is an array. This field must be defined as Group for its data type. When you flatten an array field, the entries in the array are spread into a new table, with each entry in its own field. The following screen provides options for flattening.
Select Recursive operation to repeat the flattening process on all levels. For example, if there are multiple child fields in this group, you can place the values for each field into the new table when you select this option. Select Use parent name as prefix to use the name of the parent field as a prefix when creating the new fields. For example, if the parent field is called Car Details and you have a child in the array called Color, when a new field is created in the flattening operation it will be called Car Details_Color.
Table 68 (Cont.) Field Manipulation Screen Commands Command Mark selector Description Select Mark selector to select the selector field for a variant. This is available only for variant data types. Select the Selector field form the following screen.
Select Replace variant to replace a variants selector field. Select Counter Field opens a screen where you select a field that is the counter for an array dimension.
Default values for all tables: Select this if you want to configure the same values for all the tables in the import. Make the following selections when using this option: Generate sequential view: Select this to map non-relational files to a single table. Generate virtual views: Select this to have individual tables created for each array in the non-relational file. Include row number column: Select one of the following: true: Select true, to include a column that specifies the row number in the virtual or sequential view. This is true for this table only, even in the the data source is not configured to include the row number column. false: Select false, to not include a column that specifies the row number in the virtual or sequential view for this table even if the data source is configured to include the row number column. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties. Inherit all parent columns: Select one of the following: true: Select true, for virtual views to include all the columns in the parent record. This is true for this table only, even in the data source is not configured to include all of the parent record columns. false: Select false, so virtual views do not include the columns in the parent record for this table even if the data source is configured to include all of the parent record columns. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties.
Specific virtual array view settings per table: Select this to set different values for each table in the import. This will override the data source default for that table. Make the selections in the table under this selection. See the item above for an explanation.
Click Finish.
In the Design Perspective Configuration View, expand the Machines folder and then expand the machine where you want to add the data source. Expand the Bindings folder and then expand the binding with the adapter metadata you are working with. Expand the Adapters folder and then right-click the adapter for which you want to manage the metadata. Select Show Metadata View from the shortcut menu. You can create and edit the following adapter metadata properties:
Adapter Metadata General Properties: Enter and edit information about the adapter, such as the adapter name and the way in which you connect to the adapter. You make these changes in the Design perspective, Metadata view. Adapter Metadata Schema Records: The input and output record structure for a record in the adapter definition.
Adapter Metadata Interactions: Enter details of an interaction. The interaction Advanced tab is displayed for some adapters only, such as the Database adapter and includes more details about the interaction.
Right-click the interaction that you want to edit, and select Open. The Interaction General Properties editor is displayed.
Description
Table 69 (Cont.) Adapter Metadata General Tab Field Version Header Authentication mechanism Description The schema version. A C header file with the data structures for the adapter. This header file is used with the C API for applications. The authentication method. Select from:
Max Request Size Max Active connections Max Idle timeout Adapter Specifications
The maximum size, in bytes, for an XML ACX request or response. Larger messages are rejected with an error. The maximum number of machines that can connect to the adapter at a time. By default, this number is unlimited. The maximum amount of time without activity before the connection is timed out. By default, this is 600 seconds. The maximum number of simultaneous connections for an adapter (per process).
In the Design Perspective Metadata View, expand the Adapters folder. Right-click Schema and select New record. Enter a name for the new record definition. Click OK. The Schema Record editor is displayed. You define field grouping in the Schema Record editor.
6. 7.
Click New Field to add new fields for the record, describing the data structure for the adapter. Continue adding fields until the record structure is complete.
Name: The name of the field Type: The data type of the field. See the Valid Data Types table for a list of the valid data types. Length: The size of the field including a null terminator, when the data type supports null termination (such as the string data type).
Specifications
Defines specific field properties. To display the properties, select the specific field in the Fields list.
The following table describes the valid data types that can be used when defining these specifications in the Schema Record editor.
Table 611 Binary Date Float Numeric[(p[,s])] Time Valid Data Types Boolean Double Int Short Timestamp Byte Enum Long String
In the Design Perspective Metadata View, expand the Adapters folder. Expand the Schema. Right-click the record you want to edit and select Open. The Schema Record editor for that record is displayed. You can add fields and make any necessary changes. For information on how to work in this editor, see Adapter Metadata Schema Records.
In the Design Perspective Metadata View, expand the Adapters folder. Right-click the Interactions folder and select New. Enter a name for the new Interaction. Click OK. The Interaction editor is displayed. You define interaction properties and its input and output properties in the Schema Record editor.
6.
Make any changes in the editor that you need. The table below describes the Interactions editor.
sync-send-receive: The interaction sends a request and expects to receive a response. sync-receive: The interaction sends a request and does not expect to receive a response. async-send: The interaction sends a request that is divorced from the current interaction. This mode is used with events, to identify an event request.
Identifies the input and output records. Specific properties for the interaction. When an Interaction Advanced tab is used, this section is not displayed. The parameters shown are for a Legacy Plug Adapter.
In the Design Perspective Metadata View, expand the Adapters folder. Expand the Interactions folder. Right-click the interaction you want to edit and select Open.
The Interaction editor for that record is displayed. You can add fields and make any necessary changes. For information on how to work in this editor, see Adapter Metadata Interactions.
The fields in this tab are dependent on the specific adapter. In the above screen the tab is displayed for the Database adapter and enables building or modifying an SQL statement. For information on how this tab relates to the Database adapter. See Adapter Metadata Schema Records.
Right-click Procedures, and select New Procedure. Enter a name for the new procedure definition, and click OK. The editor opens with the General properties tabs displayed.
4.
Click Procedures to view the defined procedures. Right-click the required procedure (or double-click it) to view or edit its properties. The editor opens and is different depending on which procedure driver you are working with. See the section that describes the driver you are working with for more information:
CICS Procedure Data Source Procedure Data Source (Application Connector) Natural/CICS Procedure Data Source (z/OS)
For other procedures, the metadata is created manually, as described in Adapter Metadata Schema Records. You start importing procedure metadata in the same way as Importing Data Source Metadata with the Attunity Import Wizard.
7
Handling Arrays
This section describes the support methods that Attunity Connect applies to deal with arrays. It includes the following topics:
Representing Metadata
Before looking at the different methods of handling arrays, you should understand how metadata is represented in Attunity Studio. The following figure shows an example in COBOL that illustrates arrays and nested arrays. When you import this metadata into Attunity Studio, the import process creates an ADD definition that is equivalent to the original structure, usually mapping the fields one-to-one.
The following figure shows how Attunity Studio represents the same data in XML.
On the Columns tab, Attunity Studio represents the same metadata as shown in the following figure.
Finally, if you run the NavSQL > native STUDENT command from the NavSQL utility, the same metadata is represented as shown in the following figure.
Columnwise Normalization Virtual Tables Virtual Views Sequential Flattening (Bulk Load of Array Data) ADO/OLE DB Chapters XML
Columnwise Normalization
Some small arrays are merely a short hand notation of a sequence of simple columns. For example, an address field with three lines on the screen may have been represented in a COBOL copybook by an OCCURS clause that is used three times, as a
Handling Arrays 7-5
short hand notation of writing three columns, Address_1, Address_2, and Address_3.
Figure 75 Simple Array in COBOL
This is not a real case of hierarchical dependency of data that needs to be modeled in the relational world. The simplest approach for dealing with this simple class of arrays is to replace them with simple columns during the import process. This process of replacing a small array by a sequence of columns is referred to as columnwise normalization. Columnwise normalization is useful for simple arrays that share any of the following characteristics:
They show a small number of occurrences. They do not possess a counter. They contain only one field.
You can choose to normalize an array columnwise in the Import Manipulation panel in Attunity Studio. The following figures show an example.
Figure 76 Selecting Columnwise Normalization in the Import Manipulation Panel
Virtual Tables
Exposing arrays as virtual tables is a commonly used technique to handle arrays. It generates a virtual table for every array in the parent record, with specially generated virtual fields that connect the parent and the virtual table. For example, an array called course in a table called student is represented by the virtual table STUDENT_ COURSE. Attunity Studio generates, updates, and removes virtual tables automatically, according to the status of their parent table, and names them by appending the array name to the parent name. When an array includes another array, the name of the resulting virtual table consists of the parent name, the array name, and the name of the nested array, as follows:
parentName_arrayName_nestedArrayName
The number of nested-array levels is not limited. Virtual tables includes the following columns:
The array member fields from the original structure. A column called _PARENT, which identifies the parent record. This column is a string representation of the parent records bookmark. A column called _ROWNUM, which is the ordinal that identifies the array record within the parent table.
The _PARENT and _ROWNUM columns are generated automatically and cannot be updated. Together, they uniquely identify each row in the virtual table. To identify the array field in the parent record when joining parent and child tables, you can use the _ PARENT field of the virtual table. You cannot edit the definition of virtual tables; you can only manipulate the parent table. Attunity Studio indicates virtual tables by using a differently colored icon in the Metadata view, as shown in the following figure.
Right-clicking a table in the Metadata view and selecting SQL View opens the SQL view. The following figure shows a sample table that includes the _PARENT and _ ROWNUM fields and replaces the entire array ASSIGNMENTS by a varchar(64) field that includes a string representation of the bookmark.
Figure 79 SQL View of the Virtual Table STUDENT_COURSE
When you look at an actual record, the same fields_PARENT, _ROWNUM, and NUMOF_ ASSIGNMENTSare displayed, as shown in the following figure. You can use the ASSIGNMENTS field to join with the STUDENT_COURSE_ASSIGNMENTS virtual table.
The metadata that the ADD stores for the virtual table is only a pointer to the parent table, as indicated by the attribute name, basedOn. It is filled in from the parent table upon first access. You can join the parent and the child by using the courses and _PARENT fields as the join criteria, as shown in the following figure.
Figure 711 Joining Parent and Child
Equally, you can join parent, child, and grandchild, as shown in the following figure.
Figure 712 Joining Parent, Child, and Grandchild
When joining a table and an array table, AIS reads every physical record only once, thus maximizing the joins efficiency in terms of I/O. The virtual table method supports all DML operations, with the following limitations:
Arrays without counters (DEPENDING ON clauses) only support UPDATE commands. INSERT commands ignore the _ROWNUM column and add data at the end. DELETE commands that remove data from the middle of an array move the following elements up and update the counter automatically. Therefore, if you want to delete all the elements from an array, you cannot perform the following loop: for (i=1; i<=counter; i++) delete from array where _PARENT=x and _ROWNUM=i This loop does the following:
1. 2. 3.
It deletes the first member of the array. It moves up the second member of the array so that it becomes the first member. It deletes the second member of the array, which was originally the third member. It does not delete the original second member because that is now the first member of the array.
Alternatively, you can use the following loops: while (counter>0) delete from array where _PARENT=x and _ROWNUM=1 This loop keeps deleting the first member of the array until no member is left to move up. The counter is updated by AIS. while (i=counter; i>0; i--) delete from array where _PARENT=x and _ROWNUM=i This loop deletes the members of the array from last to first. It is slightly more efficient because it avoids the moving of members.
Note:
Every write operation causes physical I/O on the parent record. If you need to use a lot of DML operations on arrays, consider using the XML approach instead.
Virtual Views
Virtual views are a more recent method of handling arrays in AIS. They eliminate the need for a _PARENT field, replacing it by primary key fields from the parent. This makes the processing of array records easier for most applications. Per binding, you can handle arrays either as virtual tables or as virtual views; you cannot mix the two models in the same binding. However, when you switch between virtual tables and virtual views, you do not need to make any changes to the metadata because they both use the same table definitions in the ADD. During the import procedure, Attunity Studio generates virtual views and names them by appending the array name to the parent name. When an array includes
another array, the name of the resulting virtual table consists of the parent name, the array name, and the name of the nested array, as follows:
parentName_arrayName_nestedArrayName
The number of nested-array levels is not limited. Virtual views includes the following:
The array member columns from the original structure. The fields from the parents first unique key or all parent fields, depending on the selection during the import process. If all parent fields are included in the virtual view, the parents indexes are available in the view definition and can be used for efficient optimization strategies.
Note:
If the view does not include all parent fields, the primary key fields (if the primary key is not the parents first unique key). A column called <array>_ROWNUM, which is the ordinal that identifies the array record within the parent table.
The unique key and <array>_ROWNUM columns are generated automatically. Together, they uniquely identify each row in the virtual view and form a unique key. When working with virtual views, consider the following limitations:
Virtual views are read-only. Virtual views currently do not support arrays within variants that have a selector field.
Including all parent fields in the virtual view greatly reduces the need for performing join operations because this in itself is an implicit join. However, if you do perform a join, it is not as efficient as a join of virtual tables because AIS reads each record twice, not once. This means that you are better advised to use Virtual Tables if you need to perform complex, explicit joins. In general, though, the query processor can devise efficient access strategies because AIS copies all relevant indexes from the parent to the virtual view. Attunity Studio indicates virtual views by using a differently colored icon in the Metadata view, as shown in Display of Virtual Tables in Attunity Studio.
The sequentially flattened view of a complex table is referred to as single table. You can choose to create a single table in Attunity Studio, by selecting Sequential View during the Metadata Model Selection step.
Figure 713 Selecting a Single Table View
The flattened table is called <table>_ST, where <table> is the name of the parent table and ST indicates a single table. For example, if a parent table is called STUDENT, the single table is called STUDENT_ST. The structure of the single table is identical to the original tables structure, except that AIS removes all array dimensions and adds some control fields. When reading a record, AIS performs a tree traversal of the parent and its array hierarchy. Each record in the resulting recordset deals with a specific array member; other arrays are nulled out, and the _LEVEL control field indicates the current array in the tree traversals hierarchy. The sequentially flattened single table includes the following columns:
The parent fields, that is the non-repeating fields. The array fields for all arrays within the parent. A column called __LEVEL, which indicates the current child level. The value comprises a concatenation of parent and child names. A column called __SEQUENCE, which indicates the sequence of the single table row in the physical, non-relational table. A value of 1 indicates a parent record. For each array, an optional column called <array>_ROWNUM, which identifies the row in the array. This column is generated automatically for the array.
A row for each parent record only, without reference to the arrays. All rows with an empty __LEVEL column and a value of 1 in the __SEQUENCE column indicate a parent record only. A record for each array record.
The following figure shows the metadata that sequential flattening produces for this data source.
Figure 715 SQL View of the Single Tables Metadata
The next figure shows the actual single table. It contains a column for each row in the SQL view above.
Figure 716 STUDENT_ST with All Parent and Child Records
Details of the first course. The first row shows the course itself, and the next three rows show the course assignments. Once the first course has been retrieved, the next course is retrieved with its assignments. Following all the courses, the next array (BOOK) is retrieved.
During a bulk load, the rows are read one by one and written to the appropriate target file for each row, based on the __LEVEL field.
ADO/OLE DB Chapters
ADO and OLEDB introduced the concept of an embedded rowset, called a chapter, as part of the API. A chapter is a result set embedded in a single column within the primary resultset that you can drill down to. This model works well with complex legacy data that includes arrays. AIS supports chapters and lets you update them. From a metadata perspective, the array is represented by a chapter column and contains a chapter identifier. As such, the chapter functions as a handle to the data that it links to. Any ADO-based programs, particularly Visual Basic programs, can use chapters to handle arrays, such as the Attunity-provided SQL sample utility, ChapView. The following figure illustrates how ChapView handles chapters.
A look at a Microsoft Visual Basic code snippet using ADO helps understand how chapters are embedded.
Figure 718 Visual Basic Code Snippet Using ADO
oRST is the main recordset. For the embedded recordset, oRSTChapter is used. However, both are simple recordset objects.
. . .
The embedded recordset is the value of the COURSE column in the main recordset. From here on, everything is simple Visual Basic recordset syntax.
Note:
Chapters are not supported with virtual views and sequential flattening. However, you can use chapters and virtual views in the same Visual Basic program, as needed.
For more information on chapters, see the OLE DB and ADO documentation.
XML
Forcing non-relational structures that include arrays to fit the relational mould is an endless source of complexity, with many potential efficiency issues. The method of using XML to handle arrays is a way to get around the restrictions of the relational model while maintaining the use of SQL. It makes conventional use of SQL, but instead of specifying a list of columns in the select clause, it transfers the records data to the client application as a BLOB column that contains the XML representation of the data. This method works for both read and write operations. By using XML, you can have a client application write an entire complex structure in a single I/O operation. Approaching the same task with virtual tables would result in multiple I/O operations (typically one I/O operation per array member). To be able to use XML, you need to make sure that the environment property exposeXmlField in the misc section of the binding definition is set to true. By default, this property is set to false. You can use the XML method from any supported client interface, including JDBC, ODBC, and ADO. It is also commonly used in the context of the query or database adapter. If you use a query adapter, the XML documents that result from a select * clause and a select XML clause are almost identical. However, the select XML clause produces a natural XML representation while the select * clause produces a hierarchical rowset representation of the record, as shown in the following figures.
Similarly, you can combine DML with XML to insert a complex record with arrays during a single I/O operation. For example, you could run the following query to add another record to the STUDENT table:
<update sql="insert into navdemo:student(xml) values(?)" executionMode="insertUpdateXml"> <inputParameter type="xml"> <STUDENT ID="1" FIRST_NAME="JOHN" LAST_NAME="SMITH" DATE_OF_ BIRTH="1984-12-01"> <COURSES COURSE_ID="1" COURSE_TITLE="MATH 1" INSTRUCTOR_ID="1"> <ASSIGNMENTS ASSIGNMENT_TYPE="QUIZ" ASSIGNMENT_TITLE="DERIVATIVES-1" DUE DATE="2004-03-14" GRADE="4.0"/> <ASSIGNMENTS ASSIGNMENT_TYPE="QUIZ" ASSIGNMENT_TITLE="DERIVATIVES" DUE_ DATE="2004-03-14" GRADE="4.5"/> </COURSES> <BOOKS ISBN="1234" RETURN_DATE="2004-05-02"/> </STUDENT> </inputParameter> </update>
Making use of XML is recommended when your application environment is Web-based. This method has the lowest overhead and performs better than chapters in Web environments.
8
Using SQL
This section contains the following topics:
Overview of Using SQL Batching SQL Statements Hierarchical Queries Copying Data From One Table to Another Passthru SQL Writing Queries Using SQL Locking Considerations Managing the Execution of Queries over Large Tables
SQL specific to the data source you want to access. Attunity SQL, which is based on standard ANSI 92 SQL. The full syntax for Attunity SQL is described in Attunity SQL Syntax. The Attunity SQL incorporates enhancements, including SQL access to a data source that does not natively support SQL.
Whatever version of SQL you use, you can always use the Attunity SQL extensions to incorporate additional features. For information about customizing the way the SQL is processed, based on the data source being accessed, see Using the Attunity Connect Syntax File (NAV.SYN). You can test SQL interactively to ensure the correct results, using NAV_UTIL EXECUTE.
Parameters are passed as a group for all the queries in the same order as they appear in the individual queries.
You cannot use this syntax to batch SQL statements from a Java application or via the NAV_UTIL EXECUTE utility or ADO Demo application supplied with Attunity Connect.
ADO Notes
Set the Multiple Results connection property to enable multiple results (before executing the compound query):
oConn.Properties("Multiple Results") = 1
The results of the first query are displayed. To see the results of the next query, request NextRecordSet.
Hierarchical Queries
This section contains the following topics:
Generating Hierarchical Results Using SQL Accessing Hierarchical Data Using SQL Flattening Hierarchical Data Using SQL Using Virtual Tables to Represent Hierarchical Data Hierarchical Queries From an Application
A hierarchical query is a query whose result is a hierarchy of rowsets linked by chapters (see Chapter), reflecting parent-child relationships. For example, Customers and Orders may constitute a hierarchical rowset, with each chapter of the child Orders rowset corresponding to all of the orders of one customer in the parent Customers rowset. Rowsets with arrays of structures as columns (which are supported by certain providers) are modeled such that the rows of an array constitute the children of a column in the containing parent row. Hierarchical queries enable you to do the following:
Arrange rowsets resulting from a query in a hierarchy, reflecting a parent-child relationship. Use nested SELECT statements to do this. Manipulate data that is stored hierarchically in a data source (such as information stored in arrays in RMS). Currently arrays are supported in the Adabas, CISAM, DISAM, DBMS, Enscribe, RMS, and VSAM drivers. You can handle this type of data in the following ways:
By including the hierarchical data as chapters, reflecting a parent-child relationship. By flattening the hierarchical data (see Flattening Hierarchical Data Using SQL). By using virtual tables to represent the data (see Using Virtual Tables to Represent Hierarchical Data). You can use virtual driver columns in a DBMS database to produce a chaptered result.
See Hierarchical Queries From an Application to see how the SQL is incorporated in an application.
8-2 AIS User Guide and Reference
Chapter
A chapter is a group of rows within a hierarchy the chapter constitutes a collection of children of some row and column in a parent rowset. The column in the parent rowset is called a chapter column and contains a chapter identifier. The name of the column is also the name identifying the child rowset (which is meaningful only in the context of the parent rowset).
Example
The following hierarchical query produces a child rowset:
SELECT C_name, {SELECT O_orderkey, {SELECT L_partkey, L_linenumber FROM lineitem WHERE L_orderkey = O_orderkey} AS items FROM torder WHERE O_custkey=C_custkey} AS orders FROM customer
The main (root) rowset has two columns. The second column (orders) is a chapter. The result has a three-tier hierarchical structure as displayed in this figure.
Figure 81 Hierarchical SQL Query Producing Child Rowset
In the SQL Utility, click a field in the second column ([CHAPTER]) to display the contents of the chapter. The second column can be opened to display another (child) rowset. This child rowset includes items, a chaptered column that can be opened to display another child rowset (showing the L_partkey and L_linenumber columns for the opened chapter) as displayed in this figure:
Figure 82 Hierarchical SQL Query Producing Multiple Child Rowsets
You can display chapters for only one parent row at a time. For example, you can display the set of orders for only one customer at a time. You can perform drill-down operations from an ADO, ODBC and JDBC-based application. For details, see Hierarchical Queries From an Application.
For example, the following hierarchical query uses an alias and produces a list containing the children stored in an array called hchild belonging to each employee:
SELECT emp_id,(SELECT name,age FROM e->hchild) FROM disam:emp_struct e
For more details about nesting a SELECT statement in the FROM clause of another SELECT statement, refer to Flattening Hierarchical Data Using SQL. Without an alias the query lists for each employee all of the children of all of the employees:
SELECT emp_id,(SELECT name,age FROM disam:emp_struct->hchild FROM disam:emp_struct
The chaptered data is specified as part of the source syntax of the FROM clause. You can use chaptered data:
In an outer SELECT statement to flatten the chaptered data. Anywhere a FROM clause is used.
Examples
The following examples assume hierarchical data with a parent employees rowset called emp_struct. This rowset has ordinary columns plus a chapter column called hchild (one row for each of the children of this employee). The child rowset hchild itself has (in addition to ordinary columns) a chapter column called hschool (one row for each school attended by this child).
Example 81 All Employees Children
Access to the hchild rowsets is via the parent rowset emp_struct. Apart from this access, the employee data is not required by the query.
When child rowsets can be accessed as normal tables, it is generally more efficient to access them directly. The presumption in the previous example is that the child information is accessible only through a parent rowset (such as emp_struct). If both the father and the mother of a particular child are employees, this child will appear in two different chapters (once through the father rowset and again
through the mother rowset). This query may therefore return the information for this child twice. If this behavior is undesirable, use the SELECT DISTINCT* syntax.
Example 82 Childrens Schools
The following query counts the number of distinct schools where the children of all employees studied:
SELECT COUNT(DISTINCT school_name) FROM emp_struct->hchild->hschool
This example illustrates a two-level hierarchy, with the child rowset hchild itself serving as a parent of the child rowset hschool.
Example 83 Employees with Children
The following query retrieves information about employees who have at least one child:
SELECT * FROM emp_struct E WHERE EXISTS (SELECT * FROM E->hchild)
Note that E->hchild refers to the children of the given employee, not of all employees, because the nested SELECT clause refers to the same rowset as the outer SELECT clause. The emp_struct rowset appears in the same role in both the outer and the inner query, with the name E (whose use is mandatory).
Example 84 School Age Children
The following query retrieves information about all children who have attended at least one school:
SELECT * FROM emp_struct->hchild C WHERE EXISTS (SELECT * FROM C->hschool)
The same scope rules as those of example 3 apply: the nested subquery SELECT * FROM C->hschool is executed for the given row of hchild and serves to filter out the children who have not attended any school.
Example 85 Multiple Hierarchies
To better understand the scope issues when multiple hierarchies are involved, consider the following queries:
SELECT * FROM emp_struct E WHERE EXISTS (SELECT * FROM E->hchild->hschool)
and:
SELECT * FROM emp_struct->hchild C WHERE EXISTS (SELECT * FROM C->hschool)
The nested subquery looks similar in both of these queries, but in the first query the outer rowset that defines the context is the emp_struct row, while in the second query it is the row of the child of an employee. Thus, the first query specifies employees such that at least one of the employees children went to at least one school, and the scope of the subquery is all schools of all children of this employee. The second query specifies all children that went to school, and the scope of the subquery is all of the schools of this child.
use parentheses to delimit the nesting. This is equivalent to specifying a left outer join (LOJ) between the parent rowset and a child rowset, and the resulting rowset reproduces each row of the parent, combining it with one row for each of its children. The nested SELECT statement can reference a child rowset (using the parent->child syntax) only in its FROM clause.
Using an Alias
In order to list the hierarchical data with the parent data only, you must use an alias for the child data. Without an alias the query lists for each parent row all of the children of all of the parent rows. Compare the following queries:
SELECT emp_id,(select name from employee->hchild)from employee
and
SELECT emp_id,(select name from e->hchild)from employees e
The first query, without an alias, lists for each employee all of the children of all of the employees. The second query uses an alias and produces a list containing the children stored in an array called hchild belonging to each employee.
Examples
The following examples assume hierarchical data with a parent employees rowset called emp_struct. This rowset has ordinary columns plus a chapter column called hchild (one row for each of the children of this employee). The child rowset hchild itself has (in addition to ordinary columns) a chapter column called hschool (one row for each school attended by this child).
Example 86 Number of Children in School Per City
The following query retrieves the number of children that study in each city for every city where the company has employees.
SELECT city, (SELECT COUNT(*) FROM emp_struct->hchild->hschool A WHERE A.city = B.city) FROM cities B
This query demonstrates the use of a nested query within a SELECT statement, using tables and not aliases.
Example 87 Employee and Child Information
The following query retrieves the employee ID, address, the number and names of children of each employee:
SELECT emp_id, child_counter, (SELECT name FROM E->hchild), Address FROM emp_struct E
Employees who have no children (such as employee 1122 in the example) appear and the corresponding child row is Null (and the output is like that of a left outer join). When more than one child rowset is specified in the query (by including more than one nested SELECT statement), the parent row is reproduced a sufficient number of times to accommodate the largest number of the parents' children, and the data from all children appears in parallel. Thus, child rows are paired randomly, resulting in side-by-side columns for the child rowsets. When one of the child rowsets is out of rows, its columns are padded with NULLs. See example 3, below.
Example 88 Employees Salary and Child Information
For each employee, the following query retrieves the employee ID, the number of the employees children, the first two salaries of the year and the names of the children:
SELECT emp_id, child_counter, (SELECT sal FROM E->Sal WHERE month IN ('JAN', 'FEB')), (SELECT name FROM E->hchild) FROM emp_struct E
Note:
When multiple levels of hierarchies are involved, the flattening operation is repeated by nesting a SELECT statement inside another nested SELECT statement. Conceptually a left outer join is performed between the parent and child rowsets as above, and then another left outer join is applied to the result and to the grandchild rowset. See Example 4, below.
The following query retrieves the employee ID, address, the number and names of the children of each employee and the number of different schools at which each child studied:
SELECT emp_id, child_counter, (SELECT name, (SELECT COUNT(DISTINCT school_name) AS dist_schools FROM C->hschool) FROM E->hchild C) FROM emp_struct E
In this example the query at the deepest level of nesting is an aggregate (COUNT DISTINCT), which returns a single value. A request for the names and addresses of the schools would result in the child information being repeated for each school where the child studied.
Example 810 Multiple Hierarchical SQL Query
To order the retrieved information according to the employee ID and the child name, use a query like the following:
SELECT emp_id, child_counter, (SELECT name, (SELECT COUNT(DISTINCT school_name) AS dist_schools FROM C->hschool) FROM E->hchild C) FROM emp_struct E ORDER BY emp_id, name
Example 811
To order the rowset according to the child name and the number of distinct schools where the child studied, use a query like the following:
SELECT emp_id, child_counter, (SELECT name, (SELECT COUNT(DISTINCT school_name) AS dist_schools FROM C->hschool) FROM E->hchild C) FROM emp_struct E ORDER BY 3, 4
You cannot specify ORDER BY inside a nested query. Ordering of the result rowset is done in the main query only. Columns can be referenced by name or by ordinal number. Ordinal numbers are determined by the order the columns appear in the result set.
Example 812 Multiple Hierarchical SQL Query
The following query retrieves the number of children that study in each city for every city where the company has employees.
SELECT city, (SELECT COUNT(*) FROM employees->hchild->hschool A WHERE A.city = B.city) FROM cities B
The array fields. A column called _parent, which contains the bookmark of the parent field. This column is generated automatically for the array and is read-only. A column called _rownum, which identifies the row in the virtual table. This column is generated automatically for the array and is read-only.
The fields _parent and _rownum together uniquely identify each row in the virtual table. Use the _parent field of the virtual table to identify the array field in the parent record when joining parent and child tables. Example A record NATION stores data about countries for a mail order application and includes an array structure REGIONS. The array structure is converted into a virtual table NATIONS_REGIONS. The following SQL accesses data from the virtual table NATIONS_REGIONS:
SELECT * FROM NATION N, NATION_REGIONS R WHERE R._PARENT = N.REGIONS
Once a virtual table has been created, it can be used in applications in the same way as any other table. Note that this SQL statement accessing a virtual table is equivalent to the SQL statement using the -> syntax to access the array data in the table:
SELECT * FROM NATION->REGIONS
Right-click the data source in Attunity Studio and select Edit Data Source. In the advanced tab set the Use runtime columnwise flattening property. This property flattens the array within the table by expanding the array into separate fields with each row in the array displayed with the row number appended to the field name.
An array with the Use runtime columnwise flattening property set is read-only.
Drill-down Operations in an ADO Application Drill-down Operations in an ODBC Application ODBC Drill-down Operations Using RDO ODBC Drill-down Operations Using C Drill-down Operations in a Java Application
You can use hierarchical queries specified with Attunity SQL to execute drill-down operations on data within the application. How the hierarchical query for drill-down operations is implemented varies according to the applications API:
8-10 AIS User Guide and Reference
For ADO applications: Use the standard ADO methods and properties (see Drill-down Operations in an ADO Application below. For ODBC applications: Use functionality provided with Attunity Connect (see Drill-down Operations in an ODBC Application). For Java: Use standard Java (see Drill-down Operations in a Java Application).
' Set active connect oConn.ConnectionString = "Provider=AttunityConnect;" oConn.Open sSQL = "select n_name, {select c_name from customer where n_nationkey = c_ nationkey} as Customers from nation" ' Execute SQL with forward only cursor and read only oRST.Open sSQL, oConn, adOpenForwardOnly, adLockReadOnly While Not oRST.EOF ' Get the Customers chapter Set oChild = oRST("Customers").Value While Not oChild.EOF ' Code that manipulates the chapter resultset oChild.MoveNext Wend ' Release chapter Set oChild = Nothing oRST.MoveNext Wend Set oRST = Nothing Set oConn = Nothing
ODBC Drill-down Operations Using RDO: In RDO you use standard methods and properties for rdoConnection, rdoQuery, rdoResultset and rdoColumn objects and their collections. ODBC Drill-down Operations Using C: In C you use standard ODBC APIs with standard arguments.
Additionally, a number of functions are provided that you can incorporate in an application in order to utilize hierarchical queries. These functions use new descriptor types that have been added to the ODBC API SQLColAttributes: SQL_COLUMN_IS_ CHAPTER_ and SQL_COLUMN_ORDINAL_.
To determine which column is a chapter, use the descriptor type SQL_COLUMN_ IS_CHAPTER_. To determine the ordinal position for any column, use the descriptor type SQL_ COLUMN_ORDINAL_.
GetChapterInfo: Returns chapter information. For details, see GetChapter(RDO). OpenEmbeddedRowset Opens an embedded rowset for a parent chapter column. For details, see OpenEmbedded Rowset (RDO).
' Resultset for chapter ' Query for chapter (required by OpenEmbeddedRowset)
' An array which indicates that a specific column is a chapter ' Number of chapter columns ' Cursor Name
' Set active connect, Attunity-Demo is the DSN Set oConn = rdoEnvironments(0).OpenConnection("Attunity-Demo", RDO.rdDriverNoPrompt, False, "UID=;PWD=;") ' SQL statement sSQL = "select n_name, {select c_name from customer where n_nationkey = c_ nationkey} as Customers from nation" ' Execute SQL with forward only cursor and read only Set oRST = oConn.OpenResultset(sSQL) ' Redims according to the number of columns ReDim IsChapterCol(oRST.rdoColumns.Count - 1) 'Calling Attunity Connect help routine to set the necessary info GetChapterInfo oRST, sCursorName, IsChapterCol(), cChaptCols While Not oRST.EOF ' Open Customers chapter - lock type of child is derived from parent OpenEmbeddedRowset sCursorName, oRST("Customers"), oConn, quChild, rsChild, oRST.LockType If rsChild Is Nothing Then ' Failed to open chapter MsgBox "Failed to open the chapter!" Exit Sub End If 8-12 AIS User Guide and Reference
While Not rsChild.EOF ' Code that manipulates the chapter resultset rsChild.MoveNext Wend ' Release chapter Set oChild = Nothing oRST.MoveNext Wend Set oRST = Nothing Set oConn = Nothing
Notes:
Before you can open any chapter in a parent resultset, you need to know which columns in the resultset are chapters. You save the ordinal positions of these columns and the cursor name of the parent statement in order to bind the parent column to child rowsets. To identify a chapter column, use the Attunity Connect RDO function GetChapterInfo. If cChaptCols > 0 is returned by GetChapterInfo, the parent resultset includes chapter columns. The information about child rdoResultset objects and parent chapter columns is set in a special array. Go to the needed row in the parent rdoResultset by using the oRST.MoveFirst, oRST.MoveNext or oRST.Move methods. Call the parent chapter column using the OpenEmbeddedRowset function.
If you want to use the Requery method on the child rdoResultset objects, save information about the embedded rowsets in an array. Use a user structure similar to the following: Type TypeChildResultset clParentOrdinal As Integer ' Ordinal position of ' parent chapter column rsChild As rdoResultset quChild As New rdoQuery End Type You need to save only the ordinal position of a parent chapter column. You can refer to any rdoColumn object using the following syntax: rsParent.rdoColumns(clParentOrdinal 1). Close all child rdoResultset objects before closing the parent rdoResultset object.
The number of chapter columns in a parent resultset. The ordinal positions of these columns. The cursor name of the parent statement (in order to bind the parent column with child rowsets).
Syntax
GetChapterInfo rsParent, sCursorName, isChapter(), cChaptCols
where
rsParent (input): A parent rdoResultset object. sCursorName (output): A string containing the parent cursor name. isChapter() (output): An array of long isChapter flags for each column of the parent resultset. The flag is set to 1 for a chapter column and unset for any other column. You can use the isChapter array with each column of the parent rdoResultset to determine whether the current column is a chapter. The isChapter flag is set by calling for each column of parent rdoResultset the ODBC API SQLColAttributes with the additional descriptor type SQL_COLUMN_IS_ CHAPTER_. If a chapter column exists, the cursor name is retrieved by calling the ODBC API SQLGetCursorName.
cChaptCols (output): A long value returns the number of chapter columns in the parent resultset.
In its pfDesc argument, SQLColAttributes returns 1 for chapter columns and 0 for non-chapter columns.
OpenEmbedded Rowset (RDO) OpenEmbedded Rowset opens an embedded rowset for a parent chapter column. This method does not return data from the embedded rowset. Syntax: OpenEmbeddedRowset sCursorName, clParent, cn, quChild, rsChild where
sCursorName (output): A string with the parent cursor name. clParent (input): An rdoColumn object representing the parent chapter column. Cn (input): An rdoConnection object. quChild (input/output): A child rdoQuery object. The first time the chapter is opened for this parent column, quChild is NULL. rsChild (input/output): A child rdoResultset object. The first time the chapter is opened for this parent column, rsChild is NULL.
For z/OS Platforms: The sample program is in NAVROOT.SAMPLES.ODBCDEMO, where NAVROOT is the high-level qualifier of the Attunity Server installation When handling chapter data, note the following:
Before you can open any chapter in a parent resultset, you need to know which columns in the resultset are chapters. You save the ordinal positions of these columns and the cursor name of the parent statement in order to bind the parent column to child rowsets, using the Attunity-provided function GetChapterInfo. GetChapterInfo returns 1 when the parent resultset includes chapter columns. Open each chapter using the Attunity OpenEmbeddedRowset function. When you call this function with the prepared child statement, the function changes only the active chapter bookmark and calls SQLExecute.
Note:
GetChapterInfo (C)
GetChapterInfo returns the following chapter information:
The number of columns in a parent resultset. The ordinal positions of these columns. The cursor name of the parent statement (in order to bind it with child rowsets).
Syntax
int GetChapterInfo(SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt, UCHAR* szCursorName, COLDESC *pColDesc, SWORD cCols, long *cChapters)
where:
henv (input): The ODBC Environment handle. hdbc (input): The ODBC Connection handle. hstmt (input): The ODBC SQL handle. szCursorName (input/output): The parent cursor name. Allocate szCursorName before calling GetChapterInfo. pColDesc (input/output): An array of descriptor information for all columns. cCols (input): The number of columns in the resultset. cChapters (output): The number of chapter columns in the parent resultset.
To save standard and additional descriptor information for each column, use the Attunity user structure stColumnDescriptor (see stColumnDescriptor User Structure (C)).
OpenEmbedded Rowset OpenEmbeddedRowset opens a chapter (embedded rowset). This function does not return data from the embedded rowset. Syntax: int OpenEmbeddedRowset(SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmtParent, UCHAR* szParentCursorName, COLDESC *pOneColDesc) where:
henv (input): The ODBC Environment handle. hdbc (input): The ODBC Connection handle. hstmt (input): The ODBC SQL handle. SzParentCursorName (input): The parent cursor name. POneColDesc (input/output): The pointer to the descriptor information of the parent chapter column.
This code checks both the column type and the column type name. In the code you need to check only one of them. To retrieve a chapter column, call getObject and cast it to a ResultSet as follows:
ResultSet rsChild = (ResultSet)parentRs.getObject(column);
Because of the need to cast the returned object, first make sure that the column is a chapter column.
Passthru SQL
SQL UPDATE, INSERT, DELETE, DDL statements anFor all SQL During a SessionFor all SQL During a Sessiond SELECT statements can be passed directly to a relational data source, instead of being processed by the Query Processor. A data retrieval query can include joins where the data from one or more of the data sources is processed directly by the data source instead of the Query Processor. This is particularly useful when dealing with a data source whose commands are not in standard SQL and whose data you want to join with data from other data sources HP NonStop Platforms: When specifying a passthru query to a HP NonStop SQL/MP database, if the query is not within a transaction, you must append the words BROWSE ACCESS at the end of the query. For statements that do not return rowsets, you can pass SQL directly to the data source in one of the following ways:
For a Specific SQL Statement: For a specific SQL statement from within the application. For all SQL During a Session: For all SQL during a session from within the application.
All SQL statements (both statements that do not return rowsets and statements that do return rowsets) can be passed as part of the SQL itself. This is particularly useful when dealing with a non-SQL data source, whose data you want to join with other SQL data. Passthru queries are not supported for complex objects, such as BLOBs.
Via ADO
To enable passthru SQL for a specific statement, use the Command object and pass it the Operating_Mode parameter. All SQL during this connection will bypass the Query Processor. To reset the connection to channel the SQL through the Query Processor, reset the Operating_Mode parameter to NULL. Example The following example code shows an ADO connection to an Oracle database. Using the Command object, individual lines of SQL can be passed directly to the database. You specify the connection with the Operating_Mode parameter set to Passthru. All SQL, until the Operating_Mode parameter is reset to NULL, subsequently bypasses the Query Processor.
Public Public Public Public cmd As Object cmd1 As Object conn As Object conn1 As Object
Private Sub Bypass_Qpex2() Dim Dim Dim Dim Dim rs As New ADODB.Recordset conn As New ADODB.Connection conn1 As New ADODB.Connection cmd As New ADODB.Command cmd1 As New ADODB.Command
-------------------------------------- An example of using a Passthru Command --------------------------------------conn1.ConnectionString = "Provider=AttunityConnect" conn1.Open conn1.DefaultDatabase = "Oracle" cmd1.ActiveConnection = conn1 cmd1.Properties("Operating_Mode") = "Passthru" cmd1.CommandText = "ALTER TABLE mytbal ADD new_column INTEGER" cmd1.Execute ------------------------------------------- Resetting the Passthru mode for the command -------------------------------------------cmd1.Properties("Operating_Mode") = "" Set cmd1 = Nothing conn1.Close Exit Sub End Sub
Via ADO/OLE DB
Use the Connection object and pass it the Operating_Mode parameter set to Passthru in order to enable passthru SQL. All SQL during this connection will bypass the Query processor. Example The following example code shows an ADO connection to an Oracle database. The connection is specified with the Operating_Mode parameter set to Passthru.
Public Public Public Public cmd As Object cmd1 As Object conn As Object conn1 As Object
Private Sub Bypass_Qpex1() Dim Dim Dim Dim Dim rs As New ADODB.Recordset conn As New ADODB.Connection conn1 As New ADODB.Connection cmd As New ADODB.Command cmd1 As New ADODB.Command
----------------------------------------- An example of using a Passthru Connection -----------------------------------------conn.ConnectionString = "Provider=AttunityConnect; Operating_Mode=Passthru" conn.Open conn.DefaultDatabase = "Oracle" cmd.ActiveConnection = conn cmd.CommandText = "ALTER TABLE mytbal ADD new_column INTEGER" cmd.Execute Set cmd = Nothing conn.Close
Via ODBC
Pass connection information to the SQLDriverConnect method, which includes the passthru parameter. For Windows Platforms: Via the Microsoft ODBC Data Source Administrator, with the Attunity ODBC connection wizard. Create or edit a DSN then select the Batch update passthru check box in the Remote Server Binding Page.
Example
ConnectString = "DRIVER=Attunity Connect Driver; DefTdpName=ORACLE;Binding=nav;Passthru=1;"
where disam and disam1 are data sources defined in the binding configuration. The query to the disam1 database is passed directly to the database, bypassing the Query Processor. Note the use of parameters in the example. You can also
specify parameters in a non-returning rowset query (see Passthru Query Statements (bypassing Query Processing) for the syntax). Standard ANSI 92 SQL has been extended so that expressions involving columns of tables that appeared previously in the FROM list are used (such as from the nation table in the above example) HP NonStop Platforms: When specifying a passthru query to a HP NonStop SQL/MP database, if the query is not within a transaction, you must append the words BROWSE ACCESS at the end of the query.
You cannot use reserved keywords in SQL for table and column names (see Reserved Keywords). The table below displays SQL query size limitations:
SQL Query Size Limitations Maximum Length
Table 81 Limitation
Length of an identifier (table or column name) 64 Length of a string1 Number of parameters in a query Level of nesting of function calls Level of nesting of nested queries Length of a LIKE mask operand Length of a comment line
1
The length can be modified in one of the following ways: By specifying a value for the tokenSize parameter within the <queryProcessor> group in the Attunity Server environment. Specify a question mark (?) instead of the string. When prompted for the data type of the value specify C (for cstring).
Comments can be included as part of the SQL. Comments are bounded by /* and */. If a comment is greater than the limit of 350 characters, break it up over a number of lines. Quotation marks ("") or square brackets ([]) can be used to quote identifiers such as table names and column names.
Use views and stored query procedures (CREATE VIEW Statement and CREATE PROCEDURE Statement). Use forward-only and read-only cursors. Batch SQL statements together in a single statement. For details, see below.
Use the HINT clause, specifying the optimization strategy you want used for the query (see Attunity SQL Syntax).
You can test connections and SQL interactively using NAV_UTIL EXECUTE.
Locking Considerations
This section includes the following topics:
Locking Modes
SQL UPDATE and DELETE statements are automatically executed in pessimistic locking mode. With SQL SELECT statements, the following locking modes are supported:
With chapters, child rowsets cannot be updated if the parent rowset is locked. Refer to the specific driver for additional locking information.
Optimistic Locking
With optimistic locking, records are locked just before an update operation. Before locking the row, Attunity Connect checks that another user hasn't changed the specified data. Optimistic locking has the following advantages over pessimistic locking:
Pessimistic Locking
With pessimistic locking, records are locked as they are read. Pessimistic locking is slower than optimistic locking. When connecting to data via Microsoft Jet or SQL Server, you must open a transaction before issuing the query.
No Locking
With no locking, records are not locked and are read-only.
SQL_CONCUR_VALUES: Optimistic locking (the locking itself is done during SQLSetPos if fLock = SQL_LOCK_EXCLUSIVE is specified). SQL_CONCUR_ROWVER: This is treated as if you specified SQL_CONCUR_VALUES.
SQL_CONCUR_LOCK: Pessimistic locking. SQL_CONCUR_READ_ONLY: Read-only mode. This is the default value.
adLockReadOnly (default): Read-only mode. adLockPessimistic: Pessimistic locking. adLockOptimistic: Optimistic locking. adLockBatchOptimistic: Optimistic batch updates. Required for batch update mode as opposed to immediate update mode.
These locking values should be used with ADO version 2.1 and higher.
Max Number of Row in a Table That Can Be Read: This parameter restricts the number of table rows that are read in a query. When the number of rows read from a table exceeds the number stated, the query returns an error. Max Number of Rows Allowed in a Table Before Scan is Rejected: This parameter restricts the number of table rows that can be scanned. This parameter impacts on the query both during query optimization and execution, as follows.
During query optimization: The value set is compared to the table cardinality. If the cardinality is greater than the value, the scan strategy is ignored as a possible strategy (unless it is the only available strategy). During query execution: A scan is limited to the value set. When the number of rows scanned exceeds the number stated, the query returns an error.
You must refresh the daemon as well as reloading the configuration after changing values in the WS Governing tab.
Property
Limitations
To optimize a query and select the largest part of a query that can be sent to the backend, the optimizer reorders the tables joined. The optimizer follows the following Outer join rules when reordering the tables to maintain outer join semantics:
Tables on the right side of a left outer join cannot be moved up the LOJ or to the LOJs left side. Tables from the left side of a left outer join that are not included in the outer join condition can be moved and joined to the outer join result. Tables from the left side of a left outer join that are included in the outer join condition cannot be joined to the outer join result.
Query Optimization
The query optimizer will attempt to send the greatest part of a query possible to the database on the backend instead of to the query processor. This can be achieved easily on joins that are executed on tables from the same database. Attunity Connect can execute outer joins on two or more databases, however these queries must be made by the Attunity query processor.
Property
The property noLojDelegation is set to false by default, which indicates that the Optimizer tries to delegate outer joins to the backend database. When this property is set to true, outer joins are always performed by the Attunity query processor even if part of the LOJs can be delegated to the backend. This is helpful for troubleshooting problems with outer join optimization or to preserve legacy optimization.
From the Configuration view on the left side, expand the machine folder. Expand the machine with the binding that has the optimizer settings you want to change. Right-click the binding that has the optimizer settings you want to change and select Edit Binding. The Binding editor opens on the right of the screen with the Properties tab open.
5. 6. 7.
From the Environment Properties list, expand Optimizer. Click the right side of the Value column for the noLojDelegaton property and select true from the drop-down list. Save the changes.
9
Working with Web Services
This section contains the following topics:
Web Services Overview Preparing to use Web Services Deploying an Adapter as a Web Service Undeploying Web Services Viewing Web Services Logging Web Service Activities
Web Services Prerequisites Setting up Attunity Studio to Work with Web Services
Apache Tomcat Web server, version 4.1 The axis.war file JDK 1.4. You must make sure that this full Java SDK is installed. Apache Tomcat will not work if only the Java Runtime Environment (JRE) is installed.
Install JDK version 1.4x on your computer. Apache Tomcat will not work with the Java Runtime Environment (JRE) only. You can download JDK 1.4 from http://tomcat.apache.org/download-41.cgi. Install Apache Tomcat version 4.1. Attunity Studio will only work with this version of Tomcat. Download Apache Tomcat from http://tomcat.apache.org/download-41.cgi. It is best to use the zip file. Extract the contents of the zip file to a folder on your main root drive, such as program files.
Copy the axis.war file to the webapps folder of the Tomcat root folder. For example, C:\Program Files\Apache\tomcat\webapps. This file should be supplied with your Attunity Studio installation. If not, you can download it from the Apache site. Run startup.bat from the tomcat\bin folder. Depending on where you installed your Apache Tomcat, the actual path will look something like C:\Program Files\Apache Software Foundation\Tomcat 4.1\apache-tomcat-4.1.34-LE-jdk14\bin. Test that Tomcat is running. Open a browser and enter the following URL: http:\\localhost:port 8080. If you changed your Tomcat default port to another number, for example, 80, enter that number instead of 8080.
Provide the connection information for the Apache AXIS servlet. Apache AXIS is an implementation of SOAP (Simple Object Access Protocol). Define the Web service and select the interactions to include in the service.
1. 2. 3. 4. 5.
To deploy an adapter as a Web service Open Attunity Studio, from the windows Start menu, select Programs, then select Attunity and then click Attunity Studio. Select the Design perspective. In the Configuration manager, expand the machine with the adapter that you want to set as a Web service. Expand the Bindings folder and then expand the binding with the adapter. Right-click the adapter you want to deploy as a Web service and find Web Services and then select Deploy. The Web Service Deployment wizard opens. This wizard has the following steps:
Connection Information for the Axis Servlet Define a new Web Service for an Adapter Select the Interactions Summary Window
Host: Enter the name of the server hosting the axis servlet. Enter the port information:
Port: The port used by the axis servlet. If your Apache Tomcat Web server is defined as port 8080, select the Use default port check box. Axis path: The path to the Axis servlet. In you copied the servlet into the Apache Tomcat webapp folder, you can use the default setting.
Enter the username and password to access the axis servlet. If you are using an anonymous connection, select the Anonymous connection check box.
Click Next. The Define a new Web Service for an Adapter step is displayed.
9-3
Name: Enter a name for the Web service. Each Web service must have a unique name that has only letters, digits and underscores. To reuse a name, you must undeploy the Web service with this name before assigning the name to the new Web service. See Undeploying Web Services.
Description: Enter a general description of this Web service. This is optional. Namespace: Enter a name for the namespace, if you want it to have a unique name. Select the Namespace enabled check box if you want to enable and use this namespace. If you do not enter a namespace, the namespace is created from the host name and Web service name.
Enter the username and password for users who can access the adapter at runtime. If you are using an anonymous connection, select the Anonymous connection check box. Click Advanced Options if you want to use any of the advanced options. The Advanced Options settings has the following tabs:
Timeout (sec): The Web server timeout in seconds. Firewall protocol: Select one of the following: None: To use no protocol. FixedNat: Select this if the machine you are working with has a fixed Network Address Translation (meaning that it is always connected to the same external IP address when accessing the Internet.
Trace enabled: Select this to enable tracing the communication between AIS and the Web service. If enabled, specify a path and name for the trace file. Encryption: Select this if you are using encryption. Enter the information for the encryption used.
When you are finished entering information in this tab, click OK to close the window and return to the Define a new Web Service for an Adapter step. You can also click The Pooling Tab or The Map Tab to enter information there.
9-5
Maximum active connections: The maximum number of connections that can be active at the same time. Maximum idle connections: The maximum number of connections that can be available in the pool. Behavior when a connection is not available: Select one of the following to indicate what behavior you want if a connection is not available: Fail: The interaction fails Grow: Create a new connection Block: Block the interaction
Time between idle connection examination runs (msec): The time (in milliseconds) to wait before checking if any connections are idle. Minimum idle time before removed from pool (msec): The minimum amount of time (in milliseconds) a connection can be idle before being closed.
When you are finished entering information in this tab, click OK to close the window and return to the Define a new Web Service for an Adapter step. You can also click The General Tab or The Map Tab to enter information there.
New connection parameters are entered as a key. For example, to open a new server for each operation, create a new key called newserver and enter 1 in the Value column. To enter a new key Right-click in the Key column and select Add. Type in a name for the key. Click in the Value column in the same row as the key to enter a value.
1. 2. 3.
To delete a key, right click on the key you want to delete and select Delete. When you are finished entering information in this tab, click OK to close the window and return to the Define a new Web Service for an Adapter step. You can also click The General Tab or The Pooling Tab to enter information there.
9-7
You can add interactions to include in the Web service, and also remove them from the Web service. To add or remove Web services, select the Web service and click on one of the buttons described in the following table.
Button Description Select an interaction from the left column and click this button to move it into the right column and include it in the Web service. Click this button to move all interactions from the left column to the right column and include all of the interactions in the Web service. Select an interaction from the right column and click this button to move it into the left column and remove it from the Web service. Click this button to move all interactions from the right column to the left column and remove all of the interactions from the Web service.
When you are finished selecting interactions to include in the Web service, click Next. A Summary Window showing the Web service settings is displayed.
Summary Window
The summary window shows you the configurations that you entered in each step of the wizard. Look over the information in this window to be sure it is correct. Click Back to return to any previous step and edit the information, if necessary.
When you are sure all the information is correct, click Finish to deploy the Web service.
Expand the Bindings folder and then expand the binding with the adapter. Right-click the adapter you want to undeploy as a Web service and find Web services, then select Undeploy. The Web Service Undeployment wizard opens.
4. 5.
Enter the Connection Information for the Axis Servlet. Click Next. A list of the Web services is displayed. You can click on the Web services and see the list of interactions that are associated with it.
6. 7.
Select the Web services you want to remove. Click Finish to undeploy the selected Web services.
Expand the Bindings folder and then expand the binding with the adapter.
Working with Web Services 9-9
3.
Right-click the adapter with the Web services and interactions you want to view, and find Web services, then select List. The Web Service Undeployment wizard opens.
4.
Click Next. A list of the Web services is displayed. You can click on the Web services and see the list of interactions that are associated with it. This is the same wizard that is displayed in when Undeploying Web Services, however you can only view the Web services.
The log file location. The level of error messages written to the log. The order of the error messages in the log.
Changes to the log file are set in log4j.properties which is located in: WebserverRoot\WebApps\Axis\Web-INF\classes\log4j.properties Where WebserverRoot is where the Web server is installed, for example: C:\Program Files\Apache Group\Tomcat 4.1\Webapps\axis\ Web-INF\classes\log4j.properties
Enter the error type as shown in the example below: log4j.logger.com.attunity.connect=error_type, LOGFILE
Part II
Attunity Connect
This part contains the following topics:
Introduction to Attunity Connect Attunity Integration Suite Architecture Flows Implementing a Data Access Solution Setting up Data Sources and Events with Attunity Studio Implementing an Application Access Solution Setting Up Adapters Application Adapter Definition
10
Introduction to Attunity Connect
This section contains the following topics:
Logical Architecture
(including diagram/s and what runs on each of the machines, ties in to next section)
The engines provide comprehensive transaction support to the extent allowed by the sources support for two-phase commit functions. AIS installations include the following engines:
Data Engine
The data engine accesses, updates, and joins enterprise information from data sources as if they were all relational databases. At the same time, it takes advantage of its query optimizer to determine the fastest way to carry out these tasks, minimizing the load on IT resources, networks, and systems. Because the data engine uses a relational model, it normalizes the data, converting hierarchical structures into tables without redundant data. By combining the relational model with the SQL language, the data engine allows applications to issue the same complex query to multiple data sources without tuning it to each target source. The relational approach also simplifies access via commercial tools and applications that interoperate with relational sources. Clients can use industry-standard JDBC, ODBC, ADO/OLE DB and .NET interfaces to submit SQL requests to the data engine. By using either the Database or Query application adapter, you can also use JCA, XML or COM as the client interface. When the data engine receives and parses an SQL request, it first determines which data source is involved, where the data resides, and how the source handles data. The data engine determines how to carry out the process based on metadata that it retrieves from a local cache, from the repository, or dynamically from the backend data sources. Then, the data engine generates a query execution plan in the form of a tree. Whenever possible the data engine passes the entire request to the underlying data source. In this case, the engine translates between standard ANSI SQL 92 and the underlying databases SQL dialect. The data engine can also accept pass-through queries to nonstandard SQL functions supported by the target source. If a data source offers limited SQL capabilities, the data engine implements missing functions as needed. If the data source offers no SQL capabilities at all, the data engine breaks the request into simple retrieval operations that an indexed or sequential table can read.
Query Optimizer
The data engine includes the query optimizer, which minimizes execution time and resource consumption. The query optimizer enhances the data engine's initial query execution plan based on the query structure, network structures, the target data sources capabilities and locations, and the statistical information available for each table. To maximize the efficiency of query execution, the query optimizer uses various caching and access techniques, including read-ahead, parallelism, and lookup-, hash-, and semi-joins. It flattens views, breaks out and propagates simple predicates down the tree, reorders joins, directs join strategies, selects indexes, and performs other related tasks. If the target data source is distributed across multiple machines, the data engine and query optimizer together generate a distributed execution plan that minimizes network traffic and round-trips. Performance Tuning Tools Database administrators can review and control the optimization strategies that the optimizer uses. Using the query analyzer, IT staff can monitor accumulated statistics and heuristic information to evaluate the success of the
10-2 AIS User Guide and Reference
optimization strategies. These tools enable users to evaluate and understand the way specific queries work by specifying hints, flags, optimization goals (first-row or all-rows optimization), and other query properties, such as requests for scrollable or updateable cursors.
Data Sources
Native data source drivers utilize the native API of each data source. Attunity Connect tailors these drivers to the individual data model and performance characteristics of the particular data source. These source-specific drivers share common logic. These drivers deal with metadata, describing the information offered by the data sources and mapping the underlying data model and functionality into relational or ISAM (Index Sequential Access Methods) models. Drivers for nonrelational data sources support sequential and indexed access, array structures and hierarchical structures, and other functions without normalization or other time-consuming operations. Drivers fall into one of the following classes:
RDBMS drivers to access data providers that support some dialect of SQL Non-relational drivers to access data providers that do not support SQL File system drivers to access files Procedure drivers to access program functionality
The functionality within each class can be factored further. For RDBMS drivers, Attunity Connect needs to be aware of the syntactic and semantic nuances of the SQL dialect for each specific data source, of the library functions supported by the data source, and other details. Similarly, a file system may or may not support functionality such as indexes, BLOBs and embedded rowsets, or be capable of efficiently executing single-table predicates (filters). For relational data sources not supported by Attunity Connect through a custom driver, Attunity Connect provides generic ODBC and OLE DB gateways. A syntax file (NAV.SYN) encapsulates backend peculiarities and facilitates the connection of the new data source to Attunity Connect using one of these generic drivers. The following data sources are supported:
Table 101 Relational DB2 Informix Supported Data Sources Non-relational Adabas CISAM File System Flat Files ODBC OLEDB-FS (Flat File System) OLEDB-SQL (Relational) Text-Delimited Procedures Procedure IMS/TM Natural CICS Procedure (Application Connector) CICS Procedure
Oracle Rdb (OpenVMS only) SQL/MP (HP NonStop only) SQL Server (Windows only)
Enscribe (HP NonStop only) IMS/DB (z/OS only) RMS (OpenVMS only)
Table 101 (Cont.) Supported Data Sources Relational Sybase Non-relational VSAM under CICS and VSAM (z/OS only) File System Procedures
In addition, procedure drivers are provided to enable access to program functionality. These procedures include a generic procedure driver and specific drivers for CICS, IMS/TM, and Natural programs on a z/OS platform.
JDBC Client Interface A pure-Java Type-3 driver that supports J2EE JDBC (such as data sources, distributed transactions, hierarchical record sets, and connection pooling). The JDBC interface is available on all platforms that support Java. ODBC Client Interface The ODBC interface enables organizations to use the API of choice for most popular client-server business intelligence tools. The ODBC interface implements the ODBC 2.5 and ISO CLI standards, so that COBOL and other 3GL programs on any platform can call it. The ODBC interface is available on all platforms running AIS. ADO Client Interface An OLE DB/ADO interface that supports advanced features, including chapters, scrollability, and multi-threading. The OLE DB/ADO interface is compatible with all Microsoft tools and applications. This provider also functions as a database gateway for Microsoft SQL Server, allowing SQL Server users to access all available data sources. The OLE DB/ADO interface is available on the Microsoft Windows platforms. .NET Client Interface ADO.NET is the data-access component of the Microsoft.NET Framework. AIS supports all ADO.NET objects, methods and properties as well as additional .NET Data Provider classes.
Transaction Support
To ensure the integrity of simultaneous updates to multiple data sources, Attunity Connect supports distributed transactions in the following ways:
As a distributed transaction manager, for safe, reliable multi-server transactions. As an OLE Transaction resource manager, enabling all AIS-enabled data sources to participate in distributed Microsoft MTS transactions using the OLE Transactions protocol. As an XA resource manager. Using the JDBC 2.x Interface, so that all AIS-enabled data sources can participate in distributed J2EE transactions under a J2EE application server.
A transactions log file backs up two-phase-commit (2PC) operations in the case of a failure to recover transactions. Generally, the ability to support distributed transactions depends on the capabilities of the data sources that participate in the transaction. Attunity Connect cannot guarantee data integrity for AIS-enabled data sources that do not support the 2PC protocol. However, Attunity Connect does employ various optimizations to extend the coverage of 2PC support. For example, Attunity Connect can execute a 2PC process as long it involves a maximum of one 1PC data source while all the other data source support 2PC.
10-4 AIS User Guide and Reference
Application Engine
The application engine provides an enterprise application integration (EAI) model that enables any kind of application to interact with applications and data sources via their own native interfaces. On the client end, applications use industry-standard interfaces to communicate with the application engine. In turn, the application engine communicates with specific adapters that access enterprise and application data on the server end. An XML-based schema supports precise application mapping. As a result, the application engine opens legacy applications of all types to integration with each other and with cutting-edge technologies such as Java and XML. Because the application engine uses an EAI model, interactions with the source application or data are precise and predictable. Requesting applications can specify exactly how interactions occur. Moreover, the application engine maps data structures faithfully, facilitating access to familiar applications within new environments. The EAI model is particularly suitable for deployment over the Internet using protocols such as TCP/IP and HTTP because it allows for both stateful and stateless interactions and can batch requests to minimize network traffic. A distinctive feature of the application engine is its ability to translate application structures, such as those typical of legacy COBOL applications, to and from XML. Web and other solutions can use the application engine to interact with both applications and data sources through a growing number of XML-based tools, as well as other application-oriented frameworks such as Suns J2EE JCA (J2EE Connectors Architecture) and Microsoft .NETs SOAP-based interfaces.
Application Adapters
With the AIS generic application adapter, developers can incorporate applications into Attunity Connect solutions. They can wrap and leverage existing application-specific business logic, protect data integrity by writing to a data source through its original application, and trigger operational tasks, all with a single adapter that runs consistently across diverse platforms. The following application adapters are provided:
CICS (on z/OS platforms) COM applications (on Windows platforms) Database and Query adapters access to any supported data source via XML, JCA, COM or .NET. IMS/TM (on z/OS platforms) Legacy applications Pathways (on HP NonStop Himalaya platforms) Tuxedo (on Windows and UNIX platforms)
XML Client Interface: The XML application interface enables any application with an XML API to access applications and data. The XML application interface supports an XML-based protocol modeled after the JCA architecture. This protocol is both readable by people and programmatically easy to use. This protocol is exceptionally well tailored for web-based, internet-wide use, particularly in conjunction with XML transformation engines. The XML application interface is directly available (callable) on all the platforms where AIS runs. On other
platforms, it is accessible via network protocols such as TCP/IP (sockets) and HTTP.
JCA Client Interface: The JCA (J2EE Connectors Architecture) interface supports application servers based on J2EE (Java 2 Enterprise Edition) standards. It provides a robust, efficient, and reliable way to integrate Java applications with native applications. COM Client Interface: A COM component that enables access to application adapters and services using the XML protocol. The COM component provides seamless integration with Microsoft Windows products and technologies. .NET Client Interface: A .NET component, called NetACX, that enables access to application adapters from any .NET-based application.
Events
AIS handles events via an event queue. The event queue is defined as an adapter in Attunity Studio where interactions are expected as events. The event queue itself is managed by a dedicated server process, which is set up by defining an events workspace in the daemon definition.
Attunity Server
Attunity Server is the server component that includes all the software required to enable AIS to run. AIS has a native installation wizard on each of the supported platforms, simplifying deployment. It takes no special skills to install AIS, so IT staff can set up the AIS infrastructure by applying only their platform- and application-specific expertise.
Attunity Studio
Attunity Studio is the configuration tool for AIS. Configuration using Attunity Studio is performed on a Windows platform. The configuration information is stored in the AIS repository on the backend system.
Design Time
Attunity Studio is used during design time to perform the following configuration tasks:
Set up access to machines running AIS Configure the daemon that is responsible for managing communication between AIS machines Configure metadata for both data sources and adapters. For all relational data sources and some non-relational data sources, Attunity Connect uses the native metadata. Otherwise, the metadata is specified to Attunity. See Working with Metadata in Attunity Studio for more information.
Runtime
Attunity Studio is used during runtime to perform the following management task:
Modify the configuration settings Manage daemons and workspaces during runtime (see Runtime Management with Attunity Studio)
Metadata Repository
AIS supports an XML-based schema. The schema and the AIS configuration are stored on the server file system and represent the repository. There is a single main repository for each installation of AIS. The repository maintains server-wide definitions (such as the daemon configuration) and application adapter definitions. There is also a repository for each data source which uses Attunity metadata. These repositories are optimized for fast run-time access. These repositories are not restricted by native operating system file naming conventions.
System Repository
The system repository is used for information that is general to AIS, such as:
Binding information, including the names of configured backend adapters and drivers and environment settings. Daemon definitions, to control client-server communication. User profiles, enabling single sign-on to multiple backend applications and data sources. Information used directly by the Query Processor. An adapter definition for each adapter defined. For each adapter, this includes a list of its interactions and the input and output structures that are used by these interactions.
Attunity metadata for non-relational data sources, files and Attunity Connect procedures, extensions of the native metadata of the data source (the extended metadata feature), and a snapshot of native metadata for better performance (the local copy feature). Synonym definitions for some of the data sources.
Daemons
A daemon, called IRPCD, runs on every machine running AIS and manages communication between machines running AIS. The daemon is responsible for allocating server processes to clients. The daemon authenticates clients, authorizes requests for a server process within a certain server workspace and provides clients with the required servers. When a client requests a connection, the daemon allocates a server process (or where applicable, a thread) to handle this connection, and refers the client to the allocated process. This may be a new process (dedicated to this client) or an already-started process. Further
communication between the client session and the server process is direct and does not involve the daemon. The daemon is notified when the connection ends and the process is either killed or remains available for use by another client. The daemon supports multiple server configurations called workspaces. Each workspace defines accessible data sources, applications, environment settings, security requirements, and server allocation rules. The allocation of servers by the daemon is based on the workspace that the client uses to access the data source. Thus, a client can access a data source via one workspace, where a server process is allocated from an existing pool of servers, or the client can access a data source via a different workspace, where a new server process is allocated for each client request. A fail-safe mechanism allows the specification of alternate daemons, which function as a standby for high availability.
Processing mode, specifying multi-threaded/single-threaded operations, the number of processes, and server pools. Security settings for impersonation, authorized users, administrators, and encryption.
AIS also supports multi-version interoperability. IT teams can simultaneously install multiple versions of AIS on all supported operating systems. As a result, organizations can begin to deploy new software versions in a staged update process, without interrupting the operations of previous versions. At the provider end of the system, servers act as agents that access, read, manipulate, and write to data sources and applications. Servers accept commands from clients, call the corresponding local functions, and package and return the results to the clients.
Note:
In the event that a target data source actually resides on another machine, the source is represented by an agent on the server using a third-party communications component such as Oracle Net Servers or Sybase CT-Lib, which is transparent to Attunity Connect.
Server software, which includes the application and data engines, drivers and adapters, resides on every AIS machine. When a client requests a connection, the daemon allocates a server process to handle this connection, and refers the client to the allocated process. This may be a new process (dedicated to this client) or an already-started process. Further communication between the client session and the server process is direct and does not involve the daemon. The daemon is notified when the connection ends and the process is either killed or remains for use by another client. This kind of server model is very flexible. It accommodates different operating systems and data source requirements. AIS supports several server models:
The multi-threaded model is effective when the data sources support multi-threading (on Windows platforms only). Serialized multi-client server processes are useful for short requests and for data sources that allow more than one simultaneous client per process. The single-client-per-process model supports data sources that only handle one client per process and to maximize client isolation.
Server processes can be reused. Various server process pooling options allow organizations to tune the solution for different application and load requirements.
11
Attunity Integration Suite Architecture Flows
This section has the following sections:
Overview Data Source Architecture Application Adapter Database and Query Adapter Change Data Capture (CDC) Flow
Overview
This section provides architectural drawings that show the basic flows used when you deploy AIS. AIS provides solutions for integrating data between data sources and through applications. In addition, you can also work with changed data captures (CDC). The basic AIS flows are:
Integration using a relational data source Integration using a non-relational data source (file system) Integration using generic database or query adapters Application-based integration Change Data Capture
Data Source
The following figure shows the flow architecture for integrating data with relational data sources.
Figure 111 Relational Data Source Flow
This table shows the flow for data integration from the client Machine to the Server Machine. The client side shows the APIs used for Java and other applications. The following table describes the parts in the relational data v flow. For more information on working with data access, see Implementing a Data Access Solution.
Table 111 Part Client Platform Java-based applications: Consumer Application in Java JDBC API NAV API Non-Java applications Consumer Application Data API An application written in Java. This is a Java application being run by the user on the client machine. The Java programming interface that allows external access to SQL queries. The standard programming interface for AIS. Any application not written in Java. This is an application being run by the user on the client machine. An interface that supports data and allows SQL queries. Relational Data Flow Parts Description
Table 111 (Cont.) Relational Data Flow Parts Part NAV API Query Engine and Optimizer Description The standard programming interface for AIS. The query engine parses the SQL and creates a statement that is read by multiple data sources, if necessary. The query optimizer refines the SQL statement so that it is most efficient and takes the least amount of time to send and receive the results. The way that a statement is handled by AIS, depends on the data source types that are queried. AIS queries the data for relational and non-relational data sources differently. For a more detailed explanation of this part of the data flow, see Query Engine Flow. Server Platform IRPCD (Daemon) Service Loop Driver This is the process that manages communication between all the machines in the flow. The service loop is the following, get request, handle request, revise request and continually repeat the process. The connecting driver for your data source. Attunity supplies many data source drivers. For more information, see the Data Source Reference. The Attunity data driver API. For more information, see The Attunity Connect Developer SDK. A driver created for a specific data source that is not one of the drivers supplied with AIS. The API for the database on the backend and the actual database used in this flow. The code on this level belongs to the database.
Making a Request between Two Relational Databases Making a Request between Two Non-Relational Databases Making a Request between a Relational Data Source and a Non-Relational Data Source
Making a Request between a Relational Data Source and a Non-Relational Data Source
The following figure shows a tree that traces an SQL query on a DISAM (non-relational) data source and an Oracle (relational) data source. In this case, the SQL statement requests an LOJ on the DISAM file and the Oracle table. The query engine splits into two branches. The first branch looks up the information in the DISAM file. The second branch uses the information in the SQL statement to carry out a filtering action and then looks up the information in the table using the filtering rules to find the correct columns.
Application Adapter
The following figure shows the flow architecture for integrating data between applications.
Figure 114 Application Flow
The following table describes the parts of the application flow. The client side is always a thin client and contains the application. The server side contains the main AIS installation and the necessary adapters. For more information on using application access, see Implementing an Application Access Solution.
Table 112 Part Client Platform Consumer Application ACX Gateway ACX Client Server Platform IRPCD (Daemon) This is the process that manages communication between all the machines in the flow. This is an application being run by the user on the client machine. The application can be 3GL, JCA, COM, or XML. A gateway based on the ACX protocol. For more information on the ACX protocol, see the Attunity Connect Developer SDK. A client based on the ACX protocol. This is always a thin client. Application Flow Parts Description
Table 112 (Cont.) Application Flow Parts Part Service Loop ACX Dispatcher Adapter GAP API Custom Adapter Application and Application API Description The service loop is the following, get request, handle request, revise request and continually repeat the process. The ACX-based program that sends XML queries to the application. The adapter that is used to provide access to your application. The Attunity Application API. For more information, see The Attunity Connect Developer SDK. An adapter created for a specific application that is not one of the adapters supplied with AIS. The actual application used in this flow and its API. The code on this level belongs to the application.
The following table describes the parts of the Change Data Capture flow. A change data capture captures changes to databases and writes them to a log file. For more information, see Implementing a Change Data Capture Solution.
Change Data Capture Flow Parts Description The data source where the changes are made. The user application makes the changes to the data source. The tool that identifies and captures the changes from the data source. A data source that saves raw change records. An Attunity Stream component that produces Attunity Stream change records (change stream). A change provider that retrieves raw change records (raw change stream) from the change source and produces Attunity Stream change records (change stream). A change provider that provides value-added services on a change stream. This element is optional. The Change Warehouse produces a change stream. An Attunity component that provides change stream records to a change consumer. A third-party tool or application that consumes change stream records. Examples include ETL and EAI tools and messaging systems.
Change Warehouse
The figure above shows how the query and database adapters handle a request. The flow has two parts. The top (above the dotted line) is the client side. The client side has the application that is making a request to the adapter. The application is based on the
ACX protocol. For information on the ACX protocol, see the Attunity Connect Developer SDK. The request is sent to the adapter on the server. If you are using a database adapter, the request is phrased in a standard XML format, which is converted to an SQL query. If you are using a query adapter, the SQL is entered directly.
Note:
The database adapter is not part of the flow if you use the Query adapter.
The SQL query is sent to the query processor, which sends it to the data source. The data source returns the result of the query, which are sent back to the application. In the figure above, the left side shows the input requests and the right side shows the output results for each phase of the flow.
12
Implementing a Data Access Solution
This section includes the following topics:
Overview Setting Up AIS for Data Access Installing AIS Configuring the System for Data Access (Using Studio) Supported Interfaces Data Access Flow Data Source Metadata
Overview
A data access solution uses data source drivers to let you connect to a supported data source from JDBC or ODBC applications on all platforms. Attunity data sources support ADO and .NET applications on Windows platforms. The following data source drivers are provided:
Table 121 Relational DB2 Data Source Informix Data Source Ingres II (Open Ingres) Data Source Oracle Data Source Oracle RDB Data Source (OpenVMS Only) SQL/MP Data Source (HP NonStop Only) SQL Server Data Source (Windows Only) Sybase Data Source Data Source Drivers Non-relational Adabas C Data Source Generic Flat File Data Source
CISAM /DISAM Data Source ODBC Data Source DBMS Data Source (OpenVMS Only) Enscribe Data Source (HP NonStop Only) IMS/DB Data Sources RMS Data Source (OpenVMS Only) VSAM Data Source (z/OS) under CICS and VSAM (z/OS only). OLEDB-FS (Flat File System) Data Source OLEDB-SQL (Relational) Data Source Text Delimited File Data Source
If you are working with a data source for which Attunity does not supply a driver, Attunity supplies an SDK to allow you to develop a driver for your data source. For details, see the Attunity Developer SDK reference.
Install AIS on the Backend. The backend are the machines where the databases are located. You also install the data source drivers here. Install the Attunity Server Software. Install Attunity Studio. Configure the Machines where you installed AIS and the data sources in Attunity Studio. Configure User Profiles. Set up and Configure the Binding for the data source. Configure the Data Sources in the Binding. Set Up the Data Source Metadata.
Installing AIS
Before you begin the process, you must install the necessary components. This includes the AIS client and server, and the data source drivers, the Attunity server software, and Attunity Studio. This section shows where to install the AIS components necessary for a data access solution.
Supported Interfaces
AIS Data Sources provide universal connectivity in many standard interfaces. In addition, Attunity also provides generic drivers for various interfaces, such as ODBC and JDBC. Attunitys universal connectivity uses Standard ANSI 92 SQL to query any supported data source, whether relational or non-relational. Specific versions of SQL for relational data sources can be used by making the SQL query directly to the data source. The following interfaces are supported by AIS:
JDBC Client Interface: A pure-Java Type-3 driver that supports J2EE JDBC (such as data sources, distributed transactions, hierarchical record sets, and connection pooling). The JDBC interface is available on all platforms that support Java. ODBC Client Interface: The ODBC interface enables organizations to use the API of choice for most popular client-server business intelligence tools. The ODBC interface implements the ODBC 2.5 and ISO CLI standards, so that COBOL and other 3GL programs on any platform can call it. The ODBC interface is available on all platforms running AIS. ODBC Client Interface Under CICS (z/OS Only): The ODBC interface on a mainframe is access through either a COBOL or C program running under CICS. On the z/OS machine you do not need to run the daemon if the daemon is running on the target machine. OLE DB (ADO) Client Interface: An OLE DB/ADO interface that supports advanced features, including chapters, scrollability, and multi-threading. The OLE DB/ADO interface is compatible with all Microsoft tools and applications. This provider also functions as a database gateway for Microsoft SQL Server, allowing SQL Server users to access all supported data sources. The OLE DB/ADO interface is available on the Microsoft Windows platforms.
Note:
The Windows Attunity Server kit is required to use the ADO client interface.
NET Client Interface: ADO.NET is the data-access component of the Microsoft .NET Framework. AIS supports all ADO.NET objects, methods and properties as well as additional.NET Data Provider classes for specific use with AIS.
<?xml version="1.0" encoding="UTF-8"?> <table name="customer" datasource="___NAVDEMO" description="" fileName="C:\Program Files\Attunity\Server\demo\customer" nBlocks="0" nRows="0" bookmarkSize="4" organization="index"> <fields> <field name="c_custkey" datatype="int4"/> <field name="c_name" datatype="cstring" size="25"/>
<field name="c_address" datatype="cstring" size="40"/> <field name="c_nationkey" datatype="int4"/> <field name="c_phone" datatype="string" size="15"/> <field name="c_acctbal" datatype="double"/> <field name="c_mktsegment" datatype="string" size="10"/> <field name="c_comment" datatype="cstring" size="117" nullable="true"/> </fields> <keys> <key name="cindex" size="4"> <segments> <segment name="c_custkey"/> </segments> </key> </keys> </table>
Adabas C Data Source Enscribe Data Source (HP NonStop Only) VSAM Data Source (z/OS) CISAM /DISAM Data Source
In Binding editor, click the Properties tab (at the bottom of the editor). In the Properties tab, expand Misc. Find the exposeXMLField property, click in the Value column and select true. Save and refresh the binding.
Note:
See also:
Environment Properties
<update> <sql>update adabas:table1 set xml=? where ISN='13'</sql> <inputParameter> <TABLE1 INT="400"> <PE1 FLOAT4="23.67" FIXED2="1500" PACKED_DEC="898900" character="XYZ"/> <PE1 FLOAT4="24.67" FIXED2="600" PACKED_DEC="898900"/> <PACKED_DEC_ARRAY>409</PACKED_DEC_ARRAY> <PACKED_DEC_ARRAY>299</PACKED_DEC_ARRAY> </TABLE1> </inputParameter> </update>
Notes:
Using the Attunity XML Utility lets you enter the input and receive the record. The recommended method for executing an XML operation is to make the select operation (for example a select Update operation), then update the output XML and then set the operation. If subfields are defined in the metadata with one of the XML operations, the subfields must match their original field or the subfield will have a non-valid offset.
13
Setting up Data Sources and Events with Attunity Studio
This section contains the following topics:
Data Sources
Data Sources are added to Bindings in Attunity Studio. A data source driver is used to connect directly to a various data sources, from JDBC, ODBC applications on all platforms, and from ADO and.NET applications on Windows. You use data sources when Implementing a Data Access Solution in Attunity Connect. The following sections describe how to set up data sources in your system.
In the Design Perspective Configuration View, expand the Machine folder and then expand the Machine where you want to add the data source. Open the Bindings folder for the machine where you want to add the data source. Expand the Binding with the data source you are working with. Right-click the Data source folder and select New Data Source. The New Data Source wizard opens.
6.
Name: Enter a name to identify the data source. Type: Select the data source type that you want to use from the list. The available data sources are described in the adapter reference section.
7.
Select the data source type from the Type list. Select the data source type that you want to use from the list. The available data sources are described in the adapter reference section.
13-1
8.
9.
Enter the information requested in this step. The information required depends on the type of data source selected. See the Data Source Reference for more information on how to configure each data source.
Note:
The above procedure is also used to add a procedure data source. To add a procedure, select a procedure driver as your data source driver. For more information, see Configuring the Procedure Data Source.
1.
To configure a data source Right-click the data source you are working with and select Open. The Data Source configuration opens in the editor.
2. 3.
Click the Configuration tab. You can make changes to the data source configuration as required. This tab can have three sections:
Connection: This section lets you make changes to the information that you entered in the Connect String page of the New Data Source wizard. Authentication: This lets you edit the authentication information for data sources that require this. The following data sources have the Authentication section: Adabas (ADD) DB2 (all types) Ingres ODBC OLEDB (all types) Oracle Oracle RDB SQL Server Sybase VSAM (CICS)
Properties: This section lets you change the default values for the configuration properties for your data source.
For information on how to enter the configuration information, see the information for your data source in the Data Source Reference.
Define the Transaction type Edit the syntax name Provide a table owner Determine if a data source is updateable or readable Provide repository information Set the virtual view policy
1. 2. 3. 4.
To configure data source advanced properties Open Attunity Studio. In the Design Perspective Configuration View, expand the Machine folder and then expand the machine where you want to configure the data source. Expand the Data sources folder, right click the data source you are configuring, then select Open. Click the Advanced tab and make the changes that you want. The table below describes the available fields:
Data Source Advanced Configuration Description
Transaction type
The transaction level (0PC, 1PC or 2PC) that is applied to this data source, no matter what level the data source supports. The default is the data sources default level. A section name in the NAV.SYN file that describes SQL syntax variations. The default syntax file contains the following predefined sections:
Syntax name
OLESQL driver and the SQL Server 7 OLE DB provider (SQLOLEDB): syntaxName="OLESQL_SQLOLEDB" OLESQL driver and JOLT: syntaxName="OLESQL_JOLT" Rdb driver and Rdb version: syntaxName="RDBS_SYNTAX" ODBC driver and EXCEL data: syntaxName="excel_data" ODBC driver and SQL/MX data: syntaxName="SQLMX_SYNTAX" ODBC driver and SYBASE SQL AnyWhere data: syntaxName="SQLANYS_SYNTAX" Oracle driver and Oracle case sensitive data: syntaxName="ORACLE8_SYNTAX" or, syntaxName="ORACLE_SYNTAX" For case sensitive table and column names in Oracle, use quotes (") to delimit the names. Specify the case sensitivity precisely.
The name of the table owner that is used if an owner is not indicated in the SQL
13-3
Table 131 (Cont.) Data Source Advanced Configuration Field Read/Write information Description Select one of the following:
Updateable data: Select this if you want to be able to update the data on the data source. Read only data: Select this to allow users to only view the data on the data source.
Repository Directory Repository directory Repository name Enter the location for the data source repository. Enter the name of a repository for a data source. The name is defined as a data source in the binding configuration. It is defined as the type Virtual and is used to store AIS views and stored procedures for the data source, if required instead of using the default SYS data.
Virtual View Policy Generate sequential view Select this to map a non-relation file to a single table. This parameter is valid only if you are using virtual array views. You configure virtual array views in the Modeling section of the binding Environment Properties. Select this if you want to have an individual table created for every array in the non-relational file. This parameter is valid only if you are using virtual array views. You configure virtual array views in the Modeling section of the binding Environment Properties. Select this to include a column that specifies the row number in the virtual or sequential view. This parameter is valid only if you are using virtual array views. You configure virtual array views in the Modeling section of the binding Environment Properties. Select this for virtual views to include all the columns in the parent record. This parameter is valid only if you are using virtual array views. You configure virtual array views in the Modeling section of the binding Environment Properties.
Select the active workspace from the drop-down list. Click Next. The next page in the wizard opens with the results. A successful result indicates that the connection is active. If there is a problem, and error message that describes the problem is displayed.
"fat" version of ODBC Client Interface (when the server installation is used as a client).1 To create a data source shortcut Drag-and-drop a data source from the Machine where the data source is defined to the machine where you want the shortcut. Or do the following:
1. 2. 3.
In the Design Perspective Configuration View, expand the machine where the data source shortcut should be defined. Expand the Bindings folder and then expand the binding where you want to add the data source. Right-click Data Sources and select New Data Source Shortcut. The New Data Source Shortcut wizard opens.
4.
If the machine is defined in Attunity Studio, select Machine from Configuration view and select the machine with the target data from the drop-down list. If the machine is defined in the binding as a remote machine (for more information see, Setting up Machines), select Machine defined in current binding remote machines list and select the machine from the list. If you want to also add the machine where the data source resides to the list of machines in the Configuration view select New machine. After clicking Next, the Add Machine screen opens where you can add the machine (see Setting up Machines).
5.
A thin ODBC client is available that does not require a data source shortcut defined on the client machine.
13-5
6.
Physical Address: The physical address of the machine with the data source. You cannot edit this field. Alias in binding: The alias given to the machine for the binding. Port: The machines port number. Workspace: Select the workspace that is used to access the data source.
7.
8.
Add the following information about the machine security in this screen.
User name: Enter the user name for a user that has rights to access this data source on this machine. Password: Enter the users password. Confirm password: Re-enter the users password to confirm. Encryption protocol: Select the encryption protocol (if any) used for this protocol. For information on encryption in AIS, see Encrypting Network Communications. Firewall protocol: Enter the firewall protocol (if any) used for the machine with the data source. For information on using a firewall in AIS, see Accessing a Server through a Firewall.
This user and password information is written in the user profile associated with the binding (the user profile with the same name as the binding name). For details about the user profiles, see Managing a User Profile in Attunity Studio.
9.
Click Next. The list of available data sources opens. Select the data source for which you are creating a shortcut and click Finish. source name is used as a data source in the binding on the client machine. The data source shortcut is displayed in the Configuration View.
10. Select the Alias in binding check box and provide an alias for the name if the data
The active workspace is displayed in a read only field. The test procedure pings the server with the selected workspace when the test is executed.
2.
Click Next The next screen in the wizard opens with the results. A successful result indicates that the connection is active. If there is a problem, an error message that describes the problem is displayed.
Events
Attunity Studio uses event queues to handle Events. TheEvent Queue is defined as an adapter in Attunity Studio where interactions are expected as events.
In the Design perspective Configuration view, expand the Machine folder and then expand the machine where you want to add the event. Expand the Bindings folder and then the binding where you want to add the event. Right-click the Events folder and select New event. The New Event editor opens. Enter a name for the event queue.
Notes:
The name must be less than 32 characters. You cannot use the word event in the event name.
6.
Select the type of queue that you are using to handle events.
Event Queue: This will handle events using a regular event queue adapter. Tuxedo Queue: This will handle events with a Tuxedo Queue adapter. CICS Queue: This will handle events with a CICS Queue adapter (for z/OS systems only).
7.
Click Finish. A message appears asking if you want to change the daemon configuration. Click OK to accept the changes made in this procedure, or cancel to close and not confirm the changes. A new editor opens in the Editor section of the Studio workbench. The name of the editor is the name of the binding where you added the event queue.
After you finish adding the event queue to the Studio, follow these steps for making changes to the event queues adapter properties. To edit the event queues adapter properties In the Design perspective Configuration view, expand the Machine folder and then expand the machine with the event, expand the Events folder, then right-click
1.
the event and select Open. The Adapter configuration properties open in the editor
Note:
2.
addExecuteTimestamp: Do not change the setting for this property. remoteExecuteCompress: Do not change the setting for this property. remoteExecuteUrl: Do not change the setting for this property. routers: A list of users who can send receive an event. If the owner of the target is not one of these users, the event is not routed to the user. To add routers, expand this property and right-click users. A new entry called Item(#) is added to the Property column. In the Value column, enter the User Name for this router. senders: A list of users who can send an event. If the owner of the event is not one of these users, the event is ignored. To add senders, expand this property and right-click users. A new entry called Item(#) is added to the Property column. In the Value column, enter the User Name for this sender.
Expand the event queue adapter, then right-click Imports and select New Import. The Metadata import screen opens in the editor.
3. 4.
Enter a name for the import. The name can contain letters, numbers and the underscore character. Select one of the following from the drop-down list:
Event Queue Import Manager Using COBOL Copybook Files Event Queue Import Manager Using Tuxedo VIEW/FML Files as the import type
5. 6.
Click Finish. The Metadata Import wizard opens. Click Add in the import wizard to add COBOL copybooks or BEA Tuxedo VIEW/FML files. The Add Resource window opens, which lets you select files from the local machine or get them from an FTP site. If the files are on another machine, you can add the FTP site.
13-9
Right-click My FTP Sites and select Add. In the Add FTP site screen, enter the server name where the COBOL copybooks reside. If you are not using an anonymous access, enter a valid username and password. You can browse and transfer files required to generate the metadata. Access the machine using the username as the root directory (high-level qualifier on z/OS systems).
Note:
After you access a machine you can right-click the machine and select Change Root Directory to change the high-level qualifier.
7.
From the Add Resource screen, select the files to transfer and click Finish.
Note:
You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks. Each COBOL copybook format must be the same. Therefore, if you try to import a COBOL copybook that uses the first six columns with a COBOL copybook that ignores the first six columns, you must repeat the import.
8.
Click Next. The Apply Filters editor opens. Use this editor to apply filters, if necessary.
Note:
You can only use filters if using COBOL. If you are using Tuxedo VIEW/FML files, go to the next step.
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type.
Setting up Data Sources and Events with Attunity Studio 13-11
Compiler source: The compiler vendor. Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP is for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Prefix nested columns: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity metadata, is replaced with an underscore. Case sensitive: Indicates whether to consider case sensitivity. Find: Searches for the selected value. Replace with: Replaces the value that is entered (in the Find field) with the value with another selected value.
9.
10. Click Add to add events. You can change the default name that is specified for the
event. The event mode is async-send, which means that the event queue waits for an input. You specify an input record used by the program associated with the event from the drop-down list in the Input column. This list is generated from the input files specified at the beginning of the procedure. Select a relevant record for the event.
11. Add as many events as necessary and click Next.
12. Click Next twice to open the Import Metadata screen. In this screen you generate
the metadata. You can import the metadata to the mainframe machine or leave the generated metadata on the Attunity Studio machine, to be imported later.
Figure 138 Import Metadata
13. In the Deploy Metadata section, select Yes if you want to transfer the metadata to
Note:
After you import the metadata, you can view the metadata in the Metadata tab. You can also make any adjustments to the metadata and maintain it, as necessary. For more information, see Working with Metadata in Attunity Studio.
13-13
14
Procedure Data Sources
This section includes the following topics:
Adding Procedure Data Sources: The procedure needs to be listed in a binding configuration. The definition in the binding includes properties, set in the procedure editor Properties tab. Each procedure has its own set of specific properties. Defining a Shortcut to a Procedure on Another Machine: A procedure driver requires a metadata definition that describes the inputs and outputs for the procedure.
Using the NAV_UTIL EDIT command. Using the NAV_UTIL UPD_DS command.
In the Design perspective, Configuration view expand the machine where you want to add the procedure data source. Expand the Bindings folder, and then expand the required binding configuration. Right-click Data sources and select New Data source. Enter a name for the procedure in the Name field. Select the procedure type from the Type list. Click Next. Enter the connect string to access the procedure. For information on how to enter the connect string, see the information for the procedure data source that you are using in the Procedure Data Source Reference. Click Finish.
9.
The procedure data source is displayed in the Configuration view and the procedure editor is displayed. You can set or change the properties for procedures in the following ways:
Using the Attunity Studio Design perspective Configuration view. Using the sp_config_datasource stored procedure as follows:
nav_proc:sp_config_datasource(ds_name, <config attribute="value"/>)
You change an environment property by executing a statement with the following format:
call nav_proc:sp_config_environment('proc_name','<config att="value"/>')
Where proc_name is the name of the procedure in the binding configuration. To edit a procedure data source definition Open Attunity Studio. In the Design perspective Configuration view, expand the machine with the procedure data source you are using. Expand the Binding folder and then expand the binding with your procedure data source. Expand the Data sources folder. Right-click your procedure data source and select Open. Click the Configuration tab. This tab should be open by default.
1. 2. 3. 4. 5.
6.
Make changes to any of the sections in this tab, if necessary. This tab can have any of the following sections.
Connection: This section lets you make changes to the information that you entered in the Connect String page of the New Data Source wizard. The Natural/CICS Procedure Data Source (z/OS) and the CICS Procedure Data Source require configuration in the Configuration section. Authentication: This lets you edit the authentication information for data sources that require this. The Procedure Data Source (Application Connector). data source requires configuration in the Authentication section: Properties: This section lets you change the default values for the configuration properties for your data source. All of the procedure data sources contain properties to be configured. For information about the properties for each data source, find the data source in the Procedure Data Source Reference.
7.
Click Save.
Define the Transaction type Edit the syntax name Provide a table owner Determine if a data source is updateable or readable Provide repository information Set the virtual view policy
1. 2. 3. 4.
To configure data source advanced properties "Open" Attunity Studio. In the Design Perspective Configuration View, expand the Machine folder and then expand the machine where you want to configure the data source. Expand the Data sources folder, right click the data source you are configuring, then select Open. Click the Advanced tab and make the changes that you want. The table below describes the available fields:
Data Source Advanced Configuration Description
Transaction type
The transaction level (0PC, 1PC or 2PC) that is applied to this data source, no matter what level the data source supports. The default is the data sources default level.
Table 142 (Cont.) Data Source Advanced Configuration Field Syntax name Description A section name in the NAV.SYN file that describes SQL syntax variations. The default syntax file contains the following predefined sections:
OLESQL driver and the SQL Server 7 OLE DB provider (SQLOLEDB): syntaxName="OLESQL_SQLOLEDB" OLESQL driver and JOLT: syntaxName="OLESQL_JOLT" Rdb driver and Rdb version: syntaxName="RDBS_SYNTAX" ODBC driver and EXCEL data: syntaxName="excel_data" ODBC driver and SQL/MX data: syntaxName="SQLMX_SYNTAX" ODBC driver and SYBASE SQL AnyWhere data: syntaxName="SQLANYS_SYNTAX" Oracle driver and Oracle case sensitive data: syntaxName="ORACLE8_SYNTAX" or, syntaxName="ORACLE_SYNTAX" For case sensitive table and column names in Oracle, use quotes (") to delimit the names. Specify the case sensitivity precisely.
The name of the table owner that is used if an owner is not indicated in the SQL Select one of the following:
Updateable data: Select this if you want to be able to update the data on the data source. Read only data: Select this to allow users to only view the data on the data source.
Repository Directory Repository directory Repository name Enter the location for the data source repository. Enter the name of a repository for a data source. The name is defined as a data source in the binding configuration. It is defined as the type Virtual and is used to store AIS views and stored procedures for the data source, if required instead of using the default SYS data.
Virtual View Policy Generate sequential view Generate virtual views Include row number column All parent columns Select this to generate virtual views for arrays when importing metadata.
A thin ODBC client is available that does not require a data source shortcut defined on the client machine.
To create a procedure shortcut You can drag-and-drop a data source from the machine where the data source is defined to the machine where you want the shortcut. or do the following:
1. 2. 3. 4.
Open Attunity Studio. In the Design perspective Configuration view, expand the machine where you want to create the shortcut. Expand the Bindings folder and the binding where you want to add the procedure shortcut. Right-click the Data sources folder and select New Data Source Shortcut. The New Data source shortcut wizard opens, as shown in the following figure:
5.
Select the machine where the target procedure is defined. If that machine is defined in Attunity Studio, then select Machine from Configuration, and then select the machine from the list. Click Next to open the Add runtime machine access information page. If the machine was defined in the binding as a remote machine, then select Machine defined in current binding remote machines list, and then select
the machine from the drop-down list. Click Next to open the Add runtime machine access information page.
If you want to also add the machine where the procedure resides to the list of machines in the tree, select New machine-add the new machine. Click Next, the Add Machine dialog opens to add the machine as described in Setting up Machines. After you add the new machine information, click Next to open the Add runtime machine access information page.
6.
In the Add runtime machine access information page, you can change the following information, if necessary:
Alias in binding: Change the name of the shortcut. Port: Change the port where the original data source is located. Workspace: Change the workspace for the original data source.
7.
Click Next. The Add runtime security information page is displayed. Add security information, if necessary (User name, Password, Encryption protocol and Firewall protocol).
Note:
This information is written to the user profile, associated with the binding. For more information, see Managing a User Profile in Attunity Studio.
8.
Click Next. The list of available data sources, including procedures, is displayed. Select the required procedure, and click Finish.
Note:
If the procedure name is used as a procedure or data source in the binding on the client machine, check the Alias in binding box and provide an alias for the name.
15
Implementing an Application Access Solution
This section contains the following:
Overview Setting up AIS for Application Access Supported APIs Application Access Flow Defining the Application Adapter ACX Protocol Transaction Support Generic and Custom Adapters
Overview
An application access solution lets you connect between 3GL applications directly. An application context is any enterprise software component where interactions occur within a transaction context. Applications include:
Internally developed applications Enterprise packaged products, such as ERP or CRM products Database systems, such as relational databases or file systems
AIS uses the Attunity Applications Adapter Framework (AAF) to accomplish this. In this framework, an application adapter that directly connects to an application is used instead of a data source. The following application adapters are currently available.
Table 151 Application Adapters Application A program via a CICS EXCI transaction Simple COM-based applications A program via an IMS/TM transaction
Adapter Name CICS Application Adapter (z/OS Only) COM Adapter (Windows Only) IMS/TM Adapter (z/OS Only)
Table 151 (Cont.) Application Adapters Adapter Name Legacy Plug Application Adapter Pathway Application Adapter (HP NonStop Only) Tuxedo Application Adapter (UNIX and Windows Only) Application Any legacy application A program via a Pathway transaction
Note:
If the application is not directly supported by one of these adapters, Attunity Connect includes an SDK that enables you to write an adapter for the specific application. For details, see the Attunity Connect Developer SDK.
Configure the system for application access. Make the configurations in Attunity Studio. For Application Access, select an adapter to use for you integration. See Configuring the System for Application Access (Using Studio) for a detailed explanation on what to configure.
AIS on the backend. The backend of the system is where your data is stored. In an application access solution, you access an application, such as CICS, directly to get the necessary data. This is where your application adapter resides. You must install the full (thick) version of AIS on the backend. For information on how to install AIS, see the Installation Guide for the platform you are working with. AIS for the Application (Thin Client): The application (XML, JCA, COM or .NET) that you are working with is installed with an AIS thin client. For information on how to install the AIS thin client, see the installation guide for the platform you are working on. Attunity Studio: Attunity Studio can be installed on any Windows computer in your system. Attunity Studio provides a graphic interface for configuring the components in your system. For information on installing Attunity Studio, see the installation guide.
Machines: You must configure the machines used in the system. Make sure to configure the machine where your backend application and application adapter reside. For information on how to add and configure machines, see Setting up Machines. You can also test the machine connection in Attunity Studio. User Profiles: You must set up the users in your system. Setting up users is for security purposes. You can specify which users have access to various machines. For information on setting up user profiles, see User Profiles and Managing a User Profile in Attunity Studio. Application adapters: This is what makes this solution the application access solution. To set up your adapter, you must: Prepare to use the adapter by Setting Up Adapters to Attunity Studio. Create the application adapter interactions. You do this by Configuring Application Adapters that you are using for your solution. Make sure that your adapter is responding correctly by carrying out the procedures in Testing Application Adapters. Define the adapter metadata. Adapter metadata defines the interactions for the application adapter and the schema of any input and output records used by the interactions. The metadata is stored as an application adapter definition in the SYS repository, on the machine where the adapter is defined. See Working with Application Adapter Metadata. All metadata is imported from relevant input files (such as COBOL copybooks) and maintained using the Attunity Studio Design perspective Metadata tab. For more information on setting up application adapters, see Setting Up Adapters and the Adapters Reference section for the adapter you are using.
Note:
Attunity metadata is independent of its origin. Therefore, any changes made to the source metadata (for example, the COBOL copybook) is not indicated in the Attunity metadata.
Supported APIs
AIS application adapters connect to supported applications using JCA, XML COM, or.NET APIs on Windows platforms.
The XML Client Interface: The XML application interface enables any application with an XML API to access applications and data. The XML application interface supports an XML-based protocol modeled after the JCA architecture. This protocol is both readable by people and programmatically easy to use. This protocol is works well for web-based, internet-wide use, particularly in conjunction with XML transformation engines. The XML application interface is directly available (callable) on all supported platforms. On other platforms, it is accessible via network protocols such as TCP/IP (sockets) and HTTP. The JCA Client Interface: The JCA (J2EE Connectors Architecture) interface supports application servers based on J2EE (Java 2 Enterprise Edition) standards.
It provides a robust, efficient, and reliable way to integrate Java applications with native applications.
The COM Client Interface: A COM component that enables access to application adapters and services using the XML protocol. The COM component provides seamless integration with Microsoft Windows products and technologies. .NET Client Interface : A .NET component, called NetACX, that enables access from any .NET-based application.
application, such as the CICS adapter. You can also create an application to work with an application developed internally. All adapters must have an adapter or metadata definition. The definition is made up of a list of interactions and a schema. The user must enter the location for an XML schema that includes the metadata for the application. The schema contains all of the record structures without the interactions. The following figure shows an example of the adapter definition. In this case, this is the adapters metadata in XML format.
Figure 152 Example of an Adapter Definition
You define the adapter in Attunity Studio. Studio provides a graphical interface that allows you to define and import metadata definitions for adapters. For more information on how to define adapters in Attunity Studio, see Setting Up Adapters.
ACX Protocol
ACX (Attunity Connect XML Protocol) is Attunitys internal XML protocol. ACX is modeled after JCA (Sun Javas connection protocol). ACX is the wire that connects the applications and APIs with the target Application metadata definitions. ACX executes its tasks with connections between applications. There are two types of connections:
Transient connection: Transient connections are used with a single ACX request. A transient connection closes when an ACX request ends, or when the connection context changes (when a new verb is used to send a new request). Persistent connection: Persistent connections are used for an ongoing dialog with the back-end adapter or for pooling scenarios. Persistent connections are closed manually or when timed out. Persistent ACX connections are logical and do not rely on an active network connection (such as a connected socket) to stay active. This lets you use disconnected protocols such as HTTP as transports for ACX.
The daemon keeps track of persistent connections with a unique connection ID. If you need to send a new ACX request at a later time, you can use a previous persistent connection by using its connection ID.
Note:
The AIS XML Utility lets you make connections between applications using the ACX protocol. For more information see Using the Attunity XML Utility. For information on using ACX, see the Adapters Reference and the XML Client Interface chapter.
Transaction Support
Application adapters may support a two-phase commit capability to the extent that transactions are implemented in the application. A two-phase commit lets a database return to its pre-transaction state if an error occurs. This type of commit is used when more than one database or resource are updated in a single transaction. In a two-phase commit either all or none of the databases are committed. In a transaction using a two-phase commit, all changes are stored temporarily by each database. A transaction monitor issues a pre-commit command that requires an answer from each database. When all databases answer with a positive response, the final commit is issued. Applications with two-phase commit support: Attunity Connect supports the PrepareCommit and Recover API calls. Applications that support two-phase commit can participate fully in a distributed transaction. The following adapters support two-phase commit:
To work with two-phase commit with either of these application adapters, RRS (Transaction Management and Recoverable Resource Manager Services) must be installed. See Transaction Support.
See the reference for the specific adapter for any two-phase commit considerations.
interactions. Examples of generic adapters include CICS Application Adapter (z/OS Only), IMS/TM Adapter (z/OS Only), Pathway Application Adapter (HP NonStop Only), and Legacy Plug Application Adapter.
It receives a string and an integer parameter It returns a string value of up to 512 characters and an integer value
If the above is true then the following figure shows the schema that is generated for this application.
Figure 153 Sample Schema for MyApp
The following is an example of the generated code for the MyApp application:
Figure 154 Code Example for MyApp
For more information on writing application adapters with the GAP SDK, see the Attunity Connect Developer SDK.
16
Setting Up Adapters
This section contains the following topics:
In the Design Perspective Configuration View, expand the Machines folder and then expand the Machine where you want to add the adapter. If you need to add a machine to your Attunity Studio setup, see Setting up Machines. Expand the Bindings folder. Expand the binding where you want to add the adapter. Right-click the Adapters folder and select New Adapter. The New Adapter wizard opens.
Setting Up Adapters 16-1
3. 4. 5.
6.
Name: Enter a name to identify the adapter. Type: Select the adapter type that you want to use from the list. The available adapters are described in the adapter reference section. Create event queue for the adapter: Select this check box if you want to associate an Event Queue with this adapter. For information on event queues, see Events.
Note:
you cannot use the word Event as part of the adapter name.
7.
Click Finish.
Expand the Machines folder. Expand the Bindings folder, and then expand the binding with the adapter you are working with. Expand the Adapter folder. Right-click the adapter that you want to work with and select Open. The adapter configuration editor opens in the editor, which displays the properties for the adapter.
6.
Configure the adapter parameters as required. The configuration properties displayed depend on the type of adapter you are working with. For an explanation of these properties, see the Adapters Reference or the Non-Application Adapters Reference to find the documentation for your adapter.
Select the active workspace from the drop-down list. The test procedure pings the server with the selected workspace when the test is executed. Click Next. The next page in the wizard opens with the results. A successful result indicates that the connection is active. If there is a problem, an error message that describes the problem is displayed.
17
Application Adapter Definition
This section includes the following topics:
Overview The adapter Element The interaction Element The schema Element The enumeration Element The record Element The variant record Element The field Element
Overview
An application adapter definition includes the following information:
Interactions List
This part lists the Interactions offered by the adapter. Information items include the interaction name, its description and input and output record names.
17-1
The attributes of the adapter element define simple adapter properties (see below). The interaction elements under the adapter describe particular interactions. The schema element under the adapter provides the schema of all the records used within the adapter.
enum basic password The type of authentication implemented by the adapter, as follows:
none: The adapter does not handle authentication. basic password: The adapter implements basic username-password authentication.
Note: Kerberos authentication will be supported in future releases. connect connectionPoolingSize description maxActiveConnections maxIdleTimeout string int string int int 600 Adapter specific connect string. The number of connections that can be held in the connections pool simultaneously. The number of connections that can be held in the connections pool simultaneously. The maximum number of simultaneous connections an adapter may take (per process). The maximum time, in seconds, that an active connection can stay idle. After that time, the connection is soft-closed and placed in the connections pool or simply destroyed (depending on the pooling settings). The maximum size in bytes that an XML ACX request or reply may span. Larger messages are rejected with an error.
maxRequestSize
int
Table 171 (Cont.) adapter Element Attributes Attribute name Type string Default Description The name of the adapter definition. (This name is normally the name of the adapter specified in the binding configuration. If this name differs from the name in the binding configuration, the binding entry must include a definition element set to the name specified here.) The operating system the application adapter runs under. 120 The maximum amount of time (in seconds) that a connection is kept in the connections pool before it is destroyed. The name of the schema used to define the adapter. The level of transaction support. Your options are:
operatingSystem poolingTimeout
string int
schemaName transactionLevelSupport
0PC: No transaction support 1PC: Simple (single phase) transactions 2PC: Distributed (two phase) transactions
<adapter name="calc" description="Attunity Connect Calc Schema" transactionLevelSupport="0PC" authenticationMechanism="basic-password" maxActiveConnections="0" maxIdleTimeout="600" maxRequestSize="32000">
17-3
Table 172 (Cont.) interaction Element Attributes Attribute mode Type enum Default Description The interaction mode. Available modes are:
sync-send-receive: The interaction sends a request and expects to receive a response. sync-send: The interaction sends a request and does not expect to receive a response. sync-receive: The interaction expects to receive a response. async-send-receive: The interaction sends a request and expects to receive a response that are divorced from the current interaction. async-send: The interaction sends a request that is divorced from the current interaction. This mode is used with events, to identify an event request.
string string
The name of the interaction. The name of the output record structure.
<interaction name="add" description="Add 2 numbers" mode="sync-send-receive" input="binput" output="output" /> <interaction name="display" description="Display msg in output stream" mode="sync-send-receive" input="inpmsg" output="outmsg" />
noAlignment name ObjectRef ParamCount program (z/OS only) transaction (z/OS only) transid (z/OS only)
Example 174
<record name="binput"> <field name="p1" type="int" /> <field name="p2" type="int" /> </record> <record name="output"> <field name="result" type="int" /> </record> <record name="inpmsg"> <field name="m" type="string" nativeType="string" length="512" /> </record> <record name="outmsg"> <field name="m" type="string" nativeType="string" length="512" /> </record>
17-5
Defining Hierarchies
The variant record element can be used to define a hierarchical structure. The hierarchical definition includes a record definition for the child. The parent record includes a field record with the type name that is used to define the child.
Example 175 Variant Record
<record name="parent"> <field name="f1" type="child" /> <field name="f2" type="int" /> </record> <record name="child"> <field name="c1" type="int" /> <field name="c2" type="string" nativeType="string" length="20" /> <field name="c3" type="string" nativeType="string" length="20" /> </record>
The XML used to access the adapter, must use the same structure as specified in the interaction definition.
Different nuances of the same data. Different usage of the same physical area in the buffer.
This section describes the common use cases of variants and how they are represented in the variant syntax. There are two types of variant:
<record name="VAR1"> <field name="VAR_0" type="VAR1__VAR_0" /> </record> <variant name="VAR1__VAR_0"> <field name="UNNAMED_CASE_1" type="VAR1__VAR_0__UNNAMED_CASE_1" /> <field name="PARTCD" type="VAR1__VAR_0__PARTCD" /> </variant> <record name="VAR1__VAR_0__UNNAMED_CASE_1">| <field name="PARTNUM" type="string"
nativeType="string" size="10" /> </record> <record name="VAR1__VAR_0__PARTCD"> <field name="DEPTCODE" type="string" nativeType="string" size="2" /> <field name="SUPPLYCODE" type="string" nativeType="string" size="3" /> <field name="PARTCODE" type="string" nativeType="string" size="5" /> </record>
<record name="ORDER"> <field name="RECTYPE" type="string" nativeType="string" size="1" /> <field name="VAR_1" type="ORDER__VAR_1" /> </record> <variant name="ORDER__VAR_1" selector="RECTYPE"> <field name="ORDER_HEADER" type="ORDER__VAR_1__ORDER_HEADER" case="H"/> <field name="ORDER_DETAILS" type="ORDER__VAR_1__ORDER_DETAILS" case="D"/> </variant> <record name="ORDER__VAR_1__ORDER_HEADER"> <field name="ORDER_DATE" type="string" nativeType="numstr_u" size="8" /> <field name="CUST_ID" type="string" nativeType="numstr_u" size="9" /> </record> <record name="ORDER__VAR_1__ORDER_DETAILS"> <field name="PART_NO" type="string" nativeType="numstr_u" size="9" /> <field name="QUANTITY" type="int" nativeType="uint4" size="4" /> </record>
17-7
Table 175 (Cont.) field Element Attributes Attribute COMtype Type enum Description (Used with the COM adapter) Specifies the field's data type as recognized by COM, using explicit COM enumeration values (for details, see COM Adapter (Windows Only). Runtime value holding the actual number occurrences in the array. A field can be specified as a counter field. The default value for the field. The default value for an integer is zero (0) and for a string NULL. Specifying a default value means that the field can be omitted from the input XML. Note: If a field isnt nullable, when using the database adapter and a default value is not supplied, an error occurs. filter length int Filtering of extraneous, unwanted metadata. This attribute is for internal use only. The size of the field including a null terminator, when the data type supports null termination (such as the cstring data type). (Used with the LegacyPlug adapter) The method by which the field is passed or received by the procedure (either byValue or byReference). When a parameter is used for both input and output, the mechanism must be the same for both the input and the output. For outer-level (non-nested) parameters, structure parameters (for the structure itself, and not structure members), and variant parameters, the default value is byReference. name nativeType string string The name of the field. The Attunity Connect data type for the field. Refer to Managing Metadata for a list of all supported data types. Note: When the type value is string, the nativeType value must also be specified as string. offset paramnum int int An absolute offset for the field in a record. (Used with the LegacyPlug adapter) The procedure argument number. 0 indicates the value is a return value. 1 indicates the value is the first argument, and so on. If paramNum is specified at the record level, it cannot be specified for any of the record members (at the field level). precision private reference required int boolean boolean boolean The float data type precision. Used in conjunction with scale (see below). The value is hidden in the response. Used with array (see above), to identify a pointer. A value is mandatory for this field.
counter
int
defult
string
mechanism
string
Table 175 (Cont.) field Element Attributes Attribute scale size type Type int int string Description The float data type scale. Used in conjunction with precision (see above). The size of the field. The data type of the field. The following are valid:
Binary Boolean Byte Date Double Enum Float Int Long Numeric[(p[,s])] Short String (When the type value is string, the nativeType value must also be specified as string) Time Timestamp
usage
string
(Used with the COM adapter) Explains what the COM adapter is about to do with this field:
InstanceTag: Names an object instance. Property: Handled as a property. Parameter: The field value should be passed as a parameter to/from a method. RetVal: The field will hold a methods return value.
value
string
Example 178
field Element
17-9
Part III
Attunity Stream
This part contains the following topics:
What is the Attunity Stream CDC Solution Implementing a Change Data Capture Solution SQL-Based CDC Methodologies Creating a CDC with the Solution Perspective
18
What is the Attunity Stream CDC Solution
This section includes the following topics:
CDC Solution Overview The Attunity Stream CDC Architecture What Can Be Captured?
Capture changes to data in real-time or near-real-time for applications that demand zero latency and require the most up-to-date data. Real-time data capture guarantees that a change event is immediately available at the consumer. Near-real-time data capture involves a configurable delay before a change is available at the consumer. Using a near-real-time configuration, when there is significant capture activity, events are reported immediately. However, after the system has been idle, it may take a few seconds for the events to start flowing again.
Enable consumers of changed data to receive changes quickly, either by asking for the changes in high-frequencies (such as every few seconds), or by sending them the changes as soon as they are identified. The consumer application periodically requests changes, receiving each time a batch of records that represent all the changes that were captured since the last request cycle. Change delivery requests can be done in low or high frequencies, for example, every 15 seconds or a set number of times a day. The extracted changes are exposed to enable the consumer application to seamlessly access the change records using standard interfaces like ODBC and JDBC or XML and JCA.
Using the Attunity Stream CDC solution enables ETL (extract, transform, and load) processes to run without bringing the site computer systems down. CDC enables the
movement of only changes to data while the operational systems are running, without the need for a downtime window. The CDC architecture consists of the following components:
CDC agents, which are located on the same computer as the changes to be captured. Each agent is customized for the specific data source on the specific platform. A CDC agent provides access to the journal (or logstream), to read the journal for specific table changes. The agent maintains the last position read in the journal (the stream position or context) and starts at this point the next time it polls the journal. The context is stored in the repository where the agent adapter definition is stored. The adapter definition includes a single primary interaction which is used to access the appropriate journal and includes the list of tables to monitor for changes.
Note:
In addition to this interaction, secondary interactions are defined during runtime, based on the table metadata of each table specified as part of the change data capture solution.
Depending on the agent, transactions are supported. If transactions are not used, then auto-commit is used.
A CDC staging area: Changes are stored in a staging area, enabling a single scan of a journal to extract the details of changes to more than one table and to also enable filtering of the changes. A committed change filter is currently available and a redundant change filter (hot-spot optimization) is planned. Both of these filters are described in Tracking Changes - Auditing. The staging area is described in more detail in The Staging Area. CDC data sources, to enable access to the changes using industry standards such as ODBC and JDBC. A CDC data source uses Attunity metadata and holds metadata for tables marked for change data capture. The CDC data source points to either the CDC agent or the staging area to enable getting the changes, as events, using ODBC or JDBC. Additionally, the CDC data source converts the data types in the table with changes to be captured to standard ODBC data types.
An audit of the changes that are captured. The audit is stored on disk and changes captured by both the CDC agent and written to the staging area are recorded.
Once a CDC solution has been defined, the changes can be pushed to the consumer, using a standard Attunity Connect event router. Setting up and using an event router is described in Attunity Connect Reference.
When a staging area is used, the change data capture agent reads the journal and channels requested changes from the journal to the staging area. The change data capture agent resides on the same machine as the data source with changed data to be captured. The staging area can reside on any machine. If the consumer application is SQL-based, a change data capture data source is available to access the relevant changes written to the staging area. The change data capture data source can reside on any machine. A context is stored both for the staging area and the agent which mark the last point where changes were captured. For details about the context, refer to The Staging Area.
Figure 182 Change Data Capture when a Staging Area is not used
When a staging area is not used, the change data capture agent reads the journal and channels requested changes from the journal either to a JCA or XML-based consumer application or, if the consumer application is SQL-based, to a change data capture data
source that is made available to access the relevant changes. The change data capture agent resides on the same machine as the data source with changed data to be captured. The change data capture data source can reside on any machine. A context is stored for the agent. For details about the context, refer to The Staging Area.
When changes to data in more than one table needs to be captured. When transactions are used. The changed data is not written to the change queue until the transaction is committed. Thus, if the transaction fails, there is no overhead of having to back out any processing done with the steps in the failed transaction. When repositioning the stream position (resetting the context) is planned to be performed often.
The staging area is cleared by default every 48 hours. All events that have been in the staging area for more than 48 hours are deleted.
To capture before images, the journal must be set up to include before images, as described for each type of journal.
None: Indicates no auditing is performed. Summary (Statistics): The total number of records retrieved from the change queue and system and error messages are reported. In addition, header information about each record captured, such as the type of operation and the table name, is reported.
Note:
Details of the header information is provided in the CDC agent specific chapters.
Detailed: The total number of changes retrieved are reported, along with system and error messages. In addition, header information and record information about each record captured is reported. The audit entries can be viewed in Attunity Studio Runtime Manager perspective in the Event monitor. Entries include a direction as follows: Entries from the CDC agent: The audit entries show what data changes were extracted from the agent by the consumer application. Entries from the staging area: The audit entries show what data changes were extracted from the staging area by the consumer application and what entries were written to the staging area by the agent.
Security Considerations
In general, Attunity Stream relies on the security mechanisms implemented at a site. For example, on az/OS system using RACF to manage security, the security rules implemented in RACF are also applied to Attunity Stream CDC. Additionally, you can specify as part of the CDC setup who can access the CDC agent and staging area to extract changed data and who can write changed data to the staging area.
DB2 Journal CDC on z/OS systems: The change data capture agent monitors both the archived and active DB2 journals and captures changes made to specific tables, which are written to these journals. Since transaction information is also stored,
What is the Attunity Stream CDC Solution 18-5
the committed change filter can be used to ensure that only committed changes are captured. For details of the committed change filter, refer to Tracking Changes Auditing.
DB2 Journal CDC on OS/400 platforms: The change data capture agent monitors a DB2 database journal and captures changes made to specific tables, which are written to this journal. Since transaction information is also stored, the committed change filter can be used to ensure that only committed changes are captured. For details of the committed change filter, refer to Tracking Changes - Auditing. DISAM on Windows platforms: The change capture agent monitors a journal for changes in DISAM tables and captures changes made to specific tables, which are written to this journal. This solution can only be used when the DISAM data is updated using Attunity Connect and not when updated directly by another program. IMS on z/OS systems: The change capture agent monitors a system log for changes in IMS/DB tables and captures changes made to specific tables, which are written to the logstream. Oracle on Windows and UNIX platforms: The change data capture agent monitors Oracle REDO log files for changes in Oracle tables from Oracle version 9iR2. The CDC solution polls the Oracle Logminer with its archive mode to capture changes. The staging area must be used when capturing Oracle data changes. VSAM-Batch on z/OS systems: The change data capture agent monitors a system log for changes in VSAM tables. Transactions are handled at the program level of the program. If a program fails, a decision to rollback must be made independently of the VSAM-batch change data capture agent. VSAM-CICS on z/OS systems: The change data capture agent monitors a CICS logstream for changes in VSAM tables. When transaction information is not available, rolled-back transactions appear as a set of backed-out changes, applied to the data. Query-based CDC on all Attunity server platforms: A generic change capture agent that enables the capture of changes in any of the data sources supported by Attunity Connect. The query-based agent only captures changes based on changes to a specific field in the table. An initial value is specified for the field as the starting change data capture context. The query-based agent does not include the ability to specify a staging area, nor to reset the context.
19
Implementing a Change Data Capture Solution
This section contains the following topics:
Overview CDC System Architecture Setting up AIS to Create a Change Data Capture CDC Adapter Definition CDC Streams Transaction Support Troubleshooting
Overview
The CDC solution lets you identify changes to data. This is referred to as consuming changes. The consumed changes are reported in a special log file. With CDC, the data is consumed in real time, that is at exactly the time the INSERT, UPDATE, or DELETE operations occur in the source tables. Changes are stored in change tables. Attunity Stream uses CDC (Change Data Capture) agents to consume changes to data that they display when needed. The following agents are supported:
VSAM Under CICS CDC (on z/OS) VSAM Batch CDC (z/OS Platforms) IMS/DB CDC on z/OS Platforms Adabas CDC on z/OS Platforms Adabas CDC on UNIX Platforms Adabas CDC for OpenVMS DB2 CDC (z/OS) DB2 CDC (OS/400 Platforms) Enscribe CDC (HP NonStop Platforms) Microsoft SQL Server CDC Oracle CDC (on UNIX and Windows Platforms) Query-Based CDC Agent (for work tables)
Install the System Components in the proper locations. See Installing System Components for an explanation on what to install and the locations for installing the components.
2. 3.
Apply the license. Use Attunity Studio to apply the license to the machines defined in your system. Configure the Change Data Capture solution. Use the Solution perspective in the Attunity Studio to add a new CDC solution and define its configuration properties. This automatically configures all the necessary components for the Change Data Capture, including the data source driver and CDC agent. See Creating a CDC with the Solution Perspective for more information.
See Configuring the System for Change Data Captures (Using Studio) for additional information.
AIS on the backend. The backend of the system is where your data is stored. In an CDC solution, you consume changes from data sources such as Oracle, to create a log with the change data information. This is where your CDC agent resides. You must install the full (thick) version of AIS on the backend. For information on how to install AIS, see the Installation Guide for the platform you are working with. Data Source: The data source that you are working with is installed with AIS. For more information, see the installation guide for the platform you are working on. Attunity Studio: Attunity Studio can be installed on any Windows computer in your system. Attunity Studio provides a graphic interface for configuring the components in your system. For information on installing Attunity Studio, see the installation guide or the platform you are working on.
Machines: You must configure the machines used in the system. Make sure to configure the machine where your backend application and application adapter reside. For information on how to add and configure machines, see Setting up Machines. You can also test the machine connection in Attunity Studio. User Profiles: You must set up the users in your system. Setting up users is for security purposes. You can specify which users have access to various machines. For information on setting up user profiles, see User Profiles and Managing a User Profile in Attunity Studio.
CDC Agents: You need to set up the CDC agent that you want to use. Attunity Studio lets you set up a CDC agent by Creating a CDC with the Solution Perspective. This lets you use Attunity Studio to manually set up your own CDC. Data Sources: If you create the CDC agent manually, you need to include the data source that your CDC agents supports. To set up your data source, you must: Prepare to use the data source by Adding Data Sources to Attunity Studio. Make sure that your data source is responding correctly by carrying out the procedures in Testing a Data Source. For non-relational data sources, you must define the metadata. Data source metadata defines the table structure for your data source. All metadata is imported from relevant input files (such as COBOL copybooks) and maintained using the Attunity Studio Design perspective Metadata tab. For more information on setting up data sources, see Data Sources and the data source Reference section for the adapter you are using.
Note:
Attunity metadata is independent of its origin. Therefore, any changes made to the source metadata (for example, the COBOL copybook) is not indicated in the Attunity metadata.
A new binding for the change data capture components on the machine where the data source with changes to be captured resides. CDC components are defined under this new binding, which is named name of project_ag, if the agent and the staging are are on different machines. If the agent and staging area are on the same machine, bindig is called name of project_router. A CDC agent, which is defined as an adapter under the CDC binding and named name of project_ag. A CDC data source, which is on the same machine as the CDC agent. This data source is called name of project. A staging area. This includes a binding and a data soruce. Both are called name of project_sa.The staging area is defined on the machine where the CDC changes are stored. A CDC router. This includes a binding, a data source, and an adapter. The binding and the adapter are called name of project_router and the data source is called name of project_sa. The router data source is a copy of the staging area s data source. For each of the bindings defined in the CDC Solution, a workspace with the same name is defined.
When using the CDC solution, the built-in flattening mechanism enables the following:
A view for the parent table records in the non-relational structure. This view does not include reference to the related child-arrays. A view for each child array that includes a unique key from the parent table and an array row number. This enables adding further columns from the parent table to the virtual array view.
This figure shows the three platforms used to deploy a CDC solution. These platforms are:
Database Platform: The database platform is where the database and the agent run. This platform can be any platform supported by AIS. The database platform is, in many cases, also a legacy application platform. This means that processing overhead on this platform should be minimized. Staging Area Platform: The staging area platform is where the change tables are hosted. This platform also hosts the SQL based change router, which enters data into the change tables. This platform can be any Windows or UNIX platform.
ETL Platform: The ETL platform is where the ETL tool runs. This platform can be any platform supported by AIS as well as any platform that can run any of AIS thin clients (such as any standard Java platform). The ETL platform may be the same as the Staging Area platform depending on the ETL tool resource requirements. If the platform is strong enough, placing both the staging area and the ETL tool on the same platform can reduce network utilization and improve throughput.
The figure above shows the adapter metadata as viewed in Attunity Studio. This shows the interactions only. You can view the schema by Using the Attunity XML Utility. The following figure shows how to configure the XML utility to return the full definition including the schema.
Figure 193 XML Utility Metadata Button
Interactions Schema
Interactions
The following are the outbound interactions in the CDC agent metadata:
getEvents: Gets the CDC events from the agent. setStreamPosition: Moves the stream position back to a specified position to re-read events from that point.
The following are the inbound interactions in the CDC agent metadata. These events are not callable by a client application.
eventStream table-name
Note:
The schema records of these interactions are important for client apps because they describe the metadata of the change events.
Schema
The following are the schema elements in the CDC agent metadata:
header: This accompanies all events. It is the same for a specific CDC agent. A list of header fields is included in the CDC agent reference sections. For more information, see the Overview for a list of the CDC agents. eventStream: An implicit union of all CDC event types. This includes all tables plus transaction events. *table-name* - A record for each table including all its fields.
CDC Streams
A Change Data Capture tracks or consumes changes in a data source using streams. A stream is a point in a data bases change log that is used as a point of reference by the CDC agent. Each time you begin to start a Change Data Capture, a new stream, with a unique name is automatically created. You can have as many concurrent streams as necessary. The place where the changes are currently being consumed is called the stream position. The stream position is automatically saved in the data base. You can filter a stream to consume for selected tables in the data base or for all of the tables. The figure below shows the CDC Stream.
The following are the parts of the CDC stream in the figure above.
Data Source: The native data source where you are consuming changes. For example, Adabas. Change Logger: This is the native tool that logs changes for a data source. Change Source: This is the data source log. It contains various information depending on the data source and the log configuration. This part has a different name depending on the data source you are working with. For example, for Adabas this is called the PLOG, for DB2 it is called a journal, and for Oracle it is called REDO logs. For more information, see the Overview for a list of the CDC agents. Change Capture Agent: This is the Attunity CDC Agent. The agent consumes the changes from the Change Source and outputs them into a standard XML format.
Transaction Support
CDC agents that support transactions can eliminate uncommitted changes from the stream service Most CDC agents support transactions. The reference section for each CDC agent indicates whether the agent supports transactions. The following CDC agents support transactions:
DB2 and DB2/400 VSAM Batch Adabas (all Adabas agents) Oracle Enscribe SQL/MP
When a CDC agent handles a transaction it reads the change record and then:
If the record is from a new transaction it creates an in memory transaction record cache for Txn-ID If the record is a DML record, then it is added to the appropriate transaction record cache by the Txn-ID If there was a Rollback, it deletes the Txn-ID transaction cache If there was a Commit, it distributes the Txn-ID transaction records to the various change files It the transactions is idled for too long it is timed out This is written to a special Txn-ID.txe file
Troubleshooting
If changes are not written to the journal or other native Change Source, make sure that the journal and system (such as CICS) file definitions match (for example, the same logstream number in CICS is used in the journal). To check that changes are written in the journal 1. From the Windows Start menu, point to Programs, Attunity and then Server Utilities, then click XML Utility. The XML Utility is displayed.
2. 3. 4.
Select the relevant server, workspace and CDC agent adapter. Click Events to open the Events listener. Click Start Events in the Events listener. You can specify the event name and qualify it with an application name to provide a unique starting point for the change events. Update a table with data to be captured (for example, using NAV_UTIL execute).
5.
The captured event is displayed in the XML Utility Events listener window. If changes are written to the journal, set the Attunity server environment properties driverTrace and acxTrace in the debug section for the CDC binding. Make changes to the data source and analyze the resulting standard Attunity server logs.
20
SQL-Based CDC Methodologies
This section contains the following topics:
Overview Configuration Parameters SQL Access to Change Events Reading the Change Tables Referential Integrity Considerations Monitoring the Change Data Capture Error Handling subscribeAgentLog Configuration Properties Performance Considerations Capacity Planning Applying Metadata Changes Migration from XML-based CDC
Overview
When using ETL (Extract Transform and Load) tools such as Informatica Power Center, Ascential Data Stage, BO Data Integrator, Microsoft SSIS and others, SQL based CDC can be used to retrieve incremental source table changes and apply them to the target tables. An SQL-based Change Event Router is used to read changes off a CDC agent and write these events into multiple change files (implemented as DISAM files). The following diagram shows the components related to SQL-based Change Event Router.
The SQL-based CDC Change Router components is displayed in the following figure:
Figure 201 SQL-based Change Router Components
Database platform: This is where the database and agent run. It can be any platform supported by AIS. The database platform is, in many cases, also a legacy application platform, which means that processing overhead on this platform should be minimized. Staging area platform: This is where the Change Table (Change File) are hosted. This platform also hosts the SQL-based Change Router which enters data into the change tables. It can be any Windows or UNIX platform. ETL platform: This is where the ETL tool runs. It can be any platform supported by AIS, as well as any platform that can run any of AIS thin clients (e.g., any standard Java platform). The ETL platform may be the same as the Staging Area platform, this depends on the ETL tool resource requirements. In general, if the platform is strong enough, then placing both the staging area and the ETL tool on the same platform can reduce network utilization and improve throughput.
Components
This section describes the various system components.
CDC Agent
The task of the CDC agent is to read the database logs (or other change source), and to transform them into a format that is easy to process. The agent does not initiate any process on its own. It serves requests for change events from various clients. In the case of SQL-based CDC, the agents client is the SQL-based Change Router. The agent represents the changes as a stream of change events with a stream position (also known as context) pointing to the next change event to be retrieved.
On the first call in a specific application context, the agent uses the initial stream position that is specified in the agent configuration. The recommended setting for the initial stream position is Now which indicates that the first retrieval by an application will determine the time after which changes are captured.
Uses memory aggressively to cache change events before they are committed. When dealing with very large transactions, the change router writes uncommitted transaction data to a temporary sequential file that is read back and processed if Commit is given, or discarded on Rollback. Maintains a stream position against the agent to keep track on processed change events.
Configuration Parameters
The following table describes the SQL-based change event router configuration parameters:
Table 201 Parameter cdcDatasource eliminateUncommittedChan ges Event Router Configuration Parameters Type string Boolean false Default Description The Change Data Source. A local DISAM data source. When set to true, only committed change records are moved to the Change Table (Change File). If false, all change records are moved to the change tables (in which case, memory usage is minimal) hence the change table may contain rolled back data. For most agents, following the RI considerations (see Referential Integrity Considerations) results in rolled-back changes eliminated naturally by means of compensating change records generated by the agent in case of a rollback. Consult the respective CDC agent documentation for details. Indicates how long change records are kept in change tables within the Staging Area. After the indicated time, change records are deleted. You can set a value between 0 and 50000. A value of 0 means that the records are never deleted. A value of 1 indicates that the records are kept for one hour. logLevel enum none One of none, api, internalCalls, info, or debug.
eventExpirationHours
int
48
Table 201 (Cont.) Event Router Configuration Parameters Parameter maxDeletedEventsInBatch Type int Default 500 Description Controls how many expired change records are delete in a single pass. This number may need to be lowered in some rare cases in order to reduce latency when a large number of change events is continuously being received. Controls the number of physical files opened by the event router. Specifies how much memory can be stored in memory per transaction before it is off-loaded to disk. This number should be higher than the average transaction size so that the slower-than-memory disk is not used too often. Specifies how much memory in total can be used for storing active transactions (ones that have not yet committed or rolled back). Connection information to the CDC agent.
maxOpenfiles maxTransactionMemory
200 1000
maxStagingMemory
int (in Kb) Structure: string string string int int int boolean string
100000
sourceEventQueue
30 250 15 false Specifies the directory where the staging area change files will be stored. This directory also stores off-loaded transactions as well as timed-out transactions and error files. 3600 Specifies how long can a transaction be active without getting new events. This parameter should be set according to the corresponding setting of the captured database. In particular, this setting must not be lower than the databases transaction time-out setting as this may lead to the loss of transactions.
stagingDirectory
transactionTimeout
useType subscribeAgentLog
enum Boolean
sqlBbased This parameter must be set to this value. Cdc False When set to true, the change router writes the contents of the CDC agents log into its own log. Do not set this property to true if the logLevel property is set to debug because the large amount of information that is sent in this mode will cause performance delays.
Change Tables
For every table in the Change Data Source, a change table by the same name is maintained by Attunity Stream in a change data source (DIFDB, a DISAM data source). A change table contains the original table columns, and CDC header columns, as listed in the following table:
Table 202 Change Event Common Header Columns Structure Data Type string string operation string Description The original change timestamp. The name of the table. beforeImage | update | insert | delete. The source specific transaction ID of the change. For auto-commit operations, it may be empty (or 0). The change record stream position in the Staging Area. The column is defined as primary unique index. It is a 32-bytes string with the following structure: <yyyymmdd>T<hhmmss>.<nnnn><cccccc> Where:
context
string (32)
<yyyymmdd>T<hhmmss> is the commit processing timestamp as generated in the staging area when starting to process the Commit event. <nnnn> is a unique number to differentiate between transactions committed during the same second (up to 99,999 are assumed). <cccccc> is a counter for the change events in the transaction making every stream position unique (up to 9,999,999 are assumed).
agent_context
string (64)
The original change record stream position from the agent (non-numeric). This column is defined as alternate, descending unique index. It is used for the following:
1. 2.
It ensures that a change event does not appear more than once in the change table. It allows scanning of a change table backwards, peeking easily for the last N change events. When working with complex records, multiple records may result from a single back-end change record. This column enables the user to associate these records with the single change record.
3.
In addition to the common CDC header columns, each change table may maintain auxiliary CDC header fields specific to the source data source CDC agent. Including these fields in the Change Table (Change File) is optional. The following table lists auxiliary CDC header fields for different data source types:
Table 203 Data Source DB2 Oracle VSAM CICS VSAM CICS DB400 DB400 DB400 DB400 DB400 DB400 DB400 DB400 DB400 DB400 DB400 DB400 DB400 DB400 DB400 VSAM Batch VSAM Batch VSAM Batch VSAM Batch VSAM Batch VSAM Batch ADABAS MF ADABAS MF ADABAS MF ADABAS MF ADABAS MF ADABAS MF ADABAS MF ADABAS MF ADABAS MF ADABAS MF
Agent Specific Auxiliary Header Columns Data Type string (16) string (24) string (4) string (8) string (1) string (2) string (10) string (10) string (6) string (10) string (10) string (10) string (10) string (10) string (10) string (8) int4 int4 string (1) string (8) string (8) string (8) string (8) string (8) string int4 string (8) string (2) string (2) string (16) string (56) uint2 uint4 int4 uint4 Description Original change record block address in the database log. Row ID of affected record. Terminal ID of the transaction that made the change. Task ID of the transaction that made the change.
Column Name RBA rowID terminalID taskID journalCode entryType jobName userName jobNumber programName fileName libraryName memberName RRN userProfile systemName referentialConstraint trigger objectNameIndicator jobName programName userName stepName procedureStepName programStartTimeStamp sequence BEFZ indicator recordType userID generalUniqueID fileNumber RABN imageType workRabChain
This tables primary unique key is the concatenation of application_name + table_name. The use of this table is not mandatory but it is part of the recommended use pattern of SQL-based CDC. The STREAM_POSITIONS table is created with the following definition (where filename is changed into an actual path):
<?xml version='1.0' encoding='UTF-8'?> <navobj> <table name='STREAM_POSITIONS' fileName='<staging-directory-path>STREAM_POSITIONS' organization='index'> <fields> <field name='application_name' datatype='string' size='64'/> <field name='table_name' datatype='string' size='64'/> <field name='context' datatype='string' size='32'/> </fields> <keys> <key name='Key0' size='128' unique='true'> <segments> <segment name='application_name'/> <segment name='table_name'/> </segments> </key> </keys> </table> </navobj>
The general preference would be for this table to be stored inside the target database which will allow committing changes along with an update of the stream position under the same transaction. However, with local access, using a STREAM_POSITIONS table in the Change Data Source introduces very limited risk.
Note:
Some ETL tools stop consuming changes when an EOF (End of File) is returned. To force an ETL to contiguously consume changes, see Reading Change Tables Continuously.
The kind of SQL query that the tools use have the following structure:
select * from change-table where context > :last-stream-position
where last-stream-position parameter represent the last processed event as maintained by the ETL tool for the specific change table and application. While some ETL tools support this stream position concept internally, with others this requires manual implementation. This chapter specifies the manual steps required for reading change logs, leaving tool-specific information for tools-specific documents. The general procedure for consuming change events for change table T in application A using SQL is outlined below. Note that this procedure does not address Referential Integrity constraints (see Referential Integrity Considerations). To create a stream position This is a one-time setup step aimed to create a stream position record for T + A in the STREAM_POSITIONS table. The following SQL statement creates that record:
insert into STREAM_POSITIONS values (A, T, ); 2.
1.
This step is where change data is actually read. It occurs on each ETL round.
select n.* from T t, STREAM_POSITIONS sp where sp.application_name = 'A' and sp.table_name = 'T' and n.context > sp.context order by n.context;;
This query retrieves change records starting from just after the last handled change record. Obviously, n.* can be replaced with an explicit list of columns. What is important is that the context column must be selected as this is the change record stream position which is required for the next step. This step occurs at the end of each ETL round once all change records were retrieved and processed. Lets assume that the value of the context column of the last change record was C. This value needs to be stored back into the STREAM_POSITION table for the next ETL round. This is done with:
update STREAM_POSITIONS set context=C where application_name A and table_name = T;
This value can be stored more frequently during the ETL process as needed. The general guideline is that once change record data has been committed to the target database, the stream position should be updated as well.
In this case, the parameter value is the last value returned in the previous ETL run and is stored in an auxiliary table of a target database. This approach works well for polling cycles that are not too close (up to several times an hour). However, in cases where a near real-time SQL-based change capture is required, this approach is not adequate. The cost of starting an ETL run is often high. The cost is even greater if several change tables need to be monitored concurrently in near real time. To compensate for the higher costs a continuous CDC approach is used. In this case, a continuous query uses a special feature of the Attunity query processor that defines a query that (almost) never ends. Internally Attunity Stream polls the data by re-executing the query as needed but with the least possible overhead. For an ETL tool that uses a data access API such as ODBC, it just appears as if the query never ends. If no data is available, the ETL tool will just be blocked in a call to fetch the next row of data. When new data becomes available, the ETL continues receiving rows back from the fetch call. The continuous CDC approach requires one ETL to be continuously active for each consumed change table.
The parameter value in this statement is the last value returned in the previous ETL and stored in an auxiliary table of the target database. This is the same as the statement used for executing regular change queries as explained in Reading Change Tables Continuously. The only difference is that the CONTEXT column in this statement uses the alias '$$StreamPosition'. Once the query starts with an initial value for the parameter, the alias name instructs the query processor to read until the end of the data and then run the query again with the last CONTEXT value as the new parameter value.
Notes:
The Stream Position column must be the first column on the SELECT list, with the alias name '$$StreamPosition'. The matching stream position parameter must be the first parameter in the WHERE clause.
Continuous queries can be invoked from ODBC, JDBC and ADO.NET interfaces.
Note:
Using continuous queries under the ADO OLE DB interface may cause problems because of the OLE DB read-ahead behavior. In this case, when a query is made, more records than the ones requested are fetched. This causes the system to continue to wait for information that is not there because it was fetched early.
(empty): If the column value is empty, the query processor continues to return rows as they become available. Pause: The query processor pauses the continuous query until this value is changed. After a retry interval, the query is re-executed and the value of the Control Command column is checked again. Stop: The query processor stops running the continuous query and returns an EOF.
In this example, table T is the change table and STREAM_POSITIONS is the table used to record the last position processed in the previous ETL run. The STREAM_ POSITION Table contains a column named command that gets the alias name $$ControlCommand. The STREAM_POSITION table must contain a row for the application and table before running this query. To stop this query while it is running continuously, run the following query from a different session:
update STREAM_POSITIONS set command='Stop' where sp.application_name = 'A' and sp.table_name = 'T'
When you use a control command column, make sure that the:
The control command column is the second column in the SELECT list of the query, immediately following the stream position column. The condition sign used in the stream position column is > + (greater than or equal to). Do not use the > (greater than) sign. This is because when no rows are returned, the control command column is also not be returned. Note: If the change table is empty, there may be a problem stopping the continuous query.
The clause limit to 1000 rows is included. If the query returns very long number of rows without re-executing, it may take it very long to re-evaluate the control command column. By setting a limit on the number of rows returned for each query, the control command column value is re-evaluated more often. The value, 1000 rows, is used as an example. You can use a higher of lower number.
The control command value can come from another table, or it can be calculated. For example, you can set its value based on the time of day (for example, if may return a value of Pause between 2:00 PM and 4:00 PM). When a continuous query is used with a thin-client (JDBC or ADO.NET), the polling takes place on the server and it may take a long time before a response is returned to the client. The server keeps monitoring the client connection so if the client goes away, the server will automatically stop the continuous query at the next poll event.
Note:
Continuous queries are subject to normal query processing rules. Make sure that the SQL that is used returns the result in the order of the stream position column. A single-segment unique index on the column and an express sort condition is one way to ensure this without performance loss.
For more information on these properties, see Environment Properties, Query Processor.
This tables primary unique key is the concatenation of application_name + sync_name. The use of this table is not mandatory but it is part of the recommended use pattern of SQL-based CDC. The SYNC_POINTS table is created with the following definition (where filename is changed into an actual path):
<?xml version='1.0' encoding='UTF-8'?> <navobj>
20-11
<table name='SYNC_POINTS' fileName='<staging-directory-path>SYNC_POINTS' organization='index'> <fields> <field name='application_name' datatype='string' size='64'/> <field name='sync_name' datatype='string' size='64'/> <field name='context' datatype='string' size='32'/> </fields> <keys> <key name='Key0' size='128' unique='true'> <segments> <segment name='application_name'/> <segment name='sync_name'/> </segments> </key> </keys> </table> </navobj>
The following procedure describes how to ensure RI is regained at the end of a group of ETL rounds. It is an extension of the procedure described earlier for consuming change records. Here we assume that tables T1, T2 and T3 are related with RI constraints and that A is the application we are working under. To create a stream position 1. This is a one-time setup step aimed to create a stream position record for T [1/2/3] + A in the STREAM_POSITIONS table. The following SQL statement creates that record:
insert into STREAM_POSITIONS values (A, T1, ); insert into STREAM_POSITIONS values (A, T2, ); insert into STREAM_POSITIONS values (A, T3, ); 2.
This step is performed at the beginning of a group of ETL rounds processing (that is before starting to process change events for T1, T2 and T3). The goal here is to get a shared sync point for retrieval of T1, T2 and T3. This is done by sampling the context column of the SERVICE_CONTEXT table. This value is the stream position of the last change record in the most recently committed transaction. This is done as follows:
insert into SYNC_POINTS select 'A' application_name, 'T123' sync_name, context from SERVICE_ CONTEXT;
Here, T123 is the name chosen for the synchronization [points of tables T1, T2, and T3.
3.
This step is where change data is actually read. It occurs on each ETL round.
select n.* from T t, STREAM_POSITIONS sp, SYNC_POINTS sy where sp.application_name = 'A' and sp.table_name = 'T' and sy.application_name = sp.application_name and sy.sync_name = 'T123' and n.context > sp.context and n.context <= sy.context order by n.context;
Note that n.context <= sy.context is used because the context represents a change record to be processed and processing should include the change record associated with sy.context, too.
This query retrieves change records starting from just after the last handled change record but stopping at a common sync point. n.* can be replaced with an explicit list of columns, however it is important that the context column must be selected as this is the change record stream position which is required for the next step. This step occurs at the end of each ETL round once all change records were retrieved and processed for a table Ti. Lets assume that the value of the context column of the last change record was C. This value needs to be stored back into the STREAM_POSITION table for the next ETL round. This is done with:
update STREAM_POSITIONS set context=C where application_name A and table_ name = Ti;
This value can be stored more frequently during the ETL process as needed. The general guideline is that once change record data has been committed to the target database, the stream position should be updated as well.
agent_context
string (64)
If there are pending uncommitted transactions, the agent_context value is the agent context of the first event of the oldest uncommitted transaction. If there are no pending uncommitted transactions the agent context of the last event of the most recently committed transaction, prefixed withnext and indicates that on recovery, the next event after that is to be processed.
The staging area maintains an internal agent_context that is more advanced than the one stored in the SERVICE_ CONTEXT table. The staging area uses memory to speed up change processing and when stopped it may revert back to an earlier agent context. The amount of extra work depends on the existence of long-running transactions.
20-13
Table 206 (Cont.) SERVICE_CONTEXT Table Structure Column Name start_time status sub_status status_message status_time completed_transactions active_transactions timedout_transactions Data Type Description timestamp The time when the staging area started. string (16) string (64) string (80) Staging area status. For more information, see Monitoring the Status. A second level status. For more information, see Monitoring the Status. Message that is returned that describes the staging area status.
timestamp The time that the status is updated. uint4 uint4 uint4 Number of transactions processed. Number of transactions in progress (in memory, not yet committed or rolled back). Number of transactions that have timed out (were in memory for too long, declared to have timed out and written to a file). Number of rolled back transactions. Number of change events written out. Number of change events deleted from Change Table (Change File). Accumulated size in bytes of change records written. Current number of physically opened files by the staging area. Current number of logically opened files by the staging area. Amount of memory currently allocated for staging. A two-digit identifier with the same value as the nodeID config property when in multi-router mode. In regular mode, this column has no value. The time of the last transaction. The version number for the router. As of AIS Version 5.0, the value for this column is 1. This value is increased when major updates are added to the router. Total number of errors reported. The number of transactions reduced to disc. The number of compensation records captured.
rolledback_transactions uint4 processed_change_events uint4 deleted_change_events bytes_written opened_files opened_files_virtual memory_usage node_id uint4 uint4 uint4 uint4 uint4 uint4
The CONTROL table is also used by the event router to persist its state for purpose of recovery. This table must not be modified by the users.
Description
Reads the change The router is connected to the CDC agent and is processing or waiting for the change events events. Writes the change events Reduces the timed-out transaction to disc Deletes any expired change events
Idle
Waits for new change The routers agent reaches the end of its events journal and does not have any new change events. Detailed error text This indicates that the change router operation involving writing to disk failed. The most common reason is not enough disk space. Other reasons such as permissions, wrong path, or locking can also cause this. The prefix component (Agent/Router) indicates where the error happened. The error in the sub_state column identifies the error.
error
router.discWriteError
component.error This error type occurs in agents and routers. The following are the errors that are returned for this error type:
xmlError requestError noActiveConnection resourceLimit noSuchResource authenticationError noSuchInteraction noSuchConnection notImplemented autogenRejected resourceNotAvailable authorizationError configurationError noSuchStream temporarilyUnavailable dataError interventionRequired Detailed error text This indicates that the change router operation with the CDC agent failed and cannot be restored.
Disconnected
20-15
Table 207 (Cont.) SERVICE_CONTEXT Status States State Paused Sub State N/A State Details Description Operator manually paused the change router using the sqlrtr_pause control reset. This indicates that the change router is not Down message (orderly shutdown or running. abort message)
Down
N/A
Error Handling
Errors can occur in a Change Data Capture in either the source machine or the staging area. Most of these errors are passive and handled automatically. The change router is an active component that reads the change events and applies them to a target. AIS lets the user determine how to handle errors that occur in the change router. The following topics describe error handing for a CDC.
Skip: The change router tries to skip a the event which caused the router error. Retry: The change router to tries to process the event again, This option lets you execute the event again after manually fixing the error. Pause: This pauses the change router when it does not pull changes from the agent. Resume: This resumes the change router if it is paused.
CONTROL_TABLE
The CONTROL_TABLE is part of the staging area. This table lets you control the router by inserting control operations that are processed by the router. The router checks the table for new records. When a new record is entered the router reads it and then deletes the record. It then tries to execute the requested action if it is valid. For a description of the possible actions, see Determining the Change Router Error Behavior.
For details on the above actions, see Determining the Change Router Error Behavior. node_id string (2) A two-digit identifier with the same value as the nodeID config property when in multi-router mode. In regular mode, this column has no value.
Parameter: subscribeAgentLog Type: Boolean Default: False Description: When set to true, the change router writes the contents of the CDC agents log into its own log. Do not set this property to true if the logLevel property is set to debug because the large amount of information that is sent in this mode will cause performance delays.
Performance Considerations
The SQL-based approach can reasonably scale in the following cases:
There are many captures tables but changes are processed in rounds with sufficient time apart. There is a relatively low number of captured tables but changes are processed in near-real-time manner.
This approach does not fit very well with many captured tables together with frequent change processing because that means constantly running SQL queries, consuming much resources whether or not there are any change records. The following sections provide further information about the various tuning parameters which may affect performance.
Memory Parameters
The maxTransactionMemory and maxStagingMemory parameters control the amount of memory used by the Change Router. As the change router processes transactions, it tries to keep them in memory in order to obtain the best performance. If a transaction is too large to be kept in memory (as determined in the maxTransactionMemory parameter), the transaction is reduced to a special disk file by the name <txn-id>.txn and from that point on, additional change events for this transaction are appended directly to this file.
SQL-Based CDC Methodologies 20-17
Since disk I/O is rather slow, it is recommended to set the maxTransactionMemory parameter to a high enough value that can be supported on the machine; The program must have sufficient system quota to allocate the memory and use it efficiently (without page-fault thrashing). To estimate the value for this parameter, you need to consider the biggest transaction likely to occur and calculate approximately the total size of all updated records (including some header overheads. For more information, see Capacity Planning). Very big transactions may occur as a result of a simple batch-update SQL query and although typical production applications do not invoke such transaction, they may still occur (for example, in month-end processing). The maxTransactionMemory parameter deals with a single transaction. Since there could be multiple transactions active concurrently, there is another parametermaxStagingMemory. This parameter determines how much memory all active transactions may consume together. This parameter value must be greater than the value of maxTransactionMemory, so that typical small transactions could still fit in memory while big transactions are reduced to disk files.
Latency
The Change Router is responsible for deleting a change record whose retention period had expired. When events are being deleted, the change router does not move data from the CDC agent to the change files. This may increase the latency of change event handling. Impact of deleting old events on latency can be reduced by setting the maxDeletedEventsInBatch parameter to a lower value. Another way to reduce the impact of deleting old events is by setting the retention period wisely. For example, if the change activity peaks between 08:00 and 16:00, then setting eventExpirationHours to 3 days plus 12 hours (that is 84 hours) would result in deletion activity matching the peak occurring between 20:00 and 04:00.
Capacity Planning
This section describes various planning considerations, and includes the following topics:
Storage
The main consideration for storage requirements is the amount of changes that needs to be cached in the Staging Area. The parameters are as follows:
D: How many days back does the staging area keeps records before deleting them (retention period). N: The number of captured tables. Ri: The size (in bytes) of a single record of the captured table (i=1, ..., N). Fi: The average number of changes per day for the captured table (i=1, ..., N).
H: The header size (in bytes). This is 225 bytes for the common header fields. It should be adjusted based on the developed solution. For example, some header fields may be omitted while some agent-specific header fields may be added. IH: The index overhead. Approximately 125 bytes.
Where SUM has taken over i=1, ..., N The Change Router also uses temporary storage for processing transactions. Storage is used when an entire transaction does not fit in the memory allocated for the change router. The parameters are as follows:
CT: The number of concurrently running large transactions. MS: The maximum record size. MR: The maximum number of records in a large transaction.
Change records are kept in the Staging Area for a specified length of time, counted from the time the changes were added to the staging area. This behavior does not consider the original time the change occurred. For this reason, if CDC processing was halted for say, 4 days, then when processing resumes, 4 days worth of changes needs to be stored in the Change Table (Change File). This needs to be considered when allocating storage, since if the retention period is shorter, say 2 days, then recovering from a 4 days pause requires twice the normal storage. The minimal storage estimate S can be NC calculated as follows:
S=St+Sp
Memory
Memory requirement is made up of the following parts:
Memory usage of the event router: This value is mostly affected by the maxStagingMemory event router setting. The default value for this is 100,000Kb (=100MB) and it can be increased or reduced as needed. Using a higher number will increase the throughput if the total size of active transactions reaches that number (active transaction are the concurrently running transactions that have not yet committed or rolled back).
Memory usage of the SQL servers: Here the evaluation should be made experimentally by monitoring a running system and checking how much memory is added per additional server.
For capacity planning, the sum of these two parts should be used.
Network
Network capacity and latency is reflected in the throughput of the Change Router as well as in the throughput of the SQL consumers (if they are located on a remote machine). The parameters are as follows:
SQL-Based CDC Methodologies 20-19
AR: The average record size, in bytes. RF: The desired number of change events per second.
A very rough estimate of network capacity NC can be calculated with the following formula:
NC=AR*RF*8*(0.5+1) (Bits per second)
Another related setting is the maximum number of events to request in a single round-trip to the CDC agent. The parameter is the config/sourceEventQueue/maxEventsAsBlock change router configuration parameter. It affects the request sizes and requires updating the environment/comm/comMaxXmlSize and the environment/comm/comMaxXmlInMemory parameters. The setting of these XML parameters can be calculated as follows:
MEAB: The maximum events as block (as defined in the configuration. The default is to request 250 events). MAXR: The maximum size of a single XML change record (including the header part). To get a rough estimate on the maximum size, one can take the original change record data+the header size and double it (taking into account the binary XML overhead in the extreme case).
comMaxXmlInMemory=comMaxXmlSize=MEAB*MAXR*1.2
Processing
Processing power is not usually the limiting factor in the work of the Change Router and the Staging Area. Actual CPU consumption depends on the rate of the change events processed as well as on concurrent ETL clients reading the Change Table (Change File). It is recommended to monitor CPU consumption under typical load to verify that the system functions within its optimal load.
At design-time, while building a solution, metadata may change either because of mapping changes or because of changes in the applications that work with the data. This use case has the following characteristics: Design-time change may occur frequently (less so towards the end of the development cycle). Changes may be small (such as adding a new column to a table). Change data can typically be deleted without any implications.
At production, replacing one production version with another (typically a new production version of the entire customer project).
This use case has the following characteristics: Production changes are relatively rare. Production changes typically contain changes to many components because production is typically held to apply changes. The preference is to wait as possible and consolidate changes into a single upgrade process. Production change data needs to be handled, and data loss is not an option.
Since applying metadata changes in production requires one to first applying these changes in the design environment, we will introduce the design changes first and then add the production requirements.
Open the relevant CDC solution in Attunity Studio. Disable the solution. Access Solution, Implementation, and then Metadata to add or remove a captured table. To apply a metadata change in a captured table, remove and immediately add back the updated table name from the list. Delete the physical DISAM change files associated with the updated or deleted captured tables. Delete the SERVICE_CONTEXT file so that changes start flowing immediately. Re-enable the solution.
4. 5. 6.
Perform a backup. Make the application go quiet so that no new events are added. Run the ETL processes until all changes were processed off all Change Table (Change File). Disable the solution workspaces. Delete the physical DISAM change files associated with the updated or deleted captured tables. Deploy the updated solution to the production environment. Re-enable the solution.
20-21
Support for the XML mode of operation is also supported for easy use with XML-based integration. The following table summarizes some features that enhance the SQL-based CDC abilities:
Table 209 Topic Attunity Stream SQL-Based CDC Features Regular Behavior Enhanced SQL Behavior
Change Table (Change File) Each captured table had a change table The same change tables are available, associated with it. The table column with the following changes: included the original captured table Two new indexes for direct access. columns plus CDC header fields. A few more CDC header fields. The change tables are now real tables based on DISAM files on disk; one file per captured table. The XML to binary conversion is done once so the DISAM files store data in an efficient binary format. Stream position management and guaranteed delivery Stream position was maintained at the agent or the Staging Area. Stream position was automatically advanced on commit or on read when auto-commit mode was used. This approach did not offer guaranteed change delivery because one might have read a change event and failed to process it (or might have failed to get it due to network failure). Friendly stream position The stream position was an opaque entity with the only quality of being strictly incremental (that is, each new change record got a higher stream position, alphabetically). Stream position is no longer maintained by the agent or the staging area. Instead, an easy to use stream position is exposed as an index column of a change table (the context column).
the stream position looks like a timestamp; it actually is the timestamp of when the event was written out to the change file (in universal coordinated time, not local time, to avoid daylight saving time conflicts). Since the ETL tool had to maintain stream position anyway for guaranteed change delivery, there is no extra work needed in the new approach.
Guaranteed change delivery To guarantee change delivery, the ETL tool needed to maintain a stream position and to reestablish it when retrieving using the SetStreamPosition stored procedure. Referential Integrity
To attain referential integrity at the end An alternative, SQL based approach of a mapping session, one had to use was developed (see Referential the SetSyncPoint procedure. Integrity Considerations). Change events in their original XML form, were stored in a one big index file (about 5 indices) whether they were committed or not. They were later extracted by a non-primary index scan (to achieve transaction order). Change data was stored, in most cases, as a CLOB attached to a change entry. Very little use was made of available system memory. Memory is used intensively to improve performance. Change records are transformed into their binary representation (just like one a COBOL copybook gives) and are kept in memory until commit time when they are written to different change files, one per captured table. Rolled-back events simply vanish without incurring any I/O overheads.
Performance
Table 209 (Cont.) Attunity Stream SQL-Based CDC Features Topic Scalability and robustness Regular Behavior A single server process (with a single thread) did all the reading from the CDC agent and the servicing of SQL to consumers. This resulted in poor scalability of the event consumption and the applied process. With more than a few consumers, time-outs would be quite likely. Enhanced SQL Behavior A single dedicated server process reads change records off the CDC agent and distributes the (after transactions are committed) to separate change files. A separate workspace with any number of servers is defined for consuming change records using a normal DISAM data source. This results in very good scalability and use of system resources.
Another disadvantage of the single server process is that a communication Having separated the Change Router hang (mostly due to network issues) and the change file access servers also could bring the entire solution to a means that problems communicating stand still. with the CDC agent no longer impact the reading process. One can even take down the agent and the change router server for updates, leaving the Change Table (Change File) accessible. Monitoring The monitoring system had a significant impact on the system in terms of resource utilization (and the more change events, bigger was the impact). Very little could be told about what the system is doing at any given moment or over time.
While the existing monitoring system is still there, now a special SERVICE_ CONTEXT table is provided in the same data source as the change file. Querying this table provides insight into what the change router is doing, as well as important counters. Having this information exposed simply via SQL makes it easy to integrate 3rd party management solutions. The service context does not introduce significant overhead and it can be sampled as needed to produce running statistics. Timed-out transactions are detected and written out to special .txt files. A special SERVICE_CONTEXT file counts timed-out transactions, enabling to easily detect timed-out transactions.
Transaction time-outs
Recreate the solution in Attunity Studio V4.8. Establish new capacity planning as explained above. Eliminate calls to the GetStreamPosition procedure. Instead, retrieve the last known handled position from the STREAM_POSITION table. Eliminate calls to the SetStreamPosition procedure. Instead, use the SQL WHERE clause with the context field greater than the last known handled position from the STREAM_POSITIONS table. Establish and use the STREAM_POSITIONS and SYNC_POINTS as explained in this document.
5.
These steps are general guidelines. Actual changes depend on the kind of solution implemented with Attunity Stream V4.6.
20-23
21
Creating a CDC with the Solution Perspective
The Solution Perspective lets you create a Change Data Capture (CDC) operation using a series of interactive guides. This section contains the following topics:
Using the Solution Perspective Getting Started Guide Project Guide Troubleshooting
From the menu bar, click Window| Open Perspective|Solution. Click the Perspective button on the perspective toolbar and select Solution from the list. The Solution perspective opens with the Getting Started view available on the left of the workbench.
21-1
configure the parts of the project or solution you are creating. In most cases you can click on each link in the order they appear. The solution perspective guides display the following symbols in front of a link to show you what tasks should be done, and what tasks were completed.
Triangle: This indicates that there are subtasks associated with this link. When you click the link, the list expands to display the subtasks. Asterisk (*): This indicates that you should click that link and carry out the tasks and any subtasks presented. If more than one link has an asterisk, you can carry out the marked tasks in any order. Check mark (): This indicates that the tasks for this link and any sublink are complete. You can double click the link to edit the configuration at any time. Exclamation mark (!): This indicates a potential validation error.
This view has two sections. The upper section has links to open or create an AIS project or to open an existing project to edit or to finish configuring the project. These options are:
The section below the line has the link, Opening Recent Projects. This lets you access existing projects quickly.
To create a new project 1. In the Getting Started Guide guide, click the Create new project link. The Create new project screen opens.
2.
In the Project name field, enter a name for your project. The types of projects available are listed in the left pane just below.
3.
Select Change Data Capture. The CDC options available are presented in the right pane.
4.
Select a CDC type from the right pane. Your options are:
ADD-ADABAS (Mainframe): Capture data changes from ADD-ADABAS Mainframe database, with or without the use of a staging area, from any type of client. ADD-ADABAS (Unix): Capture data changes from ADD-ADABAS Unix database, with or without the use of a staging area, from any type of client. ADD-ADABAS (OpenVMS): Capture data changes from ADD-ADABAS OpenVMS database, with or without the use of a staging area, from any type of client. ADABAS Mainframe: Capture data changes from ADABAS Mainframe database, with or without the use of a staging area, from any type of client. ADABAS Unix: Capture data changes from ADABAS Unix database, with or without the use of a staging area, from any type of client.
21-3
ADABAS OpenVMS: Capture data changes from ADABAS OpenVMS database, with or without the use of a staging area, from any type of client. DB2 (Mainframe): Capture data changes from DB2 Mainframe database, with or without the use of a staging area, from any type of client. DB400: Capture data changes from DB400 database, with or without the use of a staging area, from any type of client. DISAM: Capture data changes from DISAM database, with or without the use of a staging area, from any type of client. Enscribe: Capture data changes from Enscribe database, with or without the use of a staging area, from any type of client. IMS-DBCTL: Capture data changes from IMS-DBCTL database, with or without the use of a staging area, from any type of client. IMS-DBDC: Capture data changes from IMS-DBDC database, with or without the use of a staging area, from any type of client. IMS-DLI: Capture data changes from IMS-DLI database, with or without the use of a staging area, from any type of client. MS SQL Server: Capture data changes from MS SQL Server database, with the use of a staging area, from any type of client. Oracle: Capture data changes from an Oracle database, with or without the use of a staging area, from any type of client. SQL/MP: Capture data changes from SQL/MP database, with or without the use of a staging area, from any type of client. VSAM-Batch: Capture data changes from VSAM-Batch database, with or without the use of a staging area, from any type of client. VSAMCICS: Capture data changes from VSAM-CICS database, with or without the use of a staging area, from any type of client. VSAM for OpenVMS: Capture data changes from VSAM database running on the OpenVMS platform, with or without the use of a staging area, from any type of client.
5.
From the Project drop-down list, select the required project. Click Finish. The Project Guide with the information for that project is displayed.
Project Guide
The Project Guide has three parts:
Design Wizard
The Design Wizard lets you review and modify all the basic settings of your project. With CDC Solutions, you have the flexibility of customizing your project map according to different configurations based on parameters that are entered in the wizards screens.
21-5
To configure basic Solution settings 1. Click the Design link. The Design Wizard opens. Use this wizard to enter the basic settings for your project.
Note:
The wizard screens are divided into sections. Some sections provide information only and other sections let you to enter information about the project. If you do not see any information or fields for entering information, click the triangle next to the section name to expand the section.
2. 3.
In the Data Source Name field, enter a name for your data source. In the Client Type combo box, select a client type. Your options are:
BizTalk Generic SQL: SQL clients ETL: All ETL tools that work using ODBC Generic XML: Client applications that consume changes through XML SQL Over Change Queue: SQL clients using the ADD-Queue mechanism Web Logic
Note:
This selection affects the number of machines actually employed and whether or not the use of stream service is enabled as a result.
4. 5.
To use the staging area, select Use staging area. For most CDC agents, this is the default and cannot be changed. Click Next. The Design Wizards second screen is displayed. In this step you configure the machines used in your solution. Enter the information for the following machines:
Server Machine: The machine where AIS is installed Client Machine: The local machine Staging Area Machine: The machine where the staging area is located. This is only available if you selected the staging area check box in the first screen.
6.
Enter or select a name from the drop-down list each of the above machines.
Note:
You can enter the same name for any of the machines. This allows you to use more or fewer machines for your Solution.
7. 8.
Select the platform that is running on each machine from the drop-down list. The platforms available depend on the original data source type. Click Finish. The wizard closes.
Note: Studio adds a check mark () next to the Design link to indicate that you completed this part of the configuration. However, you can click this link at any time to make changes.
21-7
Implementation Guide
The Implementation Guide is done after you complete the Design Wizard. Note that the Implementation link has an asterisk (*) next to it to indicate that you need to enter configuration information in this section. To begin the Implementation Guide Click Implement. The Implementation Guide lets you customize the parameters of your CDC Solution machines, as they were defined in the Design Wizard. The tasks in the Implementation Guide are grouped under the configuration categories below, which can be expanded or collapsed with a mouse click. The order and grouping in which they are presented may change according to Design Wizard settings and/or data source type. For example, when selecting an Oracle CDC project, after setting the configurations in the Design Wizard, the Implementation Guide is displayed as follows:
Figure 216 Implementation Guide
The actual tasks performed in the Implementation Guide vary according to data source and number of machines employed. You can set up the implementation in any order. Click on any available link with an asterisk (*). Below is a complete list of tasks.
Machine
The Machine link lets you set the IP address/host name and the port of the CDC or server machine. To configure server IP address/host name and port 1. Click the Machine link. The machine definition screen is displayed:
Figure 217 Machine Definition
2.
Enter the server machines numeric IP address. Click the Browse button and select the host machine from the ones presented, then click Finish.
21-9
Note:
The machine you enter must be compatible with the platform designated in the Design Wizard (Configure Solution Machines) screen.
3.
4. 5.
If you want to connect with user authentication, enter a user name and password, with confirmation, in the Authentication Information area. Select the Connect via NAT with a fixed IP address checkbox if you are using Network Access Translation and want to always used a fixed IP address for this machine. For more information, see Firewall Support.
6.
Click OK.
Data Source
The Data Source link lets you define your data source. The information you enter depends on the type of CDC agent you are setting up. It can be a file name, or a path with a file name, or a full connect string, depending on the data source type. To enter the data source Enter the data source information requested, and click Next. For details on the format to be entered, see the chapter for the CDC agent you are using. For a list of agents, see the CDC Agents Reference.
Metadata
The Metadata link lets you define the metadata used for the data sources that are file systems or non-relational databases. You must first select a metadata source. After you select the source, then you must carry out one or more operations described below.
Note:
The Select Metadata Source link has an asterisk (*) next to it to indicate that you must carry out this operation first.
To select the metadata source 1. Click the Metadata link. The Create metadata definitions view is displayed.
2. 3.
Click the Select Metadata Source link. Select one of the following:
Create new metadata definitions Copy from existing metadata Import metadata from external source
4.
Click Finish. The screen closes. Click an available link (with an asterisk (*) next to it):
To create new metadata definitions To copy definitions from existing metadata To import metadata from an external source
To create new metadata definitions 1. Click the Customize Metadata link. The customize metadata screen is displayed.
Figure 219 Customize Metadata
2. 3.
Right-click in the fields under Customize Metadata, and select Add. Enter the table name in the field presented, and click OK.
Note: You may have validation errors in the tables created, which you can correct by the end of the procedure.
21-11
4.
Right-click the table created and select Field Manipulation. The Field Manipulation screen is displayed.
Figure 2110
Field Manipulation
5. 6. 7.
Right-click in the upper pane and select Field|Add|Field. Enter the name of the field in the screen provided, and click OK. Default values are entered for the table. To manipulate table information or the fields in the table, right-click the table and choose the option you want. The following options are available:
Add table: Add a table. Field manipulation: Access the field manipulation window to customize the field definitions. Rename: Rename a table name. This option is used especially when more than one table is generated from the COBOL with the same name. Set data location: Set the physical location of the data file for the table. Set table attributes: Set table attributes. XSL manipulation: You specify an XSL transformation or JDOM document that is used to transform the table definition.
The Validation tab in the bottom half of the window displays information about what you must do to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location).
8. 9.
Correct any remaining validation errors. Click Finish to generate the metadata.
To copy definitions from existing metadata 1. Select Copy from existing metadata, and click OK.
2.
Click the Copy Existing Metadata Source link. The Copy Existing Metadata Source screen is displayed showing your local machine and with metadata compatible with the data source selected.
Figure 2111
3. 4. 5.
From the sources in the left pane, expand the list until you see the tables from which you want to copy metadata. Using the arrow keys, bring the required tables into the right pane. Once you have selected all the desired tables, click Finish.
When you import metadata from an external source, the data source type has an impact on which metadata files you can import. IMS imports Cobol, DBD and PSB files. All other ISAM CDC projects import Cobol files for metadata.
1. 2.
Select Import metadata from external source, and click OK. Click the Import Metadata Source link. The New Import screen is displayed.
21-13
Figure 2112
New Import
3. 4.
In the Import name field, you must enter a name for the import operation. Select an import type from the options available in the drop-down list. The items in the drop-down list will be different according to data source type selected. See the Data Source Reference for a list of available data sources.
5.
Click Finish.
To import metadata from COBOL files 1. Click the Add button to select COBOL copybook files.
2.
The Add Resource window opens, which lets you select files from the local machine or FTP the files from another machine.
Add Resource Screen
Figure 2113
3. 4.
If the files are on another machine, right-click My FTP Sites and choose Add. Set the FTP data connection by entering the server name where the DBD files reside and enter a valid username and password to access the machine, unless using anonymous access.
After you access the machine, you can browse and transfer files required to generate the metadata. You access the machine using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory.
5. 6.
Select the files to import and click Finish to start the transfer. Repeat the procedure for the COBOL copybooks.
Note:
You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks. The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns with a COBOL copybook that ignores the first six columns. In this case, repeat the import.
Or, for IMS data sources, click Add in the import wizard to add a PSB file.
7.
Figure 2114
8. 9.
21-15
Figure 2115
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type. Compiler source: The compiler vendor. Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP is for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Prefix nested columns: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity metadata, is replaced with an underscore. Case sensitive: Indicates whether to consider case sensitivity. Find: Searches for the specified value. Replace with: Replaces the value specified for Find with the value specified here.
Ignore after column 72: Ignore columns 73 to 80 in the DBD files. Ignore first 6 columns: Ignore the first six columns in the DBD files. Ignore labels: Ignore labels in the DBD files.
Ignore first 6 columns: Ignore the first six columns in the PSB files.
The import manager identifies the names of the segments in the DBD files that will be imported as tables.
11. Select the tables that you want to access (and receive the Attunity metadata) and
then click Next. The Import Manipulation window is displayed. In this window, do the following:
Resolve table names, where tables with the same name are generated from different COBOL copybooks specified during the import. Specify the physical location for the data. Specify table attributes. Manipulate the fields generated from the COBOL, as follows: * * * * * * * * Merging sequential fields into one for simple fields. Resolving variants by either marking a selector field or specifying that only one case of the variant is relevant. Adding, deleting, hiding, or renaming fields. Changing a data type. Setting a field size and scale. Changing the order of the fields. Setting a field as nullable. Selecting a counter field for array for fields with dimensions (arrays). You can select the counter for the array from a list of potential fields.
21-17
Setting columnwise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension. Creating arrays and setting the array dimension.
Import Manipulation Screen
Figure 2117
Note:
The Validation tab in the bottom half of the window displays potential validation problems in the current metadata definition.
12. To manipulate table information or the fields in the table, right-click the table and
Add table: Add a table. Field manipulation: Access the Fields manipulation window to customize the field definitions. Rename: Rename a table name. This option is used especially when more than one table is generated from the COBOL with the same name. Set data location: Set the physical location of the data file for the table. Set table attributes: Set the table attributes. XSL manipulation: Specify an XSL transformation or JDOM document that is used to transform the table definition.
13. Click Next to generate the metadata. The final window lets you import the
metadata to the machine where the data source is located or leave the generated metadata on the Attunity Studio machine, to be imported later.
14. Specify that you want to transfer the metadata to the machine where the data
source is located and click Finish. The metadata is imported to the machine where the data source is located.
CDC Service
The CDC Service wizard depends on the CDC agent you are working with. This section describes the two standard screens in the wizard. For additional information required, see the chapter for the specific agent you are working with. For a list of agents, see CDC Agents Reference. To configure the CDC Service 1. Click the CDC Service link. The CDC Define change capture starting point dialog box opens.
2.
In this dialog box, select one of the following to determine the Change Capture starting point:
All changes recorded in the journal. On first access to the CDC agent (immediately when a staging area is used, otherwise when a client first requests changes). Changes recorded in journal after a specific time.
If you choose the third option, you need to select the specific time by clicking the Set time button and selecting the time from the calendar that appears.
Figure 2118 Define Time Stamp and Set Specific Time
3. 4.
If you want, select include a capture of before-image records. Click Next to open the CDC agents configuration screen. In this screen you configure the CDC Service properties for the agent you are using. See CDC Agents Reference.
21-19
5.
Figure 2119
6.
7.
Click Finish.
Figure 2120
Select Scenario
2.
Application Server using connection pooling Stand-alone applications that connect and disconnect frequently Applications that require long connections, such as reporting programs and bulk extractors
3.
Click Next. The next screen that appears depends on the type of connection you just selected.
4.
21-21
Figure 2121
5. 6. 7.
In the first field, enter the amount of time you want to wait for a new connection to be established (in seconds). In the second field, assuming a fast connection, the amount of time to wait for a response (in seconds) Click Next.
Site Security
Figure 2122
8. 9.
Enter the operating system account (user name) used to start server instances. Select allow anonymous users to connect via this workspace, if you want to allow this option. workspace, or select the users/groups that you want to have exclusive access.
10. Enter the permissions for the workspace. You can allow all users to access the 11. Select access server instances via specific ports, if you want to allow this options.
If this option is cleared, the defaults are used. If you select this option, indicate the from port and to port and make sure that you reserve these ports in the TCP/IP system settings.
12. Click Next.
Stream Service
The Stream Service configures the following:
Null filtering is currently unsupported. Filtering empty values is supported. Space values are truncated and are handled as empty values.
21-23
To configure the Stream Service 1. Click the Stream Service link. The Stream Service wizard opens.
Figure 2124 Staging Area
Note:
This screen will only appear if you selected the inclusion of a staging area in your solution.
2. 3.
Select Eliminate uncommitted changes to eliminate uncommitted changes from your CDC project. Select the use secured connection checkbox to configure the staging area to have a secured connection to the server. This is available only if you logged into the server using user name and password authentication. Set the event expiration time in hours. Under File Locations, click the Browse buttons to select the location of the changed files, and temporary staging files, if necessary. Click Next. You are prompted to select the tables to participate in the filtering process.
4. 5. 6.
Figure 2125
Select Tables
Tables
Arrow keys
Left pane
Right pane
7. 8.
Click the required tables in the left pane and move them to the right pane using the arrow keys. Click Next. You are prompted to select the relevant columns within the tables selected above from which to receive changes.
21-25
Figure 2126
Column checkboxes
Table checkboxes
9.
Table headers will appear grouped together in a separate table at the beginning of the list. You can also request the receipt of changes in the headers columns.
You are prompted to indicate the types of changes you want to receive in the tables and which columns to display.
Figure 2127
Filter Selection
Actions
11. Select the actions from which you want to receive change information. Your
options are:
12. Under the Changed Columns Filter column, select the columns for which you
If you do not select them, you will receive notification of all changes. If you select only one, you will receive change information only if the field selected undergoes a change. If you select more than one, but not all, then you will receive change information only if any or all of the selected fields undergo a change
21-27
13. To filter content from within a given column, under the Content Filter column,
double-click the relevant column, and then once again on the ellipsis button that appears. The Content Filter screen is displayed.
Figure 2128 Content Filter
Filter type
Select In for events to be returned where the relevant column value equals the values you specify (if a column is NULL, it is not captured). Select Not In for events to be returned where the column value is not in the values you specify (if the column is NULL, it is captured). Select Between for when the column value is between the two values you specify (if a column is NULL, it is not captured).
15. Click Add in the lower-left corner of the Content Filter screen.
Note:
If you select more than one condition, you will receive the change information as long as one of the conditions is true.
If you selected In/Not In, continue with step17. If you selected Between, continue with step 20.
Figure 2129
18. Enter a value for events to be returned where the relevant column value appears
(or does not appear) in that value. To filter empty values () for the Not In filter type, leave this filed blank.
19. Repeat steps 17 and 18 as many times as necessary, and then proceed to step 22. 20. Click Add in the Add items to list screen.
21. Enter values for events to be returned where the column value is between the two
You are prompted to select the level of auditing when receiving changes.
21-29
Figure 2132
Audit Level
23. Select the required level of auditing when receiving changes. Your options are:
None: For no changes. Summary: For an audit that includes the total number of recorded delivered, as well as system and error messages. Headers: For an audit that includes the total number of records delivered, system and error messages, and the record headers for each captured record. Detailed: For an audit that includes the total number of records delivered, system and error messages, the record headers for each captured record, and the content of the records.
When you complete all the Implementation operations, a check mark () is displayed next to every link. Click Done to return to the Project Guide so you can begin the Deployment activities
Deployment Guide
After you complete the design and implementation guides, you are ready to deploy your project. The Deployment Guide has two sections:
Deployment Procedure: This section is used to deploy the project. Control: This section is used to activate or deactivate workspaces after the project is deployed and you are ready to consume changes. In this section, you can
deactivate the workspace anytime you want to suspend consumption of changes from the staging area.
Figure 2133 Ready to Deploy
To deploy the project 1. Click the Deploy link. The Deployment Procedure and Control open.
21-31
Figure 2134
2.
Click the Deploy link. Studio processes the naming information. This may take a few minutes. If there are naming collisions, you are prompted to allow Studio to resolve them.
Figure 2135
3.
Click Yes to resolve any naming collisions. The Deployment Guide is displayed.
Figure 2136
Deployment Guide
4.
If you are ready to deploy, click Finish. Otherwise, click Cancel and you can return to the Design Wizard and the Implementation Guide to modify the solution. If this project was deployed previously, you will be notified that re-deployment will override the previous instance.
Figure 2137
Notes:
When you redeploy a project where the metadata is changed, the Staging Area (SA) tables should be deleted so that no incorrect information is reported. When you redeploy a solution, the a new binding is created for the solution. The new binding is created with the default parameters only. Any temporary features that were added are lost.
5. 6.
21-33
The Deployment Summary is shown. It includes the ODBC Connection String Parameters and JDBC Connection String, as well as specific logger scripts to enable CDC capturing.
Figure 2138 Deployment Summary
CDC summary
Connection strings
Scripts
7. 8.
Cut and paste any information required from the Deployment Summary screen to your environment as necessary. If there is nothing wrong with your deployment results, click Finish. If you found problems, click Cancel and to return to the Design Wizard and the Implementation Guide to modify the solution. If you are redeploying a solution you must follow these directions to make sure that the context and agent_context fields of the SERVICE_CONTEXT table should be saved. Follow these directions to save the fields:
Note:
1. 2. 3. 4. 5. 6.
In the staging area data source run: select context, agent_context from SERVICE_CONTEXT; and save the returned values. Delete the SERVICE_CONTEXT table physical files. Redeploy the solution. Activate the router to create the SERVICE_CONTEXT table. Disable the router. In the staging area datasource run: insert into SERVICE_CONTEXT (context, agent_context) values('XXX', 'YYY'). This will Insert the saved values to the SERVICE_CONTEXT table. Activate the solution.
7.
To activate and deactivate workspaces To activate workspaces, click the Activate Workspaces link.
To deactivate workspaces, click the Deactivate Workspaces link. Over the course of the activation/deactivation, you may receive messages indicating that the daemon settings on one or more of the machines involved in your solution have changed. Click Yes to proceed.
Daemon Configuration Change
Figure 2139
Troubleshooting
When you deploy your project, any problems and/or messages appear in their respective views.
Figure 2140 Deployment Message View
To resolve deployment problems 1. Right-click the problem or message and select Go To. The point in the previous guides where the problem occurred is displayed.
2. 3.
Check the settings and make any changes required. Follow the procedure To deploy the project.
21-35
Part IV
Attunity Federate
This chapter contains the following topics:
22
What is Attunity Federate
This chapter has the following sections:
Overview
Attunity Federate provides Enterprise Information Integration (EII) across heterogeneous data sources. Using Attunity Federate, you can create single views of business information, making it easier for business users to access information in multiple data silos with virtual data models. You can use Attunity Federate to complement data warehouses with real-time access to operational data stores, and guarantee data integrity with distributed transaction management. Attunity Federate joins heterogeneous data sources to make them available as a virtual data layer. Attunity Federate uses distributed query optimization and processing engines that reside natively on enterprise data servers to provide superior performance, security, and transaction management. Attunity Federate leverages AIS adapters to access any data source in the enterprise. At the heart of the Attunity Federate solution is a data engine, supplied as part of the AIS. This shared, multi-platform engine manages access and updates across the IT infrastructure. It can also integrate information from disparate systems with a single request.
When the data engine receives and parses an SQL request, it first determines which data source is involved, where the data resides, and how the source handles data. The data engine determines how to carry out the process based on metadata that it retrieves from a local cache, from the Attunity repository, or dynamically from the backend data sources. Then, the data engine generates a query execution plan in the form of a tree. Whenever possible the data engine passes the entire request to the underlying data source. In this case, the engine translates between standard ANSI SQL 92 and the underlying databases SQL dialect. The data engine can also accept pass-through queries to nonstandard SQL functions supported by the target source. If a data source offers limited SQL capabilities, the data engine implements missing functions as needed. If the data source offers no SQL capabilities at all, the data engine breaks the request into simple retrieval operations that an indexed or sequential table can read. The data engine can also work with data via generic drivers (such as ODBC and OLE DB). In this case, it uses an external syntax definition to determine which queries or parts of queries the database can handle and which it will execute itself.
Query Optimizer
The data engine includes the query optimizer, that minimizes execution time and resource consumption. The query optimizer enhances the data engine's initial query execution plan based on the query structure, network structures, the target data sources capabilities and locations, and the statistical information available for each table. To maximize the efficiency of query execution, the query optimizer uses various caching and access techniques, including read-ahead, parallelism, and lookup-, hash-, and semi-joins. It flattens views, breaks out and propagates simple predicates down the tree, reorders joins, directs join strategies, selects indexes, and performs other related tasks. If the target data source is distributed across multiple machines, the data engine and query optimizer together generate a distributed execution plan that minimizes network traffic and round-trips.
JDBC Client Interface: Attunity provides a pure-Java Type-3 driver that supports J2EE JDBC (such as data sources, distributed transactions, hierarchical record sets, and connection pooling). The Attunity Connect JDBC interface is available on all platforms that support Java. ODBC Client Interface: The Attunity Connect ODBC interface enables organizations to use the API of choice for most popular client-server business
intelligence tools. The ODBC interface implements the ODBC 2.5 and ISO CLI standards, so that COBOL and other 3GL programs on any platform can call it. The Attunity Connect ODBC interface is available on all platforms running Attunity Connect
OLE DB (ADO) Client Interface: Attunity Connect provides an OLE DB/ADO interface that supports advanced features, including chapters, scrollability, and multi-threading. The OLE DB/ADO interface is compatible with all Microsoft tools and applications. This provider also functions as a database gateway for Microsoft SQL Server, allowing SQL Server users to access all data sources available via Attunity Connect. The Attunity Connect OLE DB/ADO interface is available on the Microsoft Windows platforms.
Segmented data sources: A number of data sources on different machines, all of which have the same metadata and functionality. Virtual data sources: A view containing selected tables from one or more data sources.
The segmented data source is used to create a federated database where all the participating data sources have identical metadata. The Virtual data source is used to create a federated database when the participating data sources have different metadata. Access to the following Attunity Connect data sources are available:
Table 221 Relational DB2 Data Source Informix Data Source AIS Data Sources Non-Relational Adabas Driver CIASAM Driver Generic Flat Files Driver ODBC Driver OLEDB-FS (Flat File System) Driver OLEDB-SQL (Relational) Driver Text-Delimited File Driver
Ingres II (Open Ingres) Data DBMS Driver (OpenVMS Source Only) Oracle Data Source Oracle RDB Data Source (OpenVMS Only) SQL/MP Data Source (HP NonStop Only) SQL Server Data Source (Windows Only) Sybase Data Source DISAM Drive Enscribe Driver (HP NonStop Only) IMS/DB Drivers (z/OS only) RMS Driver (OpenVMS Only) VSAM Under CICS and VSAM Drivers (z/OS Only)
Viewing, creating, modifying, and managing metadata for data sources, such as flat files, that require Attunity metadata, is performed via Attunity Connect, from within Attunity Studio.
Base Services
Attunity includes a suite of administration and development tools for system and database administration. IT staff can run most of these utilities remotely using the GUI interface or locally on the native machine using the command line interface.
Binding information, including the names of configured backend adapters and drivers and environment settings. Daemon definitions, to control client-server communication. User profiles, enabling single sign-on to multiple backend applications and data sources. Information used directly by Attunity Connect query processor (Attunity Connect procedures and views). An adapter definition for each adapter defined, which includes adapter interactions and input and output structures used by these interactions.
Metadata for the data source. Attunity metadata for non-relational data sources and for Attunity Connect procedures. Attunity metadata that is additional to the data sources native metadata (the extended metadata feature) and a snapshot of native metadata (the local copy feature).
Binding configurations. Client-server communication via the daemon listener. User profiles, enabling single sign-on to multiple backend applications and data sources. Metadata for both data sources and adapters. For all relational data sources and some non-relational data sources, Attunity Connect uses the native metadata. Otherwise, the metadata is specified to Attunity Connect
Administrators can use Attunity Studio during runtime to manage Attunity daemons and logging.
Daemons
A daemon runs on every machine running AIS. The daemons handle user authentication and authorization, connection allocation, and server process management. A fail-safe mechanism allows the specification of alternate daemons, which function as a standby for high availability.
Clients maintain caches of data and metadata which enable it to satisfy many requests locally without needing to go to the server. They also batch some commands in order to avoid unnecessary network traffic A client starts a corresponding session for this user on one or more servers on the first remote request by a user session. Each server session remains open until the client session terminates. In the case of systems using connection pooling (such as MTS or IIS), the client and server sessions may stay open indefinitely. In the event that server operations terminate (for example, someone restarts the server machine or communication is lost), the client automatically reestablishes the connection upon the next remote operation.
Processing mode, specifying multi-threaded/single-threaded operations, the number of processes, and server pools. Security settings for impersonation, authorized users, administrators, and encryption. Accessible adapters. Various operational parameters
Attunity also supports multi-version interoperability. IT teams can simultaneously install multiple versions of Attunity Server on all supported operating systems. As a result, organizations can begin to deploy new software versions in a staged update process, without interrupting the operations of previous versions. At the provider end of the system, Attunity servers act as agents that access, read, manipulate, and write to data sources and applications. Attunity servers accept commands from clients, call the corresponding local functions, and package and return the results to the clients.1 Server software, which includes the Attunity engines, drivers and adapters, resides on every Attunity machine. When a client requests a connection, the daemon allocates a server process to handle this connection, and refers the client to the allocated process. This may be a new process (dedicated to this client) or an already-started process. Further communication between the client session and the server process is direct and does not involve the daemon. The daemon is notified when the connection ends and the process is either killed or remains for use by another client. This kind of server model is very flexible. It accommodates different operating systems and data source requirements. Attunity supports several server models:
1
IA target data source can reside on another machine. In this case, the source is represented by an agent on the server using a third-party communications component such as Oracle Net Servers or Sybase CT-Lib, which is transparent to Attunity Connect
The multi-threaded model is effective when the data sources support multi-threading. Serialized multi-client server processes are useful for short requests and for data sources that allow more than one simultaneous client per process. The single-client-per-process model supports data sources that only handle one client per process and to maximize client isolation.
Server processes can be reused. Various server process pooling options allow organizations to tune the solution for different application and load requirements.
23
Using a Virtual Database
This chapter contains the following sections:
Virtual Database Overview Defining a Virtual Data Base Metadata Considerations Defining Tables Creating Synonyms Defining Stored Procedures Creating Views Using a Virtual Database
Presents a view to the user such that only selected tables from either one or more data sources are available, as if from a single data source. Limits the data available to a user to the tables and views that are needed by that user. Presents table names in a meaningful way, by defining the name as used by a data source with a name that has meaning in the application. Enables an application to view the tables in several data sources in a uniform manner, by presenting a consistent view of each table in the virtual database.
AIS provides a mechanism that enables the user to create and access a single virtual database. A virtual database consists of selected tables and views from other Attunity Connect data sources. To the calling application, a virtual database looks like a single database with a predefined set of tables and views. The calling application cannot access the underlying sources, which prevents access to other corporate data. A virtual database can also be used to provide more meaningful names for tables and views. Because the virtual database uses a Repository to maintain its definitions, native system constraints on file and table names do not apply. This feature is particularly useful for legacy back end databases whose table/record names are restricted by the naming conventions of the backend platforms (for example, the eight-character limit on HP NonStop computers).
Views
A virtual database can also include AIS stored procedures (An SQL statement or part of an SQL statement that can be included in other SQL statements).
In the Design perspective Configuration view, expand the Machine folder and then expand the machine where you want to define the virtual database. Expand the Bindings folder and then expand the binding where you want to define the virtual database. Right-click the Data sources folder and select New data source.
5. 6.
In the Name field, enter a name for the data source. In the Type field, select Virtual. If you do not need to enter the data location where the new tables for this virtual database reside, click Finish. To enter the data location, click Next. Enter the Data Location where the new tables for this virtual database reside. This is optional. Click Finish.
7.
Once a virtual database is defined in the Binding, you can define the tables, synonyms, views, and stored procedures in the virtual database.
Metadata Considerations
Metadata must be defined in Attunity Studio for each table, synonym, view and stored procedure. To define metadata for a virtual database In the Design perspective Configuration view, right-click the virtual database, and select Show Metadata View. The Metadata view opens with the virtual database displayed with Tables, Synonyms, Stored Procedures and Views under it.
Defining Tables
Tables can be defined and used as part of the virtual database. Normally it is recommended to create tables for storing administrative details about the virtual database. To define tables included in a virtual database 1. Open Attunity Studio.
2. 3.
In the Design Perspective Configuration view, expand the virtual database you are working with. Right-click the Tables folder under and select New Table The New tables wizard is displayed.
4. 5. 6.
Enter a name for the table. Click Finish. Create metadata for the table, including the columns and indexes for the table. For more information, see Working with Metadata in Attunity Studio.
Virtual tables are automatically created for arrays. These tables are displayed in lists of tables when building queries, such as in the Attunity Query Tool. For more information on how arrays are handled, see Handling Arrays.
Note:
Creating Synonyms
A synonym is an alias for a table or view. You can use the synonym name in place of any table or view name.
Note:
You cannot create a synonym in a single session after dropping a synonym with the same name.
A synonym can be used to implement a virtual data source by defining synonyms for the tables and views you want the virtual data source to make available To create a synonym for a table of view 1. Open Attunity Studio.
2. 3. 4. 5.
In the Design Perspective Metadata view, expand the virtual database you are working with. Right-click Synonyms and select New Synonym. The New Synonym wizard is displayed. Enter a name for the synonym. Enter a target data source. You can select Browse to open the Select Target dialog box. The Select Target dialog box displays all the data sources defined in the same binding as the virtual database. Expand the data source you are working with and select the table or view you want to assign the synonym to. Click OK to close the dialog box. Click Finish. The new synonym is displayed in the Configuration view.
6. 7. 8.
In the Design Perspective Metadata view, expand the virtual database you are working with. Right-click the Stored Procedures folder and select New Stored Procedure. The New Stored Procedure wizard is displayed.
4. 5. 6.
Enter a name that identifies the stored procedure. Select the query type. Select the table.
In the left side of the New Stored Procedure wizard, expand the data source where the table resides. Click the Tables tab on the right side of the screen. Select the table and click the right arrow to move the table to the select table tab on the right side.
Note:
You cannot include tables from any data source shortcuts listed in the binding. To include a table from a data source defined in the binding that resides on a different server, manually edit the SQL.
7.
On the left side of the screen, expand the data source and the table containing the column. Click the Columns tab on the right side of the screen. Select the column and click the right arrow to move the table to the select table tab on the right side of the screen.
Using a Virtual Database 23-5
8.
Join columns, if necessary. The Create Joint tables pane opens.if a column with the same name as a column from a different table is selected.
Expand the table and select the column you want to join. Click the right arrow to move the column to the right side of the screen or click Next to edit the join statement.
9.
Click the Where tab on the right side of the screen. Select the column and click the right arrow to move the table to the Where tab on the right side of the screen. Set the operator and value conditions as needed.
Click the Group tab on the right side of the screen. Select the columns to group and click the right arrow to move the table to the Group tab on the right side of the screen.
Click the Having tab on the right side of the screen. Select the column you want to filter and click the right arrow to move the table to the Having tab on the right side of the screen. Set the operator and value conditions as needed.
Click the Sort tab on the right side of the screen. Select the column whose query result you want to sort and click the right arrow to move the table to the Sort tab on the right side of the screen. Select the sorting order as either ascending or descending.
13. You can select Enable manual query editing to fine tune the query. 14. Click Finish.
The New Stored Procedure wizard is based on the Attunity Query Tool. For more detailed information on how to create the queries you want to save as stored procedures, see Attunity Query Tool.
Creating Views
Attunity Connect lets you define views for one or more Data Sources. Views created are read-only and can be used in a FROM clause of an SQL query, or wherever a subquery can be specified. A view is stored by default in the SYS data source. A view cannot accept parameters. To create a view In the Design Perspective Metadata view, expand the virtual database you are working with. Right-click the Views folder and select New View. The New View wizard is displayed.
1. 2.
3. 4.
In the left side of the New View screen, expand the data source where the table resides. Click the Tables tab on the right side of the screen. Select the table and click the right arrow to move the table to the select table tab on the right side of the screen.
Note:
You cannot include tables from any data source shortcuts listed in the binding. To include a table from a data source defined in the binding that resides on a different server, manually edit the SQL (using the Attunity Connect ds: table syntax).
5.
On the left side of the screen, expand the data source and the table containing the column. Click the Columns tab on the right side of the screen. Select the column and click the right arrow to move the table to the select table tab on the right side of the screen.
6.
The Create Joint tables pane opens.if a column with the same name as a column from a different table is selected.
Expand the table and select the column you want to join. Click the right arrow to move the column to the right side of the screen or click Next to edit the join statement.
7.
Click the Group tab on the right side of the screen. Select the columns to group and click the right arrow to move the table to the Group tab on the right side of the screen.
8.
Click the Having tab on the right side of the screen. Select the column you want to filter and click the right arrow to move the table to the Having tab on the right side of the screen. Set the operator and value conditions as needed.
9.
Click the Sort tab on the right side of the screen. Select the column whose query result you want to sort and click the right arrow to move the table to the Sort tab on the right side of the screen. Select the sorting order as either ascending or descending.
10. You can select Enable manual query editing to fine tune the query. 11. Click Finish.
The New Stored Procedure wizard is based on the Attunity Query Tool. For more detailed information on how to create the queries you want to save as stored procedures, see Attunity Query Tool.
At the Daemon level, by setting the Workspace database name field to the virtual database name in the WS Info. tab for the workspace used by the client At the connect string level, by setting the Database parameter in the connect string. For example: connection.Open "provider=AttunityConnect; binding=production;Database=vdb_name"
If the mode of operation is set using either of these methods, the client application has access only to the data included in the virtual database. That is, when an application connects to the virtual database, all the tables, views and stored procedures defined in the virtual database from other data sources are available as if they are part of the virtual database. Any data source related task that can be performed on a normal data source can also be performed on the virtual database. For example, the user can create a new table in the virtual database or create a new view using existing tables in the virtual database. The new views are stored in the repository of the virtual database they are not stored in any actual data source.
Note:
The user cannot create a view that includes data that is not part of the virtual database.
Stored procedures in a virtual database can be either procedures defined in Attunity Connect or procedures that originate in an actual data source. The stored procedures are stored in the repository for the virtual database and are used in the same way, without regard to the source of the stored procedure (Attunity Connect or a Data Source stored procedure).
24
Segmented Data Sources
This chapter has the following sections:
Overview Creating Segmented Data Sources Environmental Properties for Segmented Data Sources Using a Segmented Data Source
Overview
A segmented data source consists of a number of different data sources, all of which have the same type (such as Oracle or SQL Server) and identical metadata and functionality. Different versions of the same data source are supported as long as the metadata and functionality used in the segmented data source are identical. Only one segmented data source can appear in a query and can be accessed only for retrieval and not for update. To update a segmented data source, update the physical data sources used in the segmented data source.
Note:
Segmented data sources do not work with tables containing BLOB fields or array fields of any type (including chapters). Stored procedures in the data sources that comprise the segmented data source are not supported in the segmented data source.
Add a data source to a binding Create a Data Source Shortcut Add a segmented Data Source to a binding
2. 3. 4. 5.
In the Design perspective Configuration view Expand the Machine where you want to add the data source. Expand the Bindings folder and then expand the binding where you want to add the data source. Right-click the Data sources folder and select New Data source. Enter the following information in this window.
Name: Enter a name to identify the data source. Type: Select the data source type that you want to use from the list. The available data sources are described in the adapter reference section.
6. 7.
Click Next. Enter the connect string required to access the data source. The connect string is data source dependent. For more information, see to the specific data source in the Data Source Reference Click Finish.
8.
For more information on how to create a data source, see Adding Data Sources. You must define these data sources as data source shortcuts to the machine you want to define the segmented data source in Attunity Studio. For more information, see Creating a Data Source Shortcut.
Note:
None of the data sources can be defined directly on the machine where the segmented data source will be defined. That is, all the data sources must be defined on other machines and then defined on the machine with the segmented data source as shortcuts.
In the Design Perspective Configuration View, expand the machine where the data source shortcut should be defined. Expand the Bindings folder and then expand the binding where you want to add the data source. Right-click Data sources and select New data source shortcut. The New Data Source Shortcut wizard is displayed:
5.
If the machine is defined in Attunity Studio, select Machine from Configuration view and select the machine from the drop-down list. If the machine was defined in the binding as a remote machine (for more information, see Setting up Machines) select Machine defined in current binding remote machines list and select the machine from the drop-down list. To add the machine where the data source resides to the list of machines, select New machine-Add the new machine to the Configuration view.
6.
Click Next to display the machine access information. Change the workspace to the relevant workspace, if necessary. Enter the configuration information. For configuration details, see Setting up Machines. Click Next to display the runtime security information. Add the information to be used to access the machine at runtime. This information is written in the user profile associated with the binding (the user profile with the same name as the binding name). For details about the user profile, see Managing a User Profile in Attunity Studio. Click Next to display the list of available data sources. Select the data source and click Finish.
Note:
7.
8.
If the data source name is used as a data source in the binding on the machine where the shortcut is defined, check the Alias in binding box and provide an alias for the data source name.
Expand the Machines folder. Expand the machine with the binding that has the data source shortcuts that you defined. See Creating a Data Source Shortcut. Expand the Bindings folder. In the binding where the data source shortcuts are defined, right-click Data sources and select New Data source. Enter a unique name to identify the segmented data source. Select Segmented from the Type field and click Next. Enter a connection string in the following format. DS1;DS2 Where DS1 and DS2 are data sources with identical metadata that where previously defined to Attunity Connect as independent data sources.
9.
Click Finish.
Query execution when one of the segments fails is controlled by the <queryProcessor IgnoreSegmentBindFailure> parameter in the Attunity Connect binding environment. Setting this parameter to true (the default) causes Attunity Connect to log a message and continue the execution of the entire query when the execution of one of the segments fails. When this parameter is set to false, execution stops when any of the segments fails.
SELECT * FROM SEGDS:tb1, SEGDS:tb2 This code example performs a join between tb1 and tb2 on each segment and then performing a union on the results of all the segments.
SELECT * FROM SEGDS:tb1, SEGDS:tb2, DEMO:tb3 This is the same as a union of: SELECT * FROM DS1:tb1, DS1:tb2, DEMO:tb3 and SELECT * FROM DS2:tb1, DS2:tb2, DEMO:tb3
Part V
Attunity Studio
This part contains the following topics:
-1
25
Working with the Attunity Studio Workbench
This section contains the following topics:
Workbench Overview Using Workbench Parts Workbench Icons Setting Attunity Studio Preferences
Workbench Overview
The workbench is the AIS development environment, where you configure the data sources, adapters, and agents used in your Attunity Connect, Attunity Federate, and Attunity Stream projects. The workbench window contains one or more perspective, which is a collection of views and editors. Each perspective also contains a menu bar, a toolbar, and a shortcut bar. The views are associated with a perspective and are not shared, however editors are shared across perspectives.
Note: The Attunity Studio contains some menu items and buttons that are not used to carry out normal tasks in AIS. These include:
In the Open Perspective dialog box, the Debug and Resource perspectives and all views included in these perspectives. All items in the Project and Run menus in the main menu bar. In the File menu, the menu item New and all of its submenus. The New button in the toolbar and all of its submenus. The following is an example of the New button:
In the File menu, the menu items Import and Export and all of the operations included when these are selected. In the Help menu, the menu item Software updates.
Welcome Screen Main Screen Main Menu Bar Working with Perspectives Working with Views
Welcome Screen
When you Open Attunity Studio, the Welcome screen is displayed.
Figure 251 Welcome Screen
The Welcome screen contains the links to help you get started working with AIS. You can open the following perspectives from this screen.
Add Machine. For more information, see Setting up Machines. Add Daemon. For more information, see Adding a Daemon.
Click the Restore button to view the Welcome screen on the right side of the perspective, while you work with the editors and views.
Main Screen
The Main Screen shows the main parts in Attunity Studio:
Figure 252 Main Screen Main Menu Bar Tool Bar
Perspective Tool
Editors
Views
Solution Perspective
The Solution Perspective implements the design, implementation and deployment of Change Data Capture solutions. CDC solutions allow IT professionals and others to track changes in various data sources. Change Data Captures allow these professionals to keep track of recently changed data. This is a major advantage to ETL solutions, especially those that use data warehouses with vast amounts of data. Traditionally all the data is extracrted from the various data sources and transferred to the data warehouse. With a CDC solution, only recently changed data needs to be extracted and transferred. This saves a large amount of valuable time and resources for an organization. You can create projects and solutions by performing the tasks that are presented to you. For more information, see Creating a CDC with the Solution Perspective.
Design Perspective
Use the Design perspective to define your environment and create the necessary connections between the relevant data sources that contain the data you want to access. The Design perspective is made up of the Configuration View and the Metadata View.
Selecting a Perspective
You can move between the perspectives in Attunity Studio using the perspective tool bar on the upper right part of the screen or from the Window menu. To open a Perspective Do one of the following:
From the Window menu, click Open Perspective and select the Perspective you want to open. Click the Perspective button on the perspective toolbar and select the perspective you want.
Customizing Views
Views can be customized to let you set up a workbench perspective in a way that is comfortable for you. This section describes how:
To move views into different positions To resize a view To open and close views
To move views into different positions Click the tab at the top of a view and drag and drop it to the top, bottom, or sides of the workbench where you want to view it. When you drag and drop a view you will see an outline for in the position you dragged it to. The outline provides you with a guide to see where you are moving the view. You can move to the same position as another view. If two views are in the same place, click the tab at the top of the view you want to see. For example, by default the Metadata and Configuration views are in the same place at the left of the workspace (in the Design perspective). To change from the Metadata view to the Configuration view, click the Configuration view tab. After you move it to a new position, you can then resize it.
To resize a view 1. Place your curser on the edge of the view you want to resize. The turns into a double-sided arrow.
2.
You cannot resize a view from all sides (top, bottom, left, right) The sides that are active for resizing depend on the views position in the workbench.
1. 2.
To open and close views From the Window menu, click Show View and then select the view you want to open from the submenu. Select the view from the list, or Select Other, and select the view from the Show View window.
The Error Log view lets you execute various tasks. For more information, see Error Log View.
Configuration View
The Configuration view lets you configure all levels of access to data. Together with the Metadata View, it makes up the Design Perspective.
Figure 257 Configuration View
Metadata View
The Metadata View lets you define the metadata for objects. Together with the Configuration View, it makes up the Design Perspective.
Workbench Icons
Studio icons are divided into the following four categories:
General
The general icons are listed and described in the following table:
Table 251 Icon General Icons Description Document Error File object Folder Help Import wizard
Table 251 (Cont.) General Icons Icon Description Information Large image Sample Star Horizontal Vertical Warning
Actions
The action icons are listed and described in the following table:
Table 252 Icon Action Icons Description Add Back
Table 252 (Cont.) Action Icons Icon Description Disconnect Delete Execute Expand all Export log file
Resume Save as
Table 252 (Cont.) Action Icons Icon Description Search Select Set up workspace Stop Undo edit
Objects
The objects icons are listed and described in the following table:
Table 253 Icon Object Icons Description Adapter Add FTP Binding Build metadata Changed data capture Client information Column Completed task Computer up Computer down Configuration Configure CDC Agent Configure data source
Table 253 (Cont.) Object Icons Icon Description Configure service point Configure staging area Daemon Daemon down Daemon offline Data source Database view Design machine Data source link Element Enable backend database Encryption Delete Error Error in task Event Execute File Group Hard disk Import Index
Table 253 (Cont.) Object Icons Icon Description Input Interaction Join Login Machine Machine down Machine offline Metadata My Computer My FTP Native data source Native metadata New project Open project Output Procedure Project Query Record Schema Search Segment
Table 253 (Cont.) Object Icons Icon Description Server Solution Perspective Stored procedure Synonym Table Table Ext. Local table Native table Transparent table Task User Virtual data source Workspace XML
Manipulation
The manipulation icons are listed and described in the following table:
Table 254 Icon Manipulation Icons Description Change data type Column normalization Combine fields Create array
Table 254 (Cont.) Manipulation Icons Icon Description Data file Fixed Flatten group Free XSL Hide Mark selector Nullable Replace variant Select counter Set dimension Set scale Set size
Studio Keys
Studio
The following tables describe the Studio preferences. The Studio preferences section has two tabs.
Studio Security Tab Description Select this to compress data used in Attunity Studio.
Use Compression
Use encrypted communication Select this to encrypt communication between Attunity Studio and servers. Remember Password Change Master Password Select this if you want Attunity Studio to automatically enter
Studio Advanced Tab Description Select this to start Attunity Studio with all editors closed and the Design perspective Configuration views collapsed. In this case, none of the editors left open at the end of the previous session will open when starting a new session. This is the default setting. If you clear this check box, all windows open at the end of the previous session will open when you start a new session and Attunity Studio will take longer to load. Select this to display advanced binding environment properties. These properties should only be displayed in coordination with Attunity Support. Select this to implement tracing and logging on the network and communication transport layer. When you select this check box, the following fields are available:
JCA log level. Select Error, Info, or Debug from the drop-down list. JCA log file: Enter the location of the JCA log file or click Browse to browse for a location.
Table 256 (Cont.) Studio Advanced Tab Option Network XML Protocol Description Select:
Text Binary
Connection timeout
Enter the amount of time (in seconds) that Attunity Studio waits for a connection to another machine (such as a server) before returning an error message. The default value is 60. In this case, Attunity Studio waits one minute before returning an error message. Enter the amount of time (in seconds) that Attunity Studio waits for a connection to a specific interaction (such as a data source) before returning an error message. The default value is 120. In this case, Attunity Studio waits two minutes before returning an error message.
Interaction timeout
Configuration
The following table describes the Configuration preferences
Table 257 Option Enable using an adapter definition by multiple adapters Configuration Preferences Description Select this to reuse adapter definitions. When adding a new adapter an additional window lists the current adapters in the same binding and lets you use an adapter definition unique to the adapter or an adapter definition from any of the listed adapters.
Enable specifying Select this if you want to enter administration authorization administration information on the machine level. It is added to the machines authorization directly in the source XML. source XML
Table 257 (Cont.) Configuration Preferences Option Show SYS data source Description Select this to display the SYS data source, including stored procedures and views defined for it in the Design perspective Metadata tab. This option is selected by default. For future use only.
Configuration Preferences
Metadata
The following table describes the Metadata preferences.
Table 258 Options Enable editing source XML Metadata Preferences Description Select this to allow editing of the source tabs XML content.
Runtime Manager
The following table describes the Runtime Manager preferences.
Table 259 Option Enable periodic machine check Runtime Manager Preferences Description Select this to set up a machine check on a scheduled basis. If you select this option, enter a time interval in the field below. The time interval is in seconds. For example, if you want a machine check every minute, enter 60.
Figure 2513
Keys
Attunity Studio has many built in keyboard shortcuts. You can also customize keyboard shortcuts in Attunity Studio. The key preferences has two tabs. The View tab shows the list of default shortcuts.
The Modify tab lets you make changes to the current keyboard shortcuts or add new shortcuts. If you want to return to the default settings, click Restore Defaults at the bottom of the screen.
Figure 2515
(Cont.) Key Sequence Ctrl+Shift+J Ctrl+V Shift+Insert Ctrl+Shift+Q Ctrl+1 Ctrl+Y Ctrl+A Ctrl+Shift+Insert Ctrl+Z Alt+/ Ctrl+F4 Ctrl+W Ctrl+Shift+F4 All,Ctrl+Shift+W Ctrl+N Alt+Shift+N Ctrl+P Alt+Enter F5 F2 Ctrl+S Ctrl+Shift+S Alt+Left Alt+Right Ctrl+L Ctrl+Q Next,Ctrl+. When (The context the command is available) Editing Text In Dialogs and Windows In Dialogs and Windows Editing Text In Windows In Windows In Dialogs and Windows Editing Text In Windows Editing Text In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows Editing Text In Windows In Windows In Windows In Windows In Windows In Windows In Windows Editing Text Editing Text Editing Text Editing Text
Incremental Find Reverse Paste Paste Quick Diff Toggle Quick Fix Redo Select All Toggle Insert Mode Undo Word Completion Close Close Close All Close New New menu Print Properties Refresh Rename Save Save All Backward History Forward History Go to Line, Last Edit Location
Open Resource Previous, Show In menu Build All Open Search Dialog,, Collapse Copy Lines Delete Line Delete Next Word,,t
(Cont.) Key Sequence When (The context the command is available) Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text Editing Text In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows In Windows
Delete Previous Word,,t Ctrl+Backspace Delete to End of Line Duplicate Lines Expand Expand Insert Line Above Current Line,, Insert Line Below Current Line Move Lines Down Move Lines Up Next Word,,Editing Text Previous Word Scroll Line Down Scroll Line Up Select Next Word Select Previous Word To Lower Case To Upper Case,,Editing Text Toggle Folding Toggle Overwrite Cheat Sheets,,In Windows Console,,In Windows Search,,In Windows Show View (View: Outline),,In Windows Show View (View: ) Activate Editor Maximize Active View or Editor Next Editor Next Perspective Ctrl+Shift+Delete Ctrl+Alt+Up Ctrl+Numpad_Add All,Ctrl+Numpad_Multiply Ctrl+Shift+Enter Shift+Enter Alt+Down Alt+Up Ctrl+Right Ctrl+Left Ctrl+Down Ctrl+Up Ctrl+Shift+Right Ctrl+Shift+Left Ctrl+Shift+Y Ctrl+Shift+X Ctrl+Numpad_Divide Insert Alt+Shift+Q, H Alt+Shift+Q, C Alt+Shift+Q, S Alt+Shift+Q, O Alt+Shift+Q, X F12 Ctrl+M Ctrl+F6 Ctrl+F8
Next View,,In Windows Ctrl+F7 Open Editor Drop Down Previous Editor, Ctrl+E ,Ctrl+Shift+F6
(Cont.) Key Sequence When (The context the command is available) In Windows In Windows In Dialogs and Windows Editing Text In Windows In Windows In Windows
Previous Perspective,,In Ctrl+Shift+F8 Windows Previous View,,In Windows Show Key Assist,,In Dialogs and Windows Show Ruler Context Menu, Show System Menu Show View Menu Switch to Editor Ctrl+Shift+F7 Ctrl+Shift+L Ctrl+F10, Alt+Ctrl+F10 Ctrl+Shift+E
Part VI
Operation and Maintenance
This part contains the following topics:
AIS Runtime Tasks from the Command Line Runtime Management with Attunity Studio Managing Security Backing Up AIS Transaction Support Troubleshooting in AIS
26
AIS Runtime Tasks from the Command Line
This section includes the following topics:
Overview
This section describes how to use AIS in a production environment. It describes the procedures necessary for smooth production time data integration. Many of the operations necessary for the production environment are carried out in Attunity Studio..
Starting a Daemon
You start a daemon from a privileged account (such as the super user account on a UNIX platform) on the machine where the daemon will run. If not run from a privileged account, the daemon can start servers only with the same user ID as the account that started it. In this case, the daemon may also have problems validating user name/password pairs within the system. Use Attunity Studio to manage all daemon operations, except for starting the daemon. A daemon can only be started via the command line. A daemon cannot be started from within Attunity Studio. The daemon startup processes vary according to the type of platform.
Installation Guide for more details). When IRPCD initializes itself as a daemon, it creates a detached process under the same account from which 'IRPCD start' was issued. In the detached process, the account's login procedure is not executed. If the daemon fails to start in the detached process, define the symbol NV_DEBUG_MODE to something before starting the daemon. This creates a process log file in SYS$LOGIN:IRPCD_START.LOG that can help you to locate the problem. UNIX Platforms To enable automatic client/server access to an Attunity Server, start the daemon at system boot time by adding the command invoking IRPCD to the /etc/inittab file. This table lists the lines to add for the supported UNIX systems.
Table 261 System Sun Solaris HP-UX AIX HP Tru64 UNIX Linux UNIX Command Lines for Starting the Daemon Automatically Starting the Daemon nv:3:once:navroot/bin/irpcd start >/dev/console 2>&1 nav:3:once:navroot/bin/irpcd start >/dev/console 2>&1 nav:2:once:navroot/bin/irpcd start >/dev/console 2>&1 nv:2:once:navroot/bin/irpcd start >/dev/console 2>&1 nv:3:once:navroot/bin/irpcd start >/dev/console 2>&1
The symbol navroot should be replaced with the directory where AIS is installed. Windows Platforms To start the daemon automatically, set the Startup type property for the Daemon (IRPCD) service to Automatic. The Daemon (IRPCD) service is accessed via the Services option in the Windows Control Panel (for example, for Windows 2000 this is accessed via Start|Settings|Control Panel|Administrative Tools|Services). If you change the account under which the daemon runs, make sure that the following user rights are assigned:
Act as part of the operating system Create a token object Log on as a batch job Log on as a service Log on locally
Set these rights in Control Panel|Administrative Tools|Local Security Policy. In the Local Security Settings screen, select Local Policies|User Rights Assignment and verify that each of the above user rights is set. After verifying the settings, reboot the Windows machine. The daemon starts up automatically each time the machine is restarted.
Manually Starting a Daemon on HP NonStop, OpenVMS, OS/400, UNIX, and Windows Platforms
The IRPCD command is used to start the daemon.
For IRPCD commands to manage the daemon on the machine itself see.
Note:
On HP NonStop you must start the daemon from a super user account.
For OS/400 platforms: Start the daemon from the root directory and from the account specified in the workspaceAccount property. * * * To go to the root directory enter: chgcurdir '/ The workspaceAccount property is specified as described in Granting Workspace Administration Rights to Users. Run the following to start the daemon:
Sbmjob cmd(call pgm(navroot/irpcd) parm([-l[host[:port | :a]][-r]] [-u username [-p password]] [-n][-v] start [daemon_name]))
Note that strings in parameters containing special characters (such as the hyphen in -u username) must be surrounded by single quotes, as in '-u' username. If navroot has been defined, start the daemon without specifying the path:
Sbmjob cmd(call pgm(irpcd) parm([-l[host[:port|:a]][-r]] [-u username [-p password]] [-n][-v] start [daemon_name]))
To use the default location for the irpcd program, when the NAVROOT library has been defined, specify the following:
Sbmjob cmd(call pgm(irpcd) parm([-l[host[:port|:a]][-r]] [-u username [-p password]] [-n][-v] start [daemon_name]))
If you do not succeed in starting the daemon, check the log file by running the following command:
Edtf '/navroot/tmp/irpcd.log'
where:
-l [host][:port | :a][-r]: The daemon uses a particular port, rather than the default attunity-uda-server port number 2551. If you specify "a" as the port, the system assigns a free port, which is registered with the portmapper. The option -r allows you to set a port range. The daemon will only start in the range of ports specified. For example, -r 2551-2553, indicates that the daemon
will start only on ports 2551, 2552, and 2553. This is used when a system defines a specific port range for AIS to run, as this ensures that the daemon will start only in the defined port range. This is important because if the daemon starts in a port that is not defined in the systm, users will be unable to use components of AIS, such as Attunity Studio. If you are starting the daemon on platforms that support a multi-home machine, such as HP NonStop, and are not using the default IP address, specify the IP address in the host parameter. Start the daemon as follows:
run irpcd -l 194.90.22.23 start
For example, if the tcpip_proc_name is $ztc0 and it corresponds to the IP address 194.90.22.23, the daemon is started as above (run irpcd -l 194.90.22.23 start).
u username -p password: The login information used to issue the daemon command. Specify '-u ""' for an anonymous login (if the daemon is configured to accept anonymous logins). The username and password may be needed to start a daemon since the daemon uses them to stop the active daemon (if one exists). -b (Blocking): OpenVMS and UNIX Platforms only. The daemon remains connected to the terminal and does not daemonize itself. By default, when the daemon is started it disconnects itself from the activating terminal and becomes a detached process. All of the daemon logging messages are sent to the standard output device, regardless of the logging settings. Use this option for troubleshooting if there are problems starting the daemon. n (No mapping) The daemon is not used as a portmapper. By default, if a portmapper is not found the daemon itself can be used as a portmapper. v (Verbose): Provides detailed information whenever applicable (for example, messages entered to the log). daemon_name: The name of a daemon. If the a daemon name is not specified the default, IRPCD, is started.
The NAVROOT.loadaut library is APF authorized. NAVROOT is the high-level qualifier specified during installation.
Note: To define a DSN as APF authorized, in the SDSF screen enter the following command:
/setprog apf,add,dsn=navroot.loadaut,volume=nav002
The navroot.LOAD library is APF authorized. Use the information in the previous step to do this, and issue this command:
/setprog apf,add,dsn=navroot.load,volume=nav002
NAVROOT.USERLIB(ATTSRVR) and NAVROOT.USERLIB(ATTDAEMN) have been copied to a library within the started tasks path. If they have not been copied, add the NAVROOT.USERLIB library to this path.
2.
Activate NAVROOT.USERLIB(ATTDAEMN)as a started task to invoke the daemon. For example, in the SDSF screen enter the following:
/s ATTDAEMN
To submit the daemon as a job, uncomment the first two lines of the ATTDAEMN JCL and run the job using the sub command. The ATTDAEMN JCL is similar to the following:
//*ATTDAEMN JOB 'RR','TTT',MSGLEVEL=(1,1),CLASS=A, //*MSGCLASS=A,NOTIFY=&SYSUID,REGION=8M //STEP1 EXEC PGM=IRPCD, // PARM='-B START ''NAVROOT.DEF.IRPCDINI''' //STEPLIB DD DSN=NAVROOT.LOADAUT,DISP=SHR //SYSPRINT DD SYSOUT=A //GBLPARMS DD DSN=NAVROOT.DEF.GBLPARMS,DISP=SHR // EXEC PGM=IRPCD,COND=((1,EQ,STEP1),(2,EQ,STEP1)), // PARM='-KATTDAEMN START ''NAVROOT.DEF.IRPCDINI''' //STEPLIB DD DSN=NAVROOT.LOADAUT,DISP=SHR //SYSPRINT DD SYSOUT=A //GBLPARMS DD DSN=NAVROOT.DEF.GBLPARMS,DISP=SHR //SYSDUMP DD DUMMY
Note:
You can also run ATTDAEMN by submitting the job, without making any changes to the JCL.
Stopping a Daemon
You can shut down the daemon on any machine with Attunity Studio or from the command line.
To shut down the daemon using Attunity Studio In the Runtime explorer, right-click the daemon you want to shut down and select Shutdown Daemon.
Note:
On Windows Platforms, run this command through the Command Line Console menu item in the Attunity menu (Start|Programs|Attunity|Command Line Console).
Shutting down the daemon does not immediately kill active servers. To kill active servers, add the NVSHKILL parameter, with a value of 1, to the NAVROOT.DEF.GBLPARMS dataset (where NAVROOT is the high-level qualifier where Attunity Server is installed).
Or
call pgm(irpcd) parm(shutdown [abort[why] | oper])
where
abort: If non-zero, the daemon shuts down regardless of any outstanding activity or active clients. why: The reason for the shutdown, which is written to the log file. oper: On HP NonStop, OpenVMS, OS/400, UNIX, and Windows platforms, shuts down the daemon by sending a signal (SIGQUIT) to the daemon process. You do not need to specify the username or password for this option but you must have system privileges (you need to be a superuser). To send a signal to the daemon, the IRPCD program requires the process ID of the target daemon: the program retrieves this information from the file irpcd[_port].pid in the directory where the daemon resides (a daemon that was started on a particular port would have the port number in the PID filename). The PID file is automatically created when a daemon starts and is deleted when a daemon ends.
Disabling a Workspace
You can disable a workspace, so that although it is defined for a daemon it is not operable. Server processes are not started via this workspace and a client requesting this workspace receives an error. To disable a workspace using Attunity Studio In the Design perspective Configuration view, right-click the workspace to be disabled and select Disable.
To check the status of a daemon using the command line Enter the appropriate command line as follows:
Note:
On Windows Platforms, run this command through the Command Line Console menu item in the Attunity menu (Start|Programs|Attunity|Command Line Console).
If you have NAVROOT define, run the following command without specifying the path:
call pgm(irpcd) parm(test)
to use the default location for the irpcd program when the NAVROOT library has been defined, run the following command:
call pgm(irpcd) parm(test)
where
daemon_location: The host name with an optional port number (specified after a colon) username, password: Used for logging onto the daemon.
For example, if you check a machine named proc.acme.com, the following is returned if the daemon is active:
Checking IRPCD on host prod.acme.com Trying anonymous login - OK This test took 0.500 seconds.
Daemon Control: Specifies the server details, including daemon failure recovery, maximum request file size, default language, and time out parameters. Daemon Logging: Specifies the logging details such as, the log file format and location, and the parameters to log and trace (as opposed to server logging, which is performed in the Workspace section). Daemon Security: Specifies the administrative privileges and access for the daemon. Daemon Workspaces: The workspaces defined for the daemon. A daemon can include a number of workspaces. A workspace defines the server processes and environment that are used for the communication between the client and the server machine for the duration of the client request. Each workspace has its own
definition and includes the data sources and applications that can be accessed as well as various environment variables. The workspace definition is divided into the following groups:
WS Info: Specifies general information including the server type, the command procedure used to start the workspace, the binding configuration associated with this workspace (which dictates the data sources and applications that can be accessed) and the timeout parameters. WS Server: Specifies workspace server information including features that control the operation of the servers started up by the workspace and allocated to clients. WS Logging: Specifies workspace tracing options. WS Security: Specifies administration privileges, user access, ports available for access to the workspace and workspace account specifications. WS Governing: Specifies the way queries are executed. This is used particularly when running queries against large tables.
Note:
The default daemon configuration supplied with AIS includes the default Navigator Workspace. This workspace is automatically used if a workspace is not specified.
Configuring Logging
You can set up logging for the following:
27
Runtime Management with Attunity Studio
This section contains the following topics:
Overview
Runtime Management tasks are done after you set up and define all of your machines and daemons. Runtime management lets you:
Monitor the status of daemons and servers Reload and refresh daemons, servers, and configurations View error logs and print and export reports for each daemon and server
You carry out the daemon and server tasks in the Runtime Explorer view and you carry out the logging tasks in the Log view.
Adding a Daemon
To add a daemon at runtime 1. Open Attunity Studio.
2. 3.
From the perspective toolbar at the top right of the workbench, open the Runtime Manager perspective. From the Runtime Explorer view, right-click the Daemons folder and select Add Daemon.
4.
Enter the following information about the machine where the daemon is located:
Host name/IP address: Enter the name of the machine on the network. The name can be entered manually or click Browse to browse all the machines running a daemon listener on the port currently accessible over the network. When you expand the daemon you can view the daemons workspaces to edit the server processes for each workspace.
Port: Enter the port where the daemon is running. The default port for Attunity Server is 2551. Display name: Enter an alias used to identify the daemon when different from the host name. This field is optional.
5.
User name: The username of a user defined as an administrator for the machine. This is optional. Password: Enter the password for the user entered in the User name field. Connect via NAT with a fixed IP address: Select this if the machine uses the NAT (Network Address Translation) firewall protocol, with a fixed configuration, mapping each external IP to one internal IP, no matter which port is used. For more information, see Firewall Support.
Note:
You create an administrator when the machine is installed or by adding the administrator using Attunity Studio. See Administration Authorization.
Daemon Tasks
Right-click a daemon to execute the following tasks at runtime.
Table 271 Task Daemon Tasks Description
Edit Daemon Configuration Opens the daemon editor, which allows you to make changes to the daemon configuration. For more information, see Defining Daemons at Design Time. See Also: AIS Runtime Tasks from the Command Line for details about the configuration settings. Status Checks the status of the daemon. The information about the daemon includes the daemon name, configuration used, the active client sessions, and logging information. For more information, see Checking the Daemon Status with Attunity Studio. If a client session ends because of power loss, network inaccessibility, or a system reset, the associated server process may remain active for a long time. In this case, the system administrator should kill those server processes. You can monitor the status of all the currently active server processes to identify server processes that need to be killed Reload Configuration Reloads the configuration after any changes. Any servers currently started are not affected by the changed configuration. A warning message opens, click OK to reload the current daemon configuration. See Also: AIS Runtime Tasks from the Command Line for details about the configuration settings. View Log Opens the daemon log in the editor window. This log provides a real-time display of the details written to the daemon log from the time the view is open. For information, see Viewing Logs. Opens the daemon events log, which displays the daemons activities. See Viewing Events. Opens the Daemon Properties screen. This screen displays the information that was entered when adding the daemon. You can make changes to this information. For information about the fields in this screen, see Adding a Daemon. Shuts down the daemon on the computer. Note: You must start a daemon from a machine command line. Recycle servers Closes all unused servers and prepares all active servers to close when the client disconnects. New connection requests are allocated with new servers. Immediately closes all active and unused servers. Note: This option can lead to data loss. Rename Remove Refresh Opens a screen where you can change the name of the daemon displayed in the Runtime Explorer view. Removes the daemon from the Runtime Explorer view. Refreshes the state of the daemon to the last state. After starting or restarting a daemon, you should refresh the daemon in Attunity Studio.
Shutdown Daemon
Kill servers
Workspace Tasks
Right-click a workspace to execute the following tasks at runtime.
Table 272 Task Edit Workspace Configuration Workspace Tasks Description Opens the daemon editor, which allows you to make changes to the daemon configuration. See Editing a Daemon. Click the workspace tabs at the bottom of the editor to edit the workspace configuration. For more information, see Adding and Editing Workspaces. See Also: AIS Runtime Tasks from the Command Line for details about the configuration settings. Status View Log Checks the status of the workspace, whether it is available or not. Opens the log for workspaces on all servers in the editor window. This log provides a real-time display of the details written to the workspace log from the time the view is open. For information, see Viewing Logs. Opens the workspace events log. See Viewing Events. Closes all unused servers and prepares all active servers to close when the client disconnects. New connection requests are allocated with new servers. Immediately closes all active and unused servers. Note: This option can lead to data loss. Refresh Refreshes the state of the workspace to the last state. After starting or restarting a daemon, you should refresh the workspaces in Attunity Studio.
Kill Servers
Server Tasks
Right-click a server to execute the following tasks at runtime:
Table 273 Task Status Server Tasks Description Checks the status of the server. The information about the server includes the server mode and the number of active client sessions for the server. Opens the server log in the editor window. This log provides a real-time display of the details written to the server log from the time the view is open. For information, see Viewing Logs. Opens the server events log. See Viewing Events. Ends the server process, regardless of its activity status. Note: It is recommended to use this option with caution, as it may lead to data loss. Refresh Refreshes the state of the server to the last state. After starting or restarting a daemon, you should refresh the server in Attunity Studio.
View Log
Viewing Logs
AIS produces a number of logs that you can use to troubleshoot problems. The daemon manages the following logs:
From the Runtime Explorer view, expand the daemon folder, daemon, or workspace. Right-click the level you want to view (daemon, workspace, or server) and select View Log. Each log is displayed in a separate tab. You can switch logs by clicking the required tab. The Attunity Studio Runtime Manager perspective opens the log monitor in the editor.
Set the logging level Start and stop the logging display Clear the activities displayed in the log
1. 2. 3.
To set the logging preferences Open Attunity Studio. Open the log view (see Viewing Logs). In the log view editor, click Properties. The Preferences screen opens.
4.
none: The log displays who has connected and disconnected from the server process. error: The log displays who has connected and disconnected from the server process and all errors. debug: The log displays who has connected and disconnected from the server process, errors, and any tracing specified in the daemon configuration.
5.
To close the screen without changing the logging level, click Cancel. To reset the logging level to the default settings, click Restore Defaults.
Click Suspend to stop collecting logging information Click Resume to start collecting logging information
To clear the information in the log Click Clear to remove all entries in the log displayed in the Events monitor. If logging is enabled, new information will continue to be displayed. The cleared information cannot be viewed again.
Note:
You can view a copy of the full log located in your system. The log location is defined when you define the daemon or workspace. For more information, see Editing a Daemon.
Viewing Events
Attunity Studio provides a view of the events for each daemon, workspace, and server. The view is displayed in the workbench editor. To view events 1. Open Attunity Studio.
2. 3.
From the Runtime Explorer view, expand the Daemons folder, daemon, or workspace. Right-click the level you want to view (daemon, workspace, or server) and select View Events. Each Event monitor is displayed in a separate tab. You can switch logs by clicking the required tab. The Attunity Studio Runtime Manager perspective opens the Event monitor in the editor.
Working with the Event Editor The Events displayed in the Event Editor display daemon, workspace, and server activities as they happen. You can carry out the following activities for each.
Set the Event logging level Start and stop the Event logging display Clear the events displayed in the log
To set the Event preferences 1. In the Event view editor, click Properties. The Preferences screen opens. You can set preferences for the following:
2.
To set the logging preferences, click Logging and then select one of the following:
none: The log displays who has connected and disconnected from the server process.
error: The log displays who has connected and disconnected from the server process and all errors. debug: The log displays who has connected and disconnected from the server process, errors, and any tracing specified in the daemon configuration.
3.
Select Server from the left side of the screen to determine whether to display connection and disconnection events for a server machine in the log.
Select serverConnect to display all users that connect to the server. Select serverDisconnect to display all users that disconnect from the server.
4.
Select Client from the left side of the screen to determine whether to display connection and disconnection events for the client machine in the log.
Select clientConnect to display all users that connect to the client. Select clientDisconnect to display all users that disconnect from the client.
5.
To close the screen without changing the logging level, click Cancel. To reset the logging level to the default settings, click Restore Defaults.
Click Suspend to stop collecting logging information Click Resume to start collecting logging information
To clear the information in the log Click Clear to remove all entries in the log displayed in the Event Editor. If logging is enabled, new information will continue to be displayed. The cleared information cannot be viewed again.
Daemon Properties
The Daemon Properties screen lets you make changes to the daemon definition that was created. See also: Adding a Daemon. To view and edit daemon properties 1. Open Attunity Studio.
2.
In the Runtime Explorer view, Right-click the daemon where you want to view the properties and select Daemon Properties. The Daemon properties screen opens:
3.
Enter the following information about the machine where the daemon is located:
Host name/IP address: Enter the name of the machine on the network. The name can be entered manually or click Browse to browse all the machines running a daemon listener on the port currently accessible over the network. When you expand the daemon you can view the daemons workspaces to edit the server processes for each workspace.
Port: Enter the port where the daemon is running. The default port for Attunity Server is 2551. Display name: Enter an alias used to identify the daemon when different from the host name. This field is optional.
4.
User name: The username of a user defined as an administrator for the machine. This is optional. Password: Enter the password for the user entered in the User name field. Connect via NAT with a fixed IP address: Select this if the machine uses the NAT (Network Address Translation) firewall protocol, with a fixed configuration, mapping each external IP to one internal IP, no matter which port is used.
Note:
You create an administrator when the machine is installed or by adding the administrator using Attunity Studio. See Administration Authorization.
5.
27-11
Error Log View Tasks Viewing the Event Details Deleting the Error Log Clearing the Error Log Restoring the Error Log Exporting Errors to a Log File Importing a Log File Opening a Log File
The logs displayed in this view are the Attunity Studio logs. These logs display details about Attunity Studio users, connections to other AIS modules, and other information about Attunity Studio.
Right click in the view or on the error you want to carry out the task on and select one of the Event Log View tasks. Or
Select an error (if the task is carried out for a specific error) and click the button at the top of the for the Event Log View task you want to carry out. For an explanation of the buttons, see Workbench Icons.
Event Log View Tasks Description Copies the Event Details for the selected error to the clipboard. The event details traces the history of the current thread. For more information, see Event Details below. Clears the information displayed in the current Error Log view. See Clearing the Error Log. Deletes the current log in Error Log View. See Deleting the Error Log. Opens the full log in text format. See Opening a Log File. Restores information that was cleared from the last error log displayed to the Error Log view. See Restoring the Error Log. Exports the currently displayed log into text format. See Exporting Errors to a Log File. Imports another Attunity Studio log into the Error Log view. See Importing a Log File. Opens the Event Details screen. You can view information on the execution history of the current thread up to the point where the error was thrown. This helps to trace the source of the error. See Viewing the Event Details.
Clear Log Viewer Delete Log Open Log Restore Log Export Log Import Log Event Details
Right click from anywhere in the Error Log view and select the Clear log viewer icon. Or
Click Clear log viewer at the top of the Error Log View.
Right click from anywhere in the Error Log view and select Delete. Or
Click the Delete button at the top of the Error Log View.
Right click in the Error Log view and select Open error log file. Or
Click Open error log file at the top of the Error Log View.
27-13
2.
Browse to select a.log file and click Open. The log file opens as a text file.
Right click in the Error Log view and select Reload error log. Or
Right click in the Error Log view and select Export log file icon. Or
Click Export log file at the top of the Error Log View.
2.
Enter a name for the log file and browse to a location, then click Save.
Right click in the Error Log view and select Import log file. Or
Click the Import log file button at the top of the Error Log View.
2.
Browse to find a.log file and click Open. The log file opens in the Error Log View.
Note:
The Error Log view displays logs for Attunity Studio only.
In the Error Log View, double click on the error with the Event Details you want to view. Or
Right click the error and select Event Details The Event Details screen opens. This screen displays the error message, the error severity and the errors event details.
To view the event details for another error, you can click the error keys at the top of the screen to scroll through all the errors in the view.
27-15
28
Managing Security
This section contains the following topics:
Overview of Attunity Security Managing Design Time Security Managing Runtime Security
Design Time: Security aspects that affect the design process of AIS solutions. Runtime: Security aspects that affect the use of AIS for accessing data sources and applications and for managing AIS solutions.
Local Access to AIS Design-Time Resources Remote Access to AIS Design-Time Resources Password Handling in Attunity Studio
XML definitions, which are usually stored in a native object store (NOS). These definitions saved in the NAVROOT/def directory or folder. Operating system scripts, which are system dependant. These are generally located in various places on the local file system.
Local file access to design resources refers to working on the system where AIS is installed using Attunity Studio or NAV_UTIL to access and change the design resources. Local file access to these design resources is controlled only by the host operating systems where AIS runs. One should treat these resources just like the source code of an application.
Local file access to the AIS design resources must be limited to people who are authorized to design and set up AIS. Authorization is usually provided through a dedicated account with full access to these design resources
Design Roles
Remote access to design-time resources has many security implications. The ACADMIN server has fine granularity control of which definitions a user can access and how the definitions can be accessed (read or write). Attunity Studio offers a simplified role model for AIS design that defines the following roles:
The Administrator role is allowed to view and modify all AIS design resources. The Designer role is allowed to view and modify all AIS design resources except for the daemon settings. The User role is allowed only to view the binding, adapter and user definitions.
A user that is assigned multiple roles in Attunity Studio will have the permissions for the most powerful role assigned. An account is set up when you add a machine to Attunity Studio. The account is defined in the Connection section of the Add Machine dialog box. By default, the AIS installation account is automatically assigned an administrator role. The administrator role or any other role assignment can be reset using the NAV_UTIL ADD_ADMIN command from an account with write access to the AIS design resources:
$ nav_util add_admin <username>
For information on assigning roles in Attunity Studio, see Assigning Design Roles. For information on adding machines in Attunity Studio, see Setting up Machines.
Administrator: Allowed to edit all of the definitions in Attunity Studio. Designer: Allowed to edit binding definitions and view daemon definitions in Attunity Studio. User: Allowed to view the definitions in Attunity Studio.
Perform the following steps to assign design roles to users and groups.
1. 2.
In the Configuration view, right-click the machine and select Administration Authorization. In the Administration Authorization screen, click Add User or Add Group to assign authorization to specific users or a specific group of users. The name cannot contain blanks.
Note: Administration Authorization is set from the top down. This means that if you specify users or groups at a higher level, you do not need to specify the same users or groups on a lower level.
Username and password to access AIS Administration Servers. Each Administration Server requires its own username and password Username and password for runtime access to servers, databases and applications (some design operations require runtime access to resources).
Prompt for passwords once per session for each secured resource that is accessed. This setting is the most secure but it requires the user to enter the password for any server being accessed. This may be easy when small number of machines and sources are involved in the AIS solution but as more secured resources are used, this becomes more difficult. However, security policy in certain organizations may require this method. Prompt for password once and then cache the password in a local file protected with a master password. With this method, the user is prompted once for the master password at the beginning of a session and if the master password is correct, Attunity Studio automatically uses the passwords stored in that file. This method is secure as long as you use a strong master password. A strong password is not easy to guess. It should not be too short and as complex as possible, yet you should be able to easily remember it. The last method is similar to the previous one but without using any master password. In this case, Studio uses an internal password so the local file does not contain plain-text passwords. However, the stored passwords may be discovered with little effort. This method is not recommended as it is not secure. It should be used only if a password leak is not considered a security risk (for example, when the system is isolated).
The following sections describe how to set up passwords for design-time security:
Setting Up the Password Caching Policy in Attunity Studio Assigning Authorization Rights to a Workspace Setting Up a Master Password for a User
Attunity Studio does not cache passwords. When Attunity Studio needs a password to access a server or database, it prompts the user to enter the password. This is the safest level, but it is less convenient. Attunity Studio caches passwords persistently but protects them through a master password. At this security level, Attunity Studio prompts for the master password at startup. Attunity Studio caches passwords persistently but hides them through a fixed internal master password. This security level is convenient but not safe because the cached password can be retrieved any time. This level is not recommended.
To set the password caching policy of Attunity Studio 1. In Attunity Studio, point to Windows, then select Preferences.
2. 3.
For the highest security level, clear the Remember passwords check box. For a lower security level, do the following: Click Change master password. The Change master password dialog box opens. Enter a master password and confirm it. Then click OK. Select the Remember passwords check box.
Note:
If you set a master password, Attunity Studio will prompt you for the password the next time you open the application. If you set the master password to an empty password, Attunity Studio will use the internal default password.
4.
Specify the user name and password for the user with authorization rights for this workspace.
Note:
The password assigned to a user profile definition must be identical to the password of the user account of the servers operating system. Likewise, if the password of the user account of the servers operating system changes, you must also change the password of the user profile definition.
To set a master password for a user profile 1. Expand the machine under which the user is set.
2. 3. 4.
Expand the Users node under the machine. Right-click the User in the Attunity Studio Design perspective Configuration view and select Change Master Password. Enter the password to be changed and the new password, and then click OK.
Daemon and Workspace Administration: Granting the authorization needed to manage a running daemon. Access Authorization: Granting the authorization needed to connect and use a server workspace. Network Communication Encryption: Encrypting the data sent over the network between the client and the server. Impersonation: Making the server process take on the security identity of the client so that data access permissions and restrictions apply based on the clients identity (rather than on the servers security level). User Profiles: Enabling a single sign-on to the server machines, application adapters, and data sources.
The Managing Runtime Security section of this document is divided into the following theory and task sections:
User Profiles Managing a User Profile in Attunity Studio Client Authentication Client Authorization and Access Restriction Transport Encryption Encrypting Network Communications Firewall Support Accessing a Server through a Firewall Dynamic Credentials Setting Up Impersonation Granting Daemon Administration Rights to Users Granting Workspace Administration Rights to Users
User Profiles
The User Profile definition is an AIS resource that plays an important role in the AIS runtime security. A User Profile is a collection of username and password pairs for accessing databases, applications and remote machines on behalf of the user. The User Profile definition also stores encryption keys for use with transport encryption. A User Profile is protected by a master password that is required for access to the passwords and keys. You need to define a user profile:
At the client with ODBC, ADO/OLEDB or NAV_UTIL At the server side when connecting with any client.
Setting a Master Password for a User Profile Using a Client User Password Using a Server User Profile
If the User Profile was already protected with a master password, you will be prompted to enter the old password. Then the program will prompt you to enter the new password twice (to make sure you entered the intended password) and will update the User Profile. Another way to change the master password of a User Profile is with Attunity Studio. You can create a master profile when you define a new user or you can edit an existing user to add or change the master password. To change the master password in Attunity Studio 1. Connect to the AIS machine where the User Profile is defined.
2. 3. 4.
From the Configuration explorer, expand the machine where the User Profile is defined. Right-click the User Profile you want to edit and select Change Master Password. In the Change password dialog box, enter the following information:
Old password: Type the current master password or the default master password. New password: Type the new password that you want to use. Make sure that it is a strong password that is not easy to guess and that you can remember. Confirm new password: Type the new password again.
For information on adding and editing user profiles in Attunity Studio, see Managing a User Profile in Attunity Studio.
An ODBC program uses AIS to access an Oracle database To access the Oracle database through AIS, the data source must be defined in a binding definition either locally or on an AIS server. In this example, it is defined with the name MYORADB. The local User Profile definition with the name NAME_R is protected with a password xA2oo4' The NAME_R User Profile definition has an entry for a data source called MYORADB with a username name and password tiger. When opening an ODBC connection, the connect string contains the following (in addition to other items): uid=scott_r;pwd= xA2oo4.
With this setting, when a query is made in MYORADB, AIS finds the entry for MYORADB in the NAME_R User Profile and finds that it should use scott/tiger to connect to Oracle.
To use a server User Profile, its name must be the same as the login name used for connecting to the server. The master password for a server User Profile, if set, must be the same as the login password for the username. If the server User Profile is not protected with a master password, then it can be used by a remote user only if the user has authenticated itself with a login password (though any local user can also use it so it is not secure). When accessing AIS with a remote client interface such as JDBC. ADO.NET, JCA and NETACX, AIS takes usernames and passwords from the server User Profile that are associated with the login user of the connection (or from the NAV User Profile if no User Profile matches the login user name). The following table shows how the User Profile and the master password are provided with each of these interfaces.
Table 282 Interface JDBC Server User Profiles and Master Passwords User Profile/Login Account Use the JDBC connection string as in: jdbc:attconnect://[usernam e: password@]machine:port/wor kspace. Also use the setUser method on the [XA]DataSource object. Also as a parameter to the DriverManager.getConnectio n method Also as a parameter to the Datasource.getConnection and XADatasource.getXAConnecti on methods. ADO.NET Use the User or UID or Username connection string options as shown here: User=<user-profile-name> Also use the Username property of the AisConnectionStringBuilder object. JCA Master Password/Login Password Use the JDBC connection string as shown in the User Profile/Login Account column. Also use the setPassword method on the [XA]DataSource object. Also as a parameter to the DriverManager.getConnection method. Also as a parameter to the Datasource.getConnection and XADatasource.getXAConnectio n methods.
Use the PASSWORD connection string option as shown here: Password=<master-password> Also use the Password property of the AisConnectionStringBuilder object.
Use the setUserName method on Use the setPassword method on the ManagedConnectionFactory the ManagedConnectionFactory class. class. Also, equivalently, through the resource adapter deployment descriptor. Also use the setUser method on the ConnectionRequestInfo class. Also, equivalently, through the resource adapter deployment descriptor. Also use the setPassword method on the ConnectionRequestInfo class. Use the Username property of the AcxClient object.
NETACX
The configuration supplied with the product installation includes the default NAV user profile. This profile is used if a user profile is not specified when accessing an application, data source or remote server machine.
Adding a User Add Authenticators Add Encryption Keys Editing a User Profile Remove an Authenticator or Encryption key
Adding a User
You can add users to Attunity Studio to grant them access to specific authenticators. Follow these steps for adding a new user. To add a new user 1. Open Attunity Studio.
2. 3.
In the Design perspective Configuration view, expand the machine where you want to set user permissions. Right click the User folder in the list and select New user. The New User screen opens.
4.
Enter a name for the user profile. If you want the user to automatically access the authenticator options, select the Use default master password check box (this is not recommended). Clear this check box to enter a specific user name and password for this user. For information on master passwords, see Setting Up a Master Password for a User.
5.
Add Authenticators
Authenticators are Data Sources, Adapters (including CDC Agents), and remote machines that the user can access. Authenticators are added in the User editor. The editor opens when Adding a User or by right clicking a user in the Configuration explorer and selecting edit. For more information on how to open the User editor, see Editing a User Profile. Follow these steps for adding authenticators. To add authenticators 1. Open Attunity Studio.
2. 3. 4. 5. 6.
In the Design perspective Configuration view, expand the machine where you want to add authenticators. Expand the User folder. Right click the user where you want to add authenticators and click Open. In the User editor, find the Authenticators section at the top of the editor. Click Add to add new authenticators for the user. Authenticators are data sources, adaptors, and machines that the user is authorized to access. The Add authenticator dialog box opens.
Managing Security
28-11
7.
Resource Information: Defines the resource to which the user is authorized. This is defined in the following fields: Resource type: Defines the resource type as Data source, Adapter or Remote machine. Resource name: The resource to which the user is authorized.
Authorization information: Defines the user authorization details. This is defined in the following fields: User name: The name of the user authorized to enter the resource. Password: The password for the resource authorization. Confirm password: Enter the password a second time to confirm that it is correct.
8.
Click OK. The new authenticator is displayed in the User editor Authenticator tab.
In the Design perspective Configuration view, expand the machine where you want to add encryption keys. Expand the User folder. Right click the user where you want to add the encryption key and click Open. In the User editor, find the Encryption keys section. Click Add to add new encryption keys for the user. Encryption keys are used to allow encrypted communication between machines. A user must have access to an encryption key to communicate with a remote machine. The Add Encryption key dialog box opens.
7.
Key name: Enter the name associated with the encryption password and which the daemon on this machine looks up. Key: Enter the encryption key. Confirm key: Re-enter the encryption key. Click OK. The new encryption key is displayed in the User editor Encryption keys tab.
Change what is displayed in the authenticators list. Edit and remove the authenticators and encryption keys that in a user profile.
You can make changes to the information you entered in the for both authenticators and encryption keys. Follow the following steps for editing a user profile. To edit a user profile 1. Open Attunity Studio.
2.
In the Design perspective Configuration view, expand the machine where you want to add encryption keys.
Managing Security
28-13
3. 4.
In the Design perspective Configuration view, expand the machine where you want to edit the user properties Expand the User Folder.
Note:
5.
Right click the user you want to make changes to and select Open. The User editor has two sections, for editing authenticators and for editing authentication keys.
6.
Double click any authenticator or encryption key in the list or select the item you want to change and click Edit. The Edit Authenticator or Edit Encryption key screen opens. This is the same as the Add Authenticators or Add Encryption Keys screens.
Note: For Authenticators, you cannot change the Resource Type field.
7.
Expand the User Folder to see a list of users available on that machine
Note:
3. 4.
Right click the user you want to remove and select Open. T Select an Authenticator from the Authenticator list or an encryption key from the list and click Remove.
Note:
Make sure to use the Remove button for the correct list. For example, if you are removing an authenticator, click the Remove button next to the authenticator list.
5.
Client Authentication
AIS clients connect to AIS using many client interfaces (for example, ODBC, ADO/OLEDB, JDBC, ADO.Net, ACXAPI). All client interfaces get a username and password as part of the connection information and this information is used to authenticate the identity of the caller (also called Principal) which may be a person or a software program such as a web server.
28-14 AIS User Guide and Reference
Client Authentication for Thin Clients Client Authentication for Fat Clients
Client authentication for fat clients is not mandatory. You can connect to either OLEDB or ODBC without authenticating. In that case, however, credentials for accessing databases, adapters and remote machines have to be specified explicitly on the connection string using the DSNPassword connect string option. For more information, see Providing Credentials in the Connection String. If the referenced user profile is protected with the default master password, then the password that is passed to the API is ignored (it is not checked for correctness). If the references user profile is protected with a non-default master password and the password provided in the API is not correct, the client connection creation fails.
Restricting Access to a User by Login User Name Restricting Access to Data with a Virtual Database
Managing Security
28-15
user name that is in the list in order to be able to connect to the workspace server and work with it. By adding a user to the list of workspace users, you grant them access to the workspace servers only. If a database on the server requires additional authentication, you need to create a user profile definition with the name of this user. When you restrict access to a specific workspace (by clearing the Allow Anonymous Client check box and specifying the users using the Workspace Access field), you must also define a user profile on the machine with the workspace for each user defined as able to access the workspace. Each user profile must have the same name as specified in the Workspace Users field. For more information, see Managing a User Profile in Attunity Studio. To define user access to a workspace 1. Open Attunity Studio.
2. 3. 4. 5. 6. 7.
In the Design perspective Configuration view, expand the machine where you want to define the user access In the Design perspective Configuration view, expand the Daemons folder. Expand the daemon with the workspace where you want to define the user access. Right click the workspace where you want to define the user access and select Open. Select the Security tab. In the Authorized Workspace Users section, select Selected users only.
8.
Click Add User to add Workspace Users (accounts) for users who can access data using this workspace.
Note:
On OpenVMS and z/OS Platforms, to define a group of users instead of a single user (so that the group name is validated by a security system), preface the name of the group in the configuration with @.
9.
In Attunity Studio, define a virtual database (V) in binding (B). See Using a Virtual Database. Edit the workspace definition. See Editing a Workspace. Select the General tab. In the Workspace binding name field, select the binding (B) where you define the virtual database. See Editing a Workspace. In the Workspace database name section, enter the name of the virtual database (V). See Editing a Workspace.
Transport Encryption
When AIS is used in client-server mode, it transfers data over the network. Except for authentication details such as passwords, all the data is transferred in without encryption and may be exposed to an eavesdropper listening on the network. In cases where the privacy of the data is important (or where the privacy of the network cannot be ensured), AIS clients can be configured to encrypt everything that is transmitted over the network. Using encryption creates unavoidable processing overhead, which is why encryption is not enabled by default. You need to weigh the risks against the processing overhead in your system to determine whether to use encryption. The transport encryption supported with AIS is called symmetric encryption which means that it is based on a secret key that is shared between the AIS client and AIS server. AIS does not handle the sharing of the encryption key, it just assumes a key was
Managing Security
28-17
selected and is known both at the client and the server. The following section called Encrypting Network Communications describes how to set up encryption.
The encryption protocol for the server machine on the client machine (see Setting a Client Encryption Protocol). The encryption communication that indicates the servers that the client will communicate with using encrypted communication (see Configuring Encrypted Communication). The user profile on the client machine, indicating that this information is encrypted (see User Profiles). The encryption key on the server machine (see Configuring the Encryption Key on the Server Machine).
For a Java thin client, you can specify encryption of client/server communication via the JDBC connect string.For more information, see the JDBC Connection String.
In the Design perspective Configuration view, expand the Machines folder and then expand the server machine where you are defining the encryption protocol. Expand the Bindings folder Right-click the binding in the Attunity Studio Design perspective Configuration view and select Open. Select the Machines tab. This figure shows the Machines tab of the Binding editor.
6.
In the Machines tab, select the client machine from the list, and click Network. The Network Settings screen is displayed.
7.
Select the protocol for encryption from the Encryption Protocol list and click OK.
Expand the Machines folder. In the Design perspective Configuration view, expand the machine where you want to configure the encryption key. Expand the User folder. Right-click the user profile where you are configuring the encrypted communication and select Open. In the User editor, select the client machine and click Add.
Managing Security
28-19
7.
Resource type: Specify the resource type as Remote machine. Resource name: Specify the communication to the machine is encrypted in the following format:
enckey: machine_name
User name: Specify the name associated with the encryption password and which the daemon on the remote machine looks up. Multiple clients may specify this name in their user profile. In this case, the user profile on the remote machine needs to list only this one username/password entry for network encryption (rather than listing and looking up multiple username/password pairs). If this user name entry is not specified, the daemon on the remote machine uses the name of the currently active user profile.
Password: Specify the password that is required in order to pass or access encrypted information over the network.
8.
Click OK.
Expand the Machines folder. In the Design perspective Configuration view, expand the machine where you want to configure the encryption key. Expand the User folder. Right-click the user profile and select Edit User. The User editor is displayed.
6.
In the Encryption Keys section, click Add. The Add Encryption Key screen is displayed.
Add Encryption Key Screen
Figure 2810
7.
Key name: Enter the name associated with the encryption password and which the daemon on this machine looks up. Key: Enter the encryption key. Confirm key: Re-enter the encryption key.
8. 9.
10. Right-click the daemon that manages the connection and select Open. 11. Select the Security tab. 12. In the Machine access area, enter RC4 in the Encryption methods field.
Managing Security
28-21
Firewall Support
AIS supports a common case of intranet firewall setup called Fixed NAT. The following describes the The Fixed NAT setup:
The AIS daemon and servers run on a machine behind a firewall with a local IP address that is not normally accessible from outside the firewall. For example, the AIS server IP address may be 10.10.10.100. The AIS clients run outside of firewall on a different network, for example, the client IP address may be something like 192.168.10.55. To access the server, a fixed network address translation is set up so the client can access an IP address that looks local and it automatically is translated into the server's IP address. For example, the client uses the IP address 192.168.10.88, which is translated by the network to 10.10.10.100. When AIS server instances start, they report their IP and port to the daemon, for example, an AIS server may report its location as 10.10.10.100:5544. The client gets this address from the daemon but cannot connect to that address since it is not directly accessible from the client's network. By setting the Fixed NAT connection option at the client side, the client ignores the IP address that the daemon returns and just uses the port number so in the example we have, upon getting the server address of 10.10.10.100:5544, the client will actually connect to 192.168.10.88:5544.
This setup also works when the fixed network address translation is restricted to a specific port range. In such case, the daemon itself and the workspaces that needs to be access must be running in that port range.
The following diagram shows the connection process with the Fixed NAT setting.
Figure 2812 Fixed NAT Firewall Connection
You can enable a Fixed NAT using NAV_UTIL or with Attunity Studio. To enable a Fixed NAT with NAV UTIL, enter the following at the command prompt:
$ nav_util -b bindurl=<host>:<port>:fixednat/<workspace> execute <ds>
To set up a Fixed NAT with Attunity Studio select the Fixed NAT check box in any dialog box that supports Fixed NAT. The following section, called Accessing a Server through a Firewall describes how to use Attunity Studio to set up Firewall Access.
Set the Fixed NAT option at the client to Select. Establish a port range for the workspace server.
Managing Security
28-23
Table 283 (Cont.) Firewall Options Firewall Traversal Technology NAT Description Attunity Connect supports Network Address Translation (NAT) only when Fixed NAT, also called static NAT or one-to-one NAT, is used. Fixed NAT uses an external IP address to connect to the daemon and starts the servers on an internal IP address. When Attunity Connect connects through Fixed NAT, the Attunity Connect client ignores the server IP address that the daemon returns and uses the port number with the original external IP address instead. When Attunity Connect connects through Fixed NAT, make sure to do the following:
Set the Fixed NAT option at the client to Select. Establish a port range for the workspace servers.
In the Design perspective Configuration view, expand the Machines folder. Expand the machine where you are defining the port range. Expand the Daemons folder and then expand the daemon with the workspace where you want to define the port ranges. Right-click the workspace you where you are defining the port range and select Open. In the Workspace editor, on the Server mode tab, Server section, select Enable port range and enter the starting and ending port numbers in the From port and To port boxes. For more information, see the Editing a Workspace, Server Mode section.
7.
This setting does not require any changes to the daemon configuration. To specify the binding information 1. On the client, specify connection information to the Windows proxy, as in the following:
<datasource name="mydata" type="remote" connect="ntproxy"/> ... <remoteMachine name="ntproxy" address="address" port="port" firewallProtocol="nat"/> 2.
On the Windows proxy, specify connection information for those data sources you want to access through the firewall on the server, as in the following:
<datasource name="mydata" type="remote" connect="acme"/> ... <remoteMachine name="acme" address="address" port="port"/>
Dynamic Credentials
In some cases, security policy or regulations dictate that credentials (user names and passwords) cannot be stored in files, encrypted or not. In other cases, applications can dynamically acquire credentials (for example, from directory services). AIS provides two mechanisms for providing credentials dynamically. These mechanisms are:
resource-name is the name of the database, application adapter or remote machine for which the authentication should be provided. user-name is the database/application/server user ID. password is the matching password for the given user-name. You can give several authenticators by repeating the same format with '&' as delimiter.
To use encryption when the resource refers to a remote machine and you are communicating with that machine, use the slightly more complex DSNPasswords syntax: DSNPasswords=<resource-name>=<user-name>/<password>[&] where:
Managing Security
28-25
resource-name is the name of the database, application adapter or remote machine for which the authentication should be provided. user-name is the database/application/server user ID. password is the matching password for the given user-name.
An example of an OLEDB connect string that uses the DSNPasswords syntax is: Provider=AttunityConnect;DSNPasswords=myOracle=scott/tiger&myDb2 =mik/maker When the resource refers to a name of a remote machine, you can also provide encryption key name and value using the following syntax: DSNPasswords=<resource-name>=<user-name>#<key-name>/<password>#< key-value>[&] where:
key-name is the name of the key the server should use. key-value is the value of the key to use when encrypting communication with the remote machine.
In the Attunity Studio Design perspective Configuration view, expand the Machines folder and expand the machine you are working with. Expand the Bindings folder. Right-click the binding you are working with and select Open. Click the Environment tab. In the Query Processor section, select Prompt DB user password . Add a user profile entry for the data source in the User Profile definition that you are using (this can be the default user profile NAV or any other user profile). Set either the username or the password in the new entry to ?.
The same procedure can be used to set up interactive prompting for a remote machine.
Note:
This feature should only be used when AIS is invoked from an interactive session. Prompting from a non-interactive process may cause the calling process stop responding, and wait for user input that will never be given. For this reason, it is not recommended to set this property in the default NAV binding.
Setting Up Impersonation
Impersonation is the ability of a server to execute in a security context that is different from the context of the process that owns the server.
The primary reason for impersonation is to cause access checks to be performed against the client's identity. Using the client's identity for access checks can cause access to be either restricted or expanded, depending on what the client has permission to do. For example, suppose a file server has files containing confidential information and that each of these files is protected by a security system. To prevent a client from obtaining unauthorized access to information in these files, the server can impersonate the client before accessing the files. Impersonation through Attunity Server is available on all platforms except for the OS/400 platform. For information on setting up inpersonization for DB2 databases on the z/OS systems, see Setting Up Impersonation for DB2. To set up impersonation 1. On the z/OS systems only, APF authorize all the steplibs in the server script. For example:
setprog... ada622-volume adavol CICS.CICS.SDFHEXCI - p390dx navroot.load - 111111 navroot.loadaut - 111111
On all platforms, on the Workspace editor, Security tab, leave the Server account field empty, as shown in the following figure.
Workspace Account Setting
Figure 2813
Managing Security
28-27
3. 4.
On the Client platform, define a user profile for the server machine with the required username and password for the remote machine in the user profile. Use Attunity Studio to add a new user authenticator with the Resource type defined as Remote, as described in Configuring Encrypted Communication.
If the site has a DB2 Exit routine, add the following line:
CALL ATYDSN3
3.
Modify the following lines in the NAVROOT.SAMPLES(DSNTIJEX) job so that the high-level qualifier is valid for the site (instead of DEV):
//ASM.SYSIN // DD DD DISP=SHR,DSN=DEV.DB2(&MEM) DISP=SHR,DSN=DEV.DB2(ATYDSN3)
If you are not using the supplied AIS DB2 Exit routine NAVROOT.SAMPLES(DSN3SATH), replace the parameter, MEM, with the name of the exit routine used at the site.
Note:
4.
Submit the DSNTIJEX job. The DSNTIJEX job builds both the exit routine and load module in the DB2 libraries at the site.
5.
Administration rights to the daemon can only be set to use a cached password.
In the Design perspective Configuration view, expand the Machines folder. Expand the machine where you are granting the administrative rights Expand the Daemons folder.
5. 6.
Right-click the daemon and select Open. In the Daemon editor, select the Security tab. This figure shows an example of the Daemon editor, Security tab.
Figure 2814
7. 8.
In the Administrator privileges area, select the Selected users only option. Use the Add Group and Add User buttons to grant Administration rights to groups and users. For more information, see the Editing a Workspace, Security section.
Note: To define a group of users on OpenVMS and z/OS Platforms, preface the name of the group in the configuration with @. Under z/OS, the group name is validated by a security system such as RACF.
The results can be seen in XML, in the Source tab. For example:
To prevent anonymous access and limit administration rights to a user called sysadmin:
<security anonymousClientAllowed="false" administrator="sysadmin" />
To allow anonymous access a server and to grant all users administration right:
<security anonymousClientAllowed="true" administrator="*" />
Managing Security
28-29
Note:
On OpenVMS and z/OS Platforms, to prevent anonymous access and limit administration rights to a user named sysadmin and to a group named sys:
In the Design perspective, in the Configuration view, expand the Machines folder. Expand the machine where you want to grant the workspace administrative rights. Expand the Daemons folder. Expand the daemon with the workspace where you want to add the administrative rights. Right-click the workspace where you are adding administrative rights and select Open. Click the Security tab.
8. 9.
In the Authorized Workspace Users section, select Selected users only. Click Add Group or Add User to grant administration rights to a group or user. For more information, see the Editing a Workspace, Security section.
Note: To define a group of users on OpenVMS and z/OS Platforms, preface the name of the group in the configuration with @. Under z/OS, the group name is validated by a security system such as RACF.
The results can be seen in XML, in the Source tab. For example:
Users must enter the correct user name and password to use a workspace. All authenticated users have workspace administration rights. This is defined as follows:
<workspace name="Navigator" description="An Attunity Server" workspaceAccount="orders" startupScript="machine_dependent" serverMode="reusable" reuseLimit="20" anonymousClientAllowed="false" administrator="*" /> </workspace>
Users must enter the correct user name and password to use a workspace. Only the user SYSADMIN has administrator rights. This is defined as follows:
<workspace name="Navigator" description="An Attunity Server" workspaceAccount="orders" startupScript="machine_dependent"1 serverMode="reusable" reuseLimit="20" anonymousClientAllowed="false" administrator="sysadmin" /> </workspace>
Notes:
The value for startupScript in these examples is machine-dependent. For example, for z/OS the startup script may be: startupScript=ATTSRVR.AB On z/OS systems, to limit administration rights to a user called SYSADMIN and a group called DEV, the following line is required: administrator="SYSADMIN,@DEV"
Managing Security
28-31
29
Backing Up AIS
This section includes the following topics:
Overview of the AIS Backup Process Backing Up and Restoring AIS Server Installation Backing Up and Restoring AIS Server Metadata Backing Up and Restoring AIS Server Scripts Backing Up and Restoring AIS Server Data Backing Up and Restoring AIS Studio Metadata
AIS Server installation (any number of instances) AIS Server scripts: (any number of instances) AIS Server data (Stream only): (any number or no instances) Attunity Studio metadata: (a single instance)
All of the directories and files in the installation. The default location for these files are in a folder or directory called Attunity/Server. The original installation file.
Place the backed-up files in a where you can easily find them. You will need them if you must restore the installation later. Follow these steps for restoring the server installation.
To restore the server installation 1. Re-install the AIS server in the original installation location with the original installation file. The default location is in a folder or directory called Attunity/Server. Make sure that you know the location of your server files if you do not use the default location. For more information, see the AIS Installation Guide for the platform you are working with.
2.
Restore the backed-up files. The reason for this two-step process is that the installation procedure sets the environment in ways that are not easy to reproduce by backing up and restoring files (e.g., the installation may register components or copy modules to various locations on the system). Depending on the scope of recovery (Just AIS or an entire system recovery), recovery may require additional activities, such as recreating user accounts, assigning permissions and system quotas. These activities are handled as part of the standard system backup procedures.
Daemon definitions User definitions Binding definitions (including environment settings) Adapter metadata for some adapters Data Source metadata for some adapters License Key
The following procedure can be used to backup and restore AIS server metadata. To back up the AIS server metadata 1. Create a list of all the Data Sources for which you provided metadata. This usually includes non-relational data sources such as VSAM, Enscribe, DISAM, RMS, IMS, DBMS).
2.
Run the following NAV_UTIL commands to back up the AIS metadata (see Using NAV_UTIL Utility for information on NACV_UTIL commands). These commands assume that you provided metadata for data sources DS1, DS2, , DSn
$ nav_util export all SYS sys.xml $ nav_util export all DS1 ds1.xml $ nav_util export all DS2 ds2.xml $ $ nav_util export all DSn dsn.xml
The set of files sys.xml , ds1.xml,, ds2.xml, , dsn.xml is the backup of the AIS server metadata. Follow this step for restoring the AIS server metadata.
To restore the AIS server metadata Run the following NAV_UTIL commands:
$ nav_util $ nav_util $ nav_util $ $ nav_util import SYS sys.xml import DS1 ds1.xml import DS2 ds2.xml import DSn dsn.xml
A more granular metadata backup and restore is possible using other options of the NAV_UTIL EXPORT command. The concept is similar to what was shown above. For information on NAV_UTIL commands, see Using NAV_UTIL Utility.
Stream Position (context) of clients against the agent (or staging area) change stream Stream position of a staging area against the agent change stream Change events stored in the staging area
To back up the server data, back up the data files. To ensure consistency of the backed-up files, disable the agent or staging area workspace before backing up or restoring data. Enable the daemon when the backup is complete. The data must also be restored with the AIS inactive, however there is also a possibility that this no longer available when the AIS is restored. In that case, a new starting point must be established For information on NAV_UTIL commands, see Using NAV_UTIL Utility.
To back up and restore the Attunity Studio, do the following 1. Backup your Studio workspace folder. The workspace folder is in the root directory where Attunity Studio is installed. The default path to this folder is Program Files\Attunity\Studio\workspace. You should back the folder up in a place where you can find it easily.
2. 3.
Install the Attunity Studio upgrade. Find the workspace folder backup and copy it to the Studio folder in the root installation directory. Replace the existing folder with your backup.
30
Transaction Support
This section contains the following topics:
Overview Using Attunity Connect as a Stand-alone Transaction Coordinator Attunity Connect Data Source Driver Capabilities Distributed Transactions Recovery Platform Specific Information
Overview
Attunity Connect serves as a distributed transaction coordinator with Two-phase Commit capability toward its Data Sources to the extent that Transaction support is implemented in the data source Drivers. Attunity Connect can be used either as a stand-alone transaction coordinator or as a sub-coordinator under another TP monitor (such as Microsoft DTC). As a transaction coordinator, Attunity Connect is called only with a Commit command and manages the two-phase commit functionality. As a sub-coordinator, Attunity Connect can be also called for a PrepareCommit function. In managing transactions, Attunity Connect does the following:
If you use the ITransactionJoin API, Attunity Connect must be a sub-coordinator under Microsoft's DTC product. DTC provides a transaction object for Attunity Connect to use. The XA_ APIs are available.
Issues transactional commands to data sources when necessary. Provides a recovery mechanism in case of system failures.
Two-phase Commit is guaranteed only when the components participating in the transaction contain no more than a single one-phase commit data source.
2. 3. 4. 5.
In Attunity Studio, expand the machine whose binding environment you want to set. Expand Bindings to view the bindings for the machine. Right-click the binding and select Open. Expand the Transaction section. In the Transaction section, do the following:
Select Use commit confirm table. Make sure that this parameter is set for each machine in the transaction. Select Convert all to distributed
6.
In the Advanced tab for each data source, check the Transaction type property for each data source. The value of this property overrides any binding environment settings. For more information, see Configuring Data Source Advanced Properties.
If Transaction type is set to datasourceDefault, the data source supports the highest possible transaction level for that data source, except for machines where the level is set to the support that is provided even if RRS is not installed.
Data Sources That Do Not Support Transactions Data Sources with One-Phase Commit Capability Data Sources with Two-Phase Commit Capability Relational Database Procedures
(and not two-phase commit) as long as one of the data sources participating in the transaction supports only one-phase commit. This is because the outside coordinator may have other data sources that support only one phase commit, or may not know to issue a PrepareCommit to Attunity Connect as its very last data source (so that Attunity Connect can commit its one-phase commit data source).
DB2 Data Source (on z/OS systems, using the DB2MFCLI driver) Informix Data Source (on UNIX and Windows platforms) Ingres II (Open Ingres) Data Source Oracle Data Source v8 and higher SQL Server Data Source (Windows Only) (using Microsoft DTC) VSAM Data Source (z/OS) under CICS (z/OS platforms with CICS TS 1.3 or higher)1
On z/OS Systems RRS (Transaction Management and Recoverable Resource Manager Services) must be installed.
The default setting of the transactionSupport property is set to the support that is provided even if RRS is not installed.
To use distributed transactions from an ODBC-based application, ensure that AUTOCOMMIT is set to 0.
Distributed Transactions
Attunity Connect is configured to enable distributed Transactions. In order for simple transactions to use the Attunity Connect distributed transaction capabilities, you can specify that Attunity Connect convert all simple transactions into distributed transactions by carrying out the following procedure. To use distributed transactions 1. Open Attunity Studio.
2. 3. 4.
In the Attunity Studio Configuration view expand the machine with the environment binding you want to set. Expand the Bindings folder and right-click the binding you are using. Expand the Transaction section. In the Transaction section, do the following:
Select Use commit confirm table. Make sure that this parameter is selected on every Server Machine in the distributed transaction. Select Convert all to distributed
Driven from the local client to recover the clients current transactions, following a crash. This is the recommended method for recovery.
Driven from the remote machine to recover all of the transactions at a given server, regardless of the availability of any client machines involved. Recovery at the server does not affect the state of the transactions as recorded in the transaction log file on the client. Thus, a client may see as needing to be resolved transactions that have already been resolved on the server. The recovery utility assumes that recovery has been performed on the server (see Recovery).
Note:
For recovery at a server to work, a transaction log file must have been defined on the server.
Under Windows, the default log file (TRLOG.TLF) is written to the same directory as the NAV.LOG file (which is specified by the <debug logFile=...> environment property). It is recommended to use the default log file and perform recovery from a PC. You can change the name and location of the log file by the <transactions logFile=...> environment property. The transaction log file has one or more entries for every transaction whose PrepareCommit or Commit commands were received by Attunity Connect but whose Commit or Rollback or Forget commands have not completed successfully. The transaction log file also includes entries that provide you with transaction status information and information to assist in heuristic recovery.
The entry is removed from the log file after the transaction has completed if Attunity Connect receives a Prepared statement from the transaction coordinator the entry exists only while a user Commit command is in progress). The following information is recorded in the transaction log file:
Information enabling you to reconnect to the data source during recovery without needing any external parameters, including:
The binding used by Attunity Connect. A timestamp field in every entry (indicating when the data source started or ended the transactional command).
You can determine whether to roll back the transaction or continue to commit the transaction, depending on the entries in the transaction log file. Before deciding whether to rollback or commit a failed transaction, you may need the information from another log (the CommitConfirm Table), which includes the following:
The state of the transaction in the transaction log file is Started Commit. All of the entries in the server machines for the data sources are Started Commit. The Data Source supports only one-phase commit and the state is Commit Issued.
This information is available using the AIS Recovery utility (see Recovery.
CommitConfirm Table
To use Data Sources that support only one-phase commit in a distributed transaction, a CommitConfirm table must be present for every one-phase commit data source. To use the CommitConfirm table 1. Execute the following CREATE TABLE statement on the data source to create the table:
CREATE TABLE CMTCNFRM ( "TRANS ID" CHAR (140) NOT NULL, "TID2" CHAR (140) NOT NULL, "CMNT" CHAR (128) )
Note:
Create the table exactly as shown (names are all uppercase and the CMNT column length is 128).
2.
In Attunity Studio binding settings, set the useCommitConfirmTable parameter to true. You can do this by opening the Attunity Studio Configuration view and expanding the machine whose environment Binding you want to set. Expand Bindings to view the bindings for the machine, right-click the binding, and select Edit Binding.
During Commit, Attunity Connect writes an entry to this table enabling Attunity Connect to determine, after a crash, whether the data source completed the Commit successfully prior to updating the status in the log file. Once a Commit is completed, the entry can be deleted.
Note:
Recovery
AIS provides a recovery utility on Windows platforms that enables you to do the following:
Examine the transaction status Initiate automatic recovery when possible Manually resolve the status of transactions that were in the middle of a Commit when a crash occurred Examine a transaction log file to determine which transactions failed
Recovery can take place starting either on the client (with automatic cascading) or on a Server Machine (cascading to its servers). To examine the status of transactions processed by Attunity Connect, use the AIS Recovery utility. The Recovery utility graphically displays the contents of the Attunity Connect transaction log file. Using the Recovery utility you can identify the status of Transactions managed by Attunity Connect. The Recovery utility enables you to:
Commit transactions that have not yet been committed Rollback transactions to their previous state Recover a transaction, based on how Attunity Connect interprets its current status Recover all the transactions, based on how Attunity Connect interprets the current status
Note:
To use the Recovery utility with a z/OS machine, define every library in the NAVROOT.USERLIB(ATTSRVR) JCL as an APF-authorized library, where NAVROOT is the high-level qualifier where AIS is installed. To use the Recovery utility 1. From the Start menu, find All Programs, Attunity Integration Suite, Server Utilities, and select Recovery Utility.
The Recovery utility is displayed, listing the transactions logged in the transaction log file and their status:
Figure 303 Recovery Utility Screen
Right-click on a transaction in the left pane or click the magnifying glass icon to get transaction button to show the transaction status. A message is displayed showing the current status of the transaction and the recommended recovery procedure. For example, the Transaction Recovery Utility Message shows that the transaction status is Commit and that no recovery is required, meaning that all the resources in the transaction were committed. If one of the resources was not committed, the recovery required would have been Commit.
3.
Right-click on a transaction in the left-hand pane or click on the appropriate button in the toolbar to select the type of recovery you want performed for the transaction. The following options are available:
Recovery is done automatically, according to the information in the log file. This is the recommended option. Commits the selected transaction. Rolls back updates made by the transaction to the state immediately before the transaction was issued.
Maintains the current situation and deletes the selected transaction information from the log file. Recovers all the transactions in the log file. Recovery is done automatically by AIS.
31
Troubleshooting in AIS
This section contains the following topics:
Troubleshooting Overview Product Flow Maps Using the Product Flow Maps for Troubleshooting Troubleshooting Methods Common Errors and Solutions
Troubleshooting Overview
AIS is an enterprise integration software that may require troubleshooting issues one that involve multiple technologies, platforms, data sources, applications and networks. This guide presents an orderly approach for troubleshooting AIS issues. Troubleshooting functions are available in Attunity Studio, command line utilities, and product logs. In some case you must use command line utilities to troubleshoot a feature because it may not be possible to use using Attunity Studio (especially if there is a problem with communications or installation). This section presents several AIS flow maps that describe common use scenarios. By identifying the appropriate flow map for your usage scenario and by following the control and data flow, you can to identify a broken flow step and what is needed to resolve the issue. Other AIS troubleshooting scenarios are described in the specific Data Source Reference, Procedure Data Source Reference, Adapters Reference, and CDC Agents Reference for the specific component that you are working with.
SQL Application: This is an application that accesses data using SQL and native (non-VM) SQL-based APIs. Examples of SQL applications include Microsoft Access and Excel, many Visual Basic applications, reporting tools such as Cognos ReportNet and Business Objects Crystal Reports, and IIS business components. SQL API: The SQL API in this scenario can be ADO (or OLEDB on Windows platforms) or ODBC. Query Processor: This is the AIS data integration engine. NOS: Native Object Store, internal storage for AIS configuration and metadata Database Driver: This is an AIS component that adapts the query processor to the specific native database APIs. There is a specific database driver for each database supported under AIS. Some database drivers are custom-built drivers that are not part of AIS. Custom-built drivers are registered in the ADDON.DEF file in the products NAVROOT/DEF directory). Native Database API: AIS access a database using its native interface. This is a component provided by the database vendor. In this usage scenario, the native database API is typically part of the database client installation that must be installed to enable database access.
The following table describes the steps in the local data access scenario map shown in the figure above.
Table 311 Flow Step A1 Local Data-Access Scenario Steps Description The SQL application loads the SQL API and uses it to retrieve and modify data.
Table 311 (Cont.) Local Data-Access Scenario Steps Flow Step A2 Description The SQL API translates standard application requests to the internal data API, also known as NAV API. The NAV API accesses the query processor. The SQL API also references the desired product configuration and other operational properties using a connection string or a similar mechanism. The query processor receives queries (SELECT, UPDATE, INSERT, DELETE, CALL) through the NAV API, devises an execution plan, optimizes the plan, and then invokes the database drivers (or possibly an SQL client component not shown here) to execute the query (using NAV API). The query processor gets configuration, metadata, and driver binding information from NOS. The database driver gets instructions through a common interface and translates the requests to the native database API. The native database API (interface) may access the underlying database locally or through the network. Examples of local access include file-system interfaces (VSAM, Enscribe, RMS, DISAM) and Oracle clients (when using a local instance).
A3
A4 A5
SQL Application: This is an application that accesses data using SQL and SQL-based APIs. Examples of SQL applications include business components deployed in J2EE application servers, Microsoft Access and Excel, many Visual Basic applications, reporting tools such as Cognos ReportNet and Business Objects Crystal Reports, and IIS business components. SQL API: The SQL API in this scenario may be thick interfaces such as ADO (or OLEDB on Windows platforms) and ODBC, or thin interfaces, such as JDBC and ADO.Net. When thin interfaces are used, the query processor component is not available (as it is part of the native product). In these cases, the SQL API communicates directly with the SQL client layer.
Query Processor: This is the data integration engine of AIS. The query processor use on the client platform is required only with the OLEDB interface. With ODBC it is optional, and with all other interfaces, it is only used on the server platform. SQL Client: The SQL client is a component that sends data access requests to a remote server for execution. The AIS SQL Client uses the same interface as an AIS database driver. This gives the query processor flexibility in deciding how to execute a query. Database Driver: This is an AIS component that adapts the query processor to the specific native database APIs. There is a specific database driver for each database supported under AIS. Some database drivers are custom-built drivers that are not part of AIS. Native Database API: AIS access a database using its native interface. This is a component provided by the database vendor. In this usage scenario, the native database API is typically part of the database client installation that must be installed for AIS to access the database.
Remote Data Access Scenario Steps Description The SQL application loads the SQL API and uses it to retrieve and modify data. The SQL API translates standard application requests to the internal data API, also known as NAV API, which accesses the query processor. The SQL API also references the desired product configuration and other operational properties via a connection string or a similar mechanism. The SQL API translates standard application requests to the internal data API, also known as NAV API, which accesses the SQL client. The SQL API also references the desired product configuration and other operational properties via a connection string or a similar mechanism. The query processor receives queries (SELECT, UPDATE, INSERT, DELETE, CALL, etc.) via the NAV API, devises an execution plan, optimizes the plan and then invokes the SQL client component (or possibly database drivers not shown here) to perform the query (using NAV API). The query processor gets configuration, metadata and driver binding information from NOS. The SQL client remote NAV API requests to an AIS SQL server where the NAV API requests are relayed to a remote query processor. The SQL client first step is to call the daemon on the server platform to ask for a server instance to call.
B2T (Thin)
B3
B4
Table 312 (Cont.) Remote Data Access Scenario Steps Flow Step B5 Description The daemon on the server platform starts a new server instance on behalf of the client or, if a server is available in a server pool immediately return its location (IP address, port and contact information). As a new instance of an AIS SQL server starts up, it opens a communication channel with the daemon informing it with its location (IP address, port and contact information).
B6
SQL Application/SQL API Issues (A1, B1) SQL API Issues/Query Processor Issues (A2, B2F)
ADO/OLEDB JDBC
ADO/OLEDB
The following are errors that may occur using the ADO/OLEDB API. Provider cannot be found. It may not be properly installed This error indicates one of the following:
The provider name in the ADO connection string is wrong. It should be AttunityConnect The AIS OLEDB provider is not installed. You can run the following command to (re)register the AIS OLEDB provider.: $ regsvr32 <NAVROOT>\bin\nav32.dll
The AIS OLEDB provider was registered but the path that is used for registration uses a network share or a substituted drive letter. When the AIS OLEDB provider is accessed from a service, the registration path must be an explicit local directory path (a UNC path or substituted drives are not allowed this is a Windows restriction).
[ODBC Driver Manager] Data source name not found This error indicates one of the following:
The data source name (DSN) provided in the ODBC connection string (or in the call to SQLConnect or SQLDriverConnect) was not defined (check the ODBC Data Source Administrator under ControlPanel->AdministrativeTools). The DSN given is defined but it is a USER DSN belonging to another user than the one used for running the SQL application.
The DSN is a FILE DSN and the path is incorrect or inaccessible (e.g., it contains a UNC path or substituted driver name and the SQL application is running as a service). The AIS ODBC driver is not properly installed. You can run the command: $ regsvr32 <NAVROOT>\bin\odnav32.dll to (re)register the AIS ODBC provider.
[ODBC Driver Manager] Specified driver could not be loaded due to system error 126 This error indicates that the AIS ODBC driver is defined but there is a problem loading the driver DLLs. This can happen if the driver DLL or one of its dependent DLLs were deleted or inaccessible.
JDBC
The following are errors that may occur using the JDBC API. java.lang.ClassNotFoundException: com.attunity.jdbc.NvDriver This error indicates that the AIS provided JDBC driver file nvjdbc2.jar does not appear on the Java class path for the SQL application.
Troubleshooting Methods
This section describes procedures and utilities that are used to check specific problems. This section includes:
Using the NAV_UTIL CHECK SERVER Utility Using the NAV_UTIL CHECK DATASOURCE Utility Using Trace Log Files
Request a server instance of the specified workspace. This returns the server location)
3. 4. 5.
Disconnect from the daemon Connect to the server instance at the determined location Disconnect from the server instance
By running this utility you can detect networking and configuration problems and get a better idea of the point where the error occurs. The complete syntax for this utility is as follows:
$ nav_util check server(<daemon-location>,<workspace-name>[,<username>,<password>])
Where:
daemon-location: The IP address (or hostname) and port where the daemon listens. For example, corpsrv.acme.com or corpsrv.acme.com:2800 workspace-name: The name of a workspace to check (the server checked will be a server of this workspace). If omitted, the default NAVIGATOR workspace will be used. username and password: The credentials to be used if access to the server requires authentication.
Note:
When used on UNIX platforms, the symbols must be prefixed with a forward slash (\) as in the following example:
$ nav_util check server\( corpsrv.acme.com:2800\)
Load the definition of the specified data source Loading the driver of the specified data source Connect to the specified data source Disconnect from the data source
By running this utility you can detect data source configuration problems and get a better idea of the point where the error occurs. The complete syntax for this utility is as follows:
$ nav_util check [-b <binding-name>] datasource(<datasource-name>])
Where:
binding-name: An optional binding name to use. If omitted, the default binding NAV is used. datasource-name: The name of the data source to check
Right click the binding and select Edit Binding. The Binding editor opens in the editor section. At the bottom of the editor, click the Properties tab. The editor displays a list of property categories. Expand the Debug category. The editor displays a list of trace options. Set the value to true for one or more of the trace options.
Note: For the binaryXmlLogLevel log, you set its level. For more information on setting the level for this log, see binaryXmlLogLevel.
Log Traces
The following table describes some of the log traces available and the type of information available in each.
Table 313 Log Trace acxTrace Available Log Traces Description Logs the input and output XML information. This lets you check whether the XML inputs and outputs are correct. You can use this trace when you use application adapters that use the Attunity XML protocol (ACX). Activates a plan file for the query analyzer. This lets you see the AIS Query Analyzers analysis of the SQL sent. This sets a log level for the binary XML log. This log provides specific debugging information and information about the API. The levels are:
analyzerQueryPlan binaryXmlLogLevel
This trace logs the driver transactions created with the AIS SDK. This trace logs the general error messages that are generated. For information on errors, see Common Errors and Solutions. This trace logs the error messages generated when working with OLEDB providers.
Table 313 (Cont.) Available Log Traces Log Trace optimizerTrace queryWarnings timeTrace transactionTrace triggerTrace Description This trace logs information about the Query Optimizer strategy. This trace logs the Query Processor warnings. This trace adds a time stamp to each event in a log. This lets you see the time frame for the various events in the log. This trace logs two- phase commit transactions in the 2PC and XA protocols and events related to those transactions. This trace logs information on triggers that are implemented. Whenever the database fires the trigger the information is logged.
New Log Entries Identifying Nodes Reading the Log Configuring Advanced Environment Parameters
Query information: The following information is logged for each RDBMS node (which represents a relational database): Elapsed Time Number of rows returned Number of bytes returned
Note:
The query information is logged for each RDBMS node in the query, not for the whole query. For example, the elapsed time for each node is entered in the log, not for the entire query.
Query processor cache information: You can set AIS to cache table data when it is accessed by a query. The log now provides the following additional information about query processor caches: Size Number of lookups Number of misses
Troubleshooting in AIS 31-9
Number of rows in the cache Number of times the cache is flushed Inefficiency threshold
Identifying Nodes
Query executions are logged in the query processor, not in the driver. The logging is carried out for each node in the query, not the query as a whole. Each node is assigned an ID number. The following figure shows the optimizer tree. This tree shows each of the nodes with assigned ID numbers. The information contained in each node is listed in the sub-branches for each node. This is useful to help identify which nodes are logged. In the log file, the nodes are identified by ID number only. You can identify the logged nodes by correlating the ID numbers in the log with the optimizer tree. The optimizer tree is part of the Optimizer Trace file.
Figure 313 XML schema of nodes and their ID numbers
Currently, the following logging information is reported for the following nodes:
optimizerTrace traceFull
You configure these parameters in Attunity Studio. To configure extended logging Open the Design Perspective in Attunity Studio.
1.
2. 3. 4.
From the Configuration view, expand the machine folder. Expand the machine with the binding that has the optimizer settings you want to change. Right-click the binding that has the optimizer settings you want to change and select Edit Binding. The Binding editor opens on the right of the screen with the Properties tab open.
5. 6. 7. 8. 9.
From the Environment Properties list, expand debug. Find the optimizerTrace property, click the right side of the Value column for the property, and select true from the drop-down list. From the Environment Properties list, expand optimizer. Find the traceFull property, click the right side of the Value column for the property, and select true from the drop-down list. Save the changes.
When the query is executed and deleted from the system, the statistics and performance tracing are logged. The following examples show how the statistics for different node types are logged.
RDBMS Node QPSTAT: RDBMS node, id = 9: QPSTAT: #Rows: 1187, Elapsed time(sec): 3.427000 QPSTAT: Total Bytes: 11870
Semi-Join Node QPSTAT: SEMI JOIN node, id = 4: QPSTAT: #Rows in cache: 1187, #Refills: 1, #Lookups: 40 QPSTAT: #Executions to right side: 4, Cache size(bytes): 1000000
Caching Node (Index Cache) QPSTAT: QPSTAT: QPSTAT: QPSTAT: CACHE node (Index cache), id = 6: #Rows in cache: 1205, #Lookups: 100 , #Hits: 2 #Flushes: 1, Cache size(bytes): 100000 Cache was not useful and canceled for this run
qpTrace
Troubleshooting in AIS
31-11
performanceTrace
You configure these parameters in Attunity Studio. To configure extended logging Open the Design Perspective in Attunity Studio. From the Configuration view on the left side, expand the machine folder. Expand the machine with the binding that has the settings you want to change. Right-click the binding that has the settings you want to change and select Edit Binding. The Binding editor opens on the right of the screen with the Properties tab open.
5. 6. 7. 8. 9.
1. 2. 3. 4.
From the Environment Properties list, expand debug. Find the qpTrace property, click the right side of the Value column for the property, and select true from the drop-down list. From the Environment Properties list, expand queryProcessor. Find the performanceTrace, click the right side of the Value column for the property, and select true from the drop-down list. Save the changes.
Notes:
You must set the value of both the qpTrace and performanceTrace properties to true to enable extended logging. To be able to view and edit the qpTrace and performanceTrace parameters in Attunity Studio, the Show advanced environment parameters option must be turn on in the Attunity Studio Preferences. For information on how to turn on this option, see Configuring Advanced Environment Parameters.
From the pane on the left of the screen, click Studio. Click the Advanced tab on the right of the screen. Select the Show advanced environment parameters check box. Click OK to close the screen and confirm the selections.
Message and Explanation Cannot shutdown a non-local IRPCD with a signal. Explanation: The oper parameter in the "irpcd shutdown" command is available only with a local daemon.
Check that a remote machine was not specified in the -l [host[:port]] parameter of the irpcd shutdown command. Check that the port number specified in the irpcd shutdown command is correct.
C001
Failed to open the IRPCD PID file. Explanation: The daemon could not open the irpcd[_port].pid file to find the process ID of the daemon to shut down. The irpcd[_port].pid file is located in the BIN directory, which is located in the directory where AIS is installed.
Check that the daemon has permission to access the irpcd[_port].pid file.
C002
Cannot shutdown IRPCD, PID cannot be found. Explanation: The shutdown operation failed because the irpcd[_port].pid file was not found in the BIN directory, which is located in the directory where AIS is installed.
Check whether the irpcd[_ port].pid file exists. Check that the daemon is running (another user may have shut down the daemon). Run the following command from a computer that is connected to the network: nav_util check irpcd(hostname[:port])
C003
Invalid PID in the IRPCD PID file (%s). Kill the daemon with a system command. Explanation: The shutdown failed because the irpcd[_port].pid file in the BIN directory, which is located in the directory where AIS is installed.
C004
Check that the account where the daemon runs has permission to access the irpcd[_ Explanation: The daemon was not able port].pid file. to create the irpcd[_port].pid file in the BIN directory, which is located in the directory where AIS is installed. AIS still runs, however when you shut down the daemon, the irpcd shutdown oper will not work. Could not open the IRPCD log file for write. Explanation: The daemon was not able to create or write to its log file.
C005
Check that the account where the daemon runs has permission to generate/write to the log file. Check the path specified for the log file in the daemon configuration. Check that there is no existing log file owned by another user at the specified location. Ensure that the disk device is not full.
Troubleshooting in AIS
31-13
Table 314 (Cont.) Client/Server Communication Error Messages Code C007 Message and Explanation Server initialization failed. Explanation: The daemon failed to start its network service. Possible Action
Check the processes that are run on the system to see whether another daemon or program is using the port specified in the -l [host[:port]] parameter of the irpcd start command. The netstat program on most platforms shows this information. Check the TCP/IP subsystem on the current machine by trying to ping it or run FTP or telnet to or from it. Check whether the daemon has privileges to use the TCP/IP services on the current machine with the designated port number.
C008
C009
IRPCD process has been terminated by user request. Explanation: This message is informational only. The daemon successfully shut down.
C00A
Application %s not found. Explanation: The requested workspace does not exist.
Check that the workspace defined in the client binding is also defined in the daemon configuration on the target server. Use the following command from a PC to check the workspace: nav_util check server(hostname, workspace) where: hostname: The host name with an optional port number (the port number is specified after a colon). workspace: The name of the workspace as defined in the client binding.
C00B
Invalid IRPCD client context. Explanation: A non-AIS program is trying to connect to the daemon.
Check the processes and kill the relevant process with a system command.
C00C
Daemon request requires a server login. Explanation: A non-AIS server or program was trying to use a daemon service that is reserved for AIS servers.
Check the processes and kill the relevant process with a system command.
C00D
Daemon request requires a client login. Explanation: The requested daemon requires a valid client login, which was not supplied.
Reissue the command and specify a username and password. Edit the User Profile in Attunity Studio to specify a valid username and password for the remote machine.
Table 314 (Cont.) Client/Server Communication Error Messages Code C00E Message and Explanation Daemon request requires an administrator login. Explanation: The requested daemon service requires an administrative login.
Possible Action
Reissue the irpcd command using the -u parameter and a valid administrator username and password. Edit the User Profile in Attunity Studio to specify a valid administrator username and password for the remote machine. Reissue the irpcd command using the -u parameter and a username and password. Enable anonymous client access by setting the AnonymousClientAllowed parameter to true in the Security section of the daemon configuration. Edit the User Profile in Attunity Studio to specify a valid username and password for the remote machine.
C00F
Anonymous client logins are not allowed. Explanation: The daemon is configured to require a valid username and password, which were not supplied.
C010
C011
Client has already timed out. Explanation: A server process was started on behalf of a client and the client has timed out before the server completed its startup.
Increase the ConnectTimeout value for the server workspace in the Workspace xxx section of the daemon configuration.
C012
Invalid username/password. Explanation: Invalid username/password supplied when logging on to the daemon. On Windows platforms, the daemon is not registered correctly.
Reissue the irpcd command using the -u parameter and a username and password. See the daemon log file for the reason that the username/password were not accepted. Edit the User Profile in Attunity Studio to specify a valid username and password for the remote machine. Make sure the daemon is started from an account that is allowed to check for system usernames and passwords. On some platforms, only a privileged account can check for authentication. On z/OS, increase the number of sub-tasks per address space in the NsubTasks parameter in the Workspace xxx section of the daemon configuration. On UNIX, increase the value of the MaxNActiveServers and/or MaxNClientsPerServer parameters in the Workspace xxx section of the daemon configuration. Try running the command later.
C014
Client connection limit reached. Try later. Explanation: The maximum number of server processes for the workspace has been reached, and none of the active servers could accept the client connection.
Troubleshooting in AIS
31-15
Table 314 (Cont.) Client/Server Communication Error Messages Code C015 Message and Explanation Failed to start server process. Explanation: The AIS daemon failed to start a server process or the started server failed upon starting up. Possible Action See the daemon and server log files for the reason the server did not start. For example, if you receive a message similar to the following: [C015] Failed to start NAVIGATOR server process: No server account name defined for anonymous client; code: -1601: SQL code: 0 If you use impersonation, check the user profile on the client. Also see C069, below. C016 Unexpected server state. Explanation: Internal error. C017 Active daemon clients exist. Shutdown canceled. Explanation: One or more clients are still connected to the daemon. C019 Contact Attunity support. Contact local support or support@attunity.com.
Wait until all the clients log off the daemon and then retry the shutdown operation. Force a shutdown by using the irpcd shutdown abort command.
Request is not granted because someone Wait for the other user to release the else is locking it. resource. Explanation: A request to lock a resource managed by the daemon was denied because another user has locked the resource.
C01A
Lock %s not found. Explanation: A request to free a resource was denied because the caller did not lock that resource. For example, another user shut down the daemon that you are working with.
C01B
Contact Attunity support. Contact local support or support@attunity.com. Contact Attunity support. Contact local support or support@attunity.com. Contact Attunity support. Contact local support or support@attunity.com. Contact Attunity support. Contact local support or support@attunity.com.
C01C C01D
Cannot update configuration without _ APPLICATIONS lock. Need to lock the application first. Explanation: Internal error.
C01F
C020
Failed in looking up host name (gethostname()) Explanation: Cannot connect to the remote machine.
Check that the machine name in the binding is correct. Check that a domain name server (DNS) is available to look up the host name. Check the TCP/IP subsystem on the machine by trying to ping it or run FTP or telnet to or from it.
Table 314 (Cont.) Client/Server Communication Error Messages Code C021 Message and Explanation Required variable %s not found Explanation: An environment variable required by the AIS server was not defined when the server started up. Possible Action
Check whether the startup script makes any changes to the environment variables used by AIS. Check whether the system-defined environment size is sufficiently large for AIS. Try to connect again. Increase the clients ConnectTimeout value for the target server workspace (in the Workspace xxx section of the daemon configuration). Check that the startup script for the workspace launches the correct version of AISt. On z/OS, increase the number of sub-tasks per address space in the NsubTasks parameter in the Workspace section of the daemon configuration. On UNIX, increase the value of the MaxNActiveServers and/or MaxNClientsPerServer parameters in the Workspace section of the daemon configuration.
C022
Server failed to connect and register with the daemon. Explanation: An AIS server started by the daemon was not able to connect or register back with the daemon.
C023
C024
Failed to create a socket. Explanation: An error occurred within the TCP/IP subsystem.
Check whether you have sufficient system privileges. Check the TCP/IP subsystem on the machine by trying to ping it or run FTP or telnet to or from it. Check whether you have sufficient system privileges. Check the TCP/IP subsystem on the machine by trying to ping it or run FTP or telnet to or from it. Check whether another program is holding the port that was specified. Check whether you have sufficient system privileges.
C025
Failed to set socket option %s Explanation: An error occurred within the TCP/IP subsystem.
C026
Failed to bind server to port %s Explanation: An AIS server or daemon was not able to bind to the specified port.
C027
Cannot create TCP service for %s Explanation: An error occurred within the TCP/IP subsystem
Check the TCP/IP subsystem on the machine by trying to ping it or run FTP or telnet to or from it.
C028
Unable to register (%s, %d, tcp) Explanation: This error may happen when a portmapper is used (host:a) but the portmapper is not available.
Enable the portmapper. Avoid using the portmapper by not using :a when starting the daemon.
C02A
Troubleshooting in AIS
31-17
Table 314 (Cont.) Client/Server Communication Error Messages Code C02B Message and Explanation Stopping the %s server - no client Explanation: A server that was started by the AIS daemon to service a client did not get a client connection request within one minute. The server terminates. Possible Action In most cases, the client was terminated by a user request, so no specific action is required. If no client can connect to the server, it may be that the server has multiple network cards and the AIS daemon is not aware of this. In this case, start the daemon with an IP address. Contact Attunity support. Contact local support or support@attunity.com.
C02C
C02D
C02E
Call made to non-existing procedure %d Verify that the client and server are using the same version of AIS. Explanation: This error typically is caused by a client of a newer version that is calling an old server. Corrupted arguments passed to procedure Explanation: Internal error. Contact Attunity support. Contact local support or support@attunity.com.
C02F
C030
Contact Attunity support. Contact local support or support@attunity.com. Contact Attunity support. Contact local support or support@attunity.com. Contact Attunity support. Contact local support or support@attunity.com. Contact Attunity support. Contact local support or support@attunity.com.
C031
C032
C033
C034
C035
Increase the process memory quota and/or add memory to the system.
C036
C037
C038
Table 314 (Cont.) Client/Server Communication Error Messages Code C042 Message and Explanation Remote call to %s failed; %s Explanation: Remote call to API failed. Possible Action Check the daemon log file. If necessary, change the level of detail that is written to the log file to help resolve the problem. Change the level of detail in the daemon configuration and run the irpcd reloadini command.
C043
Failed to connect to host %s;%s Explanation: The remote host is not correctly defined to AIS or is not working.
Check that the remote machine definition in the binding configuration. Check the daemon is up on the remote machine (NAV_UTIL CHECK). Check the network connection by trying to ping the host machine or run FTP or telnet to or from it.
C045
A system or process quota limit has been exceeded. Either increase the quota or Explanation: The server failed to create a lower the NClientsPerServer setting thread to service a client request. for the server in the Workspace xxx section of the daemon configuration. %s out of memory Explanation: Not enough memory was available to AIS to complete a requested operation.
C047
Kill unnecessary processes running on the server. Add more memory to the system. Allow the process to use more memory. Limit the number of processes that the daemon can start. If the demand for servers exceeds the number of available servers, clients get a message telling them that the maximum number of servers were reached and asking them to try again later. Check that the remote machine definition in the binding configuration. Check the daemon is up on the remote machine (NAV_UTIL CHECK). In case of a network problem, check the network connection by trying to ping the host machine or run FTP or telnet to or from it.
C066
Communication error with the server%s Explanation: Connection to the AIS daemon or server failed, or an established session with a server has failed.
C067
unexpected error occurred in server function %s Explanation: One of the server functions has exited with an exception, such as an Access Violation (a GPE) or an Invalid Instruction).
If the server contains user code, such as an AIS procedure, a user-defined data type, or a user-written provider, verify that this code is not causing the exception. Otherwise, contact Attunity support. Contact local support or support@attunity.com.
C068
fail to login daemon Explanation: The daemon is not running on the server machine.
Use the following command from a PC to check whether a daemon is running on the server: irpcd -l hostname[:port] test
Troubleshooting in AIS
31-19
Table 314 (Cont.) Client/Server Communication Error Messages Code C069 Message and Explanation Fail to get server Explanation: The AIS daemon (IRPCD) on the server machine could not start a server process to serve the client. A separate message provides more detail on why the server process could not start. There are many possible causes of this error. If the cause is not clear from the related message, see the AIS daemon log file on the server Possible Action The resolution to this error is highly dependent on the particular cause. The following are some typical causes and resolutions.
The process creation quota was exceeded. Either try again later or increase the quota or the other relevant system resources. The server startup script failed. This could be caused by some instructions in the process logon script, such as LOGIN.COM on OpenVMS, .cshrc on UNIX. The username given is not allowed to use the requested server. Use an authorized username. A limit on concurrent clients for a server has been reached. Try again later. If you use impersonation, check the user profile on the client. Also see C015.
C06A
Failed to connect to server Explanation: The server assigned to the client did not accept the client connection. A separate message provides more detail about why the server process did not accept the connection.
See the daemon and server log files for the reason that the server was not available to accept its assigned client. If a multi-threaded server is used and many clients are trying to connect to it at the same time, some may get a Connection Refused error if the TCP/IP request queue fills up.
C06B
AIS will automatically try to re-establish a connection with a server when it receives Explanation: A network failure, a server the next SQL command for the server. machine failure, or a server program failure caused the connection to abort. Once the network or machine failure is The currently active transaction is corrected, the connection to the daemon is aborted as well. re-established automatically. Disconnecting from server No conversion between server codepage Using the codepage environment variable %s and client codepage %s in the AIS environment settings, synchronize the codepages used on the Explanation: Client and server machines server and client. use different codepages. Too many codepages in use, cannot load Delete one or more of the codepages any additional codepages specified in the codepage environment variable of the server environment settings. Explanation: Multiple codepages are specified for the server. Versions of AIS client (%d) and server (%d) do not match Explanation: A new version of AIS was installed on either the client or server without using the upgrade installation procedure. Reinstall the new version of AIS.
C06C
C06D
C06E
Table 314 (Cont.) Client/Server Communication Error Messages Code C06F Message and Explanation There is no codepage defined for the server Explanation: The codepage environment variable is not specified in the environment settings. C070 Server failed to send reply to the client Explanation: Server terminated unexpectedly. C071 Connection to server %s was disconnected. Cursors state was lost. Unless the client was intentionally stopped, for example, using Control-C, contact Attunity support. Contact local support or support@attunity.com. Possible Action Specify the codepage environment variable in the AIS environment settings.
Normally, AIS automatically tries to create a new session with the server upon the next attempt to access the server. If the network Explanation: Either a network failure, a and server are accessible, the next server machine failure or a server operation should succeed, otherwise, the program failure caused the connection network and/or server machine should be to abort. The currently active transaction fixed before the connection is resumed. is aborted as well. In case of a server crash that is not related to a callable user code, contact Attunity support. Contact local support or support@attunity.com. Reconnect to server %s Explanation: This is an informational message only. The client has reestablished its connection with the server. No action required.
C072
C073
The parameters passed to the admin server are invalid: %s Explanation: Internal error.
C074
No authorization to perform the requested operation (%s) Explanation: The user or account has insufficient privileges.
Grant administrative privileges to the user or account with the Administrator parameter of the Security or Workspace sections in the daemon configuration.
C075
Failed to register daemon in the TCP/IP Check that the account running the service table daemon has the permissions to update the TCP/IP services file. Explanation: The registration of irpcd daemon in the TCP/IP services file has failed. Licensed number of concurrent users has been exceeded, try again later Explanation: The number of active AIS sessions that access local data sources exceeds the number licensed. Purchase additional concurrent user licenses.
E000
E001
The separate message indicates the cause of this error. Explanation: A lock or release operation of a global resource has failed. A There are various causes for this error, separate message provides more details. including lack of sufficient privileges or a system resource shortage.
Troubleshooting in AIS
31-21
Part VII
Utilities
This part contains the following topics:
Using Attunity SQL Utility Using the Attunity XML Utility Attunity Query Tool SQL Explain Utility Using Attunity Query Analyzer Utility Using NAV_UTIL Utility Using Attunity BASIC Import Utility
32
Using Attunity SQL Utility
This section includes the following items:
Overview Using the SQL Utility Connecting to an Attunity Server via the SQL Utility Specifying and Executing Queries Modifying Data in a Recordset Working with Chapters
Overview
AIS includes an SQL utility, which enable you to:
Execute queries, including queries that generate chapters Work with and modify chapters Execute parameterized queries Set recordset properties Work with schemas
Note:
The SQL Utility automatically sets the provider for the connection.
2.
Enter any additional connection properties you want in the Connection string field or via the Advanced button. If you change the binding configuration, via the Advanced button, the binding environment used is still the NAV binding environment.
3. 4.
By default, the cursor location is set to Server. To work with a client-side cursor engine, select Client. Click Connect to connect to the provider.
The query screen, is divided into two parts: the upper part where you specify your SQL statement, and the lower area, which contains a grid with the resulting rowset.
Figure 323 Query Screen
To execute a query Select Query|Execute, or press <F5> or click the Execute button.
Note:
You can specify a number of queries and then execute only one specific query by selecting the query to execute and pressing <F5>.
Every query screen in the SQL Utility can have its own set of parameters. To specify query parameters for the current screen 1. Select Query|Parameters or press <Ctrl>+<P>. The Set Parameters screen opens.
Figure 324 Set Parameters Screen
2. 3. 4.
Specify the value of the parameter in the Value field. Select the parameter type from the Type list. To change the parameter values, click Edit or double-click the parameter.
5. 6.
To remove a parameter, select its entry in the list and click Remove. To remove all parameters, click Remove All. To set the parameter, click OK.
Begin: Starts a transaction. Commit: Commits a transaction. Rollback: Rolls back a transaction.
1. 2.
To modify a resulting recordset Click the Modify button in the toolbar. This displays the modify toolbar in place of the edit box of the SQL. Double-click on the row whose value you want to modify. When you begin modifying a certain row, you can click Update or Cancel Update, to perform or cancel the modifications, respectively.
Note:
If you are working with BatchOptimistic locking, you must also click on UpdateBatch or CancelBatch to confirm the batch update or cancel it. In Modify mode, you can also add or delete an existing row.
3.
Modifying Chapters
With the SQL Utility you can modify chapters. Note that in ADO 1.5 the chapter is always opened with BatchOptimistic mode, which means you must apply UpdateBatch or CancelBatch after you modify the recordset. To modify a chapter, click on the Modify icon on the toolbar and apply modifications as you do for a normal recordset. Modify chapters carefully; you may end up with several open chapters. Sometimes you may need to close and open the chapter or requery the parent to see the changes.
Cursor type Lock type Cache size Maximum number of records retrieved
To set the recordset properties 1. Select Query|Recordset Properties or press <F4>. The Recordset Properties screen is displayed, as shown in the following figure:
Figure 326 Recordset Properties Screen
2.
Cursor type: Select the type of cursor from the list: ForwardOnly Keyset Dynamic Static
Note:
The default value is ForwardOnly, meaning you can only scroll forward in an ADO recordset (note that the SQL Utility caches the rowset to the Grid).
Lock type: Select the locking type from the list: Read only Pessimistic Optimistic BatchOptimistic
Cache size: Specify the size of the cache for the recordset. The default is -1, which sets the SQL Utility to use the ADO default for the cache size of the recordset. MaxRecord: Specify the maximum number of records that are retrieved. Setting -1 indicates that all rows are returned.
Note:
To save the changes in the registry, select the Save changes check box. The saved values will serve as the new default values.
3.
Click OK.
Catalogs Foreign Keys Indexes Primary Keys Procedures Procedure Columns Provider Types Statistics Tables
To view a specific schema Select the schema type from the Schema menu. The following example displays the Tables schema of the mydata data source:
Figure 327 Sample Tables Schema
You can also copy and paste from a schema grid to the Query text box in the Query screen.
33
Using the Attunity XML Utility
This section contains the following topics:
Overview
The XML Utility enables access to any AIS adapter defined on any Attunity Server. The XML utility lets you execute the connect, execute, and disconnect commands. Therefore, the XML Utility has two parts, Connect and Execute. The Connect section is used to enter information about the server with the adapter that you want to access and the type of connection. The Execute section lets you enter information necessary to execute a command or get information from the application you are working with. You click Disconnect to stop the connection with the server. You open the XML utility from the Start menu on a Windows computer. You should use the XML Utility on the same computer that Attunity Studio is installed. To open the XML Utility From Programs in the Windows Start menu, select Attunity, Server utilities, XML Utility.
Connect Properties
This section lets you enter the properties for the XML connections between the client and the adapter. These properties determine where the connection is made, the types of connections, and other information about the connection. The following table explains the available properties.
Table 331 Name Server Connect XML Description Description Select the server machine where the adapter you are working with is located. The drop-down list contains the servers that are connected to your system. Select the workspace associated with the adapter to access. Select the adapter to access. Enter the user name of the authorized user. Not necessary if using anonymous login. Enter the users password. Not necessary if using anonymous login.
Table 331 (Cont.) Connect XML Description Name Fixed NAT Description Select this check box if the machine you are working with has a fixed Network Address Translation (meaning that it is always connected to the same external IP address when accessing the Internet). For more information, see Firewall Support. Timeout (sec.) Enter the amount of time, in seconds, to wait for interactions before disconnecting. For long interactions, set a number high enough to ensure that the system does not timeout too frequently. Select this check box if you want a persistent connection. A persistent connection lets you make multiple requests on the same connection. Select this if you want to keep the connection alive until the end of the session. When this check box is cleared, the server connection will drop and reconnect as needed. Select this check box if you want the client machine to try to reconnect to the server automatically when a connection is dropped. Select this check box if you want to compress the information transmitted over the network. Select this check box to save the errors in a tracing log. Select this check box to same all actions in a tracing log. Select this check box to view the details of each step. When this is selected, each time you execute a command, a dialog box opens with details that describe the step you are carrying out.
Persistent
Keep Alive
Auto reconnect
Connect Commands
This section describes the actions (buttons) you can carry out in the Connect section of the XML Utility. You carry out these action with the buttons.
Table 332 Button Connect Commands (Buttons) Description
Click to connect to the selected Server. Click to stop the connection to the server. Click to begin a transaction. The adapter you are using must support transactions to use this command.
Click to commit a transaction after the transaction is completed. Click to rollback a transaction to its origin. You must either have Persistent connection checked or start a batch connection to start a transaction. The adapter you are using must support transactions to use this command. Click to start a group of transactions as a batch.
Start Batch
Metadata Events
Click to open the Metadata Browser. The browser lets you view the structure of the adapters metadata. Click to open the Events Listener.
Table 332 (Cont.) Connect Commands (Buttons) Button Encryption Description Click this to Set Encryption keys to allow encrypted communication between the client and the adapter.
Metadata Browser
When you click Metadata on the XML Utility, the Metadata Browser opens. The Metadata Browser provides information about the metadata for the currently selected browser. The information in the browser is set up with a tree on the left side When you click an item in the tree, information is displayed on the right side.
Figure 332 Metadata Browser
Schema: Displays the ACX metadata schema. Adapter Definition: Displays the XML formatted adapter definition. For more information on adapter definitions, see Defining the Application Adapter.
Table 333 (Cont.) Item Interactions Description The interactions (type of request) defined for the adapter are shown as subnodes for this item. Click one of interactions to display the following information about the interaction:
Events
Click this or any subnodes to display the browser readout for any events associated with this adapter. Events are only displayed if the adapter is an Events Queue adapter. Click this or any subnode to display the browser readout of the actual information contained by the application.
Records
Adapters on this workspace Click this to display the names and other information about the adapters on the current workspace.
Events Listener
The Events Listener opens when you click the Events button in the XML Utility. The events listener connects to an event queue and monitors the events in the queue. Perform the following steps to monitor events. To monitor events with the events listener 1. In the XML Utility, click Events to open the Events Listener.
Figure 333 The Events Listener
2. 3. 4. 5.
In the Event names field, enter the name of the event you want to monitor. If you want to monitor all events, enter an asterisk (*). Enter the maximum block size. The default size is 10. Enter the number of events to monitor. If you leave 0, all events will be monitored until you stop monitoring. Click Start Events to start monitoring the events. To stop the events monitoring, click Stop Events. The captured events appear at the top of the screen.
In addition, you can also save the captured events into a log file. You can do the following:
Select Save Captured events into file to save the captured events. Click Browse to select the file to save the events. Click Open Log File to open the file in the Save Captured events into files field.
Set Encryption
The XML Utility lets you set up encrypted communication between the client and the adapter. To do this you must have an encryption key available and set the encryption. Follow the steps below for setting encryption. To set encryption 1. In the XML Utility, click Encryption to open the Set Encryption screen.
Figure 334 Set Encryption
2. 3. 4.
Enter the encryption Key name. Enter the encryption Key. Click OK to save the encryption key. To erase the information click Clear.
Table 334 (Cont.) Command Select sample Description Enter a name for the input or output displayed in the XML Utility. You can save the input or output and then select it later from the drop-down list. Click this to save the currently displayed input or output as a sample. The saved sample will have the name that is currently in the Select sample field. To assign a sample a name, enter it in the Select sample field and then click Save sample. You can select a saved sample from the drop-down list to reuse the saved input or output. Delete sample Load Input Output style Input style Execute Execute Batch Deletes the current sample from the Save sample drop-down list. Click this to browse for an XML file that contains the input for the XML request. Click this to open a screen that allows you to attach an XML stylesheet to the received output. Click this to open a screen that allows you to attach an XML stylesheet for the input. Click to execute the XML request. The request you make is entered in the Input tab. Click this to executed a loaded batch. This is available only if you select Start batch in the Connect section.
Save Sample
XML Input
The input is the request that you are sending in XML form. The XML used by AIS is always wrapped with the tags <acx> </acx>. You can enter the input in the following ways:
Enter the XML request manually in the Input window. Be sure that the XML structure is correct and that it is wrapped with the tags <acx> </acx>. Load the input from an external XML file that is written in the correct structure. To load the input, click Load input and browse to the XML file you want to load. Select the file to add its contents to the Input window. Use a previously saved input sample. For more information, see Select sample and Save Sample.
XML Output
The output is returned in the Output tab. After you execute the XML request, click the Output tab to view the returned XML. The following is an example of XML output. This returned output is for a request for order information that shows the information for a sample order number 1.
- <findOrderResponse> - <ORDER ORDER_ID="0" ORDERED_BY="" N_LINES="0"> <ADDRESS ADDRESSEE="" STREET="" CITY="" ZIP="" STATE="" COUNTRY="" /> </ORDER> </findOrderResponse>
34
Attunity Query Tool
This section contains the following topics:
Query Tool Overview Getting Started with the Query Tool Using the Query Builder Creating a Query Manually Managing Queries Using the Query Tool with Transactions
Using the Query Builder lets you select the query type, tables, and other items that are manipulated in a query and add them to a table in the Query Tool interface. Selecting the items builds the query automatically. Creating a Query Manually lets you add additional parts to any SQL statement or build a new query from scratch. Any query statement types that you use when you build a statement must be supported by AIS. For more information on what type of SQL Attunity supports, see Attunity SQL Syntax.
You can save any queries created with the Query Tool. This lets you open and use any queries that you need to reuse later. The query tool also lets you work with Transactions.
Where You Can Execute Queries Opening the Query Tool The Query Builder Interface
34-1
Select the active workspace for executing SQL queries from the Select Workspace dialog box. The available workspaces are listed in the drop-down list.
Note:
If only one workspace is available, the Query Tool will open without displaying this dialog box.
3.
Click OK to open the Query Tool. The Query Tool opens in the Editor. See Query Tool Main Screen.
You will receive an error in your results if you use a query type that is not supported by the data source for your tables (for example, if your data source is not updatable and you use an Update query type, you will receive an error). For more information, see Using the Query Builder.
34-3
List of Tables, Columns, and This is a hierarchical view with tree nodes that display the tables their data sources. columns, synonyms, and views for each data source in the active workspace. Select an item in the list and then use one of the Move Item Buttons to move the item into or out of the Query Builder main window. You can also drag an item into the Query Builder main window. SQL View button Click the SQL View button to see a list of the columns in a selected table. The SQL view provides you with information about the data in each column. For more information, see Viewing Table Column Information. Use these buttons to move tables, columns or other items from the List of Tables, Columns, and their data sources. on the left side to one of the tabs in the Query Builder main window. This window lists the tables, columns, or other items that you use to build your query. This window has up to six Query Tabs, depending on the query type selected. These tabs represent different parts of a query that you build in the query builder. For example, if you want to add a WHERE clause, click the Where tab to add the columns or tables into this tab. For more information, see Using the Query Builder. The actual SQL query that is build by moving the items into the Query Builder main window is displayed here. You can select Enable manual query editing to manually edit and build the query. In this mode the query becomes the Query Editor. When you use the editor, you can use any query type that is supported by AIS. For more information about building queries, see Using the Query Builder. For information on creating or editing a query manually, see Creating a Query Manually. Use these buttons if you want to execute a transaction using the Query Tool. For more information, see Using the Query Tool with Transactions.
Select a Query Type. Select the tables and columns that you want to query and move them into the correct tab in the Query Builder main window. See The Tables Tab and The Columns Tab. If necessary, click the Where tab and add a WHERE clause. See The Where Tab. If necessary, click the Group tab to add a GROUP BY clause. See The Group Tab. If necessary, click the Having tab to add a HAVING clause. See The Having Tab. If necessary, click the Sort tab to add a SORT BY clause. See The Sort Tab. Click Execute to execute the query. In this mode the query is automatically committed. The results are automatically displayed. You can move between the
4. 5. 6. 7. 8.
Query Builder and the results by clicking the Query Builder and Query Results tabs at the bottom of the Query Tool.
Note:
The procedure described above assumes you are using the automatic mode, where the query is committed as soon as you execute it. You can also use the manual mode, where you must manually commit. This allows you to execute transactions with the Query Tool. For more information, see Using the Query Tool with Transactions.
Table: Enter a table in this column Alias: Create an alias for the table by entering a name for the alias.
For adding a table to the Tables tab, follow this procedure. To add a table to the Tables tab 1. From the list of tables on the left side, select the table you want to add. If you do not see the table in the list, find the data source for the table, and expand it by clicking the + next to it.
2.
Do one of the following to enter the selected table in the Tables tab:
Select the table you want to add to the query and click the right arrow move item button Double-click the table you want to add to the Query Builder window Drag the table into the Query Builder window.
34-5
The table is entered in the SQL Query at the bottom of the Query Tool as shown in the following figure.
Figure 344 Table Only Query
You can make changes to the queries that you build by adding more items to the Query Builder, or by removing them. For removing items, see Managing Queries.
Note:
An asterisk (*) is added to the tab when any information is entered. This reminds you that information is entered in a tab when viewing other tabs.
For adding a column to the Columns tab, follow this procedure. To add a column to the Columns tab 1. From the list of columns on the left side, select the column you want to add. If you do not see the column in the list, find the data source for the table with the column, and expand it by clicking the + next to it., then expand the table, if necessary to see the columns.
2.
Do one of the following to enter the selected column in the Columns tab.
Select the column you want to add to the query and click the right arrow move item button Double-click the column you want to add to the Query Builder window Drag the column into the Query Builder window.
The column is entered in the SQL Query at the bottom of the Query Tool as shown in the following figure.
Figure 345 Column Only Query
You can make changes to the queries that you build by adding more items to the Query Builder, or by removing them. For removing items, see Managing Queries.
Note:
An asterisk (*) is added to the tab when any information is entered. This reminds you that information is entered in a tab when viewing other tabs.
Column: Enter a column from the table that is referred to in the WHERE clause. Select the column from the Column list to the left. Operator: Select one of the following operators for the WHERE clause:
Column: Enter a column from the table that is referred to in the WHERE clause. Select the column from the Column list to the left. Operator: Select one of the following operators for the WHERE clause: Like: (For strings) Use this to indicate that the results will contain columns with parts that contain the entered value. For example, if you enter Building, all columns that contain the word Building or any part of it are returned in the results. is not: Use this to return columns that are not null. not like: (For strings) Use this to indicate that the results will not contain columns with parts that contain the entered value. For example, if you enter Building, no columns that contain the word Building or any part of it are returned in the results
Attunity Query Tool 34-7
>: (For numbers) Returns results for columns with a value that is greater than the value entered. =: Returns results for columns with a value that is equal to or the same as the value entered. <: (For numbers) Returns results for columns with a value that is less than the value entered. not between: (For numbers): Returns results for columns with a value that is not between the values entered. <>: (For numbers) Returns results for columns with a value that is different than the value entered. is: Use this to return columns that are null. <= : (For numbers) Returns results for columns with a value that is less than or equal to the value entered. >-: (For numbers) Returns results for columns with a value that is greater than or equal to the value entered. between: (For numbers): Returns results for columns with a value that is between the values entered.
Value: Enter a value from the column you entered for this WHERE clause. For example, if you have a column with data types, you can enter a data type that exists in the column. Logical: Select AND or OR if you want to add another line to the WHERE clause. AND will include items with both lines in the condition, and OR will only include items with one or the other.
For example, to create the WHERE clause, WHERE Customer Marketing Segment = HOUSEHOLD AND Comment = Had 3 complaints last year, enter the following:
For the first line: Column: Select and move the Customer Marketing Segment column into the Where tab. Operator: Select = from the drop-down list in this column. Value: Type HOUSEHOLD in this column. Logical: Select AND from the drop-down list in this column.
For the next line: Column: Select and move the Comment column into the Where tab. Operator: Select = from the drop-down list in this column. Value: Type Had 3 complaints last year in this column.
The following shows how this query may be displayed in the Query Tool.
Figure 347 WHERE Clause
For adding a WHERE clause, follow this procedure. To enter a WHERE clause 1. From the list of columns on the left side, select the column you want to be part of the WHERE clause. If you do not see the column in the list, find the data source for the table with the column, and expand it by clicking the + next to it., then expand the table, if necessary to see the columns.
2.
Do one of the following to enter the selected column in the Where tab Column.
Select the column you want to add to the query and click the right arrow move item button Double-click the column you want to add to the Query Builder window Drag the column into the Query Builder window.
3. 4. 5.
Select an operator from the drop-down list in the Operator column. Type the value you want to refer to in the WHERE clause in the Value column. If you are adding additional conditions to the WHERE clause, select either logical condition, AND or OR, from the Logical column. Note that AND is the default value for this column.
You can make changes to the queries that you build by adding more items to the Query Builder, or by removing them. For removing items, see Managing Queries.
Note:
An asterisk (*) is added to the tab when any information is entered. This reminds you that information is entered in a tab when viewing other tabs.
For adding a column to the Columns tab, follow this procedure. To add a GROUP BY clause 1. From the list of columns on the left side, select the column you want to use as the GROUP BY criteria. If you do not see the column in the list, find the data source for the table with the column, and expand it by clicking the + next to it., then expand the table, if necessary to see the columns.
2.
Do one of the following to enter the selected column in the Group tab.
Select the column you want to add to the query and click the right arrow move item button Double-click the column you want to add to the Query Builder window Drag the column into the Query Builder window.
Attunity Query Tool 34-9
The GROUP BY clause is entered in the SQL Query at the bottom of the Query Tool as shown in the following figure.
Figure 348 GROUP BY Clause
You can make changes to the queries that you build by adding more items to the Query Builder, or by removing them. For removing items, see Managing Queries.
Note:
An asterisk (*) is added to the tab when any information is entered. This reminds you that information is entered in a tab when viewing other tabs.
Column: Enter a column from the table that is referred to in the Having clause. Select the column from the Column list to the left. Operator: Select one of the following operators for the HAVING clause: Like: (For strings) Use this to indicate that the results will contain columns with parts that contain the entered value. For example, if you enter Building,
all columns that contain the word building or any part of it are returned in the results. is not: Use this to return columns that are not null. not like: (For strings) Use this to indicate that the results will not contain columns with parts that contain the entered value. For example, if you enter Building, no columns that contain the word building or any part of it are returned in the results >: (For numbers) Returns results for columns with a value that is greater than the value entered. =: Returns results for columns with a value that is equal to or the same as the value entered. <: (For numbers) Returns results for columns with a value that is less than the value entered. not between: (For numbers): Returns results for columns with a value that is not between the values entered. <>: (For numbers) Returns results for columns with a value that is different than the value entered. is: Use this to return columns that are null. <= : (For numbers) Returns results for columns with a value that is less than or equal to the value entered. >-: (For numbers) Returns results for columns with a value that is greater than or equal to the value entered. between: (For numbers): Returns results for columns with a value that is between the values entered.
Value: Enter a value from the column you entered for this HAVING clause. For example, if you have a column with data types, you can enter a data type that exists in the column. Logical: Select AND or OR if you want to add another line to the HAVING clause. AND will include items with both lines in the condition, and OR will only include items with one or the other.
For adding a HAVING clause, follow this procedure. To enter a HAVING clause 1. From the list of columns on the left side, select the column you want to be part of the HAVING clause. If you do not see the column in the list, find the data source for the table with the column, and expand it by clicking the + next to it., then expand the table, if necessary to see the columns.
2.
Do one of the following to enter the selected column in the Having tab Column.
Select the column you want to add to the query and click the right arrow move item button Double-click the column you want to add to the Query Builder window Drag the column into the Query Builder window.
3. 4.
Select an operator from the drop-down list in the Operator column. Type the value you want to refer to in the HAVING clause in the Value column.
5.
If you are adding additional conditions to the HAVING clause, select either logical condition, AND or OR, from the Logical column.
The HAVING clause is entered in the SQL Query at the bottom of the Query Tool as shown in the following figure.
Figure 3410 HAVING Clause
You can make changes to the queries that you build by adding more items to the Query Builder, or by removing them. For removing items, see Managing Queries.
Note:
An asterisk (*) is added to the tab when any information is entered. This reminds you that information is entered in a tab when viewing other tabs.
Column: Enter a column to use as the criteria for the order of the results. Order: Select ascending or descending from the drop-down list.
To add a SORT BY clause 1. From the list of columns on the left side, select the column you want to be the criteria for the result order. If you do not see the column in the list, find the data source for the table with the column, and expand it by clicking the + next to it., then expand the table, if necessary to see the columns.
2.
Do one of the following to enter the selected column in the Sort tab.
Select the column you want to add to the query and click the right arrow move item button Doubl- click the column you want to add to the Query Builder window Drag the column into the Query Builder window.
3. 4.
Select ascending or descending to determine the order of the sort. Enter any additional columns to add to the criteria. You can change the order that the columns appear by moving them up or down in list. Select a column and click Up or Down to move the selected column.
When you are finished, the SORT BY clause is entered in the SQL Query at the bottom of the Query Tool as shown in the following figure. You can make changes to the queries that you build by adding more items to the Query Builder, or by removing them. For removing items, see Managing Queries.
Note:
An asterisk (*) is added to the tab when any information is entered. This reminds you that information is entered in a tab when viewing other tabs.
Type the query manually so that you can enter the best SQL for your purpose, without leaving Attunity Studio. Add to or refine a query that you built with the Query Builder. Add to or refine a query that you created earlier.
Although the Query Builder only supports four query types, when you manually edit or create a query you can use any AIS Supported query type. If you want to use manual query editing, carry out the following procedure. To manually edit a query 1. Select the Enable manual query editing check box. The query area changes to a white background and becomes the Query Editor.
2. 3.
In the SQL Query Editor, you can type or change any of the text to create your query. Click Compile to compile the query and make it ready for execution. The Edited icon at the bottom of the Query area changes to Compile OK with a check mark to indicate that the query is compiled and ready for execution.
Attunity Query Tool 34-13
4.
Click Execute to execute the query and automatically commit it, or Click Manual to start the manual execution mode for transactions. See Using the Query Tool with Transactions.
The following figure shows the SQL Query area enabled for manual editing.
Figure 3412 Query Editor
Note:
If you create a manual query and change back to the Query Builder mode, some or all parts of the query may be lost. Therefore, you should not create a query and then return to the Query Builder to add to it.
Managing Queries
The Query Tool supports basic file management functions. This lets you do the following:
Load and use queries that were created at an earlier time. Save a query to use it at a later time. Save a query with a different name to create a new query that is based on the old one. Clear all information in the Query Builder.
The following table describes the buttons used for the file management functions.
Table 342 Button Query Tool File Management Functions Name Load Query Description Click this button to load a saved query.
Table 342 (Cont.) Query Tool File Management Functions Button Name Save Query Description Click this button to save a query. The first time you save the query, enter a name in the Save query dialog box. You can also enter a description about the query.
Save Query as
Click this button to save a query with a new name. Enter a name in the Save query dialog box. You can also enter a description about the query. See Save Query.
Clean Query Builder and Click this button to remove all entries in the Query editor Builder. This will remove all entries in all of the tabs. Check all of the tabs with entries to be sure that you want to remove them globally. Note: This only removes the entries from the Query Builder. It does not erase them physically from the data base. You can also remove one item or multiple items on a single tab. To remove items per tab: Select one item from the Tables and Columns list, or use the CTRL or SHIFT key to select multiple items and click the following button:
Click the following button to remove all of the items in the tab.
Note: If you remove a table, all columns from that table that you entered on any tab are also removed. Be sure to check all tabs with an asterisk (*) to be sure that you are not removing items you do not want removed.
Note:
All saved queries that you load into the Query Tool are opened in manual mode. If you change back to the Query Builder mode, some or all parts of the query may be lost. Therefore, you should not load a query to edit it in the Query Builder.
Scale Precision
Nullable
When you execute a transaction, you are executing it against all of the available data sources in the selected binding. Before you begin a transaction, you must make sure that all of the data sources in the binding support transactions. If any one of the data sources does not support transactions, an error message is displayed when you try to commit the transaction. However, it is possible that the system will use the auto-commit mode in some cases and that some data may be lost.
To execute a transaction, use the four buttons at the top of the Query Tool. The buttons are:
Manual: Click Manual to enter the manual mode. When this is selected, other buttons become active. When you click Execute, the query is not automatically committed. Begin: Click Begin to start a new transaction sequence. This indicates that the next set of queries that you execute are part of a transaction. Execute each query and then commit when you are finished.
Commit: Click Commit to commit the transactions that you executed after you click Begin. All of the transactions are executed and the transaction sequence ends. To start a new transaction, click Begin. Rollback: Click Rollback to roll back all the transactions that where executed after you clicked Begin. This rolls back all the transactions and ends the transaction sequence. To start a new transaction, click Begin.
For more information on creating and building queries, see Using the Query Builder and Creating a Query Manually.
35
SQL Explain Utility
This section contains the following topics:
SQL Explain Utility Overview Activating the SQL Explain Utility XML Output
Examine how a query is optimized by AIS. View the execution plan for an SQL query in XML output. Analyze an existing SQL query execution plan.
Create an indented tree view representation of the Query Plan. Format input for a graphical display application, to create a graphical view of the query plan.
The Explain command in NAV_UTIL. Using the Explain interaction in the query adapter. Automatically generating the file using the analyzeQueryPlan property.
The Query Optimizer plan for this SQL statement is displayed on the screen. The following is an example of the output that you receive for the statement select * from customer.
Figure 351 XML Output Generated When Using NAV_UTIL
A file called expn.xml is saved for each statement. By default, this file is saved to the current directory. For more information on file output, see XML Output. You can set the name of the XML file by adding the name, with the .xml file extension, in single quotes to the explain command. For example:
explain AIS.xml select * from customer
The file will now be called AIS.xml. If you want to save to another directory, include with the file name. Use the switch [-t] if you want the output to be in an text-indented tree.
Note:
For mainframe systems, you must always use the full path including the high level qualifier.
1. 2.
In the Server field, select the machine where you defined the workspace for the Query Adapter. You define the workspace in Attunity Studio. In the Workspace field, select the workspace where you defined the Query Adapter. In the Adapter field, select Query.
3. 4.
In the Connect section, Integration field, select prepareSQL. In the Input tab, enter the XML request with the statement. For example, if you want to explain the Query Optimizer plan for the statement, select * from customer, enter the following:
<prepareSql sql="select * from customer" datasource="navdemo" explain="true"/>
Figure 352 XML Utility with the Query Adapter XML Request
5.
Click Execute. You can now see the output in the Output tab.
XML Output
This section describes the XML output that is returned by the SQL Explain Utility. The XML output produces verbs. There are two main categories:
cost: the final cost of the plan sql: the original SQL statement
orderBy
orderColumns: A list of the columns by order orderColumn: Has the children, name and order
rdbms
datasource: The datasource name remotePlan: The plan built on the remote machine Parameters: The parameters that are sent to the RDBMS Metadata: The RDBMS metadata
select
columns: The columns that are in the select list. Columns are listed in the order they occur in the query.
aggregateSelect
columns: The aggregate columns. Columns are listed in the order they occur in the query.
filter
storeProcedure
datasource: The squared procedure target datasource Name: The name of the Qspec Parameters: The stored query spec parameters
rdbmsBaseTable
baseTable
Table 351 (Cont.) Tree Node Verbs Verb semiJoin Child Verbs The semiJoin verb has the following possible child verbs:
type: The join type duplicates: The number of predicate duplications cacheLimit: The maximum size, in bytes, for the cache index: The duplicated index columns leftColumns: The left columns for the index
hashJoin
type: The join type. Possible values are LOJ, CROSS buckets: The number of hash buckets estRowsCaching: The estimated number of rows that are cached before writing to disk index: The hash index columns leftColumns: The left columns for the index rightColumns: All cached right columns
cache
type: The index type. Possible values are index, subquery, or no index. expression: the cache predicate index: The indexed columns in the cache cachedColumns: The cached columns Max/Initial Buffer Size: The cache sizes (maximal or initial)
nestedJoin
expression: The nested join predicate type: The join type. Possible values are LOJ,CROSS.
set
type: The set operation type. Possible values are UNION, MINUS, INTERSECT, UNION ALL
remotePlan
distinct
table: The list verbs that describe the table in the metadata procedure: The list of procedures described in the metadata
Table 352 (Cont.) Other Verb Types Verbs table Child Verbs The table verb has the following possible child verbs:
name: The table name datasource: The datasource that he table belongs to rowsNumber: The estimated number of rows columns: The description of the columns indexes: The description of the index
procedure column
The list of procedures. The procedure verb has the following possible child verbs:
name: The column name type: The type of column uniqueValues: The estimated number of unique values in the column complexColumns: This is used if the column represents chaptered column or an expression
index
name: The index name uniqueValues: The estimated number of unique values in the index indexProperties: The index properties. Possible values are unique, clustered, hashed, pseudo, hierarchical, array. columns: The columns that the index is constructed from
expression
stringValue: The expression as a string expressionNode: The expression tree is the expression tree element. This can include the root treeNode, operator(such as = or -), constant, bindParameter.
36
Using Attunity Query Analyzer Utility
This section contains the following topics:
Overview Using the Query Analyzer Viewing the Execution Plan for an SQL Query Generating a Plan for Every SQL Statement The SQL Statement Plan The Query Analyzer Toolbar The Query Analyzer Icons Working with an Optimization Plan
Overview
AIS includes the Query Analyzer utility. This utility enables you to:
Examine how a query is optimized by AIS. Interactively view the execution plan for an SQL query. Analyze an existing SQL query execution plan.
You can automatically generate a plan for every SQL statement that is executed by any application using AIS application.
Start the Query Analyzer by selecting Start, Programs, Attunity, Server utilities, and then select Query Analyzer.
36-1
If you do not want to use the default binding, then select the binding where the data source you want to access is defined. Select File, and then Analyze SQL. The Analyze SQL Statement screen is displayed, as shown in the following figure:
4. 5.
Select the default data source (or include the data source as part of the query, as follows: ds:table). Enter the SQL you want to analyze.
Note:
6.
You can save the plan by selecting File, and then Save Plan
As.
For example, the following plan shows that a number of different strategies are used, including hash joins and semi-joins.
Figure 362 A Statement Plan
Enables you to save the SQL that generated the displayed plan.
Enables you to select the binding configuration containing the connection information for the data sources the query references.
36-3
Table 361 (Cont.) Query Analyzer Toolbar Buttons Button Menu Option View, One Level Up Function Enables you to navigate up within levels of a plan, one level at a time. Levels are created for subqueries, chapters and when part of a query is executed by a remote AIS Query Processor.
The list of retrieved expressions. If the select list includes a chapter, a link to a subordinate optimization plan is shown in the displayed box. Click on this link to display the subordinate plan. Aggregate Select: Indicates an aggregate function is included on at least one column. Returns the rows of the <select> statement, discarding any duplicate rows. Returns all the rows returned by the <select> statements, including duplicate rows. Returns rows common to both result sets returned by the <select> statements, discarding duplicate rows. Returns rows that appear only in the first <select> statement, discarding duplicate rows. Returns a rowset composed of unique rows.
For every row from the left side, an iteration of the records from the right side is performed and matching records are output. LOJ: Indicates a left outer join logic is performed.
A hash join strategy is used at this point. All the right-side rows are retrieved and broken down into buffer-sized chunks (buckets) and written to a local disk. The left-side rows are partitioned using the same key so that each partition on the left-side corresponds to the same bucket from the right side. A local join is performed between each partition of the left-side and the corresponding memory-resident bucket of the right-side. LOJ: Indicates a left outer join logic is performed.
Table 362 (Cont.) Query Analyzer Icons Icon Description A semi-join strategy is used at this point. In every iteration of the join, a number of left-side rows are retrieved and cached in memory, and a query is formulated to retrieve all of the potentially relevant right-hand rows. LOJ: Indicates a left outer join logic is performed.
The predicates used to filter the data. If one of the predicates is a subquery, a link to a subordinate optimization plan for this subquery is shown in the pop-up information panel. Click on this link to display the subordinate plan showing the subquery optimization. Ordering of the output is performed according to the ORDER BY clause in the SQL statement. A lookup cache strategy used at this point. The table is read once into memory and efficiently accessed in memory via an index that is built for it. All data is read into memory at one time and accessed in memory.
Data from the left-side of the tree is cached together with corresponding data from the right-side of the tree. On subsequent calls data is fetched from the cache if it is available. Rows returned by a subquery are cached.
The part of the SQL is processed by a remote Query Processor. A link to a subordinate optimization plan for this part of the SQL is shown in the displayed box. Click on this link to display the optimization performed by a remote Query Processor. A relational data source table is accessed. The information panel includes the known statistics for this table. A file system table is accessed. The information panel includes the known statistics for this table. A stored procedure (stored query or Attunity Connect procedure) is accessed. The name and data source where the stored procedure resides, along with result columns and parameter values are displayed.
36-5
Information Pane Controls Result The information pop-up pane is displayed. The information pane is permanently displayed (until closed, see below). Clicking an icon when a pane is displayed causes the title bar to blink (to identify the relevant pane).
Double-click an information The information pane closes. pane, or click the Close icon on the information pane.
A query optimization plan can include subordinate plans. You display a subordinate plan by clicking on a jump string, located at the lower area of the relevant additional information pane. The following diagram shows a subordinate plan, generated for a chapter, and displayed by clicking the Chapter0 jump string in the Select list information pane:
Figure 363 Subordinate Plan
The following table lists the situations where a subordinate plan is generated:
Table 364 Situation Subordinate Plans Generation Jump string in Information Pane Relevant Icon
A filter in the SQL statement includes SubQueryn (n is the nesting level) a nested SELECT statement (a subquery). Part of the query execution is done by Remote Optimization the AIS Query Processor on the remote server where the data being accessed resides. The SQL statement includes syntax for a chapter; either braces {} or parentheses (). Chaptern (n is the chapter level)
The current level of a plan is shown in the title bar. For example, a subordinate plan, two levels down (resulting from remote processing of a subquery) is displayed as:
Plan->Subquery->Remote
You can navigate through the plan levels by click the One Level Up toolbar button, or selecting View, and then One Level Up from the menu bar.
36-7
37
Using NAV_UTIL Utility
This section contains the following topics:
Overview
AIS includes the NAV_UTIL utility. It is a command-line console which enables executing a collection of commands including troubleshooting and metadata utilities.
Running NAV_UTIL ADDON ADD_ADMIN AUTOGEN CHECK CODEPAGE DELETE EDIT EXECUTE EXPORT GEN_ARRAY_TABLES IMPORT LOCAL_COPY PASSWORD PROTOGEN REGISTER SERVICE
Using NAV_UTIL Utility 37-1
Running NAV_UTIL
This section contains information on the following topics:
Basic NAV_UTIL Syntax Activating NAV_UTIL Running NAV_UTIL from a Shell Environment Running NAV_UTIL on a Java Machine
Plain text: an absence of symbols signifies a keyword, which must be entered as it appears. <>: parameters inside angular brackets need to be entered in context. For example <data_source> must be replaced with the appropriate data source on which you wish to conduct the transaction at hand. []: parameters inside square brackets are optional. You can use a combination of angular and square brackets, signifying an optional parameter that, if entered, must be in context. For example: [<data_source>] |: signifies or. For example, <bindings | datasource | remote_ machine> signifies any one of the parameters inside the angular brackets.
Activating NAV_UTIL
The syntax for activating NAV_UTIL is as follows:
Example 371 NAV_UTIL Activation
Where:
[<options>]: The following general options, which dictate the way the utility will run, such as the machine where the utility will run: -p<password>: The master password specified for the user profile with the name specified in the -u parameter (or the default NAV user profile if the -u
option is not specified). If a master password has been set, use of NAV_UTIL requires this password.
-u<name>: The name of a user profile to be used other than the default (NAV). -b<binding_name>: A binding setting other than the default (NAV) binding configuration. -nowait: Eliminates the Press any key to continue prompt. This is useful when batching multiple commands in a script. -command: Runs the utility from a shell environment. -db: Runs the utility on an Attunity Connect or Attunity Federate virtual database.
<command_name>: The name of the command you want to execute. [<utility_params>]: Command-specific parameters. If you do not supply the command parameters, you are prompted for them.
Running NAV_UTIL is platform-dependent. The following table describes how to activate NAV_UTIL on the different platforms.
Platform Windows Activation On the taskbar, click the Start button and point to Programs. Point to Attunity and select Command Line Console. Using the Command Line Console to run NAV_UTIL ensures that the environment settings for AIS are correct. UNIX and OpenVMS Execute nav_login to establish the environment. On OpenVMS, activate this command directly from DCL. On UNIX, activate this command from the shell. For details, see Running NAV_UTIL from a Shell Environment. HP NonStop If AIS is not set up to work with 2PC, make sure the TMF transaction utility is active (that is, the transaction environment property convertAllToDistributed is set to true).
If you specify a utility before the -command parameter, this utility is run prior to starting the shell environment. For example, to execute the network utility before you start the shell, run:
nav_util check network -command
Where: nowait: Eliminates the Press any key to continue prompt. This is useful when you batch multiple commands in a script. From within the shell environment, you can run any of the NAV_UTIL utilities as follows:
On the fly
Enter the command (without the NAV_UTIL at the beginning). Press Enter to execute the command.
From a file Enter the full name of a file that contains NAV_UTIL commands, prefixed by @. The file is a text file (with any extension). Multiple commands in the file must be separated by semi-colons (;). Press Enter to execute the commands contained in the file. For example, to execute the commands contained in the navutil.txt file, enter the following: Local> @C:\Program Files\Attunity\Connect \tmp\navutil.txt
Note: On z/OS systems, use single quotes () around the file name. For example: @NAVROOT.TMP.NAVUTIL1
You can access the shell environment and run a file immediately by entering the following command:
nav_util [-options] <-command @navutil_file>
Where:
options: See Activating NAV_UTIL. navutil_file: The name of the file containing the NAV_UTIL commands.
Quit the shell by typing either quit or exit at the prompt and pressing Enter.
Where java is the command to run a java class (for example, java under UNIX or jview under z/OS, and Windows). The format is case sensitive (Navutil and not navutil). Use this option to check that you can use AIS in the your Java environment. The following options are available using the Java version of NAV_UTIL:
execute: To check access to data, see EXECUTE. check: To check the client/server interaction, see CHECK.
ADDON
The ADDON command adds parameters to the $NAVROOT/def/addon.def file.
Example 372 ADDON Syntax
Where:
ADD_ADMIN
The ADD_ADMIN command enables you to specify which users can manage the machine where this command is run, from within AIS Studio.
Example 373 ADD_ADMIN Syntax
Where:
admin_username: The name of a valid user who can administer the current machine from within Attunity Studio. *: All users can administer the current machine from within Attunity Studio.
Note:
Studio.
AUTOGEN
The AUTOGEN command enables you to generate an adapter definition for specific AIS application adapters.
Example 374 AUTOGEN Syntax
Where:
adapter_name: The name for the adapter in the <adapter> statement in the binding configuration. -new answer_file: The XML file to which the specified definition template is written. You can generate an XML template for an adapter definition for an AIS application adapter. The template contains empty fields; you can use it to create an adapter definition to import to the AIS repository. answer_file: The input file with the adapter definition. -def definition_name: The name for the definition in the repository, if this is different from the adapter name. The adapter definition is automatically imported to the AIS repository. -file definition_file_name: The XML file to which the adapter definition is written. The definition is generated to an XML file. The adapter definition can be edited and then imported to the repository via the IMPORT command.
CHECK
The CHECK command checks various facets of the client/server system. You can check the following parameters:
check irpcd
This checks whether an AIS daemon is running. For example, from a UNIX machine, you can check that the daemon is active under z/OS on the production mainframe (prod.acme.com).
Example 375 check irpcd Syntax
OS/400 Platforms call prg(navroot/navutil) parm (check network(port)) Example 376 check network Syntax
check irpcdstat
This checks the status of a daemon for all workspaces, including active server processes (both those connected to a client and those that are available) and the name and location of the log file and the IRPCD configurations. Use this option to identify server processes that need terminating. You can also check the status of a specific daemon workspace.
Windows, OpenVMS, and HP NonStop Platforms nav_util check irpcdstat(<daemon_location>, <workspace> [,<username>, <password>])
z/OS Platforms NAVROOT.USERLIB(navcmD) At the prompt enter: CHECK IRPCDSTAT(<daemon_location>, <workspace> [,<username>, <password>])
daemon_location: The host name with an optional port number, where the port number is specified after a colon, as follows: machine[:port]. workspace: The name of a workspace defined in the daemon configuration. username: A user name with permission to access the server. password: The users password.
check tcpip
This checks the basic TCP/IP configuration on the machine (as far as AIS can check it).
check server
This checks whether a client can access a specific workspace and the details of the workspace configuration.
Windows, OpenVMS, and HP NonStop Platforms nav_util check server(<daemon_location>, <workspace> [,<username>, <password>])
z/OS Platforms (under TSO) NAVROOT.USERLIB(navcmD) At the prompt, enter: CHECK SERVER(<daemon_location>, <workspace> [,<username>, <password>])
daemon_location: The host name with an optional port number, where the port number is specified after a colon, as follows: machine[:port]. workspace: The name of a workspace defined in the daemon configuration. username: A user name with permission to access the server. password: The users password.
check license
This checks the license details. You can also check the license details for a specific remote machine.
check datasource
This tests the connection to a specific data source, defined in the default local binding configuration.
Windows, OpenVMS, and HP NonStop Platforms nav_util check datasource(<ds_name>[,<connect_info>])
z/OS Platforms (under TSO) NAVROOT.USERLIB(navcmD) At the prompt, enter: CHECK DATASOURCE(<ds_name>[,<connect_info>])
ds_name: The name of the data source to test, as defined in the binding configuration. connect_info: Any specific connection information to test.
CODEPAGE
CODEPAGE is used to generate a binary file from a text file with a view to mapping to and from an unsupported codepage. The result is a codepage that AIS supports.
Example 377 CODEPAGE Syntax
Where:
DELETE
DELETE is used to remove the following objects from the repository:
Where:
options: See Activating NAV_UTIL. obj_type: The type of object to be deleted. You can specify any of the following:
adapter_def[inition]: Application adapter definition. adapters: The adapters specified in the binding information. binding: A particular set of binding information. daemon: General daemon configuration settings. datasources: The data sources specified in a binding. env[ironment]: Environment properties for a particular binding. remote_machines: Remote machines defined in the binding. user: A user profile definition.
obj_name: The name of the specific object (of the type specified in the obj_type parameter) to be deleted. Use the following table to determine the obj_name to supply, dependent on the value of obj_type:
adapter_def[inition]: The name of the application adapter definition to be deleted. binding, datasources, remote_machines, environment and adapters: The name of the binding in which these objects are defined. daemon: The daemon name. user: The user name that identifies the user profile.
Tables that rely on ADD metadata ADD metadata for a table generated by the LOCAL_COPY command Stored procedures that rely on ADD metadata ADD metadata for a stored procedure generated by the LOCAL_COPY command
Views Synonyms
DELETE Data Source Objects Syntax
Example 379
Where:
options: See Running NAV_UTIL. obj_type: The type of object to be deleted. You can specify any of the following:
table: Deletes the information for the specified table. local_table: Deletes a local copy of a table. procedure: Deletes an AIS procedure. local_procedure: Deletes a local copy of a stored procedure. view: Deletes an AIS view. synonym: Deletes an AIS synonym.
ds_name: The name of the data source, as specified in the binding configuration, for the data source object that is deleted. obj_name: The name of the specific object (of the type specified in the obj_type parameter) to be deleted. Use the following table to determine the obj_name to supply, dependent on the value of obj_type:
table: The name of the table to be deleted or * to delete all the tables for the specified ds_name. local_table: The name of a local copy of a table to be deleted or * to delete all the local copy tables for the specified ds_name. procedure: The name of an AIS procedure for the specified ds_name. local_procedure: The name of a local copy of a procedure to be deleted or * to delete all the local copy procedures for the specified ds_name. view: The name of the view to be deleted or * to delete all the views for the specified ds_name. synonym: The name of the synonym to be deleted or * to delete all the synonyms for the specified ds_name.
EDIT
The EDIT command enables you to modify the contents of a repository. You can directly edit the following types of repository objects:
All configuration information for a particular machine, including all the other elements listed ahead. User profile definitions The list of available bindings Information for a particular binding, which can include information about the following:
Data sources
Information about the available daemons Information about the following for a particular data source:
Tables that rely on ADD metadata ADD metadata for a table generated by the LOCAL_COPY command Stored procedures that rely on ADD metadata ADD metadata for a stored procedure generated by the LOCAL_COPY command Views Synonyms
The object is exported to an XML file that is automatically displayed in a text editor. When the text editor is closed, the XML file is saved back to the repository. However, you cannot use this command to delete a repository entry from the text editor. To delete a repository entry, use the DELETE command. The text editor used is the native text editor for the operating system. You can change the editor in the miscellaneous environment settings, either using Attunity Studio or by adding misc edit=<path_and_name_of_editor> directly to the binding environment information.
HP NonStop Platforms navedit obj_type [<ds_name> [-native]] <obj_name>
Where:
options: See Running NAV_UTIL obj_type: The type of object to be edited. You can specify the following types of objects:
adapter_def[inition]: Application adapter definition. adapters: The adapters specified in the binding information. bindings: All available bindings and their environments. binding: A particular set of binding information. daemon: General configuration settings of a specific daemon. daemons: General configuration settings of all daemons. datasources: The data sources specified in a binding. remote_machines: Remote machines defined in the binding.
37-11
env[ironment]: Environment properties for a particular binding. table: Table definitions that rely on ADD metadata per data source. local_procedure: ADD metadata for a stored procedure generated by the LOCAL_COPY command. local_table: ADD metadata for a table generated by the LOCAL_COPY command. machine: All configuration information for a particular machine. procedure: Stored procedure definitions that rely on ADD metadata. synonym: Synonyms definitions per data source. user: A user profile definition. users: All user profile definitions.
ds_name: The name of data source for the object to be edited, as specified in the binding configuration, when the obj_type is any of: table, local_table, view, procedure, local_procedure, and synonym. -native: Extracts metadata from the native data source. This option is relevant only for viewing the definition of a local table or procedure (when the obj_type value is local_table or local_procedure). obj_name: The name of the specific object (of the type specified in the obj_type parameter) that is edited. Use the following table to confirm the obj_name to supply, according to the value of obj_type, or use * for all of the objects of the specified type:
adapter_def[inition]: The name of the application adapter definition to be edited. adapters: The name of the binding configuration. binding: The name of the binding. If not provided, the default binding (NAV) is used. bindings: No value necessary. datasources: The name of the binding configuration. daemon: The name of the daemon. daemons: No value necessary. env[ironment]: The name of the binding configuration for this working environment. local_procedure: The name of a local copy of a procedure to be edited or * to edit all the local copy procedures for the specified ds_name. local_table: The name of a local copy of a table to be edited or * to edit all the local copy tables for the specified ds_name. machine: No value necessary. procedure: The name of the procedure to be edited or * to edit all the procedures for the specified ds_name. remote_machines: The name of the binding configuration. synonym: The name of the synonym to be edited or *to edit all the synonyms for the specified ds_name.
table: The name of the table to be edited or * to edit all the tables for the specified ds_name. user: The name of the user that identifies the user profile. view: The name of the view to be edited or * to edit all the views for the specified ds_name.
Supplying a value for obj_name that does not exist in the repository will also create a template, based on the default object (such as NAV for binding or IRPCD for daemon).
EXECUTE
This section contains information on the following topics:
EXECUTE Overview
Use the EXECUTE command to test data connections and SQL statements in the interactive NavSQL environment. Running the EXECUTE command gives you the NavSQL prompt. An example of when to use the EXECUTE command is to check the available data types supported by the data source. For example, if a table in the data source requires a float, the SQL must specify a float rather than a string.
z/OS Platforms NAVROOT.USERLIB(NAVSQL) Where NAVROOT is the high-level qualifier where AIS is installed.
All Other Platforms nav_util execute [-P<password>] [-W<workspace>] <ds_name> [<filename>] Where:
password: The master password that was specified for the user profile. If the password is not supplied, you are prompted for it. workspace: The name of the binding that is used as the basis for information. If the binding is not supplied, the default AIS binding is used. ds_name: The name of the data source, as specified in the binding configuration. If you do not supply this parameter, you are prompted for it. filename: The name of a file that contains SQL statements. The SQL statements in the file are run immediately. The file is a text file (with any extension). Multiple SQL statements in the file must be separated by semi-colons (;).
NavSQL Environment
Within the NavSQL environment, you can perform the following tasks:
Execute SQL statements. Request Help and information about a data source. Change the name of the default data source.
Using NAV_UTIL Utility 37-13
Enter the command tdp with the new name that you want as the default data source. This name must have been defined in the binding configuration.
Each command entered in the NavSQL environment can span a number of lines. End the command with a semi-colon (;).
Figure 371 NavSQL Environment
Description Compose an SQL statement and end it with a semi-colon. Press Enter to execute the statement. If the SQL contains data from more than one data source, use a colon (:) to identify the data source (that is, datasource_name:Table_name).
Description Enter the full name of a file that contains the SQL, prefixed by @. Press Enter to execute the SQL. For example: NavSQL> @C:\sql\sql-query.sql; Note: For z/OS systems, use single quotes () around the filename. For example: @NAVROOT.TMP.SQL1 You can access the NavSQL environment and run a file immediately by entering the following command: nav_util execute <data_source> <file> where data_source is the name of the data source as defined in the binding and file is the name of the SQL file. If you want to run all the queries in the file without the overhead of displaying query information on the screen for each query, enter the following command: nav_util execute <data_source> -quiet <file> In this case, only queries that fail cause information to be displayed to the screen during the run. A message is displayed after all the queries have been run, stating the number of queries that succeeded and the number that failed.
Enter the command begin-transaction (optionally with either read-only or write permission) to start a transaction where you can commit a number of SQL statements together. Use commit to update the data sources with any changes, or rollback if you decide that you do not want to accept the changes.
NavSQL Commands
From within the NavSQL environment, use the HELP command to list all the available NavSQL environment commands. The following transaction-based commands are available for use within the NavSQL environment:
The following command can be used to change the default data source from within the NavSQL environment:
The following NavSQL environment commands can be used to extract information related to the data source:
describe [<ds-name>:]<table-name> [full] [index]: Provides table information. If full is specified, additional column information is provided. If index is specified, a visual representation of the record structure is displayed where available (this structure can be made available by running the NAV_UTIL EXPORT command). desc is a short form of the describe command.
describe @<proc_name>: Provides a description of a stored procedure and/or procedures that are included in an AIS procedure (the type is Application Connection (Procedure) or Natural/CICS in the binding configuration).
37-15
list catalogs [<mask>]: Lists details about all the catalogs, or a subset of the catalogs when a mask is supplied. list cata or list catas are short forms of the list catalogs command.
list columns [<table-mask>] [<column-mask>]: Lists details about the columns of the data source. You can list details about specific columns of the data source and about columns in specific tables belonging to the data source. You must also specify if the data source management system is case sensitive. list procedures [<mask>]: Lists details of all the AIS procedures, or a subset of the procedures when a mask is supplied. list procedure_col [<proc-mask>] [<column-mask>]: Lists details about the columns referenced by the AIS procedures. You can list details about specific columns and about columns in specific procedures. You must also specify if the data source management system is case sensitive. list special-col [<mask>]: Lists details about all the columns with special characteristics (for example key fields), for the data source or a specific table belonging to the data source when a mask is supplied. list statistics [<mask>]: Lists statistics about all the tables, or a subset of the tables when a mask is supplied. list synonyms: Lists details about all the synonyms. list tables [<mask>]: Lists details about all the tables, identified by the type of table: views, synonyms and system tables. A subset of the tables is displayed when a mask is supplied. list tab or list tabs are short forms of the list tables command.
list tables @*: Lists all procedures included in an AIS procedure (type is Application Connection (Procedure) in the binding configuration). list tab or list tabs are short forms of the list tables command.
show datatype [<dt-id>]: Lists details about all the data types available, or a specific data type when a number (the dt-id parameter) is supplied. list views: Lists details about all the views. native_describe [<ds-name>:]<table-name> [full] [index]: Runs the describe command of the data source. If full is specified, additional column information is provided. query[_describe] <query>: Provides query information, including the number of fields in the query with the field descriptions and the number of parameters expected by the query.
EXPORT
The EXPORT command enables you to export the contents of a repository to an XML document. You can export the following types of objects from the repository to an XML file:
All configuration information for a particular machine User profile definitions The list of available bindings
Information for a particular binding, which can include information about the following:
Information about the available daemons Information about the following for a particular data source:
Tables that rely on ADD metadata ADD metadata for a table generated by the LOCAL_COPY command Stored procedures that rely on ADD metadata ADD metadata for a stored procedure generated by the LOCAL_COPY command Views Synonyms
In addition, you can use the EXPORT utility to export metadata from a data source where the metadata is readable by AIS (such as Oracle or Sybase metadata). The metadata is converted to XML, which is editable. When running EXPORT, use the -native option, as described below. After editing, import the metadata to a local repository for the data source. For information about setting up this feature in Attunity Studio, see Extended Native Data Source Metadata.
Example 3710 EXPORT Syntax nav_util [<options>] export <obj_type> [ds_name [-native]] <obj_name> <xml_file> | con:
Where:
options: See Running NAV_UTIL obj_type: The type of object to be exported. You can specify the following types of objects:
adapter_def[inition]: Application adapter definition. adapters: The adapters specified in the binding information. all: All configuration information for a data source. bindings: All available bindings and their environments. binding: A particular set of binding information. daemon: General configuration settings of a specific daemon. daemons: General configuration settings of all daemons. datasources: The data sources specified in a binding. remote_machines: Remote machines defined in the binding.
37-17
env[ironment]: Environment properties for a particular binding. table: Table definitions per data source. local_procedure: ADD metadata for a data sources stored procedure generated by the LOCAL_COPY command. local_table: ADD metadata for a table generated by the LOCAL_COPY command. machine: All configuration information for a particular machine. procedure: Stored procedure definitions that rely on ADD metadata. synonym: Synonyms definitions per data source. user: A user profile definition. users: All user profile definitions. view: AIS view on a data source.
ds_name: The name of a data source for the object to be exported, as specified in the binding configuration, when the obj_type is any of: table, local_table, view, procedure, local_procedure, and synonym. -native: Extracts metadata from the native data source where the metadata is readable by AIS (such as Oracle or Sybase metadata). The metadata is converted to XML, which is editable. Use the -native option to view the native metadata. This option is relevant only for exporting a table or stored procedure (when the obj_ type parameter is a table or procedure). For information about setting up this feature in Attunity Studio, see Extended Native Data Source Metadata. If the data source is an ADD data source, the metadata is extracted from the repository and from information specific to the driver for that data source, which is usually retrieved from the data source at runtime. For example, the ISN value in Adabas or RFA column in RMS.
obj_name: The name of the specific object (of the type specified in the obj_type parameter) that is exported. Use the following table to confirm the obj_name to supply, dependent on the value of obj_type, or use * for all of the objects of the specified type
adapter_def[inition]: Application adapter definition. adapters: The adapters specified in the binding information. all: All configuration information for a data source. bindings: All available bindings and their environments. binding: A particular set of binding information. daemon: General configuration settings of a specific daemon. daemons: General configuration settings of all daemons. datasources: The data sources specified in a binding. remote_machines: Remote machines defined in the binding. env[ironment]: Environment properties for a particular binding. table: Table definitions per data source. local_procedure: ADD metadata for a data source stored procedure generated by the LOCAL_COPY command.
local_table: ADD metadata for a table generated by the LOCAL_ COPYcommand. machine: All configuration information for a particular machine. procedure: Stored procedure definitions that rely on ADD metadata. synonym: Synonyms definitions per data source. user: A user profile definition. users: All user profile definitions. view: An AIS view on a data source.
xml_file: The XML file to which the specified object is exported (output). If a file name is not specified, the output is displayed on the terminal. con: To send the output to the console instead of to an XML file.
Note: con: is for Windows platforms only. The colon (:) is a necessary part of the syntax.
To back up Attunity server definitions 1. Run the following command: nav_util export all sys out.xml where out.xml is the output file (including the path) with the saved configuration. The output file contains the complete configuration settings for the server machine, with the exception of the metadata definitions for data sources that require AIS metadata.
2.
Run the following command: nav_util export all <ds_name> * out1.xml where ds_name is the name of a data source in the binding with AIS metadata defined for it.
3.
Repeat the previous step for every data source with AIS metadata defined for it, changing the name of the output file for each data source. The collection of output files together constitutes a complete backup of all the AIS definitions on the machine.
GEN_ARRAY_TABLES
The GEN_ARRAY_TABLES command creates virtual tables for Adabas, CISAM, DBMS, DISAM, Enscribe, RMS, and VSAM arrays from existing metadata. The Adabas database can be accessed using ADD or Predict. Virtual tables are created automatically by AIS when the metadata is created for the data source. For more information, see Using Virtual Tables to Represent Hierarchical Data.
Example 3711 GEN_ARRAY_TABLES Syntax nav_util gen_array_tables <ds_name> <table>
Where:
37-19
ds_name: The data source name, as specified in the binding configuration. table: The name of the table in the repository that is defined with an array. Use wildcards if you want to generate virtual tables for more than one table.
IMPORT
The IMPORT command enables you to import the contents of a valid XML document (formatted correctly for AIS) to the repository. You can import the following types of objects to the repository from an XML file:
User profile definitions Binding information Environment settings (per workspace) Daemon configuration information Table definitions that rely on ADD metadata (per data source) View definitions (per data source) Stored procedures that rely on ADD metadata Synonym definitions (per data source) Adapter definitions Metadata generated by the LOCAL_COPY command
Example 3712 IMPORT Syntax nav_util [<options>] import <name> <xml_file> | con:
Where:
options: See Activating NAV_UTIL name: The name of the application adapter or data source for the object to be imported, as specified in the binding configuration, when the object is any of: table, local_table, view, procedure, local_procedure, and synonym or adapter. The value of ds_name is used and not the value of the data source attribute in the XML file. The data source value is generated when using NAV_UTIL EXPORT. Thus, for example, if you export a table definition and then want to import the definition to another data source, you do not need to change the data source attribute value in the XML file before imported the file.
xml_file: The XML file to which the specified object is exported (output). If a file name is not specified, the output is displayed on the terminal. con: Sends the output to the console instead of to an XML file.
Note: con: is for Windows platforms only. The colon (:) is a necessary part of the syntax.
When importing the following types of objects, you must specify SYS as the ds_name entry:
Binding information
Daemon configuration information User profiles Working environment configuration Adapter definitions
IRPCDCMD
The IRPCDCMD is a utility for the z/OS systems that is used to perform management tasks on the daemon. This utility can be used from the IRPCDCMD REXX. To use this utility, execute the IRPCDCMD script, which is located in the navroot\userlib directory. When you get the prompt, you can invoke the required command. For example:
> -l 183.22.12.10 status
The IRPCDCMD utility uses the following syntax: irpcd [-l daemon_location] [-u username] [-p password] command [arguments] The following commands are available:
APPLIST [app-name or app-mask] RELOADINI RESETLOG SHUTDOWN [<ABORT|OPERATOR> ["why..."]] STATUS [workspace-name] REFRESH [workspace-name] KILL [workspace-name] TEST ENABLE [workspace-name] DISABLE [workspace-name]
LOCAL_COPY
The LOCAL_COPY command extracts the data definition of a table or stored procedure from the data source catalogs and saves it to the repository. This utility enables you to improve query performance by creating a copy (snapshot) of the data source metadata, which is used instead of the data source metadata. The copy must be on the same machine as the data.
Example 3713 LOCAL_COPY Syntax nav_util local_copy <ds_name> <src_table>
Where:
ds_name: The data source name, as specified in the binding configuration. src_table: The source table name (wildcards are allowed).
Using NAV_UTIL Utility 37-21
PASSWORD
The PASSWORD command allows you to define a master password.
Example 3714 PASSWORD Syntax nav_util password [-u<username>] <new_password>
If you have an existing password, you are prompted to specify it before defining the new master password.
PROTOGEN
The PROTOGEN command generates C/C++ header or DTD/XSD files for an adapter schema.
Example 3715 PROTOGEN Syntax nav_util nav_util nav_util nav_util protogen protogen protogen protogen <xml_schema_file> <xml_schema_file> <xml_schema_file> <xml_schema_file> [<output_directory>] [-verbose] -dtd <dtd_file> [<dtd_root>] -xsd <xsd_file> -wsdl <wsdl_file>
REGISTER
Use this command to register the software directly. You need to register the software before you can access data sources on this machine. To the software, you must have a Product Authorization Key (PAK) file, called license.pak. A PAK is normally supplied by the Attunity vendor. It contains details such as the product expiration date (if any), the maximum number of concurrent sessions allowed, which drivers you are authorized to use, and other information. The PAK is supplied to you in electronic form, and you must register it before you can use the product.
Note: You cannot register two licenses at the same time. If you register a product, the new license will overwrite the old license. If you want to register a new product and continue using the previously registered products, then request a single license for all of the products.
For details, refer to the post-installation part of the Attunity Server Installation Guide for the platform on which you installed the software.
SERVICE
The SERVICE command manages NAV_UTIL service registration, allowing it to be a service, similar to a daemon.
Note:
Example 3716 SERVICE Syntax nav_util service register <service-name> <nav_util-options...> nav_util service unregister <service-name> nav_util service start <service-name> 37-22 AIS User Guide and Reference
SVC
The SVC command starts a server on the port specified.
Example 3717 SVC Syntax nav_util svc :<port-number>
TEST
For use only when instructed by Attunity Support.
UPDATE
The UPDATE command collects information about tables, indexes, and, optionally, column cardinalities for use by the AIS Query Optimizer. Each time the utility is run, the resulting statistics overwrite previous statistics. This command can be used for all data sources (both those that require ADD metadata and relational data sources). For relational data sources, an entry is created in the AIS repository for the data source. An example of when statistics would be used for a relational driver is with SQL/MP, to generate index statistics in addition to the column statistics generated by SQL/MP.
Caution:
Executing the UPDATE command with the reset option deletes all statistics on the specified table.
z/OS Platforms NAVROOT.USERLIB(navcmD) At the prompt, enter: update[_statistics] <ds_name> <table_name> [EXACT | rows <row_num>] [+All | [column-options] [index-options]]
All Other Platforms nav_util update[_statistics] <ds_name> <table_name> [EXACT | rows <row_num>] [+All | [column-options] [index-options]]
Where:
37-23
ds_name: The name of the data source, as specified in the binding configuration.
Note:
The data source must be local. For a remote data source, run the utility on the remote machine.
table_name: The name of the table. You can specify the wildcards as part of the table name:
Wildcards per Platform Platform(s) Windows UNIX (the single quotes are part of the syntax) OpenVMS and z/OS
Table 371
If you use a wildcard as part of the table name, only the default -All parameter is available (the column-options and index-options parameters are invalid).
Note:
EXACT: The exact statistical information is returned. Note that this option does not work with large tables. rows row_num: The number of rows in the table. This value is used to shorten the time to produce the statistics, assuming that the value specified here is the correct value, or close to the correct value. It is recommended to specify a value for rows. The number of unique values per index is also returned. When the number of rows in the table is not provided, the number of rows used is determined as the maximum value between the value specified in the tuningdsmMaxBufferSize parameter of the environment settings and the value set in the nRows attribute (specified as part of the metadata for the data source).
+All: Information about the table, indexes, partial indexes and columns is included in the output. The default is that only information about the table and indexes is included in the output and not information for partial indexes and columns. column-options: The following column options can be specified:
+fcol_name1 +fcol_name2: Returns information only about the specified table columns. +f*: Returns information about all the table columns (on UNIX, specify +f'*').
+i1 +i2 : Returns information only about the specified indexes and partial indexes. +i*: Returns information about all the table indexes (on UNIX, specify +i'*').
If you want information about all the indexes and only some of the partial indexes, you can run the utility twice: once with the -All option and once with the +i1, +i2,... option for the required partial indexes.
Estimates the number of rows in the NATION table of the data source. The result is based on the number of nRows specified as part of the metadata for the data source and the amount of available memory as specified by the dsmMaxBufferSize parameter of the environment settings.
nav_util update disam nation rows 100
Estimates the number of rows in the NATION table of the data source. The result is based on the number of rows specified (100). If the value specified here is the correct value, or close to the correct value, the time to calculate the statistics is shortened.
nav_util update disam nation EXACT
Exact statistics for the NATION table of the data source are returned.
UPD_DS
To update the default binding configuration, use the UPD_DS command. This enables you to update the binding only with changes that involve specifying the connection information.
Example 3720 UPD_DS Syntax nav_util [<options>] upd_ds <ds_name> <ds_type> <connect_string>
Where:
options: See Activating NAV_UTIL. ds_name: The name of the data source to be added to the binding configuration. ds_type: The name of the driver that is used when you access the data source. connect_string: The connect string to be used to access the data source.
UPD_SEC
To update the default user profile, use the UPD_SEC command. This enables you to update the user name and password for both a specific data source or machine in a user profile. Use this command if you need to update a user profile on a non-Windows platform.
Example 3721 UPD_SEC Syntax nav_util [<options>] upd_sec <ds_name> | -machine <machine>[:<port>] [-u<username>] [-p<password>]
Where:
37-25
ds_name: The name of the data source, as specified in the binding configuration, to which the user profile is related. machine[:port]: The name and, optionally, the port of the data source to which the user profile is related. username: The user name to access the data source or machine. password: The password to access the data source or machine.
VERSION
The VERSION command enables you to check which version of AIS is running on the machine.To display the version of the AIS installation, use the following command line:
Example 3722 VERSION Syntax nav_util version [-history]
Note:
On UNIX platforms, the history flag prints details of the version, such as the build and installation dates, and lists previous versions of AIS that were installed on the machine.
VERSION_HISTORY
The VERSION_HISTORY command returns a report of installations, upgrades, and patches installed on the machine.
Example 3723 VERSION_HISTORY Syntax nav_util version_history
VIEW
Note:
The VIEW command enables you to view the contents of a repository. With this command, you can see the definitions of the following types of repository objects:
All configuration information for a particular machine, including all the elements listed below. User profile definitions. The list of available bindings. Information for a particular binding, which can include information about the following:
Tables that rely on ADD metadata ADD metadata for a table generated by the LOCAL_COPY command Stored procedures that rely on ADD metadata ADD metadata for a data sources stored procedure generated by the LOCAL_ COPY command. Views Synonyms
Example 3724 VIEW Syntax nav_util [<options>] view <obj_type> [<ds_name> [-native]] <obj_name>
Where:
options: See Activating NAV_UTIL. obj_type: The type of object whose definition is displayed. You can specify the following types of objects:
adapter_[def]inition: Application adapter definition. adapters: The adapters specified in the binding information. binding: A particular set of binding information. bindings: All available bindings and their environments. datasources: The data sources specified in a binding. daemon: General configuration settings of a specific daemon. daemons: General configuration settings of all daemons. env[ironment]: Environment properties for a particular binding. local_procedure: ADD metadata for a stored procedure generated by the LOCAL_COPY command. local_table: ADD metadata for a table generated by the LOCAL_COPY command. machine: All configuration information for a particular machine. procedure: Stored procedure definitions that rely on ADD metadata. remote_machines: Remote machines defined in the binding. synonym: Synonym definitions per data source. table: Table definitions per data source. user: A user profile definition. view: An AIS view on a data source.
ds_name: The name of data source, as specified in the binding configuration, for the object whose definition is displayed when the obj_type is any of: table, local_table, view, procedure, local_procedure, and synonym.
37-27
-native: Extracts metadata from the native data source. This option is relevant only for viewing the definition of a table or stored procedure (when the obj_type value is table or procedure). You usually define this feature in Attunity Studio. obj_name: The name of the specific object (of the type specified in the obj_type parameter) that is displayed. Use the following table to confirm the obj_name to supply, dependent on the value of obj_type, or * for all of the objects of the specified type:
adapter_def[inition]: The name of the application adapter definition to be viewed. adapters: The name of the binding configuration. binding: The name of the binding. If not provided, the default binding (NAV) is used. bindings: No value necessary. datasources: The name of the binding configuration. daemon: The name of the daemon. daemons: No value necessary. env[ironment]: The name of the binding configuration for this working environment. local_procedure: The name of a local copy of a procedure to be viewed, or * to view all the local copy procedures for the specified ds_name. local_table: The name of a local copy of a table to be viewed, or * to view all the local copy tables for the specified ds_name. machine: No value necessary. procedure: The name of the procedure to be viewed, or * to view all the procedures for the specified ds_name. remote_machines: The name of the binding configuration. synonym: The name of the synonym to be viewed, or * to view all the synonyms for the specified ds_name. table: The name of the table to be viewed, or * to view all the tables for the specified ds_name. user: The user name that identifies the user profile. view: The name of the view to be viewed, or * to view all the views for the specified ds_name.
XML
The XML command sends an XML request directly to AIS for processing, much like execute sends an SQL query directly to AIS. XML is particularly suited to troubleshooting, by enabling system administrators and DBAs to check the AIS XML dispatchers handling of queries specified in XML documents.
Example 3725 XML Syntax nav_util xml <fin>.xml | con: <fout>.xml | con:
Where:
fin.xml: The file name with the input XML. con: To read the input from the keyboard.
Note: con: is for Windows platforms only. The colon (:) is a necessary part of the syntax.
fout.xml: The file name of the output XML. If a file name is not specified, the output is displayed on the terminal. con: To send the output to the console instead of to an XML file.
Note: con: is for Windows platforms only. The colon (:) is a necessary part of the syntax.
XML Samples
AIS processes XML requests (including queries) that are specified only in documents formatted in the syntax specific to AIS. The general structure of this syntax is as follows:
Example 3726 XML Sample header> <request-step1></request-step1> ... <request-stepn></request-stepn> </header>
The following input file is formatted according to the requirements of the AIS XML implementation and specifies the SQL query select * from navdemo:nation.
Example 3727 XML Input FIle Sample <?xml version="1.0"?> <acx> <connect adapter="query" /> <execute> <query id="1"> select * from navdemo:nation </query> </execute> <disconnect/> </acx>
Running the XML command with the above file as input generates the following output file:
Example 3728 XML Output File Sample <?xml version=1.0 encoding=ISO-8859-1?> <acx type=response> <connectResponse idleTimeout=0></connectResponse> <executeResponse> <recordset id=1> <record N_NATIONKEY=0 N_NAME=ALGERIA N_REGIONKEY=0 N_COMMENT=New Distributor <record N_NATIONKEY=1 N_NAME=ARGENTINA N_REGIONKEY=1
/>
37-29
N_COMMENT=Far Away <record N_NATIONKEY=2 N_NAME=BRAZIL N_REGIONKEY=1 N_COMMENT=Nearby ... </recordset> </executeResponse> </acx>
/> />
38
Using Attunity BASIC Import Utility
This section contains the following topics:
Overview
The BAS_ADL import utility produces ADD metadata from BASIC mapfiles. This utility currently runs on OpenVMS platform only.
Note:
Activation of this utility is based on environment symbols defined by the login file residing in the BIN directory under the directory where AIS is installed. You can replace the environment symbol with the appropriate entry.
Where:
filelist: A list of BASIC files containing file descriptions and text libraries that will be converted into ADD. If you try to pass BASIC code that is not part of the file descriptions, you will receive errors as the utility tries to parse the additional information. Separate the files in this list with commas (white space is not allowed). You can use wildcards for files in the file list.
ds_name: The name of an AIS data source defined in a binding configuration. The imported metadata is stored as ADD metadata in the repository for this data source. filename_table: A file containing a list of tables and their file names. If a table is not found in the file, or this argument is not specified (as its use is optional), then the file name for the table is <table>_FIL. variant_table: A file containing a list of variants with selector fields and their definitions. Each logical line has the following format:
Using Attunity BASIC Import Utility 38-1
All the val# arguments must be surrounded by double quotes. If a val# argument contains a comma or double quotes, then the character must be doubled. If a logical line is to be wrapped across physical lines, then the last non-whitespace character of the preceding line must be a comma separator.
basic_map_statement: The ordinal number of the BASIC map statement containing the field definitions to be converted. (The default value is 3). basename: The basename for the ADL and temporary files. options: Enables you to specify the following options:
d: Specifies that all intermediate files are saved (debug). You can check these files if problems occur in the conversion. c: Specifies that the column name is used for an array name, instead of the concatenation of the parent table name with the child table name. If a column name is not unique in a structure (as when a structure includes another structure, which contains a column with the same name as a column in the parent structure), the nested column name is suffixed with the nested structure name.
s: Specifies that periods in BASIC variable names are replaced with underscores (_) in the ADD column names. If this is not specified, all characters before and including the final period are removed when determining the ADD column names.
Note:
To display online help for this utility, run the command without any parameters, as follows: BAS_ADL.
Part VIII
Data Source Reference
This part contains the following topics:
Adabas C Data Source CISAM /DISAM Data Source DB2 Data Source DBMS Data Source (OpenVMS Only) Enscribe Data Source (HP NonStop Only) Flat File Data Source IMS/DB Data Sources Sybase Data Source Ingres II (Open Ingres) Data Source ODBC Data Source OLEDB-FS (Flat File System) Data Source OLEDB-SQL (Relational) Data Source Oracle Data Source Oracle RDB Data Source (OpenVMS Only) RMS Data Source (OpenVMS Only) SQL Server Data Source (Windows Only) SQL/MP Data Source (HP NonStop Only) Text Delimited File Data Source Virtual Data Source VSAM Data Source (z/OS) Informix Data Source
39
Adabas C Data Source
This section describes the Attunity Adabas C data source driver. It includes the following topics:
Overview Functionality Transaction Support Security Configuration Properties Data Types Platform-specific Information Defining an Adabas Data Source Setting Up Adabas Data Source Metadata (Using the Import Manager) Setting Up Adabas Data Source Metadata (Traditional Method) Testing the Adabas Data Source
Overview
There are two types of Adabas data sources, the Adabas data source and the ADD-Adabas data source. The Adabas data source uses Predict metadata whereas the ADD-Adabas data source uses Attunitys internal repository (ADD), which is usually imported from Natural Data Definition Module (DDM) files. Alternatively, Predict metadata can be exported and subsequently imported into the ADD-Adabas data source. Both Adabas data sources provide very similar functionality. The ADD-Adabas data sources enjoys some added flexibility and functionality resulting from the ability to customize the metadata in the ADD. Unless explicitly stated, all features and procedures described apply to both data sources. This overview also covers the following topics:
Supported Features
Adabas data sources support the following key features. More information on the details of support for some of these features will be provided in a separate topic within this section.
Read and write access to Adabas data Database and file numbers greater than 255 Adabas security Access to Adabas views as well as physical files Reading of Predict metadata at runtime or importing of metadata from DDM files at design time Predict files residing in a separate database, as well as multi-database Predict files All basic Adabas data types Natural date and time formats ISN as a column, including reading a record by ISN Multi-value (MU) and Periodic Group (PE) fields, including MUs within a PEs Transactions (1PC) using ET and BT commands Multifetch Support for complex multi-index strategies using S1-L1 with search expressions referring to several descriptors Support for various descriptor types including superdescriptors, hyperdescriptors and phonetic descriptors, as well as descriptors on MUs and PEs Null suppression Several logical tables in a single physical file Record-level locking using the L4 and HI commands Full support for XML features like select xml and update xml.
Limitations
multiClient server mode is not supported for Adabas on all platforms except for MVS. All other server modes are supported.For directions on how to setup multiClient on MVS, see z/OS Platforms. DDL operations (e.g., CREATE TABLE, ALTER TABLE) are not supported for Adabas.
Functionality
This section describes the following aspects of Adabas functionality:
Phonetic-descriptors and Hyper-descriptors Descriptors on MU and PE fields Null Suppression Handling Array Handling Logical Tables Locking Support
Statistical Information
The AIS optimizer is a cost-based optimizer that requires up-to-date statistical information regarding the cardinality of tables and indexes. AIS can automatically create this statistical information using the update_statistics utility. See the Statistics Tab for more information. Note that statistical information can be generated for both Predict and ADD data sources. Having no statistics or incomplete/inaccurate statistics may cause the Attunity optimizer to create inefficient execution strategies.
<field name ="DEPT_1_4" datatype="string" size="4" subfieldOf="DEPT" subfieldStart="0"> <dbCommand>AO</dbCommand> </field> Example 392 Index Definition
This means that you need to write the SQL correctly in order to get the correct descriptor used. Both of the following queries are valid and will return the same result. The second, however, will use the S1 descriptor and will be faster.
Note that for ADD-Adabas the metadata generated by the DDM import looks a bit different with regards to subfields if you look at the generated XML. The ADD-Adabas driver, however, knows how to read the imported Metadata and construct the exact same view as the Predict counterpart. A nav_util export table -native command from an ADD-Adabas data source will export the metadata after the driver normalized it to the same notation as the Adabas Predict notation shown here.
Can be used in where clause but not in select clause. There is no real meaning to a query like select ph_phonetic_name from employees. For this reason all search fields are referred to as non-selectable (XML attribute nonSelectable=true). Can only be used in an equal relationship. You cannot execute a query like select * from employees where ph_phonetic_name > 'Smithy'. You cannot use a search field in any other part of the query - e.g., ORDER BY, GROUP BY, HAVING clauses. Unlike normal fields, once a filter is specified on a search field, the Attunity Query Processor cannot verify that the data returns matches the filter. The query
processor recognizes that it must trust the data returned by Adabas implicitly. It cannot, for example, verify that Smiti does sound like Smithy.
To avoid generating search fields, set the configuration parameter disregardNonselectable to true. By default this flag is false and search fields are therefore generated.
For example, the LANG (AZ) MU field in the EMPLOYEES sample table is also a descriptor. This descriptor allows a user to easily search for all employees that speak English, for example. The generated search field is AZ_ACSEARCH_LANG. The equivalent query using Attunity Connect will be:
select * from employees where az_acsearch_lang='
Note that the following query will return the same result, but will not use the AZ descriptor. Rather, it will use L2 to scan the EMPLOYEES table. See Handling Arrays for more information about working with arrays and virtual array tables and views.
select e.* from employees e, employees_lang el where e.lang=el._parent and el.lang='ENG'
Exposed as NULLABLE fields. Depending on their datatype, either zeros or spaces are treated as the NULL value. That means that if a field of type A has spaces in it, an SQL user selecting data from it will get a NULL value. When the Attunity query optimizer considers possible execution strategies for a query, it will rule out any execution strategy that uses a descriptor in which at least one NULL suppressed field is not qualified. The reason for this behavior is that Adabas does not include all records in every descriptor inverted list. NULL suppressed fields with 'NULL values' (zeros or spaces) will cause the record to be excluded from any inverted list based on this field.
For example, suppose a table has text fields - AA and AB with superdescriptor S1 defined on AA, AB and AB is NULL suppressed. The user issues the following query:
select * from a_table where aa='XYZ'
The optimizer will not use the S1 superdescriptor for this query because AB is NULL suppressed. Had it used S1 it would not have read records where AA='XYZ' and AB is
Adabas C Data Source 39-5
empty. Because of the NULL suppression, Adabas does not include these records in the S1 inverted list. Because AB is not qualified, the Attunity optimizer knows that this is not a valid execution plan. On the other hand, the following query would use the S1 superdescriptor:
select * from a_table where aa='XYZ' and ab is not null
This is because ab was qualified in the query. Note that qualifying the field with the NULL value (ab=0 or ab=' ') is not considered valid and is not supported. So qualifying a text field with ab<> may return incorrect results whereas ab is not null will be handled correctly. The behavior of the Adabas driver regarding NULL suppressed fields can be modified using the nullSuppressionMode configuration attribute. It can be partially or fully disabled. Care must be taken when deciding to disable the default NULL suppression handling as incomplete results may be returned for queries, as the above example showed. See Configuration Properties for further details.
Array Handling
Attunity Connect fully supports MU and PE fields (including MU inside of a PE). These constructs are mapped as arrays and can be used with the standard AIS array handling infrastructure. See Handling Arrays for more information about Attunity's array handling support. Some specific points to Adabas arrays are listed:
A counter field is automatically added to the table for every array. For the LANG (AZ) MU field in the EMPLOYEES sample table, Attunity Connect will automatically add a field called C_LANG which will translate to AZC in the Adabas format buffer. Whenever any data from an MU/PE is included in the query, Attunity Connectwill automatically add the relevant counter field in the format buffer so that the correct number of rows is returned. For an MU inside a PE, a counter field is created for the MU field. The Adabas format buffer interpretation for this field is a bit more complex as it will generate an explicit format buffer field for every PE instance (e.g., AA1C, AA2C, AA3C). Adabas arrays support INSERT/UPDATE/DELETE operations when using the virtual array tables. All these operations are implemented using the Adabas A1 command. The following notes apply: A DELETE operation sets MU/PE fields to their empty value (zeros or spaces). So a delete of the 3rd member of the AZ MU will cause an A1 operation with format buffer AZ3. and record buffer with spaces. An INSERT operation adds another member to the end of the array. The _ ROWNUM provided is ignored.
Adabas arrays can have up to 191 members. It is, however, highly recommended to use a lower dimension which represents the maximum expected number if members. When using Adabas Predict, this applicative dimension is read from Predict. If Predict specifies no dimension, the defaultOccurrences configuration attribute is used (10 if unspecified). Note that if a record is read with a larger number of array members than the given dimension, the driver will return an error (Bad metadata on array for column.). Attunity Connect arrays are naturally row-wise arrays. When accessing PE members, Adabas returns the results in a column-wise order. For example, a PE
called INCOME (AQ) in the EMPLOYEES sample table has members like CURR_ CODE (AS) and SALARY (AS). The format buffer will include AR1-40 and AS1-40 which is a column-wise ordering (all instances of AR followed by all instances of AS). This is different than equivalent definitions in VSAM, for example, where you would have AR1, AS1, AR2, AS2, etc. The Attunity ConnectAdabas driver will represent the metadata as an array of CURR_CODE followed by an array of SALARY to match the physical layout of the buffer, but it will add a groupEntry attribute on the structure in order to expose this logically as a single array. Note that this different ordering is transparent to the user. The following is the metadata for this sample:
Example 393 Adabas Array Metadata
<group name="INCOME" groupEntry="true"> <fields> <field name="CURR_CODE" datatype="string" size="3" nullSupressed="true" dimension1="40" counterName="C_INCOME"> <dbCommand>AR</dbCommand> </field> <field name="SALARY" datatype="unsigned_decimal" size="9" nullSupressed="true" dimension1="40" counterName="C_INCOME"> <dbCommand>AS</dbCommand> </field> <field name="BONUS" datatype="unsigned_decimal" size="9" nullSupressed="true" dimension1="40" dimension2="12" counterName="C_INCOME"> <dbCommand>AT</dbCommand> </field> </fields> <dbCommand>AQ</dbCommand> </group>
Logical Tables
Storing several tables in the same physical Adabas file was a common practice, especially when file numbers were limited to 255 files in a database. When accessing these tables using AIS, users usually prefer to map the single physical file to several logical tables. Normally Predict views or DDM definitions exist with this logical mapping. Attunity Connect uses these definitions and only sees the columns and descriptors relevant to the logical table being accessed. Since it is common practice to make all the fields in such a file NULL suppressed, using a descriptor is also fine because only records or that logical table are part of the descriptor's inverted list. The only problem in providing this logical mapping is when the Attunity Query Processor decides to scan such a logical table. Using L2 will return lots of empty rows corresponding to the records of the other logical tables in the file. In order to solve this problem, it is possible to specify that a scan strategy use L3 with a particular descriptor instead of L2. This option is currently supported only using the ADD-Adabas driver. To set it, you just need to specify the descriptor name to be used for scanning the logical table in the table's dbCommand, next to the file number. For example, <dbCommand>17;AA</dbCommand> will cause L3 on the AA descriptor to be used for scanning the table. Care must be taken to make sure that the descriptor selected is such that all records belonging to the logical table will be accessible using the descriptor's inverted list.
Locking Support
The Adabas data source supports lock operations as part of an UPDATE/DELETE SQL statement, or as part of a SELECT FOR UPDATE operation. Records will be released when the transaction is committed (in autocommit mode that means immediately following the operation). When attempting to lock a record that is held by another user, the default behavior is to return an error without waiting. You can control this behavior with the lockWait configuration attribute.
Transaction Support
The Adabas data source supports one-phase commit. Transactions are implemented using the Adabas ET and BT commands. The following should be noted regarding transactions:
An Adabas data source can participate in a distributed transaction if it is the only one-phase commit data source being updated in the transaction. See Attunity Connect Data Source Driver Capabilities for more information on setting up two-phase commit transactions. There is no control over isolation-level when accessing Adabas. By default, when scanning a table using L2 Adabas will provide you with uncommitted data from other users that are in the process of modifying the same records you are reading. In cases where this is not acceptable, it is recommended that the scanUsingL1 configuration attribute be set to true. Adabas will then provide only the committed data for all records accessed. Note that using L1 to scan a file is more expensive than using L2.
Security
All the standard infrastructure provided by AIS regarding data source-level security is applicable to Adabas data sources. If a username/password is provided for an Adabas data source, the Adabas driver ignores the username specification and provides the password on the ADDITIONS 3 field of the Adabas control block. For more information, see Managing Security.
Data Types
The following table shows how AIS maps Predict data types to ADD data types.
Table 391 Predict Alphanumeric (A) Binary (B1) Binary (B2) Binary (B4) Binary (B8) Binary (B*) DATE (D) Floating (F4) Floating (F8) Predict Data Types ADD String unsigned_int1 unsigned_int2 unsigned_int4 int81 unspecified ada_d_time dfloat/gfloat double
Table 391 (Cont.) Predict Data Types Predict Integer (I1) Integer (I2) Integer (I4) Integer (I8) Integer (I1.n) Integer (I2.n) Integer (I4.n) Integer (I8.n) Logical (L) Packed Decimal (P) Unpacked Decimal (N,U) TIME (T)
1
ADD int1 int2 int4 int8 decimal 3 digits decimal 5 digits decimal 10 digits decimal 20 digits string size 1 decimal ada_numstr_s (MVS), numstr_zoned (Others) ada_time
The following table shows how AIS maps Adabas data types to ADD data types.
Table 392 Adabas Alphanumeric (A) Binary (B1) Binary (B2) Binary (B4) Binary (B8) Binary (B*) Floating (F1) Floating (F2) Floating (F4) Floating (F8) Floating (F*) Floating (G4) Floating (G8) Packed Decimal (P) Unpacked Decimal (N,U)
1
Adabas Data Types ADD String unsigned_int1 unsigned_int2 unsigned_int4 int81 unspecified int1 int2 int4 int8 unspecified float dfloat/gfloat decimal ada_numstr_s (MVS), numstr_zoned (Others)
Configuration Properties
The following properties can be configured for the Adabas data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
dbNumber: (Predict, ADD) The Adabas database number. predictFileNumber: (Predict only) The Predict file number. predictDbNumber: (Predict only) In some cases the Predict file resides in a different database than the data. If so, use this attribute to specify the database number in which the Predict file resides. svcNumber: (Predict, ADD; MVS only) The installation on MVS places the SVC number of Adabas in the GBLPARMS file. Alternatively, you can specify the SVC number using this attribute. This simplifies configuration in sites where several Adabas installations on different SVC numbers need to be accessed from a single installation. Each SVC will still require a different workspace, but the same GBLPARAMS and the same RACF profile can be used for the different workspaces. addMuInPeCounter: (Predict, ADD) Until version 4.6 AIS did not support counters for MUs inside of PEs. In version 4.6 this support was added, but since it changes behavior for existing users, this attribute was added to allow existing users to turn off this new feature to preserve compatibility. Default: addMuInPeCounter='true'. defaultOccurences: (Predict only) If the Predict occurrences field for multiple value fields or periodic group fields is not specified, the value of this parameter is used. If a record is retrieved with more occurrences than specified, an error is returned. Default: defaultOccurances='10'. disableExplicitSelect: (Predict, ADD) This attribute indicates whether or not the Explicit Select option is disabled. If disables, a select * query on an Adabas table will return all fields in the table, including ISN and subfields which are normally suppressed unless explicitly requested in the query (e.g. select ISN, *). Default: disableExplicitSelect='false'. disregardNonselectable: (Predict, ADD) This attribute enables you to configure the data source to ignore descriptors defined on a multiple value (MU) field, a periodic group (PE) field or phonetic/hyper descriptors. The special ACSEARCH fields which are normally created for a table are referred to as non-selectable because you cannot specify them in the select list of a query. Setting the disregardNonselectable attribute to 'true' will prevent these fields from being created. Default: disregardNonselectable='false'. fileList: (Predict, ADD) This attribute is passed as the record buffer to the OP command. Adabas allows a list of file numbers to be provided in the record buffer of the OP command, along with the operations allowed on each file. By using this attribute a user can restrict access to the database, allowing only specific operations on specific files. See the Software AG documentation of the OP command for more information on the syntax allowed. Note that the value provided in this attribute is passed as-is to Adabas - no validation is performed. Default: fileList='.' (i.e., unrestricted access to all files in the database). lockWait: (Predict, ADD) This attribute specifies whether the data source waits for a locked record to become unlocked or returns a message that the record is locked. In Adabas terms, if this attribute is set to true a space is passed in
command option 1 of the HI/L4 commands. Otherwise an 'R' is passed in command option 1. Default: lockWait='false'.
multiDatabasePredict: (Predict only) Turn this flag on if your Predict file includes metadata for several different databases. This has two effects on the way that the Predict information is read: Only tables that belong to the current database are returned in the table list. The file number for a table is read separate from the metadata as different databases may include the same table using a different file number.
multifetch: (Predict, ADD) This parameter controls the number of records to be retrieved in a single read command (L2, L3, S1-L1). The value provided in this attribute controls the value passed in the ISN lower limit control block field. By default no multifetch is used. The multifetch buffer size can be controlled as follows: multifetch='0': Lets the driver decide the number of records to retrieve. The driver will generally retrieve rows to fill a 10k buffer. No more than 15 rows are fetch at once. multifetch='n': Causes n rows to be read at a time, where n is a number from 2 to 15. multifetch='-n': Defines a read-ahead buffer with a fixed size, where n is less than or equal to 10000 bytes. multifetch='1': Disables the read-ahead feature. (default)
nullSuppressionMode: (Predict, ADD) This attribute controls the behavior of the Adabas driver with regard to Null Suppression Handling. This attributes allows a user to change this default NULL suppression policy. Note that changing this setting improperly may result in incomplete query results. The following values can be selected: full: (default) NULL suppressed fields are exposed as NULLABLE and must be qualified for the Attunity optimizer to consider using a descriptor based on a NULL suppressed field. disabled: NULL suppressed fields are handled like any other field. Use this setting only if you completely understand the potential implications as incomplete query results may returned. indexesOnly: Only NULL suppressed fields that are part of a descriptor/super-descriptor are exposed as NULLABLE. Other NULL suppressed fields are handled normally. This setting is as safe as the full setting and does not include the risk of incomplete results as the disabled option does.
scanUsingL1: (Predict, ADD) A scan strategy on a table is normally implemented by an L2 command. It is possible, however, to turn on this attribute in order to scan using the L1 command. This has the advantage of providing better data consistency at some performance penalty. Default: scanUsingL1='false'. supportL3Range: (Predict, ADD) Older versions of Adabas did not allow for a range specification on an L3 command (e.g., AA,S,AA in the search buffer). Only the lower limit could be provided. If your version of Adabas supports a range in the L3 command you can turn on this attribute to enjoy better performance in some queries. Default: supportL3Range='false'. traceValueBuffer: This is a debugging tool to be used in conjunction with driverTrace='true' in the environment. Turning on driverTrace will record the
Adabas C Data Source 39-11
Adabas commands executed in the server log file. If you also want a binary dump of the value buffer and record buffer, set this attribute to true. Default: traceValueBuffer='false'.
userInfo: (Predict, ADD) This attribute specifies the value passed as a null-terminated string to Adabas as the seventh parameter on the adabas call. The value provided is then available in Adabas user exits. This has no affect at all on Attunity Connect, but some users have taken advantage of this feature to implement specific types of auditing. Note that it is possible to control the value of the userInfo attribute dynamically at runtime using the nav_proc:sp_setprop stored procedure. Default: userInfo=''. useUnderscore: (Predict, ADD) This attribute indicates whether or not to convert hyphens (-) in table and column names into underscores (_). The inclusion of hyphens in Adabas table names and field names poses an inconvenience when accessing these tables from SQL because names that include a dash need to be surrounded with double quotes. To avoid this inconvenience, the data source can translate all hyphens into underscores. Default: useUnderscore='true'. verifyMetadata: (Predict, ADD) This attribute indicates whether or not to cross-check the Predict or ADD metadata against the LF command. Resulting discrepancies are written to the log and removed from the metadata at runtime. It is usually unnecessary to use this attribute. Default: verifyMetadata='false'.
Platform-specific Information
This section includes Adabas-related information and procedures as they pertain to specific platforms, as follows:
UNIX Platforms
This section includes the following topics:
z/OS Platforms
Attunity Connect accesses Adabas on MVS platforms just like other platforms. This section details a few MVS specific notes. This section includes the following topics:
Adabas_SVC in GBLPARMS: This is the default option when providing an SVC number in the CUST Rexx script. All Adabas data sources will then use this SVC number. svcNumber property on an Adabas data source: Using this option allows you to access several different Adabas instances using different SVC numbers using the same GBLPARMS and the same RACF profile for the Attunity servers. Note, however, that you must separate the data sources into different workspaces. Each workspace can only access a single Adabas instance.
You can set up Adabas to work with a multiClient workspace on MVS. multiClient mode is not supported on other platforms.
Note: Currently multiClient cannot be used from an ACX client, i.e., any client using the database adapter or query adapter to get to Adabas.
multiClient provides a way to improve scalability when using Adabas by having several clients share the same Attunity server. This saving in started tasks does come with a price as the server is single-threaded so users can affect each other performance-wise. Use the maxNClientsPerServer attribute of the workspace to control the maximum number of clients sharing a single server. Note that you can use multiClient in conjunction with subtasks to further reduce the number of started tasks. Use the following criteria to decide whether or not to implement multiClient with Adabas:
If your client uses connection pools there is usually no reason to use the multiClient mode. In a well planned application using connection pools, the application picks up the connection only when it has something it needs to do. If your client does not use connection pools, then the client may be utilizing the connection only a small percentage of the time. Using multiClient may reduce the server resources required without impacting performance. Set the maxNClientsPerServer for the workspace to the percentage utilization, for example, for 10% utilization set maxNClientsPerServers=10.
When working in multiClient mode, the Attunity Adabas driver will attempt to load a module called ADALNKR instead of ADALNK. If successful, it will internally construct a unique user ID for the session and continue working with ADALNKR. This internal user ID that we generate is the equivalent of the connection handle of Oracle or SQL Server. This is what makes it possible for multiple clients to work within a single started task (or subtask) against Adabas in isolation, just as though they were in separate started tasks. This, of course, means that each of these servers can perform updates in separate transactions. This figure shows a multiClient scenario with ADALNKR. ADALNKR is the reentrant version of ADALNK supplied by Software AG. Normally, this module is available as source code (assembler) as part of the Adabas installation, but it needs to be compiled and linked after changing it to work with your local SVC number. This module, as opposed to ADALNK, can create several isolated sessions with the Adabas nucleus from the same started task.
To use multiClient 1. Create the required ADALNKR by editing the assembler code and setting the SVC number to the Adabas SVC number of the site. This figure shows a code snippet from ADALNKR that includes the SVC number setting (245 in this snippet).
Figure 393 SVC Number Setting
2. 3. 4.
Build ADALNKR on the target MVS machine. Open Attunity Studio, and find the workspace. See Editing a Workspace. In the workspace Server Mode tab, select multiClient workspace.
5. 6.
Ensure that the ADALNKR module you create is available in the server's STEPLIB. The normal place to put this load module is in the Adabas LOAD library. It is possible to verify that you are indeed using separate connections to Adabas by looking at the list of Adabas users. Use the /F NMPM,DUQA command from SDSF and check the system log for the command output. You should see the following patterns for the user-IDs when using multiClient. This figure shows a sample of the system log output.
This figure shows the output of the same command when multiClient is not in use. Note that the user IDs are different.
Figure 396 System Log Command Output without multiClient
Defining the Adabas Data Source Connection Configuring the Adabas Data Source Properties
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your Adabas data source. Expand the Bindings folder. Expand the binding where you want to add the Adabas data source. Right-click the Data Source folder and select New Data Source. The New Data Source screen is displayed.
7. 8.
In the Name field, enter a name for the new data source. Select the import type from the Type list:
Adabas (Predict): to define an Adabas data source that is to use Predict metadata Adabas (ADD): to define an Adabas data source that is to use Attunity metadata
9.
10. Enter the connect string according to the data source type selected:
If you are defining an Adabas ADD data source, enter the Database number. If you are defining an Adabas Predict data source, emter the following: Database number Predict File Number: The Adabas Predict file number which describes the specified database. Predict database number: Enter this field only if the Predict file does not reside in the same database as the data.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Adabas data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the Adabas data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Adabas Data Source Connection. For Adabas (ADD), enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
You can use the import manager with the Adabas (ADD) data source only.
Selecting the DDM Declaration files Applying Filters Selecting Tables Import Manipulation Metadata Model Selection Import the Metadata
The following sections describe each step, and the screens that appear for that step.
In the Design perspective, Configuration view, right-click the data source and select Show Metadata View. The Metadata tab is displayed with the data source displayed in the Metadata view.
3. 4.
Expand the Adabas data source you are working with. Right-click Imports and select New Import.
Adabas C Data Source 39-19
5. 6.
Enter a name for the import. The name can contain letters, numbers and the underscore character. Click Finish. The Metadata import wizard opens with the Get Input Files screen, as shown in the following figure:
7.
Click Add. The Add Resource screen is displayed, as shown in the following figure:
Figure 3910
8.
If the files are on another machine, then right-click My FTP Sites and select Add. The Add FTP Site screen is displayed, as shown in the following figure:
Figure 3911
9.
Enter the server name where the DDM Declaration files are located and, if not using anonymous access, enter a valid username and password to access that computer. The username is then used as the high-level qualifier. qualifier by right-clicking the machine in the Add Resource screen, and selecting Change Root Directory.
10. Click OK. After accessing the remote computer, you can change the high-level
11. Select the files to import and click Finish to start the file transfer. When complete,
the selected files are displayed in the Get Input Files screen. To remove any of these files, select the required file and click Remove.
12. Click Next (The Apply Filters screen opens) to continue to the Applying Filters
step.
Note: The Adabas Declaration files can have file extensions of .DDM or .NSD.
Applying Filters
This section describes the steps required to apply filters on the DDM Declaration files used to generate the Metadata. It continues the Selecting the DDM Declaration files procedure. To apply filters 1. Expand all in the Apply Filters screen, as shown in figure below.
2. 3.
Apply the required filter attributes to the DDM Declaration files. The available filters are listed and described in the table below. Click Next (The Select Tables screen opens) to continue to the Selecting Tables step.
This screen lets you change reserved words used for the names of elements in Adabas file in case a problem occurs. The following table describes the options:
Table 393 Option Replace Column CHAPTER for FIELD Reserved Word Replacements Description If the Column FIELD is called CHAPTER, the name is changed to CHAPTER0. You can change this value to CHAPTER(n). If either or the Columns FIELD or INDEX are called END, the name is changed to END0. You can change this value to END(n) If the Column FIELD is called VARIENT, the name is changed to VARIENT0. You can change this value to VARIENT(n)
Replace Column END for FIELD and for INDEX Replace Column VARIANTS for FIELD
Selecting Tables
This section describes the steps required to select the tables from the DDM Declaration files. The import manager identifies the names of the records in the DDM Files that will be imported as tables. The following procedure continues the Applying Filters procedure. To select the required tables 1. From the Select Tables screen, select the tables that you want to access. To select all tables, click Select All. To clear all the selected tables, click Unselect All. The Select Tables screen is shown in the following figure:
Figure 3913 The Select Tables screen
2.
Click Next (the Import Manipulation screen opens) to continue to the Import Manipulation step.
Import Manipulation
This section describes the operations available for manipulating the imported records (tables). It continues the Selecting Tables procedure. The import manager identifies the names of the records in the DDM Declaration files that will be imported as tables. You can manipulate the general table data in the Import Manipulation Screen To manipulate the table metadata 1. From the Import Manipulation screen (see The Import Manipulation screen figure), right-click the table record marked with a validation error, and select the relevant operation. See the table, Table Manipulation Options for the available operations.
Adabas C Data Source 39-23
2.
Repeat step 1 for all table records marked with a validation error. You resolve the issues in the Import Manipulation Screen. Once all the validation error issues have been resolved, the Import Manipulation screen is displayed with no error indicators.
3.
The upper area of the screen lists the DDM Declaration files and their validation status. The metadata source and location are also listed. The Validation tab at the lower area of the screen displays information about what needs to be resolved in order to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location). The following operations are available in the Import Manipulation screen:
Resolving table names, where tables with the same name are generated from different files during the import. Selecting the physical location for the data. Selecting table attributes. Manipulating the fields generated from the COBOL, as follows:
Merging sequential fields into one (for simple fields). Resolving variants by either marking a selector field or specifying that only one case of the variant is relevant. Adding, deleting, hiding, or renaming fields. Changing a data type. Setting the field size and scale. Changing the order of the fields. Setting a field as nullable. Selecting a counter field for array for fields with dimensions (arrays). You can select the array counter field from a list of potential fields. Setting column-wise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension. Creating arrays and setting the array dimension.
The following table lists and describes the available operations when you right-click a table entry:
Table 394 Option Fields Manipulation Table Manipulation Options Description Customizes the field definitions, using the Field Manipulation screen. You can also access this screen by double-clicking the required table record. Renames a table. This option is used especially when more than one table with the same name is generated from the COBOL. Sets the physical location of the data file for the table. Sets the table attributes. Specifies an XSL transformation or JDOM document that is used to transform the table definitions. Removes the table record.
Rename Set data location Set table attributes XSL manipulation Remove
You can manipulate the data in the table fields in the Field Manipulation Screen. Double-click a line in the Import Manipulation Screen to open the Field Manipulation Screen.
You can carry out all of the available tasks in this screen through the menu or toolbar. You can also right click anywhere in the screen and select any of the options available in the main menus from a shortcut menu. The following table describes the tasks that are done in this screen. If a toolbar button is available for a task, it is pictured in the table.
Table 395 Command General menu Undo Click to undo the last change made in the Field Manipulation screen. Field Manipulation Screen Commands Description
The offset of a field is usually calculated dynamically by the server at runtime according the offset and size of the proceeding column. Select this option to override this calculation and specify a fixed offset at design time. This can happen if there is a part of the buffer that you want to skip. When you select a fixed offset you pin the offset for that column. The indicated value is used at runtime for the column instead of a calculated value. Note that the offset of following columns that do not have a fixed offset are calculated from this fixed position.
Table 395 (Cont.) Field Manipulation Screen Commands Command Test import tables Description Select this table to create an SQL statement to test the import table. You can base the statement on the Full table or Selected columns. When you select this option, the following screen opens with an SQL statement based on the table or column entered at the bottom of the screen.
Data file name: Enter the name of the file that contains the data you want to query. Limit query results: Select this if you want to limit the results to a specified number of rows. Enter the amount of rows you want returned in the following field. 100 is the default value. Define Where Clause: Click Add to select a column to use in a Where clause. In the table below, you can add the operator, value and other information. Click on the columns to make the selections. To remove a Where Clause, select the row with the Where Clause you want t remove and then click Remove.
The resulting SQL statement with any Where Clauses that you added are displayed at the bottom of the screen. Click OK to send the query and test the table. Attribute menu Change data type Select Change data type from the Attribute menu to activate the Type column, or click on the Type column and select a new data type from the drop-down list.
Table 395 (Cont.) Field Manipulation Screen Commands Command Create array Description This command allows you to add an array dimension to the field. Select this command to open the Create Array screen.
Enter a number in the Array Dimension field and click OK to create the array for the column. Hide/Reveal field Select a row from the Field manipulation screen and select Hide field to hide the selected field from that row. If the field is hidden, you can select Reveal field. Select this to change or set a dimension for a field that has an array. Select Set dimension to open the Set Dimension screen. Edit the entry in the Array Dimension field and click OK to set the dimension for the selected array. Set field attribute Select a row to set or edit the attributes for the field in the row. Select Set field attribute to open the Field Attribute screen.
Set dimension
Click in the Value column for any of the properties listed and enter a new value or select a value from a drop-down list. Nullable/Not nullable Select Nullable to activate the Nullable column in the Field Manipulation screen. You can also click in the column. Select the check box to make the field Nullable. Clear the check box to make the field Not Nullable. Set scale Select this to activate the Scale column or click in the column and enter the number of places to display after the decimal point in a data type. Select this to activate the Size column or click in the column and enter the number of total number of characters for a data type.
Table 395 (Cont.) Field Manipulation Screen Commands Command Add Description Select this command or use the button to add a field to the table. If you select a row with a field (not a child of a field), you can add a child to that field. Select Add Field or Add Child to open the following screen:
Enter the name of the field or child, and click OK to add the field or child to the table. Delete field Select a row and then select Delete Field or click the Delete Field button to delete the field in the selected row.
Move up or down
Select a row and use the arrows to move it up or down in the list.
Select Rename field to make the Name field active. Change the name and then click outside of the field.
Select Columnwise Normalization to create new fields instead of the array field where the number of generated fields will be determined by the array dimension.
Table 395 (Cont.) Field Manipulation Screen Commands Command Combining sequential fields Description Select Combining sequential fields to combine two or more sequential fields into one simple field. The following dialog box opens:
First field name: Select the first field in the table to include in the combined field End field name: Select the last field to be included in the combined field. Make sure that the fields are sequential. Enter field name: Enter a name for the new combined field.
Flatten group
Select Flatten Group to flatten a field that is an array. This field must be defined as Group for its data type. When you flatten an array field, the entries in the array are spread into a new table, with each entry in its own field. The following screen provides options for flattening.
Select Recursive operation to repeat the flattening process on all levels. For example, if there are multiple child fields in this group, you can place the values for each field into the new table when you select this option. Select Use parent name as prefix to use the name of the parent field as a prefix when creating the new fields. For example, if the parent field is called Car Details and you have a child in the array called Color, when a new field is created in the flattening operation it will be called Car Details_Color.
Table 395 (Cont.) Field Manipulation Screen Commands Command Mark selector Description Select Mark selector to select the selector field for a variant. This is available only for variant data types. Select the Selector field form the following screen.
Select Replace variant to replace a variants selector field. Select Counter Field opens a screen where you select a field that is the counter for an array dimension.
Default values for all tables: Select this if you want to configure the same values for all the tables in the import. Make the following selections when using this option: Generate sequential view: Select this to map non-relational files to a single table. Generate virtual views: Select this to have individual tables created for each array in the non-relational file. Include row number column: Select one of the following: true: Select true, to include a column that specifies the row number in the virtual or sequential view. This is true for this table only, even in the the data source is not configured to include the row number column. false: Select false, to not include a column that specifies the row number in the virtual or sequential view for this table even if the data source is configured to include the row number column. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties. Inherit all parent columns: Select one of the following: true: Select true, for virtual views to include all the columns in the parent record. This is true for this table only, even in the data source is not configured to include all of the parent record columns. false: Select false, so virtual views do not include the columns in the parent record for this table even if the data source is configured to include all of the parent record columns. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties.
Specific virtual array view settings per table: Select this to set different values for each table in the import. This will override the data source default for that table. Make the selections in the table under this selection. See the item above for an explanation.
Figure 3916
Click Finish.
Importing Attunity Metadata from DDM Files Exporting Predict Metadata into Adabas ADD
Windows: c:\> nav_util export table -native adapredict * adapredict.xml UNIX: nav_util export table -native adapredict \* adapredict.xml MVS (After executing the NAVCMD Rexx script in USERLIB): Local> export table -native adapredict * 'ATTUNITY.XML.ADAPRED'
2.
Windows: c:\> nav_util import adaadd adapredict.xml UNIX: nav_util import table adaadd adapredict.xml MVS (After executing the NAVCMD Rexx script in USERLIB): Local> import adaadd 'ATTUNITY.XML.ADAPRED'
40
DB2 Data Source
This section contains the following topics:
Overview Functionality Configuration Properties Metadata Transaction Support Security DB2 Data Types Defining a DB2 Data Source
Overview
The DB2 Data Source driver provides a wide range of common standard relational functionality that comply with the Relational Data Source model. It implements connectivity to a DB2 database instance by means of embedded SQL techniques.
Functionality
This section describes the following aspects of DB2 functionality:
Stored Procedures
The DB2 data source supports DB2 Stored Procedure as follows.
DB2 version 7 or higher must be installed to call a stored procedure. The DB2 stored procedure can only be called using a CALL statement and not as part of a SELECT statement.
The isolation level is used only within a transaction. The behavior of updates on locked data depends on the value of the LOCKTIMEOUT variable of DB2. If this variable is set to -1, then the update waits until the lock is released. If LOCKTIMEOUT is set to 0, the update fails immediately; and if it is set to a number greater than 0, the update waits for the specified seconds before failing.
Update Semantics
For tables without a bookmark or other unique index, the data source returns as a bookmark a combination of most (or all) of the columns of the row. The data source does not guarantee the uniqueness of this bookmark; you must ensure that the combination of columns is unique.
Configuration Properties
This section lists the properties that can be configured for the DB2 data source. For information on how to set data source properties in Attunity Studio, see Adding Data Sources. The tables below show the properties for each operating system supported by the DB2 data source. DB2 data source properties on z/OS, are listed in the following table:
Table 401 Property dbname isolationLevel DB2 Data Source Properties on z/OS Description
dynamicIsolation: The isolation level is not set at the data source level. Setting this parameter to true allows the application to set this parameter dynamically as needed. readUncommitted: Specifies that corrupt data is not read. This is the lowest isolation level. readCommitted: Specifies that only the data committed before the query begun is displayed. repeatableRead: Specifies that the data used in a query is locked and cannot be used by another query, nor can it be u[dated by another transaction. serializable: Specifies that the data is isolated serially. Handles the data as if transactions are executed sequentially.
Note: If the specified isolation level is not supported by the data source, Attunity Connect defaults to the next highest level. location The location of the library containing the database tables.
Table 401 (Cont.) DB2 Data Source Properties on z/OS Property noExtendedInfo statementCacheSize Description When set to true, no extended matadata information is read from the DB2 database, including indexes. Specifies the maximum number of SQL statements that are cached. The default is set to 0, indicating no maximum limit.
DB400 data source properties on OS/400 are listed in the following table:
Table 402 Property controlledCommit DB400 Data Source Properties on OS/400 Description When set to true, specifies that Attunity Connect handles transaction commitments. In addition, when set to true, OS/400 journaling must be set.
dbname isolationLevel
dynamicIsolation: The isolation level is not set at the data source level. Setting this parameter to true allows the application to set this parameter dynamically as needed. readUncommitted: Specifies that corrupt data is not read. This is the lowest isolation level. readCommitted: Specifies that only the data committed before the query begun is displayed. repeatableRead: Specifies that the data used in a query is locked and cannot be used by another query, nor can it be updated by another transaction. serializable: Specifies that the data is isolated serially. Handles the data as if transactions are executed sequentially. If the specified isolation level is not supported by the data source, Attunity Connect defaults to the next highest level. When set to false (the default), specifies that the DB2 RDBMS handles the commitment control.
Notes:
statementCacheSize
DB2 data source properties on UNIX and Windows are listed in the following table:
Table 403 Property dbname isolationLevel DB2 Data Source Properties on UNIX and Windows Description
dynamicIsolation: The isolation level is not set at the data source level. Setting this parameter to true allows the application to set this parameter dynamically as needed. readUncommitted: Specifies that corrupt data is not read. This is the lowest isolation level. readCommitted: Specifies that only the data committed before the query begun is displayed. repeatableRead: Specifies that the data used in a query is locked and cannot be used by another query, nor can it be u[dated by another transaction. serializable: Specifies that the data is isolated serially. Handles the data as if transactions are executed sequentially. If the specified isolation level is not supported by the data source, Attunity Connect defaults to the next highest level. When set to false (the default), specifies that the DB2 RDBMS handles the commitment control.
Notes:
The location of the library containing the database tables. When set to true, no extended matadata information is read from the DB2 database, including indexes. Specifies the maximum number of SQL statements that are cached. The default is set to 0, indicating no maximum limit.
In addition, for UNIX platforms, set the shared library environment variable (such as SHLIB_PATH, LD_LIBRARY_PATH, etc.), depending on the platform, to include $DB2HOME/lib. Set the shared library environment variable in the AIS nav_login or site_nav_login file. For further details, see Attunity AIS Installation Guide for UNIX.
Metadata
The DB2 data source driver polls the DB2 database for required metadata. Following the relational model, metadata definitions reside on a dedicated system table that is accessed by ordinary SQL queries.
Transaction Support
This section describes DB2 data source transaction support on the following platforms:
z/OS
The DB2 data source on z/OS systems supports Two-phase Commit and can fully participate in a distributed transaction when the following parameters are set:
The transaction environment property, convertAllToDistributed, is set to true in the binding configuration. RRS must be installed and configured.
The MVSATTACHTYPE parameter is set to RRSAF in the NAVROOT.USERLIB(ODBCINI) member (where NAVROOT is the high-level qualifier where AIS is installed). If RRS is not running, the data source or application adapter can participate in a distributed transaction as the only one-phase commit resource, provided that the logFile parameter is set to NORRS in the transactions node of the binding properties for the relevant binding configuration in the Design perspective, Configuration view in Attunity Studio. The XML representation is as follows:
<transactions logFile="log,NORRS" />
where log is the high-level qualifier and name of the log file. If this parameter is not specified, the format is as follows:
<transactions logFile=",NORRS" />
That is, the comma must be specified. For further details about setting up one-phase commit in a distributed transaction, refer to CommitConfirm Table. To configure two-phase commit capability To use two-phase commit capability to access data on a z/OS machine, define every library in the ATTSRVR JCL as an APF-authorized library.
To define a DSN as APF-authorized, enter the following command in the SDSF screen:
"/setprog apf,add,dsn=navroot.library,volume=ac002"
where ac002 is the volume where you installed AIS and NAVROOT is the high-level qualifier where AIS is installed.
If the AIS installation volume is managed by SMS, then when defining APF-authorization, enter the following command in the SDSF screen:
"/setprog apf,add,dsn=navroot.library,SMS"
Make sure that the library is APF-authorized, even after an IPL (reboot) of the machine. To use distributed transactions from an ODBC-based application, ensure that AUTOCOMMIT is set to 0.
OS/400
The DB400 data source on OS/400 supports one-phase commit transactions. The data can participate in a distributed transaction as a one-phase commit data source. To configure one-phase commit capability 1. Set the controlledCommit data source parameter to true, as described in Configuration Properties.
2. 3. 4.
Create a CMTCNFRM table. Set journaling to the CMTCNFRM table. Set the following binding parameters attributes for the client machine initiating the transaction:
1. 2.
Change the Transaction processor monitor name (TP_MON_NAME) property to the name of the DB2 data source (nvdbdb2 on Windows platforms or nvdb_db2 on UNIX platforms) by entering the following:
For Windows: UPDATE DATABASE MANAGER CONFIGURATION USING TP_ MON_NAME nvdbdb2 For UNIX: UPDATE DATABASE MANAGER CONFIGURATION USING TP_ MON_NAME nvdb_db2
Use DB2 with its two-phase commit capability through an XA connection.The daemon server mode must be configured to Single-client mode. For more information, see Server Mode. To use distributed transactions from an ODBC-based application, ensure that AUTOCOMMIT is set to 0.
Set the shared library environment variable (such as SHLIB_PATH, LD_ LIBRARY_PATH, depending on the platform) to include $DB2HOME/lib. Set the shared library environment variable in AIS nav_login or site_nav_ login file. For details, refer to the Attunity Installation Guide for UNIX.
Security
The DB2 data source driver is not actively involved in applying or enforcing security policy. It incorporates into the security policy and rules as set at the database instance with which it interacts.
ODBC SQL_BIGINT SQL_VARCHAR SQL_LONGVARCHAR SQL_DATE SQL_NUMERIC(p,s) SQL_DOUBLE SQL_REAL SQL_INTEGER SQL_NUMERIC(p,s) SQL_SMALLINT SQL_TIME SQL_TIMESTAMP SQL_VARCHAR SQL_LONGVARCHAR1 SQL_BIGINT
DBTYPE_STR DBTYPE_DATE dBTYPE_NUMERIC DBTYPE_R8 DBTYPE_R8 DBTYPE_I4 DBTYPE_NUMERIC DBTYPE_I2 DBTYPE_TIMESTAMP DBTYPE_TIMESTAMP DBTYPE_STR DBTYPE_STR DBTYPE_I8
Note: 1. SQL_LONGVARCHAR: Precision of 2147483647. If the <odbc longVarcharLenAsBlob> parameter is set to true in the AIS environment settings, then precision of m.
The following table shows how Attunity Connect maps data types in a CREATE TABLE statement to DB2 data types.
Table 405 CREATE TABLE Data Types DB2 Char(m) Date Float Float Long Varchar for Bit Data Integer Numeric(p,s) Smallint Text Time Timestamp Smallint Varchar(m)
CREATE TABLE Char(m) Date Double Float Image Integer Numeric [(p[,s])] Smallint Text Time Timestamp Tinyint Varchar(m)
z/OS
This section describes how to define a DB2 data source on z/OS systems. Defining a DB2 data source, involves the following procedures:
Defining an ODBCINI file Defining the Data Source Connection Configuring the Data Source
COMMON MVSDEFAULTSSID=DSN1 ; Example SUBSYSTEM odbcini for DSN1 subsystem DSN1 MVSATTACHTYPE=CAF PLANNAME=DSNACLI
The PLANAME value is the default DB2 Calling Level Interface (CLI) plan name. If a different plan is used, change the name accordingly. In the example above, CAF is used, so only one-phase commit transactions are supported. Two-phase commit transactions are supported when setting the MVSATTACHTYPE parameter to RRSAF.
Note:
The AUTOCOMMIT initialization parameter is set automatically by Attunity Studio, and should not be set in the ODBCINI file.
You must bind to the plan specified in the PLANAME parameter. Check that the DSNnnn.SDSNSAMP(DSNTIJCL) job includes the following line:
BIND PLAN (DSNACLI)
where DSNnnn is the DB2 high-level qualifier and DSNACLI is the plan name specified for the PLANAME parameter. You can specify other parameters in this file, as described in the IBM ODBC Guide and Reference.
In the Design perspective, Configuration view, expand the Machines folder. Expand the mainframe computer where you want to add your DB2 data source. Expand the Bindings folder. Expand the binding where you want to add the DB2 data source. Right-click the Data sources folder and select New Data source. The New Data Source screen is displayed.
7. 8. 9.
Enter a name for the data source in the Name field. Select DB2 CLI (Mainframe) from the Type list. Click Next. The Data Source connect string page is displayed.
Location: The DB2 location name for the connected DB2 instance. The parameter should be specified if the connected DB2 instance is different than the instance defined in the MVSDEFAULTSSID parameter of the ODBCINI file.
Database name: Enter the existing DB2 database name, only if you are creating new tables using AIS.
Note: If the DB2 CLI driver cannot connect to DB2 (SQLConnect problem), check that ALL ODBC packages are bounded.
In the Design perspective, Configuration view, expand the Machines folder. Expand the mainframe machine with your DB2 data source. Expand the Bindings folder, then expand the binding with your DB2 data source. Expand the Data sources folder, then right-click the DB2 data source and select Open. The data source editor is displayed.
6.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Data Source Connection.
7.
Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
8.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
OS/400
This section describes how to define a DB400 data source on the OS/400 platform. Defining a DB400 data source, involves the following procedures:
In the Design perspective, Configuration view, expand the AS/400 machine with your DB2 data source. Expand the Bindings folder Right-click the binding with the DB2 data source. Right-click the Data sources folder and select New Data source. Enter a name for the data source in the Name field. Select DB400 from the Type field. Click Next. The Data Source connect string screen is displayed.
9.
Database name: The name of the DB2 database. Library name: The library containing the database tables.
In the Design perspective, Configuration view, expand the Machines folder. Expand the AS/400 machine with your DB2 data source. Expand the Bindings folder, then expand the binding with your DB2 data source. Expand the Data sources folder, then right-click the DB2/400 data source in the Configuration view, and select Open. The data source editor is displayed.
6. 7.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
8.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
In the Design perspective, Configuration view, expand the Machines folder. Expand the UNIX or Windows machine with your DB2 data source. Expand the Bindings folder. Right click the binding with the DB2 data source. Right-click the Data sources folder and select New Data source. Enter a name for the data source in the Name field. Select DB2 from the Type field. Click Next. The Data Source connect string screen is displayed.
In the Design perspective, Configuration view, expand the Machines folder. Expand the UNIX or Windows machine with your DB2 data source. Expand the Bindings folder, then expand the binding with your DB2 data source. Expand the Data sources folder, then right-click the DB2 data source, and select Open. The data source editor is displayed.
6. 7.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
8.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
41
CISAM /DISAM Data Source
This section contains the following topics:
Overview Configuration Properties Transaction Support Data Types Defining a CISAM/DISAM Data Source Setting Up the CISAM/DISAM Data Source Metadata
Overview
The following sections provide information about defining and configuring the Attunity Connect CISAM/DISAM data source driver. This includes information regarding the Metadata that must be defined.
Supported Features
The CISAM data source supports the following key features:
Limitations
The number of records that can be locked at the same time in the DISAM data source is no more than 32767. If more than 32767 records are locked at the same time, an overflow occurs.
Configuration Properties
The following parameters can be configured in Attunity Studio for the CISAM/DISAM data source in the Properties tab of the Configuration Properties screen. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
audit=true|false: When set to true, this parameter activates an audit file for each table.
auditFile: The audit filename that is the concatenation of the value specified for the name attribute of the table statement with an aud suffix. This parameter is a string data type. disableExplicitSelect: When set to true, this parameter disables the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. filepoolCloseOnTransaction: When set to true, all files in the file pool for this data source close at the each end of each transaction (commit or rollback). filepoolSize: The number of instances of a file from the file pool that can be open concurrently. filepoolSizePerFile: The number of instances of a file from the file pool that can be open concurrently for each file. lockWait: This parameter specifies whether the data source driver waits for a locked record to become unlocked or returns a message that the record is locked. newFileLocation=string: The Data directory in the connect string, this parameter specifies the location of the CISAM/DISAM files and indexes you create with CREATE TABLE and CREATE INDEX statements. You must specify the full path for the directory. transactionLogFile: This parameter specifies the name of the file where the transaction log is written. The data type for this parameter is string. useGlobalFilepool: When set to true, this parameter specifies that a global file pool that can span more than one session is used.
Transaction Support
The CISAM/DISAM data source driver supports one-phase commit for CISAM/DISAM version 7.6 and above. It can participate in a distributed transaction if it is the only one-phase commit data source being updated in the transaction. A log file must exist and the path and name of this log file must be specified in the data source configuration, in the binding configuration. For details, refer to Defining a CISAM/DISAM Data Source.
Note:
Both the transaction environment properties convertAllToDistributed and useCommitConfirmTable must be set to true.
Data Types
The table below shows how Attunity Connect maps data types in a CREATE TABLE statement to CISAM/DISAM data types.
Table 411 CREATE TABLE Data Types CISAM/DISAM Char[(m)]
Table 411 (Cont.) CREATE TABLE Data Types CREATE TABLE Date Double Float Image Integer Numeric[(p[,s])] Smallint Text Tinyint Varchar(m) CISAM/DISAM Date+time Double Float Integer Numeric(p,s) Smallint Tinyint Varchar(m)
Defining the CISAM/DISAM Data Source Connection Configuring the CISAM/DISAM Data Source
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine where you want to add your CISAM/DISAM data source. Expand the Bindings folder. Expand the binding where you want to add the CISAM/DISAM data source. Right-click the Data sources folder and select New Data source. The New Data Source screen is displayed.
7. 8. 9.
Enter a name for the data source in the Name field. Select CISAM/DISAM from the Type list. Click Next. The Data Source Connect String screen is displayed.
Data Location: Enter the directory where the CISAM/DISAM files and indexes created with CREATE TABLE and CREATE INDEX statements reside. You must specify the full path. If a value is not specified in this field, the data
files are written to the DEF directory under the directory where AIS is installed.
Note:
The data files can have a physical file name or an environment variable name (which is translated before accessing the data). This is useful if the data is distributed among several physical files. For example, under UNIX the environment variable can be similar to the following:
when the employees table name is set in the data dictionary to $ALL_ EMPLOYEES. The value specified is used for the Data File field in the Design perspective Metadata tab in Attunity Studio
11. Click Finish.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your data source. Expand the Bindings folder and the binding with your CISAM/DISAM data source. Expand the Data sources folder. Right-click the CISAM/DISAM data source and select Open. The Configuration Properties screen is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the CISAM/DISAM Data Source Connection. Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
42
DBMS Data Source (OpenVMS Only)
This section contains the following topics:
Overview Functionality Configuration Properties Data Types Transaction Support Platform-specific Information Defining the DBMS Data Source Setting Up the DBMS Data Source Metadata
Overview
The DBMS data source provides:
Dynamic multi-streaming support: Any combination of databases and subschemas can be accessed, when needed. Minimal realm impact: Realms are readied only when you access their data, which ensures that you do not impact more resources than necessary. Full relational mapping: All DBMS operations are mapped to a relational model. This includes joining set members with their owners, joining owners with their set members, and using specific system sets. Update operations such as connecting, disconnecting, and reconnecting records and sets are also mapped to equivalent relational operations. This provides a host of client/server tools with access to DBMS data, without sacrificing DBMS functionality.
In addition, the DBMS data source provides array handling; see Handling Arrays. Hierarchical queries over owner and member sets, using the owner or member column to produce a chaptered result are also described in Producing Chapters.
Note:
The DBMS access examples refer to the PARTS database that is described throughout the Oracle DBMS documentation. See the Introduction to Oracle DBMS for information about creating the PARTS database.
Prerequisites
For information on supported DBMS versions, see Attunity Integration Suite Supported Systems and Resources.
The DBMS data source does not require CDD. A DBMS runtime license is sufficient to use the DBMS data source. A development license is not necessary.
Functionality
This section describes the following aspects of DBMS functionality:
Locking
Locking
Records are locked only when an explicit lock is requested by the client application or when a record is updated. This solves most of the locking problems that DBMS users frequently encounter. Locking behavior using the DBMS data source differs in some cases from that of typical DBMS strategies because the DBMS data source relaxes some of the strict locking strategies DBMS usually imposes when reading records. However, update related locks are imposed by DBMS regardless of the data source. Refer to the DBMS documentation set for further discussion of locking issues. Locking-related aspects of the DBMS data source include:
No records are locked when read unless a lock is requested by the client application. Because DBMS automatically locks every record you read, the data source driver implements this by unlocking each record immediately after it is read. If a client explicitly requests a lock on a particular record, the data source driver implements this request by placing the record DBKEY in a keeplist (see the DBMS documentation set for details on keeplists). If the client subsequently unlocks the record, the data source driver removes the corresponding DBKEY from the keeplist. Updating a record causes the record to be locked for the duration of the transaction. Connecting or disconnecting a record from a set causes an update lock on the record itself, and possibly on the prior and next records in a chain set. These locks remain in effect for the duration of the transaction.
Update Semantics
Updating a column or deleting a row in SQL is very similar to DBQ, although the syntax differs slightly. For example, the following syntax is used when changing a part price:
UPDATE PART SET PART_PRICE = 50 WHERE PART_ID = BR890123
For examples of comparisons between SQL and DBQ syntax, see SQL to DBQ Mapping Examples. Set operations, like connecting or disconnecting a record and an owner-member set or a systems set, however, are not typical SQL operations. For these operations to work from any SQL-based client, they need to be mapped to standard SQL operations. The
mapping implemented by the DBMS data source involves the same virtual columns used to map various set read operations.
Configuration Properties
The following properties can be configured for the DBMS data source in the Properties tab of the Configuration Properties screen. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect: When set to true, this parameter disables the explicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. rootFile: The root file in the connect string, this parameter specifies the database root file. This file may be referenced using a logical name. runMode: The Access Mode in the connect string, this parameter specifies the operation mode of the server readOnly, readwrite, batchRetrieval or reporting). The default setting is readonly. subSchema: The Sub schema in the connect string, this parameter specifies the name of a subschema. A separate directory must be specified for each subschema.
Data Types
This table shows how the DBMS_ADL utility imports DBMS database field types to the Attunity Data Dictionary (ADD) data types, which Attunity Connect maps to ODBC and OLE DB data types:
Table 421 DBMS Character D_Floating D_Floating Complex Date F_Floating F_Floating Complex G_Floating G_Floating Complex H_Floating H_Floating Complex Left Overpunched Numeric Mapping DBMS Data Types ADD string dfloat Not Supported vms_date dfloat Not Supported double Not Supported Not Supported Not Supported numstr_nlo SQL_NUMERIC SQL_NUMERIC SQL_NUMERIC DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_NUMERIC SQL_DOUBLE DBTYPE_R8 SQL_DATE SQL_DOUBLE DBTYPE_DATE DBTYPE_R8 ODBC SQL_CHAR SQL_DOUBLE OLE DB DBTYPE_STR DBTYPE_R8
Table 421 (Cont.) Mapping DBMS Data Types DBMS Right Overpunched Numeric Right Separate Numeric Signed Byte Signed Longword Signed Octaword Signed Quadword Signed Word Unsigned Byte Unsigned Longword Unsigned Numeric Unsigned Octaword Unsigned Quadword Unsigned Word Zoned Numeric ADD numstr_s numstr_nr int1 int4 Not Supported int8 int2 int1 int4 numstr_u Not Supported Not Supported int2 numstr_zoned SQL_SMALLINT SQL_NUMERIC DBTYPE_I2 DBTYPE_NUMERIC SQL_DOUBLE SQL_SMALLINT SQL_SMALLINT SQL_INTEGER SQL_NUMERIC DBTYPE_I4 DBTYPE_NUMERIC SQL_DOUBLE DBTYPE_I2 ODBC SQL_NUMERIC SQL_NUMERIC SQL_TINYINT SQL_INTEGER DBTYPE_I4 OLE DB DBTYPE_NUMERIC DBTYPE_NUMERIC
The DBMS data types listed above as Not Supported are transferred into the Attunity data dictionary as placeholders to allow Attunity Connect to be used on data that is supported. See also ADD Supported Data Types.
Transaction Support
The DBMS data source supports one-phase commit. It can participate in a distributed transaction if it is the only one-phase commit data source being updated in the transaction. Both the transaction environment properties convertAllToDistributed and useCommitConfirmTable must be set to true.
Platform-specific Information
This section contains the following topics:
Database Model Mapping Requirements Virtual Column Categories Virtual Columns and Indexes Using Virtual Columns Accessing DBMS Data DBMS Error Codes
Virtual Column Categories Virtual Columns and Indexes Using Virtual Columns SQL to DBQ Mapping Examples
Virtual Columns
Virtual columns are columns which are not part of the DBMS data record. Virtual columns are used to facilitate the mapping of sets to the relational model. This section has the following topics:
Using Virtual Columns Virtual Columns and Indexes Virtual Column Categories
Performing Owner-to-Member Set Joins Performing Member-to-Owner Set Joins Using System Sets Producing Chapters Using Reverse Fetch Connecting, Disconnecting, and Reconnecting Records and Owner Sets Connecting and Disconnecting Records and System Sets
Performing Owner-to-Member Set Joins Users experienced in retrieving data from DBMS are familiar with the idea of traveling through the database. For example, you start from the CLASS record and travel to the PART record using the CLASS_PART set to join the tables. In DBQ commands, you would fetch the CLASS record and then fetch all the parts within CLASS_PART to join CLASS to PART using the CLASS_PART set. In the DBMS data source, you use the virtual columns to traverse owner-member set joins. To move from one table to another table, you must pick up the DBKEY column
of the current table, and equate it to the virtual column of the set you want to use in the target table. For example, in SQL, using the virtual columns, write the following SQL statement:
SELECT * FROM CLASS CLASS, PART PART WHERE (PART._M_CLASS_PART = CLASS.__CLASS)
Start from the CLASS table and take the __CLASS column. Then move to the PART table using the CLASS_PART set, and equate the __CLASS column with the _M_ CLASS_PART column in the PART table. This yields the correct result because the _M_ CLASS_PART is always the DBKEY of the owner CLASS record, and the __CLASS field is also the DBKEY of the CLASS record. This concept of data traversal can be demonstrated using graphical query tools such as Microsoft MS Query. This figure shows the MS Query display for a join between CLASS, PART and QUOTE. Note how the query starts with CLASS, moves to PART (CLASS.__CLASS = PART._M_CLASS_PART), and then moves from PART to QUOTE (PART.__PART = QUOTE._M_PART_INFO).
Figure 421 MS Query Example for Data Traversal
Performing Member-to-Owner Set Joins Traversing the data from member-to-owner is specified just like the owner-to-member joins described in Performing Owner-to-Member Set Joins. For example, to start from PART and join to CLASS by equating PART.__PART and CLASS._O_CLASS_PART, use the following SQL syntax:
SELECT * FROM PART PART, CLASS CLASS WHERE (PART.__PART = CLASS._O_CLASS_PART)
Even though the operations resemble the owner-to-member join, the processing of the member-to-owner join is slightly different. The _O_CLASS_PART is usually empty. When used in an SQL statement like the above example, the DBMS data source assigns _O_CLASS_PART to the DBKEY of the member record. This is done so that the equation will remain true; the _O_CLASS_PART column will have the value of the __PART column.
This figure shows a combination of an owner-to-member join with a member-to-owner join. Note how the query starts with CLASS, moves to PART (owner-to-member), and then moves to EMPLOYEE (member-to-owner).
Figure 422 Member-to-Owner Query Example
Using System Sets The virtual columns for system sets, such as _S_ALL_PARTS_ ACTIVE, are assigned either 1 or 0 to indicate whether the row is a member of the set. To access the ALL_ACTIVE_PARTS set using this information, you write the following SQL:
SELECT * FROM PART PART WHERE ("_S_ALL_PARTS_ACTIVE" = 1)
You can also do the opposite, selecting all the records that are not members of the set:
SELECT * FROM PART PART WHERE ("_S_ALL_PARTS_ACTIVE" = 0)
Although the syntax is similar, the two operations are implemented differently: the first will actually use the ALL_PARTS_ACTIVE set, while the second may scan the table sequentially in order to find the matching rows. The Query Processor may use a system set without a virtual column even though the set was not explicitly requested in the SQL statement, if using such a set will yield better performance. For example, consider the following SQL statement:
SELECT * FROM PART PART WHERE (PART_ID = AZ456789)
The Query Processor will choose the ALL_PARTS system set because it is the equivalent of a normal index in a relational data source. The Query Processor factors these indexes into its execution strategy for the query when advantageous. Producing Chapters By using the virtual column of an owner record in the SQL, the DBMS data source retrieves all the set members for each specific owner record. In this example, the virtual column for the CLASS table is used to retrieve the parts for each class record:
In the SQL Utility, clicking on a chapter in the output displays all the set members for the specific owner. The chapterOF attribute must be specified for the member in the Attunity metadata. This attribute is generated automatically when generating Attunity metadata using the DBMS_ADL utility (see Metadata Considerations). Using Reverse Fetch The virtual column to enable a reverse fetch for a table is named _ REVERSE_FETCH. Such columns are not assigned real values, but serve as flags indicating that rows should be retrieved in reverse order. To use reverse fetch, you must include _REVERSE_FETCH in the WHERE clause, assigning any value to the column. For example, to retrieve all the rows in PARTS in reverse order, write the following SQL:
SELECT * FROM PART WHERE _REVERSE_FETCH = 1
This results in the DBQ command FETCH LAST followed by one or more FETCH PRIOR , instead of FETCH FIRST and then FETCH NEXT. Connecting, Disconnecting, and Reconnecting Records and Owner Sets The connection between a record and an owner set can be manipulated by changing the value of the associated _M_ driver column. The following statement, for example, will disconnect the PART record from the RESPONSIBLE_FOR set:
UPDATE PART SET _M_RESPONSIBLE_FOR = NULL WHERE PART_ID = BR890123
Similarly, using the following example you can connect the PART record to the EMPLOYEE record whose DBKEY is 4:2:1:
UPDATE PART SET _M_RESPONSIBLE_FOR = 4:2:1 WHERE PART_ID = BR890123
The DBMS data source includes the following special features related to set connections:
The data source driver validates any connection changes against the insertion and retention requirements defined in DBMS. For example, trying to disconnect from a mandatory retention set results in an appropriate error. Similarly, trying to insert a new record without supplying values for all the automatic insertion sets also fails. When changing a set connection, the data source driver checks whether the record was previously connected to the set. The data source driver then determines whether to use the DBQ CONNECT or RECONNECT command to implement the request. NULL values and blank values are treated the same for virtual columns; both cause the record to be disconnected from the set. An update command that tries to reconnect a record to its current set is ignored by the data source driver. You may connect a record to a specific position in a chained set by giving the currency of the preceding member instead of the currency of the owner as the value of the virtual column. The data source driver validates all supplied DBKEYs before performing any of the updates. If any element of the update request is invalid, the update is not performed. For example, when you issue an update that connects a PART to the RESPONSIBLE_FOR set and changes the PART_PRICE field, the entire operation fails if the DBKEY of the EMPLOYEE is invalid.
Connecting and Disconnecting Records and System Sets As with owner-member sets, the membership of a record in a system set is manipulated by changing the value of the associated virtual column. Virtual columns for system sets accept either 1 or 0 to denote membership or non-membership, respectively. For example, the following statement can be used to make a PART record non-active, that is, disconnecting it from the ALL_PARTS_ACTIVE set:
UPDATE PART SET _S_ALL_PARTS_ACTIVE = 0 WHERE PART_ID = BR890123
Similarly, you can make a PART active using the following syntax:
UPDATE PART SET _S_ALL_PARTS_ACTIVE = 1 WHERE PART_ID = BR890123
SQL to DBQ Mapping Examples The following examples show how the DBMS data source driver processes SQL statements into DBQ commands. Users familiar with DBQ may find these examples helpful in understanding how the data source driver works and how to best utilize it. Each example shows SQL text and the DBQ commands used by the data source driver to implement the request. (Tracing writes the actual DBQ commands to the server log file for the SQL.)
Example 421 Selecting from a Table Without Key Criteria
Selecting from a table without any key criteria (set) causes Attunity Connect to read through the records in DBMS chain (sequential or sorted) order.
(SQL) SELECT PART.PART_ID, PART.PART_DESC FROM PART (DBQ) FIND FIRST PART GET PART_ID PART_DESC FREE ALL CURRENT
Example 422
If any key columns are specified in the WHERE statement, Attunity Connect attempts to utilize the key (set).
(SQL) SELECT PART.PART_ID, PART.PART_DESC FROM PART WHERE (PART.PART_ID=BR890123) (DBQ) FIND FIRST PART WITHIN ALL_PARTS WHERE PART_ID EQ "BR890123" GET PART_ID PART_DESC FREE ALL CURRENT Example 423 Referencing a DBMS Set With _S_<SetName> Virtual Column Name
To reference a DBMS set that has the _S_<SetName> virtual column name, you must set the column equal to 1. This results in the Query Processor passing the column name to the data source driver. The data source driver then utilizes the set.
(SQL) SELECT PART.PART_ID, PART.PART_DESC FROM PART PART WHERE (PART."_S_ALL_PARTS_ACTIVE"=1) (DBQ) FIND FIRST PART WITHIN ALL_PARTS_ACTIVE GET PART_ID PART_DESC FREE ALL CURRENT Example 424 Joining an Owner Record to a Member Record
To select and join an owner record to a member record, set the _M_<SetName> virtual column in the member record equal to the virtual anchor __<RecordName> of the owner record. (Note the double underscore __ in the virtual anchor name.)
(SQL) SELECT PART.PART_ID, COMPONENT.COMP_SUB_PART FROM COMPONENT COMPONENT, PART PART WHERE (COMPONENT."_M_PART_USES" = PART."__PART") (DBQ) FIND FIRST PART GET PART_ID FREE ALL CURRENT FIND DBKEY FIND FIRST COMPONENT WITHIN PART_USES GET COMP_SUB_PART FREE ALL CURRENT
To select and join a member record to an owner record, set the _O_<SetName> virtual column in the owner record equal to the virtual anchor __<RecordName> of the member record.
(SQL) SELECT COMPONENT.COMP_SUB_PART, PART.PART_ID FROM COMPONENT COMPONENT, PART PART WHERE (PART."_O_PART_USED_ON" = COMPONENT."__COMPONENT") (DBQ) FIND FIRST COMPONENT GET COMP_SUB_PART FREE ALL CURRENT FIND DBKEY FIND OWNER WITHIN PART_USED_ON GET PART_ID FREE ALL CURRENT
Example 425
Adding a Record
To add a new record, all of the automatic insertion _M_<SetName> member virtual columns must be set to a valid DBKEY. The DBKEY can be that of a desired owner record or the DBKEY of an existing record in the table which has the owner that is needed, in the format Area:Page:Line. To add a new record with automatic insertion using an owner record and a system chain set:
(SQL) INSERT INTO PART (PART_ID, PART_DESC, PART_STATUS, PART_PRICE, PART_COST, PART_SUPPORT, "_S_ALL_PARTS_ACTIVE", "_M_CLASS_PART", "_M_RESPONSIBLE_FOR", "__PART") VALUES (AA0001,DESC, G, 1.5, 0.5, Y, 1, 2:4:1, NULL, NULL) (DBQ) FIND DBKEY RETAINING ALL EXCEPT CLASS_PART STORE PART FREE ALL CURRENT COMMIT Example 426 Deleting a Record
To delete a record:
(SQL) DELETE FROM CLASS WHERE (CLASS_CODE = OL) (DBQ) FIND FIRST CLASS WITHIN ALL_CLASS WHERE CLASS_CODE EQ "OL" GET CLASS_CODE CLASS_DESC CLASS_STATUS FREE ALL CURRENT FIND DBKEY RETAINING ALL EXCEPT ALL_CLASS FIND NEXT CLASS WITHIN ALL_CLASS WHERE CLASS_CODE EQ "OL" FREE ALL CURRENT FIND DBKEY ERASE FREE ALL CURRENT COMMIT
To delete a record that has a mandatory member with records, the member records must be removed first. As shown in the following example, attempting to delete such a record fails, and the transaction is rolled back.
(SQL) DELETE FROM CLASS WHERE (CLASS_CODE = PC)
GET CLASS_CODE CLASS_DESC CLASS_STATUS FREE ALL CURRENT FIND DBKEY RETAINING ALL EXCEPT ALL_CLASS FIND NEXT CLASS WITHIN ALL_CLASS WHERE CLASS_CODE EQ "PC" FREE ALL CURRENT FIND DBKEY ERASE DB_FS_INTERFACE(35); Error: DB_DBMS_INTERFACE(2), %DBM-F-ERASEMANDT, MANDATORY member can be erased only with ERASE ALL; EXECUTE DB_DBMS_INTERFACE(2), ERASE(DELETE) FREE ALL CURRENT ROLLBACK Example 427 Utilizing a Connect on the PART Record
Note: If you place any member virtual columns _M_<SetName> into a SELECT, the data source driver reads the member records to get a DBKEY value for the member virtual column. This occurs regardless of whether the SELECT includes a specific value or a wildcard for the member virtual column. You should do this only if you either need information from the member record or will join to the member record.
Exposing Virtual Columns and Indexes Insertion Automatic Manual Retention Fixed Mandatory Fixed Mandatory Optional Virtual Column None _S_<SetName> Index _K_<SetName> _S_<SetName>
System sets
Automatic
An ordered system set that has insertion and retention such that every row is always a member of the set is considered to be the equivalent of a regular index in a Relational Data Source. As such, it does not need a special virtual column. An index (_K_ <SetName>) is created for it and the Query Processor utilizes it if it benefits query performance. An example is the ALL_PARTS system set in the PARTS table. All system sets that include only a subset of the table rows have a _S_ driver column created for them. An example is the ALL_PARTS_ACTIVE system set. In the Attunity metadata for the virtual columns, the explicitSelect clause should not be set in order to display the columns with a SELECT * statement. If the explicitSelect clause is set, the virtual columns must be explicitly stated in the SELECT statement (SELECT *, _M_aaa, ). The following table shows the values returned in virtual columns for a simple SELECT * FROM PART SQL statement.
Table 423 Values Returned for a SELECT SQL Statement _S_ALL _PARTS PART_ID BR890123 TE234567 TE217890 _ACTIVE 1 0 0 _M _CLASS _PART 1:53:2 1:21:1 1:21:1 _M_RESPONSIBLE _FOR 4:82:1 4:82:1 4:23:1 _O_ PARTS _USES _O_PART _USED _ON _O_PART _INFO __PART 1:8:1 1:13:1 1:16:1
BR890123 is the only active part. The others have 0 as the value of _S_ALL_ PARTS_ACTIVE. 1:53:2 is the DBKEY of the CLASS record that owns BR890123. 4:82:1 is the DBKEY of the EMPLOYEE record that is responsible for part BR890123 and part TE234567. All of the owner virtual columns are empty unless used in a member-to-owner join. 1:8:1 is the DBKEY of the BR890123 PART record.
System set
_S_<set-name>
Owner of a set
_O_<set-name>
_REVERSE_ FETCH
The CLASS table of the sample PARTS database, for example, is the owner of the CLASS_PART set, while the PART table is the member of the CLASS_PART set, as well as the RESPONSIBLE_FOR set. It is also the owner of the PARTS_USES, PART_USED_ ON and PART_INFO sets. This example shows the columns exposed by the data source for the CLASS and PART tables:
Figure 424 CLASS and PARTS Tables
If the DBMS data source link was not set during the AIS installation, then you need to link the data source before you can access DBMS data. To link the DBMS data source 1. Link the DBMS data source using the following command:
$ @NAVROOT:[BIN]NAV_DBMS_BUILD
If specified DBMS as one of the data sources during the installation., then continue to step 2.
2.
If you want to install the DBMS data source (NAVROOT:[BIN]NVDB_DBMS.EXE) as a shareable image, add the DBMS data source to NAV_START.COM in NAVROOT:[BIN] and SYS$STARTUP so that stopping and restarting AIS will install the image. You must restart AIS after relinking the data source by executing the NAV_ START.COM script.
3.
If you are upgrading the DBMS data source from a previous version, the DBMS data source installation links the data source at the site with the current version of DBMS. If you upgrade the DBMS installation to a new version, then you may need to relink the DBMS data source (you must relink when upgrading from DBMS 4.3 to the 6.0 series). The following command relinks the data source:
$ @NAVROOT:[BIN]NAV_DBMS_BUILD
Note:
When accessing DBMS, do not specify multiClient as the server mode in the daemon workspace.
DBMS Code Symbolic Name 2654220 2654236 2654252 2654268 2654284 2654300 2654316 2654332 2654348 2654364 2654380 2654396 DBM$_ABORT_WAIT DBM$_AREABUSY DBM$_BAD_ARGLST DBM$_BADDBNAME DBM$_BADKBIND DBM$_BADSSCLST DBM$_BADZERO DBM$_BUGCHECK DBM$_CANTBINDRT DBM$_CANTEXTDBS DBM$_CANTOPENOUT DBM$_CANTUSERUJ
Table 425 (Cont.) DBMS Error Codes DBMS Code Symbolic Name 2654412 2654428 2654444 2654460 2654476 2654492 2654508 2654524 2654540 2654556 2654572 2654588 2654604 2654620 2654636 2654652 2654668 2654684 2654700 2654716 2654732 2654748 2654764 2654780 2654796 2654820 2654836 2654852 2654868 2654884 2654900 2654916 2654932 2654945 2654964 2654980 2654996 DBM$_CHKMEMBER DBM$_CKEYMOVE DBM$_COMPMOVE DBM$_CRELM_NULL DBM$_CRTYP_NULL DBM$_CRUN_NULL DBM$_CSTYP_NULL DBM$_DBBUSY DBM$_DUPNOTALL DBM$_ERASEMANDT DBM$_ID_MAP DBM$_INTERLOCK DBM$_NODEFVAL DBM$_NOLOCKAVAIL DBM$_NOMONITOR DBM$_NOROOTBIND DBM$_NOTIMPLYET DBM$_NOTWITHIN DBM$_NOT_MBR DBM$_NOT_OPTNL DBM$_NOT_UPDATE DBM$_OVERFLOW DBM$_REENTRANCY DBM$_SHUTDOWN DBM$_SKEYMOVE DBM$_TRAN_IN_PROG DBM$_UNDERFLOW DBM$_UNSCONV DBM$_USRFRCEXT DBM$_SSVERSION DBM$_CURDISPLA DBM$_BUGCHKDMP DBM$_ROLLBACK DBM$_TRUE DBM$_DORURECOV DBM$_CANTOPENIN DBM$_DATCNVERR DBMS Code Symbolic Name 2654420 2654436 2654452 2654468 2654484 2654500 2654516 2654532 2654548 2654564 2654580 2654596 2654612 2654628 2654644 2654660 2654676 2654692 2654708 2654724 2654740 2654756 2654772 2654788 2654804 2654828 2654844 2654860 2654876 2654892 2654908 2654924 2654937 2654956 2654972 2654988 2655004 DBM$_CHKRECORD DBM$_COMPLEX DBM$_CONVERR DBM$_CRELM_POS DBM$_CRTYP_POS DBM$_CRUN_POS DBM$_CSTYP_POS DBM$_DEADLOCK DBM$_END DBM$_FIXED DBM$_ILLNCHAR DBM$_NOCREMBX DBM$_NOLLBAVAIL DBM$_NONDIGIT DBM$_NOREALM DBM$_NOSSBIND DBM$_NOTOTYP DBM$_NOT_BOUND DBM$_NOT_MTYP DBM$_NOT_READY DBM$_NOW_MBR DBM$_READY DBM$_SETSELECT DBM$_SINGSTYP DBM$_STAREAFUL DBM$_TRUNCATION DBM$_UNSCOMP DBM$_USE_EMPTY DBM$_WRONGRTYP DBM$_SSVERSION2 DBM$_KPLDISPLA DBM$_ABORTED DBM$_FALSE DBM$_NOWILD DBM$_INVDBSFIL DBM$_CNVNUMDAT DBM$_MISMMORDD
Table 425 (Cont.) DBMS Error Codes DBMS Code Symbolic Name 2655012 2655028 2655044 2655236 2655252 2655268 2655284 2655300 2655316 2655332 2655348 2655364 2655380 2655396 2655412 2655428 2655444 2655460 2655476 2655492 2655508 2655524 2655540 2655556 2655572 2655588 2655604 2655620 2655636 2655652 2655668 2655684 2655700 2655716 2655732 2655748 2655764 DBM$_BDDATRANG DBM$_NOTSYSCONCEAL DBM$_NODBK DBM$_BAD_KCALL DBM$_KBOUND DBM$_NOTBOOL DBM$_UNSARITH DBM$_STRNOTFND DBM$_EXQUOTA DBM$_SIP DBM$_CANTOPENRUJ DBM$_MONMBXOPN DBM$_NOPRIV DBM$_MONTRMFOR DBM$_MONMBXDEL DBM$_MONDELLOG DBM$_CANTSNAP DBM$_BADAIJFILE DBM$_ROOMAJVER DBM$_BADAIJTAD DBM$_CANTCREMBX DBM$_CANTSENDMAIL DBM$_NOCHAR DBM$_CANTDELETE DBM$_LOGINISTA DBM$_LOGREINIT DBM$_CANTCREDBS DBM$_CANTGETRUJ DBM$_CANTREADDBS DBM$_CHECKSUM DBM$_BUFTOOSML DBM$_LOGCREATE DBM$_LOGSNPSTA DBM$_LOGSNPINI DBM$_INVREREADY DBM$_BADBNDPRM DBM$_AIJOPEN DBMS Code Symbolic Name 2655020 2655036 2655052 2655244 2655260 2655276 2655292 2655308 2655324 2655340 2655356 2655372 2655388 2655404 2655420 2655436 2655452 2655468 2655484 2655500 2655516 2655532 2655548 2655564 2655580 2655596 2655612 2655628 2655644 2655660 2655676 2655692 2655708 2655724 2655740 2655756 2655772 DBM$_BADDATDEF DBM$_LCKCNFLCT DBM$_NOUSERNAM DBM$_ISI DBM$_MONABORT DBM$_WASBOOL DBM$_STALL DBM$_AREA_CORRUPT DBM$_NOSIP DBM$_NOSNAPS DBM$_CANTOPENAIJ DBM$_NOMONLOGNAM DBM$_MONTRMDEL DBM$_MONTRMSUI DBM$_GBLSECDEL DBM$_CANTDELLOG DBM$_EMPTYAIJ DBM$_NOTROOT DBM$_MUSTRECDB DBM$_DBRABORTED DBM$_CANTREADAIJ DBM$_CANTCREDBR DBM$_LOGDELFIL DBM$_LOGINIDBS DBM$_LOGNEWDBS DBM$_CANTFLSHRUJ DBM$_CANTCONNRUJ DBM$_CANTTRNCRUJ DBM$_QIOXFRLEN DBM$_CANTWRITEDBS DBM$_CANTCREROO DBM$_LOGGBLSEC DBM$_LOGSNPFNM DBM$_ACCVIO DBM$_NONODE DBM$_BADBOUNDS DBM$_CORRUPT_ROOT
Table 425 (Cont.) DBMS Error Codes DBMS Code Symbolic Name 2655780 2655796 2655812 2655828 2655844 2655860 2655876 2655892 2655908 2655924 2655940 2655956 2655972 2655988 2656004 2656020 2656036 2656052 2656068 2656084 2656100 2656116 2656132 2656148 2656164 2656180 2656196 2656212 2656244 2656284 2656300 2656316 2656332 2656356 2656372 2656388 2656412 DBM$_DUPGSDNAM DBM$_INV_ROOT DBM$_INV_SSDD DBM$_NORTUPB DBM$_RECOVERY DBM$_ROOT_OPEN DBM$_STOPPED DBM$_DBJ_NOTREADY DBM$_BADAIJNAM DBM$_FREE_VM DBM$_ROOTMAJVER DBM$_HARDERROR DBM$_TERMINATE DBM$_CANTREAD DBM$_BADFILTYP DBM$_MODVALSTR DBM$_CANTQIOMBX DBM$_AIJSQ2EOF DBM$_AIJCLSTAD DBM$_AIJLIMBOC DBM$_AIJSTART2 DBM$_AIJUNCOMR DBM$_AIJLIMBOI DBM$_AIJBADPID DBM$_AIJSTART1 DBM$_BADROOTMATCH DBM$_CANTMODFYEOF DBM$_CANTMASTERDB DBM$_NO DBM$_CANTADDUSER DBM$_OPERSHUTDN DBM$_CANTLCKTRM DBM$_CANTREADDB DBM$_DBNOTACTIVE DBM$_MONSTOPPED DBM$_CANTASSMBX DBM$_FILACCERR DBMS Code Symbolic Name 2655788 2655804 2655820 2655836 2655852 2655868 2655884 2655900 2655916 2655932 2655948 2655964 2655980 2655996 2656012 2656028 2656044 2656060 2656076 2656092 2656108 2656124 2656140 2656156 2656172 2656188 2656204 2656236 2656260 2656292 2656308 2656324 2656340 2656364 2656380 2656404 2656420 DBM$_INHIBRECOV DBM$_INV_SCDD DBM$_INV_STDD DBM$_NOUSERPID DBM$_ROOT_NOT_OPEN DBM$_SSNOTINROOT DBM$_NORESEXT DBM$_NOWILDAIJ DBM$_NOLABEL DBM$_GET_VM DBM$_MICROFAIL DBM$_SUICIDE DBM$_CANTWRITE DBM$_MONOC DBM$_LOGMODIFY DBM$_CANTCREMON DBM$_AIJERREOF DBM$_AIJSEQEOF DBM$_AIJRECFST DBM$_AIJLIMBOR DBM$_AIJLOGMSG DBM$_AIJERRSTP DBM$_AIJSUCCES DBM$_AIJBADMAI DBM$_CANTMAPTROOT DBM$_CANTGETEOF DBM$_TOOMANYDUPS DBM$_YES DBM$_MODVAL DBM$_CANTCLOSEDB DBM$_CANTCREGBL DBM$_CANTOPENDB DBM$_DBACTIVE DBM$_DBSHUTDOWN DBM$_OPERCLOSE DBM$_MODAREVAL DBM$_NOAIJDIR
Table 425 (Cont.) DBMS Error Codes DBMS Code Symbolic Name 2656428 2656444 2656460 2656476 2656492 2656508 2656524 2656540 2656556 2656572 2656588 2656604 2656620 2656636 2656652 2656668 2656684 2656700 2656716 2656732 2656748 2656764 2656780 2656796 2656812 2656828 2656844 2656860 2656876 2656892 2656908 2656924 2656940 2658308 2658324 2658340 2658356 DBM$_LOGFILACC DBM$_NOAIJDEF DBM$_AIJENABLED DBM$_NOTRANAPP DBM$_LOGAIJBCK DBM$_TADMISMATCH DBM$_NOCONVERT DBM$_NOTDSKFIL DBM$_NODEVDIR DBM$_QUIETPT DBM$_MODAREFLG DBM$_LOGRECSTAT DBM$_INVHEADER DBM$_BKUPEMPTYAIJ DBM$_ERROPENIN DBM$_ERRFOREIGN DBM$_RUJDEVDIR DBM$_LOGBCKAIJ DBM$_LOGCREDB DBM$_LOGCRESTO DBM$_LOGCREOUT DBM$_LOGINISTO DBM$_LOGRECDB DBM$_LOGMODFLG DBM$_LOGMODSTR DBM$_ERRWRITE DBM$_LOGALGFAC DBM$_AREARSTR DBM$_BADSPAMINT DBM$_MONFLRMSG DBM$_BADBUFSIZ DBM$_LOGMODSPM DBM$_CONFTXNOPTION DBM$_GROUPNA DBM$_NOTSTAREA DBM$_BADUWALST DBM$_OBSRTDDCB DBMS Code Symbolic Name 2656436 2656452 2656468 2656484 2656500 2656516 2656532 2656548 2656564 2656580 2656596 2656612 2656628 2656644 2656660 2656676 2656692 2656708 2656724 2656740 2656756 2656772 2656788 2656804 2656820 2656836 2656852 2656868 2656884 2656900 2656916 2656932 2656948 2658316 2658332 2658348 2658364 DBM$_LOGINIFIL DBM$_BADASCTOID DBM$_LOGRECOVR DBM$_AIJDISABLED DBM$_RESTART DBM$_CANTSPAWN DBM$_LOGCONVRT DBM$_NOTIP DBM$_BADAIJVER DBM$_DBNOTOPEN DBM$_PREMEOF DBM$_EMPTYFILE DBM$_DELAREA DBM$_AREA_INCONSIST DBM$_ERROPENOUT DBM$_AIJDEVDIR DBM$_SNAPFULL DBM$_LOGOPNAIJ DBM$_LOGCREAIJ DBM$_LOGCRESNP DBM$_LOGCREBCK DBM$_LOGINISNP DBM$_LOGPAGCNT DBM$_LOGMODVAL DBM$_READ_ONLY DBM$_LOGALGCNT DBM$_SETWIDTH DBM$_BADPARAM DBM$_TIMEOUT DBM$_PARTDTXNERR DBM$_LOGMODSTO DBM$_GETTXNOPTION DBM$_LOGRESOLVE DBM$_SECURVIO DBM$_BADSTRADDR DBM$_NOSTREAM DBM$_NOROLLB
Table 425 (Cont.) DBMS Error Codes DBMS Code Symbolic Name 2658372 2658388 2658404 2658420 2658436 2658452 2658468 2658484 2662411 2662427 2662443 2662459 2662475 2662491 2662507 2662523 2662539 2662555 2664451 2664467 2664483 2664499 2664515 2664531 2668555 2668571 2668587 2668603 2668619 10059796 10059812 10059828 10059844 10059860 10059876 10059892 10059908 DBM$_ONSTREAM DBM$_OUTSTRCTX DBM$_NETERR DBM$_RECNOTINSS DBM$_UNIRECORD DBM$_EPCBADCAL DBM$_DTXNABORTED DBM$_NOBATUPD DBM$_STAT_COMMIT DBM$_STAT_DISCONNECT DBM$_STAT_FETCH DBM$_STAT_KEEP DBM$_STAT_READY DBM$_STAT_STORE DBM$_STAT_IF_EMPTY DBM$_STAT_IF_NULL DBM$_STAT_IF_TENANT DBM$_STAT_USE DBM$_STAT_DBM_VERBS DBM$_STAT_LCK_LOCK DBM$_STAT_PIO_DB_R DBM$_STAT_RUJ_FLUSH DBM$_STAT_LCK_CNFL DBM$_STAT_PIO_FETCH DBM$_STAT_PSII_CRE DBM$_STAT_PSII_INS DBM$_STAT_PSII_REM DBM$_STAT_PSII_DIST1 DBM$_STAT_PSII_DIST3 DBQ$_BAD_ARGLST DBQ$_CABORT DBQ$_CANTDOIT DBQ$_END DBQ$_EXTRAINPUT DBQ$_ILLCHAR DBQ$_LISTTOOBIG DBQ$_NOFILE DBMS Code Symbolic Name 2658380 2658396 2658412 2658428 2658444 2658460 2658476 2662403 2662419 2662435 2662451 2662467 2662483 2662499 2662515 2662531 2662547 2662563 2664459 2664475 2664491 2664507 2664523 2668547 2668563 2668579 2668595 2668611 10059788 10059804 10059820 10059836 10059852 10059868 10059884 10059900 10059916 DBM$_NO_DBMREG DBM$_BADPROTOCOL DBM$_BADDBKEY DBM$_CURDISNUL DBM$_UNIMEMBER DBM$_NOCMRLDTXN DBM$_NOTSET DBM$_STAT_TRANS DBM$_STAT_CONNECT DBM$_STAT_ERASE DBM$_STAT_FREE DBM$_STAT_MODIFY DBM$_STAT_ROLLBACK DBM$_STAT_IF_ALSO DBM$_STAT_IF_MEMBER DBM$_STAT_IF_OWNER DBM$_STAT_IF_WITHIN DBM$_STAT_STAT DBM$_STAT_DBM_VROLL DBM$_STAT_LCK_DEMO DBM$_STAT_PIO_DB_W DBM$_STAT_RUJ_PUT DBM$_STAT_LCK_HOLD DBM$_STAT_PSII_BAL DBM$_STAT_PSII_DES DBM$_STAT_PSII_MOD DBM$_STAT_PSII_SEA DBM$_STAT_PSII_DIST2 DBQ$_AMBIGITEM DBQ$_BADELSE DBQ$_IGNRCAST DBQ$_OBS_CONVERR DBQ$_EXIT DBQ$_IGNORED DBQ$_INCONRECITEM DBQ$_NOCURREC DBQ$_NOTBOUND
Table 425 (Cont.) DBMS Error Codes DBMS Code Symbolic Name 10059924 10059940 10059956 10059972 10059988 10060004 10060020 DBQ$_OBS_NOTIMPLYET DBQ$_NOTITEM DBQ$_SYNTAX DBQ$_TOKTOOBIG DBQ$_CANTBEUSED DBQ$_EMPTYLOOP DBQ$_OPANDOVR DBMS Code Symbolic Name 10059932 10059948 10059964 10059980 10059996 10060012 10060028 DBQ$_NOTINCALL DBQ$_NOTPOSNUM DBQ$_SYNTXEOS DBQ$_ZABORT DBQ$_CANTPRINT DBQ$_MISMATMOV DBQ$_OPATOROVR
Defining the DBMS Data Source Connection Configuring the DBMS Data Source Properties
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine where you want to add your data source. Expand the Bindings folder. Expand the binding where you want to add the DBMS data source. Right-click the Data sources folder and select New Data Source. The New Data Source screen is displayed.
7. 8. 9.
Enter a name for the data source in the Name field. Select DBMS from the Type list. Enter the connect string as follows:
Root File: Specify the database root file. This file may be referenced using a logical name. Subschema: Specify the name of a subschema. (You must specify a separate directory for each subschema.) Access Mode: Enter the access mode for the connection (ReadOnly, readwrite,batchRetrieval or reporting). The default value is reporting.
Note:
You must specify a database definition for each database and subschema combination that you need to access.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the DBMS data source and select Open. The Configuration Properties screen is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the DBMS Data Source Connection. Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
Note:
You must specify a database definition for each database and subschema combination that you need to access.
9.
After setting the binding, you must define Attunity metadata describing the DBMS data.
where:
root-file: The name of the DBMS root file. If a logical is used for the root-file, the extension.ROO must be part of the logical specification.
subschema: The name of the DBMS subschema. ds_name: The name of a data source defined in the binding. The imported metadata is stored as ADD metadata in the repository for this data source. exp_select: When x is specified for this parameter, the explicit select attribute of virtual fields is disabled. basename: A user defined name, used for the intermediate files used during the import operation
The following example creates an ADD entry in the repository for the DBMS_PROD data source, for the PARTS.ROO and the PARTSS1 subschema: $ CREATE/DIRECTORY DKA100:[PARTS.PARTSS1] $ DBMS_ADL PART$DIR:PARTS.ROO PARTSS1 DBMS_PROD Also refer to Data Types and how they are converted to Attunity metadata data types.
43
Enscribe Data Source (HP NonStop Only)
This section describes the Attunity Enscribe Data Source Driver. It includes the following topics:
Overview Functionality Configuration Properties Metadata Transaction Support Security Enscribe Data Types Defining the Enscribe Data Source Setting up the Enscribe Data Source Metadata Testing the Enscribe Data Source
Overview
Attunity Connect supports the following Enscribe file types:
Key-sequenced. Entry-sequenced Relative: The Enscribe driver exposes a column called # for the relative record number. The # column can be used in SQL statements just like any other column. The Enscribe driver exposes a virtual index on the # column. It implements the index functionality using the Enscribe API. Unstructured: Unstructured files that keep fixed length records are supported. The unstructured file is read using a read-ahead buffer of 4K. The Enscribe driver also supports RBA usage. The RBA holds the relative record number in the stream file where the record begins. The RBA column can be used in SQL statements just like any other column. Set the record organization in the metadata to unstructured.
Functionality
The Attunity Enscribe data source driver supports the following Enscribe key features:
Record-level locking on Enscribe data for both audited and unaudited files using the HP NonStop LOCKREC and UNLOCKREC calls
Array structures within the Enscribe record Variant (redefined) structures within the Enscribe record
Configuration Properties
The following parameters can be configured in Attunity Studio for the Enscribe data source in the data source Properties tab. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
createAuditFiles: Specifies that any Enscribe file created using the CREATE TABLE SQL statement is audited. The volume must be audited in order to create audited files. This parameter value can be set to True or False. disableExplicitSelect: Disables the field level ExplicitSelect ADD attribute. Every field is returned by a SELECT * FROM... statement. This parameter value can be set to True or False. enscribeLockMode: Specifies the value of the SETMODE parameter of the Guardian Set Lock Mode Procedure. The default value is set to 3. Valid values are:
0: Normal mode. A request is suspended when a read or lock is attempted and an established record lock or file lock is encountered. 1: Reject mode. A request is rejected with file-system error 73 when a read or lock is attempted and an established record lock or file lock is encountered. No data is returned for the rejected request. 2: Read-through/normal mode. READ or READUPDATE ignores record locks. Encountering a lock does not delay nor prevents the reading of a record. The locking response of LOCKFILE, LOCKREC, READLOCK, and READUPDATELOCK is identical to normal mode (mode 0). 3: Read-through/reject mode. READ or READUPDATE ignores record locks and file locks. Encountering a lock does not delay nor prevents the reading of a record. The locking response of LOCKFILE, LOCKREC, READLOCK, and READUPDATELOCK is identical to reject mode (mode 1). 6: Read-warn/normal mode. READ or READUPDATE returns data without regard to record and file locks. However, encountering a lock causes code 9 to be returned with the data. The locking response of LOCKFILE, LOCKREC, READLOCK, and READUPDATELOCK is identical to normal mode (mode 0). 7: Read-warn/reject mode. READ or READUPDATE returns data without regard to record and file locks. However, encountering a lock causes code 9 to be returned with the data. The locking response of LOCKFILE, LOCKREC, READLOCK, and READUPDATELOCK is identical to reject mode (mode 1).
enscribeLockType: Specifies whether record or file level locking are used when a lock is requested. Valid values are:
-1: No locking.
filepoolCloseOnTransaction: Specifies that all files in the file pool for this data source close at each end of transaction (commit or rollback). This parameter value can be set to True or False. filepoolSize: Specifies how many instances of a file from the file pool may be open concurrently. filepoolFilePerSize: Specifies how many instances of a file from the file pool may be open concurrently for each file. newFileLocation: Specifies the location of the Enscribe files and indexes you create with CREATE TABLE and CREATE INDEX statements. You must specify the full path for the subvolume. This parameter value is of a string type. supportFormat2: Specifies whether Format2 is supported by the version of the NSK operating system used. This property can be overridden in the metadata by setting dbCommand to FORMAT1 or FORMAT2. This parameter value can be set to True or False. transactions: Specifies whether or not TMF transactions are started. Set this property to False when dealing with unaudited files as a TMF transaction is not required. This parameter value can be set to True or False. useGlobalFilepool: Specifies a global file pool that can span over more than one session. This parameter value can be set to True or False.
Metadata
The Enscribe data source driver requires Attunity Metadata. You can import the metadata from COBOL copybooks, a DDL subvolume or from TAL files. If COBOL copybooks or a DDL subvolume or TAL files, which describe the Enscribe records, do not exist, then the metadata must be manually defined. If the metadata exists only as COBOL copybooks, then you can import the metadata to Attunity using the Enscribe import utility in the Design perspective, Metadata tab of Attunity Studio. If the metadata exists in a DDL subvolume or as TAL data files, you can use the stand-alone ADDIMP and TALIMP import utilities to import metadata to Attunity metadata from these sources. You use the Metadata tab in Attunity Studio to maintain the Attunity metadata and update the statistics for the data.
Transaction Support
Attunity Enscribe data source driver supports one-phase commit transactions. It can
participate in a distributed transaction if it is the only one-phase commit data source being updated in the transaction, when the covertAllToDistributed and useCommitConfirmTable environment properties are set to true. The Enscribe and SQL/MP data sources and the Pathway adapter share the same transaction which automatically provides consistency between Enscribe and SQL/MP.
As a result, you cannot start the new transaction for SQL/MP when one is open for Enscribe.
Note:
Security
The Enscribe data source driver does not apply or enforce security policy.
Defining the Enscribe Data Source Connection Configuring the Enscribe Data Source
In the Design perspective, Configuration view, expand the Machines folder. Expand the computer where you want to add your Enscribe data source.
4. 5. 6.
Expand the Bindings folder. Expand the binding where you want to add the Enscribe data source. Right-click the Data sources folder and select New Data source. The New Data Source screen is displayed.
7.
When you enter a name for the data source, the name must begin with a letter. In addition, if you do not supply the Repository Information on the Advanced tab of the Data Source editor, the default names that AIS generates for the metadata files will be unique. AIS creates a NOS file and a BBNOS file. The file names are created by using the characters in the data source name and then by ensuring that the first letter is legal on the HP NonStop platform. To make sure that the generated files are unique, you must make the sixth through eighth alphanumeric characters of the data source name alphabetic and unique. If the data source name contains fewer than eight alphanumeric characters, the last three alphanumeric characters must be alphabetic and unique. If the data source name contains five or more alphanumeric characters, the last five cannot all be the letter B.
If you enter the Repository Information on the Advanced tab of the Data source editor, make sure that you use the rule above for the filenames created by the Repository directory (HP NonStop volume/subvolume) and name, not the data source name.
8. 9.
Select Enscribe from the Type list. Click Next. The Data Source Connect String screen opens.
10. Enter the Enscribe the Data SubVolume where the Enscribe files and indexes
created with CREATE TABLE and CREATE INDEX statements reside. If a value is not specified, then created files are written to the subvolume where the Attunity Connect is installed. The name of an index created in this subvolume must be different from the name of any table in the subvolume. If only accessing existing Enscribe files, then this value does not need to be specified.
11. Click Finish.
The new Enscribe data source is now displayed in the Configuration view, and its properties tabs are displayed in the Editor pane. See also: Adding Data Sources.
3. 4. 5. 6.
Expand the machine with your Enscribe data source. Expand the Bindings folder and the binding with your Enscribe data source. Expand the Data sources folder. Right-click the Enscribe data source and select Open. The Configuration Properties screen is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Enscribe Data Source Connection. Configure the Enscribe data source parameters as required. For a description of the available Enscribe parameters, see Configuration Properties.
Importing Metadata from COBOL Importing Metadata Using the ADDIMP Utility Importing Metadata Using the TALIMP Utility Maintaining Metadata
In the Design perspective, Configuration view expand the Machines folder and then expand the machine with the data source where you are importing the metadata. Expand the Bindings folder and expand the binding with the data source metadata you are working with. Expand the Data Source folder. Right-click the data source that you are working with and select Show Metadata View. The Metadata view opens with the selected data source displayed.
3. 4. 5.
6.
Right-click Imports under the data source and select New Import. The New Import dialog box is displayed, as shown in the following figure:
7. 8.
Enter a name for the import. The name can contain letters, numbers and the underscore character. Select the Import type from the list. You can select:
9.
Click Finish.
See Importing Data Source Metadata with the Attunity Import Wizard for an explanation of how to use the import wizard.
Where:
template: The template used in the COBOL COPYFROM statement. replace_string: The string used to replace all occurrences of template, if it has a value. If template has a value and replace_string is not set, all occurrences of template are made empty. ds_name: The name of the data source defined in the binding. The imported metadata is stored as ADD metadata in the repository for this data source. DDL_export_list: The records to be imported from the DDL dictionary. If the list contains more than one record, then the list must be surrounded by double quotes (""). This parameter defaults to *, importing all records. To import DDL definitions, set the z parameter as described below. filename_table: A text file containing a list of records and the names of their data files. Each row in this file has two entries: record_name and physical_enscribe_data_file_name (used for the value for the Data file field for the table in Attunity Studio Design perspective metadata tab). If a table is not listed in this text file, the entry for the Data file field for the table defaults to table_FIL, where table is the name of the table. If this text file does not exist, the names for the Data file field specifying the tables default to table_FIL, where table is the name of the table. The format of the file is tablename $vol.subvol.file. For example:
EMPLYEE $USER.PERS.EMPLOYEE
Notes: Fields mapped to a key segment must be contiguous in each table definition.
When the filename defaults to table_FIL, you must change this name (using Attunity Studio Design perspective metadata tab, or NAV_UTIL EDIT) to the correct name, in order to access the data.
variant_table: A list of variants with their selector fields and the valid values for each selector field. Each line in the list has the following format:
variant-field, selector,-field, "val1", "val2", ..., "valN"
Note:
All the val# arguments must be surrounded by double quotes. If a val# argument contains a comma or double quote, then the character must be doubled.
If the variant line is too long, break the line at a comma separator. For example:
var_1,selector_1,"a","b","c" var_2,selector_2,"a23456789012345", "b23456789012345","c23456789012345", "d23456789012345"
rec_filter: Specifies the set of records you want to import as an AWK regular expression. For example, you can use special characters, such as ., *, "[...]", "\{n,m\}", ^, $. For information on AWK regular expression, see AWK reference documentation.
basename: Specifies the user-defined name of the intermediate files used during the import procedure. The following files are generated (the default file names appear in parentheses): basenameA (IADDIMPA) basenameF (IADDIMPF) basenameL (IADDIMPL) basenameC (IADDIMPC)
Note:
If these files already exist, write/purge access to them is required when you run the utility.
d: Specifies that all intermediate files are saved. You can check these files if problems occur in the conversion. c: Specifies that the column name is used for an array name, instead of the concatenation of the parent table name with the child table name.
Note:
f a column name is not unique in a structure (as when a structure includes another structure, which contains a column with the same name as a column in the parent structure), the nested column name is suffixed with the nested structure name.
f a counter field is defined after the array field, check the resulting XML to ensure that the column name is fully qualified.
p: Specifies that punch card formatting is implemented. Columns after column 72 in every line are ignored. 6: Specifies that the first 6 columns of every line are ignored (ANSI COBOL is assumed instead of extended COBOL). 7: Specifies that COBOL74 is used. If this is not specified, then COBOL85 is used. z: Specifies that the metadata is exported from DDL definitions and not the DDL records (the default). files: Specifies the structure files for the Enscribe tables. Each file is in the format of a COBOL copylib file. Only one subvolume of a DDL dictionary is allowed. An intermediate filename file and an intermediate copylib file are generated from the dictionary. Separate the files in this list with blanks.
Note: The COBOL file must start at the 01 level (that is 01 record-name) and include the entire record definition (and not a reference to a copybook file elsewhere).
Example
run addimp -n ENSDATA d0117.ddldata
To display online help for this utility, run the command with help as the only parameter, as follows:
ADDIMP -i
The files in the command line are processed in order. When the same table name occurs more than once, the latest definition of the table is used for the ADD. If a DDL dictionary is specified, the generated intermediate location file and structure file are placed first. The ADDIMP utility enables you to overwrite the location (listed in the DDL dictionary) of an Enscribe table with a specific filename file, in cases when the dictionary entry is not current. For unstructured Enscribe files, ADDIMP sets the Organization attribute in the generated metadata to Index. Edit the metadata from Attunity Studio Design perspective, Metadata tab to change the Organization value from Index to Unstructured for each table, in the metadata editor General tab.
Note:
Note that you must include a filler field, of size one, when including an odd record size in an even unstructured Enscribe file.
You have a TAL data file instead of a COBOL copybook. The DDL uses identifiers that are restricted words in COBOL but not in TAL.
Note:
When using a HP NonStop Himalaya $CMON system monitor, the system monitor may conflict with the import utility. This may cause the utility to hang. In this case, temporarily stop the $CMON process
To generate the metadata 1. From the Start menu, select Programs, Attunity, and then select Command Line Console.
2.
Where:
ds_name: The name of the data source defined in the binding. The imported metadata is stored as ADD metadata in the repository for this data source. DDL_export_list: The records to be imported from the DDL dictionary. If the list contains more than one record, then the list must be surrounded by double quotes (""). This parameter defaults to *, importing all records. To import DDL definitions, set the z parameter as described below. filename_table: A text file containing a list of records and the names of their data files. Each row in this file has two entries: record_name and physical_enscribe_data_file_name (used for the value for the Data file field for the table in Attunity Studio Design perspective, metadata tab). If a table is not listed in this text file, the entry for the Data file field for the table defaults to table_FIL, where table is the name of the table. If this text file does not exist, the names for the Data file field specifying the tables default to table_FIL, where table is the name of the table. The format of the file is tablename $vol.subvol.file. For example:
EMPLYEE $USER.PERS.EMPLOYEE
Notes: Fields mapped to a key segment must be contiguous in each table definition.
When the filename defaults to table_FIL, you must change this name (using Attunity Studio Design perspective metadata tab, or NAV_UTIL EDIT) to the correct name, in order to access the data.
variant_table: A list of variants with their selector fields and the valid values for each selector field. Each line in the list has the following format:
variant-field, selector,-field, "val1", "val2", ..., "valN"
Note:
All the val# arguments must be surrounded by double quotes. If a val# argument contains a comma or double quote, then the character must be
43-11
If the variant line is too long, break the line at a comma separator. For example:
var_1,selector_1,"a","b","c" var_2,selector_2,"a23456789012345", "b23456789012345","c23456789012345", "d23456789012345"
rec_filter: Specifies the set of records you want to import as an AWK regular expression. For example, you can use special characters, such as ., *, "[...]", "\{n,m\}", ^, $. For information on AWK regular expression, see AWK reference documentation.
TAL_columns: Specifies the value of the COLUMNS directive in the TAL compilation command. If a value is not specified, then 132 is used (the TAL default). basename: Specifies the user-defined name of the intermediate files used during the import procedure. The following files are generated (the default file names appear in parentheses): basenameA (TTALIMPA) basenameF (TTALIMPF) basenameF (TTALIMPF) basenameL (TTALIMPL) basenameC (TTALIMPC)
Note:
If these files already exist, write/purge access to them is required when you run the utility.
q: Turns on the query mode, in which the import process pauses at each intermediate step. d: Specifies that all intermediate files are saved. You can check these files if problems occur in the conversion. c: Specifies that the column name is used for an array name, instead of the concatenation of the parent table name with the child table name.
Note:
f a column name is not unique in a structure (as when a structure includes another structure, which contains a column with the same name as a column in the parent structure), the nested column name is suffixed with the nested structure name
z: Specifies that the metadata is exported from DDL definitions and not the DDL records (the default). files: Specifies the structure files for the Enscribe tables. Each file is in the format of a COBOL copylib file. Only one subvolume of a DDL dictionary is
allowed. An intermediate filename file and an intermediate copylib file are generated from the dictionary. Separate the files in this list with blanks. To display online help for this utility, run the command with help as the only parameter, as follows:
ADDIMP -i
The files in the command line are processed in order. When the same table name occurs more than once, the latest definition of the table is used for the ADD. If a DDL dictionary is specified, the generated intermediate location file and structure file are placed first. Embedded COLUMNS are processed according to TAL language rules. The TALIMP utility enables you to overwrite the location (listed in the DDL dictionary) of an Enscribe table with a specific filename file, in cases when the dictionary entry is not current. For unstructured Enscribe files, TALIMP utility sets the Organization attribute in the generated metadata to Index. Edit the metadata from Attunity Studio Design perspective, Metadata tab to change the Organization value from Index to Unstructured for each table, in the metadata editor General tab. You must include a filler field, of size one, when including an odd record size in an even unstructured Enscribe file.
Maintaining Metadata
You can maintain the metadata and update the statistics for the data in Attunity Studio Design perspective, Metadata tab. The indexId attribute in Attunity metadata for an alternate index is the ASCII value corresponding to the 2 bytes of the key specifier. For example, for an alternate index in Enscribe described by fup as:
ALTKEY (2, FILE 0, KEYOFF 15, KEYLEN 12, UNIQUE)
21337 is derived from the ASCII values of S (0x53) and Y (0x59). Thus the ASCII value of SY is 0x5359 and its decimal equivalent is 21337 (the value in the indexId clause must be in quotes).
Connection test: This tests the physical connection to the data source. Query test: This test runs an SQL SELECT query against the data source.
These test are described in the following sections: To test the connection to the Enscribe data source 1. Open Attunity Studio.
2. 3. 4.
In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your Enscribe data source. Expand the binding with the Enscribe data source.
43-13
5. 6.
Expand the Data sources folder. Right-click the required Enscribe data source, and select Test. The Test Wizard screen opens.
7.
Select Navigator from the Active Workspace Name list, and click Next. The system now tests the connection to the data source, and returns the test result status.
8.
1. 2. 3. 4. 5. 6.
To test the Enscribe data source by query Open Attunity Studio. In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your Enscribe data source. Expand the binding with the Enscribe data source. Expand the Data sources folder. Right-click the required Enscribe data source entity, and select Query Tool. The Select Workspace screen opens.
7.
Select Navigator and click OK. The Query Tool opens in the Editor pane, with the Build Query tab displayed (see step 10.).
8. 9.
Select the required query type from the Query Type list. The default is a SELECT-type query. Locate and expand the required Enscribe data source. The Enscribe data source tables are listed.
10. Drag the required table to the Table column, as shown in the following figure:
The Query Result tab opens, displaying the results of the query.
12. Close the Query Tool in the Editor pane.
<<<<<<<<<<<<<<<<<<<
43-15
Accessing Database 'informix' with SQL: SELECT T0000.n_nationkey AS c000, T0000.n_name AS c001, T0000.n_regionkey AS c002, T0000.n_comment AS c003 FROM 'inf9'.nation T0000
>>>>>>>>>>>>>>>>>>>> Execution Strategy End >>>>>>>>>>>>>>>>>>>>>>>>>>>> nvOUT (./qpsqlcsh.c 140): ---------------------------> Using Cached QSpec SELECT T0000.n_nationkey AS c000, T0000.n_name AS c001, T0000.n_regionkey AS c002, T0000.n_comment AS c003 FROM 'inf9'.nation T0000
nvRETURN (./drviunwn.c 804): -1210 (Last message occurred 2 times) Disabled FilePool Cleanup(DB=___sys, FilePool Size=0) FilePool Shutdown(DB=___SYS, FilePool Size=0) Closing log file at SAT DEC 3 13:39:12 2005
44
Flat File Data Source
This section contains the following topics:
Configuration Properties Defining a Flat File Data Source Setting Up the Flat File Data Source Metadata
Configuration Properties
The following parameters can be configured in Attunity Studio for the Flat File data source in the Properties tab of the Configuration Properties screen. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect: When set to true, this parameter disables the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. headerRows: This parameter specifies the number of lines at to be skipped at the beginning of each file. You can override this value by specifying a <dbCommand> statement in ADD. newFileLocation: The data location in the connect string, this parameter specifies the location of the Flat files and indexes you create with CREATE TABLE statements. You must specify the full path for the directory.
Defining the Flat File Data Source Connection Configuring the Flat File Data Source
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine where you want to add your Flat File data source. Expand the Bindings folder. Expand the binding where you want to add the Flat File data source. Right-click the Data sources folder and select New Data Source. The New Data Source screen is displayed.
7. 8. 9.
Enter a name for the data source in the Name field. Select Flat files from the Type list. Click Next. The Data Source Connect String screen is displayed.
Data Location: Specify the directory where the Flat files and indexes created with CREATE TABLE and CREATE INDEX statements reside. You must specify the full path. If a value is not specified in this field, the data files are written to the DEF directory under the directory where AIS is installed.
Note:
The value specified is used for the Data File field in the Design perspective, Metadata tab in Attunity Studio.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the Flat File data source and select Open. The Configuration Properties screen is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Flat File Data Source Connection. Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
In the Design perspective, Configuration view, right-click the data source and select Show Metadata View. The Metadata tab is displayed with the data source displayed in the Metadata view.
3. 4. 5. 6. 7.
Right-click Imports and select New Import. Enter a name for the import. The name can contain letters, numbers and the underscore character. Select COBOL Import Manager for Data Sources as the import type. Click Finish. The Metadata Import Wizard is displayed. Click Add in the Import Wizard to add COBOL copybooks. The Add Resource screen is displayed, providing the option of selecting files from the local machine or to FTP the files from another machine. This figure shows the Add Resource Screen.
8. 9.
If the files are on another machine, then right-click My FTP Sites and select Add. Set the FTP data connection by entering the server name where the COBOL copybooks reside and, if not using anonymous access, enter a valid username and password to access the machine. using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory.
10. To browse and transfer files required to generate the metadata, access the machine
11. Select the files to import and click Finish to start the transfer.
The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns together with a COBOL copybook that ignores the first six columns. In this type of case, repeat the import process.
You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks. The selected files are displayed in the Get Input Files screen of the wizard, as shown in Get Input Files Screen.
Figure 443 Get Input Files Screen
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type. Compiler source: The compiler vendor. Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Prefix nested column: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity] metadata, is replaced with an underscore. Case sensitive: Specifies whether to consider case sensitivity or not. Find: Searches for the specified value. Replace with: Replaces the value specified for in the Find field with the value specified here.
The import manager identifies the names of the records in the COBOL copybooks that will be imported as tables.
15. Select the tables that you want to access (and thus require Attunity metadata) and
You can perform the following actions in the Import Manipulation screen.
Resolve table names, where tables with the same name are generated from different COBOL copybooks specified during the import. Specify the physical location for the data. Specify table attributes. Manipulate the fields generated from the COBOL, as follows: Merge sequential fields into one for simple fields Resolve variants either by marking a selector field or by specifying that only one case of the variant is relevant Add, delete, hide, or rename fields Change a data type Set a field size and scale Change the order of the fields Set a field as nullable Select a counter field for array for fields with dimensions (arrays) Set r fields with dimensions (arrays) Create new fields instead of the array field, where the number of generated fields will be determined by the array dimension. Create arrays and set the array dimension.
The Validation tab in the bottom half of the screen displays information about what must be done to validate the tables and fields generated from the COBOL.
The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location).
16. To manipulate table information or the fields in the table, right-click the table and
Fields manipulation: Access the Fields Manipulation screen to customize the field definitions. Rename: Rename a table name. This option is used especially when more than one table is generated from the COBOL with the same name. Set data location: Set the physical location of the data file for the table. Set table attributes: Set table attributes. The table attributes are described XSL manipulation location: Specify an XSL transformation or JDOM document that is used to transform the table definition.
This section lets you generate virtual and sequential views for imported tables containing arrays. In addition, you can configure the properties of the generated views. In the Metadata Model Selection step, you can select configure values that apply to all tables in the import or set specific settings for each table. To configure the metadata model
Select one of the following: Default values for all tables: Select this if you want to configure the same values for all the tables in the import. Make the following selections when using this option: Generate sequential view: Select this to map non-relational files to a single table. Generate virtual views: Select this to have individual tables created for each array in the non-relational file. Include row number column: Select one of the following: true: Select true, to include a column that specifies the row number in the virtual or sequential view. This is true for this table only, even in the the data source is not configured to include the row number column. false: Select false, to not include a column that specifies the row number in the virtual or sequential view for this table even if the data source is configured to include the row number column. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties. Inherit all parent columns: Select one of the following: true: Select true, for virtual views to include all the columns in the parent record. This is true for this table only, even in the data source is not configured to include all of the parent record columns.
false: Select false, so virtual views do not include the columns in the parent record for this table even if the data source is configured to include all of the parent record columns. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties. Specific virtual array view settings per table: Select this to set different values for each table in the import. This will override the data source default for that table. Make the selections in the table under this selection. See the item above for an explanation.
The final window lets you import the metadata to the machine where the data source is located or leave the generated metadata on the Attunity Studio machine, to be imported later.
19. Specify that you want to transfer the metadata to the machine where the data
source is located and click Finish. The metadata is imported to the machine where the data source is located.
45
IMS/DB Data Sources
This section contains the following topics:
Overview Functionality Configuration Properties Transaction Support Defining the IMS/DB DLI Data Source Defining the IMS/DB DBCTL Data Source Defining the IMS/DB DBDC Data Source Setting Up IMS/DB Metadata
Overview
AIS supports SQL data access to IMS/DB data in the following three IMS/DB environments:
IMS-DLI: Batch access. The AIS server issues direct DLI commands to retrieve data as a standalone batch program. This means that the database is accessed from the AIS-started task without going through any of the IMS control regions. This access method is suited to nightly processing, such as bulk loading when the IMS control region is down. It is usually not suited for general multi-user data access. IMS-DBCTL: This data source is suited to users employing CICS as their primary application platform for accessing IMS data. All AIS servers communicate with an AIS-supplied CICS program. This program accepts requests for scheduling PSBs and retrieving data through DBCTL services. IMS-DBDC: This data source is suited to users employing IMS/TM as their primary application platform for accessing IMS/DB data. All AIS servers communicate with an AIS-supplied IMS/TM transaction. This MPP transaction accepts requests from AIS servers and performs the DLI requests on their behalf.
Supported Features
The IMS/DB data sources support the following key features:
Relational-like view of an IMS hierarchical database. For more information, see Functionality. Metadata import from a combination of DBD files, TSBs and COBOL copybooks. DML access to IMS/DB data. Transactional support including one-phase commit or two-phase commit. OCCURS clauses within segment data are supported. For more information, see Handling Arrays. Primary key access support to IMS/DB data.
Environmental Prerequisites
Environmental prerequisites vary according to specific data source.
IMS-DLI Prerequisites
There are no specific environmental prerequisites for IMS-DLI.
IMS-DBCTL Prerequisites
AIS uses EXCI to interface to CICS. EXCI requires some set up:
IRC must be open. Use CEMT I IRC from the CICS screen to check your IRC status. If in closed state, set it to open. A specific connection must be set up. Use CEMT I connection to get the list of available connections. Note that you can only use specific connections which have a VTAM netname associated with them. The default available on most systems is BATCHCLI. Attunity provides a JCL for defining an Attunity connection. See the CICS CONF member in the USERLIB. An EXCI mirror transaction ID must be available. The default on most systems is transaction ID EXCI. You can use the CEMT I TRA PROG(DFHMIRS) to get the list of EXCI transaction IDs available on your system. The PSBs to be accessed through AIS must be available in the DBCTL environment, i.e. the AIS CICS program must be able to do EXEC DLI SCHEDULE PSB.
IMS-DBDC Prerequisites
OTMA must be installed and running by executing the command /DISP OTMAto verify that this is the case.
An XCF group and member must be defined for IMS. The OTMA C/I must be installed. Note that for OTMA C/I, the OTMAINIT job must be run following an IPL. See Appendix C of the OTMA Guide and Reference online at http://tinyurl.com/lrpn.
Limitations
When accessing IMS data, the following limitations apply:
General IMS Limitations Limitations Specific to IMS/DLI Limitations Specific to IMS-DBCTL Limitations Specific to IMS/DBDC
Supported are only databases that have a unique key for every element in a hierarchy, except for end-segments. The support of end-segments without a unique key is limited to read only, with no array (OCCURS clause) support. DDL is not supported. Logical databases are supported. Logical children are not supported. Secondary indexes are not supported. Segments whose key is partitioned to several fields in the COBOL layout are supported by exposing both the COBOL-level fields and an additional field that overlays these fields and spans the entire key. The following limitations apply: Only queries that refer to the overlaid field in the WHERE clause develop an efficient execution strategy. For such a key, only alphanumeric field types are supported.
The IMS/DLI data source must be set up in a separate workspace for every PSB accessed because the PSB is explicitly coded in the started task JCL. Transactional operations, such as COMMIT and ROLLBACK, are not supported. All DML operations are therefore non-transactional. UPDATE operations are supported, but it is not recommended to run them over several servers in parallel.
Transactional operations, such as COMMIT and ROLLBACK, are not supported. All DML operations are therefore non-transactional. Every data source definition can work with a single PSB only. Multiple data source can be created for multiple PSBs. Segments within a non-unique index are not supported at any level.
Functionality
Examples in this section use the Hospital Database Example. This section contains information on the following topics:
Hierarchical Modelling
The IMS/DB data sources map the hierarchical model of IMS/DB to the relational model in the following manner:
Every segment is mapped to a table. The fields in a table consist of the IMS segment buffer and the IMS keyfeedback area. The index for an IMS table consists of the keyfeedback, i.e. the entire path leading to the specific segment.
The Hospital Database Example includes a simple hierarchy HOSPITAL > WARD > PATIENT. The following figures show the relational model of this three-level hierarchy in AIS.
Selecting a PCB
When accessing any segment, the data source driver first needs to select a PCB to be used for this purpose. The choice of PCB is made according to the metadata. The metadata import includes the PSB as one of the import sources. As a result, each table definition in the AIS data dictionary includes a list of PCB numbers that can be used for every table. For example, in the following figure, PCB0 will be used to access the HOSPITAL database. Note that you can have several PCBs for each table if your PSB includes several PCBs for the same database.
Figure 455 PCB Selection
DLI Samples
The Attunity IMS data source employs a small but effective vocabulary of IMS commands and SSA variations to satisfy incoming requests. The following list of examples shows SQL queries and the equivalent IMS commands used.
Table 451 SQL Query select * from patient; SQL Queries with Respective IMS Commands IMS Command GU/GN HOSPITAL WARD PATIENT select * from patient where hospname='Spalding Rehabilitat'; GU/GN HOSPITAL*C(Spalding Rehabilitat) WARD PATIENT select * from patient where hospname='Spalding Rehabilitat' and wardno='3 '; select * from patient where hospname='Spalding Rehabilitat' GU/GN HOSPITAL WARD PATIENT GU/GN HOSPITAL WARD PATIENT *C(Spalding Rehabilitat3 020 ) select * from patient where hospname>'Spalding Rehabilitat'; GU/GN HOSPITAL(HOSPNAME>=Spalding Rehabilitat) WARD PATIENT select * from patient where hospname='Spalding Rehabilitat' and wardno>'2 '; GU/GN HOSPITAL*C(Spalding Rehabilitat) WARD PATIENT ( WARDNO >=2 ) *C(Spalding Rehabilitat3 )
Table 451 (Cont.) SQL Queries with Respective IMS Commands SQL Query select * from patient where hospname='Spalding Rehabilitat' and wardno='3 ' and bedident>='020'; IMS Command GU/GN HOSPITAL WARD *C(Spalding Rehabilitat3 )
PATIENT (BEDIDENT>=020 )
Configuration Properties
The properties configured for the IMS/DB data source vary according to the specific type of data source in use.
IMS/DB DLI Configuration Properties IMS/DB DBCTL Configuration Properties IMS/DB DBDC Configuration Properties
For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect: When set to true, this parameter disables the explicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement.
cicsProgname: This parameter specifies the ATYDBCTL program that is supplied with AIS to enable updating the IMS data source. To use the ATYDBCTL program, copy the program from NAVROOT.LOAD to a CICS DFHRPL library (such as CICS.USER.LOAD) and then define the ATYDBCTL program under CICS using any available group such as ATY group: NAVROOT is the high-level qualifier where AIS is installed. After defining the ATYDBCTL program to a group, install it as follows: CEDA IN G(ATY)
cicsTraceQueue: This parameter specifies the e name of queue for output which is defined under CICS when tracing the output of the ATYDBCTL program. When not defined, the default CICS queue is used. disableExplicitSelect=true|false: When set to true, this parameter disables the explicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. exciTransid: This parameter specifies the CICS TRANSID. This value must be EXCI or a copy of this transaction. pbsName=string: The PSB Name in the connect string, this parameter contains details of all the IMS/DB databases that you want to access.
targetSystemApplid: The Target System in the connect string, this parameter specifies the VTAM applid of the CICS target system. The default value is CICS. This parameter is used when updating VSAM data. You can determine this value by activating the CEMT transaction on the target CICS system. The legend APPLID=target_system appears in the bottom right corner of the screen. vtamNetname: The VTAM NetName in the connect string, this parameter specifies the connection being used by EXCI (and MRO) to relay the program call to the CICS target system. The default value is ATYCLIEN.
disableExplicitSelect: When set to true, this parameter disables the explicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. imsTransname: This parameter specifies the name of the IMS transaction that points to the program that is used to access the PSB used to access the IMS/DB data. The default name of the transaction is ATYIMSTM. maxSessions: This parameter specifies the maximum number of sessions allowed. The default value is 5. racfGroupId: This parameter specifies the security facility group identification (for example, the RACF group identification). racfUserId: This parameter specifies the security resource user name. tpipePrefix: The TPipe prefix in the connect string, this parameter is used to associate between the transaction and the transaction pipe it is using. The default is ATTU. xcfClient: This parameter specifies the client name for the Cross System Coupling Facility to which the connection belongs. xcfGroup: The XCF group in the connect string, this parameter specifies the Cross System Coupling Facility collection of XCF members the connection belongs to. A group may consist of up to eight characters, and may span between multiple systems. xcflmsMember: This parameter specifies the Cross System Coupling Facility group member. xcfServer: The XCF server in the connect string, this parameter specifies the Cross System Coupling Facility group member.
Transaction Support
The IMS-DBCTL data source supports transaction processing. The IMS/DB DLI and IMS/DB DBDC data sources do not support transaction processing.
RRS must be configured and running on your system in order to use 1PC. When working with 1PC, it is important to correctly configure the timeout of your EXCI mirror transaction. The DTIMEOUT parameter in the CEDA transaction definition must exceed the maximum expected transaction duration. The default EXCI transaction is usually configured with a DTIMEOUT of 10 seconds, which may be problematic in terms of its short duration.
3.
01 HOSPITAL. 03 HOSPNAME 03 HOSP-ADDRESS 03 HOSP-PHONE 03 ADMIN 01 WARD. 03 WARDNO 03 TOT-ROOMS 03 TOT-BEDS 03 BEDAVAIL 03 WARDTYPE
01 PATIENT. 03 PATNAME 03 PATADDRESS 03 PAT-PHONE 03 BEDIDENT 03 DATEADMT 03 PREV-STAY-FLAG 03 PREV-HOSP 03 PREV-DATE 03 PREV-REASON
PIC X(20). PIC X(30). PIC X(10). PIC X(4). PIC X(6). PIC X. PIC X(20). PIC X(4). PIC X(30).
01 SYMPTOM. 03 DIAGNOSE PIC X(20). 03 SYMPDATE PIC X(6). 03 PREV-TREAT-FLAG PIC X. 03 TREAT-DESC PIC X(20). 03 SYMP-DOCTOR PIC X(20). 03 SYMP-DOCT-PHONE PIC X(10). 01
1
TREATMNT.
Kapp, Dan and Leben, Joe: IMS Programming Techniques. Van Nostrand Reinhold Company Inc., New York, 1986.
03 03 03 03 03 03 03
TRTYPE PIC X(20). TRDATE PIC X(6). MEDICATION-TYPE PIC X(20). DIET-COMMENT PIC X(30). SURGERY-FLAG PIC X. SURGERY-DATE PIC X(6). SURGERY-COMMENT PIC X(30).
01 DOCTOR. 03 DOCTNAME 03 DOCT-ADDRESS 03 DOCT-PHONE 03 SPECIALT 01 FACILITY. 03 FACTYPE 03 TOT-FACIL 03 FACAVAIL Example 452
Hospital DBD
PRINT NOGEN DBD NAME=HOSPDBD,ACCESS=HDAM,RMNAME=(DFSHDC40,40,100) DATASET DD1=PRIME,DEVICE=3390 SEGM NAME=HOSPITAL,PARENT=0,BYTES=80 FIELD NAME=(HOSPNAME,SEQ,U),BYTES=20,START=1,TYPE=C FIELD NAME=ADMIN,BYTES=20,START=61,TYPE=C SEGM NAME=WARD,PARENT=HOSPITAL,BYTES=31 FIELD NAME=(WARDNO,SEQ,U),BYTES=2,START=1,TYPE=C FIELD NAME=BEDAVAIL,BYTES=3,START=9,TYPE=C FIELD NAME=WARDTYPE,BYTES=20,START=12,TYPE=C SEGM NAME=PATIENT,PARENT=WARD,BYTES=125 FIELD NAME=(BEDIDENT,SEQ,U),BYTES=4,START=61,TYPE=C FIELD NAME=PATNAME,BYTES=20,START=1,TYPE=C FIELD NAME=DATEADMT,BYTES=6,START=65,TYPE=C SEGM NAME=SYMPTOM,PARENT=PATIENT,BYTES=77 FIELD NAME=(SYMPDATE,SEQ),BYTES=6,START=21,TYPE=C FIELD NAME=DIAGNOSE,BYTES=20,START=1,TYPE=C SEGM NAME=TREATMNT,PARENT=PATIENT,BYTES=113 FIELD NAME=(TRDATE,SEQ),BYTES=6,START=21,TYPE=C FIELD NAME=TRTYPE,BYTES=20,START=1,TYPE=C SEGM NAME=DOCTOR,PARENT=PATIENT,BYTES=80 FIELD NAME=DOCTNAME,BYTES=20,START=1,TYPE=C FIELD NAME=SPECIALT,BYTES=20,START=61,TYPE=C SEGM NAME=FACILITY,PARENT=HOSPITAL,BYTES=26 FIELD NAME=FACTYPE,BYTES=20,START=1,TYPE=C FIELD NAME=FACAVAIL,BYTES=3,START=24,TYPE=C DBDGEN FINISH END
Example 453
Hospital PSB
PRINT NOGEN PCB TYPE=DB,DBDNAME=HOSPDBD,PROCOPT=AP,KEYLEN=32 * SENSEG SENSEG SENSEG SENSEG SENSEG SENSEG SENSEG * PSBGEN LANG=COBOL,PSBNAME=HOSPPSB END NAME=HOSPITAL,PARENT=0 NAME=WARD,PARENT=HOSPITAL NAME=PATIENT,PARENT=WARD NAME=SYMPTOM,PARENT=PATIENT NAME=TREATMNT,PARENT=PATIENT NAME=DOCTOR,PARENT=PATIENT NAME=FACILITY,PARENT=HOSPITAL
If you are writing to IMS/DB under CICS, use the IMS-DBCTL data source. If you are writing to IMS/DB under IMS/TM, use the IMS-DBDC data source. Change the allocation size of the IEFREDR data set, dependent on server usage. If the data set is used too often a DUMP results.
The process of defining an IMS/DB DLI data source consists of the following tasks:
Defining the IMS/DB DLI Data Source Connection Configuring the IMS/DB DLI Data Source Setting Up the Daemon Workspace
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine where you want to add your IMS/DB DLI data source. Expand the Bindings folder. Expand the binding where you want to add the IMS/DB DLI data source. Right-click the Data sources folder and select New data source. The New Data Source screen is displayed.
7. 8. 9.
Enter a name for the data source in the Name field. Select IMS-DLI from the Type list. Click Next. The Data source connect string screen is displayed. No connection information is required.
IMS/DB Data Sources 45-11
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the IMS/DB DLI data source and select Open. The Configuration Properties screen is displayed.
7.
Configure the data source parameters as required. For a description of the available parameters, see IMS/DB DLI Configuration Properties.
Either use the default NVIMSSRV workspace, supplied as part of the AIS installation, or, in a workspace that you define, set the server type to IMS and the startup script to NVIMSSRV.XY. The NVIMSSRV workspace has the same settings as the normal Navigator default workspace, except that it uses the IMS server.
Notes:
The suffix for the startup script enables instances of the server process for the workspace. Any suffix can be used, and Attunity Connect automatically extends the suffix for each instance. The remote machine specification in the binding setting for the IMS/DB data source on the client must include the workspace as part of the <remoteMachine> statement. The IMS server does not work with subtasks. Therefore, you must set the number of subtasks in the NsubTasks parameter to zero.
Defining the IMS/DB DBCTL Data Source Connection Configuring the IMS/DB DBCTL Data Source Accessing IMS/DB Data under CICS
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your IMS/DB DBCTL data source. Expand the Bindings folder. Expand the binding with the IMS/DB DBCTL data source. Right-click the Data sources folder and select New Data Source. The New Data Source screen is displayed.
7. 8. 9.
Enter a name for the data source in the Name field. Select IMS-DBCTL from the Type list. Click Next. The Data Source Connect String screen is displayed.
PSB Name: Specify the name of the PSB file that contains details of all the IMS/DB databases that you want to access. Target System: Specify the VTAM APPLID of the CICS target system. The default value is CICS. This parameter is used when updating VSAM data. You can determine this value by activating the CEMT transaction on the target CICS system. The legend APPLID=target_system appears in the bottom right corner of the screen. VTAM NetName: The VTAM netname of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system. For example, if you issue the following command to CEMT: CEMT INQ CONN On the display screen that the netname is BATCHCLI (this is the default connection supplied by IBM upon the installation of CICS). The default value is ATYCLIEN.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your IMS/DB DBCTL data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the IMS/DB DBCTL data source and select Open. The Configuration Properties screen is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the IMS/DB DBCTL Data Source Connection. Configure the data source parameters as required. For a description of the available parameters, see IMS/DB DBCTL Configuration Properties.
After assigning the ATYDBCTL program to a group, install it as follows: CEDA IN G(ATY
3.
Under CICS, run the CDBC transaction and select the first option (Connection). Provide the startup table suffix and DBCTL ID override value.
Defining the IMS/DB DBDC Data Source Connection Configuring the IMS/DB DBDC Data Source Accessing IMS/DB Data under IMS/TM
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your IMS/DB DBDC data source. Expand the Bindings folder. Expand the binding with the IMS/DB DBDC data source. Right-click the Data sources folder and select New Data Source. The New Data Source screen is displayed.
7. 8. 9.
Enter a name for the data source in the Name field. Select IMS-DBDC from the Type list. Click Next. The Data Source Connect String screen is displayed.
XCF Group: Specify the Cross System Coupling Facility collection of XCF members to which the connection belongs. A group may consist of up to eight characters, and may span between multiple systems. XCF server: Specify the Cross System Coupling Facility group member. TPipe prefix: Specify the transaction pipe prefix used to associate between the transaction and the transaction pipe it is using. The default value is ATTU. User name: Specify the security facility user identification (for example, the RACF user identification). Group name: Specify the security facility group identification (for example, the RACF group identification).
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your IMS/DB DBDC data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the data source and select Open. The Configuration Properties screen is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the IMS/DB DBDC Data Source Connection. Configure the data source parameters as required. For a description of the available parameters, see IMS/DB DBDC Configuration Properties.
Define a transaction to point to the program, using statements similar to the following:
APPLCTN PSB=ATYDBDC,SCHDTYP=PARALLEL TRANSACT CODE=ATYIMSTM,PRTY=(7,10,2),INQUIRY=NO,MODE=SNGL,EDIT=ULC The default transaction name is ATYIMSTM. If you use a different transaction, the transaction name must be less than or equal to eight characters and you must specify this value in the imsTransname data source property in the binding.
3.
Set up OTMA, as described in the Attunity Server Installation Guide for z/OS.
Segments are defined as tables within <table> elements. Tables inherit the key fields of their ancestors. Tables have indexes for their full hierarchical paths. Additional information is defined in dbCommand attributes specified within the <table> and <field> elements.
If COBOL copybooks describing the data source records are available, then you can import the metadata by running the metadata import in the Attunity Studio Design perspective, Metadata tab. If the metadata is provided in a number of COBOL copybooks with different filter settings (such as whether the first 6 columns are ignored or not), first import the metadata from copybooks with the same settings, and then import the metadata from the other copybooks. If COBOL copybooks do not exist that describe the IMS/DB records, then you must manually define the metadata. For more information, see Managing Data Source Metadata.
COBOL copybooks: These copybooks are copied to the machine running Attunity Studio as part of the import procedure. DBD files: These files are copied to the machine running Attunity Studio as part of the import procedure. PSB file: This file is copied to the machine running Attunity Studio as part of the import procedure. This step is optional.
Selecting the Input Files Applying Filters Selecting Tables Matching DBD to COBOL Import Manipulation Metadata Model Selection Import the Metadata
Open Attunity Studio. In the Design perspective, Configuration view, right-click the data source and select Show Metadata View. The Metadata tab is displayed with the data source displayed in the Metadata view.
3. 4. 5. 6. 7.
Right-click Imports under the data source and select New Import. Enter a name for the import. The name can contain letters, numbers and the underscore character. Select the import type. The is only one choice available depending on the type of IMS/DM data source you are using. Click Finish. The Metadata Import Wizard is displayed. Click Add in the Import Wizard to add DBD files. The Add Resource screen is displayed, providing the option of selecting files from the local machine or copying the files from another machine. Add Resource Screen shows the Add Resource screen.
8. 9.
If the files are on another machine, then right-click My FTP Sites and select Add. Set the FTP data connection by entering the server name where the DBD files reside and, if not using anonymous access, enter a valid username and password to access the machine. using the username as the high-level qualifier.
10. To browse and transfer files required to generate the metadata, access the machine
After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory.
11. Select the files to import and click Finish to start the transfer. 12. Repeat the procedure for COBOL copybooks.
The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns together with a COBOL copybook that ignores the first six columns. In this type of case, repeat the import process. You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks.
13. Click Add in the Import wizard to add a PSB file, if necessary.
The selected files are displayed in the Get Input Files screen, as shown in the figure below.
Figure 4510 Get Input Files Screen
Applying Filters
This section describes the steps required to apply filters on the COBOL Copybook files used to generate the Metadata. It continues the Selecting the Input Files step. Perform the following steps to apply filters.
1.
Figure 4511
2.
Apply filters to the copybooks, as needed. The following COBOL filters are available:
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type. Compiler source: The compiler vendor. Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Prefix nested column: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity metadata, is replaced with an underscore. Case sensitive: Specifies whether to consider case sensitivity or not. Find: Searches for the specified value. Replace with: Replaces the value specified for in the Find field with the value specified here.
Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Ignore labels: Ignore labels in the DBD files.
Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks.
3.
Selecting Tables
This section describes the steps required to select the tables from the COBOL Copybooks. The following procedure continues the Applying Filters procedure. Perform these steps to select the tables.
1.
From the Select Tables screen, select the tables that you want to access. To select all tables, click Select All. To clear all the selected tables, click Unselect All. The Select Tables screen is shown in the following figure:
The import manager identifies the names of the segments in the DBD files that will be imported as tables.
2.
Click Next (the Import Manipulation screen opens) to continue to the Matching DBD to COBOL step.
Figure 4513
1.
Match each table selected from the DBD file with the COBOL copybook that contains the relevant table structure. Select the files and tables from the dropdown lists for each DBD entry. Click Next (the Import Manipulation screen opens) to continue to the Import Manipulation step.
2.
Import Manipulation
This section describes the operations available for manipulating the imported records (tables). It continues the Selecting Tables procedure. The import manager identifies the names of the records in the DDM Declaration files that will be imported as tables. You can manipulate the general table data in the Import Manipulation Screen. Perform the following steps to manipulate the table metadata.
1.
From the Import Manipulation screen (see Import Manipulation Screen figure), right-click the table record marked with a validation error, and select the relevant operation. See the table, Table Manipulation Options for the available operations. Repeat step 1 for all table records marked with a validation error. You resolve the issues in the Import Manipulation Screen. Once all the validation error issues have been resolved, the Import Manipulation screen is displayed with no error indicators.
2.
3.
The upper area of the screen lists the DDM Declaration files and their validation status. The metadata source and location are also listed. The Validation tab at the lower area of the screen displays information about what needs to be resolved in order to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location). The following operations are available in the Import Manipulation screen:
Resolving table names, where tables with the same name are generated from different files during the import. Selecting the physical location for the data. Selecting table attributes. Manipulating the fields generated from the COBOL, as follows: Merging sequential fields into one (for simple fields). Resolving variants by either marking a selector field or specifying that only one case of the variant is relevant. Adding, deleting, hiding, or renaming fields. Changing a data type. Setting the field size and scale. Changing the order of the fields. Setting a field as nullable. Selecting a counter field for array for fields with dimensions (arrays). You can select the array counter field from a list of potential fields.
Setting column-wise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension. Creating arrays and setting the array dimension.
The following table lists and describes the available operations when you right-click a table entry:
Table 452 Option Fields Manipulation Table Manipulation Options Description Customizes the field definitions, using the Field Manipulation screen. You can also access this screen by double-clicking the required table record. Renames a table. This option is used especially when more than one table with the same name is generated from the COBOL. Sets the physical location of the data file for the table. Sets the table attributes. Specifies an XSL transformation or JDOM document that is used to transform the table definitions. Removes the table record.
Rename Set data location Set table attributes XSL manipulation Remove
You can manipulate the data in the table fields in the Field Manipulation Screen. Double-click a line in the Import Manipulation Screen to open the Field Manipulation Screen.
You can carry out all of the available tasks in this screen through the menu or toolbar. You can also right click anywhere in the screen and select any of the options available in the main menus from a shortcut menu. The following table describes the tasks that are done in this screen. If a toolbar button is available for a task, it is pictured in the table.
Table 453 Command General menu Undo Click to undo the last change made in the Field Manipulation screen. Field Manipulation Screen Commands Description
The offset of a field is usually calculated dynamically by the server at runtime according the offset and size of the proceeding column. Select this option to override this calculation and specify a fixed offset at design time. This can happen if there is a part of the buffer that you want to skip. When you select a fixed offset you pin the offset for that column. The indicated value is used at runtime for the column instead of a calculated value. Note that the offset of following columns that do not have a fixed offset are calculated from this fixed position.
Table 453 (Cont.) Field Manipulation Screen Commands Command Test import tables Description Select this table to create an SQL statement to test the import table. You can base the statement on the Full table or Selected columns. When you select this option, the following screen opens with an SQL statement based on the table or column entered at the bottom of the screen.
Data file name: Enter the name of the file that contains the data you want to query. Limit query results: Select this if you want to limit the results to a specified number of rows. Enter the amount of rows you want returned in the following field. 100 is the default value. Define Where Clause: Click Add to select a column to use in a Where clause. In the table below, you can add the operator, value and other information. Click on the columns to make the selections. To remove a Where Clause, select the row with the Where Clause you want t remove and then click Remove.
The resulting SQL statement with any Where Clauses that you added are displayed at the bottom of the screen. Click OK to send the query and test the table. Attribute menu Change data type Select Change data type from the Attribute menu to activate the Type column, or click on the Type column and select a new data type from the drop-down list.
Table 453 (Cont.) Field Manipulation Screen Commands Command Create array Description This command allows you to add an array dimension to the field. Select this command to open the Create Array screen.
Enter a number in the Array Dimension field and click OK to create the array for the column. Hide/Reveal field Select a row from the Field manipulation screen and select Hide field to hide the selected field from that row. If the field is hidden, you can select Reveal field. Select this to change or set a dimension for a field that has an array. Select Set dimension to open the Set Dimension screen. Edit the entry in the Array Dimension field and click OK to set the dimension for the selected array. Set field attribute Select a row to set or edit the attributes for the field in the row. Select Set field attribute to open the Field Attribute screen.
Set dimension
Click in the Value column for any of the properties listed and enter a new value or select a value from a drop-down list. Nullable/Not nullable Select Nullable to activate the Nullable column in the Field Manipulation screen. You can also click in the column. Select the check box to make the field Nullable. Clear the check box to make the field Not Nullable. Set scale Select this to activate the Scale column or click in the column and enter the number of places to display after the decimal point in a data type. Select this to activate the Size column or click in the column and enter the number of total number of characters for a data type.
Table 453 (Cont.) Field Manipulation Screen Commands Command Add Description Select this command or use the button to add a field to the table. If you select a row with a field (not a child of a field), you can add a child to that field. Select Add Field or Add Child to open the following screen:
Enter the name of the field or child, and click OK to add the field or child to the table. Delete field Select a row and then select Delete Field or click the Delete Field button to delete the field in the selected row.
Move up or down
Select a row and use the arrows to move it up or down in the list.
Select Rename field to make the Name field active. Change the name and then click outside of the field.
Select Columnwise Normalization to create new fields instead of the array field where the number of generated fields will be determined by the array dimension.
Table 453 (Cont.) Field Manipulation Screen Commands Command Combining sequential fields Description Select Combining sequential fields to combine two or more sequential fields into one simple field. The following dialog box opens:
First field name: Select the first field in the table to include in the combined field End field name: Select the last field to be included in the combined field. Make sure that the fields are sequential. Enter field name: Enter a name for the new combined field.
Flatten group
Select Flatten Group to flatten a field that is an array. This field must be defined as Group for its data type. When you flatten an array field, the entries in the array are spread into a new table, with each entry in its own field. The following screen provides options for flattening.
Select Recursive operation to repeat the flattening process on all levels. For example, if there are multiple child fields in this group, you can place the values for each field into the new table when you select this option. Select Use parent name as prefix to use the name of the parent field as a prefix when creating the new fields. For example, if the parent field is called Car Details and you have a child in the array called Color, when a new field is created in the flattening operation it will be called Car Details_Color.
Table 453 (Cont.) Field Manipulation Screen Commands Command Mark selector Description Select Mark selector to select the selector field for a variant. This is available only for variant data types. Select the Selector field form the following screen.
Select Replace variant to replace a variants selector field. Select Counter Field opens a screen where you select a field that is the counter for an array dimension.
Default values for all tables: Select this if you want to configure the same values for all the tables in the import. Make the following selections when using this option: Generate sequential view: Select this to map non-relational files to a single table. Generate virtual views: Select this to have individual tables created for each array in the non-relational file. Include row number column: Select one of the following: true: Select true, to include a column that specifies the row number in the virtual or sequential view. This is true for this table only, even in the the data source is not configured to include the row number column. false: Select false, to not include a column that specifies the row number in the virtual or sequential view for this table even if the data source is configured to include the row number column. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties. Inherit all parent columns: Select one of the following: true: Select true, for virtual views to include all the columns in the parent record. This is true for this table only, even in the data source is not configured to include all of the parent record columns. false: Select false, so virtual views do not include the columns in the parent record for this table even if the data source is configured to include all of the parent record columns. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties.
Specific virtual array view settings per table: Select this to set different values for each table in the import. This will override the data source default for that table. Make the selections in the table under this selection. See the item above for an explanation.
Figure 4516
Select Yes to transfer the matadata to the target computer immediately or No to transfer the metadata later. Click Finish.
46
Informix Data Source
This section describes the Attunity Informix data source driver. It includes the following topics:
Overview Functionality SQL Capability Configuration Properties Metadata Transaction Support Security Data Types Defining an Informix Data Source Testing the Informix Data Source
Overview
Attunity supports two Informix-type data sources, Informix 7.x and Informix 9.x. Both provide similar functionality and are bundled into two separate loadable libraries, which are introduced upon demand.
Functionality
The Informix database provides a wide range of common functionality that comply with the relational database model, as follows:
Supports common RDBMS capabilities including transaction management, logging, security, recovery, ordinary scalar data types, large data objects, locking, triggers, and stored procedures. Implements connectivity to an Informix database instance by means of embedded SQL techniques, through which it interacts with the database server, database access, and data manipulation. Serves as a mediating layer between a consumer of database resources within Attunity AIS and an Informix database instance. Complies with appropriate database application design outlines (as a database process).
As a run-time component, it is subjected to the deployment considerations that involves the available machines, I/O devices characteristics, network throughput and traffic.
The connection to Informix data source, is implemented by an Informix client. If you need a direct connection from this machine, then the Informix client must be installed locally. Otherwise, a connection to Informix data sources can be defined using remote computers, where the Informix client is already installed.
SQL Capability
Attunity Connect SQL syntax and semantics are enhanced with extended functionality and post-relational capabilities. It delegates supported SQL to the Informix RDBMS engine for processing, assuming standard SQL is supported. Extended capabilities and/or unsupported functionality are processed internally by Attunity Connect. The following table lists and describes the Informix RDBMS SQL elements supported by Attunity Connect:
Table 461 Supported Informix SQL Elements Description DB does not support DISTINCT keyword in AGG HAVING expressions. Supports GROUP BY <num> syntax, when num refers to expression. Does not support expression in INSERT: insert into values (10+10). LOJ is not supported. IDs from right LOJ side table cant participate in a filter expression. Only one table can be from right side of LOJ (A LOJ B). DB does not support LOJ in father and subquery. For LOJ that does not support the ON clause (ORACLE: =(+)). DB supports distributed transactions. DB supports read uncommitted transactions.
Symbolic Property Notation nvDB_NO_DISTINCT_HAVING nvDB_GROUP_EXPR_BY_NUM nvDB_NO_EXPR_IN_INSERT ~nvDB_NO_LOJ_SUPPORT nvDB_NO_LOJ_ID_IN_FILTER nvDB_RS_LOJ_ONLY nvDB_NO_NESTED_LOJ nvDB_NO_LOJ_ON_CONDITION nvDB_SUPPORT_2PHASE_COMMIT nvDB_SET_SUPP_READ_ UNCOMMITETED
nvDB_SET_SUPP_REPEATABLE_READ DB supports repeatable read transactions. nvDB_SET_SUPP_SERIALIZABLE nvDB_USE_QUOTED_OWNER DB supports serializable transactions. Quotes the owner name when creating table name in SQL.
Table 461 (Cont.) Supported Informix SQL Elements Symbolic Property Notation nvDB_USE_COL_PREFIX_IN_UPD_ nvDB_SUPPORTS_UNION_ nvDB_SUPPORTS_UNION_ALL_ nvDB_ORDER_BY_NUM_IN_UNION_ nvDB_SUPPORTS_FOR_UPDATE_ nvDB_SUPPORTS_UPDATE_OF_ nvDB_NO _ORDER_FOR_UPDATE_ nvDB_ONE_TAB_FOR_UPDATE_ Description Prefixes each column in UPDATE/DELETE statements with the full table name. DB supports UNION. DB supports UNION ALL. Supports only ORDER BY <num> syntax in a UNION SQL, when num is a column number. DB supports FOR UPDATE. DB supports FOR UPDATE OF. Does not support FOR UPDATE with SELECT statement that includes ORDER BY. DB does not support FOR UPDATE with statement select data from more than one table.
The following table lists the Informix data type textual representation, as expressed in its SQL:
Table 462 Data Type DT_B_ DT_Q_ DT_F_ DT_OPAQUE_ DT_IMAGE_ DT_ODBC_DATE_ DT_ODBC_TIME_ DT_ODBC_TIMESTAMP_ Informix Data Types and Textual Representation Informix SQL Textual Representation SMALLINT INT DOUBLE PRECISION BYTE Not Supported. DATETIME YEAR TO SECOND Not Supported. Not Supported.
The following table lists the main Informix SQL functionalities and their symbolic syntax:
Table 463 Informix SQL Functions and Symbolic Syntax Symbolic Syntax Not Supported Not Supported Not Supported TRIM(LEADING " " FROM ~) TRIM(TRAILING " " FROM ~) Not Supported Not Supported MOD(~,~) Not Supported
Functional Notation YACC_POSITION_ YACC_SUBSTR2_ YACC_SUBSTR3_ YACC_LTRIM_ YACC_RTRIM_ YACC_LOWER_ YACC_UPPER_ YACC_MOD_ YACC_NVL_
Table 463 (Cont.) Informix SQL Functions and Symbolic Syntax Functional Notation YACC_COS_ YACC_SIN_ YACC_TAN_ YACC_ACOS_ YACC_ASIN_ YACC_ATAN_ YACC_LOG10_ YACC_LN_ YACC_EXP_ YACC_POWER_ YACC_ROUND_ YACC_TRUNC_ YACC_FLOOR_ YACC_DATE_CONST_ YACC_TIMESTAMP_ CONST_ YACC_CURRENT_DATE_ YACCCURRENT_TIME_ STAMP_ YACC_DAYOFWEEK_ Symbolic Syntax COS(~) SIN(~) COS(~) ACOS(~) ASIN(~) ATAN(~) LOG10(~) LOGN(~) EXP(~) POW(~,~) ROUND(~,~) TRUNC(~,~) TRUNC(~,0) DATE("1/2/0") DATETIME(~-~-~ ~:~:~.~) YEAR TO FRACTION") TODAY CURRENT YEAR TO SECOND (WEEKDAY(~) +1)
Stored Procedures
Attunity Informix data source driver supports Informix stored procedures. To retrieve output parameters and the return code from the stored procedure, the ?=CALL syntax should be used. In addition, the Attunity Informix data source driver is capable of handling a row set as output.
Limitations
The following are known restrictions when using Informix stored procedures:
The LIKE keyword, which is supported by Informix SQL syntax, cannot be used when defining parameters. Thus, procedures that include the LIKE keyword in the parameter definitions, are not supported and errors can be anticipated. For example, the following stored procedure returns an error because the LIKE keyword is used:
CREATE PROCEDURE "inf92".nation_sp1( n_nkeyp like "inf92".nation.n_nationkey ) RETURNING int; define n_nkey int; foreach SELECT n_nationkey INTO n_nkey FROM "inf92".nation WHERE n_nationkey>n_nkeyp return n_key with resume; end foreach; END PROCEDURE;
Informix Stored Procedure Language (SPL) enforces certain limitations on SQL statements applicable within the stored procedure itself. For details, check with your specific Informix vendor. Informix identifier length is limited to 18 characters (inclusive). Therefore, procedure names must be less than or equal to 18 characters long.
Informix CLOB/BLOBs
The Informix driver provides support for the built-in, predefined opaque data types CLOB/BLOB. This is implemented by relying on the CLOCATORTYPE type, associated with a DESCRIBE-d data type at the ESQL/C programming interface.
Configuration Properties
The following properties can be configured for the Adabas data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect: Set to true to enable explicit selection. isolationLevel: The isolation level to be applied on an Informix transaction.
Metadata
Informix metadata definitions resides at a dedicated system table which is accessed by the Attunity Informix data source driver, using standard SQL queries. Informixsystables holds information regarding tables and sysprocedures holds information regarding procedures. Similarly, sysindexes holds information regarding table indexes. The following example is a typical metadata query issued by the driver for table listing:
select tabname, owner, tabtype from informix.systables where tabid>=100 and
Specific table descriptions or record details such as fields, types, etc. are sampled by querying the table and using a DESCRIBE statement, by ESQL/C standard techniques, as listed in the following example:
set $sql_str to "SELECT * FROM MYtable" $ PREPARE record_query FROM $sql_str; $ DESCRIBE record_query INTO rec_sqlda;
Statistics
Attunity Informix data source driver collects available statistics held in an Informix database instance. Statistics are used for developing and evaluating execution strategies at the query optimization stages. Statistics elements of interest can be the number of rows in a table, the number of blocks occupied, index properties, structural information, etc. The following query provides an example to the way by which statistics are retrieved:
select t.nrows, t.npused from informix.systables t where t.tabname = ? and t.owner = ?;
Owner Support
The Informix database, each table, view, index, procedure and synonym are owned by a specific owners. Database objects ownership is a key issue in maintaining privacy and privileges management. Usually, the owner of a database object is the person who created it, yet users with DBA privilege can create objects to be owned by others. The Attunity Informix data source driver assumes ownerships on an "AS IS" basis. It recognizes OWNER as an acceptable syntactical token wherever the underlying SQL syntax allows it. It accepts the ownership semantics, as implemented by the Informix RDBMS.
Transaction Support
Attunity Informix data source driver for Informix version 7.x supports the one-phase commit transaction protocol. The driver for Informix version 9.x supports the two-phase commit transactions and can fully participate in a distributed transaction. Transaction logging must be enabled in the Informix database or transactions are not supported by the driver (which is always in auto-commit mode). You use Informix with its two-phase commit capability through an XA connection.The daemon server mode must be configured to single-client mode. To use distributed transactions with Informix, use DBAccess to change the locking level of tables to row level locking. In addition, from an ODBC-based application, ensure that AUTOCOMMIT is set to 0. An Informix client on a PC cannot use MTS as the transaction manager.
Locking Levels
Informix database supports a multi-user database environment by utilizing a locking mechanism for managing a consistent and concurrent access to data. The Informix
database management system provides run-time and design-time syntax for controlling the locking level. Attunity Informix data source driver has no explicit control over the locking policy. It functions under the existing database settings. The locking mechanism includes four locking levels which are applicable on data items, as follows:
Page: A page is a physical amount of data that Informix works with at any one time. Under this locking mode, a page is locked. Row: A row is a logical record. Under this locking mode, the logical record is being locked as an atomic unit. Table: Under this locking mode, a table as a whole, is being locked as a complete unit. Database: Under this locking mode, the entire database is locked.
Isolation Levels
The Attunity Informix data source driver supports the following isolation levels, where each is controlled by an appropriate configuration setting. The isolation level is used only within a transaction. The terminology used within each configuration setting is based on common descriptive keywords, used by Attunity Connect. The following table summarizes the isolation level semantics applied by the Attunity Informix data source driver:
Table 464 Isolation Level Semantics Informix Transaction Isolation Level "Dirty Read" Comments Provides no isolation from locks. All locks are ignored by the header. The reader process can view data freely, regardless of locks applied by others. The default setting. Ensures that the reader only returns values that are committed to the database. Incompatible locks held by others causes the reader to wait or fail. Ensures that while stepping along a cursor, the current row is not changed by others. This is achieved by placing a shared lock on the current row, which prevents others from placing a "modifying" exclusive lock on that row. This shared lock is released as the cursor moves to the next row. Ensures that once a cursor has been read, all consecutive reads will pass back the same values. This is implemented by applying a similar locking policy to "Cursor Stability", excluding the locks releases.
readCommitted
"Committed Read"
repeatableRead
"Cursor Stability"
serializable
"Repeatable Read"
Security
Attunity Informix data source driver is not actively involved in applying or enforcing any security policy. It complies with the security policy and rules as set in the Informix database instance with which it interacts.
Data Types
This section lists the Informix data types and how Attunity maps these data types to OLE DB and ODBC data types. The following table lists Informix data types and how they are mapped to Attunity data types:
Table 465 Informix BYTE CHAR DATE DATETIME DECIMAL FLOAT INTEGER INTERVAL MONEY NCHAR NVARCHAR SERIAL SMALLFLOAT SMALLINT TEXT VARCHAR Informix Data Types AIS DT_TYPE_OPAQUE_ DT_TYPE_T_ DT_TYPE_INF_DATE_ DT_TYPE_INF_DATETIME_ DT_TYPE_INF_DECIMAL_ DT_TYPE_G_ DT_TYPE_L_ DT_TYPE_CSTRING_ DT_TYPE_INF_MONEY_ Not Supported Not Supported DT_TYPE_L_ DT_TYPE_F_ DT_TYPE_W_ DT_TYPE_T_ DT_TYPE_CSTRING Comments BLOB property is set. Character-coded text; a single character or a string. Informix date type implementation. Informix date-time implementation. Informix decimal type implementation. G_floating; 64-bit double-precision floating point. Long word integer; 32-bit signed 2s-complement integer. A null terminated string. Informix money type implementation. Long word integer; 32-bit signed 2s-complement integer. F_floating; 32-bit signed 2s-complement integer. Word integer; 16-bit 2s complement integer. BLOB property is set. A null terminated string.
The following table shows how Attunity Connect maps Informix data types to ODBC and OLE DB data types.
Table 466 Informix BYTE Char(m<256), Character(m<256) Informix Data Types Mapping to OLE DB and ODBC OLE DB DBTYPE_BYTES DBTYPE_STR ODBC SQL_LONGVARBINARY SQL_CHAR
Table 466 (Cont.) Informix Data Types Mapping to OLE DB and ODBC Informix Char(m>255), Character(m>2566) Date Datetime Dec, Decimal Double Float Int, Integer Interval Money Nchar (not supported) Numeric Nvarchar (not supported) Precision Real Serial Smallfloat Smallint Text Varchar(m<256) Varchar(m>256)
1 2 3
OLE DB DBTYPE_STR DBTYPE_DBTIMESTAMP DBTYPE_DBTIMESTAMP DBTYPE_NUMERIC DBTYPE_R8 DBTYPE_R8 DBTYPE_I4 DBTYPE_STR DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_R8 DBTYPE_R8 DBTYPE_I4 DBTYPE_R4 DBTYPE_I2 DBTYPE_STR DBTYPE_STR DBTYPE_STR
2
ODBC SQL_LONGVARCHAR 1 SQL_TIMESTAMP SQL_TIMESTAMP SQL_NUMERIC SQL_DOUBLE SQL_DOUBLE SQL_INTEGER SQL_CHAR SQL_NUMERIC SQL_NUMERIC SQL_DOUBLE SQL_REAL SQL_INTEGER SQL_REAL SQL_SMALLINT SQL_LONGVARCHAR SQL_CHAR SQL_LONGVARCHAR 3
IS_LONG attribute is TRUE IS_LONG attribute is TRUE Precision of 2147483647. If the <odbc longVarCharLenAsBlob> parameter is set to true in the Server environment settings, then precision of m.
Defining the Informix Data Source Connection Configuring the Informix Data Source Properties
3. 4. 5. 6.
Expand the machine where you want to add your Informix data source. Expand the Bindings folder. Expand the binding where you want to add the Informix data source. Right-click the Data Source folder and select New Data Source. The New Data Source screen is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select Informix from the Type list: Click Next. The Data Source Connect String page is displayed.
10. Enter the connect string according to the data source type selected:
If you are defining an Adabas ADD data source, enter the Database number. If you are defining an Adabas Predict data source, enter the following: Database name: Enter the Informix database instance identification.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Adabas data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the Adabas data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Informix Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
Connection test: This tests the physical connection to the data source. Query test: This test runs an SQL SELECT query against the data source.
These test are described in the following sections: To test the connection to the Informix data source 1. Open Attunity Studio.
2. 3. 4. 5. 6.
In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your Informix data source. Expand the binding with the Informix data source. Expand the Data sources folder. Right-click the required Informix data source, and select Test. The Test Wizard screen opens.
7.
Select Navigator from the Active Workspace Name list, and click Next. The system now tests the connection to the data source, and returns the test result status.
8.
In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your Informix data source. Expand the binding with the Informix data source. Expand the Data sources folder. Right-click the required Informix data source, and select Query Tool. The Select Workspace screen opens.
7.
Select Navigator and click OK. The Query Tool opens in the Editor pane, with the Build Query tab displayed (see step 10.).
8. 9.
Select the required query type from the Query Type list. The default is a SELECT-type query. Locate and expand the your Informix data source. The Informix data source tables are listed.
10. Drag the required table to the Table column, as shown in the following figure:
The Query Result tab opens, displaying the results of the query.
12. Close the Query Tool in the Editor pane.
<<<<<<<<<<<<<<<<<<<
Accessing Database 'informix' with SQL: SELECT T0000.n_nationkey AS c000, T0000.n_name AS c001, T0000.n_regionkey AS c002, T0000.n_comment AS c003 FROM 'inf9'.nation T0000
>>>>>>>>>>>>>>>>>>>> Execution Strategy End >>>>>>>>>>>>>>>>>>>>>>>>>>>> nvOUT (./qpsqlcsh.c 140): ---------------------------> Using Cached QSpec SELECT T0000.n_nationkey AS c000, T0000.n_name AS c001, T0000.n_regionkey AS c002, T0000.n_comment AS c003 FROM 'inf9'.nation T0000
nvRETURN (./drviunwn.c 804): -1210 (Last message occurred 2 times) Disabled FilePool Cleanup(DB=___sys, FilePool Size=0) FilePool Shutdown(DB=___SYS, FilePool Size=0) Closing log file at SAT DEC 3 13:39:12 2005
47
Ingres II (Open Ingres) Data Source
This section contains the following topics:
Supported Versions and Platforms Functionality Configuration Properties Transaction Support Data Types Platform-Specific Information Defining the Ingres II Data Source
Functionality
This section describes the following aspects of Ingres II functionality.
Stored Procedures
The Ingres II Data Source supports Ingres II Stored Procedures. To retrieve output parameters and the return code from the stored procedure, use the ? = CALL syntax, described in the CALL Statement.
Dynamic isolation Read uncommitted Read committed Repeatable read Serializable read
Ingres II (Open Ingres) Data Source 47-1
Ingres II supports page level locking. Updates are performed with the no wait flag. If one of the records is locked, then the update operation fails. This value cannot be changed. Once a record is locked, all other update operations fail. In accordance with ANSI standards, if the user or application specifies the read-uncommitted isolation level, by default Ingres II grants read-only access. If the user or application specifies a different isolation level, by default Ingres grants read-write permission.
Update Semantics
For tables with no bookmark or other unique index, the data source returns a combination of most (or all) of the columns of the row as a bookmark. The data source does not guarantee the uniqueness of this bookmark; you must ensure that the combination of columns is unique.
BLOBs
The Ingres II data source data source driver provides support for the built-in predefined opaque data types known as Segmented String/List Of Byte Varying. Both READ and WRITE operations are supported. BLOBs are addressed as ordinary fields. They are handled by dedicated cursors that step along their data. For handling a BLOB field, successfully the table must have a genuine unique key defined.
Passthru Queries
SQL capabilities, as implemented internally by AIS, are equipped with means for delegating SQL statements as-is to the backend engine. When using this technique, known as Passthru, SQL statements are passed as a whole and processed directly by the database engine, much like the ordinary interactive SQLplus utility would process them. Passthru processing is especially advantageous in cases where one attempts gain explicit control on the processed statement and facilitate proprietary features. For example, introducing refined specific nuances of a CREATE INDEX statement can be carried out using this technique. The following example demonstrates how one can create an index with explicit control on specified attributes, with Passthru Using NAV_UTIL Utility.
NV_EMPLOY is defined as follows: NavSQL > desc nv_employ; Connecting .... ----------------------------------------------------------------Table NV_EMPLOY There are 5 fields in the table: # Name Datatype Size Width Scl Nullable ----------------------------------------------------------------------- 0 EMPLOYEE_ID string 5 5 0 no 1 LAST_NAME string 14 14 0 yes 2 CITY string 20 20 0 yes 3 ROWID string 18 18 0 yes (2 indexes specified) Index 1: length is 5, Unique name is NV_EMPLOY_ID segments are: EMPLOYEE_ID Index 2: length is 18, Unique, Hashed
name is ROWID segments are: ROWID <END OF TABLE DESCRIPTION> NavSQL >
Assume that last_name is a common key of reference which warrants an index. Nevertheless, for the sake of usability, one attempts to have a case blind index to ease formulating and processing queries where case sensitivity is of no importance. The Ingres II data source provides the following syntax for doing this:
CREATE INDEX lname_case_blind ON NV_EMPLOY(UPPER(LAST_NAME));
This syntax would take the following format when Using NAV_UTIL Utility:
NavSQL > text = {{CREATE INDEX lname_case_blind ON NV_EMPLOY(UPPER(LAST_NAME))}}; Executing: text = {{CREATE INDEX lname_case_blind ON NV_EMPLOY(UPPER(LAST_NAME))}} OK 0 rows affected
This index would typically improve delegated queries like the following:
SELECT * FROM NV_EMPLOY WHERE UPPER(LAST_NAME) = 'SMITH'; NavSQL > select * from nv_employ; EMPLOYEE_ID LAST_NAME CITY 00164 Toliver Chocorua 00165 Smith Chocorua 00166 Dietrich Boscawen 00167 Kilpatrick Marlow 00168 Nash Meadows 00169 Gray Etna 00170 Wood Jefferson 7 rows returned NavSQL > SELECT * FROM NV_EMPLOY WHERE UPPER(LAST_NAME) = 'SMITH'; EMPLOYEE_ID LAST_NAME CITY 00165 Smith Chocorua 1 rows returned NavSQL >
Recall that the SQL statement is passed through on an as-is basis, with no interpretation and/or any other intervention of any kind. Consequently - it should be phrased according to the lexical notations and syntax rules that comply with those expected by the backend Ingres II SQL engine.
Configuration Properties
The following properties can be configured for the Adabas data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
isolationLevel: Specifies the default isolation level for the Data Source, as follows:
dynamicIsolation: The isolation level is not set at the data source level. Setting this parameter to true allows the application to set this parameter dynamically as needed. readUncommitted: Specifies that corrupt data is not to be read. This is the lowest isolation level. readCommitted: Specifies that only the data committed before the query began is displayed. repeatableRead: Specifies that data used in a query is locked and cannot be used by another query nor updated by another Transaction. serializable: Specifies that the data is isolated serially. Treats data as if transactions are executed sequentially.
Note:
If the specified level is not supported by the data source, then Attunity Connect defaults to the next highest level.
lockWait: Specifies how many seconds a transaction waits before timing out when it encounters a locked row, as follows: -1: Sets the transaction to wait indefinitely (the default). 0: Sets the transaction to wait the minimum amount of time possible. n(>0): Specifies how many seconds the transaction waits.
openIngresConnect: Specifies the name of the virtual node used by the Ingres client to access a remote networked Ingres II server and the name of the database with the format vnode::database_name: Enables you to specify a logical name (environment variable in UNIX) instead of the database name if the logical database is distributed among several physical databases. The Ingres data source translates the logical name before binding. For example, a logical name (ALL_ SITES) can be defined to use as the Database name for a logical database distributed among two physical databases (BOSTON_DB and PARIS_DB), as follows:
For OpenVMS DCL,define ALL_SITES BOSTON_DB,PARIS_DB For UNIX C-shell, define setenv ALL_SITES BOSTON_DB,PARIS_ DB
readLockMode: Specifies the lock mode as either read only or writable. timezone: Sets the time (in hours) on the client to be the same as the time on the server, when the two times are different. For example, if the client time is 13:00 and the server time is 9:00, set <Properties timezone=4 />. A negative number sets the number of hours ahead of the client.
Transaction Support
The Ingres II data source supports Two-phase Commit and can fully participate in a distributed Transaction when the transaction environment property convertAllToDistributed is set to true.
You use Ingres II with its two-phase commit capability through an XA connection.The daemon server mode must be configured to Single Client mode (see Server Mode). To use distributed transactions with Ingres II from an ODBC-based application, ensure that AUTOCOMMIT is set to 0.
Data Types
The following table shows how Attunity Connect maps Ingres II data types to OLE DB and ODBC data types:
Table 471 Ingres Byte Char (m<256), C Char (m>255), C Date Float, Float8 Float4 Integer, Integer4 Integer1 Integer2 Money Ingres II Data Types OLE DB DBTYPE_BYTES DBTYPE_STR DBTYPE_STR DBTYPE_DBTIMESTAMP DBTYPE_R8 DBTYPE_R4 DBTYPE_I4 DBTYPE_I1 DBTYPE_I2 DBTYPE_R8 ODBC SQL_LONGVARBINARY SQL_CHAR SQL_LONGVARCHAR 1 SQL_TIMESTAMP SQL_DOUBLE SQL_REAL SQL_INTEGER SQL_TINYINT SQL_SMALLINT SQL_DOUBLE
Long Byte (not supported) Long Varchar (not supported) SmallInt Text Varchar (m<256) Varchar (m>255) DBTYPE_I2 DBTYPE_STR DBTYPE_STR DBTYPE_STR SQL_SMALLINT SQL_VARCHAR SQL_CHAR SQL_LONGVARCHAR1
Note: Precision of 2147483647. If the <odbc longVarcharLenAsBlob> parameter is set to true in the AIS environment settings, then precision of m.
This table shows how Attunity Connect maps data types in a CREATE TABLE statement to Ingres II data types.
Table 472 CREATE TABLE Data Types Ingres Byte Char[(m)] Date Float Real
Table 472 (Cont.) CREATE TABLE Data Types CREATE TABLE Image Integer Numeric [(p[,s])] Smallint Text Time Timestamp Tinyint Varchar(m) Ingres Long Byte Integer Float Smallint Long Varchar Date Date Integer1 Varchar(m)
Platform-Specific Information
Checking Ingres Environment Variables on UNIX
Check that the II_SYSTEM environment variable is correctly set and that the Ingres database is readable by Attunity Connect. For example, set the following in the nav_ login or site_nav_login file on a UNIX machine: Make sure that the Ingres user has enough privileges or the data source returns the following error: II_SS01007_PRIV_NOT_GRANTED. Use the Ingres accessDB utility to add or modify users so that they have the correct privileges.
setenv II_SYSTEM /ingsw setenv PATH $II_SYSTEM/ingres/utility:$II_SYSTEM/ingres/bin:$PATH setenv PATH usr/openwin/bin:$PATH setenv LD_LIBRARY_PATH $II_SYSTEM/ingres/lib:$LD_LIBRARY_PATH
Defining the Ingres II Data Source Connection Configuring the Ingres II Data Source Properties
In the Design Perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your Ingres data source.
4. 5. 6.
Expand the Bindings folder. Expand the binding where you want to add the Ingres data source. Right-click the Data Source folder and select New Data Source. The New Data Source screen is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select Ingres from the Type list. Click Next. The Data Source Connect String screen is displayed.
10. Enter a connect string in the Connect string field. The connect string should
vnode: Specify the name of the virtual node which is used by the Ingres II client to access a remote networked Ingres II server. You can retrieve a list if the available nodes on the machine by running the Ingres net_util utility. If you specify only database name, omitting vnode name, then the data source binds to the specified local database. database_name: Specify the name of the database. You can specify a logical name (environment variable in UNIX) instead of the database name if the logical database is distributed among several physical databases. The Ingres data source translates the logical name before binding. For example, a logical name (ALL_SITES) can be defined to use as the Database name for a logical database distributed among two physical databases (BOSTON_DB and PARIS_DB), as follows: OpenVMS DCL define ALL_SITES BOSTON_DB,PARIS_DB UNIX C-shell setenv ALL_SITES BOSTON_DB,PARIS_DB If you want to connect to a particular Ingres class-server instance that is already defined, specify the following in the Database name field: database/Ingres_instance
Note:
To access Ingres II on 64-bit operating systems (HP-UX 11 and higher, AIX 4.4 and higher and Sun Solaris 2.8 and higher), the data source 32-bit client must be used.
2. 3. 4. 5. 6.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Ingres data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the Ingres data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Ingres II Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties. After setting the binding, you must define Attunity Metadata describing the Ingres data.
48
ODBC Data Source
This chapter contains the following sections:
Overview Functionality SQL Capabilities Configuration Properties Metadata Transaction Support Security Data Types Platform-Specific Information Defining the ODBC Data Source Testing the ODBC Data Source
Overview
The ODBC Data Source provides a wide range of common standard relational functions that comply with the Relational Data Source model. The ODBC Data Source is a generic Driver to data providers that have an SQL processing capability and expose the ODBC API. Some capabilities are actively implemented as data source driver functions while others are implied by the methods and techniques the data source driver uses for interacting with the ODBC Backend Database.
Supported Features
The ODBC data source driver supports the core of the following common traditional relational capabilities:
Data manipulation (DML) Data definition (DDL) Transaction management Logging Security Recovery Ordinary scalar data types Large data objects Locking Stored procedures
Functionality
This section describes the following aspects of ODBC functionality:
Stored Procedures
The ODBC data source supports Stored Procedures. You can use a SELECT statement only for a procedure having only a single SELECT statement. To retrieve output parameters, multiple result sets, and the return code from a stored procedure, use the? = CALL syntax as described in the CALL Statement.
Isolation Levels
The ODBC data source supports the following Isolation Levels:
If the back-end data source does not support an isolation level, the data source supports the isolation levels that are supported by the back-end data source. The isolation level is used only within a transaction.
SQL Capabilities
The ODBC data source conforms to ANSI92 SQL. This standard includes both the SQL syntax and semantics. AIS uses its own extended SQL (see Attunity SQL Syntax), endowed with advanced capabilities. In most cases, AIS will attempt to delegate SQL portions to the ODBC back end engine for the processing of those SQL features which are supported there.
Extended and/or unsupported functions are processed internally by AIS. This notion is a part of Attunity Query Processor and Query Optimizer core. Because the ODBC data source is a generic driver, it assumes only the following minimal set of supported SQL elements about the back end:
Basic SQL operators. Any expressions allowed in GROUP BY clauses. When creating table name in, owner name is also quoted.
Configuration Properties
The following parameters can be configured for the ODBC Data Source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect: Exposes explicit-select fields. The default setting is false. disableExtendedFetch=true|false: Specifies whether or not extended fetch is used by the driver, regardless of whether extended fetch is supported by the Backend Database. ignoreSqlState: A string property that can include a concatenation of SQLStates to ignore. Since this data source driver is ODBC generic, some providers behave differently than others so that you may want to ignore certain SQLStates with one provider and other with another. For example: ignoreSqlState=S1104
isolationLevel: The default isolation level for the data source, as follows: dynamicIsolation: Specifies that he isolation level is not set at the data source level. Setting this parameter to true allows the application to set this parameter dynamically as needed. readUncommitted: When selected corrupt data is not read. This is the lowest isolation level. readCommitted:When selected, only the data committed before the query began is displayed. repeatableRead: When selected, data used in a query is locked and cannot be used by another query nor updated by another transaction. serializable: When selected, the data is isolated serially. Treats data as if transactions are executed sequentially.
Note:
If the specified level is not supported by the data source, then AIS defaults to the next highest level.
notSupportSqlColumns: Specifies whether the driver uses the SQLColumns ODBC API. The default value is false. optTrace: When set to true, this boolean field activates the tracing by the ODBC provider.
Metadata
The ODBC data source uses the standard ODBC API to get metadata information from the back end database.
Statistics
The ODBC data source gathers available statistics held inside the database instance by using the SQLStatistics ODBC API. This information is used later by the run time components for developing, evaluating and choosing execution strategies at query optimization phases.
Transaction Support
The ODBC data source supports one-phase commit if Transactions are supported in the Backend Database. It can participate in a distributed transaction if it is the only one-phase commit Data Source being updated in the transaction.
Note:
When the ODBC data source participates in a distributed transaction, the transaction environment properties convertAllToDistributed and useCommitConfirmTable must be set to true.
Security
The ODBC data source driver is not actively involved in applying or enforcing a security policy. It incorporates the security policy and rules as set at the database instance with which it interacts. User name and password are passed to the provider when SQLConnect is called. See Managing a User Profile in Attunity Studio for more information.
Data Types
The following table shows how ODBC data types are mapped to OLE DB data types.
Table 481 ODBC SQL_BINARY SQL_BIT SQL_CHAR SQL_DATE SQL_DOUBLE SQL_FLOAT SQL_INTEGER SQL_LONGVARBINARY Mapping ODBC Data Types OLE DB DBTYPE_BYTES DBTYPE_I1 DBTYPE_STR DBTYPE_DBDATE DBTYPE_R8 DBTYPE_R8 DBTYPE_I4 DBTYPE_BYTES
Table 481 (Cont.) Mapping ODBC Data Types ODBC SQL_LONGVARCHAR SQL_NCHAR SQL_NTEXT SQL_NVARCHAR SQL_NUMERIC SQL_REAL SQL_SMALLINT SQL_TIME SQL_TIMESTAMP SQL_TINYINT SQL_VARBINARY SQL_VARCHAR OLE DB DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_R4 DBTYPE_I2 DBTYPE_DBTIME DBTYPE_DBTIMESTAMP DBTYPE_I1 DBTYPE_BYTES DBTYPE_STR
The following table shows how data types in a CREATE TABLE statement are mapped to ODBC data types.
Table 482 CREATE TABLE Data Types ODBC SQL_CHAR[(m)] SQL_DATE SQL_DOUBLE SQL_DOUBLE SQL_LONGVARBINARY SQL_INTEGER SQL_NUMERIC SQL_DOUBLE SQL_DECIMAL SQL_SMALLINT SQL_LONGVARCHAR SQL_TIME SQL_TIMESTAMP SQL_TINYINT SQL_VARCHAR(m)
CREATE TABLE Char[(m)] Date Double Float Image Integer Numeric Numeric(p,s) Numeric(p[,s]) Smallint Text Time Timestamp Tinyint Varchar(m)
Platform-Specific Information
When running a Microsoft Jet driver with the ODBC data source, to access BLOBs stored in an MS Access database, use Attunity Studio to set odbc fixAccessBug=true in the environment properties. To insert a BLOB into a table, the table must have a primary key. When running a Microsoft Jet driver with the ODBC data source, to access an Microsoft Access database, the application might unexpectedly lock. In this case, use Attunity Studio to set queryProcessor noThreads=true in the environment properties (the application will run slower than it does if this parameter is not set).
Defining the ODBC Data Source Connection on a Windows Platform orDefining the ODBC Data Source Connection on a non-Windows Platform Configuring the ODBC Data Source
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your ODBC data source. Expand the Bindings folder. Expand the binding where you want to add the ODBC data source. Right-click the Data Source folder and select New Data Source. The New Data Source screen is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select ODBC from the Type list. Click Next. The Data Source Connect String wizard is displayed.
10. Enter a connect string in the ODBC Connect String field. The connect string
should have the following information. ODBC Connect String: Specify the User, System, or File DSN that previously defined using the Microsoft ODBC Driver Manager. For a User or System DSN, specify the name of the DSN. For a File DSN, specify the following: filedsn=dsn where dsn is the name of the File DSN.
If you are connecting to the data source through the driver for that data source, precede the DSN by the name of the driver as it appears in the Registry, followed by a semi-colon (;).
Note:
Make sure that you specify the name exactly as it appears in the Registry (since the Registry is case sensitive).
where:
name: Specifies the unique identifier for the ODBC data source. This value is used as the type attribute for a data source defined in the <datasource> section of the binding when you identify a data source to be accessed by this custom ODBC. Therefore, the name of an ODBC data source must be unique. odbc_backend: Specifies the full path and name of the ODBC back end sharable on the non-Windows platform.
2.
Use the NAV_UTIL ADDON to register the ODBC data source definition to Attunity Connect: nav_util addon define_file where define_file is the input text file containing the ODBC data source specification. Unless you specify a full path, NAV_UTIL searches for the file in the current working directory. For z/OS systems, run the following command: NAVROOT.USERLIB(NAVCMD) and enter ADDON define_file at the prompt (where NAVROOT is the high-level qualifier specified during installation of AIS Server). For OS/400 platforms, run the following command: define_file NAV_UTIL ADDON is used when developing using the developer SDK (to define a custom data type, data source or application adapter). For details, see Attunity Developer SDK.
3.
Specify a binding entry similar to the following: <datasource name=PERSONNEL type=datasource_type connect="odbc_connect" syntaxName="ODBC" />
where:
datasource_type: The section name specified in the define_file file odbc_connect: The connect string for the ODBC back end data source required by the ODBC back end on the non-Windows platform.
To define the data source connection for ODBC 2.5 (with a driver manager) 1. For example, from applications that link to the ODBC driver manager provided by Intersolv, define an entry in the odbc.ini file of Intersolv (for example, /opt/odbc/odbc.ini ) as follows:
[DS-NAME] Driver = odbc_backend
where:
DS-NAME: The name of the data source as defined in the binding odbc_backend: The directory where AIS Server is installed
2.
Define a data source connection for ODBC 2.5 without driver manager. Make sure to do the following:
Define the driver manager as the ODBC back end, that is use the driver manager sharable as the back end sharable. Use the DS-NAME defined in step 1 as the ODBC connect attribute value in the bindings data source definition.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your ODBC data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the ODBC data source and select Open. The Configuration editor is displayed.
7.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the ODBC Data Source Connection on a Windows Platform. For Adabas (ADD), enter the information in the Authentication section, if necessary. You can define the following parameters:
8.
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties
Connection test: This tests the physical connection to the data source. Query test: This test runs an SQL SELECT query against the data source.
These tests are described in the following procedures: To test the connection to the ODBC data source Open Attunity Studio.
ODBC Data Source 48-9
1.
2. 3. 4. 5. 6.
In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your ODBC data source. Expand the binding with the ODBC data source. Expand the Data sources folder. Right-click the required ODBC data source, and select Test. The Test Wizard screen opens.
7.
Select the workspace that you want to work against from the Active Workspace Name list, and click Next. The system now tests the connection to the data source, and returns the test result status.
8.
In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your ODBC data source. Expand the binding with the ODBC data source. Expand the Data sources folder. Right-click the required ODBC data source entity, and select Query Tool. The Select Workspace screen opens.
7.
Select the workspace that you want to work against and click OK. The Query Tool opens in the Editor pane, with the Build Query tab displayed (see step 10).
8. 9.
Select the required query type from the Query Type list. The default is a SELECT-type query. Locate and expand the your ODBC data source. The ODBC data source tables are listed.
10. Drag the required table to the Table column, as shown in the following figure:
The image shows the Query Tool screen, when testing the ODBC RDB data source. ***********************************************************************************************
11. Click Execute query.
The Query Result tab opens, displaying the results of the query.
12. Close the Query Tool in the Editor pane.
Logging
Log files are used for troubleshooting and error handling. The log file is generated when the driverTrace debug binding parameter is set to True. The log file includes various information concerning the functions used or called by the driver, queries executed, data sources accessed, and so on. First, you need to create the log file. To create a log file 1. Open Attunity Studio.
2.
From the main menu, click Windows, Preferences. The Preferences screen is displayed.
In the left pane, click Studio. Select the Advanced tab. Select the Show advanced environment parameters check box. Click OK. In the Design perspective, Configuration view, right-click the binding under which the ODBC data source resides, and select Open. Expand the Debug category. Select GDB Trace and General Trace.
49
OLEDB-FS (Flat File System) Data Source
This section contains the following topics:
Overview Data Provider Requirements Functionality Transaction Support Data Types Configuration Properties Defining the Data Source
Overview
The OLEDB-FS Data Source driver is a generic data source for data providers that do not have SQL processing capabilities but expose OLE DB Index interfaces. The data source is certified against JOLT, a Microsoft OLE DB interface over JET. The current version of this data source does not support OLE objects. It also does not support the Variant data type for columns. Attunity Connect passes any required username and password to the provider when the application calls IDBInitialize::Initialize(). See Managing a User Profile in Attunity Studio.
For tables to be updateable, the provider must expose bookmarks. The provider must expose the following OLE DB interfaces.
Notes:
1. 2. 3.
Required only if BLOBs are used in the OLE DB provider. Required only if indexes are used in the OLE DB provider. The IErrorLookup with the GetErrorDescription method can also be used.
Functionality
This section describes the following aspect of OLEDB-FS functionality:
Isolation Levels
Isolation Levels
The OLEDB-FS data source supports the following Isolation Levels:
If the back-end data source does not support an isolation level, the data source supports the isolation levels that are supported by the back-end data source. The isolation level is used only within a transaction.
Transaction Support
The OLEDB-FS data source supports one-phase commit if distributed transactions are supported in the back-end data source. It can participate in a distributed transaction if it is the only one-phase commit data source being updated in the transaction. Both the transaction environment properties convertAllToDistributed and useCommitConfirmTable must be set to true.
Data Types
SQL data types are mapped to OLE DB data types as described in OLE DB (ADO) Client Interface. See also ADD Supported Data Types.
Configuration Properties
The following properties can be configured for the OLEDB-FS data source Design perspective, Configuration view of Attunity Studio. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect: This parameter indicates whether or not the Explicit Select option is disabled. isolationLevel: This parameter specifies the default isolation level for the data source, as follows: dynamicIsolation: The isolation level is not set at the data source level. Setting this parameter to true allows the application to set this parameter dynamically as needed. readUncommitted: This value specifies that corrupt data is not be read. This is the lowest isolation level. readCommitted: This value specifies that only the data committed before the query began is displayed. repeatableRead: This value specifies that data used in a query is locked and cannot be used by another query nor updated by another transaction. serializable: This value specifies that the data is isolated serially. Data is treated as if transactions are executed sequentially.
Note:
If the specified level is not supported by the data source, then Attunity Connect defaults to the next highest level.
Defining the OLEDB-FS Data Source Connection Configuring the OLEDB-FS Data Source Properties
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your OLEDB-FS data source. Expand the Bindings folder. Expand the binding where you want to add the OLEDB-FS data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select OLEDB-FS from the Type list. Enter the connect string information as described below: Enter the following:
OLEDB Provider: Enter the name of the provider as it appears in the registry (this value is case sensitive). Oledb Data Source Name: Enter the name of the data source. Catalog Name (optional): Enter the name of the catalog.
Data Link File : Specify the full path and name of the UDL file.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your OLEDB-FS data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the OLEDB-FS data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the OLEDB-FS Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
50
OLEDB-SQL (Relational) Data Source
This section contains the following topics:
Overview Data Provider Requirements Functionality Transaction Support Data Types Configuration Properties Defining the Data Source
Overview
The OLEDB-SQL Data Source is a generic driver for data providers that have an SQL processing capability and expose OLE DB interfaces. This data source has been tested with Microsoft Kagera (MSDASQL), enabling an OLE DB interface over the Microsoft SQL Server data provider. Attunity Connect passes username and password to the provider when calling IDBInitialize::Initialize(). For more information, see Managing a User Profile in Attunity Studio. When working with a BRAZOS (with MS Access) database, the OLEDB-SQL data source driver does not support tables or stored procedures, which have duplicate column names.
The provider must be registered with the OLE clsid. The provider must have an SQL processing capability exposed via the ICommand interface.
Batch UPDATE commandsin standard ANSI 92 SQL must be supported. For tables to be updateable, at least one unique index with non-nullable key fields must be reported by the provider. The provider must expose the following OLE DB interfaces.
Notes:
1. 2.
IErrorLookup can be used with the GetErrorDescription method as well. Required only if BLOBs are used in the OLE DB provider.
Functionality
This section describes the following aspects of OLEDB-SQL data source driver functionality:
Isolation Levels
The OLEDB-SQL data source supports the following Isolation Levels:
If the back-end data source does not support an isolation level, the data source supports the isolation levels that are supported by the back-end data source. The isolation level is used only within a transaction.
Stored Procedures
The OLEDB-SQL data source driver supports stored procedures. To retrieve output parameters, multiple resultsets, and the return code from the stored procedure, use the "? = CALL" syntax (see CALL Statement).
Transaction Support
The OLEDB-SQL data source driver supports one-phase commit if distributed transactions are supported in the back-end data source. It can participate in a distributed transaction if it is the only one-phase commit data source being updated in the transaction. Both the transaction environment properties convertAllToDistributed and useCommitConfirmTable must be set to true.
Data Types
This table shows how Attunity Connect maps OLE DB data types to SQL data types.
Table 502 Mapping OLE DB Data Types SQL Data Type SQL_TIMESTAMP SQL_DATE SQL_BINARY SQL_TIME SQL_TINYINT SQL_SMALLINT SQL_INTEGER SQL_REAL SQL_DOUBLE SQL_CHAR SQL_VARCHAR SQL_TINYINT
OLE DB Data Type DBTTYPE_DBTIMESTAMP DBTYP_DBDATE DBTYPE_BYTES DBTYPE_DBTIME DBTYPE_I1 DBTYPE_I2 DBTYPE_I4 DBTYPE_R4 DBTYPE_R8 DBTYPE_STR DBTYPE_STR DBTYPE_UI1
Table 502 (Cont.) Mapping OLE DB Data Types OLE DB Data Type DBTYPE_UI2 DBTYPE_UI4 SQL Data Type SQL_SMALLINT SQL_INTEGER
The OLEDB-SQL data source driver does not support the Variant data type for columns. See also ADD Supported Data Types.
Configuration Properties
The following properties can be configured for the OLEDB-SQL data source Design perspective, Configuration view of Attunity Studio. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect: This parameter indicates whether or not the Explicit Select option is disabled. isolationLevel: This parameter specifies the default isolation level for the data source, as follows: dynamicIsolation: The isolation level is not set at the data source level. Setting this parameter to true allows the application to set this parameter dynamically as needed. readUncommitted: This value specifies that corrupt data is not be read. This is the lowest isolation level. readCommitted: This value specifies that only the data committed before the query began is displayed. repeatableRead: This value specifies that data used in a query is locked and cannot be used by another query nor updated by another transaction. serializable: This value specifies that the data is isolated serially. Data is treated as if transactions are executed sequentially.
Note:
If the specified level is not supported by the data source, then Attunity Connect defaults to the next highest level.
Defining the OLEDB-SQL Data Source Connection Configuring the OLEDB-SQLData Source Properties
2. 3. 4. 5. 6.
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your OLEDB-SQL data source. Expand the Bindings folder. Expand the binding where you want to add the OLEDB-SQL data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select OLEDB-SQL from the Type list. Enter the connect string information as described below: Enter the following:
OLEDB Provider: Enter the name of the provider as it appears in the registry (this value is case sensitive). OLEDB Data Source Name: Enter the name of the data source. Catalog Name (optional): Enter the name of the catalog.
Data Link File: Specify the full path and name of the UDL file.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your OLEDB-SQL data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the OLEDB-SQLdata source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the OLEDB-SQL Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
51
Oracle Data Source
This section contains the following topics:
Overview Functionality SQL Capabilities Configuration Properties Metadata Transaction Support Security Data Types Platform-Specific Information Defining the Oracle Data Source Testing the Oracle Data Source
Overview
The Oracle Data Source provides a wide range of common standard relational functionalities that comply with the Relational Data Source model. The Oracle data source Driver implements connectivity to an Oracle database instance by means of an embedded OCI interface. Some capabilities are actively implemented as data source driver functionalities while others are implied by the methods and techniques the data source driver uses for interacting with the Oracle Backend Database.
Supported Features
The Oracle data source driver covers the core of the following common traditional relational capabilities:
Transaction management Logging Security Recovery Ordinary scalar data types Large data objects Locking Triggers Stored procedures
Functionality
This section covers the following aspects of Oracle functionality:
Stored Procedures
The Oracle data source driver supports Oracle stored procedures with scalar type parameters and output cursors (one or more). It also supports functions with a return type of cursor. The stored procedure name must be less than 27 characters. The Oracle data source driver carries out the Invocation of stored procedures natively. To retrieve output parameters and the return code from the stored procedure, use the ? = CALL syntax. Oracle Stored Procedure enforces certain limitations on SQL statements and logic applicable within the stored procedure itself. See specific product documentation for details.
With a row-level locking strategy, each row within a table can be locked individually. Under table-level locking strategy, the entire table is locked as an entity. The Oracle data source locks themselves are categorized into two modes:
The exclusive lock mode prevents locked objects from being shared. An exclusive lock is obtained for modifying data. The first transaction that applies an exclusive lock is the only one that can modify the locked object, until the lock is released. The shared lock mode allows objects to be share among several users, subject to the operation involved. Multiple users can read data in a shared mode while preventing access by writers who attempt to apply an exclusive lock.
Locks applied on database objects within a transaction scope are released only as the transaction ends, i.e. when changes are either committed or rolled back. Oracle automatically converts a table lock mode of lower restrictiveness to one of higher restrictiveness as appropriate. For example, assume that a transaction uses SELECT FOR UPDATE syntax to lock rows. If the transaction later UPDATEs locked rows, the shared lock is automatically converted to an exclusive lock on the row. Another approach, known as lock escalation, occurs when numerous locks are held at a given object level of granularity (i.e. rows) and a database raises the locks to a higher level of granularity (for example, table). The Oracle data source does not escalate locks, thereby reducing the chances for potential deadlocks where two or more users are waiting for data locked by each other in a circular fashion. See also:
Consistency Attunity Connect Treatment of Locking Attunity Connect Treatment of Isolation Levels
Consistency
Oracle data source optimized concurrent access policy for obtaining consistent read access can be briefly summarized as follows:
Readers do not wait for Writers Readers do not wait for other readers Writers do not wait for Readers (of the same data) Writers wait for other Writers only if they attempt to update identical rows in concurrent transactions
The Oracle data source controls read consistency by qualifying transactions with an appropriate isolation level. Isolation level can be set to either READ COMMITED, which is the default, or SERIALIZABLE, in which case all queried data within that transaction reflect the state of the database as of the time that transaction began. Queries that do not modify any data can ask for a READ ONLY transaction.
manner by specifying individual rows to be locked upon demand at a specific point in time. The Oracle data source driver is sensitive to the transaction mode being applied. In cases where it senses a READ ONLY transaction, it composes a SET TRANSACTION statement qualified with a READ ONLY clause:
SET TRANSACTION READ ONLY ...
The configured setting affects the ISOLATION LEVEL clause of the composed SET TRANSACTION statement. However, since the Oracle data source supports only READ COMMITED and SERIALIZABLE, the following conversion is applied:
Table 511 Isolation Level Conversions Effective Isolation Level Clause READ COMMITTED READ COMMITTED SERIALIZABLE SERIALIZABLE
BLOBs
The Oracle data source data source driver provides support for the built-in predefined opaque data types known as Segmented String/List Of Byte Varying. Both READ and WRITE operations are supported. BLOBs are addressed as ordinary fields. They are handled by dedicated cursors that step along their data. For handling a BLOB field, successfully the table must have a genuine unique key defined.
Passthru Queries
SQL capabilities, as implemented internally by AIS, are equipped with means for delegating SQL statements as-is to the backend engine. When using this technique, known as Passthru, SQL statements are passed as a whole and processed directly by the database engine, much like the ordinary interactive SQLplus utility would process them. Passthru processing is especially advantageous in cases where one attempts gain explicit control on the processed statement and facilitate proprietary features. For
example, introducing refined specific nuances of a CREATE INDEX statement can be carried out using this technique. The following example demonstrates how one can create an index with explicit control on specified attributes, with Passthru Using NAV_UTIL Utility.
NV_EMPLOY is defined as follows: NavSQL > desc nv_employ; Connecting .... ----------------------------------------------------------------Table NV_EMPLOY There are 5 fields in the table: # Name Datatype Size Width Scl Nullable ----------------------------------------------------------------------- 0 EMPLOYEE_ID string 5 5 0 no 1 LAST_NAME string 14 14 0 yes 2 CITY string 20 20 0 yes 3 ROWID string 18 18 0 yes (2 indexes specified) Index 1: length is 5, Unique name is NV_EMPLOY_ID segments are: EMPLOYEE_ID Index 2: length is 18, Unique, Hashed name is ROWID segments are: ROWID <END OF TABLE DESCRIPTION> NavSQL >
Assume that last_name is a common key of reference which warrants an index. Nevertheless, for the sake of usability, one attempts to have a case blind index to ease formulating and processing queries where case sensitivity is of no importance. The Oracle data source provides the following syntax for doing this:
CREATE INDEX lname_case_blind ON NV_EMPLOY(UPPER(LAST_NAME));
This syntax would take the following format when Using NAV_UTIL Utility:
NavSQL > text = {{CREATE INDEX lname_case_blind ON NV_EMPLOY(UPPER(LAST_NAME))}}; Executing: text = {{CREATE INDEX lname_case_blind ON NV_EMPLOY(UPPER(LAST_NAME))}} OK 0 rows affected
This index would typically improve delegated queries like the following:
SELECT * FROM NV_EMPLOY WHERE UPPER(LAST_NAME) = 'SMITH'; NavSQL > select * from nv_employ; EMPLOYEE_ID LAST_NAME CITY 00164 Toliver Chocorua 00165 Smith Chocorua 00166 Dietrich Boscawen 00167 Kilpatrick Marlow 00168 Nash Meadows 00169 Gray Etna 00170 Wood Jefferson 7 rows returned
NavSQL > SELECT * FROM NV_EMPLOY WHERE UPPER(LAST_NAME) = 'SMITH'; EMPLOYEE_ID LAST_NAME CITY 00165 Smith Chocorua 1 rows returned NavSQL >
Recall that the SQL statement is passed through on an as-is basis, with no interpretation and/or any other intervention of any kind. Consequently - it should be phrased according to the lexical notations and syntax rules that comply with those expected by the backend Oracle SQL engine.
SQL Capabilities
The Oracle data source conforms to ANSI92 SQL. This standard includes both the SQL syntax and semantics. AIS uses its own extended SQL (see Attunity SQL Syntax), endowed with advanced capabilities. In most cases, AIS will attempt to delegate SQL portions to the Oracle back end engine for the processing of those SQL features which are supported there. Extended and/or unsupported functionalities are processed internally by AIS. This notion is a part of Attunity Query Processor and Query Optimizer core. To implement it, AIS is fluent in Oracle QL syntax and functionality. The Oracle data source driver assumes the following Oracle SQL elements:
Allows any expressions in GROUP BY clauses Allow any expressions in ORDER BY clauses DB supports distributed Transactions DB does support LOJ transactions LOJ queries are supported but subject to any Query Processor restrictions When creating table name in t2sql, quote also the owner name DB supports UNION operator DB supports UNION ALL DB supports FOR UPDATE inclusion in statement DB supports FOR UPDATE OF inclusion in statement Oracle native RDBMS hints are supported
The following table lists the main Oracle functionalities as symbolically expressed in its SQL.
Table 512 Functionality _POSITION_ _NVL_ _CASE_ _DATE_CONST_ _TIMESTAMP_CONST_ _CURRENT_TIMESTAMP_ Oracle Functionality Expressed in SQL Symbolic Syntax Not Supported NVL(~, ~) DECODE (`,) TO_DATE(''~-~-~'', ''YYYY-MM-DD'') TO_DATE(''~-~-~ ~:~:~'',''YYYY-MM-DD HH24:MI:SS'') SYSDATE
Table 512 (Cont.) Oracle Functionality Expressed in SQL Functionality _ADD_MONTHS_ _LAST_DAY_ _MONTHS_BETWEEN_ _NEXT_DAY_ _CONTAINS2_ _CONTAINS3_ _COS_ _SIN_ _TAN_ _ACOS_ _ASIN_ _ATAN_ _COSH_ _SINH_ _TANH_ _LOG10_ _LN_ _EXP_ _POWER_ Symbolic Syntax ADD_MONTHS(~, ~) LAST_DAY(~) MONTHS_BETWEEN(~, ~) NEXT_DAY(~, ~) CONTAINS(~, ~) CONTAINS(~, ~,~) COS(~) SIN(~) TAN(~) ACOS(~) ASIN(~) ATAN(~) COSH(~) SINH(~) TANH(~) LOG(10,~) LN(~) EXP(~) POWER(~)
To optimize the result of a query. To force the query processor to read past any locked tables. This is useful when you need to scan tables during work hours and you must get information as quickly as possible. To limit the rows of a table that are scanned. To carry out an index scan.
AIS supports both its own hints and backend relational database hints (currently only Oracle hints are supported). For more information on using hints in SQL statements, see Attunity SQL Syntax. See also:
Attunity Hints
Attunity hints indicate the optimization strategy. If more than one hint is entered in the statement, the optimizer uses the most efficient strategy. Before selecting an
optimization strategy, you should check it with the Attunity Query Analyzer. The following hints are supported:
SCAN: Indexes are ignored and the data is scanned according to its physical order. INDEX: The index identified by the indname parameter is used to find specific values in the WHERE clause. If the WITHOUT parameter is used, the index is ignored for the indicated values. INDEXSCAN: The index identified by the indname parameter is used to seek for all values. If the WITHOUT parameter is entered, the index is ignored. FIRST: The left table in the join strategy. This table will be the first table in the optimized tree (on the left side). LAST: The table will be the last table in the optimized tree. ON <cond>: A condition determining the results of the <join>.
The following parameters are used with hints in the SQL statement to define how the hint will work:
WITH: Use the optimization strategy indicated by the hint. WITHOUT: Do not use the optimization strategy indicated by the hint. indname: The name or an ordinal of an index. <n>: The number of segments used with the INDEX hint. A value of zero (0) is the same as using the INDEXSCAN hint.
In this Select statement, the hint Index is used and emp_prim is the indname parameter; 2 is the n or number parameter.
Oracle Hints
Attunity connect also supports hints in Oracle syntax when using an Oracle data source. For a list of hints used with the Oracle syntax, see the Oracle documentation. You use hints with the following statements:
You can use any supported Oracle hint. You can also create a statement that includes more than one table and more than one hint. In this case, AIS combines the hints and separates them with a space delimiter. AIS combines the hints from all the tables processed by the delegated SQL statement. The hints are added after the first key word of the resulting statement. For example: When you enter the following SQL statement:
Select from A <DBHINT(hint1)> ;
It is converted to:
Select /*+ hint1 */ from A ;
It is converted to:
Select /*+ hint1 hint2*/ from A,B ;
It is converted to:
Insert /*+ hint1 hint2*/into A select * from B ;
When a hint refers directly to a schema (such as, tablename, index, or column) the hint must contain an explicitly provided alias. For example:
select * from T1 b <dbhint ('index (B t1i2)')> where b.c = 1);
Notes:
If your hint refers to a schema, and you do not provide an alias, AIS will generate its own alias and the hint will not work. AIS does not check the content of Oracle hints.
Configuration Properties
The following properties can be configured for the Oracle data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
isolationLevel=value: This parameter specifies the default isolation level for the data source, as follows: readUncommitted: This value specifies that corrupt data is not to be read. This is the lowest isolation level. readCommitted: This value specifies that only the data committed before the query began is displayed. repeatableRead: This value specifies that data used in a query is locked and cannot be used by another query nor updated by another transaction. serializable: This value specifies that the data is isolated serially. Treats data as if transactions are executed sequentially.
Note:
If the specified level is not supported by the data source, then Attunity Connect defaults to the next highest level.
newDecimal=true|false: This parameter specifies whether or not the decimal data type is treated as a decimal or double data type. The default value is false, which is valid for users of Oracle 8.0. Users of Oracle 8i and higher should change the value to true.
Metadata
Within the relational model, metadata definitions are maintained and held in dedicated system tables that are accessed by ordinary SQL queries. The Oracle data source queries these system tables for its own metadata needs. A metadata query issued by the data source driver to display a list of tables matching a given pattern would have the following generic format:
select table_name, table_owner from all_synonyms where synonym_name = :1 and (owner like :2 or owner='PUBLIC')";
Similarly, retrieving index information for a given table is achieved by the following compound generic statement:
select i.index_name, i.uniqueness, c.column_name, i.distinct_keys from all_indexes i,all_ind_columns c where i.index_name = c.index_name and i.table_name = c.table_name and i.owner = c.index_owner and i.table_owner = c.table_owner and c.table_name = :1 and c.table_owner like :2 order by c.index_name,c.column_position
Specific details regarding the inner components of a given table, such as fields, data types and so forth are sampled by querying the table and describing its contents using standard programmed techniques. A sequence which is logically equivalent to the following example is applied programmatically:
Set recqry_str to "SELECT * FROM EMPLOYEES" PREPARE record_query FROM recqry_str; DESCRIBE record_query INTO rec_sqlda;
As a result rec_sqlda structure now holds the full mapping of EMPLOYEES table.
Statistics
Statistical information is, in a sense, yet another piece of metadata maintained internally at dedicated system tables. Consequently, the same notions regarding metadata objects prevail for statistics as well.
The Oracle data source gathers available statistics held inside the database instance. This information is used later by the run time components for developing, evaluating and choosing execution strategies at query optimization phases. Consider the following example:
select num_rows , blocks from all_tables where table_name = :1 and owner like :2
A particular instantiation of this query introduced to the driver will result the following:
NavSQL > select num_rows , blocks from all_tables where table_name = 'EMPLOYEES' and owner like '%'; num_rows 107 1 rows returned NavSQL > blocks 5
Upon optimizing a query involving the EMPLOYEES table for achieving best solution, these figures are considered, together with other structural and quantitative factors. In a similar manner, index statistics, which have an important role in the optimization phase, are also gathered from the metadata tables.
Transaction Support
The Oracle driver supports two-phase commit and can fully participate in a distributed transaction when the transaction environment property convertAllToDistributed is set to true. Use Oracle with its two-phase commit capability through an XA connection.The daemon server mode must be configured to Single-client mode (see Server Mode). To use distributed transactions from an ODBC-based application, ensure that AUTOCOMMIT is set to 0.
Security
The Oracle data source driver is not actively involved in applying or enforcing security policy. It incorporates into the security policy and rules as set at the database instance with which it interacts.
Data Types
This table shows how Attunity Connect maps Oracle data types to OLE DB and ODBC data types.
Table 513 Oracle BFILE BLOB CFILE Char (m<256) Char (m>255) Mapping Oracle Data Types OLE DB DBTYPE_BYTES DBTYPE_BYTES DBTYPE_STR DBTYPE_STR DBTYPE_STR ODBC SQL_LONGVARBINARY SQL_LONGVARBINARY SQL_LONGVARCHAR SQL_CHAR SQL_LONGVARCHAR1
Table 513 (Cont.) Mapping Oracle Data Types Oracle CLOB Date Float Long Long Raw Number(9<p<31) Number(p,s) Number(p<=4) Number(p<=9) Number(p>31) Varchar2 (m<256) Varchar2 (m>255) OLE DB DBTYPE_STR DBTYPE_DATE DBTYPE_R8 DBTYPE_BYTES DBTYPE_BYTES DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_I2 DBTYPE_I4 DBTYPE_R8 DBTYPE_STR DBTYPE_STR ODBC SQL_LONGVARCHAR SQL_TIMESTAMP SQL_DOUBLE SQL_LONGVARCHAR SQL_LONGVARBINARY SQL_NUMERIC(p) SQL_NUMERIC(p,s) SQL_SMALLINT SQL_INTEGER SQL_DOUBLE SQL_VARCHAR SQL_LONGVARCHAR1
Note:
21. Precision of 2147483647. If the <odbc longVarcharLenAsBlob> parameter is set to true in the Attunity Server environment settings, then precision of m.
This table shows how Attunity Connect maps data types in a CREATE TABLE statement to Oracle data types.
Table 514 CREATE TABLE Data Types Oracle Raw Char[(m)] Date Float Float Long Raw Raw(m) Number (10) Float Numeric(p,s) Number (5) Long Date Date Number (3) Varchar2(m)
CREATE TABLE Binary Char[(m)] Date Double Float Image Image(m) Integer Numeric Numeric(p[,s]) Smallint Text Time Timestamp Tinyint Varchar(m)
Platform-Specific Information
This section includes Oracle-related information and procedures as they pertain to specific platforms, as follows:
UNIX Platforms
This section includes Oracle-related information and procedures as they pertain to UNIX platforms.
Make sure that the Oracle shared library directories come after $NAVROOT/lib in the UNIX shared library environment variable.
Oracle only allows a dba group or superuser the right to access the Oracle libraries. In client/server mode, the server process owner allocated by the daemon must have the main group as dba or super user.
OpenVMS Platform
This section includes Oracle-related information and procedures as they pertain to OpenVMS platforms. The following topics provide information about the Oracle Data Source on the OpenVMS Platform.
Verifying Environment Variables on OpenVMS Platforms Linking to Oracle Libraries on OpenVMS Platforms
To verify the environment variables 1. Add the following line to the shared library environment variable: ORACLE_HOME:[rdbms.lib] and ORACLE_HOME:[lib] directories where ORACLE_HOME is the directory where Oracle is installed.
2.
Make sure that the Oracle shared library directories come after NAVROOT:[lib] in the OpenVMS shared library environment variable.
Oracle only allows a dba group or superuser the right to access the Oracle libraries. In client/server mode, the server process owner allocated by the daemon must have the main group as dba or super user.
Run the login procedure NAV_LOGIN using its full pathname. $ @NAVROOT:[BIN]NAV_ORA_BUILD $ @SYS$STARTUP:NAV_START
Defining the Oracle Data Source Connection Configuring the Oracle Data Source Properties Configuring Table and Column Names to be Case Sensitive Checking Oracle Environment Variables
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your Oracle data source. Expand the Bindings folder. Expand the binding where you want to add the Oracle data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select Oracle from the Type list. Click Next. The Data Source Connect String screen is displayed.
10. Enter the Oracle connect string. See the Oracle documentation for the specific
connect string.
11. Click Finish.
Note: The data source 32 bit client must be used to access Oracle on 64 bit operating systems (HP-UX 11 and higher, AIX 4.4 and higher and Sun Solaris 2.8 and higher).
Open Attunity Studio. In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Oracle data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the Oracle data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. See the Oracle documentation for the specific connect string. For Adabas (ADD), enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties
Connection test: This tests the physical connection to the data source. Query test: This test runs an SQL SELECT query against the data source.
These tests are described in the following procedures: To test the connection to the Oracle data source 1. Open Attunity Studio.
2. 3. 4. 5. 6.
In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your Oracle data source. Expand the binding with the Oracle data source. Expand the Data sources folder. Right-click the required Oracle data source, and select Test. The Test Wizard screen opens.
7.
Select Navigator from the Active Workspace Name list, and click Next. The system now tests the connection to the data source, and returns the test result status.
8.
1. 2. 3. 4. 5. 6.
To test the Oracle data source by query Open Attunity Studio. In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your Oracle data source. Expand the binding with the Oracle data source. Expand the Data sources folder. Right-click your Oracle data source, and select Query Tool. The Select Workspace screen opens.
7.
Select Navigator and click OK. The Query Tool opens in the Editor pane, with the Build Query tab displayed (see step 10).
8. 9.
Select the required query type from the Query Type list. The default is a SELECT-type query. Locate and expand your Oracle data source. The Oracle data source tables are listed.
10. Drag the required table to the Table column, as shown in the following figure: Figure 512 The Query Tool screen
The Query Result tab opens, displaying the results of the query.
12. Close the Query Tool in the Editor pane.
From the main menu, click Windows, Preferences. The Preferences screen is displayed.
3. 4. 5. 6. 7. 8. 9.
In the left pane, click Studio. Click the Advanced tab. Click the Show advanced environment parameters check box. Click OK. In the Design perspective Configuration view, right-click the binding with the Oracle data source, and select Open. Expand the Debug section. Select GDB trace and General trace.
10. Execute the following query: Select * from nation limit to 3 rows.
Attunity Server Log (V4.9.0.0, ALPHA-VMS) Started at 2006-04-25T12:51:12 Licensed by ISG LTD. on 02-APR-2000 (001001205) Licensed to ISG LTD for <all providers> on 194.90.22.* (<no platform>) Licensed by ATTUNITY LTD. on 09-AUG-2000 (001001237) Licensed to ATTUNITY for <all providers> on 194.90.22.* (<all platforms>) RDB Execute: CONNECT AS 'NAV_READmyRDBSQL'
RDB Execute: ATTACH 'ALIAS MYRDBSQL FILENAME US:[TEST.APTEST.APP.RDB70]MAIN_ DB.RDB' RDB Execute: SET TRANSACTION ON MYRDBSQL USING (READ ONLY NOWAIT )
COMMIT NAV_READmyRDBSQL
COMMIT NAV_READmyRDBSQL
nvOUT (VER:[WORK]QP_SQTXT.C;6 56): select * from nation limit to 3 rows nvRETURN (VER:[WORK]QPSYNON.C;6 1140): -1 RDB Execute: SET TRANSACTION ON MYRDBSQL USING (READ ONLY NOWAIT
<<<<<<<<<<<<<<<<<<<
Accessing Database 'myrdbsql' with SQL: SELECT T0000.N_NATIONKEY, T0000.N_NAME, T0000.N_REGIONKEY, T0000.N_COMMENT FROM MYRDBSQL.nation T0000
>>>>>>>>>>>>>>>>>>>> Execution Strategy End >>>>>>>>>>>>>>>>>>>>>>>>>>>> nvOUT (VER:[WORK]QPSQLCSH.C;6 140): ---------------------------> Using Cached QSpec SELECT T0000.N_NATIONKEY, T0000.N_NAME, T0000.N_REGIONKEY, T0000.N_COMMENT FROM MYRDBSQL.nation T0000 nvRETURN (VER:[WORK]DRVIUNWN.C;6 804): -1210 (Last message occurred 2 times) Disabled FilePool Cleanup(DB=___sys, FilePool Size=0) COMMIT NAV_READmyRDBSQL RDB Execute: disconnect 'NAV_READmyRDBSQL' FilePool Shutdown(DB=___SYS, FilePool Size=0) Closing log file at TUE APR 25 12:52:08 2006
52
Oracle RDB Data Source (OpenVMS Only)
This section contains the following topics:
Overview Functionality SQL Capabilities Configuration Properties Metadata Transaction Support Security Oracle RDB Data Types Defining the Oracle RDB Data Source Testing the Oracle RDB Data Source
Overview
The Oracle RDB Data Source provides a wide range of common standard relational functions that comply with the Relational Data Source model. The Oracle RDB data source Driver implements connectivity to an Oracle RDB database instance by means of an embedded SQL technique. Some capabilities are actively implemented as data source driver functions while others are implied by the methods and techniques the data source driver uses for interacting with the Oracle RDB Backend Database.
Supported Features
The Oracle RDB data source driver covers the core of the following common traditional relational RDBMS capabilities:
Logging Security Recovery Ordinary scalar data types Large data objects Locking Triggers Stored procedures
Functionality
This section covers the following aspects of Oracle RDB functions:
Stored Procedures
The Oracle RDB data source driver supports Oracle RDB stored procedures, however the stored procedure name must be less than 27 characters and cannot return a resultset. Invocation of stored procedures is carried out natively by the data source driver. To retrieve output parameters and the return code from the stored procedure, use the? = CALL syntax. The Oracle RDB data source driver is not capable of handling row set as output. Oracle RDB Stored Procedure enforces certain limitations on SQL statements and logic applicable within the stored procedure itself. See specific product documentation for details.
Lock the object Perform the required work on the object Unlock the object at a later time, most likely at the end of the Transaction
Index node
Oracle RDB implements a dedicated logic that chooses the appropriate object and adjusts the lock granularity. It selects a suitable lock object and level which are based on the operation being performed in a given context. All this is aimed at minimizing potential lock conflicts. Note that the locking scope is normally associated with a transaction. The SET TRANSACTION syntax contains elements for controlling the LOCKING applied:
Nevertheless Oracle RDB locking policy is rather strict. Lock conflicts are a matter of routine in a database that serves multiple users concurrently. A user can be a 'Blocker', while holding a locked resource required by others, or 'Blocked By', while waiting for a resource locked by others to be released or 'Both'. Circular lock conflicts can lead to deadlock situations where User A locks Resource 1 and waits for Resource 2, which is locked by User B who is waiting for Resource 1. The Oracle RDB data source driver is aware of Oracle RDB potential locking conflicts and provides certain built-in relief measures:
The default transaction WAIT parameter is 0. This translates to NOWAIT, which actually means that a default transaction initiated by the Oracle RDB data source will not be blocked. Instead it will inform of a lock conflict if one is encountered. The default proposed isolation level is READ COMITTED which reduces lock contention and increases the degree of concurrency. Note that this affects 'pure' transactional integrity, since data committed by others is visible in your transaction. The Oracle RDB data source maintains dual (multiple) connections to the database. This notion is based on the fact that when snapshots are enabled for a database (the default), READ ONLY transactions do not lock the rows they read. Data is read from the snapshot maintained by Oracle RDB. Therefore the Oracle RDB data source driver normally holds two connections to the database. The first, denoted as NAV in the data source driver's log, is used for WRITE transactions, which are subject to LOCK conflicts. The second, denoted as NAVREAD, serves the READ transactions. This notion of duplicating connections is also extended to separating DDL and stored procedure locking activities from the main data source driver's course, which is READ/WRITE operations. The Oracle RDB data source provides explicit control on elements that affect locking along the transaction. This is carried out by assigning appropriate values to configurable parameters, as described above. In particular, ISOLATION LEVEL can be set explicitly both for READ and WRITE transactions as follows: readCommitted: Allows your transaction to see all data committed by other transactions. repeatableRead: Guarantees that if you execute the same query again, your program receives the same rows it read the first time. However, you may also see rows inserted and committed by other transactions (known as Phantoms). serializable: Guarantees that the operations of concurrently executed transactions are not affected by any other transaction.
BLOBs
The Oracle RDB data source data source driver provides support for the built-in predefined opaque data types known as Segmented String/List Of Byte Varying. Both READ and WRITE operations are supported. BLOBs are addressed as ordinary fields. They are handled by dedicated cursors that step along their data. For handling a BLOB field successfully, the table must have a genuine unique key defined.
Passthru Queries
Attunity SQL Syntax provides the ability to pass SQL code directory to the Oracle engine. This technique, known as Passthru, is useful in cases when attempting to be very accurate in controlling the processed statement and facilitate proprietary features. For example, introducing refined specific nuances of a CREATE INDEX statement can be carried out using this technique. The following example shows how to create an index with explicit control on RANKED/COMPRESSED qualifiers, using Passthru Using NAV_UTIL Utility. In interactive SQL it would look as follows:
SQL> CREATE INDEX JH_EMP_ID cont> ON JOB_HISTORY (EMPLOYEE_ID) cont> TYPE IS SORTED RANKED cont> DUPLICATES ARE COMPRESSED;
Remember that the SQL statement is passed through on an as-is basis, with no interpretation and/or any other intervention of any kind. Consequently, this statement should comply with the syntax rules of the Oracle SQL engine.
SQL Capabilities
The Oracle8 data source conforms to the ANSI 92 SQL standard for both syntax and semantics. While it has its own extended SQL (see Attunity SQL Syntax), including advanced capabilities, it will endeavour to delegate all the SQL code that can be processed by Oracle to the database engine. All extended or unsupported functions are passed to the Oracle engine for processing. The Oracle RDB data source driver assumes the following Oracle RDB SQL elements:
Does not support aliases for columns Allows an optional prefix before table name Allows 'ORDER BY <column name>' when <column name> does not have to appear in SELECT If a date/timestamp literal is set, this means that the month is JAN and not 01 No support for owners DB supports UNION DB supports UNION ALL
DB supports FOR UPDATE DB supports FOR UPDATE OF DB supports LOJ transactions LOJ queries are supported but subject to any Query Processor restrictions
The following table lists the main Oracle RDB functions as symbolically expressed in its SQL.
Table 521 Oracle RDB Functions Expressed in SQL Symbolic Syntax Not Supported CHAR_LENGTH(~) SUBSTRING(~ FROM ~ FOR 9999) SUBSTRING(~ FROM ~ FOR ~) TRIM(LEADING '' '' FROM ~) TRIM(TRAILING '' '' FROM ~) CASE WHEN '0 >= 0 THEN '0 ELSE -('0) END Not Supported COALESCE(~, ~) CASE ~ {{WHEN ~ THEN ~}} [[ELSE ~]] END CASE {{WHEN ~ THEN ~}} [[ELSE ~]] END_ Not Supported CAST(~ AS ~) DATE VMS '''2-'1-'0 00:00:00.00'" DATE VMS '''2-'1-'0 '3:'4:'5.'6'' TIME ''~:~:~.~' CURRENT_DATE CURRENT_TIMESTAMP(2) CURRENT_TIME(2) CASE EXTRACT(WEEKDAY FROM '0) WHEN 7 THEN 1 ELSE (EXTRACT(WEEKDAY FROM '0) + 1) END
Functional Notation YACC_POSITION_ YACC_LENGTH_ YACC_SUBSTR2_ YACC_SUBSTR3_ YACC_LTRIM_ YACC_RTRIM_ YACC_ABS_ YACC_MOD__ YACC_NVL_ YACC_CASE_ YACC_CASE2_ YACC_SQRT_ YACC_CONVERT_ YACC_DATE_CONST_ YACC__TIMESTAMP_ CONST_ YACC_TIME_CONST_ YACC_CURRENT_DATE_ YACC_CURRENT_ TIMESTAMP_ YACC_CURRENT_TIME_ YACC_DAYOFWEEK_
The following table specifies Oracle data type SQL lexical notations as associated with the corresponding AIS types.
Table 522 Oracle and AIS corresponding data types AIS Symbolic Type DT_B_ DT_W_ DT_L_ DT_Q_
Table 522 (Cont.) Oracle and AIS corresponding data types Oracle Lexical Notation FLOAT NUMBER(%d,%d) LONG VARCHAR2(%d) RAW(%d) LONG RAW Not Supp Not Supp AIS Symbolic Type DT_D_ DT_NUMERIC DT_TEXT_ DT_C_ DT_OPAQUE_ DT_IMAGE_ DT_ODBC_TIME_ DT_ODBC_TIMESTAMP_
Configuration Properties
The following properties can be configured for the Oracle RDB data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
Note: The dbName element identifies the Oracle RDB database instance for example - dbName='personnel.rdb'.
accessModeThreshold: Setting this parameter to readOnlyThreshold will restrict the access to read only while setting it to readWriteThreshold will allow both read and write. No additional thresholds are currently supported.
commitReadOnly: Instructs the data source driver to place COMMIT between consecutive READ ONLY transactions. This has certain effects on the managed transaction and snapshot renewal as implemented by Oracle RDB. Further details are available in the product documentation. constraintsMode: Does not affect the ordinary data source driver mode of execution. defaultTransaction: Directs the data source driver as to how to handle situations where no explicit transaction is initiated. It may be either readOnly or readWrite. DisableExplicitSelect: Relevant if the data source driver allows for the suppressing of certain fields for Select *. Thus, if you disable this parameter, all fields will appear for Select *. For example, rowID and dbKey are explicit select. imposedTransactionMode: Enables the enforcement of a transaction mode regardless of the specified transaction qualifiers. You can specify: none: This value specifies that the default access mode is used. read: This value specifies that the database is read only. write: This value specifies that the database is accessed in WRITE mode.
This is useful for imposing read access via the Oracle RDB data source driver.
isolationLevel: In charge of controlling the isolation level applied on an Oracle RDB transaction. Isolation level determines to what extent data manipulated at a given session is affected by changes made by others concurrently. Oracle RDB is fully compliant with the ANSI92 standard in this regard.There are four supported levels that can be configured as attributes for this element: readUncommitted: This value specifies that corrupt data is not to be read. This is the lowest isolation level. readCommitted repeatableRead serializable
See Isolation Levels and Locking for additional descriptive information. Further details regarding the corresponding semantics can be found at the related Oracle RDB /ANSI92 documentation.
lockWait: Controls the composition of the WAIT clause upon transaction start. The default setting of 0 results in the NOWAIT keyword. A positive integer X assembles a WAIT X clause. reservingForReadTransaction/reservingForWriteTransaction: Can be set with a 'reserving clause' of choice which is introduced upon starting a Read/Write transaction respectively. showDbkey: determines whether the DBKEY field is recognized by the Oracle RDB data source driver as a field associated with manipulated tables. A DBKEY is an artificial field managed for every table. It holds information regarding the physical addressing of a given record. By setting it appropriately, you can expose or hide the DBKEY. Thus, when setting showDbkey=true, the following is accepted:
select * from nation where DBKey = ? select n_nationkey,dbkey from nation;
transactionsInSP: addresses conflicts that may occur between the transactions managed by the driver and those possibly set at the stored procedure body. Since a stored procedure is an independent code section that can hold most of the SQL repertoire, there may be an internally initiated transaction, which the data source driver is not aware of. This can put the managed transaction protocol out of synchronization. For these cases, setting this parameter to TRUE results in a dedicated connection for the stored procedure that does not interfere with the data source driver transactional sequence.
useSeparateRWconnections: Manage only one RW connection to a database. The default is two RW connections.
Metadata
The Oracle RDB data source driver polls the Oracle RDB database for required metadata. Following the relational model, metadata definitions reside in a dedicated system table that is accessed by ordinary SQL queries. In this regard, system tables of interest are RDB$RELATIONS, holding information about tables, and RDB$ROUTINES, where procedures are maintained. A metadata query issued by the data source driver for a table listing can look as follows:
SELECT RDB$RELATION_NAME, RDB$DESCRIPTION FROM RDB$RELATIONS
Detailed table/record information fields, types and alike are sampled by querying the table and describing its contents by standard programmed techniques. The following statement sequence illustrates this symbolically:
Set recqry_str to "SELECT * FROM EMPLOYEES" PREPARE record_query FROM recqry_str; DESCRIBE record_query INTO rec_sqlda;
Statistics
The same notions regarding Metadata objects prevail for statistics also. The Oracle RDB data source driver gathers available statistics held inside the database instance. This information is used later for developing, evaluating and choosing execution strategies at query optimization phases (unless dealing with pure Passthru Queries delegated as a whole). Oracle RDB maintains internal cardinality book keeping of various kinds. These figures provide an (estimated) indication as to 'how many pieces are there'. The following illustrates the retrieval of index statistics:
SELECT I.RDB$INDEX_NAME, F.RDB$FIELD_NAME, I.RDB$UNIQUE_FLAG, F.RDB$FLAGS, I.RDB$CARDINALITY FROM RDB$INDICES I, RDB$INDEX_SEGMENTS F WHERE I.RDB$INDEX_NAME = F.RDB$INDEX_NAME and I.RDB$RELATION_NAME = 'EMPLOYEES';
As shown, index properties and structural information are also queried and retrieved.
Transaction Support
The Oracle RDB data source provides support for managing transactions using the following transactional qualifiers:
READ/WRITE: Sets the access mode applied. WAIT x/NOWAIT: Determines how the transaction reacts when a locked resource is required. ISOLATION LEVEL: A configurable property for READ and WRITE that control the degree of sharing/concurrency among users. Reserving clause: Provides refined instruction regarding access/lock mode to be applied on individual listed tables.
Read/Write qualifiers are normally implied by the DML being processed. Other qualifiers are configured as described above. This relates to the ordinary fundamental one-phase commit transactional protocol as implemented by Oracle RDB. Starting from Oracle RDB V.7x, running on Alpha OpenVMS 7.x, supports Two-phase Commit and can fully participate in a distributed transaction. 2PC support is implemented via a dedicated AIS run time component, namely the XAGW manager. The XAGW manager is a gateway to DECdtm which is the common transaction manager in OpenVMS. The protocol implemented there is the XA interface which is the X/OPEN de facto standard. An Oracle RDB instance plays the role of a Resource Manager that responds to AIS transaction management. The XAGW manager is an independent component which is not a part of the Oracle RDB data source driver.
3.
Use the XGCP control program utility to create a new XG gateway log with the same name as the name of the machine that is within the OpenVMS cluster.
run sys$system:xgcp XA Gateway Control Program V1.0 XGCP> create_log ALPHA XGCP>
Run the server using the XGCP program utility to run the server.
XGCP> start_server
5.
Security
The Oracle RDB data source driver is not actively involved in applying or enforcing security policy. All security policies and rules are defined in and applied by the Oracle database engine.
Table 523 (Cont.) Corresponding AIS and Oracle RDB Data Types Common AIS Mapped Data type DT_TYPE_RDB_DBKEY_ DT_TYPE_VT_ DT_TYPE_ADT_ DT_TYPE_G_, DT_TYPE_F_ DT_TYPE_P_ , DT_TYPE_NL_ _ DT_TYPE_L_ DT_TYPE_LS_ DT_TYPE_W_ DT_TYPE_WS_ DT_TYPE_B_ DT_TYPE_BS_ DT_TYPE_Q_ DT_TYPE_OPAQUE_ DT_TYPE_FILLER_ Generic Oracle RDB SQL Types DBKEY VARCHAR DATE, SQLDA2_DATETIME FLOAT DECIMAL INTEGER Scaled INTEGER SMALLINT Scaled SMALLINT BYTE Scaled BYTE QUADWORD SEGSTRING Others
This table shows how Attunity Connect maps data types in a CREATE TABLE statement to Oracle RDB data types.
Table 524 CREATE TABLE Data Types Oracle RDB CREATE TABLE Text DATE LIST OF BYTE VARYING(x) LIST OF BYTE VARYING(x) VARCHAR(x) CHAR(x) TINYINT SMALLINT INTEGER DECIMAL(x, y) REAL DOUBLE PRECISION
AIS Generic Type DATE of any type DT_TYPE_OPAQUE_ STRING (sacled) DT_TYPE_CSTRING_ DT_TYPE_T_ DT_TYPE_B_ DT_TYPE_W_ DT_TYPE_L_ Scaled DT_TYPE_F_ DT_TYPE_F_
Defining the Oracle RDB Data Source Connection Configuring the Oracle RDB Data Source Properties
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your Oracle RDB data source. Expand the Bindings folder. Expand the binding where you want to add the Oracle RDB data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select RDBSQL from the Type list. Click Next. The Data Source Connect String screen is displayed.
Database file path: Specify the full path name of the database. You can specify a logical name. This is useful if the logical database is distributed across multiple physical databases. For example, if the logical database is distributed across two physical databases called BOSTON_DB and PARIS_DB, you can define the logical name as follows:
define ALL_SITES BOSTON_DB,PARIS_DB
After defining this logical, you can specify ALL_SITES as the Database file path. The driver translates the logical name before binding.
Note:
Attunity Connect does not natively support multi schema databases. As a workaround to use multi schema databases via their stored names, you must explicitly disable multi schema mode. You do this by specifying the following in the Database File Path:
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Oracle RDB data source. Expand the Bindings folder and the binding with your data source.
5. 6.
Expand the Data sources folder. Right-click the Oracle RDB data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Oracle RDB Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source driver properties as required. For a description of the available parameters, see Configuration Properties.
Connection test: This tests the physical connection to the data source.
Query test: This test runs an SQL SELECT query against the data source.
These tests are described in the following procedures: To test the connection to the Oracle RDB data source Open Attunity Studio. In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your Oracle RDB data source. Expand the binding with the Oracle RDB data source. Expand the Data sources folder. Right-click the required Oracle RDB data source, and select Test. The Test Wizard screen opens.
7.
1. 2. 3. 4. 5. 6.
Select Navigator from the Active Workspace Name list, and click Next. The system now tests the connection to the data source, and returns the test result status.
8.
To test the Oracle RDB data source by query 1. Open Attunity Studio.
2. 3. 4. 5. 6.
In the Design perspective, Configuration view, expand the Machines folder. Expand machine with your Oracle RDB data source. Expand the binding with the Oracle RDB data source. Expand the Data sources folder. Right-click the your Oracle RDB data source, and select Query Tool. The Select Workspace screen opens.
7.
Select Navigator and click OK. The Query Tool opens in the Editor pane, with the Build Query tab displayed (see step 10.)
8. 9.
Select the required query type from the Query Type list. The default is a SELECT-type query. Locate and expand your Oracle RDB data source. The Oracle RDB data source tables are listed.
10. Drag the required table to the Table column, as shown in the following figure:
The Query Result tab opens, displaying the results of the query.
12. Close the Query Tool in the Editor pane.
From the main menu, click Windows, Preferences. The Preferences screen is displayed.
3. 4. 5. 6. 7. 8. 9.
In the left pane, click Studio. Click the Advanced tab. Click the Show advanced environment parameters check box. Click OK. In the Design perspective, Configuration view, right-click the binding with the Oracle RDB data source, and select Open. Expand the Debug section. Select GDB Trace and General Trace.
10. Execute the following query: Select * from nation limit to 3 rows.
Attunity Server Log (V4.9.0.0, ALPHA-VMS) Started at 2006-04-25T12:51:12 Licensed by ISG LTD. on 02-APR-2000 (001001205) Licensed to ISG LTD for <all providers> on 194.90.22.* (<no platform>) Licensed by ATTUNITY LTD. on 09-AUG-2000 (001001237) Licensed to ATTUNITY for <all providers> on 194.90.22.* (<all platforms>) RDB Execute: CONNECT AS 'NAV_READmyRDBSQL'
RDB Execute: ATTACH 'ALIAS MYRDBSQL FILENAME US:[TEST.APTEST.APP.RDB70]MAIN_ DB.RDB' RDB Execute: SET TRANSACTION ON MYRDBSQL USING (READ ONLY NOWAIT )
COMMIT NAV_READmyRDBSQL
COMMIT NAV_READmyRDBSQL
nvOUT (VER:[WORK]QP_SQTXT.C;6 56): select * from nation limit to 3 rows nvRETURN (VER:[WORK]QPSYNON.C;6 1140): -1 RDB Execute: SET TRANSACTION ON MYRDBSQL USING (READ ONLY NOWAIT
<<<<<<<<<<<<<<<<<<<
Accessing Database 'myRDBSQL' with SQL: SELECT T0000.N_NATIONKEY, T0000.N_NAME, T0000.N_REGIONKEY, T0000.N_COMMENT FROM MYRDBSQL.nation T0000
>>>>>>>>>>>>>>>>>>>> Execution Strategy End >>>>>>>>>>>>>>>>>>>>>>>>>>>> nvOUT (VER:[WORK]QPSQLCSH.C;6 140): ---------------------------> Using Cached QSpec SELECT T0000.N_NATIONKEY, T0000.N_NAME, T0000.N_REGIONKEY, T0000.N_COMMENT FROM MYRDBSQL.nation T0000 nvRETURN (VER:[WORK]DRVIUNWN.C;6 804): -1210 (Last message occurred 2 times) Disabled FilePool Cleanup(DB=___sys, FilePool Size=0) COMMIT NAV_READmyRDBSQL RDB Execute: disconnect 'NAV_READmyRDBSQL' FilePool Shutdown(DB=___SYS, FilePool Size=0) Closing log file at TUE APR 25 12:52:08 2006
53
RMS Data Source (OpenVMS Only)
This section contains the following topics:
Overview Functionality Configuration Properties Transaction Support Data Types Defining the RMS Data Source Setting Up the RMS Data Source Metadata with the Import Manager
Overview
The following sections provide information about defining and configuring the RMS Data Source.
Supported Features
The RMS data source supports the following key features:
Hierarchical Queries RFA Usage. The RFA can be used as a column in a WHERE clause, when the RMS record is indexed.
Functionality
Record level locking is supported. The lock is released only when the file is closed or when the record is re-read without a lock being applied.
Configuration Properties
The following properties can be configured for the RMS data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect: When true, this parameter disables the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. filepoolCloseOnTransaction: When true, this parameter specifies that all files in the filepool for this data source close at each end of transaction (commit or rollback). filepoolSize: This parameter specifies how many instances of a file from the filepool may be open concurrently. filepoolSizePerFile: Specifies how many instances of a file from the filepool may be open concurrently for each file. lockWait: Specifies whether or not the data source waits for a locked record to become unlocked or returns a message that the record is locked. newFileLocation: The Data directory in the connect string, this parameter specifies the location of the CISAM files and indexes you create with CREATE TABLE and CREATE INDEX statements. You must specify the full path for the directory. useGlobalFilepool: When true, this parameter specifies that a global filepool that can span more than one session is used. useRmsJournal: Specifies whether or not RMS journalling is enabled when the SET FILE/RU_JOURNAL command is issued under OpenVMS. The SET FILE/RU_JOURNAL command marks an RMS file for recovery unit journalling. Any RMS table used in a Transaction where journalling applies must be defined with an index. This table lists the SQL statements that are used with RMS journalling and their OpenVMS equivalents.
Transaction Support
The RMS Data Source supports Two-phase Commit and can fully participate in a distributed Transaction when the transaction environment property convertAllToDistributed is set to true. You use RMS with its two-phase commit capability through an XA connection using the OpenVMS integrated DTM transaction processing manager.
Multiple concurrent transactions are not supported. Also refer to the useRmsJournal data source property described in Defining the RMS Data Source.
Data Types
This table shows how Attunity Connect maps data types in a CREATE TABLE statement to RMS data types:
Table 532 CREATE TABLE Data Types RMS Char[(m)] Date+time Double Float Integer Numeric(p,s) Smallint Tinyint Varchar(m)
CREATE TABLE Char[(m)] Date Double Float Image Integer Numeric[(p[,s])] Smallint Text Tinyint Varchar(m)
Defining the RMS Data Source Connection Configuring the RMS Data Source
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your RMS data source. Expand the Bindings folder. Expand the binding where you want to add the RMS data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select RMS from the Type list. Click Next. The Data Source Connect String screen is displayed.
Data Location: Enter the directory where the RMS files and indexes you create with CREATE TABLE and CREATE INDEX statements reside. You must specify the full path for the directory. If a value is not specified, created files are written to the DEF directory under the directory where AIS is installed. The value specified is used for the Data file field of the Design perspective, Metadata tab in Attunity Studio.
11. Click Finish.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your RMS data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the RMS data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the RMS Data Source Connection. Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties. After you set up the data source, you must define Attunity metadata describing the RMS data.
Setting Up the RMS Data Source Metadata with the Import Manager
The RMS data source requires Attunity Metadata. You can import the metadata from COBOL copybooks or CDD metadata. If COBOL copybooks or CDD metadata do not exist that describe the RMS records, the metadata must be manually defined. For more information of the metadata definition see Managing Data Source Metadata and Data Source Metadata Overview. If COBOL copybooks describing the data source records are available, you can import the metadata by running the metadata import in the Attunity Studio Design perspective, Metadata tab. If the metadata is provided in a number of COBOL copybooks, with different filter settings (such as whether the first 6 columns are ignored or not), first import the metadata from copybooks with the same settings, and then import the metadata from the other copybooks. COBOL copybooks are required for this import procedure. These copybooks are copied to the machine running Attunity Studio. This process has the following steps:
Applying Filters Selecting Tables Import Manipulation Metadata Model Selection Import the Metadata
In the Design perspective, Configuration view, right-click the data source and select Show Metadata View. The Metadata tab is displayed with the Data Source displayed in the Metadata view.
3. 4. 5.
Right-click Imports and select New Import. Enter a name for the import. The name can contain letters, numbers and the underscore character. Select one of the following import types.
6. 7.
Click Finish. The Metadata Import Wizard is displayed. Click Add in the Import Wizard to add COBOL copybooks. The Add Resource screen is displayed, providing the option of selecting files from the local machine or copying the files from another machine using FTP. The following figure shows the Add Resource screen.
8. 9.
If the files are on another machine, then right-click My FTP Sites and select Add. Set the FTP data connection by entering the server name where the COBOL copybooks reside and, if not using anonymous access, enter a valid username and password to access the Machine. using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory.
10. To browse and transfer files required to generate the metadata, access the machine
11. Select the files to import and click Finish to start the transfer.
The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns together with a COBOL copybook that ignores the first six columns. In this type of case, repeat the import process. You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks. The selected files are displayed in the Get Input Files screen of the wizard, as shown in the following figure.
Figure 533 Import Wizard
12. To manipulate table information or the fields in the table, right-click the table and
select the option you want. The following options are available:
Fields manipulation: Access the Fields Manipulation screen to customize the field definitions. Rename: Rename a table name. This option is used especially when more than one table is generated from the COBOL with the same name. Set data location: Set the physical location of the data file for the table.
Set table attributes: Set table attributes. The table attributes are described in Table Attributes. XSL manipulation location: Specify an XSL transformation or JDOM document that is used to transform the table definition.
Applying Filters
This section describes the steps required to apply filters on the COBOL Copybook files used to generate the Metadata. It continues the Selecting the Input Files step. To apply filters 1. Click Next, the Apply Filters step is displayed in the editor.
Figure 534 Apply Filters
2.
Apply filters to the copybooks, as needed. The following COBOL filters are available:
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type. Compiler source: The compiler vendor. Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks.
Prefix nested column: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity metadata, is replaced with an underscore. Case sensitive: Specifies whether to consider case sensitivity or not. Find: Searches for the specified value. Replace with: Replaces the value specified for in the Find field with the value specified here.
3.
Selecting Tables
This section describes the steps required to select the tables from the COBOL Copybooks. The following procedure continues the Applying Filters step.
1.
From the Select Tables screen, select the tables that you want to access. To select all tables, click Select All. To clear all the selected tables, click Unselect All. The following figure shows the Select Tables screen.
The import manager identifies the names of the records in the COBOL copybooks that will be imported as tables.
2.
Select the tables that you want to access (that require Attunity metadata) and then click Next to go to the Import Manipulation step.
Import Manipulation
This section describes the operations available for manipulating the imported records (tables). It continues the Selecting Tables step. The import manager identifies the names of the records in the DDM Declaration files that will be imported as tables. You can manipulate the general table data in the Import Manipulation Screen To manipulate the table metadata 1. From the Import Manipulation screen (see Import Manipulation Screen figure), right-click the table record marked with a validation error, and select the relevant operation. See the table, Table Manipulation Options for the available operations.
2.
Repeat step 1 for all table records marked with a validation error. You resolve the issues in the Import Manipulation Screen. Once all the validation error issues have been resolved, the Import Manipulation screen is displayed with no error indicators.
3.
The upper area of the screen lists the DDM Declaration files and their validation status. The metadata source and location are also listed. The Validation tab at the lower area of the screen displays information about what needs to be resolved in order to validate the tables and fields generated from the
COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location). The following operations are available in the Import Manipulation screen:
Resolving table names, where tables with the same name are generated from different files during the import. Selecting the physical location for the data. Selecting table attributes. Manipulating the fields generated from the COBOL, as follows: Merging sequential fields into one (for simple fields). Resolving variants by either marking a selector field or specifying that only one case of the variant is relevant. Adding, deleting, hiding, or renaming fields. Changing a data type. Setting the field size and scale. Changing the order of the fields. Setting a field as nullable. Selecting a counter field for array for fields with dimensions (arrays). You can select the array counter field from a list of potential fields. Setting column-wise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension. Creating arrays and setting the array dimension.
The following table lists and describes the available operations when you right-click a table entry:
Table 533 Option Fields Manipulation Table Manipulation Options Description Customizes the field definitions, using the Field Manipulation screen. You can also access this screen by double-clicking the required table record. Renames a table. This option is used especially when more than one table with the same name is generated from the COBOL. Sets the physical location of the data file for the table. Sets the table attributes. Specifies an XSL transformation or JDOM document that is used to transform the table definitions. Removes the table record.
Rename Set data location Set table attributes XSL manipulation Remove
You can manipulate the data in the table fields in the Field Manipulation Screen. Double-click a line in the Import Manipulation Screen to open the Field Manipulation Screen.
You can carry out all of the available tasks in this screen through the menu or toolbar. You can also right click anywhere in the screen and select any of the options available in the main menus from a shortcut menu. The following table describes the tasks that are done in this screen. If a toolbar button is available for a task, it is pictured in the table.
Table 534 Command General menu Undo Click to undo the last change made in the Field Manipulation screen. Field Manipulation Screen Commands Description
The offset of a field is usually calculated dynamically by the server at runtime according the offset and size of the proceeding column. Select this option to override this calculation and specify a fixed offset at design time. This can happen if there is a part of the buffer that you want to skip. When you select a fixed offset you pin the offset for that column. The indicated value is used at runtime for the column instead of a calculated value. Note that the offset of following columns that do not have a fixed offset are calculated from this fixed position.
Table 534 (Cont.) Field Manipulation Screen Commands Command Test import tables Description Select this table to create an SQL statement to test the import table. You can base the statement on the Full table or Selected columns. When you select this option, the following screen opens with an SQL statement based on the table or column entered at the bottom of the screen.
Data file name: Enter the name of the file that contains the data you want to query. Limit query results: Select this if you want to limit the results to a specified number of rows. Enter the amount of rows you want returned in the following field. 100 is the default value. Define Where Clause: Click Add to select a column to use in a Where clause. In the table below, you can add the operator, value and other information. Click on the columns to make the selections. To remove a Where Clause, select the row with the Where Clause you want t remove and then click Remove.
The resulting SQL statement with any Where Clauses that you added are displayed at the bottom of the screen. Click OK to send the query and test the table. Attribute menu Change data type Select Change data type from the Attribute menu to activate the Type column, or click on the Type column and select a new data type from the drop-down list.
Table 534 (Cont.) Field Manipulation Screen Commands Command Create array Description This command allows you to add an array dimension to the field. Select this command to open the Create Array screen.
Enter a number in the Array Dimension field and click OK to create the array for the column. Hide/Reveal field Select a row from the Field manipulation screen and select Hide field to hide the selected field from that row. If the field is hidden, you can select Reveal field. Select this to change or set a dimension for a field that has an array. Select Set dimension to open the Set Dimension screen. Edit the entry in the Array Dimension field and click OK to set the dimension for the selected array. Set field attribute Select a row to set or edit the attributes for the field in the row. Select Set field attribute to open the Field Attribute screen.
Set dimension
Click in the Value column for any of the properties listed and enter a new value or select a value from a drop-down list. Nullable/Not nullable Select Nullable to activate the Nullable column in the Field Manipulation screen. You can also click in the column. Select the check box to make the field Nullable. Clear the check box to make the field Not Nullable. Set scale Select this to activate the Scale column or click in the column and enter the number of places to display after the decimal point in a data type. Select this to activate the Size column or click in the column and enter the number of total number of characters for a data type.
Table 534 (Cont.) Field Manipulation Screen Commands Command Add Description Select this command or use the button to add a field to the table. If you select a row with a field (not a child of a field), you can add a child to that field. Select Add Field or Add Child to open the following screen:
Enter the name of the field or child, and click OK to add the field or child to the table. Delete field Select a row and then select Delete Field or click the Delete Field button to delete the field in the selected row.
Move up or down
Select a row and use the arrows to move it up or down in the list.
Select Rename field to make the Name field active. Change the name and then click outside of the field.
Select Columnwise Normalization to create new fields instead of the array field where the number of generated fields will be determined by the array dimension.
Table 534 (Cont.) Field Manipulation Screen Commands Command Combining sequential fields Description Select Combining sequential fields to combine two or more sequential fields into one simple field. The following dialog box opens:
First field name: Select the first field in the table to include in the combined field End field name: Select the last field to be included in the combined field. Make sure that the fields are sequential. Enter field name: Enter a name for the new combined field.
Flatten group
Select Flatten Group to flatten a field that is an array. This field must be defined as Group for its data type. When you flatten an array field, the entries in the array are spread into a new table, with each entry in its own field. The following screen provides options for flattening.
Select Recursive operation to repeat the flattening process on all levels. For example, if there are multiple child fields in this group, you can place the values for each field into the new table when you select this option. Select Use parent name as prefix to use the name of the parent field as a prefix when creating the new fields. For example, if the parent field is called Car Details and you have a child in the array called Color, when a new field is created in the flattening operation it will be called Car Details_Color.
Table 534 (Cont.) Field Manipulation Screen Commands Command Mark selector Description Select Mark selector to select the selector field for a variant. This is available only for variant data types. Select the Selector field form the following screen.
Select Replace variant to replace a variants selector field. Select Counter Field opens a screen where you select a field that is the counter for an array dimension.
Default values for all tables: Select this if you want to configure the same values for all the tables in the import. Make the following selections when using this option: Generate sequential view: Select this to map non-relational files to a single table. Generate virtual views: Select this to have individual tables created for each array in the non-relational file. Include row number column: Select one of the following: true: Select true, to include a column that specifies the row number in the virtual or sequential view. This is true for this table only, even in the the data source is not configured to include the row number column. false: Select false, to not include a column that specifies the row number in the virtual or sequential view for this table even if the data source is configured to include the row number column. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties. Inherit all parent columns: Select one of the following: true: Select true, for virtual views to include all the columns in the parent record. This is true for this table only, even in the data source is not configured to include all of the parent record columns. false: Select false, so virtual views do not include the columns in the parent record for this table even if the data source is configured to include all of the parent record columns. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties.
Specific virtual array view settings per table: Select this to set different values for each table in the import. This will override the data source default for that table. Make the selections in the table under this selection. See the item above for an explanation.
Click Finish.
Note:
Use double quotes (") to hold the position of a parameter when you do not specify its value and it is followed by a parameter whose value is specified. For example, $ CDD_ADL "" sales. Activation of this utility is based on environment symbols defined by the login file that resides in the BIN directory under the directory where AIS is installed. You can always replace the environment symbol with the appropriate entry.
where:
cdd_dir: The location of the CDD records record_spec: The set of records that you want converted. All CDD records matching record_spec in the specified CDD directory are converted. If you
want all the record information in the directory converted, do not specify a value for record_spec.
ds_name: The name of a data source defined in the binding. The imported metadata is stored as ADD metadata in the repository for this data source. filename_table: A text file containing a list of records and the names of their data files. Each row in this file has two entries: record_name and physical_ Cdd_data_file_name (which is used for the value for the Data file field for the table in the Design perspective, Metadata tab in Attunity Studio). If a table is not listed in this text file, the entry for the Data file field for the table defaults to table_FIL, where table is the name of the table. If this text file does not exist, the names for the Data file field specifying the tables default to table_FIL, where table is the name of the table. The text file specified in this parameter contains entries similar to the following: on OpenVMS Platforms:
orders us5:[attunity.acme]orders.inx purchase us5:[attunity.acme]purchase.inx
Note:
In cases where the filename defaults to table_FIL, the filename must be changed to the correct name in order to access the data. This is done using the Design perspective, Metadata tab of Attunity Studio, or NAV_UTIL EDIT.
CDD/Plus_version_majorThe CDD/Plus version major, which determines the separator between the record_name and version_number in the output CDD records, and the repository metadata format. The values available for this parameter are:
0: Specifies that the metadata is in DMU format and the semicolon (;) is the separator between record name and version number. 4: Specifies that the metadata is in CDO format and the semicolon (;) is the separator between record name and version number. x (anything else, or blank): Specifies that the metadata is in CDO format and the open parenthesis ( is the separator between record name and version number.
If you are using a version of CDD prior to V4.0, specify "0" (since CDO format was introduced in version 4.0).
basename: Specifies the user-defined name of the intermediate files used during the import operation. Options: Enables you to specify the following options:
d: Specifies that all intermediate files are saved. You can check these files if problems occur in the conversion. c: Specifies that the column name is used for an array name, instead of the concatenation of the parent table name with the child table name. If a column name is not unique in a structure (as when a structure includes another structure, which contains a column with the same name as a column in the parent structure), the nested column name is suffixed with the nested structure name.
Example
$ CDD_ADL cdd$top.personnel sales rmsdemo
To display online help for this utility, run the command with help as the only parameter: ADDIMP -i.
54
SQL Server Data Source (Windows Only)
This section includes the following topics:
Overview Supported Versions and Platforms Configuration Properties Transaction Support Data Types Defining an SQL Server Data Source
Overview
Attunity provides an ODBC-based SQL Server driver. In Attunity Studio, this driver appears as SQL Server; in the binding configuration, it appears as MSSQLODBC. The SQL Server driver is supported for existing applications that use it.
Note:
The SQL Server driver requires an SQL Server connection per SQL statement. This can cause problems when you work with multiple data sources referencing more than a single SQL Server database or when you work with Microsofts InterDev application (since it issues an SQL_CONNECT command every time it executes a query). You can use the SQL Server Enterprise Manager to increase the number of available connections.
Table names in SQL Server must be less than or equal to 64 characters to be usable.
The security information required to access SQL Server is taken from the machine where AIS and SQL Server are installed. The drivers support:
For information on supported SQL Server versions, see Attunity Integration Suite Supported Systems and Resources.
Configuration Properties
The following properties can be configured for the SQL Server data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
ansiNull: This parameter specifies whether or not the treatment of NULLs is compliant with the ANSI standard. The default is true. cursorMode: The cursor type that is used. Select one of the following modes: clientMultipleConnections: This lets you work with client-side cursors with multiple connections. serverMultipleConnections: This lets you work with server-side cursors with multiple connections. clientSingleConnection: This lets you work with client-side cursors with a single connection. serverSingleConnection: This lets you work with client-side cursors with a single connection. marsConnection: This lets you work with multiple access result sets.
isolationLevel: This parameter specifies the default isolation level for the data source, as follows: readUncommitted: This value specifies that corrupt data is not to be read. This is the lowest isolation level. readCommitted: This value specifies that only the data committed before the query began is displayed. serializable: This value specifies that the data is isolated serially. Treats data as if transactions are executed sequentially. repeatableRead: This value specifies that data used in a query is locked and cannot be used by another query nor updated by another transaction.
Note:
If the selected level is not supported by the data source, then the next highest level is used.
NumericNullable: This parameter specifies that a numeric field can receive null values. timeout: This parameter specifies the timeout on any SQL Server API call, via the dbsettime API. values.
Transaction Support
The SQL Server drivers support two-phase commit and can fully participate in a distributed transaction when the transaction environment parameter convertAllToDistributed is set to true. You can use SQL Server with its two-phase commit capability both under MTS, and directly through an XA connection. In both cases, Microsoft DTC must be running on the server. If you are working under MTS, start an OLE transaction. The SQL Server data source is automatically included in the distributed transaction. If the connection to the data is through an XA connection, the connection is made automatically. The daemon server mode must be configured to Single-client mode (see Server Mode). To use distributed transactions from an ODBC-based application, ensure that AUTOCOMMIT is set to 0.
Data Types
This table shows how Attunity Connect maps SQL Server data types to OLE DB and ODBC data types.
Table 541 SQL Server Binary Bit Char(m<256) Char(m>255) Datetime Decimal Float Image Integer Money Nchar Ntext Numeric Nvarchar Real Small Datetime Small Int Small Money Text Timestamp TinyInt Mapping SQL Server Data Types OLE DB DBTYPE_BYTES DBTYPE_I2 DBTYPE_STR DBTYPE_STR DBTYPE_DBTIMESTAMP DBTYPE_NUMERIC DBTYPE_R8 DBTYPE_BYTES DBTYPE_I4 DBTYPE_NUMERIC DBTYPE-STR DBTYPE-STR DBTYPE_NUMERIC DBTYPE-STR DBTYPE_R4 DBTYPE_DBTIMESTAMP DBTYPE_I2 DBTYPE_numeric DBTYPE-STR DBTYPE_BYTES DBTYPE_I2 ODBC SQL_BINARY SQL_TINYINT SQL_CHAR SQL_LONGVARCHAR1 SQL_TIMESTAMP SQL_NUMERIC SQL_DOUBLE SQL_LONGVARBINARY SQL_INTEGER SQL_NUMERIC(19,4) SQL_VARCHAR SQL_LONGVARCHAR1 SQL_NUMERIC SQL_VARCHAR SQL_REAL SQL_TIMESTAMP SQL_SMALLINT SQL_NUMERIC(10,4) SQL_LONGVARCHAR1 SQL_BINARY SQL_TINYINT
Table 541 (Cont.) Mapping SQL Server Data Types SQL Server Varbinary Varchar(m<256) Varchar(m>255) OLE DB DBTYPE_BYTES DBTYPE-STR DBTYPE-STR ODBC SQL_BINARY SQL_VARCHAR SQL_LONGVARCHAR1
Note:
1.
Precision of 2147483647.If the <odbc longVarcharLenAsBlob> parameter is set to true in the AIS environment settings, then precision of m. Supported by the SQL Server (ODBC) or MSSQLODBC driver. The column definition is returned as varchar(255) and the data is truncated to 255 characters.
2. 3.
This table shows how Attunity Connect maps data types in a CREATE TABLE statement to SQL Server data types.
Table 542 CREATE TABLE Data Types SQL Server Raw Char[(m)] Datetime Float Real Image Binary(m) Integer Float Numeric(p,s) Smallint Text Datetime Datetime Tinyint Varchar(m)
CREATE TABLE Binary Char[(m)] Date Double Float Image Image (m) Integer Numeric Numeric(p[,s]) Smallint Text Time Timestamp Tinyint Varchar(m)
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your SQL Server data source. Expand the Bindings folder. Expand the binding where you want to add the SQL Server data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select SQL Server from the Type list. Click Next. The Data Source Connect String screen is displayed.
SQL Server name: Enter the name of the server machine for the SQL Server data. Database name: Enter the name of the database.
Note:
If you enter the Database name only, without the Server name, the driver uses the following subtree of the Windows registry:
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your SQL Server data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder.
SQL Server Data Source (Windows Only) 54-5
6.
Right-click the SQL Server data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the SQL Server Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
55
SQL/MP Data Source (HP NonStop Only)
This section contains the following topics:
Overview Functionality Configuration Properties Transaction Support Data Types Defining the SQL/MP Data Source
Overview
The SQL/MP and Enscribe data sources and Pathway adapter share the same transaction, which automatically provides consistency between Enscribe and SQL/MP. As a result, you cannot start a new transaction for Enscribe when one is open for SQL/MP.
Note:
When specifying a passthru query to SQL/MP, if the query is not within a transaction, you must include the words BROWSE ACCESS at the end of the query. Fully qualified table names in non-returning rowsets (such as UPDATE, INSERT, DELETE and DDL statements) must be delimited by quotes ().
The SQL/MP driver uses the maxSqlCache parameter, which is set in the queryProcessor category of the binding environment. In addition to the Query Processor cache, the SQL/MP driver also caches SQL/MP queries for reuse. For details of the Query Processor parameter, see the queryProcessor category in Environment Properties.
Limitations
If you are using view with a Left Outer Join, note that a Left Outer Join cannot contain multuple tables ar a view. Functions are not supported in SQL/MP, therefore there is no delegation for queries that have functions in the select list.
55-1
Functionality
This section describes the following aspects of SQL/MP functionality:
Mapping SQL/MP Table Names SQL/MP Primary Keys Partitioned Tables Transaction Support Isolation Levels and Locking
For example:
a1 = \mach1.$D3018.sqlmp.emp
Since SQL tables always have a primary key (either user defined or SYSKEY), a unique index is always defined. The SQL/MP driver always generates table bookmarks consisting of the fields of the first unique index, thereby guaranteeing the uniqueness of the bookmark.
Partitioned Tables
You can create SQL/MP tables that are partitioned. The first (head) partition is always the partition with the lowest key range. Different partitions of one table can be registered in different catalogs the only restriction being that a partition must be registered in a catalog of the same system as the partition itself.
In handling partitioned tables, you follow standard SQL/MP behavior. This includes the ability to refer to any one of the partitions and not necessarily to the head partition. For example, when an SQL/MP database has more than one partitioned table with the same table name, for the first table you use the short name and for the other tables you use the full path name of any one of the partitions. (Attunity Connect refers to the full path name by dropping the $ prefix and replacing the periods with underscores, as in volume_subvolume_tablename.) For information about defining an alias for the full path name, see Mapping SQL/MP Table Names. Example The following example creates a new SQL/MP catalog in $D0117.partcat anda table $DSMSCM.orders.ODETAIL that consists of two partitions. $DSMSCM.orders.ODETAIL is the first (head) partition and $D0117.orders.ODETAIL is the second partition.
CREATE TABLE $DSMSCM.orders.ODETAIL ORDERNUM NUMERIC (6) UNSIGNED NO DEFAULT NOT NULL, PARTNUM NUMERIC (4) UNSIGNED NO DEFAULT NOT NULL, UNIT_PRICE NUMERIC (8,2) NO DEFAULT NOT NULL, QTY_ORDERED NUMERIC (5) UNSIGNED NO DEFAULT NOT NULL, PRIMARY KEY ( ORDERNUM, PARTNUM ) ) CATALOG $D0117.partcat ORGANIZATION KEY SEQUENCED PARTITION $D0117.orders.ODETAIL CATALOG $D0117.partcat EXTENT (16368,64) MAXEXTENTS 650 FIRST KEY 450000 ) EXTENT (16368,64) MAXEXTENTS 650 BUFFERED NO AUDIT;
The isolation levels supported can be overwritten in the binding settings. This table lists the SQL/MP isolation levels for the IsolationLevel attribute.
Table 551 Isolation Level Attributes Equivalent SQL/MP Isolation Level BROWSE ACCESS STABLE ACCESS REPEATABLE ACCESS REPEATABLE ACCESS
55-3
To change the isolation level, set the data source isolation level field to the desired isolation level. Once the isolation level is changed all statements sent to SQL/MP are sent with the corresponding SQL/MP isolation level, if under a transaction or not. When setting SQL/MP isolation level to either REPEATABLE ACCESS or STABLE ACCESS, a transaction must be started explicitly. Otherwise SQL/MP returns the following error:
8312 The statement cannot be executed because no TMF transaction is currently in progress. The error was detected for value-1.
The isolation level is used only within a Transaction. The SQL/MP data source supports locking of the single row in the database table. SELECT statements are performed with BROWSE ACCESS, so there is no wait for the data to be unlocked by another application.
Configuration Properties
The following properties can be configured for the SQL/MP data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect=true|false: When set to true, this parameter disables the explicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. isolationLevel=value: This parameter specifies the default isolation level for the data source, as follows: readUncommitted: This value specifies that corrupt data is not to be read. This is the lowest isolation level. readCommitted: This value specifies that only the data committed before the query began is displayed. repeatableRead: This value specifies that data used in a query is locked and cannot be used by another query nor updated by another transaction. serializable: This value specifies that the data is isolated serially. Treats data as if transactions are executed sequentially.
Note:
If the specified level is not supported by the data source, then Attunity Connect defaults to the next highest level.
statementCacheSize=value: This parameter specifies the maximum number of SQL statements that are cached. The default value is 6.
Transaction Support
The SQL/MP driver supports one-phase commit. It can participate in a distributed transaction if it is the only one-phase commit data source being updated in the Transaction.
Note:
Both the transaction environment properties convertAllToDistributed and useCommitConfirmTable must be set to true.
If Using Attunity Connect as a Stand-alone Transaction Coordinator is necessary, in the Configuration Properties, set convertAllToDistributed to TRUE If you want to use SQLMP as one-phase commit data source participating in a Two-phase Commit distributed transaction, in the Configuration Properties, set useCommitConfirmTable to TRUE Other than the above conditions, do not set either of the above-mentioned parameters to TRUE.
Data Types
This table shows how Attunity Connect maps SQL/MP data types to OLE DB and ODBC data types.
Table 552 SQL/MP Char(m<256) Char(m>255) Date Datetime year to day Datetime year to minue Datetime year to fraction Double Precision Float Integer Large Integer Numeric (x,y) Real Small Integer Time Timestampt Varchar(m<256) Varchar(m>255) Mapping SQL/MP Data Types OLE DB DBTYPE_STR DBTYPE_STR DBTYPE_DBTIME DBTYPE_DBTIMESTAMP DBTYPE_DBTIMESTAMP DBTYPE_DBTIMESTAMP DBTYPE_R8 DBTYPE_R4 DBTYPE_I4 DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_R4 DBTYPE_I2 DBTYPE_DBTIME DBTYPE_DBTIMESTAMP DBTYPE_STR DBTYPE_STR ODBC SQL_CHAR SQL_LONGVARCHAR1 SQL_DATE SQL_TIMESTAMP SQL_TIMESTAMP SQL_TIMESTAMP SQL_DOUBLE SQL_REAL SQL_INTEGER SQL_NUMERIC SQL_NUMERIC SQL_REAL SQL_SMALLINT SQL_TIME SQL_TIMESTAMP SQL_CHAR SQL_LONGVARCHAR1
Note: 1. Precision of 2147483647.If the <odbc longVarcharLenAsBlob> parameter is set to true in the AIS environment settings, then precision of m.
55-5
Other SQL/MP data types (such as Interval and Multibyte string) are not supported. When retrieving a table that includes columns with unsupported data types, only columns with supported data types are retrieved correctly in all circumstances. This table shows how Attunity Connect maps data types in a CREATE TABLE statement to SQL/MP data types.
Table 553 CREATE TABLE Data Types SQL/MP Char[(m)] Date Float Real Integer signed Float Numeric(p) Numeric(s) Smallint signed Text Time Datetime year to fraction Smallint signed Varchar(m)
CREATE TABLE Binary Char[(m)] Date Double Float Image Integer Numeric Numeric(p) Numeric(s) Smallint Text Time Timestamp Tinyint Varchar(m)
Defining the SQL/MP Data Source Connection Configuring the SQL/MP Data Source Properties
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your SQL/MP data source. Expand the Bindings folder. Expand the binding where you want to add the SQL/MP data source.
6.
Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7.
In the Name field, enter a name for the new data source.
Note:
If you use a local copy of the metadata or extended metadata, the data source name must begin with a letter. In addition, if you do not supply the Repository Information on the Advanced tab of the Data Source editor, the default names that AIS generates for the metadata files will be unique. AIS creates a NOS file and a BBNOS file. The file names are created by using the characters in the data source name and then by ensuring that the first letter is legal on the HP NonStop platform. To make sure that the generated files are unique, you must make the sixth through eighth alphanumeric characters of the data source name alphabetic and unique. If the data source name contains fewer than eight alphanumeric characters, the last three alphanumeric characters must be alphabetic and unique. If the data source name contains five or more alphanumeric characters, the last five cannot all be the letter B. If you enter the Repository Information on the Advanced tab of the Data source editor, make sure that you use the rule above for the filenames created by the Repository directory (HP NonStop volume/subvolume) and name, not the data source name.
8. 9.
Select SQL/MP from the Type list. Click Next. The Data Source Connect String screen is displayed.
Catalog name: Specify the subvolume used as the default catalog for new tables.
11. Click Finish.
Open Attunity Studio. In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your SQL/MP data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the SQL/MP data source and select Open. The Configuration editor is displayed.
55-7
7. 8. 9.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the SQL/MP Data Source Connection. Configure the driver parameters as required. For a description of the available parameters, see Configuration Properties Click Finish.
56
Sybase Data Source
This section contains the following topics:
Overview Supported Versions and Platforms Functionality Configuration Properties Transaction Support Data Types Platform-Specific Information Defining the Sybase Data Source
Overview
The following sections provide information about defining and configuring the Sybase Data Source. This includes information regarding the Metadata that must be defined.
Functionality
This section describes the following aspects of Sybase functionality.
Stored Procedures
The Sybase data source driver supports Sybase stored procedures functions, including procedures that return multiple result sets. To retrieve output parameters, multiple result sets, and the return code from the stored procedure, use the ? = CALL syntax.
The isolation level is used only within a transaction. Sybase supports page level locking. Updates in Sybase are blocking, i.e. if another connection tries to access a locked record, AIS is locked. Update Semantics For tables with no bookmark or other unique index, the data source driver returns a combination of most (or all) of the columns of the rows as a bookmark. The driver does not guarantee the uniqueness of this bookmark; you must ensure that the combination of columns is unique.
Configuration Properties
The following properties can be configured for the Sybase data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
ansiNull: This parameter determines whether or not the treatment of NULLs is compliant with the ANSI standard. The default setting is true. chained: This parameter determines whether or not the Sybase transaction mode is set to chained transactions. This is equivalent to the Sybase command set chained on. The default setting is false. cursorRows: This parameter specifies the number of rows retrieved in a read-ahead buffer. This value controls the CS_CURSOR_ROWS parameter in the Sybase OpenClient CTLIB. If n is negative, the number of rows read at one time is the number that will fill the buffer. If n is 0, read-ahead is disabled. dbName: The Database name in the connect string, this parameter specifies the name of the database. If you omit the Database name, the data source driver binds to the default Sybase database. disableCursors: This parameter specifies whether or not CTLIB cursors are used. When set to true, performance of retrieval-based queries is improved. However, parameters and BLOBs cannot be used in the queries and only one open statement can be used. The setting is ignored if the query is included in a started transaction. The default setting is false. interfaceFile: The Interface file in the connect string, this parameter specifies the full path and name of a Sybase interface file. If you omit the interface file, the default Sybase interface file is used. isolationLevel=value: This parameter specifies the default isolation level for the data source, as follows: readUncommitted: This value specifies that corrupt data is not to be read. This is the lowest isolation level. readCommitted: This value specifies that only the data committed before the query began is displayed.
repeatableRead: This value specifies that data used in a query is locked and cannot be used by another query nor updated by another transaction. serializable: This value specifies that the data is isolated serially. Treats data as if transactions are executed sequentially.
Note:
If the specified level is not supported by the Data Source, then Attunity Connect defaults to the next highest level.
packetSize: This parameter specifies the size of a Sybase packet. Valid values are 1 to n, where n is the number of units for the packet. Each unit is 512 bytes. parmWithAt: This parameter specifies whether or not all parameters in Sybase stored procedures begin with the symbol @. The default setting is false.
Transaction Support
The Sybase Data Source supports one-phase commit. It can participate in a distributed Transaction if it is the only one-phase commit data source being updated in the transaction.
Note:
Both the transaction environment properties convertAllToDistributed and useCommitConfirmTable must be set to true.
Data Types
This shows how Attunity Connect maps Sybase data types to OLE DB and ODBC data types.
Table 561 Sybase Bit Binary Char(m<255) Char(m>255) Datetime Decimal Double Precision Float Image Integer Money Numeric Mapping Sybase Data Types OLE DB DBTYPE_I2 DBTYPE_BYTES DBTYPE_STR DBTYPE_STR DBTYPE_DBTIMESTAMP DBTYPE_numeric DBTYPE_R4 DBTYPE_R8 DBTYPE_BYTES DBTYPE_I4 DBTYPE_numeric DBTYPE_numeric ODBC SQL_TINYINT SQL_BINARY SQL_CHAR SQL_LONGVARCHAR1 SQL_TIMESTAMP SQL_NUMERIC SQL_REAL SQL_DOUBLE SQL_LONGVARBINARY SQL_INTEGER SQL_NUMERIC(19,4) SQL_NUMERIC
Table 561 (Cont.) Mapping Sybase Data Types Sybase Real Small Datetime Small Int Small Money Text TinyInt Varbinary Varchar(m<256) Varchar(m>255) OLE DB DBTYPE_R4 DBTYPE_DBTIMESTAMP DBTYPE_I2 DBTYPE_numeric DBTYPE_BYTES DBTYPE_I2 DBTYPE_BYTES DBTYPE_STR DBTYPE_STR ODBC SQL_REAL SQL_TIMESTAMP SQL_SMALLINT SQL_NUMERIC(10,4) SQL_LONGVARCHAR SQL_SMALLINT SQL_BINARY SQL_CHAR SQL_VLONGVARCHAR1
Note: 1. Precision of 2147483647.If the <odbc longVarcharLenAsBlob> parameter is set to true in the AIS environment settings, then precision of m.
This table shows how Attunity Connect maps data types in a CREATE TABLE statement to Sybase data types.
Table 562 CREATE TABLE Data Types Sybase Raw Char[(m)] Datetime Float Real Image Binary(m) Integer Float Numeric(p,s) Smallint Text Datetime Datetime Tinyint Varchar(m)
CREATE TABLE Binary Char[(m)] Date Double Float Image Image(m) Integer Numeric Numeric(p[,s]) Smallint Text Time Timestamp Tinyint Varchar(m)
Platform-Specific Information
This section includes Sybase-related information and procedures as they pertain to specific platforms, as follows:
For Sybase version 12.5, rename the nvdb_syb125.so file to nvdb_syb.so. For Sybase version 15, rename the nvdb_syb150.so file to nvdb_syb.so.
Defining the Sybase Data Source Connection Configuring the Sybase Data Source Properties Checking Sybase Environment Variables
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your Sybase data source. Expand the Bindings folder. Expand the binding where you want to add the Sybase data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select Sybase from the Type list. Click Next. The Data Source Connect String screen is displayed.
Server name: Enter the name of the Sybase Server. If you omit the Server name, the data source driver binds to Sybases default server as specified in the Sybase interface file.
Sybase Data Source 56-5
Database name: Enter the name of the database. If you omit the Database name, the data source driver binds to Sybases default database as specified in the Sybase interface file.
Note:
The entries for both the Server name and Database name fields are case sensitive.
Interface file: Enter the full path and name of a Sybase interface file. If you omit the interface file, the default Sybase interface file is used.
Note: To access Sybase on 64 bit operating systems (HP-UX 11 and above, AIX 4.4 and above and Sun Solaris 2.8 and above), the data source 32 bit client must be used.
Open Attunity Studio. In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Sybase data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the Sybase data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Sybase Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties
operating system. For UNIX specific instructions, refer to Verifying Environment Variables on UNIX Platforms.
57
Text Delimited File Data Source
This section contains the following topics:
Overview Configuration Properties Defining the Text Delimited File Data Source Setting Up the Text Delimited Data Source Metadata
Overview
Text files are called text delimited when:
The text fields are delimited by a specified character Rows are delimited by new lines
Features
The Text Delimited File data source supports the following key feature:
Variable length records. The data source handles files larger than 2GB on UNIX platforms only.
The Text Delimited File data source does not support the following SQL statements:
Limitations
The Text Delimited File data source does not support transactions.
Configuration Properties
The following properties can be configured for the Text Delimited data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
disableExplicitSelect: When true, this parameter disables the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. headerRows=n: This parameter specifies the number of lines to be skipped at the beginning of each file.
Note:
newFileLocation: The Data directory in the connect string, this parameter specifies the location of the text-delimited files and indexes you create with CREATE TABLE statements. You must specify the full path for the directory.
Defining the Text Delimited File Data Source Connection Configuring the Text Delimited File Data Source
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your Text Delimited data source. Expand the Bindings folder. Expand the binding where you want to add the Text Delimited data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7. 8. 9.
In the Name field, enter a name for the new data source. Select Delimited Text Files from the Type list. Click Next. The Data Source Connect String screen is displayed.
Data Location: Enter the directory where the Text Delimited files and indexes you create with CREATE TABLE statements reside. You must specify the full path for the directory. If a value is not specified, created files are written to the DEF directory under the directory where AIS is installed. The value specified is used for the Data file field of the Design perspective, Metadata tab of Attunity Studio.
11. Click Finish.
To configure the Text Delimited File data source 1. Open Attunity Studio.
2. 3. 4. 5. 6.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Text Delimited data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the Text Delimited data source and select Open. The Configuration editor is displayed.
7. 8. 9.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Text Delimited File Data Source Connection. Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties. Click Finish. After you define the data source, you must define Attunity metadata describing the Text Delimited File data.
If COBOL copybooks do not exist that describe the Text Delimited File records, the metadata must be manually defined. For more information about the metadata definition, see Managing Data Source Metadata. This section includes the following topics:
Right-click Imports under the data source and select New Import. Enter a name for the import. The name can contain letters, numbers and the underscore character. Select COBOL Import Manager for Data Sources as the import type. Click Finish. The Metadata Import Wizard is displayed. Click Add in the Import Wizard to add COBOL copybooks. The Add Resource screen is displayed, providing the option of selecting files from the local machine or copying the files from another machine using FTP.
7. 8.
If the files are on another machine, then right-click My FTP Sites and select Add. Set the FTP data connection by entering the server name where the COBOL copybooks reside and, if not using anonymous access, enter a valid username and password to access the machine. To browse and transfer files required to generate the metadata, access the machine using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory.
9.
10. Select the files to import and click Finish to start the transfer.
The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns together with a COBOL copybook that ignores the first six columns. In this type of case, repeat the import process. You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks.
The selected files are displayed in the Get Input Files screen of the wizard, as shown in this figure.
Figure 573 Import Wizard
11. Click Next. The Apply Filters screen is displayed. Figure 574 Apply Filters Screen
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type. Compiler source: The compiler vendor.
Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Prefix nested column: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity metadata, is replaced with an underscore. Case sensitive: Specifies whether to consider case sensitivity or not. Find: Searches for the specified value. Replace with: Replaces the value specified for in the Find field with the value specified here.
13. Click Next. The Select Tables screen is displayed. Figure 575 Select Tables Screen
The import manager identifies the names of the records in the COBOL copybooks that will be imported as tables.
14. Select the tables that you want to access (and thus require Attunity Metadata) and
You can perform the following actions in the Import Manipulation screen:
Resolve table names, where tables with the same name are generated from different COBOL copybooks specified during the import. Specify the physical location for the data. Specify table attributes. Manipulate the fields generated from the COBOL, as follows: * * * * * * * * * * * Merge sequential fields into one for simple fields Resolve variants either by marking a selector field or by specifying that only one case of the variant is relevant Add, delete, hide, or rename fields Change a data type Set a field size and scale Change the order of the fields Set a field as nullable Select a counter field for array for fields with dimensions (arrays) Set column wise normalization for fields with dimensions (arrays) Create new fields instead of the array field, where the number of generated fields will be determined by the array dimension. Create arrays and set the array dimension.
The Validation tab in the bottom half of the screen displays information about what must be done to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location).
15. To manipulate table information or the fields in the table, right-click the table and
select the option you want. The following options are available:
Fields manipulation: Access the Fields Manipulation screen to customize the field definitions. Rename: Rename a table name. This option is used especially when more than one table is generated from the COBOL with the same name. Set data location: Set the physical location of the data file for the table. Set table attributes: Set table attributes. The table attributes are described in Managing Metadata. XSL manipulation location: Specify an XSL transformation or JDOM document that is used to transform the table definition.
The final window enables you to import the metadata to the machine where the data source is located or leave the generated metadata on the Attunity Studio machine, to be imported later.
17. Specify that you want to transfer the metadata to the machine where the data
source is located and click Finish. The metadata is imported to the machine where the data source is located.
58
Virtual Data Source
This section contains the following topics:
Overview
Attunity Connect includes a data source driver enabling you to access AIS proprietary data sources. These data sources are accessed using the Virtual data source driver. You can use a Virtual data source to store the following in a location other than the default SYS data source:
The following statement, for example, creates a view on Oracle data and stores it in a Virtual data source named oraviews (rather than in the default SYS Virtual data source):
create view oraviews:emps as select * from ora:employees_us,ora:employees_uk
Configuration Properties
The following properties can be configured for the Virtual data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Data Sources.
audit: Activates an audit file. This property must be set when including a Virtual data source in a distributed Transaction.
Note:
on HP (Compaq) NonStop platforms, the volume must be audited in order to create audited files.
auditFile: The audit filename is the concatenation of the value specified for the name attribute of the <table> statement and an.aud suffix.
disableExplicitSelect: When set to true, this parameter disables the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. filepoolCloseOnTransaction: This parameter specifies that all files in the file pool for this data source close at each end of transaction (commit or rollback). filepoolSize: This parameter specifies how many instances of a file from the file pool may be open concurrently. filepoolSizePerFile=n: This parameter specifies how many instances of a file from the file pool may be open concurrently for each file. lockWait: This parameter specifies whether the data source driver waits for a locked record to become unlocked or returns a message that the record is locked. maxSecondsLockingWait: This parameter specifies the maximum amount of time (in seconds) to wait before a locked record becomes unlocked or returns a message that the record is locked. newFileLocation: The Data location in the connect string, this parameter specifies the location where the views and stored procedure definitions reside. The connect attribute is optional. You must specify the full path for the directory. transactionLogFile: This parameter specifies the name of the file where the transaction log is written. transactions: This parameter specifies whether to start the TMF transactions. Use this property when dealing with unaudited files. useGlobalFilepool: This parameter specifies whether a global file pool that can span more than one session is used.
HP NonStop Platforms
The following parameters are unique to HP NonStop platforms:
enscribeLockMode=read|write: This parameter specifies the lock mode as either read only or writable. enscribeLockType=value: This parameter specifies the LockType property of the Recordset object:
adLockOptimistic: Optimistic locking. adLockBatchOptimistic: Optimistic batch updates. Required for batch update mode as opposed to immediate update mode.
newFileVolume=string: The Data disk in the connect string, this parameter specifies the file volume where the file is catalogued.
z/OS Platforms
The following parameters are unique to z/OS systems:
newFileSMSDataClass: This parameter specifies the data class where views and stored procedure definitions reside. newFileSMSStorageClass: This parameter specifies the storage class where views and stored procedure definitions reside.
OpenVMS Platforms
The following parameter is unique to OpenVMS platforms: useRmsJournal: This parameter specifies enables the use of RMS journaling, when SET FILE/RU_JOURNAL is issued under OpenVMS. The SET FILE/RU_JOURNAL OpenVMS command marks an RMS file for recovery unit journaling. Any RMS table used in a Transaction where journaling applies must be defined with an index. The following SQL statements are used with RMS journaling, with their OpenVMS equivalents:
Defining the Virtual Data Source Connection Configuring the Virtual Data Source
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your Virtual data source. Expand the Bindings folder. Expand the binding where you want to add the Virtual data source. Right-click the Data Source folder and select New Data Source.
Select Virtual from the Type list. Click Next. The Data Source Connect String screen is displayed.
9.
Data location: Specify the full path for the directory where the views and stored procedure definitions reside. If a value is not specified, the views and stored procedures are stored in data source files in the DEF directory under the directory where AIS is installed.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Virtual data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the Virtual data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Virtual Data Source Connection. Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties. After setting the binding, you must define Attunity Metadata.
59
VSAM Data Source (z/OS)
This section includes the following topics:
Overview Configuration Properties Metadata Transaction Support Data Types Defining a VSAM Data Source Setting Up the VSAM Data Source Metadata
Overview
Attunity Connect supports two types of VSAM data sources:
VSAM (CICS): The VSAM under CICS data source accesses VSAM by making EXCI calls to a CICS program provided as part of the AIS installation. This agent CICS program does the actual VSAM reads and writes from within CICS. When accessing VSAM data using this data source, the following restrictions apply:
SQL DELETE operations are not supported for ESDS files. Using an alternate index to access an ESDS file is not supported. A non-unique alternate index for a KSDS file is not supported.
VSAM: This data source connects directly to the VSAM data and is limited if the VSAM files are managed by CICS. In this case, it is recommended to use this data source for read-only access to VSAM files. However, this may not give you adequate read integrity if some changes are buffered by CICS. Another alternative is to use the VSAM under CICS data source. When accessing VSAM data using the VSAM data source, the following restrictions apply:
Transactions are not supported when accessing VSAM directly. When accessing VSAM under CICS, two-phase commit transactions are supported.
Locking is not supported. You cannot update an array value (a child record in a hierarchical table) when the parent record is included in the SQL in a subquery. SQL DELETE operations are not supported for ESDS files.
An RRDS file cannot have an alternate index. The primary key of a KSDS file must be one segment only (however, it can be several consecutive fields). You cannot modify the primary key value of a KSDS file. To enable you to create and delete VSAM data under z/OS, submit the following JCL: // IDCSYSIN DD DSN=&&VSAM,DISP=(NEW,DELETE,DELETE), // SPACE=(TRK,(1)),UNIT=SYSDA, // DCB=(BLKSIZE=3200,LRECL=80,RECFM=FB)
Environmental Prerequisites
AIS uses EXCI to interface to CICS. EXCI requires some set up:
IRC must be open. Use CEMT I IRC from the CICS screen to check your IRC status. If in closed state, set it to open. A specific connection must be set up. Use CEMT I connection to get the list of available connections. Note that you can only use specific connections which have a VTAM netname associated with them. The default available on most systems is BATCHCLI. Attunity provides a JCL for defining an Attunity connection. See the CICS CONF member in the USERLIB. An EXCI mirror transaction ID must be available. The default on most systems is transaction ID EXCI. You can use the CEMT I TRA PROG(DFHMIRS) to get the list of EXCI transaction IDs available on your system.
Configuration Properties
This section includes the following topics:
disableExplicitSelect: When set to true, this parameter disables the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. filepoolCloseOnTransaction: This parameter specifies that all files in the file pool for this data source close at each end of transaction (commit or rollback). filepoolSize: This parameter specifies how many instances of a file from the file pool may be open concurrently. newFileSMSStorageClass: This parameter specifies the storage class when SMS is used to manage volumes.
newFileSMSDataClass: This parameter specifies the data class when SMS is used to manage volumes. trigger: A name of a user defined trigger or user exit that can be setup. User code is activated on specific events like PRE-UPDATE, POST-READ etc. Triggers are normally used for either compression/decompression code or advanced logic for filtering. The the Attunity SDK book for further information. useGlobalFilepool: This parameter specifies whether or not a global file pool that can span more than one session is used.
allowUpdateKey: When set to true, this parameter specifies that the key is updatable. cicsProgname: The ProgramName in the connect string, this parameter specifies the UPDTRNS program that is supplied with AIS to enable updating VSAM data. cicsTraceQueue: The TraceQueue in the connect string, this parameter indicates the name of queue for output that is defined under CICS when tracing the output of the UPDTRNS program. When not defined, the default CICS queue is used. disableExplicitSelect: When set to true, this parameter disables the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. trigger: A name of a user defined trigger or user exit that can be setup. User code is activated on specific events like PRE-UPDATE, POST-READ etc. Triggers are normally used for either compression/decompression code or advanced logic for filtering. The the Attunity SDK book for further information. exciTransid=string: The Transaction ID in the connect string, this parameter indicates the CICS TRANSID. This value must be EXCI or a copy of this transaction. targetSystemApplid=string: The CICS Application ID in the connect string, this parameter specifies the VTAM applid of the CICS target system. vtamNetname=string: The VTAM Netname in the connect string, this parameter specifies the connection being used by EXCI (and MRO) to relay the program call to the CICS target system.
Metadata
The VSAM and VSAM (CICS) data source drivers require Attunity metadata. COBOL copybooks are required for the import. These copybooks are copied to the machine running Attunity Studio as part of the import procedure. If COBOL copybooks describing the data source records are available, then you can import the metadata by running the metadata import in Attunity Studio Design perspective, Metadata tab. If COBOL copybooks that describe the VSAM records are not available, then you must manually define the metadata. For information about the metadata definition, see Managing Data Source Metadata. If the metadata is provided in a number of COBOL copybooks with different filter settings (such as whether the first 6 columns are ignored or not), first import the metadata from copybooks with the same settings, and then import the metadata from the other copybooks. This section describes specific metadata requirements for the following data sources:
Index entries The dbCommand in the <table> statement must specify the volume for VSAM files created via Attunity Connect: <dbCommand>volume</dbCommand>
The dbCommand of all alternate keys must include the filename of the alternate key. For example:
<key name="AccountNo" size="4"> <dbCommand>VSAM.DATA.ACCOUN01.IO.PATH</dbCommand> <segments> ... </segments> </key>
For information about the metadata definition, see Managing Data Source Metadata.
Index entries. The filename attribute must specify the CICS logical name. The dbCommand in the <table> statement must specify the VSAM file type:
<dbCommand>file_type</dbCommand>
The dbCommand of all primary and alternate keys must include the CICS logical name of the alternate key. For example:
For information about the metadata definition, see Managing Data Source Metadata.
Transaction Support
The VSAM (CICS) data source supports two-phase commit and can fully participate in distributed transactions when the transaction environment parameter convertAllToDistributed is set to true. To use Attunity Connect with 2PC, you must have RRS installed and configured and have CICS TS 1.3 or above installed. If RRS is not running, then the data source can participate in a distributed transaction as the only one-phase commit data source if the logFile parameter is set to NORRS in the Transactions section of the binding properties for the relevant binding configuration in the Design perspective, Configuration tab in Attunity Studio. The XML representation is as follows: <transactions logFile="log,NORRS" /> where log is the high-level qualifier and name of the log file. If this parameter is not specified, then the format is the following: <transactions logFile=",NORRS" /> That is, the comma must be specified. For further details about setting up a data source to be one-phase commit in a distributed transaction, see CommitConfirm Table for more information. To use two-phase commit capability to access data on the z/OS machine, define every library in the ATTSRVR JCL as an APF-authorized library.
To define a DSN as APF-authorized, in the SDSF screen enter the command: "/setprog apf,add,dsn=navroot.library,volume=ac002" where ac002 is the volume where you installed AIS and NAVROOT is the high-level qualifier where AIS is installed.
If the AIS installation volume is managed by SMS, then when defining APF-authorization enter the following command in the SDSF screen: "/setprog apf,add,dsn=navroot.library,SMS"
Make sure that the library is APF-authorized, even after an IPL (reboot) of the machine.
The VSAM file participating in the 1PC or 2PC transaction must be defined as recoverable. To use distributed transactions from an ODBC-based application, ensure that AUTOCOMMIT is set to 0.
RRS must be configured and running on your system in order to use 1PC. When working with 1PC, it is important to correctly configure the timeout of your EXCI mirror transaction. The DTIMEOUT parameter in the CEDA transaction definition must exceed the maximum expected transaction duration. The default EXCI transaction is usually configured with a DTIMEOUT of 10 seconds, which may be problematic in terms of its short duration.
3.
Data Types
This table shows how Attunity Connect maps data types in a CREATE TABLE statement to VSAM data types.
Table 591 CREATE TABLE Data Types VSAM Char[(m)] Date+time Double Float Integer Numeric(p,s) Smallint Tinyint Varchar(m)
CREATE TABLE Char[(m)] Date Double Float Image Integer Numeric[(p[,s])] Smallint Text Tinyint Varchar(m)
Defining the VSAM Data Source Connection or Defining the VSAM (CICS) Data Source Connection Configuring the VSAM Data Source Properties or Configuring the VSAM (CICS) Data Source Properties
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your VSAM data source. Expand the Bindings folder. Expand the binding where you want to add the VSAM data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7.
The default names that AIS generates for the metadata files must be unique. AIS creates files for the data source, the file names are created by using the characters in the data source name and then by ensuring that the first character in the file name is legal. If the first character is not legal, it is replaced by a G. To make sure that the generated files are legal, you must make the last eight characters of the name alphabetic and unique.
8. 9.
Select VSAM from the Type list. Click Next. The Data Source Connect String screen is displayed.
Data HLQ: The high-level qualifier where the data files are located. Disk Volume Name: The high-level qualifier (volume) where the data resides. The values specified are used in the Data File field in the Attunity Studio Design perspective, Metadata tab. For tables created using the CREATE TABLE statement, the values specified are used to create the data files. If values are not specified, then data files are written to the DEF high-level qualifier under the high-level qualifier where AIS is installed. When SMS is used to manage the volumes, leave this value empty and set the newFileSMSStorageClass and newFileSMSDataClass properties as described in VSAM Data Source Parameters.
In the Design perspective, Configuration view expand the Machines folder. Expand the machine where you want to add your VSAM (CICS) data source. Expand the Bindings folder.
5. 6.
Expand the binding where you want to add the VSAM (CICS) data source. Right-click the Data Source folder and select New Data Source. The New Data Source wizard is displayed.
7.
The default names that AIS generates for the metadata files must be unique. AIS creates files for the data source, the file names are created by using the characters in the data source name and then by ensuring that the first character in the file name is legal. If the first character is not legal, it is replaced by a G. To make sure that the generated files are legal, you must make the last eight characters of the name alphabetic and unique.
8. 9.
Select VSAM (CICS) from the Type list. Click Next. The Data Source Connect String screen is displayed.
CICS Application ID: The VTAM applid of the CICS target system. The default value is CICS. This parameter is used when updating VSAM data. You can determine this value by activating the CEMT transaction on the target CICS system. On the bottom right corner of the screen appears the legend APPLID=target_system. Transaction ID: The mirror transaction within CICS that receives control via MRO, which transfers the transaction from the AIS environment to CICS. The default value is EXCI. VTAM Netname: The VTAM netname of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system. For example, if you issue the following command to CEMT: CEMT INQ CONN Then you see on the display screen that the netname is BATCHCLI (this is the default connection supplied by IBM upon the installation of CICS). The default value is ATYCLIEN. If you plan to use the IBM defaults, then specify BATCHCLI as the VTAM_ netname parameter, otherwise define a specific connection (with EXCI protocol) and use the netname you provided there for this parameter. * Attunity provides a netname, ATYCLIEN that can be used after the following procedure is followed: Either, use the JCL in the NAVROOT.USERLIB(CICSCONF) member to submit the DFHCSDUP batch utility program to add the resource definitions to the DFHCSD dataset (see the IBM CICS Resource Definition Guide for further details). Or Use the instream SYSIN control statements in the NAVROOT.USERLIB(CICSCONF) member as a guide to defining the resources online using the CEDA facility.
After the definitions have been added (via batch or using the CEDA facility), logon to CICS and issue the following command to install the resource definitions under CICS: CEDA INST GROUP(ATYI) Henceforth, specify ATYCLIEN as the NETNAME.
Program Name: The UPDTRNS program that is supplied with AIS to enable updating VSAM data. To use the UPDTRNS program, copy the program from NAVROOT.LOAD to a CICS DFHRPL library (such as CICS.USER.LOAD) and then define the UPDTRNS program under CICS using any available group such as ATY group: CEDA DEF PROG(UPDTRNS) G(ATY) LANG(C) DA(ANY) DE(ATTUNIT VSAM UPDATE PROG) NAVROOT is the high-level qualifier where AIS is installed. After defining the UPDTRNS program, install it as follows: CEDA IN G(ATY)
Trace Queue: The name of the queue for output that is defined under CICS when tracing the output of the UPDTRNS program. When not defined, the default CICS queue is used.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your VSAM data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the VSAM data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the VSAM Data Source Connection. Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your VSAM (CICS) data source. Expand the Bindings folder and the binding with your data source. Expand the Data sources folder. Right-click the VSAM (CICS) data source and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the VSAM Data Source Connection. Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
9.
Configure the data source parameters as required. For a description of the available parameters, see Configuration Properties.
Selecting the COBOL files Applying Filters Selecting Tables Import Manipulation Create VSAM Indexes (VSAM (ADD) only)
59-11
Assigning File Names (VSAM CICS only) Assigning Index File Names (VSAM CICS only Metadata Model Selection Importing the Metadata
The following sections describe each step, and the screens that appear for that step.
In the Design perspective, Configuration view, right-click the data source and select Show Metadata View. The Metadata tab is displayed with the data source displayed in the Metadata view.
3.
Right-click Imports and select New Import. The New Import screen is displayed, as shown in the following figure:
4. 5. 6.
Enter a name for the import. The name can contain letters, numbers and the underscore character. Select VSAM Import Manager or COBOL Import Manager for Data Sources from the list. Click Finish. The Metadata import wizard opens with the Get Input Files screen, as shown in the following figure:
7.
Click Add. The Add Resource screen is displayed, as shown in the following figure:
8.
If the files are on another machine, then right-click My FTP Sites and select Add. The Add FTP Site screen is displayed, as shown in the following figure:
59-13
9.
Enter the server name where the COBOL copybooks are located and, if not using anonymous access, enter a valid username and password to access that computer. The username is then used as the high-level qualifier. qualifier by right-clicking the machine in the Add Resource screen, and selecting Change Root Directory.
10. Click OK. After accessing the remote computer, you can change the high-level
11. Select the files to import and click Finish to start the file transfer. When complete,
he selected files are displayed in the Get Input Files screen. To remove any of these files, select the required file and click Remove.
12. Click Next (The Apply Filters screen opens) to continue to the Applying Filters
step.
Applying Filters
This section describes the steps required to apply filters on the COBOL copybooks used to generate the Metadata. It continues the Selecting the COBOL files procedure. To apply filters Expand all in the Apply Filters screen. Apply the required filter attributes to the COBOL copybooks. The available filters are listed and described in the table that describes the Metadata Filters. Click Next (The Select Tables screen opens) to continue to the Selecting Tables step.
1. 2. 3.
Compiler source
z/OS AS400 HP NonStop VMS MICROFOCUS Hardware (UNIX vendor) Default/Not known/Other
Storage mode
NOIBMCOMP for byte storage mode. IBMCOMP for word storage mode.
When set to true, ignores columns 73 to 80 in the COBOL copybook. When set to true, ignores the first six columns in the COBOL copybook.
When set to true, replaces all hyphens in either the record or Replace hyphens (-) in record and field names with field names in the metadata generated from the COBOL with underscore characters. underscores (_)
59-15
Table 592 (Cont.) Metadata Filters Filter Prefix nested columns Case sensitive Find Replace with Description When set to true, prefix all nested columns with the previous level heading. Specifies whether to be sensitive to the search string case. Searches for the specified value. Replaces the value specified for Find with the value specified here
Selecting Tables
This section describes the steps required to select the tables from the COBOL copybooks. The import manager identifies the names of the records in the COBOL copybooks that will be imported as tables. The following procedure continues the Applying Filters procedure. To select the required tables 1. From the Select Tables screen, select the tables that you want to access. To select all tables, click Select All. To deselect all selected tables, click Unselect All.
Figure 598 The Select Tables screen
2.
Click Next (the Import Manipulation screen opens) to continue to the Import Manipulation step.
Import Manipulation
This section describes the operations available for manipulating the imported records (tables). It continues the Selecting Tables procedure.
The import manager identifies the names of the records in the DDM Declaration files that will be imported as tables. You can manipulate the general table data in the Import Manipulation Screen. To import the metadata 1. From the Import Manipulation screen (see Import Manipulation Screen figure), right-click the table record marked with a validation error, and select the relevant operation. See the table, Table Manipulation Options for the available operations.
2.
Repeat step 1 for all table records marked with a validation error. You resolve the issues in the Import Manipulation Screen. Once all the validation error issues have been resolved, the Import Manipulation screen is displayed with no error indicators.
3.
Click Next.
If you are importing metadata for a VSAM (ADD) data source, continue to Create VSAM Indexes. If you are importing metadata for a VSAM CICS data source, continue to Assigning File Names.
The upper area of the screen lists the COBOL files and their validation status. The metadata source and location are also listed. The Validation tab at the lower area of the screen displays information about what needs to be resolved in order to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location).
VSAM Data Source (z/OS) 59-17
Resolving table names, where tables with the same name are generated from different files during the import. Selecting the physical location for the data. Selecting table attributes. Manipulating the fields generated from the COBOL, as follows: Merging sequential fields into one (for simple fields). Resolving variants by either marking a selector field or specifying that only one case of the variant is relevant. Adding, deleting, hiding, or renaming fields. Changing a data type. Setting the field size and scale. Changing the order of the fields. Setting a field as nullable. Selecting a counter field for array for fields with dimensions (arrays). You can select the array counter field from a list of potential fields. Setting column-wise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension. Creating arrays and setting the array dimension.
The following table lists and describes the available operations when you right-click a table entry:
Table 593 Option Fields Manipulation Table Manipulation Options Description Customizes the field definitions, using the Field Manipulation screen. You can also access this screen by double-clicking the required table record. Renames a table. This option is used especially when more than one table with the same name is generated from the COBOL. Sets the physical location of the data file for the table. Sets the table attributes. Specifies an XSL transformation or JDOM document that is used to transform the table definitions. Removes the table record.
Rename Set data location Set table attributes XSL manipulation Remove
You can manipulate the data in the table fields in the Import Manipulation Screen. Double-click a line in the Import Manipulation Screen to open the Field Manipulation Screen.
Figure 5910
You can carry out all of the available tasks in this screen through the menu or toolbar. You can also right click anywhere in the screen and select any of the options available in the main menus from a shortcut menu. The following table describes the tasks that are done in this screen. If a toolbar button is available for a task, it is pictured in the table.
Table 594 Command General menu Undo Click to undo the last change made in the Field Manipulation screen. Field Manipulation Screen Commands Description
The offset of a field is usually calculated dynamically by the server at runtime according the offset and size of the proceeding column. Select this option to override this calculation and specify a fixed offset at design time. This can happen if there is a part of the buffer that you want to skip. When you select a fixed offset you pin the offset for that column. The indicated value is used at runtime for the column instead of a calculated value. Note that the offset of following columns that do not have a fixed offset are calculated from this fixed position.
59-19
Table 594 (Cont.) Field Manipulation Screen Commands Command Test import tables Description Select this table to create an SQL statement to test the import table. You can base the statement on the Full table or Selected columns. When you select this option, the following screen opens with an SQL statement based on the table or column entered at the bottom of the screen.
Data file name: Enter the name of the file that contains the data you want to query. Limit query results: Select this if you want to limit the results to a specified number of rows. Enter the amount of rows you want returned in the following field. 100 is the default value. Define Where Clause: Click Add to select a column to use in a Where clause. In the table below, you can add the operator, value and other information. Click on the columns to make the selections. To remove a Where Clause, select the row with the Where Clause you want t remove and then click Remove.
The resulting SQL statement with any Where Clauses that you added are displayed at the bottom of the screen. Click OK to send the query and test the table. Attribute menu Change data type Select Change data type from the Attribute menu to activate the Type column, or click on the Type column and select a new data type from the drop-down list.
Table 594 (Cont.) Field Manipulation Screen Commands Command Create array Description This command allows you to add an array dimension to the field. Select this command to open the Create Array screen.
Enter a number in the Array Dimension field and click OK to create the array for the column. Hide/Reveal field Select a row from the Field manipulation screen and select Hide field to hide the selected field from that row. If the field is hidden, you can select Reveal field. Select this to change or set a dimension for a field that has an array. Select Set dimension to open the Set Dimension screen. Edit the entry in the Array Dimension field and click OK to set the dimension for the selected array. Set field attribute Select a row to set or edit the attributes for the field in the row. Select Set field attribute to open the Field Attribute screen.
Set dimension
Click in the Value column for any of the properties listed and enter a new value or select a value from a drop-down list. Nullable/Not nullable Select Nullable to activate the Nullable column in the Field Manipulation screen. You can also click in the column. Select the check box to make the field Nullable. Clear the check box to make the field Not Nullable. Set scale Select this to activate the Scale column or click in the column and enter the number of places to display after the decimal point in a data type. Select this to activate the Size column or click in the column and enter the number of total number of characters for a data type.
59-21
Table 594 (Cont.) Field Manipulation Screen Commands Command Add Description Select this command or use the button to add a field to the table. If you select a row with a field (not a child of a field), you can add a child to that field. Select Add Field or Add Child to open the following screen:
Enter the name of the field or child, and click OK to add the field or child to the table. Delete field Select a row and then select Delete Field or click the Delete Field button to delete the field in the selected row.
Move up or down
Select a row and use the arrows to move it up or down in the list.
Select Rename field to make the Name field active. Change the name and then click outside of the field.
Select Columnwise Normalization to create new fields instead of the array field where the number of generated fields will be determined by the array dimension.
Table 594 (Cont.) Field Manipulation Screen Commands Command Combining sequential fields Description Select Combining sequential fields to combine two or more sequential fields into one simple field. The following dialog box opens:
First field name: Select the first field in the table to include in the combined field End field name: Select the last field to be included in the combined field. Make sure that the fields are sequential. Enter field name: Enter a name for the new combined field.
Flatten group
Select Flatten Group to flatten a field that is an array. This field must be defined as Group for its data type. When you flatten an array field, the entries in the array are spread into a new table, with each entry in its own field. The following screen provides options for flattening.
Select Recursive operation to repeat the flattening process on all levels. For example, if there are multiple child fields in this group, you can place the values for each field into the new table when you select this option. Select Use parent name as prefix to use the name of the parent field as a prefix when creating the new fields. For example, if the parent field is called Car Details and you have a child in the array called Color, when a new field is created in the flattening operation it will be called Car Details_Color.
59-23
Table 594 (Cont.) Field Manipulation Screen Commands Command Mark selector Description Select Mark selector to select the selector field for a variant. This is available only for variant data types. Select the Selector field form the following screen.
Select Replace variant to replace a variants selector field. Select Counter Field opens a screen where you select a field that is the counter for an array dimension.
Figure 5911
To create VSAM Indexes Click Next to go to the Metadata Model Selection step. The indexes are created automatically.
Note: Make sure that the data location is supplied in the Import Manipulation step.
Specify the CICS logical file name for each record listed. Click Next (The Assign Index File Names screen opens) to continue to the Assigning Index File Names step.
59-25
Specify the CICS logical index file name for each record listed. Click Next (The Import Metadata screen opens) to continue to the Metadata Model Selection step.
Default values for all tables: Select this if you want to configure the same values for all the tables in the import. Make the following selections when using this option: Generate sequential view: Select this to map non-relational files to a single table. Generate virtual views: Select this to have individual tables created for each array in the non-relational file. Include row number column: Select one of the following: true: Select true, to include a column that specifies the row number in the virtual or sequential view. This is true for this table only, even in the the data source is not configured to include the row number column.
59-27
false: Select false, to not include a column that specifies the row number in the virtual or sequential view for this table even if the data source is configured to include the row number column. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties. Inherit all parent columns: Select one of the following: true: Select true, for virtual views to include all the columns in the parent record. This is true for this table only, even in the data source is not configured to include all of the parent record columns. false: Select false, so virtual views do not include the columns in the parent record for this table even if the data source is configured to include all of the parent record columns. default: Select default to use the default data source behavior for this parameter. For information on how to configure these parameters for the data source, see Configuring Data Source Advanced Properties.
Specific virtual array view settings per table: Select this to set different values for each table in the import. This will override the data source default for that table. Make the selections in the table under this selection. See the item above for an explanation.
If you want to update the metadata using the VSAM data source, and then access the data under CICS, you must: Close the file in CICS Make the updates in with the VSAM data source Exit navcmd. This closes the file in VSAM Return to CICS and open the file there. The data should be available and you can now read the file.
To import the metadata 1. Specify Yes to transfer the matadata to the target computer or No to transfer the metadata later.
2.
Click Finish.
If you specified Yes, then the metadata will be imported to the target computer immediately. The Import Metadata screen is shown in the following figure:
Figure 5915 The Import Metadata screen
59-29
Part IX
Procedure Data Source Reference
This part contains the following topics:
Procedure Data Sources Natural/CICS Procedure Data Source (z/OS) Procedure Data Source (Application Connector) CICS Procedure Data Source
-1
60
Natural/CICS Procedure Data Source (z/OS)
This section includes the following topics:
Overview Supported Platforms and Versions Metadata Security Defining the Natural/CICS Procedure Data Source Writing a Natural Remote Procedure Call Maintaining the CICS Environment for the Natural Agent
Overview
Attunity AIS provides a Natural data source driver and application agent to execute Natural subprograms under CICS as remote procedure calls. The returned rowset is handled in the same way that data from any data source is handled, using the relational model: The procedure can be used in SQL and a resulting rowset can be joined with other row sets from other data sources or Attunity Connect procedures The following diagram shows a simplified model of the how the Natural data source and application agent work within a CICS environment:
Figure 601 Natural Data Source and Application Agent within CICS Environment
The Natural/CICS procedure data source receives a remote procedure call from the client and passes it via a CICS EXCI-interface transaction to the agent in CICS (ATYNAGNT). The agent receives control and assigns a server task to process the client request. The server executes the subprogram call and passes the results back to the agent. The agent packages the results for the EXCI interface, which passes them back to the Natural data source, which then returns the results to the client. You can execute the Natural/CICS transaction by calling it either directly in a CALL statement, or within a SELECT statement. For example:
CALL NATPROC:TESTLSTN(1234.123,STRINGA ,123.123) Select * from NATPROC:TESTLSTN(1234.123,STRINGA ,123.123)
Environmental Prerequisites
AIS uses EXCI to interface to CICS. EXCI requires some set up:
IRC must be open. Use CEMT I IRC from the CICS screen to check your IRC status. If in closed state, set it to open. A specific connection must be set up. Use CEMT I connection to get the list of available connections. Note that you can only use specific connections which have a VTAM netname associated with them. The default available on most systems is BATCHCLI. Attunity provides a JCL for defining an Attunity connection. See the CICS CONF member in the USERLIB. An EXCI mirror transaction ID must be available. The default on most systems is transaction ID EXCI. You can use the CEMT I TRA PROG(DFHMIRS) to get the list of EXCI transaction IDs available on your system.
Configuration Properties
The following properties can be configured for the Natural/CICS procedure data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Procedure Data Sources.
disableExplicitSelect: Set to true to disable the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement. exciTransid: The CICS TRANSID. This value must be EXCI or a copy of this transaction.
Metadata
The metadata describes the input and output structures for the Natural/CICS transaction to be executed.
To define the metadata, define a new procedure in the Attunity Studio Design perspective Metadata tab, and provide the following information by editing the XML in the Source tab, displayed after the procedure is generated.
The program name to be run in the Natural/CICS transaction. The input parameters and output data. Attunity Connect treats the input variables as parameters and the output variables are treated as a rowset produced by the Natural/CICS transaction.
To define metadata for a Natural procedure, right-click the Procedures folder, under the data source, and select New Procedure. Once the procedure has been defined in Attunity Studio, you can define the metadata for it, in XML.
Syntax
<dbCommand>PROGRAM=ATYLSTN;TRANSID=ATYI; SUBPROGRAM=natural_subprogram; LIBRARY=library_of_subprogram; CONTEXT=context_data_field; </dbCommand>
Where:
Table 601 Parameter PROGRAM (optional) TRANSID (optional) <dbCommand> Statement Parameters Description The main program of the Natural agent. The default value is ATYLSTN. The mirror transaction within CICS that receives control through MRO, which transfers the Natural transaction from the Attunity AIS environment to CICS. The default value is ATYI. The Natural subprogram that is executed. The library where the Natural subprogram resides. A user area, used by the subprogram to read and save the state between successive calls to the subprogram.
Syntax
Where EOS_VALUE is the value that signals the end of the transaction, assuming that the transaction has a context. The value assigned can be a string or an integer value, that when encountered, causes the transaction to end. If you specify more than one EOS_VALUE, then a logical OR condition is implied.
Note:
If EOS_VALUE is specified neither for a field nor a parameter (see below), then the transaction is assumed not to have a context and only one row is returned. If a value is specified both for a field and a parameter, then the first value encountered causes the transaction to end.
Where:
Table 602 Parameter EOS_VALUE <dbCommand> Statement Parameters Description The value that signals the end of the transaction, assuming that the transaction has a context. The value assigned can be either a string or an integer value, that when encountered causes the transaction to end. If you specify more than one EOS_VALUE, the a logical OR condition is implied. Note: If EOS_VALUE is specified neither for a parameter nor a field (see above), the transaction is assumed not to have a context and only one row is returned. If a value is specified both for a parameter and a field, the first value encountered causes the transaction to end. REAPPLY The original value supplied for the parameter is reapplied when the transaction modifies the parameter value. This attribute is only relevant when executing stream-type transactions. The offset of the output parameter from the input parameter. If OUTPUTOFFSET=0, the same field is used for both the input and output parameters, with the value updated for the output. If OUTPUTOFFSET is not specified, you cannot configure input parameters to also be output parameters and all the input parameters must physically precede the output fields in the COMMAREA itself. ADD Metadata
OUTPUTOFFSET
Example 601
<?xml version=1.0 encoding=US-EBCDIC?> <navobj> <procedure name=testlstn> <dbCommand> program=atylstn;transid=atyi; subprogram=testlstn; </dbCommand> <parameters> <field name=p1 datatype=ada_numstr_s size=15 scale=3 /> <field name=p2 datatype=string size=39 /> <field name=p3 datatype=ada_decimal size=17 scale=4 /> <field name=p4 datatype=string size=10 />
</parameters> <fields> <field name=f1 datatype=ada_numstr_s size=10 scale=3/> <field name=f2 datatype=string size=45 /> <field name=f3 datatype=ada_decimal size=17 scale=4 /> </fields> </procedure> </navobj>
Security
The required security authorizations depend on the specific site. The following rules should be applied:
Check the list of resources being defined to CICS in the CICSDEF member in the NatAgent source library (programs, transactions, connections, etc.) and decide what to authorize in order for the Natural/CICS agent to work. The ATYN, ATYP, and ATYM transactions are all being started as asynchronous non-terminal tasks and should be defined to the security tool (for example, RACF) accordingly. To activate the installed groups ATYI and ATYL in the applid of CICSPRDC, add these groups to the applid of CICSPRDC list LISTC, where LISTC includes all groups that will be active or included at CICS startup. For example, the applid of CICSPRDC startup parms can have the parameter specified as the following:
GRPLIST=(DFHLIST, LISTC316)
The ATYCLIEN connection for EXCI has to be defined to the security tool (for example, RACF).
Defining the Natural/CICS Procedure Data Source Connection Configuring the Natural/CICS Data Source
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine where you want to add your Natural/CICS procedure data source. Expand the Bindings folder. Expand the binding where you want to add the Natural/CICS procedure data source. Right-click Data sources and select New Data source.
7. 8. 9.
Enter a name for the procedure data source in the Name field. Select Natural/CICS from the Type list. Click Next. The Data Source Connect String screen is displayed.
Target system: The VTAM applid of the CICS target system. VTAM Netname: The VTAM netname of the specific connection used by the ATYI transaction (and MRO) to relay the program call to the CICS target system.
For example, if you issue the following command to CEMT, you will see ATYCLIEN for the ATYS connection on the display screen:
CEMT INQ CONN 11. Click Finish.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Natural/CICS procedure data source. Expand the Bindings folder and the binding with your procedure data source. Expand the Data sources folder. Right-click the procedure data source and select Open. The Configuration editor is displayed.
7.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the Natural/CICS Procedure Data Source Connection. Configure the data source driver properties as required. For a description of the available parameters, see Configuration Properties. Click Finish.
8. 9.
Include the ATYLRTN routine as part of the subprogram. This is the Natural Agent general service routine to implement the API. The routine includes a number of call requests available for use by the user. These include the call requests listed in the following table:
Retrieves input parameters from the Natural agent. It has the following format: CALL ATYLRTN GETPARMS ATYL_STRUCT len1 inparm1 len2 inparm2 len3 inparm3 ... The first parameter is the group-field ATYL_STRUCT, which is defined in the LDA mentioned above. Following this field are a series of one or more parameter definitions, where each definition consists of an optional length override field and the actual input parameter field. The length override field is a four-byte signed binary integer (I4 in Natural terminology), which is normally set to zero but may be set to an override value. If the length override is set to zero, the length of the input parameter is taken from its Natural data definition. If the length override is set to a value greater than zero, that value defines the length of the input parameter, as in the following example, where the data definition portion of the subprogram contains the following: DEFINE DATA LOCAL USING ATYPARMS LOCAL 1 #LAST-NAME (A20) 1 #JOB-TITLE (A20) 1 #ADDRESS (A30) 1 #CITY (A20) 1 #L70 (I4) CONST <70> 1 #L0 (I4) CONST <0> ... END-DEFINE The subprogram could receive from the Natural Agent a 70-byte group field containing the elementary fields #JOB-TITLE, #ADDRESS, and #CITY, as well as a 20-byte elementary field containing #LAST-NAME, using the following call: CALL ATYLRTN USING GETPARMS ATYL_STRUCT #L70 #JOB-TITLE #L0 #LAST-NAME Note: The specification of the input parameters in the call must match their specification in the ADD metadata defined for the Natural procedure call on the client side (see Metadata). You can pass a maximum of 50 parameters (where a parameter is defined as the parameter and its length).
Table 603 (Cont.) Call Requests within ATYLRTN Routine Request GETCTEXT Description Retrieve context data from the Natural Agent. It has the following format: CALL ATYLRTN GETCTEXT ATYL_STRUCT len cdata The first parameter is the group-field ATYL_STRUCT, which is defined in the LDA mentioned above. Following this field is a parameter definition consisting of an optional length override field and the actual context data field. The length override field is a four-byte signed binary integer (I4 in Natural terminology), which is normally set to zero but may be set to an override value. If the length override is set to zero, the length of the context data is taken from its Natural data definition. If the length override is set to a value greater than zero, that value defines the length of the context data, as in the following example, where the data definition portion of the subprogram contains the following: DEFINE DATA LOCAL USING ATYPARMS LOCAL #CONTEXT-DATA1 (A30) #CONTEXT-DATA2 (A20) 1 #L50 (I4) CONST <50> ... END-DEFINE The subprogram could receive 50 bytes of context data from the Natural agent, using the following call: CALL ATYLRTN USING GETCTEXT ATYL_STRUCT #L50 #CONTEXT-DATA1 Note: The length of the context data in the call must match its length specification in the ADD metadata defined for the Natural procedure call on the client side (see Metadata).
Table 603 (Cont.) Call Requests within ATYLRTN Routine Request GETUINFO Description Retrieve user information from the Natural agent. The user information is defined at the data source level at the client side, and is passed to every procedure call in the data source. Its use is optional, and its often used to implement user security at the application (subprogram) level. The GETUINFO call has the following format: CALL ATYLRTN GETUINFO ATYL_STRUCT userid password len userinfo The first parameter is the group-field ATYL_STRUCT, which is defined in the LDA mentioned above. The second parameter is an eight-byte field which receives the userid that was defined in the procedure call. The third parameter is an eight-byte field, which receives the password that was defined in the procedure call, providing that SECMODE=0 or SECMODE=1; if SECMODE=2, the password field is filled with blanks for security reasons. Following the password field is a parameter definition consisting of an optional length override field and the actual user information field. The length override field is a four-byte signed binary integer (I4 in Natural terminology), which is normally set to zero but may be set to an override value. If the length override is set to zero, the length of the user information is taken from its Natural data definition. If the length override is set to a value greater than zero, that value defines the length of the user information, as in the following example, where the data definition portion of the subprogram contains the following: DEFINE DATA LOCAL USING ATYPARMS LOCAL 1 1 1 #USERID (A8) #PASSWORD #USER-INFO 2 #USER-INFO-1 (A20) 2 #USER-INFO-2 (A40) #L60 (I4) CONST <60>
1 ... END-DEFINE
The subprogram could receive 60 bytes of user information from the Natural agent using the following call: CALL ATYLRTN USING GETUINFO ATYL_STRUCT #USERID #PASSWORD #L60 #USER-INFO-1 Note: The length of the user information in the call from the Natural subprogram must not be smaller than its length specification as defined at the data source level on the client side (see Metadata). PUTPARMS Return output parameters to the Natural Agent. It has the following format: CALL ATYLRTN PUTPARMS ATYL_STRUCT len1 outparm1 len2 outparm2 len3 outparm3 ... The first parameter is the group-field ATYL_STRUCT, which is defined in the LDA. Following this field are a series of one or more parameter definitions, where each definition consists of an optional length override field and the actual input parameter field. The length override field is a four-byte signed binary integer (I4 in Natural terminology), which is normally set to zero but may be set to an override value. If the length override is set to zero, the length of the input parameter is taken from its Natural data definition. If the length override is set to a value greater than zero, that value defines the length of the input parameter. See the GETPARMS call request above for an example.
Table 603 (Cont.) Call Requests within ATYLRTN Routine Request PUTCTEXT Description Return context data to the Natural agent. It has the following format: CALL ATYLRTN PUTCTEXT ATYL_STRUCT len cdata The first parameter is the group-field ATYL_STRUCT, which is defined in the LDA mentioned above. Following this field is a parameter definition consisting of an optional length override field and the actual context data field. The length override field is a four-byte signed binary integer (I4 in Natural terminology), which is normally set to zero but may be set to an override value. If the length override is set to zero, the length of the context data is taken from its Natural data definition. If the length override is set to a value greater than zero, that value defines the length of the context data. See the GETCTEXT call request above for an example. REPLY Return code and optional error message to the Natural agent. It has the following format: CALL ATYLRTN REPLY ATYL_STRUCT Prior to the call, the return code and error message are set, as in the following example: IF AS_RETURN_CODE = 0 COMPRESS *PROGRAM EXECUTED SUCCESSFULLY INTO AS_ERROR_TEXT END-IF CALL ATYLRTN REPLY ATYL_STRUCT In the above example, if the previous call to ATYLRTN was unsuccessful, the return-code and error-message set by ATYLRTN are not altered and are returned to the Natural agent unchanged. Otherwise, a new success message is created and returned together with the zero return-code. Note: The fields AS_RETURN_CODE and AS_ERROR_TEXT are defined in the group ATYL_STRUCT supplied in the ATYPARMS LDA.
Declaration of ATYPARMS LDA in the data definition. Declaration of input and output parameters, length override fields and other work fields. CALL ATYLRTN USING GETCTEXT etc. to retrieve input parameters from the Natural agent. Optionally, CALL ATYLRTN USING GETCTEXT etc. to retrieve context data from the Natural agent. On the first procedure call the Natural subprogram receives the context data initialized to binary zeros. Processing section of the subprogram. CALL ATYLRTN USING PUTPARMS etc. to return output parameters to the Natural agent, assuming the subprogram logic leads to a successful outcome.
Note:
5. 6.
This call is not required if the subprogram does not execute successfully, that is, the return-code does not equal zero.
7.
Optionally, CALL ATYLRTN USING PUTCTEXT etc. to return context data to the Natural agent.
Natural/CICS Procedure Data Source (z/OS) 60-11
8.
CALL ATYLRTN USING REPLY etc. to return a return-code and optional error-message to the Natural agent.
Transids, enqueue names, program names, TSQ prefixes, TDQ names, etc. should be left unchanged unless this creates a conflict with already existing names and ids in the system.
TTENQ: Enqueue name for Attunity AIS Natural/CICS thread table. Default value: ATYLTHTB PTASK: Transid responsible for purging a runaway server task. Default value: ATYP. If changed, the corresponding CICS PCT entry must be modified accordingly.
NTASK: Transid activating the Natural server front end, which in turn activates the Natural server nucleus. Default value: ATYN. If changed, the corresponding CICS PCT entry must be modified accordingly.
MTASK: Transid activating the Attunity Connect message handler program. Default value: ATYM. If changed, the corresponding CICS PCT entry must be modified accordingly.
NFRONT: Name of server front end program. Default value: ATYFRONT. If changed, the actual program must also be renamed and the corresponding PCT and PPT entries modified accordingly.
NBACK: Name of server back end program. Default value: ATYBACK. If changed, the actual program must also be renamed and the corresponding PPT entry modified accordingly.
NATNUC: Name of Natural/CICS nucleus, to which the server front end does an XCTL. This should be the name of the standard Natural/CICS nucleus installed on the system. Default value: NC314RE. PDELAY: The delay in seconds allowed for the Natural server to perform the remote procedure call. Default value: 60. If the time set is exceeded, it is assumed that the Natural server is in a runaway loop and it is purged from the system.
Note: In most environments, PDELAY and LDELAY (see below) should be identical.
LDELAY: The delay in seconds allowed for the agent to wait for the Natural server to perform the remote procedure call. Default value: 60. If the time set is exceeded, the Agent returns a non-zero response code to the client indicating that the server has not responded.
Note:
PXINTQ: The prefix used to build, together with the thread number, the name of a temporary storage queue used to pass the input parameters to the procedure call. Default value: ATYIN. For example, assuming the default, the TSQs will be named ATYIN001, ATYIN002, etc.
PXOUTQ: The prefix used to build, together with the thread number, the name of a temporary storage queue used to pass the output parameters from the procedure call back to the agent. Default value: ATYOU. For example, assuming the default, the TSQs will be named ATYOU001, ATYOU002, etc.
PXCLTQ: The prefix used to build, together with the thread number, the name of a temporary storage queue used to pass control data from the agent to the subprogram and back. Default value: ATYCL. For example, assuming the default, the TSQs for the respective threads will be named ATYCL001, ATYCL002, etc.
PXPTRQ: The prefix used to build, together with the thread number, the name of a request id (REQID) used to identify the wait of the task responsible for purging the Natural server should it enter a runaway loop. Default value: ATYPT. For example, assuming the default, the REQIDs will be named ATYPT001, ATYPT002, etc.
PXLWRQ: The prefix used to build, together with the thread number, the name of a request id (REQID) used to identify the wait into which the Agent enters while awaiting a reply from the Natural server. Default value: ATYLW. For example, assuming the default, the REQIDs will be named ATYLW001, ATYLW002, etc.
PXNWRQ: The prefix used to build, together with the thread number, the name of a request id (REQID) used to identify the wait into which the Natural server task enters after it has concluded a procedure call and waits for its thread to be chosen for a subsequent procedure call. Default value: ATYNW. For example, assuming the default, the REQIDs will be named ATYNW001, ATYNW002, etc.
MAXTH: The maximum number of threads (and therefore the maximum number of Natural server tasks available for work) that can be activated per CICS address space.
60-13
This value should not exceed the number of sessions available for specific (non-generic) EXCI connections to the CICS address space. Default value: 10.
MSG: The destination for error messages written by the Natural/CICS agent or its component modules. Permissible values are: JOBLOG: Error messages are written as operator messages to the CICS job log. TDQ: (The default value) Messages are written to the transient data queue specified by the TDQID parameter. BOTH: Messages are written to both JOBLOG and TDQ destinations.
TDQID: The name of the transient data queue to which error messages are written if the MSG parameter (see above) is specified as TDQ or BOTH. Default value: ATYL. MAXNTM: Maximum number of no thread available error messages that will be written within the period of an hour. Default value: 20. MAXMSG: Maximum number of all error messages that will be written within the period of an hour. Default value: 300. MXINAC: Maximum inactivity in minutes permitted to a Natural server task before it terminates and is purged from the system. Default value: 15. SECMODE: A flag specifying which security strategy the user has opted to implement for the Natural server task. The following options are: 0 (No server-side security): Natural Security is not installed. A library parameter, if passed, will cause a logon to that library if it is not yet the current library-id for the server task. All userid and password passed parameters are optional and have no effect on the agent per se; the subprogram may interrogate them as well as additional user information for the purpose of enforcing homemade security as it sees fit. 1 (Minimal server-side security (trusted mode)): This is the default value. Natural Security is installed. The Natural server task will be initialized with a trusted userid and password (specified in the configuration parameters) with which it will work throughout the life of the server task. All libraries from which subprograms are to be invoked must be authorized for use with this trusted user. A library parameter, if passed, will cause a logon to that library if it is not yet the current library-id for the server task. All userid and password passed parameters are optional and have no effect on the agent per se; the subprogram may interrogate them as well as additional user information for the purpose of enforcing homemade security as it sees fit. 2 (Maximum server-side security): Natural Security is installed. The Natural server task will be initialized with a userid of limited authorization. Each procedure call must supply its own library/userid/password combination as part of the call. This will enable a high level of server-side security but will incur considerable overhead during the repeated authorization work being performed by Natural Security. The Natural agent will try to minimize this overhead as much as possible by attempting to dedicate a separate thread for each library/userid/password combination, up to the maximum thread limit defined in the configuration parameters. In addition, if no new threads are available, then the agent will attempt to locate an available thread (server) currently logged onto the same userid, requiring only a change to the current library. If no such threads are available, only then will the agent choose the oldest inactive thread and cause its associated server to incur the full overhead of a library/userid/password re-logon. Nonetheless, one should expect additional processing overhead using SECMODE=2.
Note:
If AUTO=ON is specified, then SECMODE=2 will be flagged as a configuration parameter error, since AUTO=ON does not provide a means to alter the userid in the middle of the Natural session.
AUTO: The value to which the Natural Security dynamic parameter AUTO should be set. ON (the default value): Userid and password are not entered during Natural logon; the userid is taken from the CICS External Security Interface. OFF: Userid and password are entered during Natural logon. This parameter is specified only when SECMODE=2.
Note:
Changes have to be made to the Natural assembler exit NCIUIDEX in order that an asynchronous (non-terminal) Natural task will obtain the userid externally. To avoid this problem, even users that normally implement Natural Security with AUTO=ON should consider using AUTO=OFF for the asynchronous Natural server tasks.
SENDER: The value to which the Natural dynamic parameter SENDER should be set for asynchronous Natural tasks. This should be the name of a transient data queue. Default value: CSSL. OUTDEST: The value to which the Natural dynamic parameter OUTDEST should be set for asynchronous Natural tasks. This should be the name of a transient data queue. Default value: CSSL. TBTCH: Specifies whether the Natural server task issues the command SET CONTROL 'T=BTCH' during its initialization, in order to operate inline support mode for messages, etc. output to the SENDER and OUTDEST destinations. YES: When the Natural server task initializes, the command SET CONTROL 'T=BTCH' is issued. This enables error messages and messages issued by the WRITE and DISPLAY commands in called subprograms to be output successfully to the SENDER or OUTDEST destinations.
Note: The NATBTCH module must be installed in the Natural CICS nucleus when the nucleus is link-edited. If the NATBTCH module is not present and TBTCH=YES, an error will occur during server task initialization.
NO (the default value): The command SET CONTROL 'T=BTCH' is not be issued during Natural server task initialization. TBTCH should be allowed to default to NO if the NATBTCH module is not present in the link-edit of the Natural CICS nucleus. Natural error messages and WRITE or DISPLAY messages output by subprograms are not written to the SENDER or OUTDEST destinations (that is, the messages will be lost but the server task will continue to operate normally).
LOGON: The startup library to which Natural should logon when the server task is initiated. This library will be specified in the LOGON command specified in the dynamic STACK parameter when Natural is started. Default value: ATYLSTN.
60-15
USERID: The userid with which Natural should logon when the server task is initiated. This userid is specified in the LOGON command specified in the dynamic STACK parameter when Natural is started. Default value: ATTY. This parameter is specified only when SECMODE=2 and AUTO=OFF (see above).
PASSWD: The password with which Natural should logon when the server task is initiated. This password is specified in the LOGON command specified in the dynamic STACK parameter when Natural is started. Default value: ATTY. This parameter is specified only when SECMODE=2 and AUTO=OFF (see above).
MONITR: Name of Natural dispatcher program. This program receives control when the Natural server task is initiated and is responsible for dispatching each subsequent procedure call in its thread, error-handling, interaction with the Agent, etc. Default value: ATYNDISP. If changed from default value, the actual program must be renamed as well.
ADDPARM: A string of additional dynamic parameters for the Natural server task, which may be optionally added to the dynamic parameters mentioned above. Default value: (null string). For example:
ADDPARM=(MADIO=0,LT=99999,TD=2)
Note: Use this parameter with great care. You must make sure that the correct library is logged onto upon initialization of the Natural server session and the correct Natural agent dispatcher program is activated. Normally this parameter is used to specify a profile defined by SYSPARM or NTSYS, where the actual list of dynamic parameters are defined.
TRSRECL: The maximum length of a record that may be written to main temporary storage. Default value: 32748. DYNPARM: A string of dynamic parameters for the Natural server task, which will replace the dynamic parameters mentioned above. Default value: (null string). For example:
DYNPARM=(SYS=NATAGENT)
Note: Use this parameter with great care. You must make sure that the correct library is logged onto upon initialization of the Natural server session and the correct Natural agent dispatcher program is activated. Normally this parameter is used to specify a profile defined by SYSPARM or NTSYS, where the actual list of dynamic parameters are defined.
61
Procedure Data Source (Application Connector)
This section includes the following topics:
Overview Configuration Properties Transaction Support Security Data Types Platform-specific Information Defining the Procedure Data Source Setting Up Procedure Data Source Metadata Testing the Procedure Data Source Executing a Procedure
Overview
This section contains information on the following topics:
Introduction
The Procedure data source deals with activating any piece of 3GL code (COBOL, C, RPG, etc.) as an SQL stored procedure. The Metadata for such a stored procedure includes a description of the input and output parameters as well as the DLL name and entry name where the code resides. The Procedure data source is activated when the client application executes one of its stored procedures. It uses its metadata to construct the calling stack for the back-end 3GL code. It loads the user DLL, locates the entry point, runs the function and returns a result as SQL stored procedure output parameters.
Note:
Attunity Connect includes separate modules for data access, as opposed to application access. This distinction however is drawn more along the lines of Client Interface and access method rather than whether a database or application is being activated. The Procedure Data Source is part of the data access component, although it deals strictly with activating applications. This is because the model used is SQL Stored Procedures. If SQL language and/or interfaces are not required, it is recommended to use the Legacy Plug Application Adapter instead of the Procedure data source.
Supported Features
The Procedure data source supports the following main features:
Exposes user-written functions and/or procedures as Stored Procedures that can be activated from any supported platform to any Attunity-supported interface. Parameter-passing mechanisms by value, reference, and descriptor. On OpenVMS, the descriptor-passing mechanism is especially useful because the Attunity descriptor structure matches the OpenVMS descriptor structure. You can view the C-language version of the Attunity descriptor structure in the gdb_val_desc struct and GDB_VAL_DESC typedef that is contained in the C header file dbgdb.h. This file is part of the AIS kit for each platform.
Functions optionally returning a value. Complex structures passed as parameters. Multiple levels of indirection (for example, in C, char***). Triggers activated on session and transactional events. When using structures, different alignments are supported. Multi-record result set composed by multiple activation of the user procedure until satisfying an end condition.
Limitations
No array support. If array support is required, you must use the Legacy Plug Adapter.
Configuration Properties
This section contains the following topics:
Overview
The simple task of activating user 3GL code does not require any configuration parameters to be set. All the information regarding the DLL name, symbol name, parameter passing mechanisms are all defined as part of the Stored Procedure Metadata. The following set of configuration properties deals with setting up triggers on a Procedure data source Driver. The need for these properties is best explained by an example. For the purposes of this example, the 3GL code being activated by the Procedure Data Source driver accesses an Oracle database. This type of use case raises the following challenges.
At what point does the user code connect to the Oracle database; when can it disconnect from the database? How does a user of this data source control the transactional boundaries? How does one roll back changes performed by activating one or more of the stored procedures?
To support this type of use case, the Procedure data source allows for the registration of user triggers/user exits to be called on specific events related to the data source.
Parameter Descriptions
The following properties can be configured for the Procedure data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Procedure Data Sources.
commitTransaction: The name of a symbol within the triggerShareable attribute, to be activated when the client commits the transaction. The function prototype is GDB_STATUS commit_transaction_trigger(void *connect_handle);. This trigger has one argument and a return value:
commitTransaction Attribute Arguments Input/Output Input Type void * Description The handle returned by the connect trigger, or NULL if no such trigger was provided. The trigger should normally return a GDB_OK_ in case of success, or GDB_NOT_ in case of failure. These enumeration codes can be found in the DBGDB.h header file in the include directory.
connect_handle
return-value
Output
GDB_STATUS
connect: The name of a symbol within the triggerShareable attribute, to be activated when the client application connects to the data source. Note that in a reusable server, this trigger may be called several times as different clients connect and disconnect from the server. The function prototype is GDB_STATUS connect_trigger(void **connect_handle, char *datasource_name,
void * unused, char *username_password);. The function has four arguments and a return value:
Table 612 Name connect_handle connect Attribute Arguments Input/Output Output Type void ** Description The address of a handle that can be created by the connect trigger to store and pass information between the triggers. The handle provided by the connect trigger will be passed as input to all the other triggers. The use of different connection handles is important in a multi-client scenario, to separate the environments of different clients (for example, from the Overview example, maintain separate connections to Oracle for each of the clients). A NULL-terminated string containing the name of the data source. Not currently in use. If a user name and password was set up for the Procedure data source, these will be passed to the connect trigger. A Procedure data source does not require a user name or password for itself, but the back-end user code may require a user name and password (e.g. in the Overview example, the user name and password of the Oracle database).
datasource_name
Input
char *
Input Input
void * char *
Table 612 (Cont.) connect Attribute Arguments Name return-value Input/Output Output Type GDB_STATUS Description The trigger should normally return a GDB_OK_ in case of success, or GDB_ NOT_ in case of failure. These enumeration codes can be found in the DBGDB.h header file in the include directory.
disableExplicitSelect: For future use. disconnect: The name of a symbol within the triggerShareable attribute, to be activated when the client application disconnects from the data source. Note that in a reusable server, this trigger may be called several times as different clients connect and disconnect from the server. This trigger is normally used for clean-up operations. The function prototype is GDB_STATUS disconnect_ trigger(void *connect_handle);. This trigger has one argument and one return value:
disconnect Attribute Arguments Input/Output Input Type void * Description The handle returned by the connect trigger, or NULL if no such trigger was provided. The trigger should normally return a GDB_OK_ in case of success, or GDB_ NOT_ in case of failure. These enumeration codes can be found in the DBGDB.h header file in the include directory.
connect_handle
return-value
Output
GDB_STATUS
rollbackTransaction: The name of a symbol within the triggerShareable attribute, to be activated when the client rolls back the transaction. The function prototype is GDB_STATUS rollback_transaction_trigger(void *connect_handle);. This trigger has one argument and a return value:
rollbackTransaction Attribute Arguments Input/Output Input Type void * Description The handle returned by the connect trigger, or NULL if no such trigger was provided.
connect_handle
Table 614 (Cont.) rollbackTransaction Attribute Arguments Name return-value Input/Output Output Type GDB_STATUS Description The trigger should normally return a GDB_OK_ in case of success, or GDB_ NOT_ in case of failure. These enumeration codes can be found in the DBGDB.h header file in the include directory.
startTransaction: The name of a symbol within the triggerShareable attribute to be called when a transaction is started. The function prototype is GDB_ STATUS start_transaction_trigger(void *connect_handle, GDB_ TRANS_MODE mode);. This trigger has two arguments and a return value:
startTransaction Attribute Arguments Input/Output Input Type void * Description The handle returned by the connect trigger, or NULL if no such trigger was provided. The mode of a transaction. It can be read-only or read-write. The value of this enumeration can be found in the DBGDB.h header file in the include directory. The trigger should normally return a GDB_OK_ in case of success, or GDB_ NOT_ in case of failure. These enumeration codes can be found in the DBGDB.h header file in the include directory.
connect_handle
mode
Input
GDB_TRANS_MODE
return-value
Output
GDB_STATUS
triggerShareable: The name of the DLL/shareable image containing the triggers. This DLL may be separate from the procedural 3GL code being activated, or more often, within the same DLL as the user code being activated.
Transaction Support
There is no generic meaning to Transaction support when connecting to 3GL code. In some cases however, the back end code being activated does require transactional context. For example, 3GL code connecting to an Oracle database would potentially require the client application to control the transactional boundaries. Support for such back end systems can be achieved using the trigger mechanisms described in Configuration Properties.
Security
There is no generic meaning to security when connecting to 3GL code. In case the back end system activated is such that it requires security credentials, this can be achieved using the trigger mechanism for the connect trigger described in Configuration Properties.
Data Types
All available Attunity Connect data types can be used as parameters to the Procedure data sources stored procedures. Support for passing parameters by value is somewhat limited. You may only pass fields by value if their size does not exceed the pointer size of the machine, i.e. four bytes on 32-bit AIS, and eight bytes on 64-bit AIS. Also refer to Passing Parameters in OS/400.
Platform-specific Information
This section contains the following topics:
Windows Platforms and AIS Procedures (ADO Considerations) HP NonStop Platforms and Attunity Connect Procedures Load Modules and DLLs on MVS Descriptors on OpenVMS OS/400 Issues
To specify an Attunity Connect procedure that does include parameters, specify within the parentheses a question mark for each parameter and manually supply the parameters to Attunity Connect.
' Set parameters Dim con As ADODB.Connection
Dim com As ADODB.Command Dim prm As ADODB.Parameter ... Set prm = com.CreateParameter("Julian", adVarChar, adParamInput, 15, "Empty") Set prm = com.CreateParameter("White", adVarChar, adParamInput, 10, "Empty") ... ' execute procedure with parameters cmd.Text = "MyProcedure(?,?)" cmd.Type = adCmdStoredProc rs = cmd.Execute
Where:
STRING fnc_name: The name of the function to be registered. STRING fnc_class: The name of the group you want the function to be in (this is equivalent to the DLL module name). The name specified for this parameter is the same name specified in the filename attribute in the ADD metadata definition XML file. FNC_PT fnc_pt: A pointer to the user function. To register the symbols, call this function within the main() function of the procedure, as shown in the following example:
#include "utlmain.h" main(int argc, char *argv[]) { /* calls to nav_register_function() with all the new procedures */ return(nav_util_main(argc, argv)); }
The AIS installation package includes several files that you can use to become familiar with Attunity Connect procedures. These are:
mathc: This file contains sample procedures. It includes main() as in the above example. prcsmxml: ADD metadata XML files for the math procedures. utlmainh: An h file that should be included in the main program. bldproc: A procedure that links the libnava library with the math module. This file generates a new mathmain file that is used instead of the navutil call. That is, 'run mathmain execute MyProc' is used to call Attunity Connect with the MyProc data source (the Attunity Connect procedure definition in the binding configuration).
Notes:
When working in client/server mode, change the bldproc procedure to reproduce navutil, instead of mathmain. When using COBOL for the Attunity Connect procedure, you can only use HP NonStop NMCOBOL. To use Attunity Connect procedures on an HP NonStop platform 1. Create a custom version of the main() function for the NAV_UTIL program.
2. 3.
Add a call to the NAVSETUP() function at the beginning of your main. This is an internal function that loads the AIS server environment. In the custom main() function, register all user functions that will be referenced by the procedure driver. Use the following Attunity Connect function to register the functions: long nav_register_function(STRING fnc_name, STRING func_class, FNC_PT fnc_ pt) where: fnc_name: The name of the "external" function to be registered (that is, the LOAD function for a driver, the registration function for a data type, or a startup function). fnc_class: The name of the group you want the function to be in (this is equivalent to the DLL module name on other platforms). fnc_pt: A pointer to the user function.
4.
Statically link the custom functions with the Attunity Connect library LIBNAVA, located in the subvolume where Attunity Connect is installed, to create a custom version of the NAV_UTIL program.
Example 611 #include "utlmain.h" main(int argc, char *argv[]) { NAVSETUP(); nav_register_function("AddEmployee", "CLASS1", add_employee); return(nav_util_main(argc, argv)); }
Load module: This is a program, and as such has one entry point. There is no need for a symbol name, since there is only one function. DLL: This includes several entry points, each of which can be mapped as stored procedure using the Procedure data source. Therefore every stored procedure must specify the entry point name. Note that the DLL will only be loaded once into memory.
Descriptors on OpenVMS
Parameters passed by the descriptor are always set up as static text descriptors.
DSC$K_CLASS_S DSC$_DTYPE_T
OS/400 Issues
Service Programs
Currently activation of programs is not supported. You can only use the Procedure data source to activate service programs.
Passing Parameters
Passing parameters by value is not supported on OS/400. If required, you can pass parameters by reference or descriptor.
Defining the Procedure Data Source Connection Configuring the Procedure Data Source
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine where you want to add your Procedure data source. Expand the Bindings folder. Expand the Binding where you want to add the Procedure data source. Right-click the Data sources folder and select New Data source. Enter a name for the procedure data source in the Name field. Select Procedure (Application Connector) from the Type field. Click Finish.
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your Procedure data source.
4. 5. 6.
Expand the Bindings folder and the binding with your procedure data source. Expand the Data sources folder. Right-click the Procedure data source and select Open. The Configuration editor is displayed.
7.
Enter the information in the Authentication section, if necessary. You can define the following parameters:
User profile: Select the user profile that has permissions to access this data source. The available user profiles are in the list. For information on user profiles, see User Profiles. User name: Enter the name of user with access to this data source. Password: Enter the password for the user with access to this data source. Confirm Password: Enter the password again, to ensure it was entered correctly.
8.
Configure the Procedure data source driver properties as required. For a description of the available parameters, see Configuration Properties.
The Metadata tab is displayed with the selected procedure data source highlighted in the tree.
2. 3. 4. 5. 6.
Right-click Procedures, and select New Procedure. Enter the procedure name that the data source will search for in the given DLL. Enter the path and/or name for the DLL or, click Browse and locate the DLL. Select the source language of the DLL. Click Finish. The procedure is now displayed in the Metadata view and the procedure opens for editing.
Note:
The Language field in the The Procedure Properties General tab is intended for future implementation.
To specify return values 1. Click Add. The New Field screen opens.
2. 3.
Enter the return value name and click OK. The default return data type is string. Edit this value by clicking the data type and selecting the relevant data type from the list.
The following table lists and describes the default properties that are displayed for each return value:
Default Field Properties Description The method by which this argument is passed/received by the procedure. Valid values are VALUE, DESCRIPTOR, and REFERENCE. For outer-level (non-nested) arguments, structure arguments (for the structure itself, and not structure members), and variant arguments, the default value is REFERENCE. The default for all other columns is VALUE. A DESCRIPTOR can only be a static descriptor containing strings. Note: For OS/400 Platforms, any parameter that is an argument to the function (that is, contains a dbCommand statement with a non-zero ORDER) cannot have a MECHANISM of VALUE. This arises from the fact that the natural size of an integer on the OS/400 stack is smaller than a pointer.
ORDER
The ORDER for a return value is zero (0). Additional return value properties can be manually added by clicking Value for a property, and then clicking the ellipses button. The DB Command string is defined as follows: property=value;property=value;...
BASE_ALIGNMENT
The value for nested structures/variant fields. Valid values are SYSTEM (the default) or an integer greater than 0. This value is not case sensitive. Specifying an integer as the value for BASE_ALIGNMENT sets the initial offset, in increments of bytes, of the alignment of every structure and variant (until reset). For example, setting BASE_ ALIGNMENT to 2, aligns structures and variants on a word boundary.
MEMBER_ALIGNMENT
The value (until reset) for structure/variant fields. Valid entries are SYSTEM, YES, and NO. This value is not case sensitive. The default is the value at the table attribute level. Setting MEMBER_ALIGNMENT to YES specifies that the start of every structure member and variant member (until reset) is aligned on a boundary equivalent to the atomic size of that member. For example, a word is aligned on a word boundary.
61-13
Enter the argument name and click OK. Click the Type field, and set the type of the argument (input, output or input/output).
Note:
If an argument is defined as Input/Output, an additional argument is created in order to set the parameters input properties.
4. 5.
The default argument data type is string. Edit this value by clicking the Data Type area and selecting the relevant data type from the list. Use the Up and Down buttons to set the order of the arguments. The following table lists and describes the default properties that are displayed for each argument:
Input/Output Argument Default Properties Description The method by which this argument is passed/received by the procedure. Valid values are VALUE, DESCRIPTOR, and REFERENCE. This entry is not case-sensitive For outer-level (non-nested) arguments, structure arguments (for the structure itself, and not structure members), and variant arguments, the default value is REFERENCE. The default for all other columns is VALUE. A DESCRIPTOR can only be a static descriptor containing strings. Note: For OS/400 Platforms, any parameter that is an argument to the function (that is, contains a dbCommand statement with a non-zero ORDER) cannot have a MECHANISM of VALUE. This arises from the fact that the natural size of an integer on the OS/400 stack is smaller than a pointer.
Table 617 (Cont.) Input/Output Argument Default Properties Property ORDER Description The procedure argument number. The order can be changed using the Up and Down buttons. Additional argument properties can be manually added by clicking Value for a property, and then clicking the ellipses button. The DB Command string is defined as follows: property=value;property=value;... BASE_ALIGNMENT The initial value for the current argument, and all subsequent structure/variant arguments. Valid values are SYSTEM (the default) or an integer greater than 0. This value is not case sensitive. Specifying an integer as the value for BASE_ALIGNMENT sets the initial offset, in increments of bytes, of the alignment of every structure and variant (until reset). For example, setting BASE_ ALIGNMENT to 2, aligns structures and variants on a word boundary. MEMBER_ALIGNMENT The initial value for the current argument and all subsequent structure/variant arguments. Valid entries are SYSTEM, YES, and NO. This value is not case sensitive. The default is the value at the table attribute level. Setting MEMBER_ALIGNMENT to YES specifies that the start of every structure member and variant member from this point on is aligned on a boundary equivalent to the atomic size of that member. For example, a word is aligned on a word boundary. LEVEL The number of levels of indirection of the field pointer. This argument applies only to fields passed/received by REFERENCE. The argument value must be greater than 0 and defaults to 1 if not specified. Setting this token to 1 indicates that the address of the column is passed to the procedure. Setting the token to 2 indicates that you are using a pointer to another pointer. NULL This is used only for arguments passed by REFERENCE or DESCRIPTOR. This arguments value specifies what to pass to the procedure when the Attunity Connect buffer contains a null value for a nullable parameter. Valid entries differ depending on how the parameter is passed:
For parameters passed by REFERENCE, the valid entries are any integer from 0 through the value of the LEVEL parameter, where 0 passes a pointer to the data types null-value and n passes a pointer that when dereferenced (n 1) times is NULL. This defaults to the value of the LEVEL parameter for REFERENCE parameters. For parameters passed by DESCRIPTOR, the valid entries are 0 and 1, where 0 passes a pointer to the descriptor to the data types null-value and 1 passes a NULL pointer. This defaults to 1 for DESCRIPTOR parameters. For example, assuming foo = NULL, a parameter with LEVEL=2 and NULL=1 would pass &foo, while a parameter with LEVEL=2 and NULL=2 would pass &&foo.
EOS_VALUE
Optional, for output arguments. The value that marks the end of stream. By default, the stream ends after each fetch. If there are any EOS_VALUE arguments, then all must match their respective field values to end the stream. This entry is case sensitive.
61-15
3.
Click Finish.
Executing a Procedure
You can execute a 3GL procedure by calling it as follows:
Call MyProc:MATH_SIMPLE(12,33)
where MyProc is treated as a data source name and MATH_SIMPLE is the name of a function defined in MyProc. You can also use the procedure in a select statement, even performing joins between the results returned by the procedure and other tables. The following example shows the procedure used in a SELECT statement:
SELECT * from MyProc:MATH_SIMPLE(12,33)
Attunity Connect treats the input variables of the procedure as parameters and the output variables are treated as a rowset produced by this procedure. For an actual implementation as a sample, see the following directory on the Attunity installation CD: Samples\Drivers\StoreProc
62
CICS Procedure Data Source
This section describes the Attunity CICS Procedure data source driver. It includes the following topics:
Overview Configuration Properties Metadata Transaction Support Security Data Types Defining the CICS Procedure Data Source Setting-up the CICS Procedure Data Source Metadata Editing the XML in the Source Code
Overview
The CICS Procedure data source enables you to execute a CICS program using standard SQL from any supported Attunity client platform and API (e.g., from Windows using ODBC). The data source uses the External CICS Interface and the EXCI mirror transaction to execute programs within a CICS region. The CICS Procedure data source uses COMMAREA to pass input values to the CICS program and receives the output and therefore can only be used to execute COMMAREA programs. 3270 based CICS programs are not supported. After you define the new CICS program to the data source, it will be listed as a stored procedure to SQL clients, enabling you to execute a program by calling it either directly in an SQL CALL statement, or within an SQL SELECT statement. For example:
CALL CICSPROG1 (100, TEST1);
Or
SELECT * FROM CICSPROG1 (100, TEST2);
CICS version 4.1 or higher. CICS Transaction Server version 1.3 or higher.
Environmental Prerequisites
AIS uses EXCI to interface to CICS. EXCI requires some set up:
IRC must be open. Use CEMT I IRC from the CICS screen to check your IRC status. If in closed state, set it to open. A specific connection must be set up. Use CEMT I connection to get the list of available connections. Note that you can only use specific connections which have a VTAM netname associated with them. The default available on most systems is BATCHCLI. Attunity provides a JCL for defining an Attunity connection. See the CICS CONF member in the USERLIB. An EXCI mirror transaction ID must be available. The default on most systems is transaction ID EXCI. You can use the CEMT I TRA PROG(DFHMIRS) to get the list of EXCI transaction IDs available on your system.
Limitations
The CICS Procedure data source does not support arrays. If the CICS program returns an array, then you must use the CICS application adapter. For more information, see CICS Application Adapter (z/OS Only). The CICS Procedure data source does not support conversational programs.
Design Considerations
A single CICS Procedure data source can support one CICS region and is defined by a CICS APPLID and an IRC connection name. When creating the metadata for multiple CICS programs, it is recommended to use one data source unless you have different requirements of the different programs, such as:
Programs from different CICS regions Using a different mirror transaction (for monitoring, workload, or security reasons) Different level of transaction support (one-phase commit vs. Two-phase Commit)
Configuration Properties
The following properties can be configured for the CICS procedure data source. You set the properties in Attunity Studio, Design perspective. For information on how to set data source properties in Attunity Studio, see Adding Procedure Data Sources.
disableExplicitSelect: relevant if the data source driver allows for the suppressing of certain fields for Select *. So if you disable this, all fields will appear for Select *. exciTransid: Specifies the EXCI mirror transaction ID in the CICS region. On most systems you will usually find a default mirror transaction called EXCI. You can find out the transaction ID on your system using the following command from the CICS screen: CEMT INQUIRE TRANS PROG(DFHMIRS). The default value is EXCI.
reusePipe: Specifies if a PIPE on the EXCI connection is going to be reused for multiple DPL requests. Valid value is true or false. transactionSupport: The CICS data source normally works without a transactional context. This means that CICS programs are activated within their own unit of work (SYNCONRETURN). The data source is capable, however, of working in 1PC mode or even 2PC mode. See Transaction Support. userInfo: Not currently used. You can issue to CEMT the following command:CEMT INQ CONNThe netname is BATCHCLI to get the list of connections defined on your system. The default connection supplied by IBM is called has a VTAM_netname of BATCHCLI.
Note:
The AIS installation includes a JCL for defining a CICS connection to be used with AIS. If you choose to use the AIS connection (netname ATYCLIEN) perform the following procedure:
Either use the JCL in the NAVROOT.USERLIB(CICSCONF) member to submit the DFHCSDUP batch utility program to add the resource definitions to the DFHCSD dataset (see the IBM CICS Resource Definition Guide for further details) or use the instream SYSIN control statements in the NAVROOT.USERLIB(CICSCONF) member as a guide to defining the resources online using the CEDA facility. After the definitions have been added (via batch or using the CEDA facility), log on to CICS and issue the following command to install the resource definitions under CICS:
CEDA INST GROUP(ATYI)
Metadata
The CICS Procedure data source requires Attunity Metadata. The metadata describes the program that should be executed, its input and output. Each CICS program to be activated requires a procedure definition in the data source ADD. You need to supply the following information:
The program name to be executed in CICS. The layout of the COMMAREA (the input parameters and output data).
Attunity Connect treats the input variables as parameters and the output variables are treated as a rowset produced by the CICS program. If COBOL copybooks which describe the CICS program input and output records are available, then you can use the Attunity Studio Metadata Import wizard. For more information, see Importing Procedure Metadata to create the metadata for these programs. If the metadata is provided in a number of COBOL copybooks, with different filter settings (such as whether the first 6 columns are ignored or not), you import the
metadata from copybooks with the same settings and later import the metadata from the other copybooks. Otherwise, the metadata must be manually defined, as described in Setting-up the CICS Procedure Data Source Metadata.
Transaction Support
Attunity CICS Procedure data source can work with either one-phase commit or Two-phase Commit transactions. It can fully participate in a distributed transaction. By default, the Attunity CICS Procedure data source is configured as zero-phase commit. This means that transactions are not supported; rollbacks are not available and all operations via EXCI are executed as SYNCONRETURN invocations.
RRS must be configured and running on your system in order to use 1PC. When working with 1PC, it is important to correctly configure the timeout of your EXCI mirror transaction. The DTIMEOUT parameter in the CEDA transaction definition must exceed the maximum expected transaction duration. The default EXCI transaction is usually configured with a DTIMEOUT of 10 seconds, which may be problematic in terms of its short duration.
3.
To enable one-phase commit 1. In Attunity Studio, in the Configuration perspective, double-click the relevant data source to open the Data Source Editor.
2. 3. 4.
At the bottom of the editor, click the Advanced tab. In the Transaction Type field, select 1PC. Click Save.
As a full two-phase commit resource: In this scenario you must use CICS TS 1.3 or higher, and have the Resource Recovery Services (RRS) configured for your CICS region. As a one-phase commit resource: In this scenario you must use CICS TS 1.3 or higher, but you dont need to have RRS installed. Attunity Connect can still manage a two-phase commit scenario with one of the data sources participating in the transaction is a one-phase commit resource. To use Two-phase Commit capability to access data on the z/OS computer, you must define each library in the ATTSRVR JCL as APF-authorized. To define a DSN as APF-authorized, enter the following command in the SDSF screen:
2.
3.
Where ac002 is the volume where at is installed and NAVROOT is the high-level qualifier where AIS is installed. If the AIS installation volume is managed by SMS, enter the following command in the SDSF screen when defining APF authorization:
"/setprog apf, add, dsn=navroot.library, SMS"
Make sure that you add these libraries to your APF list so they will remain APF-authorize after IPL. To use CICS Procedure in two-phase commit transactions you must make the following configuration changes:
1.
Edit the following parameters under the Transactions section of the binding properties for the relevant binding configuration in Attunity Studio Design Perspective:
Set convertAllToDistributed to true. Set logFile to provide the recovery log file dataset name.
Where log is the log file dataset name. If this parameter is not specified, then the format is:
logFile=,NORRS
Edit the CICS Procedure data source in Attunity Studio Design Perspective Configuration tab, and change the transactionSupport parameter value to 2PC or 1PC, according to the level of participation in the two-phase commit scenario.
Security
Depending on the security level on your mainframe, you may need grant the following permissions to Attunity Server in addition to the general security requirements:
READ access to the EXCI library (e.g. SYS1.CICSTS.SDFHEXCI). UPDATE authority on the IRC connection (e.g. DFHAPPL.ATYCLIEN). Execute permission on the CICS programs you want to call and all their dependant resources.
Data Types
The CICS Procedure data source supports add ADD data types. For a list of all ADD data types, see ADD Supported Data Types. For further information on mapping COBOL types to ADD data types, see COBOL Data Types to Attunity Data Types. Input parameters can only be simple (real) data types. Output fields can be of simple types and variants (COBOL REDEFINES).
CICS Procedure Data Source 62-5
Defining the CICS Procedure Data Source Connection Configuring the CICS Procedure Data Source
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine where you want to add your CICS procedure data source. Expand the Bindings folder. Expand the binding where you want to add the CICS procedure data source. Right-click the Data sources folder and select New Data Source. The New Data Source wizard opens:
7. 8. 9.
Enter a name for the new CICS Procedure data source in the Name field. Select CICS from the Type list. Click Next. The Data Source Connect String screen opens.
Target System: Specify the VTAM APPLID of the CICS region. Vtam NetName: Specify the VTAM netname of the IRC connection being used by the EXCI transaction. If you do not know the NetName you are using in the CICS region, ask your CICS administrator, or issue the following CEMT command:
CEMT INQ CONN STATUS: RESULTS - OVERTYPE Con(ATYS) Net(atyclien) Con(EXCG) Con(EXCS) Net(BACHCLI) TO MODIFY Ins Irc Ins Irc Ins Irc
The netname displayed on the screen is BATCHCLI (this is the default connection supplied by IBM upon installation of CICS). If you plan to use IBM defaults, then specify BATCHCLI as the Vtam_netName parameter. Otherwise, define a special connection (with EXCI protocol) and use the netname you provided there for this parameter.
Note: Attunity provides a netname ATYCLIEN, which can be used after the following procedure is carried out:
1.
Use the JCL in the NAVROOT.USERLIB(CICSCONF) member to submit the DFHCSDUP batch utility program to add the resource definitions to the DFHCSD dataset (see the IBM CICS Resource Definition Guide for further details). Or Use the instream SYSIN control statement in the NAVROOT.USERLIB(CICSCONF) member as a guide to defining the resources online using the CEDA facility.
2.
After the definitions have been added (via batch or using the CEDA facility), log on to CICS, and issue the following command to install the resource definitions under CICS: CEDA INST GROUP(ATYI)
In the Design perspective, Configuration view, expand the Machines folder. Expand the machine with your CICS procedure data source. Expand the Bindings folder and the binding with your procedure data source. Expand the Data sources folder. Right-click the CICS Procedure data source in the Configuration view, and select Open. The Configuration editor is displayed.
7. 8.
If necessary, edit the information in the Connection section. For a description, see the connection string in Defining the CICS Procedure Data Source Connection. Configure the CICS Procedure data source parameters as required. For a description of the available CICS Procedure parameters, see Configuration Properties.
Importing Metadata from COBOL Editing the XML in the Source Code
COBOL copybooks, to describe the programs COMMAREA for input and output. The copybooks need to be available by either copying them over to the computer on which you use Attunity Studio, or via FTP connection to a remote location. The names of the CICS programs to be executed via the CICS Procedure data source. A basic knowledge of the programs and their COMMAREA structure for input/output.
2. 3. 4. 5.
Expand Machine folder and then expand the machine you are using. Expand the binding where you want to import the metadata. Expand the Data sources folder. Right-click the CICS Procedure data source where you want to import the metadata, and select Show Metadata View. The Metadata tab is displayed with the data source displayed in the Metadata view.
6.
Right-click Imports, and select New Import. The New Import screen opens.
7. 8.
Enter a name for the import. The name can contain letters, number and the underscore character. Select one of the following from the Import Type list.
9.
The Add Resource dialog box opens. This screen lets you select files from the local computer, or to copy the files from another computer.
Figure 622 The Add Resources screen
11. If the files are on another computer, then right-click My FTP Sites and select Add.
12. Enter the server name or IP address where the COBOL copybooks reside and, if
not using anonymous connection, enter a valid username and password to access the computer. Once the required information is entered, the Add FTP Site screen should look like the following figure:
Figure 623 The Add FTP Site screen
computer using the username as the high-level qualifier. You can change the high-level qualifier by right-clicking the machine, and selecting Change Root Directory.
15. Select the required files for the import and click Finish to start the transfer.
The selected files are now displayed in the Get Input Files screen of the Metadata Import wizard.
16. Click Next.
Replace hyphens (-) in Replace all hyphens in either the record or field names in the record and field names with metadata generated from the COBOL with underscore underscores (_) characters. Prefix nested columns Prefix all nested columns with the previous level heading. In addition, you can specify a search string and the string that will replace this search string in the generated metadata, and whether the replacement is dependent on the case of the found string. Case sensitive Find Replace with Specifies whether to be sensitive to the search string case. Searches for the specified value. Replaces the value specified for Find with the value specified here.
Procedure Name: A name for the procedure. This name is used by Attunity Connect to access the procedure. A default, editable procedure name is automatically provided. Record Name: The record name of the I/O structure. The record is selected from a list of records, extracted from the designated COBOL copybooks. You must specify a record for each procedure.
Program Name: The name of the CICS program to be executed by the procedure. You must specify a program for each procedure.
EXCI TRANSID: The mirror transaction ID in the CICS region (default value is EXCI).
21. The fields from the selected record are displayed in the Table Details area. Check
the fields from this record that you want to use for the input and output to the program which is called by the procedure. Input can only be set for simple field types. Output can be set for all field types except for arrays (COBOL OCCURS). The following figure shows two procedures that call a program called PROG1, which expects to receive the customer key (CUST_KEY) as input and returns the CUSTOMERS record without the MKT_SEGMENT value as output:
Figure 625 The Create Procedures screen
23. The last two steps let you determine how you want to handle arrays in your
metadata, and then import the metadata. For more information, see:
Editing the <procedure> Statement Editing the <field> Statement Editing the <parameters> Statement Sample ADD Metadata
Where:
PROGRAM: The name of the program to run in the COMMAREA. TRANSID: The TRANSID for the program. The TRANSID is the mirror transaction ID in the CICS region, such as EXCI, or a copy of this transaction. If a value is not specified, then EXCI is used. COMMAREASIZE: The size required to hold the output from the program in the COMMAREA buffer. If a value is not specified, the size of the record is dynamically determined. Setting this value allows greater control over the COMMAREA size in case all the data is mapped. OUTPUTOFFSET: The offset in the COMMAREA buffer where the mapping of the stored procedure fields begins. If not specified, the output offset is dynamically set to immediately follow the input.
Where:
EOS_VALUE: Specifies the value that signals the end of the program, assuming that the program has a context. The value assigned can be either a string or an integer value, that when encountered, causes the program to end. Use this property when you need to make consecutive calls to the CICS program in order to return multiple records and the program can provide a context field to be passed as an input on the next call or has its own context. If you specify more than one EOS_VALUE, then a logical OR condition is implied. If an EOS_VALUE is specified neither for a field nor a parameter, then the CICS program is assumed not to have a context and only one row is returned. If a value is specified both for a field and a parameter, then the first value encountered causes the program to end.
OFFSET: The offset attribute allows you to control the field offset of an output field within the COMMAREA buffer. If a value is not specified for the offset, it is dynamically evaluated to immediately follow the preceding field. If an offset is not specified for the first output field, the offset is dynamically evaluated to be either immediately following the last input parameter, or according to the output offset attribute in the procedure <dbCommand>. Note that by setting the offset of an input parameter and output field to the same value, you can map an input/output area.
Where:
EOS_VALUE: Specifies the value that signals the end of the program, assuming that the program has a context. The value assigned can be either a string or an integer value, that when encountered, causes the program to end. Use this property when you need to make consecutive calls to the CICS program in order to return multiple records and the program can provide a context field to be passed as an input on the next call or has its own context. If you specify more than one EOS_VALUE, then a logical OR condition is implied. If an EOS_VALUE is specified neither for a field nor a parameter, then the CICS program is assumed not to have a context and the program will only be executed once and one row returned. If a value is specified both for the parameter and a field, then the first value encountered causes the transaction to end.
REAPPLY: The original value supplied for the parameter is reapplied when the program modifies the parameter value. This attribute is only relevant when executing stream-type programs.
OFFSET: The offset attribute allows you to control the field offset of an input field within the COMMAREA buffer. If a value is not specified for the offset, it is dynamically evaluated to immediately follow the preceding parameter. If an offset is not specified for the first input field, the offset is dynamically evaluated to zero. Note that by setting the offset of an input parameter and output field to the same value, you can map an input/output area.
Part X
Adapters Reference
This part contains the following topics:
CICS Application Adapter (z/OS Only) COM Adapter (Windows Only) Pathway Application Adapter (HP NonStop Only) IMS/TM Adapter (z/OS Only) Legacy Plug Application Adapter Tuxedo Application Adapter (UNIX and Windows Only)
63
CICS Application Adapter (z/OS Only)
This section includes the following topics:
Overview Transaction Support Configuration Properties Defining the CICS Application Adapter Setting Up CICS Application Metadata Testing CICS Application Adapter Interactions
Overview
The CICS Application Adapter allows users of the AIS application engine to activate CICS programs from any of the supported AIS application interface. These include JCA, .NET, COM, XML and 3GL. The CICS Application Adapter accepts client requests, constructs a COMMAREA, activates the CICS program using EXCI, and translates the response back to XML. Each program to be activated must be predefined in the Attunity Data Dictionary (ADD). The COMMAREA layout is usually imported from COBOL copybooks. Several options exist regarding unit-of-work (UOW) scope ranging from each program activation residing in its own UOW, to larger UOWs including other data sources in a two-phase commit transaction.
CICS version 4.1 or higher. CICS Transaction Server version 1.3 or higher.
Supported Features
The CICS application adapter supports the following key features:
Activates any COMMAREA-based CICS program Supports zero-phase commit, one-phase commit, and two-phase commit transactions
All AIS data types and constructs are supported. This includes OCCURS clauses and REDEFINES.
Environmental Prerequisites
AIS uses EXCI to interface to CICS. EXCI requires some set up:
IRC must be open. Use CEMT I IRC from the CICS screen to check your IRC status. If in closed state, set it to open. A specific connection must be set up. Use CEMT I CONNECTION to get the list of available connections. Note that you can only use specific connections which have a VTAM netname associated with them. The default available on most systems is BATCHCLI. Attunity provides a JCL for defining an Attunity connection. See the CICSCONF member in the USERLIB. An EXCI mirror transaction ID must be available. The default on most systems is transaction ID EXCI. You can use the CEMT I TRA PROG(DFHMIRS) to get the list of EXCI transaction IDs available on your system.
Limitations
3270 programs are not supported Conversational transactions are not supported The CICS adapter requires the use of a specific connection; generic connections are not supported (e.g. the default EXCS connection is supported via NETNAME BATCHCLI, while the default generic connect EXCG is not supported). REDEFINES are supported on both input and output as the AIS variant metadata construct. However, when specifying a variant without a selector field in the program output, only the first variant case is returned.
Transaction Support
In the context of transaction1 support, the CICS Application Adapter can be configured in one of three ways:
Zero-phase commit adapter (default): Each CICS program invocation resides within its own unit of work. CICS programs are activated using EXCI with SYNCONRETURN. One-phase commit adapter: Requires CICS TS 1.3 or higher. Requires RRS to be installed and running. CICS programs are activated using EXCI with NOSYNCONRETURN. The client indicates a commit or a rollback using the appropriate client interface. A commit request triggers an ATRCMIT call. A rollback request triggers an ATRBACK call. This allows the client application to control the unit of work boundaries. When working with 1PC, it is important to correctly configure the time-out of your EXCI mirror transaction. The DTIMEOUT parameter in the CEDA transaction definition must exceed the maximum expected transaction duration. The default EXCI transaction is usually configured with a DTIMEOUT of 10 seconds, which may be problematic in terms of its short duration.
The term transaction in this section refers to the unit of work in the database sense of the word. This should not be confused with the use of the term transaction in the CICS world.
Two-phase Commit adapter: Requires CICS TS 1.3 or higher. Requires RRS to be installed and running. The Attunity server-started task communicates with the NAVCRM server to receive an RRS context ID. All CICS program invocations are activated as part of that RRS context. The governing transaction manager (usually an application server transaction manager) views this application adapter as a 2PC resource manager. The required mechanisms for preparing the transaction, recovery of the transaction after failure, transaction status inquiries, are all handled by the application adapter.
Configuration Properties
The following parameters can be configured for the CICS adapter in the Attunity Studio Design perspective, Configuration view, Configuration Properties editor. For information on how to add adapters to Attunity Studio, see Adding Application Adapters.
exciTransid: The four-character EXCI MRO transaction ID (program DFHMIRS). The IBM default for the EXCI transaction ID is EXCI. targetSystemApplid: The VTAM applid of the CICS target system.
Note: You can determine this value by activating the CEMT transaction on the target CICS system. On the bottom right corner of the screen appears the legend APPLID=target_system.
transactionSupport: The level of Transaction support for this adapter. To set transaction support, refer to Transaction Support. vtamNetnamg: The VTAM netname of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system. You can issue to CEMT the following command:CEMT INQ CONNThe netname is BATCHCLI to get the list of connections defined on your system. The default connection supplied by IBM is called has a VTAM_netname of BATCHCLI.
Note:
The AIS installation includes a JCL for defining a CICS connection to be used with AIS. If you choose to use the AIS connection (netname ATYCLIEN) perform the following procedure:
Either use the JCL in the NAVROOT.USERLIB(CICSCONF) member to submit the DFHCSDUP batch utility program to add the resource definitions to the DFHCSD dataset (see the IBM CICS Resource Definition Guide for further details) or use the instream SYSIN control statements in the NAVROOT.USERLIB(CICSCONF) member as a guide to defining the resources online using the CEDA facility. After the definitions have been added (via batch or using the CEDA facility), log on to CICS and issue the following command to install the resource definitions under CICS:
CEDA INST GROUP(ATYI)
Defining the CICS Application Adapter Connection Configuring the CICS Application Adapter Setting Up CICS Application Metadata Refining CICS Application Adapter Metadata
In the Design perspective Configuration view, expand the Machines folder. Expand the machine where you want to add the CICS adapter. Expand the Bindings folder. Expand the binding where you want to add the CICS adapter. Right-click the Adapters folder and select New Adapter. The New Adapter dialog box is displayed.
7.
The word event is a reserved word and cannot be used when naming an application adapter.
8. 9.
Expand the Machines folder. Expand the machine with your CICS adapter. Expand the Bindings folder. Expand the binding with the CICS adapter. Expand the Adapters folder. Right-click the CICS adapter that you want to work with and select Open. The adapter Configuration editor is displayed.
8. 9.
Configure the adapter Configuration parameters as required. For a description of the available parameters, see Configuration Properties. Click Finish.
A list of interactions. Each interaction corresponds to a single CICS program to be invoked. It includes details such as the CICS 8-character program name, and references to an input and output record describing the COMMAREA program activation. A schema section, including a group of record definitions, usually derived from a COBOL copybook, describing the layout and structure of the COMMAREA input and output.
If COBOL copybooks describing the COMMAREA layout are available, you can import the metadata using the import utility in the Design Perspective Metadata tab in Attunity Studio. See also Importing Attunity Metadata from COBOL
and the output. During the import process, users therefore usually provide the same record name for input and output. Some further manual refinement can be done outside the import process, as described in Setting Up CICS Application Metadata. The following information is needed during the import:
COBOL copybooks which are copied to the machine running Attunity Studio as part of the import procedure. The names of the CICS programs to be executed via the procedure data source driver.
1. 2.
To define CICS application adapter metadata Open Attunity Studio. In the Design perspective, Configuration view, right-click the adapter and select Edit Metadata. The Metadata tab is displayed with the CICS Adapter displayed in the Metadata view.
3. 4. 5. 6. 7.
Right-click Imports under the adapter in the view and select New Import. Enter a name for the import. The name can contain letters, numbers, and the underscore character. Select CICS Import Manager as the import type. Click Finish. The Metadata Import Wizard is displayed. Click Add in the Import Wizard to add COBOL copybooks. The Add Resource screen is displayed, providing the option of selecting files from the local machine, or copying the files from another machine using FTP.2 This figure shows the Add Resource screen.
8.
2
If the files are on another machine, then right-click My FTP Sites and select Add. If the metadata is provided in a number of COBOL copybooks, with different filter settings (such as whether the first 6 columns are ignored or not), first import the metadata from copybooks with the same settings, and then import the metadata from the other copybooks.
9.
Set the FTP data connection by entering the server name where the COBOL copybooks reside and, if not using anonymous access, enter a valid username and password to access the machine. using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory. This figure shows the Add Resource screen detailing the FTP sites
10. To browse and transfer files required to generate the metadata, access the machine
11. Select the files to import and click Finish to start the transfer.
The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns together with a COBOL copybook that ignores the first six columns. In this type of case, repeat the import process. You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks. The selected files are displayed in the Get Input Files screen.
12. Click Next. The Apply Filters screen is displayed. Figure 635 Apply Filters Screen
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type. Compiler source: The compiler vendor. Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Prefix nested column: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity metadata, is replaced with an underscore. Case sensitive: Specifies whether to consider case sensitivity or not. Find: Searches for the specified value. Replace with: Replaces the value specified for in the Find field with the value specified here.
14. Click Next. The Add Interactions screen is displayed. Figure 636 Add Interactions Screen
15. Click Add to add interactions for the CICS Adapter. You can change the default
name that is specified for the interaction and then specify the mode of the interaction, which can be one of the following:
sync-receive: A response is expected from the program. That is, the program returns a result. sync-send: The program expects an input. sync-send-receive: The program expects an input and the program returns a result. This is the default mode.
You specify an input record used by the program associated with the interaction from the dropdown list in the Input column. This list is generated from the COBOL programs specified at the beginning of the procedure. Select a relevant record for the interaction.
Note:
You must specify an input record for each interaction before clicking Next. If the interaction does not require an input record (sync-receive-mode), the record specified here is ignored.
If the mode is either sync-receive or sync-send-receive, you must also specify an output record used by the program from the dropdown list in the Output column. Select a relevant record for the interaction. Finally, for each interaction, specify the program that you want associated with the interaction.
Note:
This example shows an interaction that calls a program called CUST, which expects to receive input and returns a result.
The Import Metadata screen, lets you import the metadata to the z/OS machine or leave the generated metadata on the Attunity Studio machine, to be imported later.
63-11
17. Select Yes to transfer the metadata to the mainframe machine and click Finish.
After performing the import, you can view the metadata in the Metadata view. You can also make any fine adjustments to the metadata and maintain it, as necessary. See Working with Application Adapter Metadata.
Expand the Bindings folder and then expand the binding with the adapter metadata you are working with. Expand the Adapters folder and then right-click the data source for which you want to manage the metadata. Right-click the required adapter and select Show Metadata View. The Metadata view opens.
5.
6. 7.
Under Schema right-click the relevant record and select Copy. Right-click Schema and select Paste. You are prompted to provide a new name for the record to be replicated.
8. 9.
Add _output (or another appropriate differentiation) to the end of the record name and click OK. Under Interactions, double click the imported interaction(s).
10. Modify the Output to reflect the name of the replicated record.
At this point you can start refining the input and output records separately.
11. To refine the input record:
Double-click the input record. For input fields, optionally, provide a default value by specifying the default property in the Property sheet. The default value is used if the client application does not provide a default value as part of the request. For output fields, in the Property sheet, ensure that the private field is set to true.
12. To refine the output record, in the Property sheet, ensure that the private field is
set to false.
Note:
You can also use this technique to hide output fields that are of no interest to the client application.
Expand the Interactions folder. Right-click the Interaction you want to test and select Test. The Test Interaction wizard is displayed.
4.
5.
Specify any values for the parameters as necessary, and click Next. The test result is displayed.
6.
Click Finish.
63-13
64
COM Adapter (Windows Only)
This section includes the following topics:
Overview Defining COM Data Types Registering the COM Application Defining the COM Application Adapter Setting Up COM Application Interactions Defining COM Data Types
Overview
The COM Application Adapter provides connectivity to simple COM-based applications. COM objects are defined with interfaces, which group public methods into sets. The COM application adapter treats each COM method as an interaction, specified in an adapter definition. The definition functions as the glue linking the COM application adapter and the COM object accessed by the adapter. This adapter definition provides the run-time executable of the adapter with definitions for the following:
The COM object the adapter accesses. The interactions/methods the adapter invokes (the COM adapter can run interactions with up to 10 parameters). The properties of the COM object that are accessible to the adapter. The parameters of the COM object.
Data Types
The following table lists the supported COM data types and their equivalent data types in AIS:
Table 641
COM Adapter Data Types Mapping Value 16 2 3 20 4 5 6 7 8 10 11 14 17 18 19 21 22 23 29 25 30 31 C/Windows Type char short long __int64 float double CY DATE BSTR SCODE VARIANT_BOOL DECIMAL BYTE USHORT ULONG ACX Generated Type type="int" nativeType="int1" type="int" nativeType="int2" type="int" nativeType="int4" type="int" nativeType="int8" type="float" type="double" N/A type="string" type="int" nativeType="ole_date" type="string" type="int" nativeType="uint4" type="Boolean" type="ole_decimal" type="int" nativeType="uint1" type="int" nativeType="uint2" type="int" nativeType="uint4" N/A type="string" type="int" nativeType="int4" type="int" nativeType="uint4" type=nameOfUserDefinedTty pe type="int" nativeType="uint4" type="string" type="string"
COM Named Type VT_I1 VT_I2 VT_I4 VT_I8 VT_R4 VT_R8 VT_CY VT_DATE1 VT_BSTR VT_ERROR VT_BOOL VT_DECIMAL2 VT_UI1 VT_UI2 VT_UI4 VT_UI8 VT_INT VT_UINT VT_USERDEFINED3 VT_HRESULT VT_LPSTR VT_LPWSTR
1 2 3
struct HRESULT
char * wchar_t*
Dates are interpreted according to the user defined locale definitions. Decimal does not support the ByReference attribute. Defining a user-defined data type is described below.
Open Attunity Studio. In the Design perspective Configuration view, expand the Machines folder. Expand the machine where you want to add the COM adapter. Expand the Bindings folder. Expand the binding where you want to add the COM adapter.
Note:
6.
Right-click the Adapters folder and select New Adapter. The New Adapter dialog box is displayed.
7. 8. 9.
Enter a name for the adapter in the Name field. Select COM from the Type list. Click Finish.
where adapter is the name specified in the binding configuration for the adapter. An XML file called answer.xml is generated with the following content:
<autogen ProgId=sample_Prog_Id /> <autogen ProgId=sample_Prog_Id typeLib=
ignoreList=Equals,GetHashCode,GetType,ToString/>
where:
ProgId: The program id of the COM object, as defined in the Windows registry. typeLib (Optional): A typeLib that overrides the default (which is the one held in the registry). IgnoreList (Optional): A comma delimited (case sensitive) list of functions to be ignored upon adapter schema generation. It defaults to the internal interfaces contributed by.NET interop.
2.
Change sample_Prog_Id to the program id of the COM object, as defined in the Windows registry. For example: <autogen ProgId=trig.TrigCls />
3.
Import the definition to the repository: Nav_Util autogen adapter answer.xml where adapter is the name specified in the binding configuration for the adapter.
A list of the interactions that correspond to methods found in the COM object.
The definition uses the XML protocol described in Application Adapter Definition.
EntryRef: The name of the method to be invoked within that object. IID: The UUID of a user-defined type. This attribute is used for user-defined data types only. libIID: The UUID of the library in which the user-defined data type is defined. This attribute is used for user-defined data types only. ObjectRef: A ProgID or UUID of the COM to which this input record refers. ParamCount: The number of parameters passed to that method.
Usage: Explains what the COM adapter is about to do with this field: InstanceTag: Names an object instance. Property: Treats the field as a property. Parameter: Passes the field value to/from a method.as a parameter. RetVal: Specifies that the field will hold the return value of a method. COMtype: Specifies the data type of the field as recognized by COM, using explicit COM enumeration values (for details, see Data Types.
Note:
After performing the import, you can view the metadata in the Metadata tab. You can also make any fine adjustments to the metadata and maintain it, as necessary. For details, see Adapter Metadata General Properties.
Running NAV_UTIL AUTOGEN against this code produces the following definition:
record name=PersonRecord IID={F81A190B-F903-424F-898D-9F23B7BD5EB6} libIID={C140C9C8-0F9C-41DA-ADBA-B367DA66791B}> <field name=ID type=int nativeType=int2 required=true COMtype=2/> <field name=firstName type=string nativeType=string required=true COMtype=8/> <field name=lastName type=string nativeType=string required=true COMtype=8/> <field name=birthDate type=date nativeType=ole_date required=true COMtype=7/> </record>
65
IMS/TM Adapter (z/OS Only)
This section includes the following topics:
Overview Transaction Support Configuration Parameters Defining the IMS/TM Application Adapter Setting Up the IMS/TM Application Metadata
Overview
You can execute a program via IMS/TM using the IMS/TM Application Adapter.
Transaction Support
The IMS/TM Application Adapter supports Two-phase Commit and can fully participate in a distributed Transaction when the transaction environment property convertAllToDistributed is set to true. To use the IMS/TM application adapter with 2PC, you must have RRS installed and configured.
Note:
If RRS is not running, the Data Source can participate in a distributed transaction, as the only one-phase commit data source, if the logFile parameter is set to NORRS in the Transaction section of the binding properties for the relevant binding configuration, in the Attunity Studio Design perspective Configuration view. The XML representation is as follows: <transactions logFile=log,NORRS />
where log is the high-level qualifier and name of the log file. If this parameter is not specified, the format is the following: <transactions logFile=log,NORRS /> That is, the comma must be specified. For further details about setting up a data source to be one-phase commit in a distributed transaction, refer to the CommitConfirm Table. To use two-phase commit capability to access data on the z/OS machine, define every library in the ATTSRVR JCL as an APF-authorized library.
Note:
To define a DSN as APF-authorized, in the SDSF screen enter the command: /setprog apf,add,dsn=navroot.library,volume=ac002 where ac002 is the volume where you installed AIS and NAVROOT is the high-level qualifier where AIS is installed. If the AIS installation volume is managed by SMS, when defining APF-authorization enter the following command in the SDSF screen: /setprog apf,add,dsn=navroot.library,SMS Make sure that the library is APF-authorized, even after an IPL (reboot) of the machine.
Configuration Parameters
The following parameters can be configured for the IMS/TM Application Adapter in Attunity Studio Design perspective, Configuration view, Configuration Properties editor. For information on how to add adapters to Attunity Studio, see Adding Application Adapters.
cacheLastTpipe: This parameter specifies whether or not to cache the last transaction pipe used. cacheXcfConnection: This parameter specifies whether or not to cache the XCF connection information. maxSessions: This parameter specifies the maximum number of sessions allowed. The default value is 5. racfGroupId: This parameter specifies the RACF facility group identification. racfUserId: This parameter specifies the RACF facility user identification.
tpipePrefix: This parameter specifies the transaction pipe prefix used to associate between the Transaction and the transaction pipe it is using. The default value is ATTU. xcfClient: This parameter specifies the Cross System Coupling Facility client to which the connection belongs. xcfGroup: This parameter specifies the Cross System Coupling Facility collection of XCF members to which the connection belongs. A group may consist of up to eight characters, and may span multiple systems. xcfImsMember: This parameter specifies the Cross System Coupling Facility group member.
Defining the IMS/TM Application Adapter Connection Configuring the IMS/TM Application Adapter
In the Design perspective Configuration view, expand the Machines folder. Expand the machine where you want to add the IMS/TM adapter. Expand the Bindings folder. Expand the binding where you want to add the IMS/TM adapter. Right-click the Adapters folder and select New Adapter. The New Adapter dialog box is displayed.
7.
8. 9.
Expand the Machines folder. Expand the machine with your IMS/TM adapter.
IMS/TM Adapter (z/OS Only) 65-3
4. 5. 6. 7.
Expand the Bindings folder. Expand the binding with the IMS/TM adapter. Expand the Adapters folder. Right-click the IMS/TM adapter that you want to work with and select Open. The adapter Configuration editor is displayed.
8.
Configure the adapter parameters as required. For a description of the available parameters, see Configuration Parameters.
COBOL copybooks which are copied to the machine running Attunity Studio as part of the import procedure. The names of the IMS/TM programs to be executed via the procedure driver.
To define IMS/TM adapter metadata 1. In the Configuration view, right-click the Data Source and select Edit Metadata. The Metadata tab is displayed with the IMS/TM Adapter displayed in the Metadata view.
2. 3. 4. 5. 6.
Right-click Imports under the data source view and select New Import. Enter a name for the import. The name can contain letters, numbers, and the underscore character. Select IMS/TM Import Manager as the import type. Click Finish. The Metadata Import Wizard is displayed. Click Add in the Import Wizard to add COBOL copybooks. The Add Resource screen is displayed. In this screen, you select files from the local machine or copy the files from another machine using FTP.
7. 8.
If the files are on another machine, then right-click My FTP Sites and select Add. Set the FTP data connection by entering the server name where the COBOL copybooks reside, and if not using anonymous access, enter a valid username and password to access the Machine.
9.
To browse and transfer files required to generate the metadata, access the machine using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory. This figure shows the Add Resource screen detailing the FTP sites.
10. Select the files to import and click Finish to start the transfer.
The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns together with a COBOL copybook that ignores the first six columns. In this type of case, repeat the import process. You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks. The selected files are displayed in the Get Input Files screen.
11. Click Next. The Apply Filters screen is displayed. 12. Apply filters to the copybooks, as needed. Figure 655 Apply Filters Screen
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type. Compiler source: The compiler vendor. Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Prefix nested column: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity metadata, is replaced with an underscore.s Case sensitive: Specifies whether to consider case sensitivity or not. Find: Searches for the specified value. Replace with: Replaces the value specified for in the Find field with the value specified here.
13. Click Next. The Add Interactions screen is displayed. Figure 656 Add Interactions Screen
14. Click Add to add interactions for the IMS/TM Adapter. You can change the
default name that is specified for the interaction and then specify the mode of the interaction, which can be one of the following:
sync-receive: A response is expected from the program. That is, the program returns a result. sync-send: The program expects an input. sync-send-receive: The program expects an input and the program returns a result. This is the default mode.
You specify an input record used by the program associated with the interaction from the drop-down list in the Input column. This list is generated from the COBOL programs specified at the beginning of the procedure. Select a relevant record for the interaction.
Note:
You must specify an input record for each interaction before clicking Next. If the interaction does not require an input record (sync-receive-mode), the record specified here is ignored.
If the mode is either sync-receive or sync-send-receive, you must also specify an output record used by the program from the drop-down list in the Output column. Select a relevant record for the interaction. Finally, for each interaction, you specify the program that you want associated with the interaction.
Note:
The maxSegmentSize property enables dynamically splitting large messages into smaller segments. By default the largest segment size is 32763. This value can be modified by setting the maxSegmentSize property. However, the logic of the IMS/TM Transaction must correspond to this behavior. The transaction must perform a GU call followed by a series of GN calls in order to compile the entire input message.
Note:
There is no effect on the output message of the transaction which can be larger that 32K and composed of several segments (the OTMS C/I interface already performs the task of assembling the output segments into a single buffer).
An interaction that calls a program called STUD, which expects to receive input and returns a result is displayed.
16. Select the first data field to be used for inputs and outputs. You can select one of
the following:
: Select this and enter a line number for both the First input field and the First output field. The data at that line number will be the first data used for the input or output. Right-click Schema and select New record. Manually mark the first data field of the transaction following the LL ,ZZ and TRANSNAME fields: When you select this option, select the first line to use for the imports and outputs from the field below.
The Import Metadata screen, lets you import the metadata to the mainframe machine or leave the generated metadata on the Attunity Studio machine, to be imported later.
Figure 659 Import Metadata Screen
18. Select Yes to transfer the metadata to the mainframe machine and click Finish.
Note:
After performing the import, you can view the metadata in the Metadata tab. You can also make any fine adjustments to the metadata and maintain it, as necessary. For more information, see Adapter Metadata General Properties.
66
Legacy Plug Application Adapter
This section includes the following topics:
Overview Configuration Parameters Defining the Legacy Plug Application Adapter Setting Up Legacy Application Metadata
Overview
The Legacy Plug Application Adapter provides access to legacy applications using interfaces such as XML, JCA and COM.
Note:
The Legacy Plug application adapter enables executing a program via JCA, XML or on a Microsoft Windows platform from a COM-based application, unlike the Procedure Data Source (Application Connector), which enables an SQL front end to the program.
If the procedure returns an array, you must use the Legacy Plug application adapter and not the Procedure Data Source.
Configuration Parameters
The following parameters can be configured for the Legacy Plug adapter in the Attunity Studio Design perspective, Configuration view, Configuration Properties editor. For information on how to add adapters to Attunity Studio, see Adding Application Adapters.
dllName: (Optional) This parameter specifies the path and name of the DLL. If the DLL information is not specified here it must to be specified for each interaction in the Adapter Definition. triggerDllName: (Optional) This parameter specifies the path and name of the DLL which is used to trigger the adapter. For further details, refer to Configuring a Trigger for the Legacy Plug Adapter. triggerSymbolName: (Optional) This parameter specifies the function in the DLL that triggers the adapter. If a value is not specified, triggerSymbolName defaults to the triggerDllName value. For further details, refer to Configuring a Trigger for the Legacy Plug Adapter.
Defining the Legacy Plug Application Adapter Connection Configuring the Legacy Plug Application Adapter
In the Design perspective Configuration view, expand the Machines folder. Expand the machine where you want to add the Legacy Plug adapter. Expand the Bindings folder. Expand the binding where you want to add the Legacy Plug adapter. Right-click the Adapters folder and select New Adapter. The New Adapter dialog box is displayed.
7.
8. 9.
Expand the Machines folder. Expand the machine with your Pathway adapter. Expand the Bindings folder. Expand the binding with the Pathway adapter. Expand the Adapters folder. Right-click the Legacy Plug adapter that you want to work with and select Open. The adapter Configuration editor is displayed.
8. 9.
Configure the adapter parameters as required. For a description of the available parameters, see Configuration Parameters. Click Finish.
Importing Attunity Metadata from PCML Files Defining Interactions and Records Configuring a Trigger for the Legacy Plug Adapter
To import Legacy Plug Adapter metadata 1. In the Configuration view, right-click the adapter and select Edit Metadata. The Metadata tab is displayed with the Legacy Plug Adapter displayed in the Metadata view.
2. 3. 4. 5. 6.
Right-click Imports under the adapter and select New Import. Enter a name for the import. The name can contain letters, numbers, and the underscore character. Select Legacy plug Import Manager Using PCML Files as the import type. Click Finish. The Metadata Import Wizard is displayed. Click Add in the Import Wizard to specify the PCML files. The Add Resource screen is displayed. In this screen you select files from the local machine or copy the files from another machine using FTP.
7. 8.
If the files are on another machine, then right-click My FTP Sites and select Add. Set the FTP data connection by entering the server name where the PCML files reside and, if not using anonymous access, enter a valid username and password to access the machine. To browse and transfer files required to generate the metadata, access the machine using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory.
9.
10. Select the files to import and click Finish to start the transfer.
Note:
11. Click Next. The Apply Filters screen is displayed. You do not have to do anything
in this step.
12. Click Next. The source files are analyzed. When this is done, the Select Interactions
step is displayed.
13. Select the interactions for which you want to import metadata, and click Next.
If you are importing data types that are not supported by PCML (Date, Time, Timestamp, Pointer, Procedure Pointer, 1-byte Integer or 8-byte Unsigned Integer), a message indicating an error in the PCML file is displayed. This error message can be ignored since AIS deals with these data types independently of PCML when they are extracted from the PCML file. The Import Metadata window lets you import the metadata to the computer where the application adapter is defined or leave the generated metadata on the Attunity Studio machine, to be imported later.
14. Click Next to display the Import Metadata step.
15. Select Yes to import the metadata now or click No to leave the generated metadata
on the Attunity Studio machine and click Finish. The Legacy Plug Adapter Configuration Properties editor opens. New interactions and schema records are added to the Metadata view.
In the Design perspective, Metadata view, expand the Interactions folder for the Legacy Plug adapter with the Metadata you are working with. Right-click the interaction you want to define and select Refresh. Right-click the interaction and select Open. The Interactions editor for the selected interaction is displayed.
5.
dllName (Optional): The path and name of the DLL or program (when the value of symbolName is @main). If the information is not specified here, then it must be specified in the binding, as described in Defining the Legacy Plug Application Adapter. If the value of symbolName is @main, the value of dllName is a program name, including the full path.
symbolName (Optional): The function in the program to be executed. If a value is not specified, symbolName defaults to the interaction name. If the value of symbolName is @main, the value of dllName is a program name, including the full path. Working with multiple entry points requires that aliases be constructed for any entry point that is not the main entry point of the program.
Note:
For z/OS systems, an alias is specified for a load module within the load library (or PDS). Each new alias creates an additional entry in the load library directory pointing to an additional entry point within a load module. A load module can have many aliases, each pointing to a different entry point within that module. An alias is established during the link-edit step of the build of the module. For example, using the MATHSAMP sample supplied with AIS, we can set up the link-edit control cards as follows:
//SYSLIN DD * INCLUDE SYSLIB(MATHSAMP ALIAS MATHSTRU ALIAS MATHASTR ALIAS MATHVARI ALIAS MATHINOU ALIAS MATHSTRM ALIAS MATHEOSV ENTRY MATHSIMP NAME MATHSIMP(R) /*
There are seven entries in the load library directory (one main entry name and six aliases), corresponding to each of the seven entry points in the load module.
In the Design perspective, Metadata view, expand the Schema for the Legacy Plug adapter with the Metadata you are working with. Right-click the record you want to define and select Refresh. Right-click the record and select Open to define any parameters to open the Schema Record editor.
The schema definitions define the input and output structure fields and records for each interaction. The field and record parameters contain information regarding the method (using the mechanism attribute) by which this field is passed or received by the procedure, and the argument number of the procedure (using the paramNum attribute).
5.
Enter the paramNum for the record or any field in the record as relevant. The paramNum attribute can be specified as 0 to indicate it is a return value, 1 to indicate it is first argument, and so on. If paramNum is specified at the record level, it cannot be specified for any of the record members (at the field level). Enter the mechanism by editing the source XML for the adapter. The mechanism is the method by which the field is passed or received by the procedure. The mechanism attribute can be set to byValue and byReference. For outer-level (non-nested) parameters, structure parameters (for the structure itself, and not structure members), and variant parameters, the default value is byReference. When a parameter is used for both input and output, the mechanism must be set as the same for both the input and the output. For example:
<schema version=1.0> <record name=MATH_INOUT_OUT> <field name=SUM1 type=int paramnum=4/> <field name=SUBTRACT type=int paramnum=1/> <field name=MULTIPLY type=int paramNum=2/> <field name=DIVIDE type=int paramNum=3/> </record> <record name=MATH_RETURN_OUT> <field name=SUM1 type=int paramNum=0 mechanism=byValue/> <field name=SUBTRACT type=int paramNum=1/>
6.
<field name=MULTIPLY type=int paramNum=2/> <field name=DIVIDE type=int paramNum=3/> </record> </schema>
where:
pContext: Provides a way for the trigger to keep some context. For example, if the connect trigger establishes a connection with a back end application, it may want to keep a handle to that connection to be used with the other triggers. The pPrivate pointer in the pContext structure is used to keep that context. The context structure is allocated by Attunity Connect and passed to the trigger with every call. The pPrivate pointer can be used by the trigger for any purpose. The other exception fields can be used for error reporting. peEvent: A pointer to an enumeration that specifies what event occurred. This is passed by reference to make it easier for a COBOL implementation. Note that the szException text must be one of the following exceptions to allow the client application to behave correctly:
66-11
server.resourceLimit server.redirect client.noSuchResource client.authenticationError client.noSuchInteraction client.noSuchConnection server.notImplemented server.xaProtocolError server.xaUnknownXID server.xaDuplicateXID server.xaInvalidArgument client.autogenRejected server.xaTransactionTooFresh server.resourceNotAvailable client.authorizationError server.configurationError
Further information about these exceptions is documented in the Attunity Developer SDK. Sample In the following sample, the trigger allows the math_all_structs function to pass back an error condition with a text message when the second input parameter is zero (which would cause an error when trying to divide the value specified as the first input parameter by zero).
#ifdef WIN32 # define EXPORT_SYMBOL __declspec(dllexport) #else # define EXPORT_SYMBOL #endif #include <stdio.h> #include <string.h> #include "gap.h" /* Global variable used to keep the context in case of an exception */ static GAP_LP_TRIGGER_CONTEXT *pGlobalContext = NULL; typedef struct { int oper1 ; int oper2 ; } MATH_IN_STRUCTURE ; typedef struct { int sum ; int subtract ; int multiply ; int divide ; } MATH_STRUCTURE ;
EXPORT_SYMBOL GAP_STATUS trigger_sample(GAP_LP_TRIGGER_CONTEXT *pContext, GAP_LP_ TRIGGER_EVENT *peEvent) { /* On every connect the context changes, so keep it globally */ if (*peEvent == GAP_LP_TRIGGER_EVENT_CONNECT_) pGlobalContext = pContext; return GAP_STATUS_OK; } EXPORT_SYMBOL void math_all_structs(MATH_STRUCTURE *m_struct, MATH_IN_STRUCTURE *m_in) { /* This shows how an error condition is reported */ if (m_in->oper2 == 0) { pGlobalContext->eStatus = GAP_STATUS_ERROR; strcpy(pGlobalContext->szException, "client.requestError"); strcpy(pGlobalContext->szExceptionText, "division by zero error"); return ; } m_struct->sum = m_in->oper1 + m_in->oper2 ; m_struct->subtract = m_in->oper1 - m_in->oper2 ; m_struct->multiply = m_in->oper1 * m_in->oper2 ; m_struct->divide = m_in->oper1 / m_in->oper2 ; }
66-13
67
Pathway Application Adapter (HP NonStop Only)
This section includes the following topics:
Overview Transaction Support Pathway Adapter Configuration Parameters Defining the Pathway Application Adapter Setting Up Pathway Application Metadata
Overview
The Pathway environment is used to manage online Transaction processing applications. You can execute a program via a Pathway using the Pathway application adapter. The application adapter supports TMF transactions, enabling a connection between Enscribe, SQL/MP and Pathway in a single transaction.
Note:
If a TMF transaction is started before a Pathway server is activated, all changes made by that server are also part of the TMF transaction.
Transaction Support
An ACX request can explicitly specify transaction tokens (transactionStart, transactionCommit, transactionRollback) that cause a TMF Transaction to be started, committed or aborted. All Pathway servers activated after a transaction is started run under that TMF transaction. This enables full control over the transaction boundary. By using persistent connections you can also have the TMF transaction span more than one ACX request.
Note:
The ACX request can be generated from any supported front end application: JCA, COM or an XML file using the ACX protocol. For more information, see Implementing an Application Access Solution.
If no transaction tokens are provided in the ACX request, the ACX dispatcher assumes you are working in autocommit mode. In this case, the dispatcher calls the adapter to start a transaction before the first interaction is run and commits the transaction after the last interaction is run. Thus, each ACX request is a single TMF transaction; whether it is a single interaction request or a batch request with several interactions in it. If you do not want a TMF transaction to be started by AIS (for example, with Pathway servers that control the transactions themselves (start and commit a transaction), then transaction support should be disabled in the adapter configuration. TMF transactions are coordinated across the server so that you can use the same server to run a Pathway server as well as access SQL/MP and Enscribe audited files directly from Attunity Connect, all within the same TMF transaction. The dispatcher will rollback a TMF transaction if the Pathway server returns SERVERCLASS_SEND with a non-zero status.
Note:
An error condition that should cause a rollback of the TMF transaction should be handled by the Pathway server returning the actual error.
pathmonProcess: This parameter specifies the Pathway monitor process name. This parameter must be specified for each interaction in the transaction component of the adapter definition. transaction: This parameter specifies whether or not a TMF transaction is started when activating a Pathway interaction, either explicitly by the user in the ACX XML request document, or implicitly by the server using the autocommit feature. When transaction is set to false, a TMF Transaction is not started, even if the user explicitly specifies a startTransaction statement in the ACX XML request document. This is useful when accessing Pathway servers that start their own TMF transaction.
Defining the Pathway Application Adapter Connection Configuring the Pathway Application Adapter
In the Design perspective Configuration view, expand the Machines folder. Expand the machine where you want to add the Pathway adapter. Expand the Bindings folder. Expand the binding where you want to add the Pathway adapter. Right-click the Adapters folder and select New Adapter. The New Adapter dialog box is displayed.
7.
The word event is a reserved word and cannot be used when naming an application adapter.
8. 9.
Expand the Machines folder. Expand the machine with your Pathway adapter. Expand the Bindings folder. Expand the binding with the Pathway adapter. Expand the Adapters folder. Right-click the adapter the Pathway adapter that you want to work with and select Open. The adapter Configuration editor is displayed.
8. 9.
Configure the adapter parameters as required. For a description of the available parameters, see Pathway Adapter Configuration Parameters. Click Finish.
The Pathway application adapter utilizes the Pathway PATHSEND interface, enabling the Pathway environment to handle non-screen COBOL clients.
This section includes the following topic: Importing Attunity Metadata from COBOL
Right-click Imports under the data source and select the New Import menu option. Enter a name for the import. The name can contain letters, numbers and the underscore character. Select Cobol Import Manager as the import type. Click Finish. The Metadata Import Wizard is displayed. Click Add in the Import Wizard to add COBOL copybooks. The Add Resource screen is displayed, providing the option of selecting files from the local machine or copy the files from another machine using FTP. This figure shows the Add Resource screen.
7. 8.
If the files are on another machine, then right-click My FTP Sites and select Add. Set the FTP data connection by entering the server name where the COBOL copybooks reside and, if not using anonymous access, enter a valid username and password to access the machine.
9.
To browse and transfer files required to generate the metadata, access the machine using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory. This figure shows the Add Resource screen detailing the FTP sites.
10. Select the files to import and click Finish to start the transfer.
The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns together with a COBOL copybook that ignores the first six columns. In this type of case, repeat the import process. You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks. The selected files are displayed in the Get Input Files screen.
When importing using the VSAM Under Pathway Import Manager there is an additional step (described later in this procedure), and hence the step shown in the top right of the screen is step 1 of 6.
11. Click Next. The Apply Filters screen is displayed.
COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-61 to treat COMP-6 as a COMP data type or COMP-62 to treat COMP-6 as a COMP-3 data type. Compiler source: The compiler vendor. Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP for word storage mode. Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks. Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks. Prefix nested column: Prefix all nested columns with the previous level heading. Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Attunity metadata, is replaced with an underscore. Case sensitive: Specifies whether to consider case sensitivity or not. Find: Searches for the specified value. Replace with: Replaces the value specified for in the Find field with the value specified here.
14. Click Add to add interactions for the Pathway Adapter. You can change the
default name that is specified for the interaction and then specify the mode of the interaction, which can be one of the following:
sync-receive: A response is expected from the program. That is, the program returns a result. sync-send: The program expects an input. sync-send-receive: The program expects an input and the program returns a result. This is the default mode.
You specify an input record used by the program associated with the interaction from the drop down list in the Input column. This list is generated from the COBOL programs specified at the beginning of the procedure. Select a relevant record for the interaction.
Note:
You must specify an input record for each interaction before clicking Next. If the interaction does not require an input record (sync-receive-mode), the record specified here is ignored.
If the mode is either sync-receive or sync-send-receive, you must also specify an output record used by the program from the drop down list in the Output column. Select a relevant record for the interaction.
15. Add as many interactions as necessary and then click Next.
The Import Metadata screen lets you import the metadata to the machine where the application adapter is defined or leave the generated metadata on the Attunity Studio machine, to be imported later.
Pathway Application Adapter (HP NonStop Only) 67-9
16. Select Yes to transfer the metadata to the machine where the application adapter is
Refresh.
18. Right-click each interaction and select View interaction. The Adapter Metadata
pathmonProcess: (Optional) The Pathway monitor process name. This is a system process that manages all Pathway objects, including SERVER objects which the requester program activates. If the name is not specified here, it must be specified in the binding configuration (via the pathmonProcess parameter), as described in Pathway Adapter Configuration Parameters.
Note: The Pathway application adapter uses PATHSEND process. Pathway provides two ways to activate servers: Screen COBOL SEND command and PATHSEND interfaced available to non-screen-COBOL clients.
serverClass: The serverClass specifies a single server class that provides several services (such as insert, read and delete services).
Note:
The interaction serverClass value is often the destination for the pathway SEND command.
The record statements for both the input and output must not be aligned. Alignment is set in the Source XML. An example record definition for a Pathway adapter is similar to the following:
<record name="read_request" noAlignment="true"> <field ... /> ... </record> <record name="read_reply" noAlignment="true"> <field ... /> ... </record>
where: noAlignment: A boolean value used to determine whether or not buffers are aligned.
Note:
noAlignmentis essential for Pathway as HP NonStop COBOL does not expect aligned structures. By default all buffers constructed are aligned.
Structure initializations prior to the SEND command are often values that can be used for the default attribute in a field statement.
67-11
68
Tuxedo Application Adapter (UNIX and Windows Only)
This section includes the following topics:
Overview of the Tuxedo Application Adapter Configuration Properties Metadata Transaction Support Data Types Security Checking the Tuxedo Environment Variables Defining the Tuxedo Adapters Setting Up Tuxedo Application Adapter Interactions Testing Tuxedo Application Interactions
Attunity Tuxedo Application Adapter: This adapter supports inbound transactions. It provides direct access to the platform where Tuxedo runs. Attunity Tuxedo Queue: This adapter supports outbound transactions by pulling messages from a queue.
Feature Highlights
The Tuxedo adapter interacts with Tuxedo using the Tuxedo ATMI (Application-to-Transaction Manager Interface) procedure library. In addition, the adapter uses the Tuxedo System Field Manipulation Language (FML) to support related data transfer needs.
Configuration Properties
The following parameters can be configured for the Tuxedo Application Adapter and the Tuxedo Queue adapter. in Attunity Studio in the Properties tab of the Configuration Properties screen:
applicationPassword: The application password in unencrypted format that is used for validation against the application password (mapped to Tuxedo TPINIT password). clientName: The client name. The semantics are application defined (mapped to to the Tuxedo TPINIT cltname).
The following parameters can be configured for the Tuxedo Queue adapter only.
queueName: The name of the Tuxedo Queue. Queue spaces are used for mapping requests in the Tuxedo queue. queueRetryInterval: When sending an interaction (for example, get time), this is the amount of time that the Tuxedo Queue waits for an answer. If no answer is received in this time interval, the Tuxedo Queue sends the interaction again. It continues to send the interaction at the defined interval until an answer is received. queueSpaceName: The name of the Tuxedo queue space.
Metadata
After setting up the binding, define the metadata (an adapter definition) for the Tuxedo adapter. The adapter definition describes the program that should be executed via a Tuxedo transaction for each required interaction. If either a BEA Jolt bulk loader file or Tuxedo configuration and FML/VIEW source files describing the adapter are available, you can import the adapter definition by running the metadata import in the Design Perspective Metadata view in Attunity Studio.
Note:
Jolt files are files where definitions of Tuxedo services are bulked into one file along with the metadata using the BEA Jolt Bulk Loader. FML and VIEW files are metadata files used by Tuxedo, often in conjunction with a configuration file that includes the Tuxedo services.
If BEA Jolt bulk loader files, Tuxedo configuration and FML/VIEW source files do not exist that describe the input and output structures, the metadata must be manually defined. For details on the metadata definition, see:
Transaction Support
The Tuxedo adapter supports one-phase commit transactions. You can limit the transaction duration before timing out at the adapter level.
Data Types
The Tuxedo adapter provides support for the following Tuxedo data types as Input/Output:
STRING: Null terminated character array. CARRAY: Array of uninterrupted arbitrary binary data. XML: The XML formatted data. VIEW: C structure layout. VIEW32: C structure layout with 32-bit FML identifiers. FML: Tuxedo system type that provides transparent data portability. FML32: FML type where 32-bit FML identifiers are used.
Note:
Synonyms for the above list (such as X_C_TYPE, X_OCTET) are also recognized.
Security
The Attunity Tuxedo adapter works with the BEA Tuxedo security parameters. See Configuration Properties for a list of these parameters. For more information on using security in Tuxedo, see the BEA Tuxedo documentation.
TUXDIR is set to the Tuxedo root directory. WSNADDR is set to the Tuxedo Workstation network address
To verify the Tuxedo environment variables On UNIX platforms, verify that the shared library environment variable includes the path to the Tuxedo bin directory, as in the following example:
LD_LIBRARY_PATH = /disk2/users/tuxedo/tuxedo8.0/bin
On Windows platforms, verify that the PATH environment variable includes the path to the Tuxedo bin directory, as in the following example:
PATH=C:\tuxed\tuxedo8.0\bin
Defining the Tuxedo Application Adapter Defining the Tuxedo Queue Adapter
Open Attunity Studio. In the Design perspective Configuration view, expand the Machines folder. Expand the machine where you want to add the Tuxedo Queue adapter.
Note: If the machine is not displayed in Attunity Studio, see Setting up Machines to see how to add machines to the Configuration view.
4. 5. 6. 7. 8. 9.
Expand the Bindings folder. Expand the binding where you want to add the Tuxedo adapter. Right-click the Adapters folder and select New Adapter. Enter a name for the adapter in the Name field. Select Tuxedo from the Type list. Click Finish.
When you finish defining the connection, you must set up the interactions. For information on how to set up Tuxedo adapter interactions, see Setting Up Tuxedo Application Adapter Interactions.
Open Attunity Studio. In the Design perspective Configuration view, expand the Machines folder. Expand the machine where you want to add the Tuxedo Queue adapter.
Note: If the machine is not displayed in Attunity Studio, see Setting up Machines to see how to add machines to the Configuration view.
4. 5. 6. 7. 8. 9.
Expand the Bindings folder. Expand the binding where you want to add the Tuxedo Queue adapter. Right-click the Events folder and select New Event. Enter a name for the adapter in the Name field. Select Tuxedo Queue from the Type list. Click Finish.
When you finish defining the connection, you must set up the interactions. For information on how to set up Tuxedo adapter interactions, see Setting up Tuxedo Queue Adapter Interactions.
Importing Metadata Using a BEA Jolt Bulk Loader File Importing Metadata Using FML/VIEW Files
In the Design perspective, Configuration view, expand the Machines folder and then expand the machine with your Tuxedo Adapter. Expand the Bindings folder and then expand the binding with the Tuxedo adapter you are working with. Expand the Adapters folder. Right-click the your Tuxedo application adapter and select Show Metadata View. The Metadata view is displayed with the Tuxedo Adapter selected.
6. 7. 8. 9.
Right-click Imports and select New Import. Enter a name for the import. The name can contain letters, numbers, and the underscore character. Select Tuxedo Import Manager Using Jolt Bulk Loader File as the import type. Click Finish. The Metadata Import Wizard Get Input file step is displayed.
10. Click Add in the Import Wizard to add a Jolt bulk loader file.
11. If the files are on another machine, then right-click My FTP Sites and select Add. Figure 682 Add FTP Site screen
anonymous access, enter a valid username and password to access the machine. The user name provided is used as the high-level qualifier.
13. Click OK. 14. After accessing the machine, you can change the high-level qualifier by
The selected files are displayed in the Get Input File step, as shown in the following figure:
The Applying filters step is displayed. There is nothing to add in this step.
18. Click Next. The import wizard analyzes and converts the source files. When this is
complete, the Select Interactions step is displayed, as shown in the following figure:
The window lists the Services from the input Jolt file as interactions, along with the input and output structures to use with each interaction.
19. Select the interactions you want to implement from the list and Click Next.
The Configure Tuxedo Records step is displayed, as shown in the following figure:
20. Define how the Tuxedo records should be configured and click Next to generate
the metadata. The Import Metadata Screen, lets you import the metadata to the target computer or leave the generated metadata on the computer running Attunity Studio, to be imported later.
21. Specify that you want to transfer the metadata to the remote computer and click
After importing the metadata, you can access the metadata in the Design perspective, Metadata view. You can make any fine adjustments to the metadata and maintain it, as necessary. For more information, see Working with Application Adapter Metadata.
In the Design perspective, Configuration view, expand the Machines folder and then expand the machine with your Tuxedo Adapter. Expand the Bindings folder and then expand the binding with the Tuxedo adapter you are working with. Expand the Adapters folder. Right-click the your Tuxedo application adapter and select Show Metadata View. The Metadata view is displayed with the Tuxedo Adapter selected.
6.
7. 8. 9.
Enter a name for the import. The name can contain letters, numbers, and the underscore character. Select Tuxedo Import Manager Using VIEW Files as the import type. Click Finish. The Metadata Import Wizard, Get Input Files step is displayed. Import Wizard to add the configuration files. You can add the following types of files:
10. Click Add next to one or more of the sections in the Get Input Files step of the
Select Tuxedo Records Definition FML files. Select Tuxedo Records Definition VIEW files Select Tuxedo Configuration files
Configuration files are used to get the information necessary for starting application servers and initializing the bulletin boards in an orderly sequence in Tuxedo. Configuration files have a number of sections, including a SERVICES section which provides information on services used by the application, from which interactions are generated during the import procedure. The FML files contain metadata used by Tuxedo and are used to provide the data structures for the interactions. The Add Resource window is displayed. In this screen you can select files from the local machine or copy the files from another machine using FTP.
Figure 687 Add Resource Screen
11. If the files are on another machine, then right-click My FTP Sites and select Add. 12. Set the FTP data connection by entering the server name where the FML/VIEW
files reside and, if not using anonymous access, enter a valid username and password to access the machine.
13. To browse and transfer files required to generate the metadata, access the machine
using the username as the high-level qualifier. After accessing the machine, you can change the high-level qualifier by right-clicking the machine and selecting Change Root Directory.
14. Select the files to import and click Finish to start the transfer.
The selected files are displayed in the Get Input File step, as shown in the following figure:
Figure 688 Get Input Files
15. Click Next. The Add FML Records step is displayed. Carry out the procedures in
Createrecords: Click Add to create a new record. Enter a name for the record. You add fields from the FML fields selected in the previous step. After you add the record, it is added to the Records list. When you click on the record, the fields you added to the record are displayed in the Selected fields left on the top right section of this step. If you have a long list of records, use the field at the top of the Records list to filter the records.
Add fields to the record. Select a record from the Records list. You can add fields to the record by selecting one or more fields in the Available Fields list and adding them to the Selected Fields list. Use the triangle buttons on the screen to add the fields to the Selected Fields list or to remove fields. Use the double-triangle buttons to add all of the fields in the Available Fields list to the Selected Fields list or to remove all fields from the Selected Fields list. If you have a long list of records, use the field at the top of the Available Fields list to filter the records.
View the fields for a record. Select a record from the Records list. The fields added to that record are displayed in the Selected Fields list. If you have a long list of records, use the field at the top of the Selected Fields list to filter the records.
Add additional simple record definitions, if necessary. These records are stored in the following Tuxedo buffer types:
17. Enter the name of the record and select the buffer type from the Field list.
A message buffer of type STRING is wrapped within a record containing a single field of type string. A message buffer of type CARRAY is wrapped within a record containing a single field of type binary with a fixed size. A message buffer of type XML is wrapped within a record containing a single field of type XML.
Figure 6811
Add Interactions
Name: The name of the interaction. If a configuration file was included as one of the input files for the import, the name is selected from the drop down list, which is generated based on the services specified in the configuration file. Mode: The interaction mode. Your options are: sync-receive: A response is expected from the program. That is, the program returns a result. sync-send: The interaction sends a request and does not expect to receive a response. sync-send-receive: The interaction sends a request and expects to receive a response.
Input: Identifies an input record. The input record is the data structure for the outbound interaction. The records generated from the FML/VIEW files specified at the beginning of the procedure are included in a drop down list. Select the relevant record for the interaction
Note:
You must specify an input record for each interaction before you can click Next. If the interaction does not require an input record, the record specified here is ignored.
Output: Identifies an output record. The output record is the data structure for the results of the outbound interaction. The records generated from the FML programs specified at the beginning of the procedure are included in a drop down list. Select the relevant record for the interaction.
You must specify an output record for the interaction if the mode is set to sync-send-receive or sync-receive, before you can click Next.
Note:
Input Buffer Type: The type of data used for the input. Output Buffer Type: The type of the buffer to use for the results of an outbound interaction. No Transaction: Enables a service to be executed, regardless of transaction context. This parameter should always be checked. No Reply Expected: For future use. No Blocking Request: Avoids a FROM request submission if a blocking condition exists. No Timeouts: Ignores blocking timeouts. Signal Restart: If selected, whenever a signal interrupts an underlying system call, this call is reissued. Interaction Type: Select any of the following: service: Enables service interaction (default). enqueue: Stores a message on the queue that is specified by the information provided in the Queue Name box and the Queue Space Name box. post: Posts an event, whose name is specified by the Event Name box, and any related data.
Queue Space Name: Specifies the name of the queue space. Only enabled with enqueue interactions. Queue Name: Specifies the name of the queue. Only enabled with enqueue interactions. Event Name: Specifies the name of the event. Only enabled with event interactions.
The Configure Tuxedo Records step is displayed, as shown in the following figure:
Figure 6812
22. Define how the Tuxedo records should be configured and click Next. 23. Click Next to generate the metadata.
The Import Metadata screen lets you import the metadata to remote computer or leave the generated metadata on the computer running Attunity Studio to be imported later.
24. Select Yes to transfer the metadata to the target computer and click Finish.
After performing the import, you can view the metadata in the Metadata tab. You can also make any fine adjustments to the metadata and maintain it, as necessary. For more information, see Adapter Metadata General Properties.
All the events described in a single Tuxedo Queue adapter, should have the same Tuxedo buffer type. In case that FML/FML32 buffer type is used, a common field with the same FBName must be included in all events. This field should contain the record/event name. The interaction is of async-send type (it does not expect to receive a response).
1. 2. 3. 4. 5.
Open Attunity Studio. In the Design perspective, Configuration view, expand the Machines folder and then expand the machine with your Tuxedo Queue adapter. Expand the Bindings folder and then expand the binding with the Tuxedo Queue adapter you are working with. Expand the Events folder. Right-click the Tuxedo Queue adapter and select Show Metadata View. The Metadata view is displayed, with the Tuxedo Queue adapter displayed.
6.
Right-click Imports and select New Import. The New Import dialog box is displayed.
7. 8.
Enter a name for the import. The name can contain letters, numbers and the underscore character only. Select the import type from the Import Type list. You have the following options:
Tuxedo Queue Import Manager for XML/STRING/CARRAY Buffers: This option lets you manually define the required Tuxedo record. Tuxedo Queue Import Manager for VIEW/VIEW32 Buffers Tuxedo Queue Import Manager for FML/FML32 Buffers Tuxedo Queue Import Manager for FML/FML32 Buffers by VIEW
9.
Click Finish. The next step depends on the selected import type. If the VIEW/VIEW32 Buffers, the FML/FML32 Buffers by VIEW, or the FML/FML32 Buffers options is selected, then the Metadata Import wizard opens, in which case, proceed to the following step. If the XML/STRING/CARRAY Buffers option is selected, go to Defining the Tuxedo Queue Unstructured Records for an explanation of the manual metadata import.
10. In the Get Input Files step of the input wizard, click Add. 11. The Select Resources dialog box is displayed, which provides the option to select
files from the local computer or copy the files from another computer.
12. If the files are on another computer, right-click My FTP Sites and select Add.
Optionally, double-click Add FTP Site. The Add FTP Site screen is displayed.
13. Enter the server name or IP address where the required reside and enter a valid
username and password to access the computer (if anonymous access is used, select Anonymous connection), then click OK. The FTP site is added to the list of available sites.
14. Right-click the computer and select Set Transfer Type. Enter the appropriate
computer and select Change Root Directory. Enter the new directory name, and click OK.
16. Select the required file or files and click Finish.
The selected file or files are displayed in the Metadata Import wizard, Get Input Files step, as shown in the following figure:
Figure 6815 Get Input Files
The Configure Tuxedo Records screen is displayed, as shown in the following figure:
Figure 6816 Configure Tuxedo Queue Records
18. Ensure that the settings are correct for the following properties:
Buffer type: Indicates the buffer type, as read from the FML/VIEW file. This property should not be modified. Get Tuxedo Queue header field in the output record: Indicates that the header filed of each record is read. The default setting is true. Read strings from buffer as null terminated: Indicates that strings are handled as null terminated. The default setting is true.
19. Specify the FBName of the field that contains the event name. This field is common
to all incoming events and it should include the record name. This property is required only for FML/FML32 files.
20. Click Next to generate the metadata definitions for the Tuxedo Queue adapter, and
21. Select Yes to transfer the data to the server, then click Finish.
The Import wizard generates record structures, which are used for the record structures for the inbound interactions, and the metadata is imported based on the options specified and it is stored on the target platform. An XML representation of the metadata is also generated. After performing the import, you can view the metadata in Attunity Studio Design perspective Metadata tab, under Imports of the Queue adapter. You can also make any fine adjustments to the metadata.
Note:
See Working with Application Adapter Metadata for details about fine tuning the adapter metadata.
Open Attunity Studio. In the Design perspective, Configuration view, expand the Machines folder and then expand the machine with your Tuxedo Queue adapter. Expand the Bindings folder and then expand the binding with the Tuxedo Queue adapter you are working with. Expand the Events folder. Right-click the Tuxedo Queue adapter and select Show Metadata View.
The Metadata view is displayed, with the Tuxedo Queue adapter displayed.
6.
Right-click Imports and select New Import. The New Import screen is displayed.
7. 8. 9.
Enter a name for the import. The name can contain letters, numbers and the underscore character only. Select Tuxedo Queue Import Manager for XML/STRING/CARRAY Buffers from the Import Type list. Click Finish. The Get Tuxedo Records screen is displayed, as shown in the following figure:
Figure 6818
10. Click Add Record. A new record entry is added to the records list, with a default
type.
11. Select the field type from the Field Type list. Your options are:
12. Specify the maximum buffer size in the Size column. This is not required if XML
The Configure Tuxedo Records screen is displayed, as shown in the following figure:
14. Ensure that the settings are correct for the following properties:
Buffer type: Indicates the buffer type, as read from the FML/VIEW file. This property should not be modified. Get Tuxedo Queue header field in the output record: Indicates that the header filed of each record is read. The default setting is true. Read strings from buffer as null terminated: Indicates that strings are handled as null terminated. The default setting is true.
15. Specify the FBName of the field that contains the event name. This field is common
to all incoming events and it should include the record name. This property is required only for FML/FML32 files.
16. Click Next to generate the metadata definitions for the Tuxedo Queue adapter, and
Figure 6820
Import Metadata
17. Select Yes to import the data to the target platform, then click Finish.
The record structure is generated, and the metadata is imported to and stored on the target platform. An XML representation of the metadata is also generated. After performing the import, you can view the metadata in Attunity Studio Design perspective Metadata tab, under Imports of the Queue adapter. You can also make any fine adjustments to the metadata.
Note:
See Working with Application Adapter Metadata for details about fine tuning the adapter metadata.
Open Attunity Studio. In the Design perspective Configuration view, expand the Machines folder. Expand the machine with the Tuxedo interactions you want to test. Expand the Bindings folder, then expand the binding with the Tuxedo Adapter you are testing. Expand the Adapters folder Right-click the Tuxedo Application adapter with the interactions you want to test and select Show Metadata View. The Metadata view opens, with the Tuxedo Application Adapter selected.
7. 8. 9.
Expand the Interactions folder. Right-click the interaction you want to test and select Test. Click Next. The parameters specification wizard opens.
10. Specify any values for the parameters, as necessary, and click Next. 11. View the test result and click Finish.
Part XI
Non-Application Adapters Reference
This part contains the following topics:
Database Adapter Query Adapter Managing the Execution of Queries over Large Tables
69
Database Adapter
This section includes the following topics:
Overview Configuration Properties Metadata Security SQL Interaction Types Transaction Support Interaction Parameters Defining the Database Adapter Configuring Database Adapter Interactions Testing Database Adapter Interactions Creating SQL Queries
Overview
The Database Adapter enables access to all Attunity Connect Data Sources using predefined SQL statements, via JCA, XML, COM or .NET.
Note:
Supported Features
The Database Adapter supports generating automatic and manual SQL interactions that, once generated, can be executed via JCA, XML, COM or .NET to access Attunity Connect data sources.
Configuration Properties
The following properties can be configured for the Database Adapter in the Properties tab of the Configuration Properties screen, when Configuring the Database Adapter.
connectString: This parameter specifies the connect string used to access the data source. For backward compatibility only. defaultDatasource: This parameter specifies name of a Data Source in the Binding configuration. multipleResult: This parameter specifies whether or not multiple results are returned. This property default value is true. It applies to Stored Procedure Call interactions (see Stored Procedure Call Interaction), where the call procedure includes multiple SQL statements (either batched one after the other or in a loop, such as a WHILE loop).
Metadata
The Database Adapter has a set of built-in schemas and interactions. These can be viewed and used from the Design Perspective Metadata tab.
Security
There are no specific security requirements for this adapter. The security for this adapter is governed by the administration authorization parameters for the current machine, and the relevant data source. For more information, see Add Authenticators.
Database Query Interaction Database Modification Interaction Stored Procedure Call Interaction
SQL Statements: The SQL query that will be performed when executing the interaction. Pass Through: Whether the query is passed directly to the Backend Database for processing or is processed by the Query Processor. Reuse compiled query: Whether or not the query objects created in the previous execution are saved in a cache for reuse. Encoding: The type encoding used to return binary data in text format. The options are: base64: Sets base 64 encoding. hex: Sets hexadecimal encoding.
Fail on no rows returned: Whether or not an error is returned if data is not returned. Root element: The root element name for records returned by the query. Record element: The record element name for records returned by the query. Max. records: The maximum number of records returned by the query execution. NULL string: The string returned in place of a null value. If not specified, the column is skipped. Interaction Parameters: The input parameters to the query in sequential order (as they appear in the SQL statement). For details about parameter definition, refer to Specifying Parameters.
SQL Statement: The SQL batch update statement that you want to execute. For example, an INSERT INTO or DELETE statement. Pass Through: Whether the batch update statement is passed directly to the Backend Database for processing or processed by the Query Processor. Reuse compiled query: Whether or not the query objects created at previous execution are saved in a cache for reuse. Fail on Zero Affected: Whether or not an error is returned if no rows were affected as a result of the batch update execution. Interaction Parameters: The input parameters to the query in sequential order (as appear in the SQL statement). For details about parameter definition, refer to Specifying Parameters.
Datasource: The name of the Data Source as defined in the Binding configuration, where the stored procedure is found. Procedure Name: The name of the stored procedure. Procedure Return Value: The procedure return value attribute name (the optional default is RETURNVALUE). Return Results: Whether to fetch the procedure results (default is false). Encoding: The encoding used to return binary data in text format, optional values: base64: Sets base 64 encoding. hex: Sets hexadecimal encoding.
Root Element: The root element name and the record element name for records returned by the query, using the format <root>\<record>. (Optional default is 'root\record') NULL string: The string returned in place of a null value. If not specified, the column is skipped.
Interaction Parameters: The input parameters for the stored procedure in the sequential order defined in the creation of the procedure. For details about parameter definition, refer to Specifying Parameters.
Transaction Support
The Database adapter supports working in the following modes.
Non-transacted mode: The adapter works in auto-commit mode. Local transaction mode: The first interaction starts a transaction that lasts until an explicit commit or an explicit rollback occurs. Distributed transaction operation: The ACX adapter participates in a distributed transaction by exposing the appropriate XA methods.
For more information on how to work with transactions, see Transaction Support.
Interaction Parameters
Any input parameters you add when Manually Creating Interactions must be specified. The following information is configurable for a parameter.
name: The name of the parameter. This will be the attribute name in the input record. type: The type of parameter, which can be any one of the following: string number timestamp binary xml
nullable (boolean): Whether the value can be null or not. The default is true. default: A default value for the parameter, used if the parameter attribute is missing in the input record.
Notes:
If a field is not nullable and a default value is not supplied in the schema part of the Adapter Definition, an error occurs if the parameter attribute is missing in the input record. The parameters must be defined in the same order as they are used in the SQL statement. With the Stored Procedure Call interaction, if the database reports output parameters as input-output, make sure to provide an input value.
Open Attunity Studio. In the Design perspective, Configuration view, expand the Machine folder. Expand the Machine with the adapter you are working with. Expand the Binding folder. Expand the binding where with the adapter you are working with. Right-click Adapters and select New Adapter. The New Adapter dialog box is displayed.
7.
The word event is a reserved word and cannot be used when naming an adapter.
8. 9.
Right-click the adapter and select Open. The Configuration Properties screen is displayed.
2. 3.
Select the Properties tab. The configuration properties are displayed. Configure the adapter parameters as required. For a description of the available parameters, see Configuration Properties.
The Database Adapter requires predefined SQL statements, as opposed to the Query Adapter, where the SQL statement is specified at runtime.
In the Configuration view, right-click Adapters and select Show Metadata View. The Metadata tab is displayed with the Database Adapter displayed in the Metadata view.
2.
Right-click the Interactions folder and select New. The New Interaction wizard is displayed.
3. 4.
To automatically generate interactions, select Automatic. Click Next. The Select Tables screen is displayed, enabling you to add tables from any of the data sources in the same binding as the Database Adapter and that you want to access with the interaction.
5.
Expand the data sources and select the tables that you want to access with the interaction and click the right arrow to move these tables to the right-hand pane.
Figure 692 Select Tables for Interaction
6.
Click Finish. The selected data sources and tables are displayed. Optionally, you can select a table and set the following for the SQL statements generated for that table:
Use XML Field: The output is formatted as XML according to its actual structure. This is useful for tables which include variant fields and arrays.
Note:
For this field to be available, the exposeXmlField in the misc section of the binding environment properties must be set to true.
Use Key in Select: The table key columns are used in the SELECT statement in the WHERE section as column1 = ? AND column2 = ? AND . If no key exist, all columns will be added.
Upsert: This property has the default of false but, when set to true makes the insert and update interactions generated behave as follows: When inserting a row, if the row does not exist, it is inserted, otherwise the row is updated with the new information. When updating a row, if the row exist, it is updated, otherwise new row is inserted with the new information.
7.
Click Finish. Four interactions are generated for each table selected, together with the input and output record structures to support the interactions.
Note:
If the Upsert property is checked, only three interactions are generated. An insert interaction is generated with an update property instead of both an insert and update interaction.
8.
Click Yes to complete the task. The interactions and the record structures that relate to the interactions are displayed in the Metadata tab.
In the Configuration view, right-click Adapters and select Show Metadata View. The Metadata tab is displayed with the Database Adapter displayed in the Metadata view. Right-click Interactions and select New. The New Interaction wizard is displayed.
2.
3. 4.
To manually generate interactions, select Manual. Select the type of SQL as Query for the interaction and click Next. You are prompted to provide a name for the interaction.
5.
In the Query Group area, using the radio buttons, select if you want to create a new query or load an existing one. To select a previously saved query, click Browse and select the SQL.
Note: Only queries saved on the current machine running Attunity Studio and defined for data sources in the same binding as the database adapter can be used. Queries can be saved when they are created using the Query Tool in Attunity Studio by right-clicking a data source and selecting Query Tool.
6.
7.
Create the SQL query. This can be done as described in Creating SQL Queries or the query can be written manually by checking Enable manual query editing, and actually writing the query in the bottom pane. Click Next. The Interaction Properties screen is displayed.
8.
9.
11. Specify the input parameters for the interaction, as detailed in Specifying
Parameters.
12. Click Finish to generate the interaction, including the record schema required to
support the interaction input and output. The SQL used in the interactions can be modified to the exact application requirements. For more information, see Adapter Metadata General Properties. The SQL can be changed as long as the changes are supported by the schema. Follow these steps for manually creating modification interactions.
1.
In the Configuration view, right-click Adapters and select Show Metadata View. The Metadata tab is displayed with the Database Adapter displayed in the Metadata view. Right-click the Interactions folder and select New. The New Interaction wizard is displayed.
2.
3. 4.
To manually generate interactions, select Manual. Select the type of SQL as Modification for the interaction and click Next. You are prompted to provide a name for the interaction.
5.
In the Query Group area, using the radio buttons, select if you want to create a new query or load an existing one. To select a previously saved query, click Browse and select the SQL.
Note: Only queries saved on the current machine running Attunity Studio and defined for data sources in the same binding as the database adapter can be used. Queries can be saved when they are created using the Query Tool in Attunity Studio by right-clicking a data source and selecting Query Tool.
6.
7.
8.
Create the SQL query. This can be done as described in Creating SQL Queries or the query can be written manually by checking Enable manual query editing, and actually writing the query in the bottom pane. At the bottom of the screen, under Interaction properties, you can optionally configure the interaction properties as described in Database Modification Interaction.
9.
Figure 6911
Interaction Parameters
11. Specify the input parameters for the interaction, as detailed in Specifying
Parameters.
12. Click Finish to generate the interaction, including the record schema required to
support the interaction input and output. The SQL used in the interactions can be modified to the exact application requirements. For more information, see Adapter Metadata General Properties. Follow these steps for manually creating stored procedure interactions.
1.
In the Configuration view, right-click Adapters and select Edit Metadata. The Metadata tab is displayed with the Database Adapter displayed in the Metadata view.
2.
Right-click Interactions and select New. The New Interaction wizard is displayed.
3. 4.
To manually generate interactions, select Manual. Select the type of SQL as a Stored Procedure Call and click Next. The Interaction Name screen is displayed.
5.
6.
Figure 6914
Define Interaction
7.
Specify the data source and procedure name, and optionally the other procedure interaction properties. For more information about these properties see Stored Procedure Call Interaction. Click Next. The Interaction Parameters screen is displayed.
8.
9.
Specify the input parameters for the interaction, as detailed in Specifying Parameters. support the interaction input and output.
10. Click Finish to generate the interaction, including the record schema required to
Specifying Parameters
When Manually Creating Interactions, upon defining the interaction, if you decide to enable manual query editing and there are parameters in your SQL statement, you will need to define the Interaction Parameters for each input parameter entered. Follow these steps for adding a parameter.
1.
2. 3. 4.
Enter a unique name and click OK. Edit the parameters properties, as necessary. Refer to Interaction Parameters for details. Click Finish.
In the Configuration view, right-click the data source and select Show Metadata View. The Metadata tab is displayed with the Database Adapter displayed in the Metadata view. Expand Interactions. Right-click the Interaction you want to test and select Test. The Test Interaction wizard is displayed.
2. 3.
4.
5.
Specify any values for the parameters as necessary, and click Next. The test result is displayed.
6.
Click Finish.
Select tables.
In the left pane, expand the data source where the table resides. Select the table and click the right arrow to move the table to the right pane of selected tables
2.
Select columns.
In the left pane, expand the data source and the table containing the column. Open the Columns tab in the right pane. Select the column and click the right arrow to move the column to the right pane.
3.
Join columns from different tables. The Create Joint tables pane is displayed.
Expand the table and select the column you want to join. Click the right arrow to move the column to the right pane. Optionally, click Next and edit the join statement. Click Finish.
4.
Add conditions in a WHERE clause. WHERE clauses are set in the Where tab.
Select and move the column you are setting the WHERE clause for to the right pane.
5.
Filter results using a HAVING clause. The HAVING clause provides conditions for grouping columns. HAVING clauses are set in the Having tab.
Select and move the column you are filtering to the right pane. Set the operator and value conditions as needed.
6.
Select and move the column whose query result you want to sort to the right pane. Select the sorting order as either ascending or descending. For a modification query, the following options are also available: Pass Through: Whether the query is passed directly to the Backend Database for processing or processed by the Query Processor. Reuse compiled query: Whether the query is saved in a cache for reuse. Fail on Zero Affected: Whether an error is returned if data is not returned.
70
Query Adapter
This section includes the following topics:
Overview Metadata Security Predefined Interactions Transaction Support Using the Query Adapter
Overview
The Query Adapter enables accessing all of the AIS data source drivers to execute SQL statements via JCA, XML, COM or .NET. The Query adapter is automatically set and configured as part of the AIS Installation. If you have predefined SQL, use the Database Adapter. The Query Adapter can be used in an application without any definition in a binding configuration. However, if you want to specify a default data source to use with the adapter (so that the data source does not have to be included in SQL statements), you can define another adapter in a binding configuration, of type "query".
Features Highlights
The Query Adapter supports a set of predefined interactions which enable you to access AIS using SQL statements using applicative interfaces.
Metadata
The Query adapter has a set of built-in schemas and interactions, which compose its metadata.
Security
There are no specific security requirements for this adapter. The security for this adapter is governed by the administration authorization parameters for the current machine, and the relevant data source For more information, see Add Authenticators.
Transaction Support
The Query adapter supports the following transaction modes:
Non-transacted: The adapter operates in auto-commit mode. Local transaction: The first interaction starts a transaction that lasts until an explicit commit or an explicit rollback occurs. Distributed transaction: The ACX adapter participates in a distributed transaction by exposing the appropriate XA methods.
Predefined Interactions
The following interactions can be used with the ACX EXECUTE verb on data sources and AIS procedures which are defined in the binding configuration:
callProcedure Interaction ddl Interaction getSchema Interaction query Interaction setErrorAction Interaction update Interaction
callProcedure Interaction
The callProcedure interaction enables calling a stored procedure. If the stored procedure has multiple results, then all the recordsets are returned in the output. The last recordset is always dedicated to the return-value and output parameters.
Note: Several databases report output parameters as input-output. If this is the case with the procedure you are running, ensure that you provide an input value for this parameter.
Input Record
The callProcedure interaction gets the input attributes listed in the following table:
Table 701 Attribute id (string) datasource callProcedure Interaction Attributes Required Yes Optional
Description A string which uniquely identifies the interaction. The name of the data source, as defined in the binding configuration where the stored procedure is found.
Table 701 (Cont.) callProcedure Interaction Attributes Attribute name inputParameter Description The name of the stored procedure. The input parameters to the stored procedure in sequential order (as defined in the createProcedure statement). You can specify the following attributes for each parameter:
value: A value for the parameter. type: The parameter type. Your options are string|number|timestamp|binary|xml. null (boolean): Specifies whether the value is null or not. xmlValue: Specifies the value when the parameter is of XML type.
outputFormat
Specifies how the query results are formatted. Your Optional options are:
attributes (the default) elements msado (specifies the MS ADO XML recordset persistance format) Optional
binaryEncoding
Specifies the encoding used to return binary data in text format. Your options are:
base64 (the default): Sets base 64 encoding. hex: Sets hexadecimal encoding. Optional
metadata (boolean) Specifies whether the interaction returns metadata for the retrieved recordset. The default is set to false. nullString (string) outputRoot Specifies the string returned in place of a null value. If not specified the column is skipped. Specifies the root element name and the record element name for records returned by the query, using the <root>\<record> format. Specifies whether to fetch the procedure results. The default is set to false. Specifies the procedure return value attribute name. The default is RETURNVALUE.
Optional Optional
Optional Optional
Output Record
The callProcedure interaction output record looks as follows:
<record name="multipleResultset"> <field name="id" type="string"/> <field name="sqlCode" type="string"/> <field name="recordset" type="recordset" reference="true" array="*"/> </record> <record name="recordset"> <field name="data" type="xml" array="*"/> <field name="id" type="string"/> <field name="sqlCode" type="string"/> </record>
Where:
data: An array of XML sub element which are the query execution results in the appropriate format. id: The id attribute specified in the input record. sqlCode: Status code indicating the query execution success or failure.
A Simple callProcedure Interaction
Example 701
The following XML request calls a stored procedure called in_out_multi, stored in a database specified as dbsql in the binding settings:
<?xml version="1.0" encoding="UTF-8"?> <acx> <connect adapter="query"/> <execute> <callProcedure datasource="dbsql" name="in_out_multi" metadata="true" returnResults="true"> <inputParameter value="1" type="number"/> <inputParameter value="2" type="number"/> </callProcedure> </execute> <disconnect/> </acx>
ddl Interaction
The ddl interaction specifies a DDL statement.
Input Record
The ddl interaction gets the input attributes listed in the following table:
Table 702 Attribute id (string) sql (string) passTrough (boolean) datasource (string)
Description A string which uniquely identifies the DDL SQL. The DDL SQL that you want to execute. It can be specified as an attribute or as a text sub element. Specifies whether the SQL is passed directly to the back-end database for processing, or processed by the Query Processor. The default is set to false. Specifies the default data source against which to execute the query. The query itself, in non pass-through case, may include the data source.
Optional
Output Record
The ddl interaction output record looks as follows:
<record name="status"> <field name="id" type="string"/> <filed name="sqlStatus" <field name="sqlCode" type="string"/> <field name="rowsAffected" type="int"/> </record>
Where:
id: The id attribute specified in the input record. sqlStatus: The SQL status. It include ok|error|duplicateKey| constraintViolation|permissionError. sqlCode: Status code indicating the query execution success or failure. rowsAffected: Indicates the number of rows affected.
A Simple ddl Interaction
Example 702
getSchema Interaction
The getSchema interaction retrieves schema information for different data source objects.
Input Record
The getSchema interaction gets the input attributes listed in the following table:
Table 703 Attribute id (string) type getSchema Interaction Attributes Required
Description A string which uniquely identifies the interaction call. The type of object whose schema you want to retrieve. One of the following must be specified:
Yes
datasource: Retrieves schema information on a data source. tables: Retrieves schema metadata on all tables. table: Retrieves schema metadata on a specific table. procedures: Retrieves schema metadata on all procedures. procedure: Retrieves schema metadata on a specific procedure. columns: Retrieves schema metadata on all columns. indexes: Retrieves schema metadata on all indexes. procedureColumns: Retrieves schema metadata on all procedure columns. primaryKeys: Retrieves schema metadata on all primary keys. foreignKeys: Retrieves schema metadata on all foreign keys.
datasource owner
The name of the data source, whose schema is retrieved. The name of the owner of the object whose schema is retrieved.
Table 703 (Cont.) getSchema Interaction Attributes Attribute table tableType column Description The name of the table whose schema is retrieved. The type of table whose schema will be retrieved, such as synonym, system or table. The name of the column whose schema is retrieved. This attribute is required only when columns is specified for the type attribute. The name of the procedure whose schema is retrieved. This attribute is required only when procedure is specified for the type attribute. The owner of the table that is referenced in the foreignKeys specification for the type attribute. This attribute can be specified only if foreignKeys is specified for the type attribute. The name of the table referenced in the foreignKeys specification of the type attribute. This attribute can be specified only if foreignKeys is specified for the type attribute. Required
procedure
foreignOwner
foreignTable
Note:
values.
Example 703 A tables getSchema Interaction Call
Example 704
</table> </schema>
query Interaction
The query interaction specifies an SQL query, which is executed by the ACX EXECUTE verb.
Input Record
The query interaction gets the input attributes listed in the following table:
Table 704 Attribute id (string) sql (string) outputFormat query Interaction Attributes Description A string which uniquely identifies the query. The SQL query that you want to execute. It can be specified as an attribute or as a text sub element. Required Optional Yes
Specifies how the query results are formatted. Your Optional options are:
attributes (the default) elements msado (specifies the MS ADO XML recordset persistance format) xml (Used to get the full table schema when a SELECT XML statement is executed. This is the standard ACX format)
Note: For details, see Output Data Formats. outputRoot Specifies the root element name and the record element name for records returned by the query, using the <root>\<record> format. Specifies the encoding used to return binary data in text format. Your options are:
Optional
binaryEncoding
Optional
base64 (the default): Sets base 64 encoding. hex: Sets hexadecimal encoding.
Specifies whether the query returns metadata for Optional the retrieved recordset. The default is set to false. Specifies the maximum number of records returned by the query. The default value is set to zero, indicating no limitation Specifies the string returned in place of a null value. If not specified the column is skipped. Specifies whether the query is passed directly to the back-end database for processing or it is processed by the Query Processor. The default is set to false. Specifies the default data source against which to execute the query. The query, in a non pass-through case may include the data source. Optional
Optional Optional
datasource (string)
Optional
Table 704 (Cont.) query Interaction Attributes Attribute inputParameter Description The input parameters to the query in sequential order (as it appears in the SQL statement). You can specify the following attributes for each parameter:
Required Yes
value: A value for the parameter. type: The parameter type. Your options are string|number|timestamp|binary|xml. null (boolean): Specifies whether the value is null or not. xmlValue: Specifies the value when the parameter is of XML type. Optional
failOnNoRowsReturned Specifies whether the query execution should fail (boolean) in case that no rows are returned from it. The default is set to false.
Output Record
The query interaction output record looks like the following:
<record name="recordset"> <field name="data" type="xml" array="*"/> <field name="id" type="string"/> <field name="sqlCode" type="string"/> </record>
Where:
data: An array of XML sub element which are the query execution results in the appropriate format. id: The id attribute specified in the input record. sqlCode: Status code indicating the query execution success or failure.
Attributes: Each column is represented by an attribute in the row element. Recordsets which contain chapter columns are formatted as child elements. For example, the format for a chapter column (columnX), is as follows:
<record column1="value1" ... columnN="valueN"> <columnX> <rowchild child_column1="value1" ... child_columnN="valueN"/> ... </columnX> </record>
Recordsets containing BLOB columns are formatted as child elements with encoded binary text content. For example, the format for a BLOB column (columnX), is as follows:
<record column1="value1" ... columnN="valueN"> <columnX encoding="base64|hex"> ... encoded_binary_data ... </columnX> </record>
The binary data can be either of base64 encoding or hex encoding (two hexadecimal digits per data byte). Recordsets containing CLOB columns are formatted as child elements with CDATA content.
Elements: Each column is represented by a sub element in the row element. For example:
<records> <record> <column1>value1</column1> ... <columnN>valueN</columnN> </record> ... </records>
If the value of a column is NULL, then the corresponding child element is omitted. This format takes more space then the attributes format but it lends itself more easily to representing hierarchical data. For example, the format for a chapter (columnX) is as follows:
<record> <column1>value1</column1> ... <columnX> <record>...child_row ...</record> ...child_rows... </columnX> ... <columnN>value1</columnN> </record>
Recordsets containing BLOB columns are formatted as child elements with encoded binary text content. For example, the format for a BLOB column (columnX), is as follows:
<record> <column1>value1</column1> ... <columnXencoding="base64|hex"> ...encoded_binary_data... </columnX> ... <columnN>valueN</columnN> </record>
The binary data can be either of base64 encoding or hex encoding (two hexadecimal digits per byte). Recordsets containing CLOB columns are formatted as child elements with CDATA content.
Example 705 An ACX query interaction that returns a recordset formatted in theattributes (default) format <?xml version="1.0"?> <acx> <connect adapter="query"/> <execute> <query id="1"> <sql> select * from navdemo:nation </sql> </query> </execute> <disconnect/> </acx>
<?xml version="1.0"?> <acx> <connect adapter="query" /> <execute> <query id="1" metadata="true"> <sql> select * from navdemo:nation </sql> </query> </execute> <disconnect/> </acx>
Query Adapter
70-11
N_COMMENT=New Distributor/> <record N_NATIONKEY=1 N_NAME=ARGENTINA N_REGIONKEY=1 N_COMMENT=Far Away/> ... </recordset> </executeResponse> </acx>
Example 707 An ACX query interaction that returns a recordset formatted in the elements format and using input parameters <?xml version="1.0"?> <acx> <connect adapter="query" /> <execute> <query id="1" outputFormat="elements"> <sql> select * from navdemo:nation where N_NATIONKEY > ? </sql> <inputParameter value="-1" type="number"/> </query> </execute> <disconnect/> </acx>
Example 708 An ACX query interaction that executes a hierarchical query and returns a recordset formatted in the default format <?xml version="1.0"?> <acx type="request" id="5169729"> <connect adapter="query" persistent="false" /> <execute> <query outputFormat="attributes"> <sql> select r.r_name as "Region", {select n.n_name as "Name" from navdemo:nation n where n.n_regionkey = r.r_regionkey}
setErrorAction Interaction
The setErrorAction interaction sets the default adapter behavior on error while performing an interaction. The value set is valid for connection. This interaction has no output.
Input Record
<record name="setErrorAction"> <field name="onError" type="onErrorAction"/> </record>
This interaction gets a single attribute which can get one of the following values:
abort: Indicates that an error is returned. This is the default behavior. next: Causes the adapter to perform the next interaction on error.
update Interaction
The update interaction specifies an SQL batch update statement (such as INSERT or UPDATE), executed by the ACX EXECUTE verb.
Input Record
The update interaction gets the input attributes listed in the following table:
Query Adapter
70-13
update Interaction Attributes Description A string which uniquely identifies the update SQL query. The batch update SQL query that you want to execute. It can be specified as an attribute or as a text sub element. Specifies whether the query is passed directly to the back-end database for processing or it is processed by the Query Processor. The default is set to false. Required Optional Yes
passThrough (boolean)
Optional
Optional Specifies whether the query execution should fail in case the batch update SQL didnt affect any row. The default is set to false. Specifies the default data source against which to execute the query. The query, in a non pass-through case may include the data source. The input parameters to the query in sequential order (as it appears in the SQL statement). You can specify the following attributes for each parameter:
Optional
inputParameter
Yes
value: A value for the parameter. type: The parameter type. Your options are string|number|timestamp|binary|xml. null (boolean): Specifies whether the value is null or not. xmlValue: Specifies the value when the parameter is of XML type.
Output Record
The update interaction output record looks like the following:
<record name="status"> <field name="id" type="string"/> <field name="sqlStatus"/> <field name="sqlCode" type="string"/> <field name="rowsAffected" type="int"/> </record>
Where:
id: The id attribute specified in the input record. sqlStatus: One of: ok| error| duplicateKey| constraintViolation| permissionError. sqlCode: The status code, indicating the query execution success or failure. rowsAffected: The number of rows affected.
A simple update interaction
Example 709
<update datasource="DISAM"> <sql> Update nv_dept set dept_budget = 2 where dept_budget = 0 </sql> </update> </execute> <disconnect/> </acx>
Example 7010 An update interaction with XML parameter <?xml version="1.0"?> <acx type="request" id="5169729"> <connect adapter="query" persistent="false" /> <execute> <update datasource="DISAM"> <sql> Update nv_dept set XML = ? where dept_id = 'DP00' </sql> <inputParameter type="XML"> <nv_dept dept_id="DP00" dept_budget="5"/> </inputParameter> </update> </execute> <disconnect/> </acx>
testDatasource: This interaction tests the connection to the specified data source. It attempts to retrieve a list of tables. transactionGetStatus: This interaction retrieves status information on failed transactions that needs to be recovered. transactionHeuristicRecover: This transaction heuristically recovers a transaction. updateStatistics: This interaction updates the specified statistics information. prepareSql: This interaction prepares an SQL query and return its metadata.
Query Adapter
70-15
localCopy: This interaction makes a local copy of a specified table. export: This interaction exports the native schema of a specified table.
The following XML request uses the query adapter to access the nation table, which is part of the NAVDEMO demo database, supplied as part of the AIS Server installation. The query returns a recordset that is formatted in the default format.
<?xml version="1.0"?> <acx> <connect adapter="query" /> <execute> <query> select * from navdemo:nation </query> </execute> <disconnect/> </acx>
Note that the table name is qualified by the data source (navdemo). The output is formatted in the default format:
<?xml version=1.0 encoding=ISO-8859-1?> <acx type=response> <connectResponse idleTimeout=0></connectResponse> <executeResponse> <recordset id=1> <record N_NATIONKEY=0 N_NAME=ALGERIA N_REGIONKEY=0 N_COMMENT=New Distributor /> <record N_NATIONKEY=1 N_NAME=ARGENTINA N_REGIONKEY=1 N_COMMENT=Far Away /> <record N_NATIONKEY=2 N_NAME=BRAZIL N_REGIONKEY=1 N_COMMENT=Nearby /> ... </recordset> </executeResponse> </acx> Example 7012
An adapter is defined with a default data source. Thus, the data source does not need to be specified in the SQL statement in the XML document.
<adapter name="demo" type="query" connect="defaulttdp=navdemo" />
The adapter demo can be used to access the nation table using the following XML:
<?xml version="1.0"?> <acx> <connect adapter="demo" /> <execute>
Query Adapter
70-17
71
Managing the Execution of Queries over Large Tables
This section includes the following topics:
n the Design Perspective Configuration view, expand the Machines with the workspace you are working with. Expand the Daemons folder, then expand the daemon with the workspace you are working with. Right- click the Workspace you want to edit, and select Open Click the General tab, find the Query governing restrictions section at the bottom of the editor.
6.
Max Number of Rows in a Table That Can be Read: Specify the number of table rows that can be read in a query. When the number of rows read from a table during query execution exceeds the number stated, the query returns an error. Max Number of Rows Allowed in a Table Before Scan is Rejected: Specify the number of table rows that can be scanned during query execution. This parameter also has an impact during query optimization.
Note: After changing the values in the WS Governing tab, you must refresh the daemon and reload the configuration.
Part XII
CDC Agents Reference
This part contains the following topics:
Adabas CDC on z/OS Platforms Adabas CDC on UNIX Platforms Adabas CDC for OpenVMS DB2 CDC (z/OS) DB2 CDC (OS/400 Platforms) Enscribe CDC (HP NonStop Platforms) IMS/DB CDC on z/OS Platforms Microsoft SQL Server CDC Oracle CDC (on UNIX and Windows Platforms) Query-Based CDC Agent SQL/MP CDC on HP NonStop VSAM Under CICS CDC (on z/OS) VSAM Batch CDC (z/OS Platforms)
72
Adabas CDC on z/OS Platforms
This section includes the following topics:
Overview Functionality Configuration Properties Change Metadata Transaction Support Security Platform Specific Information Data Types Configuring the Adabas CDC Setting up the Adabas Agent in Attunity Studio
Overview
The Attunity Stream CDC solution for Adabas on mainframe systems captures changes made to the Adabas files that are written to archive files using the User Exit 2 (UE2) procedure. The UE2 procedure is activated by Adabas when the current PLOG file is full. The Attunity Adabas agent for the mainframe maintains its own tracking file to register the archive files that are created after configuring the UE2 procedure. For information on how to configure the UE2 procedure, see Adding the Tracking File Usage Step to the UE2 Procedure. The Adabas CDC solution works with Adabas data sources that use either ADD or Predict. Adabas versions 6.2 and 7.4 are supported.
Functionality
The Adabas agent supports the basic functionality for all AIS CDC agents. You should note that the behavior for this agent when setting the Set Stream Position parameter by Time Stamp is different. In this agent the time stamp is defined per block, not per event. Timestamp of a block is defined as the last event in a block. When you configure Set Stream Position by Timestamp, it is possible to
get events that occurred before the requested event and reside in the same block as the event requested by the timestamp. If you want to capture all changes, this will return all the changes from all Adabas archive files registered in the Attunity tracking file. When capturing changes from a specific time stamp, you can select a time that is later than the creation time of the last archive file created.
The dataset names of archived Adabas PLOGs. The timestamp indicating the starting time of each archived PLOG. The Adabas session number. The starting block counter.
Configuration Properties
The following parameters can be configured for the DB2 CDC agent:
dbNumber: The Adabas database number. predictFileNumber: (Predict only) The Predict file number. predictDbNumber: (Predict only) When the Predict file resides in a different database than the data indicate the database number in which the Predict file resides.
Change Metadata
Changes are captured and maintained in a change table. The table contains the original table columns and CDC header columns. The header columns are described in the following table:
Table 721
Header Columns Description The current context. The date and time of the occurrence. The name of the table where the change was made. This column lists the operations available for the CDC agent. The available operations are:
BEFOREIMAGE UPDATE INSERT DELETE COMMIT Note: All operations for Adabas Mainframe appear as
committed in the PLOG. In case of rollback, delete will appear before commit and no rollback event is generated.
transactionID fullTransactionID sequence BEFZ indicator recordType userID fileNumber RABN imageType workRabChain The operations transaction ID. The untruncated full transaction ID of the operation, with all 64 bytes. The Adabas input record sequence This is an Adabas PLOG header field This is an Adabas PLOG header field The Adabas record type (INCLUDE or EXCLUDE) The Adabas user ID number The Adabas file number The Relative Adabas Block Number The captured image type (BEFORE or AFTER) This is an Adabas PLOG header field
Transaction Support
The Adabas CDC agent for Mainframe systems supports transactions The rollback event is not supported, instead, compensating records are supplied.
Security
The user profile for the Attunity Server (ATTSRV) must have read privileges for the archive files.
Data Types
The Adabas CDC agent for mainframe systems supports both Adabas and ADD-Adabas data sources. For more information, see Adabas Data Types.
Setting up the ATTSRVR Started Task Setting up the Tracking File Adding the Tracking File Usage Step to the UE2 Procedure
Note: Before carrying out the following tasks, be sure that the PLOG (Protection log) is active in the used Adabas instance. You may need to consult the Adabas system administrator.
Change navroot to the used Attunity HLQ. Change DBXXX so that the XXX specifies the used Adabase database number. Change the JOB card according to your site demands.
Provide two positional parameters to the UADATRF program: The name of the new archive file The length of the STCK (store clock), depending on the Adabas version. If using an Adabas version 7.4 or later, then set this parameter to a value of 8. This value indicates that the store clock uses 8 bytes. For Adabas versions earlier than version 7.4, use a value of 4. The following is an example of this step.
//ASUPDBSD EXEC PGM=UADATRF, // PARM='ADB.PLOG.D&SDATE..T&STIME 8' //STEPLIB DD DISP=SHR,DSN=Attunity.LOAD //ASADTRF DD DISP=SHR,DSN=Attunity.DEF.ADATRF.DB005
When Creating a New Project, if you are using Adabas with ADD metadata, select ADD-Adabas (mainframe). If you are using Adabas with Predict metadata, select Adabas (mainframe). The CDC solution does not support views when using Adabas with Predict metadata. When selecting tables in a CDC solution using Adabas with Predict metadata, you must use tables that include the full physical file. For information on selecting tables for the CDC solution, see Stream Service.
In the Server Configuration section, click Data Source. The Data Source Configuration window is displayed. The following figure shows the Data Source Configuration window when using Predict. If you are using ADD data, this dialog box only contains the Database number field.
3.
Database number: The Adabas database number. PREDICT File Number: (Predict only) The Predict file number. predict database Number: (Predict only) When the Predict file resides in a different database than the data indicate the database number in which the Predict file resides. If the Predict file resides in the same database, enter -1.
4.
Click Finish. The window closes. Continue with Configuring the CDC Service.
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
All changes recorded to the journal On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
4.
5.
Tracking file name: The name of the tracking file used in the UE2 procedure. See The Tracking File and Setting up the Tracking File for more information Adabas version: Select the Adabas version that you are using. If you are using a version earlier than version 7.4, then select V62; if you are using version 7.4, select V74.
6.
Click Finish.
To set up the stream service, follow the instructions in Creating a CDC with the Solution Perspective.
73
Adabas CDC on UNIX Platforms
This section contains the following topics:
Overview Functionality Configuration Properties Change Metadata Transaction Support Data Types Security Platform Specific Information Configuring the Adabas CDC Defining Adabas CDC in Attunity Studio
Overview
The Attunity Stream CDC solution for Adabas captures changes made to the Adabas files that are written to PLOG (Protection log) files. The PLOG files are polled for changes. The Adabas CDC solution is works for with Adabas ADD and Adabas Predict data sources.
Functionality
The Adabas agent supports the basic functionality for all AIS CDC agents. You should note that the behavior for this agent when setting the Set Stream Position parameter by Time Stamp is different. In this agent the time stamp is defined per block, not per event. Timestamp of a block is defined as the last event in a block. When you configure Set Stream Position by Timestamp, it is possible to get events that occurred before the requested event and reside in the same block as the event requested by the timestamp.
Configuration Properties
The following are configuration properties that you use when configuring this agent in Attunity Studio.
PLOG Name: The full path to the PLOG file without the session number. Starting Session: Enter the type of session. Adabas Version: Indicate the version of Adabas you are using. For information on the Adabas versions supported by AIS, see Attunity Integration Suite Supported Systems and Resources Virtual Block Len: This is the default size of a block in megabytes. The automatic default is 512.
This agent also supports the standard AIS Agent configuration properties. For more information, see Creating a CDC with the Solution Perspective. For information on how to enter these properties, see Defining Adabas CDC in Attunity Studio.
Change Metadata
Changes are captured and maintained in a change table. The table contains the original table columns and CDC header columns. The header columns are described in the following table:
Table 731 Header Columns Description The date and time of the occurrence. The name of the table where the change was made. This column lists the operations available for the CDC agent. The available operations are:
transactionID context
Transaction Support
The Adabas for UNIX agent supports transactions. It uses the Transaction ID to identify the transaction. This agent uses transaction demarcation. It does not use compensating records.
Data Types
The Adabas for UNIX agent supports both Adabas and ADD-Adabas data sources. For more information, see Adabas Data Types.
Security
There are no special security requirements for this agent.
Find the directory where the PLOG is created and note the session number that appears at the end of the PLOG name. For example: SAG$DEVICE:[SAG.ADABAS.DB001]PLOG.DAT;18 Find the Adabas version being used. For information on the Adabas versions supported by AIS, see Attunity Integration Suite Supported Systems and Resources.
You will need this information when you define the Adabas CDC in Attunity Studio.
Note: When Creating a New Project, if you are using Adabas with ADD metadata, select ADD-Adabas (Unix). If you are using Adabas with Predict metadata, select Adabas (Unix).
In the Server Configuration section, click Data Source. The Data Source Configuration window is displayed. The following figure shows the Data Source Configuration window when using Predict. If you are using ADD data, this dialog box only contains the Database number field.
3.
Database number: The Adabas database number. PREDICT File Number: (Predict only) The Predict file number. predict database Number: (Predict only) When the Predict file resides in a different database than the data indicate the database number in which the Predict file resides. If the Predict file resides in the same database, enter -1.
4.
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
All changes recorded to the journal On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
4.
5.
Enter the following information for the Adabas for UNIX agent:
Plog name: The directory where the PLOG is created and the PLOG name. Omit the session number which appears at the end of the PLOG name. For example, for SAG$DEVICE: [SAG.ADABAS.DB001]PLOG.DAT;18, the PLOG name should be: SAG$DEVICE:[SAG.ADABAS.DB001]PLOG.DAT4
Starting session number: The session number which appears at the end of the PLOG name. For example, if the PLOG name is SAG$DEVICE:[SAG.ADABAS.DB001]PLOG.DAT;18, the Starting Session should be 18.
Adabas CDC on UNIX Platforms 73-5
Adabas version: 221(to indicate Version 2.1.1). Versions 2.1.1. 3.1.1. and 3.3.1 are supported.
6.
Click Finish.
To set up the stream service, follow the instructions in Creating a CDC with the Solution Perspective.
74
Adabas CDC for OpenVMS
This chapter has the following sections:
Overview Functionality Configuration Properties Change Metadata Transaction Support Data Types Security Platform Specific Information Configuring the Adabas CDC Defining Adabas CDC in Attunity Studio
Overview
The Attunity Stream CDC solution for Adabas on OpenVMS captures changes made to the Adabas files that are written to PLOG (Protection log) files. The PLOG files are polled for changes. The Adabas CDC solution is relevant for Adabas ADD and Adabas Predict.
Functionality
The Adabas agent supports the basic functionality for all AIS CDC agents. Note that the behavior for this agent when setting the Set Stream Position parameter by Time Stamp is different. In this agent the time stamp is defined per block, not per event. Timestamp of a block is defined as the last event in a block. When you configure Set Stream Position by Timestamp, it is possible to get events that occurred before the requested event and reside in the same block as the event requested by the timestamp.
Configuration Properties
The following are configuration properties that are used when you configure this agent in Attunity Studio.:
PLOG Name: The full path to the PLOG file without the version number.
Starting Session: The PLOG file version number where the event logging begins. Adabas Version: Indicate the version of Adabas you are using. Currently only version 4.1.1 is supported. Virtual Block Len: The size of a PLOG file virtual block in bytes. The default value is 512.
This agent also supports the standard AIS Agent configuration properties. For more information, see Creating a CDC with the Solution Perspective. For information on how to enter these properties, see Defining Adabas CDC in Attunity Studio.
Change Metadata
Changes are captured and maintained in a change table. The table contains the original table columns and CDC header columns. The header columns are described in the following table.
Table 741 Header Columns Description The date and time of the occurrence. The name of the table where the change was made. This column lists the operations available for the CDC agent. The available operations are:
transactionID context
Transaction Support
The Adabas for OpenVMS agent supports transactions. It uses the Transaction ID to identify the transaction. This agent uses transaction demarcation. It does not use compensating records.
Data Types
The Adabas agent for OpenVMS supports both Adabas and ADD-Adabas data sources. For more information, see Adabas Data Types.
Security
There are no special security requirements for this agent.
74-2 AIS User Guide and Reference
Find the directory where the PLOG is created and note the session number that appears at the end of the PLOG name. For example: SAG$DEVICE:[SAG.ADABAS.DB001]PLOG.DAT;18 Find the Adabas version being used. Currently only Version 4.1.1 is supported.
You will need this information when you define the Adabas CDC in Attunity Studio.
2.
In the Server Configuration section, click Data Source. The Data Source Configuration window is displayed. The following figure shows the Data Source Configuration window when using Predict. If you are using ADD data, this dialog box only contains the Database number field.
3.
4.
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
All changes recorded to the journal On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Changes recorded in the journal after a specific date and time.
When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
4.
5.
Enter the following information for the Adabas for UNIX agent:
Plog name: The directory where the PLOG is created and the PLOG name. Omit the session number which appears at the end of the PLOG name. For example, for SAG$DEVICE: [SAG.ADABAS.DB001]PLOG.DAT;18, the PLOG name should be: SAG$DEVICE:[SAG.ADABAS.DB001]PLOG.DAT4
Starting session number: The session number which appears at the end of the PLOG name. For example, if the PLOG name is SAG$DEVICE:[SAG.ADABAS.DB001]PLOG.DAT;18, the Starting Session should be 18. Adabas version: 411(to indicate Version 4.1.1). Only version 4.1.1 is currently supported. Virtual block length: Enter the size (in bytes) of the virtual block in the PLOG file. For example, 512.
6.
Click Finish.
To set up the stream service, follow the instructions in Creating a CDC with the Solution Perspective.
75
DB2 CDC (z/OS)
This section includes the following topics:
Overview Functionality Configuration Properties Change Metadata Transaction Support Security Data Types Configuring the DB2 Tables for CDC Configuring the ATTSRVR Started Task Setting up the DB2 Agent in Attunity Studio
Overview
Attunity Stream CDC agent for DB2 on mainframe systems captures changes that are written to DB2 log and archive files. You connect to the agent in the same way that you connect with the DB2 data source. For more information on connecting to a DB2 database, see DB2 Data Source. The DB2 CDC agent uses the DSNJU004 module internally to find an archive or log file that contains the first LRBA corresponding to the provided timestamp, based on the provided bootstrap data set. See Configuring the CDC Service for more information. The DB2 CDC agent uses the IFI interface to capture the records from the log. The monitoring process is started using the IFI command, -STA TRA(MON) CLASS(1) IFCID(306). Creating the CDC solution for DB2 is performed in Attunity Studio using a wizard as described in Creating a CDC with the Solution Perspective.
Functionality
The DB2 CDC for mainframe systems supports the basic functionality for all AIS CDC agents with the exception of the Limitations listed in the section below.
Limitations
The DB2 agent has the following limitations:
The DB2 agent does not support the All changes recorded in the journal mode. If you choose to consume changes from a specific date and time (timestamp), the DB2 agent uses the DSNJU004 module internally to find an archive or active log file that contains the corresponding log records. Then it reads the changes sequentially from the beginning of the file until the log record corresponding to the provided timestamp is found. The DB2 agent does not support DB2 Data Sharing (also known as DB2plex).
z/OS. For more information, see Attunity Integration Suite Supported Systems and Resources.
Configuration Properties
The following parameters can be configured for the DB2 CDC agent:
Location: The DB2 location name for the connected DB2 instance. The parameter should be specified if the connected DB2 instance is different than the instance defined in the MVSDEFAULTSSID parameter of the ODBCINI file. Database name: Enter the existing DB2 database name, only if you are creating new tables using AIS. Bootstrap dataset name: This dataset is used to keep track of the DB2 logs.
Change Metadata
Changes are captured and maintained as a change table. The table contains the original table columns and CDC header columns. The header columns are described in the following table:
Table 751 Header Columns Description The date and time of the event. The name of the table where the change was made. This column lists the operations available for the CDC agent. The available operations are (set as hex values):
Table 751 (Cont.) Header Columns Column Name transactionID RBA context Description The identifier for the transaction. The event LRBA The current internal context
Transaction Support
The Attunity DB2 agent for mainframe systems supports transactions.
Security
To work with Attunity Stream and DB2, the following requirements must be met:
All the libraries in the ATTSRVR STEPLIB must be APF-Authorized. Provide the following grants to the owner of the ATTSRVR started task.
Purpose This command grants the -start trace() privilege. This command grants the READA and READS IFI requests privilege.
The owner of the ATTSRVR started task must have privileges in DB2 to run offline. For details about setting DB2 security to use DB2 with Attunity Stream, refer to Attunity Server Installation Guide for z/OS.
Data Types
The following data types are supported by the DB2 CDC agent:
All standard DB2 data types are supported by the DB2 agent for mainframe except for large objects (BLOBs and CLOBs). User defined data types are not supported.
Configure the ODBCINI file defined in the DSNAOINI DD card of the ATTSRVR started task. In most cases, you can use the default configurations in the ODBCINI file however, you can make changes to the file, if needed. The following is an example of the ODBCINI file:
; This is a comment line... ; Example COMMON odbcini COMMON MVSDEFAULTSSID=DSN1 ; Example SUBSYSTEM odbcini for DSN1 subsystem DSN1 MVSATTACHTYPE=CAF PLANNAME=DSNACLI
The following table describes the configurations that are important for the DB2 CDC agent.
Table 752 ODBCINI configuration values Description The Sub-System ID (SSID) of the default used DB2 instance. Use the CAF only. If MVSATTACHTYPE has the RRSAF value, the DB2 agent will not work. PLANNAME The DB2 Calling Level Interface (CLI) plan name. Usually the name of the CLI plan is DSNACLI (as defined in HLQ.SDSNSAMP(DSNTIJCL) job).
You can specify other parameters in this file, as described in the IBM ODBC Guide and Reference.
In the Server Configuration section, click Data Source. The following is displayed.
3.
Location: Enter the DB2 location name for the connected DB2 instance. The parameter should be specified if the connected DB2 instance is different than the instance defined in the MVSDEFAULTSSID parameter of the ODBCINI file. Database name: Enter the existing DB2 database name, only if you are creating new tables using AIS.
4. 5.
Click Next. Enter the User Name and Password, if you need to provide security credentials to the DB2 database. Click Finish.
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
4.
5.
Bootstrap dataset name: This dataset is used to keep track of the DB2 logs.
6.
Click Next and select one of the following from the drop-down list to define the logging level:
7.
Click Finish.
To set up the stream service, follow the instructions in Creating a CDC with the Solution Perspective.
76
DB2 CDC (OS/400 Platforms)
This section describes the DB2 CDC agent on OS/400. It includes the following topics:
DB2 CDC Agent Overview Functionality Configuration Properties Change Metadata Transaction Support Data Types Security Platform Specific Information Setting-up the DB2 Journal on OS/400 Setting-up the DB2 for OS/400 Agent in Attunity Studio
Functionality
The Attunity DB2 for OS/400 CDC agent supports the basic functionality for all AIS CDC agents with the exception of the Limitations listed.
Limitations
The DB2 for AS/400 agent has the following limitations:
The DB2 for AS/400 agent does not handle rollback to savepoint type transactions correctly because some of the rolled back events are reported.
Configuration Properties
The following parameters must be configured for the DB2 CDC agent:
Journal library name: The name of the library where the journal is located.
Change Metadata
Changes are captured and maintained in the journal as events. The journal contains the original table columns and CDC header columns. The header columns are described in the following table:
Table 761 Header Columns Description
Column Name
The date and time of the occurrence. The name of the table where the change was made.
This column lists the operations available for the CDC agent. The available operations are (set as hex values):
transactionID
context
Headers (these headers are also returned, and can be used in a consumer application to filter the information retrieved)
journalCode jobName jobNumber fileName memberName userProfile entryType userName programName libraryName RRN systemName referentialConstraint objectNameIndicator trigger
Transaction Support
The DB2 for OS/400 supports single-phase transactions only.
Data Types
The DB2 for OS/400 can use all of the data types supported by the DB2 data source. For information on the supported data types, see DB2 Data Types.
Security
No specific security measures are required for this agent.
If you are upgrading from a previous version that supported User managed journals only, be sure to consume all changes and redeploy the solution in the current version to use System Managed Journals.
The following steps are used to configure the logstream and make it accessible to an application. To set up the journal 1. In the primary DB2 screen, create a journal receiver by executing the following command:
crtjrnrcv
The Create Journal Receiver screen is displayed, as shown in the following figure:
Figure 761 Create Journal Receiver Screen
2.
Set the required values for the following parameters, then press Enter.
DB2 CDC (OS/400 Platforms) 76-3
Journal receiver: The journal receiver name (up to 10 characters). Library: An existing library name to create the receiver in (up to 10 characters). ASP number: The ASP Number. Leave the default value.
Note:
A value less than 100,000 will automatically be reset to 100,000. When the size of the space for the journal receiver is larger than the size specified by this value, a message is sent to the identified message queue if appropriate, and journaling continues.
Journal receiver threshold: A storage space threshold value (in KB) for the journal receiver. Enter a value ranging between 100,000 and 1,000,000,000 (KB) of storage. Text description: A text description of the connection.
3.
4.
Set the required values for the following parameters, then press Enter.
Journal: The journal name (up to 10 characters). Library: The existing library name (up to 10 characters). This name can be the same name used for the journal receiver. Journal receiver: The journal receiver name, which was created in the previous step. Library: The name of journal receiver library. Manage receivers: The journal manager. Set this field to User.
5.
The Start Journal Physical Files screen is displayed, as shown in the following figure:
Figure 763 Start Journal Physical File screen
6.
Set the required values for the following parameters, then press Enter.
Physical file to be journaled: The physical file name of the table to be journaled. Only tables specified in the journal are captured, irrelevant of the tables listed to be captured in Attunity Stream.
Note:
The file name changed from the logical file name if the SQL name exceeds 10 characters. For example, THE_NEW_TEST_TABLE logical name can have THE_N00001 as the physical file name. To retrieve system table names, use the following SQL query:
select system_table_name from qsys2.systables where table_name like THE_NEW_TEST_TABLE and system_table_schema like NEWLIB
Library: The library name where database files resides. (+ for more values): Add multiple tables by entering + in this field. A new screen opens where up to 50 files can be added to the journal. Journal: The name of the journal created in the previous step. Library: The library name where the journal was created. Record images: Set *AFTER to record only after image events. Set *BOTH for both before and after image events. Journal entries to be omitted: Leave this field with its default setting.
Note:
When selecting the tables captured in the CDC agent, all the database tables are displayed, whether specified in the journal or not. If you choose tables not defined in the journal, they will not have updates captured.
In the Server Configuration section, click Data Source. The following is displayed.
3.
Database name: Enter the existing DB2 database name, only if you are creating new tables using AIS. Library name: The name of the library that contains the database tables.
4.
Figure 765
5. 6. 7.
At the top of the window, enter the Default table owner. This is the name of the person that owns the DB2 table where the changes are consumed. Enter the User Name and Password, if you need to provide security credentials to the DB2 database. Click Finish.
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
All changes recorded to the journal On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
Select Include capture of before-image records if you want to begin logging records before the image.
4.
5.
Journal file name: Enter the name of the physical file name of the journal file. Journal library name: Enter the name of the library that has the journal.
6.
Click Next and select one of the following from the drop-down list to define the logging level:
7.
Click Finish.
77
Enscribe CDC (HP NonStop Platforms)
This section contains the following topics:
Overview Functionality Configuration Properties Change Metadata Transaction Support Data Types Security Platform-specific Information
Overview
Attunity Stream CDC solution for Enscribe captures changes that are written to the Enscribe database guarded by the Transaction Management Facility (TMF).
Functionality
The Enscribe CDC agent supports the basic functionality for all AIS agents.
Notes: The Enscribe Agent does not fully support unstructured files. If you want to use the Enscribe CDC to capture an unstructured file, you must make sure that any application that changes this file defines its metadata (or at least the buffer size) the same way its defined in Attunity Connect.
Configuration Properties
The Enscribe CDC agent supports the standard configuration properties for all AIS agents.
Change Metadata
Changes are captured and maintained in a change table. The table contains the original table columns and CDC header columns. The header columns are described in the following table:
Table 771
Header Columns Description The date and time of the occurrence. The name of the table where the change was made. This column lists the operations available for the CDC agent. The available operations are:
The current context. The operations transaction ID. The name of the file where changes are made.
In the data portion, the following data is received from the TMF file:
Sequential file: The RBA field that contains the changed record number. Relative file: The RRN field that contains the relative record number of the changed record. Unstructured file: The RBA field that contains the changed record number.
Transaction Support
The Enscribe CDC agent supports transactions.
Data Types
The Microbe CDC supports all Enscribe Data Types.
Security
There are no specific security requirements for the Enscribe CDC agent.
Platform-specific Information
There is no platform specific information for this CDC agent.
Set the following attributes for the tables that are captured:
FUP ALTER filename, AUDIT FUP ALTER filename, NO AUDITCOMPRESS
Note:
3.
Copy the script that was generated after the deployment to the Tandem terminal prompt.
In the Server Configuration section, click Data Source. The following is displayed.
3.
Data sub-volume:
4.
Click Finish.
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Master audit trail sequence number Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
4.
5.
6.
Click Finish.
To set up the stream service, follow the instructions in Creating a CDC with the Solution Perspective.
78
IMS/DB CDC on z/OS Platforms
This section describes the Attunity IMS/DB CDC agent. It includes the following topics:
Overview Functionality Configuration Properties Change Metadata Transaction Support Security Data Types Configuring the DFSFLGX0 Exit Setting-up the IMS/DB CDC Agent in Attunity Studio Troubleshooting
Overview
The Attunity Stream CDC solution for IMS/DB, captures changed IMS/DB segments that are passed to the DFSFLGX0 IMS user exit, and saves them in an MVS logstream. The IMS/DB CDC Agent polls the logstream for the changes. Creating a CDC solution for IMS/DB is executed in Attunity Studio. A staging area is used, enabling the elimination of uncommitted changes from being captured, and to reduce the number of the change events generated. For more information, see The Staging Area.
Functionality
The Attunity Stream CDC IMS/DB Batch solution uses its own DFSFLGX0 IMS/DB exit routine for capturing the IMS/DB changes. If another DFSFLGX0 user exit is used, the CDC solution cannot work. The IMS/DB CDC agent supports the basic functionality for all CDC agents. To enable writing IMS/TM internal buffers, the agent sends the IMS/TM CHECKPOINT command, using MCS, or replying to an IMS/TM DFS996I message.
z/OS IMS/TM
For information on the operating system versions supported by AIS, see Attunity Integration Suite Supported Systems and Resources.
Configuration Properties
The following properties can be configured for the IMS/DB CDC solution:
CDC$PARM Properties
CDC$PARM is the name of DD card that defines a QSAM data set or PDS member that contains the parameters for a DFSFLGX0 user exit. For an explanation on how to create this and its syntax see Creating and Configuring the CDC$PARM Data Set. The following list describes the CDC$PARM properties:
BUFFER_NUM: The logstream buffer number. The valid values are Default-30. BUFFER_SIZE: The logstream buffer size. The valid values are Default-22550 bytes. DEBUG: If this is ON the debug information is printed using WTO. The default value is OFF. LOGSTREAM: The logstream name. The default value is ATTUNITY.IMS.DCAPDATA.
Agent Properties
The agent properties described below are configured if you want the CHECKPOINT to be sent to IMS/TM instance. If the checkpoint is not configured, the changes may be captured by DFSFLGX0 exit with a delay, if IMS/TM Control Region executes a small amount of updates. The CDC agent properties are configured after the deployment of the solution using the Attunity Studio, Design perspective.
envImsBatch: Set to false to execute the CHECKPOINT command. The default value is true. checkPointFrequency: The frequency for issuing checkpoints. The default value is 60 (seconds). The smallest time frequency supported is 10 seconds. consoleCheckPoint: Set to true to use and extended MCS console. If false a reply to WTOR is used. The default value is true.
imsJobName: IMS job name for the IMS/TM for which the WTOR reply to the message DFS996I should be sent. This must be provided if be provided if more than one IMS/TM instances run on a Z/OS box. consoleCheckPointCommand: The command that should be sent to the MCS console. The default value is "/CHE."
Change Metadata
Changes are captured and maintained in a change table. The table contains the original table columns and CDC header columns. The header columns are described in the following table:
Table 781 Header Columns Description The records current context. This column lists the operations available for the CDC agent. The available operations are:
transactionID tableName
The operations transaction ID. The name of the table where the change was made. For INSERT, UPDATE, and BEFOREIMAGE operations, the owner name and then the table name are displayed. For COMMIT and ROLLBACK operations, this value is the same as the OPERATION value.
timestamp
Transaction Support
IMS/DB CDC supports transactions within IMS/DB transaction boundaries. However, no compensating records are available in the log in case of rollback.
Security
The IMS/DB CDC adapter connects to the MVS logstream with an authorization level of READ. The DFSFLGX0 user exit connects to the logstream with an authorization level of WRITE. To determine the proper security authorizations see the MVS Auth Assm Services Reference ENF-IXG IBM manual.
Notes:
To access a logstream in an application with a READ authorization level, set the READ access to RESOURCE(<logstream name>) in SAF class CLASS(LOGSTRM). To update a logstream in a program with a WRITE authorization level, set the ALTER access to RESOURCE(<logstream name>) in SAF class CLASS(LOGSTRM).
Data Types
All data types supported by the IMS/DB data source are supported by the IMS/DB CDC solution.
MVS Logstream Creation Creating and Configuring the CDC$PARM Data Set Update the IMS Environment Adjust the DBD for the Relevant Databases
Delete all events Delete events to a specific timestamp Print events between two timestamps Print all events from the oldest to a selected timestamp Print all events from the newest to a selected timestamp Print all events
A sample job for managing MVS Logstreams called ATTUNITY.CDC.VSAMBTCH is supplied in the <HLQ>.USERLIB(RUNLOGR) member.
The data set contains parameters, one parameter on a line, according to the follow syntax: <parameter name>=<parameter value> The parameters and their valid values are described in CDC$PARM Properties.
Copy the supplied DFSFLGX0 exit module from the Attunity supplied <HLQ>. LOADCDIM library to the IMS RES library. If necessary, add the CDC$PARM DD card to the IMS Control Region and batch jobs. Restart the IMS Control Region.
Adjust the DBD for each IMS/DB database that is included in your CDC solution, defining the usage of DFSFLGX0 exit, by adding the following parameter to the DBD macro:
EXIT= (*, KEY, NOPATH, DATA, LOG, (CASCADE, KEY, NODATA, NOPATH))
Recompile DBD and the corresponding PSB and ACB objects, then restart the IMS Control Region.
After you set up the IMS/DB CDC agent, follow the directions in Setting the envlmsBatch Property. This is done in the Attunity Studio Design perspective. Before setting-up the IMS/DB CDC agent, make sure that:
The IMS system and logstream are properly configured, as described in Configuring the DFSFLGX0 Exit. The security measures are implemented, as described in Security. If you did not import the metadata while creating the CDC solution, see Setting the envlmsBatch Property.
Note:
When you set up an IMS/DB CDC solution, you must know what type of IMS data source you are using. For more information on using the IMS/DB DLI data source, see Defining the IMS/DB DLI Data Source. For more information on using the IMS/DB DBCTL data source, see, Defining the IMS/DB DBCTL Data Source For more information on using the IMS/DB DBDC data source, see Defining the IMS/DB DBDC Data Source
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
All changes recorded to the journal On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
4.
5.
Enter the Change Logger Name and specify the name for the logger, as entered in the IMS system fix 80 file. This is configured when Configuring the DFSFLGX0 Exit. the default name for the logger is ATTUNITY.IMS.DCAPDATA. If you changed the name when configuring IMS, then enter the new name in this field.
6.
Click Next to go to the next step where you set the CDC Service Logging. Enter the CDC logging level in this step.
7.
Click Finish.
2. 3. 4.
Right-click the adapter for the change data capture, and select Edit Adapter. Select the Properties tab from the adapter editor. Change the value for the envImsBatch property to False, as shown in the following figure:
5.
Troubleshooting
This section describes how to troubleshoot the IMS/CDC agent. Review the following checklist:
Look for any errors in the IMS job. Ensure a message similar to the following appears under the IMS:
DD JESYSMSG: DFSFLGX0 Attunity CDC *Active*
Where HLQ is the high-level qualifier where Attunity Server is installed, as shown in the following example:
//RUNLOGR JOB 'RR','TTT',MSGLEVEL=(1,1),CLASS=A, // MSGCLASS=X,NOTIFY=&SYSUID,REGION=8M //* //LOGR EXEC PGM=ATYLOGR, //*PARM=('/DEBUG ATTUNITY.IMS.DCAPDATA MAXLEN 1024 ', // PARM=('/NAME ATTUNITY.IMS.DCAPDATA MAXLEN 1024 ', // 'PRINT FROM 2005-03-13,02:13:57 TO 2007-10-27,02:38:23') //* 'DELETE ALL') //* 'DELETE TO 2004-10-28,02:17:11') //* 'DELETE TO YOUNGEST') //* 'PRINT FROM 2003-12-23,22:07:16 TO 2004-10-27,02:38:23') //* 'PRINT FROM OLDEST TO 2007-10-27,02:38:23') //* 'PRINT FROM 2004-10-27,02:51:57 TO YOUNGEST') //* 'PRINT FROM OLDEST TO YOUNGEST') //STEPLIB DD DISP=SHR,DSN=TEST.AC4800.LOADCDCY
To use RUNLOGR, un-comment the option you want to use and submit the member. The following options are available: Delete all events. Delete events to a specific timestamp. Delete the newest events. Print events between two timestamps. Print all the events from the oldest to a specified timestamp. Print all the events from the newest to a specified timestamp. Print all the events.
79
Microsoft SQL Server CDC
This section contains the following topics:
Overview Functionality Supported Versions and Platforms Configuration Properties Change Metadata Transaction Support Data Types Security Platform Specific Information Setting up the SQL Server CDC in Attunity Studio Enabling MS SQL Replication Configuring Security Properties Setting up Log On Information Setting up the Database Setting Up the TLOG Miner (LGR) Testing Attunitys Microsoft SQL Server CDC Solution Handling Metadata Changes Environment Verification
Overview
Attunitys Microsoft SQL Server CDC solution is based on the MS SQL databases Transaction Logs (TLOG). TLOG records are identified by a Log Sequence Number (LSN). The LSN is used by Attunitys Microsoft SQL Server CDC agent to identify log stream records. When logging an UPDATE operation, the MS SQL Server records only changed data to the TLOG. This is not enough information for the CDC agent to provide before and after images for UPDATE statements. There is not enough information to provide the values for changed columns with primary keys, which is the minimum requirement for a CDC agent.
To solve this problem, you must turn Replication on in the MS SQL Server. The log will be able to report update changes as usual. In addition, Before Image results are also supported in this mode. Replication is valid only for tables with primary keys. Therefore, the MS SQL Server CDC Agent works only with tables that have a primary key. The Microsoft Replication solution used by Attunitys MS SQL Server CDC must be enabled by a qualified system administrator. The system administrator must use the tools provided with the MS SQL Server to enable replication. For information, see Enabling MS SQL Replication. The Microsoft SQL Server handles logs in a way that is not fully compatible with standard Attunity CDC solutions. For example, the MS SQL Server will truncate a TLOG after a period of inactivity to make more space available for logging operations. Uncontrolled LOG truncation could cause a loss of the truncated data. To solve these problems, Attunitys MS SQL Server CDC solution uses a TLOG miner. This component is initiated as a Microsoft Windows service. It mines the data and sends it to a Transient Storage area. The MS SQL Server CDC agent uses the data in Transient Storage to consume changes. For detailed information on the flow and architecture of this solution, see Microsoft SQL Server CDC Solution.
This figure shows that in order to capture the changes in the MS SQL Server TLOGs, a TLOG miner mechanism is used to extract the necessary data and place it into Transient Storage. The data in the Transient Storage logs is used to carry out the standard CDC solution. These sections, explain the main blocks in the diagram.
MS SQL Server
MS SQL Server
The Microsoft SQL server creates transaction logs that log server activity for recovery purposes. When using Replication, the logs hold information in a format that is consumable by Attunitys CDC agents. For more information, see Enabling MS SQL Replication. The TLOGs are divided into two sections. The active section of the TLOG contain the changes made to the currently active transaction. The reusable or inactive section has the information from older transactions, which do not require further processing by MS SQL server. This space is reusable. It is possible to back up the data or the MS SQL Server might truncate the log to create more space. When a TLOG is truncated, some of the data is dropped and is no longer available for the CDC agent to use. The Attunity CDC solution for the MS SQL Server is designed to prevent potential data loss.
TLOG Miner
The TLOG miner (LGR) is an Attunity component and is installed as a stand-alone Microsoft Windows service. It reads the TLOG file and extracts or mines the data and send them to the Transient Storage area. It has two parts.
TLOG Detainer: The Microsoft SQL Server management policy periodically reorganizes the data files when necessary. In this case, the data files are truncated when data is no longer active. The truncated data is erased from the system and cannot be used. Occasional truncation of the transaction LOG can expose the LGR to potential loss of data. No appropriate means are provided for controlling these activities. The detainer is used to prevent TLOG data loss from truncation. Truncation only takes place in the non-active section of the TLOG. The detainer places a detained transaction behind the logged records to be read. This creates a limit for the TLOGs active portion, which protects records from being truncated before they are read.
TLOG Parser: The parser parses the TLOG information and then writes it into Transient Storage.
The miner process must be active at all times to prevent loss of changes Change records must be finished to disk before releasing the TLOG detainer Start the service when the machine is started or restarted The miner must be able to restart automatically (see note below)
Manage this service with the Windows Services utility. Set the recovery options to Restart the Service for all failures (see Setting the Recovery Policy.
Note:
Transient Storage
The LGR sends the data it mines from the TLOG into Transient Storage. The log records are kept in Transient Storage according to the LGR cleanup policy.
The CDC consumer reads the changes from Transient Storage, not from the data source itself. The Microsoft SQL Server agent uses the data in transient storage to consume the changes. Transient Storage is implemented as sequential-variable flat files. These files must have a defined size limit. You must also indicate a working folder to store the Transient-Storage files. For more information, see Configuration Properties.
Functionality
The Microsoft SQL Server CDC agent supports the basic functionality for all CDC agents, with the exception of specific Limitations listed in the following section.
Limitations
The MS SQL Server CDC agent has the following limitations:
Savepoints are not supported. Therefore, you cannot rollback to a specific savepoint. Compensating records are not handled. The timestamp used is not exact. It provides an approximate value. When using the Microsoft SQL Server 2005 on the backend, the Attunity MS SQL CDC Agent does not support the MS SQL 2005 Large Row feature, which allows variable data to overflow beyond 8KB page limits.
Note:
If you use varchar or nvarchar data types, and the amount of data is more than 8kb, the CDC will read the field as vacant. The data is replaced by an ~Overflow:Vacant~ designator.
This is because that when the consuming changes, the CDC must have all data present. In some cases, the MS SQL Server will truncate data. When the CDC encounters an MS Large Row instance, it acts as follows: If the data in a row is greater than 8kb, then the overflowed data (which was moved by MS SQL Server to an overflow page and handled like a BLOB) is read by the CDC as vacant and designated as such. However, if the amount of data fits 8KB page limits, the CDC will handle it normally.
When using the Microsoft SQL Server 2000, in very few cases, an Update operation, is executed as an Delete/Insert pair. This is related to internal MS SQL Server behavior. The MS SQL Server agent will report this as it was executed by the SQL Server (a Delete/Insert pair). The Microsoft SQL Server CDC agent does not support filtering of events. This is because of the need for preserving consistency under all circumstances. An UPDATE may, in very few cases, be executed by the SQL Server as a DELETE/INSERT pair. In this case, the filtering of the DELETE values will break the consistency to the logical UPDATE that was originally executed. The same is true for column values where filtering by a given value can match a DELETE event associated with an UPDATE but not its INSERT pair.
When using the Microsoft SQL Server 2000, problems may occur while capturing changes to tables with a clustered non-unique index. Therefore, data captures in tables with this type of index are not supported by the MS SQL Server on the backend. When using Mircrosoft SQL Server 2005, there may be infrequent instances where there is truncation.This may occur due to the combinations of record fields of various data types when their total actual storage size and internal overhead space is more than 8000 bytes. Captured table names cannot be more than 31 characters in length.
Configuration Properties
Configure the following Environmental property in Attunity Studio:
transientStorageDirectory: Enter the full path to the folder with the Transient Storage file.
In addition, you must install the TLOG miner, create the TLOG Miner (LGR) service, and enable MS SQL Replication. See the following sections for more information.
Change Metadata
Changes are captured and maintained in a change table. The table contains the original table columns and CDC header columns. The header columns are described in the following table:
Table 791 Header Columns Description The records current context.The change record stream position in the Staging Area. The column is defined as primary unique index. For more information, see Change Tables. The original change record stream position from the agent (non-numeric). This column is defined as alternate, descending unique index. It is used for the following:
1. 2. 3.
agent_context
It ensures that a change event does not appear more than once in the change table. It allows scanning of a change table backwards, peeking easily for the last N change events. When working with complex records, multiple records may result from a single back-end change record. This column enables the user to associate these records with the single change record.
Table 791 (Cont.) Header Columns Column Name operation Description This column lists the operations available for the CDC agent. The available operations are:
transactionID
The operations transaction ID. The transaction ID is increased each time a new transaction starts and a BEGIN_AXACT record is logged. The name of the table where the change was made. For the DML operations, the owner name and the table name are displayed. For COMMIT and ROLLBACK operations, this value is the same as the OPERATION value (either COMMIT or ROLLBACK).
tableName
rowID timestamp
An identifier for the row. The date and time of the occurrence. In MSSQL Server, the timestamp is an approximate value, which comes from the most recent MS SQL Server COMMIT/ROLLBACK records scanned where a timestamp is recorded.
Transaction Support
The Microsoft SQL Server agent supports transactions.
Data Types
The following table shows the AIS data types and their SQL equivalent that are supported by the Microsoft SQL Server CDC agent. In addition to the data types listed in this table, there is some limited support for User Defined Data Types (UDT).
Table 792 Char Char Datetime Decimal Double Float Int Money Nchar Supported Data Types SQLCHAR SQLCHAR SQLDATETIME SQLDECIMAL SQLFLT8 SQLFLT8 SQLINT4 SQLMONEY SQLNCHAR
Table 792 (Cont.) Supported Data Types Char Nvarchar Numeric Real Smalldatetime Smallint Smallmoney Tinyint Bigint Binary Varchar Bit (Limited to one column per table) Ntext- Value processing is skipped. The filed is exposed as NULL Text - Value processing is skipped. The filed is exposed as NUL. Uniqueidentifier SQL_UNIQUEIDENTIFIER SQLCHAR SQLNVARCHAR SQLNUMERIC SQLFLT4 SQLDATETIM4 SQLINT2 SQLMONEY4 SQLINT1 SQL_BIGINT SQLBINARY SQLCHAR SQLBIT
Note:
The Microsoft SQL Server agent supports only the data types listed in the Supported Data Types table.
The following data types are supported by Attunitys MS SQL Driver, however the CDC Agent does not support them:
Varbinary Image Timestamp: The MS SQL timestamp data type is a type of automatic record change sequencer. It is not handled by the driver or the CDC Agent. Cursor SQL_VARIANT Table XML
Security
The following are some specific security requirements for this CDC agent:
You must have an account with administrator rights to run the MS SQL Server and MS SQL Server CDC components. The CDC agent and the TLOG Miner (LGR) must be executed as members of the sysadmin server role.
A full (thick) installation of AIS. This should include Attunity Studio and the Attunity Server. Make sure that you have a valid licence for all Attunity products. Microsoft SQL Server 2000 or 2005 (Standard, Enterprise, or SBS editions). For MS SQL Server 2005 you must use Service Pack 1 or higher.
The Microsoft SQL Server agent works on Windows platforms only. It works according to standard Windows requirements.
In the Create new project screen, type a Project Name. Select Change Data Capture and then select SQL Server as shown in this figure:
4. 5. 6.
Click Finish to close the New Project screen and then click Design from the Project Guide. Enter the details for your project. When you select the machines in your design, use one machine. You select machines in the following screen.
If you select a Staging Area machine, you should select Server Machine. This will create the Staging Area on the same machine specified as the Server Machine. Although this is not the default selection, and you can select a different machine, for guaranteed delivery reasons, Attunity recommends a One Machine solution when working with the SQL Server CDC. For more information on how to enter the information for the Design window, see Design Wizard.
7.
Click the links in the under Implement to enter the information requested for the database and stream service configurations. When you enter the information about the data source:
The SQL Server Name and dbName must be in the same literal form as the server and database names given when Setting Up the TLOG Miner (LGR).
Select Include capture of before image records if you want to include these records in the CDC solution. Enter the path to the folder where the transient storage is located. This should be the same location as defined in the LGR setup. The transient storage should be on the same machine where the CDC agent is defined. The following figure shows the Transient Storage section of the CDC Service window.
For more information on how to enter the information in these windows, see Implementation Guide.
8.
Enabling MS SQL Replication Configuring Security Properties Setting up Log On Information Setting up the Database Setting Up the TLOG Miner (LGR) Run the SQL Server Replication Script that appears in the Deployment Summary. For more information, see Deployment Guide
In the Microsoft SQL Server Management Studio, right-click the Replication folder and select Configure Distribution.
79-11
The Configure Distribution wizard opens. You should make the following selections in the wizard:
In the Distributor step, select <SQL Server Name> will act as its own distributor; SQL Server will create a distribution database and log In the SQL Server Agent Start step, select Yes, configure the SQL Server agent to start automatically
Set the Authentication settings to SQL Server and Windows. Set the Audit level to None.
To access the SQL Server (MSSQLSERVER) service properties 1. From the Windows Start menu, select Control Panel.
2. 3. 4. 5.
Double-click Administrative Tools. Double-click Services. The Services control panel is displayed. From the Services list, right-click SQL Server (MSSQLSERVER) and select Properties. Configure the system as shown in the figure below.
The configuration shown is the default for the IRPCD and LGR services, which allows anonymous access. If you want the SQL Server (MSSQLSERVER) to Log on using Windows authentication, the system administrator must enter the correct settings to log On to accounts for Attunity services.
In the database properties Options tab, set the Recovery Model to Full. In this mode, the transaction Log is more durable and truncation occurs less frequently. Create enough log space to handle the size of the published database. In the database properties Transaction Log tab, select the correct setting for File Growth based on the applications capacity profile. Set the trunc. log on chkpt property to FALSE. To set this property, enter the following in the SQL Query Analyzer:
EXEC sp_dboption '<database name>', 'trunc. log on chkpt.', 'FALSE'
Make sure that all tables that will be consumed by the SQL Server CDC have a primary key.
79-13
Note:
See the documentation provided with Microsoft SQL Server for information on how to set the above properties correctly.
From the Object Explorer, right click the database and select Properties. In the Options tab, set the Recovery model to Full. In this mode, the transaction Log is more durable and truncation occurs less frequently. Create enough log space to handle the size of the published database. From the Object Explorer, right click the database and select Properties. In the Files tab, set the initial size and growth parameters for the log files based on the applications capacity profile. Set the trunc. log on chkpt property to FALSE. To set this property, run the following query:
EXEC sp_dboption '<database name>', 'trunc. log on chkpt.', 'FALSE'
Make sure that all tables that will be consumed by the SQL Server CDC have a primary key.
Note:
See the documentation provided with Microsoft SQL Server for information on how to set the above properties correctly.
Call the LGR Service Interface Configuring the Template Input File Registering the TLOG Miner (LGR) Service Setting the Recovery Policy
The service interface is displayed. The service interface shows commands that you can use. The following is an example of the service interface that is displayed.
SQLCDCLGR Transaction LOG mining service controller: ---------------------------------------------------sqlcdclgr -s register -a <service-name> <input-file> Register a service and its input file
sqlcdclgr -s unregister -a <service-name> Unregister a service sqlcdclgr -s start -a <service-name> Start service execution sqlcdclgr -s stop -a <service-name> Stop service execution sqlcdclgr -s restart -a <service-name> Restart service execution (=refresh parameters) sqlcdclgr -p name <service-name> Display input file P_arameter name registered for a service sqlcdclgr -p contents <service-name> Display input file P_arameter contents registered for a service sqlcdclgr -p help Display help for parameters values assignment sqlcdclgr -t T_ype an input file template sqlcdclgr -b <input-file> Run the service in an online 'B_locking' mode, using input file sqlcdclgr [-h|-?] Display this H_elp banner Service input is held at: HKEY_LOCAL_MACHINE\SOFTWARE\Attunity\Attunity Server\Services
You must enter the correct values for some of the parameters in this file. These parameters are shown as placeholders ?xxx? in the example above. Enter the current information for your system where the placeholders are shown. The following table describes the parameters to be changed.
Table 793 Property Origin Configuration Parameters Parameter database Parameter Description Enter the name of the MS SQL server database you are using. The name given for the database must be in the same literal form as the name given to the dbName when Setting up the SQL Server CDC in Attunity Studio.
79-15
Table 793 (Cont.) Configuration Parameters Property Parameter server Parameter Description Enter the name of the server machine where the MS SQL Server is installed. The name given for the server must be in the same literal form as the name given to the SQL Server Name when Setting up the SQL Server CDC in Attunity Studio. user Enter the name of the authorized user for the server. Note: The user entered must have sysadmin permissions in the MS SQL database. password useWindowsAuthenti cation Enter the password for the user entered in the User parameter. The default value for this property is false. Change this property to true if you want to use Windows authentication. In this case, when you start the LGR service you do not need to provide credentials to sign in to the MS SQL Server. Enter the full path to the directory where the transient storage files are located. The maximum size (in MB) allowed for a single transient storage file. For this parameter, you can change the default value.1 The maximum size (in MB) allowed for all of the transient storage. For this parameter, you can change the default value.1 For this parameter, you can change the default value.1 For this parameter, you can change the default value.
totalSize
lowThreshold highthreshold
Table 793 (Cont.) Configuration Parameters Property logging Parameter directory Parameter Description Enter the full path to the directory where he log files are located. LOG files are named by adding the leading prefix, SQLCDCLGR, then the server machine identifier and the database name. An example of an LGR file name is: SQLCDCLGR-192_168_165_ 167+CDClog5#0002.log You can view the information about the log file for an LGR instance in the Windows Event Properties dialog box.
control
batchSize retryInterval
The limit of the batch size for records being read upon a single LGR scan pass. The time interval in seconds that the system waits for additional information when the number of lines is less than defined in the batch parameter. Set the level for the debugging log. Set true or false to determine if trace information is returned to the log. Set true or false to determine if tracing statistics are returned to the log. Set the amount of time is seconds that data is held in the TLOG before it can be truncated. You can change the default for this parameter. This is not an active parameter. Set true or false to determine whether to trace the detainer activity and send the information to the log.
Transient storage management is space oriented. It is based on a maximum allowed allocated space (default:100MB) and upper/lower thresholds. After every LOG scan, the LGR checks whether the transient storage space is close to exceeding its upper threshold (by default it checks to see if the storage space it at 85% or more). If it is close to exceeding the maximum space, a cleanup is started. The cleanup reduces the occupied space to the lowThreshold parameter (default 65%) of the total size specified. Cleanup activity is always reported in the LGR log file for all debug/trace settings.
79-17
Notes:
The -p help option displays a list of these parameters and an explanation for each. All paths must be fully qualified. You cannot use logical names.
Note:
You must enter the full path to the configuration template file as the last parameter, as shown above.
In the Windows Services control Panel, right click your new TLOG Miner service and select Properties. In the Properties screen, click the Recovery tab. Select the following computer response for each failure:
First failure: Restart the Service Second failure: Restart the Service Subsequent failures: Restart the Service
The system contains a Temporary Transient working folder All consumed tables are "articled" within at least one Replication/publication definition All consumed tables have a primary key Verify that the TLOG Miner components are running (see Environment Verification)
Update the metadata on the backend database for the table you are working with. In Microsoft SQL Server 2005, an inconsistency between the modified metadata and the data layout can appear because of the changes made to the metadata. To handle this inconsistency:
Where <table name> is the table with updated metadata, and <clustered index> is the name of its clustered index.
79-19
3.
Update the metadata in the Staging Area by doing one of the following:
If you made manual changes to the CDC solution after deployment, or if you do not want to redeploy the solution, then on the Router's (Staging Area) machine, do the following: Run Attunity Studio, and open the Design perspective. Edit the Metadata for the Router's Data source. Expand the table list and edit the metadata for the table. If you are adding a new column, make sure to add it to the end of the COLUMN list. This operation can also be done using the Source view. Make sure you select the correct datatype. If you are modifying a datatype, make sure to select the corresponding data type when making the modification. Save the metadata. For more information, see Working with Metadata in Attunity Studio.
For cases where you can redeploy the solution: Run Attunity Studio, and open the Solution perspective. Open the CDC solution project. Click Implement and then click Stream Service. Run the wizard. Redeploy the solution, but do not activate it. For more information, see Creating a CDC with the Solution Perspective.
4. 5.
Delete the physical files that represent the modified tables from the Staging Area. Make sure not to delete the SERVICE_CONTEXT and CONTROL_TABLE files. Reactivate the solution using Attunity Studio.
Environment Verification
The following topics show how to ensure that the SQL Server CDC solution components are configured properly. This section has the following topics.
Verify the MS SQL Server Version Ensure that the Service is Registered Verify that the LGR Service is Running Viewing the Service Greetings Check the Output Files
In the initial setup section of the LGR log file, find the backend version stamping as follows:
<<20070315-113327>> Module:sqlcdclgr/Line:697 MS-SQL version sampled: Microsoft SQL Server 2005 - 9.00.1399.06 (Intel X86) Oct 14 2005 00:33:37 Copyright (c) 1988-2005 Microsoft Corporation Developer Edition on Windows NT 5.2 (Build 3790: Service Pack 1)
In the Windows Event Viewer, do the following: Find the lgrdev source for any Information entry. Double-click the entry to display the following. Check to see if the message describes the SQL version. If not, try another entry.
The TLOG Miner service is registered The TLOG Miner service is assigned as a Windows event log source
To check that the TLOG Miner service is registered In the System Registry (REGEDIT), approve the service and its parameters. To access the registry:
Click Start, click Run, type regedit, and then click OK. Scroll thorough the registry tree by expanding the folders that lead to the root folder where you installed the Attunity Server. The path listed here assumes that you installed the Attunity Server in the default location: HKEY_LOCAL_MACHINE\SOFTWARE\Attunity\Attunity Server\Services. Be sure that the LGR service registration is listed on the right side. The following is an example of how the registry may look:
79-21
For checking if the TLOG Miner service is assigned as a Windows event log source, follow this procedure. To check that the LGR service is assigned as a Windows event log source In the System Registry (REGEDIT), browse to the CDClog folder. To access the registry:
Click Start, click Run, type regedit, and then click OK. Scroll thorough the registry tree by expanding these folders: SYSTEM\CurrentControlSet\Services\EventLog\Application\CDClog 5. Be sure that the LGR service registration is listed on the right side. The following is an example of how the registry may look:
Ping the Service Start the service for a period of time, and then stop it. To start the service:
From the Windows Start menu, select Control Panel, Administrative Tools and double-click the Services icon. Find the service is listed in the Name list and click Stop the service. To start the service click Restart the service. See the example below.
Figure 7911
Select System on the left side of the viewer. From the right pane, right click and event from the SQL Server CDC and select Properties. The following figure is a sample of the information that is displayed:
Service Greeting
Figure 7912
LGR Service log files: These files are in the folder or directory that is selected in the Logging parameter of the template input file. Transient storage output file: This file is in the folder or directory that is selected in the transientStorage parameter of the template input file.
For information on where to define these parameters, see Configuring the Template Input File.
79-23
80
Oracle CDC (on UNIX and Windows Platforms)
This section contains the following topics:
Overview Functionality Supported Versions and Platforms Configuration Properties Change Metadata Transaction Support Data Types Security Setting-up the Oracle REDO Log Testing the Database Logging Settings Changing the Operation Mode for Metadata Changes Setting up the Oracle CDC in Attunity Studio
Overview
Attunity Stream CDC solution for Oracle captures changes that are written to the Oracle REDO log by polling the log for changes. The CDC solution for Oracle supports online and archived REDO logs.
Functionality
The following describes the Oracle CDC agent functionality.
The Oracle CDC agent supports the basic functionality for all CDC agents. Basic CDC functionality does not support real-time metadata changes. However, the Oracle CDC solution can be configured to handle the following real-time metadata change operations: Adding a column to a captured Oracle table Changing columns to be nullable Dropping and renaming captured tables
When these operations are disregarded, the solution will continue to work, however the data for the tables affected by these operations may not be accurate. See Changing the Operation Mode for Metadata Changes for more information on how to activate this mode.
For UNIX, link your Oracle libraries by running the ora8_build and oracdc_ build scripts, from navroot/bin. The user account where these scripts are executed must have WRITE permission to navroot/lib.
Configuration Properties
The following parameters can be configured for the Oracle CDC agent:
useOnlineRedoLogsOnly: This property forces the agent to capture changes from the online REDO logs only. Archive REDO logs are ignored. dictinaryFilename: Enter the full path to the dictionary file you want to use in this property. If no dictionary file is indicated, the Oracle CDC agent uses the dictionary file used by the REDO logs. timeDelay: This property is used only if you are using Oracle Version 9.x with an RAC configuration. The timeDelay property determines the amount of time (in seconds) to wait from the time an operation occurs until it can be returned by the agent. For example, if you set 7 in this parameter, the agent will not return the event from the log miner for at least seven seconds from the time the change was made.
Note: This parameter cannot be less than the time delay indicated in the Oracle RAC configuration. For example, if you set 7 for the time delay, the time delay set in the Oracle configuration must be at no more than seven seconds. It is important to note that the Oracle configuration is in hundredths of a second, therefore a seven second delay in the Oracle RAC configuration is set to 700. For additional information, refer to the Oracle documentation.
maxRollbackedTransactionMinutesDuration: The maximum time (in minutes) a transaction can be open before issuing a rollback to guarantee that CDC solution continues to work. The default value is 60.
Change Metadata
Changes are captured and maintained in a change table. The table contains the original table columns and CDC header columns. The header columns are described in the following table:
Table 801
Header Columns Description The records current context. This column lists the operations available for the CDC agent. The available operations are:
INSERT DELETE UPDATE BEFOREIMAGE XINSERT XDELETE XUPDATE XBEFOREIMAGE COMMIT ROLLBACK
The X operations listed above refer to compensating records. The X operations do not have actual data. These operations are not written to the change tables, however they are used to filter the corresponding operation. transactionID tableName The operations transaction ID. The name of the table where the change was made. For INSERT, DELETE, UPDATE, and BEFOREIMAGE operations, the owner name and the table name are displayed. The same is true for the X operations. For COMMIT and ROLLBACK operations, this value is the same as the OPERATION value. timestamp rowID The date and time of the occurrence. The identification number for the rows in the change record.
Transaction Support
The Oracle agent supports transactions. It uses the Transaction ID to identify the transaction. This agent uses transaction demarcation. Compensating records are marked as X operations. See Change Metadata.
Data Types
The following data types are supported by the Oracle CDC agent:
Other data types are either set to NULL (if they are NULLABLE) or set to empty values. Multi-byte character sets are not supported.
Security
The Oracle account defined in the CDC solution must be granted with the following privileges:
SELECT ANY TABLE EXECUTE on DBMS_LOGMNR SELECT on V$LOGMNR_LOGS SELECT on V$LOGMNR_CONTENTS SELECT on V$ARCHIVED_LOG SELECT on V$LOG SELECT on V$LOGFILE SELECT on V$DATABASE SELECT on V$PARAMETER SELECT on DBA_REGISTRY
If any of these privileges cannot be granted to a V$xxx, then grant it to the V_$xxx instead). For Oracle 10G, the account should also be granted the following privilege:
When you edit this script information, table names, owner names, and column names should be in double quotes. For example ALTER TABLE "SYSTEM"."TEST" ADD . This is how Oracle enforces case senitivity. Without quotes all names are translated as upper case. Therefore, if lower-case naming is used, edit the script manually and add the double quotes. Make sure that the case used for table and columns names are corret.
The returned result should be YES or IMPLICIT. Use the command ALTER DATABASE ADD SUPPLEMENTAL LOG DATA to change the value of this property.
Add a temp feature called cdcIgnoreMetadataChanges, with a value of true to both the router and agent environments. Reactivate/reenable the router and agent workspaces.
In the Server Configuration section, click Data Source. The Data Source Configuration window is displayed.
3. 4.
Enter the Oracle Connect String for the Oracle database where you are consuming changes. Click Next. The Define Data Source window is displayed.
5. 6. 7.
Enter the Default table owner for the Oracle database where you are consuming changes. Enter a User name and Password if the data base where you are consuming changes requires it. Click Finish. The window closes. Continue with .
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
All changes recorded to the journal On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
Select Include capture of before-image records if you want to begin logging records before the image.
4.
5.
6.
Click Finish.
Troubleshooting
When deploying a solution, no new events may be received in the Staging Area. The following error message appears in the router log.
"[C044] Select() failed"
The reason for this is the execution time of the query sent to Oracle by the CDC agent takes too long. To prevent this from happening and to be able to receive new events, do the following:
1. 2.
Increase the value of the eventWait router property. Reactivate the CDC solution.
After getting new events, the eventWait parameter can be changed back to it's original value.
81
Query-Based CDC Agent
This section contains the following topics:
Overview Setting-up Query-based CDC Agent Changing a Query-based CDC Agent Definition
Overview
With query-based change data capture (CDC), the change data capture mechanism polls the database using a specified query and when a change is encountered that meets a set criteria, the relevant data is written to an event queue, where it can then be further processed. When the query-based CDC is all set, a separate binding is created containing the following:
A data source events adapter. This adapter polls the data source for updates and is defined with an interaction type of async-send. A copy of the data source to be polled.
In addition, a new workspace to manage the change data capture event queue is created. The data source is polled using the specified query and when a change is encountered that meets the criteria, the relevant data is written to the event queue. During the query-based CDC agent set-up, an SQL statement is formulated to return all modified records. For example, if timestamps are used as part of the database to mark the last change date to the record, you can formulate a statement similar to the following:
select * from table where last_change_timestamp > ?
Note:
If the SQL statement will not return all changes to the table, then the query-based CDC will fail.
2.
In the Design perspective Configuration view, expand the computer where the required data source is located.
Note:
You can add the data source in offline design mode, in a design machine and later drag-and-drop the adapter to this machine, as described in Using an Offline Design Machine to Create Attunity Definitions.
3. 4. 5. 6. 7. 8. 9.
Expand the Binding folder and then expand the binding configuration where you want to add the data source. Right-click Data sources and select New Data source. Enter a unique name to identify the new data source. Select the data source type from the Type list. Click Next. Enter the connect string required to access the data source. The connect string is data source dependent. Click Finish. changes.
10. Right-click the data source which includes tables for which you want to capture 11. Select Add Change Data capture, and then select By Query from the popup menu. 12. Specify a unique name for the change data capture and click Finish.
A popup message is displayed, informing you that changes have been made to the daemon configuration and prompts you to reload the daemon configuration. The change to the daemon is the addition of the new workspace to manage the data source event queue.
13. Click Yes.
The CDC mechanism is defined and the objects required to support the CDC mechanism are created.
14. Right-click the adapter under the change data capture binding and select Edit
You can now build a SELECT statement that checks for changes to a data source table. Build the query as follows:
1.
Selecting tables: Expand the required data source in the left pane.
2.
Select the required table and click the right-pointing arrow button to move the table to the right-hand pane, where the selected tables are listed.
Selecting columns: Select the Columns tab in the right-hand pane. Expand the data source and the tables containing the required column in the left pane. Select the required column and click the right-pointing arrow button to move the column to the right-hand pane.
3.
Adding conditions in a WHERE clause: Select the Where tab in the right-hand pane. Select and move the column you are setting the WHERE clause for to the right-hand pane. Set the operator and value conditions as needed.
18. Expand the required data source in the left pane. 19. Select the required table and click the > button.
The selected table now appears in the Tables tab in the right-hand pane.
20. Select the Columns tab in the right-hand pane. 21. Expand the data source table in the left pane. 22. Select the required column and click the > button. The selected column now
Note:
Other features available (such as sorting the results) are not relevant to building the query which checks for changes to the data.
Pass Through: Indicates whether the query is passed directly to the back-end database for processing or processed by the Query Processor. Reuse compiled query: Indicates whether the query is saved in a cache for reuse. Encoding: Sets one of the following as the encoding method used to return binary data in text format: base64: Sets base 64 encoding method. hex: Sets hexadecimal encoding method.
Event: Indicates the interaction mode is async-send. Fail on no Rows Returned: Indicates whether an error is returned if data is not returned. Root Element: The root element name for records returned by the query, using the format <root>\<record>. Record Element: The record element name for records returned by the query, using the format <root>\<record>. Max. records: The maximum number of records returned by the query. Null string: The string returned in place of a null value. If not specified, the column is skipped.
29. Select a field from the table from the Field list. The selected field will be used for
Note:
When the initial context is satisfied, it is incriminated. Thus, the next check of data source for an update is based on the updated context.
31. Define the initial value in the Initial Value field. 32. Click Finish.
A popup message is displayed, stating the interaction generation status and the number of records generated.
Figure 815 The Automatic Generation Results message
82
SQL/MP CDC on HP NonStop
This section contains the following topics:
Overview Functionality Supported Versions and Platforms Configuration Properties Change Metadata Transaction Support Data Types Security Defining the SQL/MP Agent Setting up the SQL/MP Agent in Attunity Studio
Overview
The Attunity Stream CDC solution for SQL/MP captures changes that are written to the SQL/MP databases guarded by the TMF (Transaction Management Facility).
Functionality
The SQL/MP agent supports the basic functionary for all AIS CDC agents.
Configuration Properties
The SQL/MP agent supports the standard Configuration Properties for the SQL/MP data source.
Change Metadata
Changes are captured and maintained as an event in the journal. The journal contains the original table columns and CDC header columns. The header columns are described in the following table.
Table 821 Header Columns Description The date and time of the occurrence. The name of the table where the change was made. This column lists the operations available for the CDC agent. The available operations are:
The name of the file where the changes were made. The operations transaction ID. The current context.
The following is an example of the data portion of the journal. It is an exact copy of the backend table layout:
<event name="tableA" timestamp="2004-03-18 11:57:04.748320"> <tableA> <header timestamp="2004-03-18 11:57:04.748784" tableName="tableA" operation="update" context="E8406789A0"> </header> <data name="Joe" dept_id="DP02"></data> </tableA> </event>
Transaction Support
The SQL/MP agent supports transactions.
Data Types
The SQL/MP agent is supports all SQL/MP Data Types.
Security
The SQL/MP agent has no specific security requirements.
To set up SQL/MP 1. Make sure that the TMF environment is configured and running for the table being followed by CDC.
2.
Open the SQLCI utility to set the following attributes for the tables:
Copy the script generated post deployment to the HP NonStop terminal prompt.
In the Server Configuration section, click Data Source. The following is displayed.
3.
Catalog Name: Enter the subvolume used as the default catalog for new tables.
4.
Click Finish.
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Master audit trail sequence number Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
4.
5.
6.
Click Finish.
To set up the stream service, follow the instructions in Creating a CDC with the Solution Perspective.
83
VSAM Under CICS CDC (on z/OS)
This section describes the VSAM under CICS CDC agent. It includes the following topics:
Overview Functionality Configuration Properties Change Metadata Transaction Support Security Data Types Managing the CICS User Journal
Overview
The Attunity Stream CDC solution for VSAM under CICS captures changes that are written to the CICS User Journal defined for all captured VSAM clusters. Before setting up the CDC agent, you must define the same CICS journal name for each VSAM cluster with changes to be captured, as described in this chapter. Creating a CDC solution for VSAM under CICS is performed using Attunity Studio.
Functionality
The VSAM CICS CDC agent supports the basic functionality for all CDC agents
Configuration Properties
This section describes the configuration properties for the VSAM CICS CDC agent. There are two types of properties:
CICS Application ID (targetSystemApplid): The VTAM ID of the CICS target system (mandatory).
VSAM Under CICS CDC (on z/OS) 83-1
Transaction ID (exciTransid): EXCI or another CICS transaction that activates DFHMIRS CICS program. VTAM NetName (vtamNetname): The VTAM network name of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system (mandatory). BATCHCLI is the default connection supplied by IBM when the installing CICS. If you use the IBM defaults, enter BATCHCLI as the VTAM_netname parameter. If not, define a specific connection (with the EXCI protocol) and use the netname you provided for this parameter. Note: Attunity provides a netname, ATYCLIEN, which can be installed by one of the following methods:
Configure and submit a JOB from the NAVROOT.USERLIB(CICSCONF) member to submit the DFHCSDUP batch utility program to add the resource definitions to the DFHCSD dataset (see the IBM CICS Resource Definition Guide for further details). Use the NAVROOT.USERLIB(CICSCONF) member as a guide to define the resources online using the CEDA facility.
After the new netname is defined in CICS, issue the following CICS command to install the new resource definitions under CICS: CEDA INST GROUP(<used CICS group>)
Program Name: (cicsProgname): The UPDTRNS program (supplied by Attunity), if the CDC data source is used to access VSAM under CICS. If the data source is not used, you may not have a UPDTRNS program, however, must enter a value in this property to continue.
Trace Queue (cicsTraceQueue): The name of queue for output which is defined under CICS when tracing the output of the UPDTRNS program. When not defined, the default CICS queue is used.
Logger Name: The name of the MVS logstream used as the CICS user journal for the data capture.
Change Metadata
The VSAM (CICS) drivers require Attunity metadata. You can import the metadata from COBOL copybooks. If COBOL copybooks that describe the VSAM records do not exist, manually define the metadata. For information creating a data source definition, see Managing Data Source Metadata. If COBOL copybooks describing the data source records are available, you can import the metadata by running the metadata import in the Attunity Studio Design perspective Metadata tab. For more information, see Importing Data Source Metadata with the Attunity Import Wizard and Setting Up the VSAM Data Source Metadata. If the metadata is provided in a number of COBOL copybooks, with different filter settings (such as whether the first 6 columns are ignored or not), you import the
metadata from copybooks with the same settings and later import the metadata from the other copybooks. Changes are captured and maintained in the CICS journal. The journal contains the original table columns and CDC header columns. The header columns are described in the following table:
Table 831 Header Columns Description The records current context. This column lists the operations available for the CDC agent. The available operations are:
The operations transaction ID. The terminal ID that originated the change. The task ID originating the change. The name of the table where the change was made. For INSERT, UPDATE, and BEFOREIMAGE operations, the owner name and then the table name are displayed. For COMMIT and ROLLBACK operations, this value is the same as the OPERATION value.
timestamp
The data portion is an exact copy of the back-end table layout. Each change in the journal is captured as an event with the following format:
<event name=table_name timestamp=...> <table_name> <header ...></header> <data ...></data> </table_name> </event>
Transaction Support
The VSAM CICS CDC agent supports transactions in their CICS boundaries.
Security
The VSAM CICS CDC agent connects to the MVS logstream with an authorization level of READ. All security authorizations need to be set as described in IBMs MVS Auth Assm Services Reference ENF-IXG manual.
To permit access to a logstream with a READ authorization level, set the READ access to RESOURCE(<logstream name>) in the SAF class CLASS(LOGSTRM).
Note:
Data Types
The VSAM CICS CDC agent supports all data types supported by the Attunity VSAM CICS data source. For more information see the VSAM Data Types.
Setting up the CICS User Journal for VSAM Print out the CICS User Journal Content
This displays the list of all the available CICS Journals, for example:
Jou(DFHJ77) Mvs Ena Str(CICSTS13.CICS.DFHJ77) Jou(DFHJ66) Mvs Ena Str(CICSTS13.CICS.DFHJ66) Jou(DFHLOG) Mvs Ena Str(CICSTS13.CICS.DFHLOG)
Each User Journal has the CICS name DFHJxx, where xx is the number of the journal. You can use any of them as the CDC Logger. Its logstream name (for example, CICSTS13.CICS.DFHJ77) should be provided as CDC Logger Name property. If you cannot use one of the available journals, go to steps 2 and 3. If you can use a journal in the list, go to step 4.
2.
Create an MVS logstream that can be used as a CICS journal. A sample job for the creation of DASD MVS logstream called ATTUNITY.CDC.VSAMBTCH is supplied in the <HLQ>.USERLIB(LOGCRVSM) member. For additional information, see IBMs MVS Setting Up a Sysplex manual. Define and install the log stream as a user journal by entering the following CICS command:
CEDA DEF JO(<journal name>) GR(<CICS group name>) TY(MVS) STR(<logstream name>) CEDA INST JO(journal name) GR((<CICS group name>)
3.
4.
For each VSAM cluster to be captured, use the CICS command CEDA DI FI, and edit the properties as shown in the following example:
+ JOurnal : <journal number> JNLRead : Updateonly JNLSYNCRead : Yes JNLUpdate : Yes JNLAdd : AFter JNLSYNCWrite : Yes
The value JNLRead means that before images are also written to the journal. The value JNLSYNCWrite means that CICS writes the changes to the journal immediately, instead of saving them in a buffer and writing them to the journal in blocks. Close the VSAM cluster by using the following CICS command:
CEMT S F(<CICS file name>) CLOSE
where:
DSNAME: This is the name of the journal logstream. FROM: This is the earliest change you want to print out. TO: This is the latest change you want to print out (TO=YOUNGEST prints all the entries up to the last change logged).
In the Server Configuration section, click Data Source. The Data Source Configuration window is displayed. The following figure shows the Data Source Configuration window.
3.
CICS Application ID: Enter the VTAM ID of the CICS target system (mandatory). Transaction ID Enter the EXCI or other CICS transaction that activates DFHMIRS CICS program. VTAM NetName Enter the VTAM network name of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system (mandatory). Program Name: Enter the UPDTRNS program (supplied by Attunity), if the CDC data source is used to access VSAM under CICS. If the data source is not used under CICS, you may not have a UPDTRNS program, however, must enter a value in this property to continue.
Trace Queue Enter the name of queue for output which is defined under CICS when tracing the output of the UPDTRNS program. When not defined, the default CICS queue is used.
4.
Click Finish. The window closes. Continue with the rest of the configuration.
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
All changes recorded to the journal On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
4.
5.
Logger name: Enter the name of the MVS logstream used for the data capture.
6.
Click Finish.
To set up the stream service, follow the instructions in Creating a CDC with the Solution Perspective.
VSAM Under CICS CDC (on z/OS) 83-7
84
VSAM Batch CDC (z/OS Platforms)
This section includes the following topics:
Overview Functionality Configuration Properties Change Metadata Transaction Support Data Types Security Platform Specific Information Configuring the Logger Setting up the VSAM Batch Agent in Attunity Studio
Overview
The Attunity Stream CDC solution for VSAM clusters updated by batch programs, captures changed VSAM records that are passed to JRNAD VSAM user exit, and saves them in an MVS logstream. The Attunity VSAM Batch CDC agent polls the logstream for the changes. The solution supports genuine VSAM clusters only. You create a CDC solution for VSAM Batch with Attunity Studio.
Functionality
The Attunity Stream CDC VSAM Batch solution automatically sets its own JRNAD user exit routine during the open process of a VSAM cluster (if another JRNAD exit has been already in use, the solution cannot work). A customer makes changes in the corresponding jobs to:
Provide the Attunity VSAM hook for automatic JRNAD definition Manage Logical Transactions (see Logical Transaction Manager)
The VSAM Batch CDC agent supports the basic functionality for all CDC agents.
Configuration Properties
This section describes the configuration properties for the VSAM Batch CDC agent. There are two types of properties:
Logger name: The name of the MVS logstream used for the data capture.
CDC$PARM Properties
CDC$PARM is the name of DD card that defines a QSAM data set or PDS member that contains the parameters for the JRNAD exit and Logical Transaction Management. For more information on the creation and syntax, see Configuring the Logger.
Table 841 Name CD$PARM Values Valid Values Default YES YES OFF * Comment Write before image to logstream Use blocking write Print debug info using WTO VSAM cluster that should be captured; An asterisk (*) indicates that all the VSAM clusters opened with Attunity JRNAD should be captured. Each DSNAME defines only one cluster. You may provide up to 50 clusters. ERROR IGNORE/ABEND ABEND When IGNORE is used, mostabnormal situations cause a warning message and the process terminates. Allows the use of the Logical Transaction Manager
YES/NO
YES
<Logstream name> ATTUNIT The name of the used MVS logstream Y.CDC.V SAMBTCH UPD/DEL/INS OFF/ON YES/NO All OFF YES Defines the type of operations that are written to the logstream. Ignore dummy records used for empty KSDS cluster access. Use synchronize logstream write.
Change Metadata
VSAM batch CDC events contain the original table columns and CDC header columns. The header columns are described in the following table:
Table 842
The date and time of the occurrence. The name of the table where the change was made.
This column lists the operations available for the CDC agent. The available operations are:
COMMIT ROLLBACK
Transaction Support
The VSAM Batch CDC Agent supports Transactions. There are two types of batch transaction management:
The logical transaction is started The logical transaction is terminated using both COMMIT and ROLLBACK The logical transaction is delayed (and should be continued later in another JOB) The logical transaction continued in another JOB
The logical transaction operation: BEGIN: Indicates a new logical transaction. If a logical transaction with the same name exists, the old transaction is terminated using ROLLBACK. COMMIT ROLLBACK: Terminates the logical transaction CONTINUE: The default. This should be used at the end of each JOB that does not terminate the current logical transaction, and at the beginning of each JOB that continues a logical transaction initiated by another JOB.
The logical transaction name: By default, the BEGIN operation initiates single job logical transaction with the same name as the JOB. If the logical transaction is continued to another JOB, or the transaction name is changed, the transaction name must be provided explicitly with the BEGIN operation. The same name should be provided with the CONTINUE operation at the beginning of the other JOB to continue the transaction. The transaction name can be up to 15 characters long.
Data Types
The VSAM Batch CDC agent supports all data types supported by the Attunity VSAM Batch data source. For more information see the VSAM Data Types.
Security
The VSAM Batch CDC adapter connects to the MVS logstream with an authorization level of READ. Batch applications updating VSAM files and the VSAM adapter (when updating VSAM files) connect to the logstream with an authorization level of WRITE,
if change data capture is active. The proper security authorizations should be set as described in the MVS Auth Assm Services Reference ENF-IXG IBM manual.
Notes:
To access a logstream using an application with a READ authorization level, set the READ access to RESOURCE(<logstream name>) in SAF class CLASS(LOGSTRM). To update a logstream using a program with a WRITE authorization level, set the ALTER access to RESOURCE(<logstream name>) in SAF class CLASS(LOGSTRM)
Creating the Logstream Creating the CDC$PARM Data Set Updating Jobs and Scripts
Delete all events Delete events to a specific timestamp Delete the newest events Print events between two timestamps Print all the events from the oldest to a specified timestamp Print all the events from the newest to a specified timestamp Print all the events
A sample job for managing the default VSAM Batch CDC MVS Logstream called ATTUNITY.CDC.VSAMBTCH is supplied in the <HLQ>.USERLIB(RUNLOGR) member.
The parameters and their valid values are described in CDC$PARM Properties. The minimal set of the parameters for any solution can be taken from Project Information section of Deployment Summary screen of Attunity Studio Solution Perspective. If the CDC$PARM data set is not provided to the JRNAD or Logical Transaction Manager, it is managed as follows:
DSNAME=* LOGSTREAM=ATTUNITY.CDC.VSAMBTCH
Updating Jobs for Activating CDC JRNAD Updating Jobs for Using the Logical Transaction Manager Update the REXX Scripts
Make sure that that the <HLQ>.LOADAUT load library is APF authorized.
Start a Logical Transaction: To begin a logical transaction, add the following step as the first step in a job:
//BEGINLT EXEC PGM=ATYLTRAN, // PARM='BEGIN,TRAN_NAME=<logical transaction name>' //STEPLIB DD DSN=<HLQ>.LOADAUT,DISP=SHR //CDC$PARM DD DSN=<CDC$PARM DS name>, DISP=SHR
Move a Logical Transaction to another job: To move a logical transaction to another job, add the following step as the last step of the job:
//MOVELT EXEC PGM=ATYLTRAN,COND=(4,LT) //STEPLIB DD DSN=<HLQ>.LOADAUT,DISP=SHR //CDC$PARM DD DSN=<CDC$PARM DS name>, DISP=SHR
Continue Logical Transaction: To continue a logical transaction in another job, add the following step as the first step of this job:
//CONTLT EXEC PGM=ATYLTRAN, // PARM='TRAN_NAME='<logical transaction name>' //STEPLIB DD DSN=<HLQ>.LOADAUT,DISP=SHR //CDC$PARM DD DSN=<CDC$PARM DS name>, DISP=SHR
Terminate Logical Transaction: To terminate a logical transaction, add the following two steps as the last steps of this job:
//COMMITLT EXEC PGM=ATYLTRAN,COND=(4,LT), // PARM='COMMIT' //STEPLIB DD DSN=<HLQ>.LOADAUT,DISP=SHR //CDC$PARM DD DSN=<CDC$PARM DS name>, DISP=SHR //RLBCKLT EXEC PGM=ATYLTRAN,COND=(EVEN,(0,EQ,COMMIT)) // PARM='ROLLBACK' //STEPLIB DD DSN=<HLQ>.LOADAUT,DISP=SHR //CDC$PARM DD DSN=<CDC$PARM DS name>, DISP=SHR
The COND clause in the COMMITLT step should provide the condition when the Logical Transaction terminates successfully by COMMIT. The COND clause in the RLBCKTL step always writes a ROLLBACK to the logstream when COMMITLT is not executed or fails.
In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed. In the first screen select one of the following to determine the Change Capture starting point:
On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes Changes recorded in the journal after a specific date and time. When you select this option, click Set time, and select the time and date from the dialog box that is displayed.
4.
5.
Logger name: Enter the name of the MVS logstream used for the data capture.
6.
Click Finish.
To set up the stream service, follow the instructions in Creating a CDC with the Solution Perspective.
Part XIII
Interface Reference
This part contains the following topics:
C and COBOL 3GL Client Interfaces JCA Client Interface JDBC Client Interface ODBC Client Interface OLE DB (ADO) Client Interface XML Client Interface
85
C and COBOL 3GL Client Interfaces
This section contains the following topics:
Overview of the C and COBOL 3GL APIs to Applications APIs and Functions Using APIs to Invoke Application Adapters - Examples CICS as a Client Invoking an Application Adapter (z/OS Only) CICS Connection Pooling under CICS IMS/TM as a Client Invoking an Application Adapter (z/OS Only)
C Programs (see Using the API with C Programs) COBOL Programs (see Using the API with COBOL Programs)
The gap.h header: The GAP API declarations. The GAP_LOAD function: This function loads the API functions.
The function does not have any parameters. A non-zero value is returned for success and 0 for failure
C and COBOL 3GL Client Interfaces 85-1
When called, the function searches for the AIS shared library and loads it. The current path and NAVROOT environment variable are used in the function. On Windows, the NVBASE environment variable is the first to be searched. On OpenVMS, the NVBASESHR logical name is the first to be searched. This function must be exposed.
Supported Interfaces
z/OS Platforms To use the APIs under CICS, link the program with the stub NAVROOT.FIXLIB(ACX3GL).
Connection APIs Transaction APIs Execution APIs Get Adapter Schema Function Get Event Function Ping Function Get Error Function
The syntax uses C terminology, followed by the equivalent COBOL function name.
Connection APIs
The following functions handle the connection and connection context for a request:
The Connect Function The Clean Connection Function The Disconnect Function The Retry Connection Function
Transient connections are created for use within a single request. A transient connection is disconnected when a request ends, or when the connection context changes (that is, with the connect, setConnection, or disconnect functions). Persistent connections can persist across multiple requests or connection context changes. Persistent connections are disconnected upon an explicit disconnect function or when a connection idle timeout expires.
ACXAPI_CONNECT( char* char* char* char* char* int long ACXAPI_CONNECT_MODE char* char* char* void Example 852
ServersUrls, Username, Password, Workspace, AdapterName, Persistent, IdleTimeout, ConnectMode, DefinitionFileName, KeyName, KeyValue, **ConnectHandle)
nvBOOL ACXACNCT( STRING_256 sServersUrls, /* IP1:port[,IP2:port] [,...] */ STRING_64 sUsername, STRING_64 sPassword, STRING_64 sWorkspace, STRING_64 sAdapterName, nvINT4 *pbPersistent, nvINT4 *piIdleTimeout, nvINT4 *piConnectMode, STRING_256 sSchemaFileName, STRING_64 sEncKeyName, STRING_256 sEncKeyValue, nvINT4 *phConnectHandle) Example 853 Connect Function called from COBOL
03 03 03 03 03
CP-CONNECT-MODE pic s9(8) value is 0. CP-SCHEMA-FILE pic x(256) value is "tcobxml". CP-ENC-KEY-NAME pic x(64) value is low-value. CP-ENC-KEY-VALUE pic x(256) value is low-value. CP-CON-ID pic s9(8) comp.
Table 851 (Cont.) Connect Function Parameters Parameter C: DefinitionFileNa me (string_256) COBOL: SCHEMA-FILE-NAME pic x(256) C: KeyName (string_ 64) COBOL: ENC-KEY-NAME pic x(64) C: KeyValue (string_ 256) COBOL: ENC-KEY-VALUE pic x (256) C: **ConnectHandle Output A pointer to the connection. A pointer is always returned when the connection fails. This enables calling the getError (nvINT4) function to determine what caused the error. COBOL: *CON-ID pic The Disconnect function must always be called to clear the s9 (8) connection handle.
1
Usage Input
Description The name and path of the local adapter definition file used for calling the adapter. This parameter must be provided for remote adapters.
Input
Input
This parameter represents a common behavior within application servers limiting the amount of time a resource can be tied up by a client.
The definition produced using this command matches the server environment and may need editing to be appropriate for the client API. Usually the editing that is necessary is related to datatypes. For example, a database adapter may have an interaction input record with a field called QUANTITY of type Double, but the interaction is invoked from a COBOL program with a buffer where the QUANITY field is a PIC S9(11)V9(2) COMP-3 (a packed decimal). In this case, change the QUANTITY field native type in the adapter definition from DOUBLE to DECIMAL(13,2).
Note:
@hen the API is used when the Server is accessed through CICS (z/OS or OS390) there is a problem indicating the adapter definition file because CICS does not support dynamically opening files. You can provide the adapter definition file by creating an ESDS VSAM file and filling it with the contents of the adapter definition, then add this file to CICS using its CICS name as the value for the definitionFileName parameter.
Syntax
ACXAPI_CLEAN_CONNECTION( void* ConnectHandle int forgetAuthentification)
Syntax
ACXAPI_DISCONNECT( void* ConnectHandle)
The RetryConnection function is used to retry the Connect function when there has been a timeout to all the servers listed in the Connect function. The user can set the RetryConnection function to call a user function that returns TRUE in order to repeat the connection attempt or FALSE to end the process. This enables the user to decide in real-time whether or not to reattempt the connection.
Syntax
ACXAPI_SET_RETRYABLE_CONNECTION_HANDLER( void* ConnectHandle void* Retry)
Transaction APIs
Transaction APIs are used in the following scenarios:
Non-transacted operation: The adapter works in auto-commit mode. Work is committed immediately and automatically upon execution. This operation mode is the default operation mode when no transaction APIs are used, or when the setAutoCommit function is set to True. Local transaction operation: When auto-commit is set to False, the first interaction starts a transaction that lasts until an explicit commit (using the transactionCommit function) or an explicit rollback (using the transactionRollback function) occurs. All interactions performed in between are part of that transaction. Note that local is used here to indicate the scope of the transaction, rather than its location: Using ACX, the local transaction may be running on a remote machine.
Syntax
ACXAPI_SET_AUTO_COMMIT( void* ConnectHandle int AutoCommit)
Syntax
ACXAPI_TRANSACTION_COMMIT void* ConnectHandle ACX_XID *Xid)
Table 856 (Cont.) Transaction Commit Function Parameters Parameter C *Xid Usage Input Description A global transaction identifier, automatically assigned. If not given (or empty), the transaction is assumed to be local. The Xid comprises the following:
formatID: Specifies the format of the Xid. globalTransactionID: Defines the transaction ID. The value must be less than 128. branchQualifier: Defines the transaction branch. The value must be less than 128.
Syntax
ACXAPI_TRANSACTION_ROLLBACK( void* ConnectHandle ACX_XID *Xid)
Transaction Rollback Function Parameters Usage Input Description A pointer to the connection.
formatID: Specifies the format of the Xid. globalTransactionID: Defines the transaction ID. The value must be less than 128. branchQualifier: Defines the transaction branch. The value must be less than 128.
Execution APIs
ACX defines the following execution functions:
Execute Function
The Execute function executes a given interaction against the application.
Syntax
ACXAPI_EXECUTE( void* ConnectHandle char* InterationName void* BufferIn void* BufferOut nvINT4 BufferOutLen)
Table 858 (Cont.) Execute Function Parameters Parameter C BufferOutLen COBOL *iOutputSize (nvINT4) Usage Output Description The length of the output record.
Syntax
ACXAPI_EXECUTE_BATCH( void* ConnectHandle char* Operation void* BufferOut nvINT4 BufferOutLen)
START: Start batching ACXAPI_EXECUTE operations. EXECUTE: Execute all the batched operations. RESET: Clear the input buffer of all interaction information.
BufferOut BufferOutLen
Output Output
Syntax
ACXAPI_SET_ENVIRONMENT( char* Environment nvINT4 Flags)
85-11
Syntax
ACXAPI_GET_ADAPTER_SCHEMA( void* ConnectHandle void** *Definition)
Syntax
ACXAPI_GET_EVENT( void* ConnectHandle char* EventName long iWait int Keep long *iMaxEvents, void* BufferOut 85-12 AIS User Guide and Reference
85-13
(Cont.) Get Event Function Parameters Usage Output Description The name of the returned event.
C OutputEventName COBOL sOutputEventName (STRING_64) C EventTimestamp COBOL sEventTimestamp (STRING_64) C iEventsAvailable COBOL *piEventsAvailab le (nvINT4)
Input
Input
Ping Function
The Ping function returns, in a pingResponse response, information about an active adapter.
Syntax
ACXAPI_PING( void* ConnectHandle struct _ACX_PING_RESPONSEvoid** OutputStructpPingResponse)
(Cont.) Ping Function Parameters Usage Input Description The adapter name.
C *pszName COBOL sName (STRING_64) C *pszDescription COBOL sDescription (STRING_256) C *pszVersion COBOL sVersion (STRING_64) C *pszType COBOL sType (STRING_64) C *pszOperatingSys tem COBOL sOperatingSystem (STRING_64) C *pszVendor COBOL sVendor (STRING_64) C *pszAuxiliaryInf o COBOL sAuxiliaryInfo (STRING_256) C *pszGenre
Input
Input
Input
Input
Input
Input
Input
Syntax
ACXAPI_GET_ERROR( void* ConnectHandle char* *Error long *Status)
85-15
C Program Example
#include <stdio.h> #include <stdlib.h> #include <string.h> #include "gap.h" GAP_HELP_DEFINE; #include "scm.h" struct _SYS_ placeIn = {0, "Julian W", {"Julian White", "Oxford St.", "London", "12345", "UK", "ENGLAND",3 { {1, "Red book", 1, 31.2}, {2, "Green book", 1, 31.2}, {3, "Tarzan book", 3, 5.2}, } };
/* Returns the real length of the string in a buffer the buffer is padded with spaces. */ int bufStrLen(char* Buffer, int Len) { int i; for (i=Len; i>1; i--) { if (Buffer[i-1] != ) { return i; }
} return 0; } void display(struct _SYS_* ) { int i; printf(" details:\n"); printf(" ID = %i\n", ->i_ID); printf(" By = %.*s\n", bufStrLen(->sED_BY, 64), ->sED_BY); printf(" Address: %.*s\n", bufStrLen(->ADDRESS.sADDRESSEE, 64), ->ADDRESS.sADDRESSEE); printf(" Street: %.*s\n", bufStrLen(->ADDRESS.sSTREET, 64), ->ADDRESS.sSTREET); printf(" City: %.*s\n", bufStrLen(->ADDRESS.sCITY, 64), ->ADDRESS.sCITY); printf(" ZIP: %.*s\n", bufStrLen(->ADDRESS.sZIP, 5), ->ADDRESS.sZIP); printf(" State: %.*s\n", bufStrLen(->ADDRESS.sSTATE, 2), ->ADDRESS.sSTATE); printf(" Country: %.*s\n\n", bufStrLen(->ADDRESS.sCOUNTRY, 64), ->ADDRESS.sCOUNTRY); printf(" Lines %i:\n", ->iN_LINES);
for(i=0; i<->iN_LINES; i++) { printf(" %i. Item Name = %.*s, Quantity = %i, Price = %f\n", ->LINES[i].iLINE_NO, bufStrLen(->LINES[i].sITEM_NAME, 64), ->LINES[i].sITEM_NAME, ->LINES[i].iQUANTITY, ->LINES[i].dITEM_PRICE); } } void report_error(void *pCh, char *pError) { char *pAcxError; ACXAPI_GET_ERROR(pCh, &pAcxError, NULL); printf("%s, %s\n", pError, pAcxError); } long main(int argc, char** argv) { int ret_code = 0; int i = 0; void *pCH; char hostname[128]; struct _SYS_ ; struct _SYS_FIND_ struct _SYS_PLACE__RESPONSE find; placeOut;
85-17
else strcpy(hostname, "localhost:2551"); if (!GAP_LOAD()) { printf("Failed to load the ACX API\n"); exit(1); } printf("\nConnecting to %s...\n\n", hostname); if (!ACXAPI_CONNECT(hostname, "", "", "", "s", TRUE, 0, 0x01, NULL, NULL, NULL, &pCH)) { printf("Failed to connect\n"); return 1; } printf("Place an with %i items.\n\n", placeIn.iN_LINES); if (!ACXAPI_EXECUTE(pCH, "place", &placeIn, &placeOut, sizeof(placeOut))) { report_error(pCH, "ACXAPI_EXECUTE failed"); return 1; } printf(" was accepted, printf("Retrieve an, ID = %i was returned.\n\n", placeOut.i_ID);
ID = %i.\n\n", placeOut.i_ID);
find.i_ID = placeOut.i_ID; if (!ACXAPI_EXECUTE(pCH, "find", &find, &, sizeof())) { report_error(pCH, "ACXAPI_EXECUTE failed"); return 1; } display(&); printf("\nDisconnect...\n"); ACXAPI_DISCONNECT(pCH); pCH = NULL; return 0; }
pic pic pic pic pic pic pic pic pic pic pic pic
x(256) x(64) x(64) x(64) x(64) s9(8) s9(8) s9(8) x(256) x(64) x(256) s9(8)
value is "localhost:2551". value is low-value. value is low-value. value is low-value. value is "orders". COMP value is 0. COMP value is 0. COMP value is 0. value is "". value is low-value. value is low-value. COMP.
01 GETERR-PARM. 03 GE-STATUS-CODE pic s9(8) comp. 03 GE-ERROR-TEXT pic x(256). 01 EXEC-PARM. 03 EP-INTERACTION-MODE pic s9(8) comp value is 0. 03 EP-INTERACTION-NAME pic x(64). 03 EP-OUT-LENGTH pic s9(8) comp. 77 RET-CODE pic s9(8) comp. procedure division. acx3gl-main section. main-start. display "Initializing ACX3GL API". call "ACXAINIT". display "Connecting to the Orders system". call "ACXACNCT" using CP-SERVERS-URL CP-USERNAME CP-PASSWORD C and COBOL 3GL Client Interfaces 85-19
CP-WORKSPACE CP-ADAPTER CP-PERSISTENT CP-IDLE-TIMEOUT CP-CONNECT-MODE CP-SCHEMA-FILE CP-ENC-KEY-NAME CP-ENC-KEY-VALUE CP-CON-ID returning RET-CODE. if RET-CODE = 0 perform report-error thru report-error-x. display "Placing an order...". perform fill-order thru fill-order-x. move "placeOrder" to EP-INTERACTION-NAME. Some COBOLs have a LENGTH function... compute AA-ORDER-CONFIRM-LEN = 4. call "ACXAEXEC" using CP-CON-ID EP-INTERACTION-MODE EP-INTERACTION-NAME AA-ORDER AA-ORDER-CONFIRM AA-ORDER-CONFIRM-LEN returning RET-CODE. if RET-CODE = 0 perform report-error thru report-error-x. display "New order ID is " AA-NEW-ORDER-ID with conversion. display "Disconnecting...". call "ACXADSCO" using CP-CON-ID. stop run. main-end. exit program. report-error. call "ACXAGTER" using CP-CON-ID GE-STATUS-CODE GE-ERROR-TEXT. display "Error: " GE-ERROR-TEXT. stop run. report-error-x. exit. fill-order. move 0 to AA-ORDER-ID. move "Julian W" to AA-ORDERED-BY. move "Julian White" to AA-ADDRESSEE. move "Oxford St." to AA-STREET. move "London" to AA-CITY. move "12345" to AA-ZIP. move "UK" to AA-STATE. move "ENGLAND" to AA-COUNTRY. move move move move 1 to AA-LINE-NO(1). "Red Book" to AA-ITEM-NAME(1). 12 to AA-QUANTITY(1). 19.90 to AA-ITEM-PRICE(1).
*-
Configuring the IBM z/OS Machine Using a CICS Transaction to Invoke an Application Adapter Calling the Transaction
Copy NAVROOT.LOAD(TRANS3GL) to a CICS DFHRPL library. Verify that the CICS Socket Interface is enabled by issuing the following CICS command: EZAO START CICS If you are not sure if the system is configured with the Socket Interface, try running the EZAC transaction. If the transaction produces a screen, you should be able to run the EZAO startup transaction. If not, check if the transaction has been defined in a group that has not been installed, for example: CEDC V TRANS(EZAC) G(*). If it is defined in a group, install that group and try running EZAO again. If not successful, you need to configure CICS as outlined in the TCP/IP V3R2 For MVS: CICS Sockets Interface Guide.
3.
Set up the CICS resource definitions for the C or COBOL program. The following JCL can be used as a template and modified according to the guidelines below:
//ATTCSD JOB Attunity,CSD,MSGLEVEL=1,NOTIFY=&SYSUID //STEP1 EXEC PGM=DFHCSDUP,REGION=512K, // PARM=CSD(READWRITE),PAGESIZE(60),NOCOMPAT //STEPLIB DD DSN=<HLQ1>.SDFHLOAD,DISP=SHR //DFHCSD DD UNIT=SYSDA,DISP=SHR,DSN=<HLQ2>.CSD
85-21
//OUTDD DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD * */******************************************************/ */* Attunity CICS Definitions */ */******************************************************/ *-------------------------------------------------------* * Note: Install GROUP(att) - CEDA IN G(att)* *If you are rerunning this, uncomment the DELETE command. * *-------------------------------------------------------* * * Start attunity RESOURCES: * * DELETE GROUP(att) DEFINE PROGRAM(ATTCICSD) GROUP(att) LANGUAGE(C) DATALOCATION(ANY) DE(attunity DLL) DEFINE PROGRAM(TRANS3GL) GROUP(att) LANGUAGE(C) DATALOCATION(ANY) DE(attunity DLL) DEFINE PROGRAM(<PROG>) GROUP(att) LANGUAGE(<LANG>) DATALOCATION(ANY) DE(attunity) DEFINE TRANSACTION(<attTRAN>) GROUP(att) PROGRAM(<PROG>) TASKDATAL(ANY) DE(attunity TRAN ID) LIST GROUP(att) * * End attunity RESOURCES * /* // 4.
Change the JOB card to suit the site. Change <HLQ1> to point to the CICS SDFHLOAD library. Change <HLQ2> to point to the CICS CSD dataset. Change <LANG> to the Language: C or COBOL. Change <PROG> to the COBOL program name. If you are calling the C or COBOL program from a CICS transaction, change <attTRAN> to the CICS transaction name that calls the COBOL program.
5.
Install the ORA group, from CICS, by issuing the following command: CEDA IN G(att)
Data Buffer Parameters Size 4 256 Description The version of the APIs used. The expected value is 4. The URL of the z/OS machine and the port number where the daemon runs. For example, IP1:2551, where IP1 is the URL and 2551 is the port. A valid username to access the z/OS machine. A valid password for the user name. A daemon workspace. The default is Navigator. The name of the adapter. For future use. Leave blank. For future use. Leave blank. For future use. Leave blank. The name of the interaction in the application definition. The following flags are available:
1. 2. 3. 4. 5. 6.
64 64 64 64 256 64 256 64 4
A trace of the XML is performed. A trace of the communication calls is performed. Both the XML and communication calls are traced. The NAT firewall protocol is used, with a fixed address for the daemon. A trace of the XML is performed and the NAT firewall protocol is used, with a fixed address for the daemon. A trace of the communication calls is performed and the NAT firewall protocol is used, with a fixed address for the daemon. Both the XML and communication calls are traced and the NAT firewall protocol is used, with a fixed address for the daemon.
7.
For information on the NAT firewall protocol, see Firewall Support. Input format 4 The following formats are available: 0: Input is provided as XML. 1: Input is provided using parameters.
85-23
(Cont.) Data Buffer Parameters Size Description The size of the input depends on the value specified in the Input size parameter. If the Input format is set to 0 (XML), the input is formatted as follows:
The first four bytes specify the size of the input XML string. The next 64 bytes specifies the name of the record used for the output (the inbound interaction). The next bytes (to the exact length specified in the first four bytes) specify the input XML string. For example: <findorder ORDER_NO=17 /> where findorder is the inbound interaction name.
If the Input format is set to 1 (the input is done using parameters), the input is formatted as follows:
The first four bytes specify the number of parameters. The next 4 bytes specify the maximum size of any parameter value. The next 64 bytes specify the name of the record used for the output (the inbound interaction). The next 32 bytes specify the name of the parameter. The next bytes (to the exact length specified in the first four bytes) specify the input parameter. The following bytes repeat the last two entries until all the parameters are specified.
01
INCOM-EXEC-INPUT. 15 INCOM-XML-BUFF. 20 INCOM-XML-ILEN PIC S9(8) COMP SYNC. 20 INCOM-XML-INTER-OUTREC-NAME PIC X(64). *====>>> CHANGE ??? TO LEN SPECIFIED IN INCOM-XML-ILEN 20 INCOM-XML-INPUT PIC X(???). 15 INCOM-PARAM-BUFF REDEFINES INCOM-XML-BUFF. 20 INCOM-PARAM-COUNT PIC S9(8) COMP SYNC. 20 INCOM-PARAM-VALUE-LEN PIC S9(8) COMP SYNC. 20 INCOM-PARAM-INT-OUTREC-NAME PIC X(64). *====>>> CHANGE ?? TO COUNT SPECIFIED IN INCOM-PARAM-COUNT 20 INCOM-PARAM-NAME-VALUE OCCURS ?? TIMES. 25 INCOM-PARAM-NAME PIC X(32). *====>>> CHANGE ?? TO LEN SPECIFIED IN INCOM-PARAM-VALUE-LEN 25 INCOM-PARAM-VALUE PIC X(??). 01 COMM-DATA-BUFF-OUTPUT REDEFINES COMM-DATA-BUFF. 05 05 05 COMM-OUT-STATUS COMM-OUT-LENGTH COMM-OUT-DATA PIC S9(8) COMP SYNC. PIC S9(8) COMP SYNC. PIC X(4992)
10
where: commDataBuff: The buffer with the interaction details, used in the COMMAREA. iCommSize: The size of the buffer. This value is also used to determine the size of the output string. Thus make sure the value is big enough for the expected output. After defining the COMMAREA and calling the TRAN3GL transaction in the COBOL program, compile and move the COBOL program to a CICS DFHRPL (LOAD) library.
Transaction Output
The output includes a 4-byte success flag: Zero for success, otherwise failure. The output overrides the input. If the result is failure, an error message with a length of 256 bytes is returned. If XML was specified for the input and the result is success, the output is formatted as XML, as follows:
The first four bytes specify the size of the output. The following bytes make up the XML output.
If parameters were specified for the input and the result is success, the output is formatted as follows:
The first four bytes specify the size of the output. The next 32 bytes specify the name of the output attribute.
85-25
The next bytes (to the exact length specified for the input string in the) specify the output value. The following bytes repeat the last two entries until all the output is specified.
Using Connection Pooling under CICS CICS Connection Pool Flow ATTCALL Program Interface ATTCNTRL Program Setting up 3GL under CICS
ATTHRDPL: This program is the thread program used for providing a persistent connection to an adapter. ATTCALL: This is a dispatcher program that: Provides a control activity for connection pools and the threads in the pools with a 3GL control protocol Provides 3GL operations being moved to 3GL with a Pool 3GL protocol.
ATTCNTRL: This program supports most of the ATTCALL Control Protocol operations as a standalone CICS transaction.
The following is the flow as shown in the above figure. It describes each operation in in the flow. In this flow, the user enters the request into the COMMAREA and then activates the ATTCALL Program Interface using the EXEC CICS LINK. The ATTCALL program uses the ATTHRDPL program, which is defined as a CICS transaction, to move 3GL requests to Attunity 3GL operations. The flow has two parts:
PURGELOG operation: Restarts the logging in the ATYCPLOG file. This can be executed at any time in the in the flow. INITPOOL: The first operation is the initialization operation (INITPOOL). This allocates the pool memory from CICS for each thread and activates the corresponding thread transaction (defined in the COMMAREA). Each thread (ATTHRDPL program) tries to connect to the corresponding adapter using the provided connect string. If the connection cannot be established, each subsequent request initiates a reconnection. TERMPOOL: In this operation, the ATTCALL program checks that there are no active requests on any thread and terminates the request after a delay. The delay is defined as an INITPOOL operation parameter. When there are no more active
85-27
requests in any thread, the transactions are terminated, and the pool memory is freed.
RELOAD: Each 3GL request locks a thread to execute the operation. In some cases the thread is not unlocked after the operation is completed, usually because of an abnormal termination of a user program. The RELOAD operation is used to return the tread to active service. In the RELOAD operation, ATTCALL sends a signal to a thread and the thread activates anther thread and then terminates itself.
BEGINT: In this operation, ATTCALL searches for an inactive tread, locks it, and posts the corresponding thread. This tread executes the Begin Transaction 3GL operation and ATTCALL returns the locked thread ID to the user program. EXECT: In this operation, ATTCALL posts the thread that was locked in the BEGINT operation. The thread executes the requested 3GL interaction and moves the 3GL output data to the user program. ATTCALL returns the 3GL operations return code to the user program. ENDT: In this operation, ATTCALL posts the tread that was locked in the BEGINT operation. The tread executes the End Transaction 3GL operation and ATTCALL unlocks the thread. EXECI: This is a stand-alone operation. In this operation, ATTCALL searches for an inactive thread, locks it, and posts the corresponding thread. The thread executes the requested 3GL interaction and moves the 3GL output data to the user program. ATTCALL returns the 3GL operations return code to the user program and unlocks the thread.
COMMAREA
A user program and ATTCNTRL provide a commarea for the ATTCALL program. The following program is loaded into the commarea.
typedef struct ATTREQ { char operation[8]; /* POOL operation*/ char pool_name[8]; int operation_RC;/* POOL return code */ unsigned int trace_level;/* 0/1 */ union { struct { char txn_name[4];/* transaction name of ATTHRDPL */ unsigned int n_threads;/* parallel connections */ unsigned int delay_time;/* wait when all threads are busy */ unsigned int attempt_num;/* retries after the wait */ ATT_CONNECT *ais_connect;/* AIS connect info */ } initpool; struct { unsigned int thread_number; /* the thread to be reload */
} reload; struct { unsigned int thread_handle; /* for BEGINT/EXECT/ENDT */ char *error_message_buffer;/* ATT 3GL error message */ unsigned int max_error_message_size; /* 0 - no message is returned */ int interaction_RC;/* ATT 3GL return code*/ union {/* thread operations data */ struct { char interaction[64];/* 3GL interaction */ void *input;/* 3GL EXECUTE input */ unsigned int output_length;/* 3GL EXECUTE output length */ void *output;/* 3GL EXECUTE output */ } exec; struct { int commit; /* 1 - commit, 0 - rollback */ } endt; } data; } inter; } op; } ATTREQ;
Control Protocol
This section describes the ATTCALL Control parameters. The operations in the Control Protocol are:
INITPOOL initiates a pool. It allocates pool and thread memory, and activates thread transactions (that use the ATTHRDPL program) TERMPOOL terminates threads and returns the pool memory STATUS prints a list of pools or a pool status to a temporary storage queue called ATTHRDPL RELOAD interrupts a thread and reloads it TRACELVL changes the pool trace level PURGELOG purges the ATYCPLOG file
The following tables describe the parameters for the Control operations. All of the operations share some common parameters. Some operations have additional parameters. These are also shown in the tables below. The following table describes the Control protocol common parameters:
85-29
Control Protocol Common Parameters Description The name of the operation. The name of the connection pool. The ATTCALL trace level. The thread trace level can be changed using the TRACEVL operation. The return code. The valid values are: General:
0: OK (The operation is completed, the request has been moved to a thread) 08: Invalid operation name 16: Invalid number of threads 20: Error during start thread task 04: Pool is busy 12: Pool not found 16: EXECT/ENDT was not invoked by the task that had invoked BEGINT 20: ABEND in thread
INITPOOL operations:
Other operations:
The following table describes the additional parameter for the RELOAD operation:
Table 8518 Parameter thread_number (input) RELOAD Parameter Description The number of threads to be reloaded (starting from 0).
3GL Protocol
This section describes the ATTCALL 3GL operation parameters. The operations in the 3GL protocol are:
BEGINT: Locks a thread and starts a transaction in the thread. ENDT: Commits or rolls back the transaction in the thread and frees the thread so that it can receive a new transaction.
The following tables describe the parameters for the 3GL operations. All of the operations share some common parameters. Some operations have additional parameters. These are also shown in the tables below. The following table describes the 3GL Protocol common parameters:
Table 8519 Parameter error_message_buffer (input) interaction_RC (output) thread_handle parameter (output) 3GL Protocol Common Parameters Description A buffer address that is used to return the 3GL error message max_error_message_size, which is the size of error message buffer. 3GL return code An output for BEGINT and an input parameter for EXECT and ENDT operations.
The following table describes additional parameters in the EXECT and EXECI operations:
Table 8520 Parameter interaction (input) input (input) output (input) output_buffer (input) EXECT and EXECI Parameters Description A buffer containing the name of the 3GL interaction. An input record address An output record address The size of output buffer
The following table describes the additional parameter for the ENDT operation:
Table 8521 Parameter commit (input) ENDT Parameter Description A commit/rollback switch. The values are commit (1) and rollback (0).
ATTCNTRL Program
The ATTCNTRL program receives its input from the CICS window. The input is provided in the following format: tran name [PLOG] operation (poolname) operation parameters The entry of the key words is not case sensitive. You can enter the parameters first three letters or its full name. See ATTCNTRL Parameters for a description of the parameters for this program. You can carry out the PLOG (purge log) operation before the other operations. Only one operation can be executed for each program activation. The ATTCNTRL program has the following operations:
PINIT: The initiation (init) pool TPLVL: Changes the trace level in the pool threads RELOAD: Reloads a pool thread
85-31
STATUS: Prints the pool status or a list of pools (if no pool name is provided). PTERM: Terminates a pool
ATTCNTRL Parameters
This section describes the parameters for each operation in the ATTCNTRL program.
PINIT Parameters TPLVL Parameters RELOAD Parameters STATUS Parameters PTERM Parameters
PINIT Parameters Description
Connection Pool Parameters TRACELVL THREADS DELAY RETRYNUM CTARN 3GL Parameters SERVER ADAPTER USER PASSWORD WORKSPACE The URL for the server where the connection pool resides. The name of the CICS adapter being used. The User Name. The Users password. The name of the workspace where the adapter resides. The trace level for the pool threads. Enter 0 or 1. The number of threads that are initiated. The delay time. The number of attempts allowed to retry the connection before getting a BUSY return code. The ATTTHRDPL CICS connection time.
TPLVL Parameters Description The trace level for the pool threads. Enter 0 or 1.
RELOAD Parameters Description The trace level for the pool threads. Enter 0 or 1. The number of threads to be reloaded. If reloading the first thread only, enter 0.
STATUS Parameters Description The trace level for the pool threads. Enter 0 or 1.
PTERM Parameters Description The trace level for the pool threads. Enter 0 or 1.
Make sure the ATTCALL program is linked with the REUS parameter. Define the LKED.SYSIN parameter in ATTHRDPL: INCLUDE SYSLIB (EZACIC07) NAME ATTHRDPL(R)
CICS Definitions
Enter the following CICS definitions:
DEFINE FILE(ATYCPLOG) GROUP(ATY) DSNAME() RECORDFORMAT(F) ADD(YES) BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES) STRINGS(5) DEFINE PROGRAM(ATTHRDPL) GROUP(ATY) LANGUAGE(C) DEFINE PROGRAM(ATTCALL) GROUP(ATY) LANGUAGE(C) DEFINE PROGRAM(ATTCNTRL) GROUP(ATY) LANGUAGE(C) DEFINE TRANSACTION() PROGRAM(ATTCNTRL) GROUP(ATY) DEFINE TRANSACTION() PROGRAM(ATTHRDPL) GROUP(ATY) DEFINE TRANCLASS(ATY) GROUP(ATY) MAXACTIVE()
85-33
To use the transaction in a C program, copy NAVROOT.LOAD(ATYDC3GC) to the same IMS/TM program library (such as IMS.PGMLIB). To use the transaction in a COBOL program, copy NAVROOT.LOAD(ATYDC3GL) to the same IMS/TM program library (such as IMS.PGMLIB).
64 64 64 64 256 64 256 64
(Cont.) Data Buffer Parameters Size 4 Description The following flags are available:
1. 2. 3. 4. 5. 6.
A trace of the XML is performed. A trace of the communication calls is performed. Both the XML and communication calls are traced. The NAT firewall protocol is used, with a fixed address for the daemon. A trace of the XML is performed and the NAT firewall protocol is used, with a fixed address for the daemon. A trace of the communication calls is performed and the NAT firewall protocol is used, with a fixed address for the daemon. Both the XML and communication calls are traced and the NAT firewall protocol is used, with a fixed address for the daemon.
7.
For information on the NAT firewall protocol, see Firewall Support. Input format 4 The following formats are available: 0: Input is provided as XML. 1: Input is provided using parameters. Input The size of the input depends on the value specified in the Input size parameter. If the Input format is set to 0 (XML), the input is formatted as follows:
The first four bytes specify the size of the input XML string. The next 64 bytes specifies the name of the record used for the output (the inbound interaction). The next bytes (to the exact length specified in the first four bytes) specify the input XML string. For example: <findorder ORDER_NO=17 /> where findorder is the inbound interaction name.
If the Input format is set to 1 (the input is done using parameters), the input is formatted as follows:
The first four bytes specify the number of parameters. The next 4 bytes specify the maximum size of any parameter value. The next 64 bytes specify the name of the record used for the output (the inbound interaction). The next 32 bytes specify the name of the parameter. The next bytes (to the exact length specified in the first four bytes) specify the input parameter. The following bytes repeat the last two entries until all the parameters are specified.
85-35
C Call
The ATYDC3GC transaction is called as follows:
unsigned char commDataBuff[5000]; short comlen = 5000; typedef void (*f_ptr)(char *, short int*); static f_ptr fetch_ptr; fetch_ptr = (f_ptr) fetch("ATYDC3GC"); ....... preparing the buffer ...... fetch_ptr(commDataBuff , &comlen ); ....... preparing the buffer ...... fetch_ptr(commDataBuff , &comlen );
where: commDataBuff: The buffer with the interaction details. comlen: The size of the buffer. This value is also used to determine the size of the output string. Thus make sure the value is big enough for the expected output. After defining the buffer and calling the ATYDC3GC transaction, compile and move the C program to the IMS/TM program library (such as IMS.PGMLIB).
COBOL Call
The ATYDC3GL transaction is called using a template similar to the following:
* * COBOL COPY OF DATA BUFFER * 01 COMM-DATA-BUFF PIC X(5000). 01 COMM-DATA-BUFF-ERROR REDEFINES COMM-DATA-BUFF. 05 COMM-ERROR-STATUS PIC S9(8) COMP SYNC. 05 COMM-ERROR-MSG PIC X(256). COMM-DATA-BUFF-INPUT REDEFINES COMM-DATA-BUFF. 05 INPUT-COMMAREA-3GL. 10 INCOM-VERSION PIC S9(8) COMP SYNC. 10 INCOM-SERVERS-URLS PIC X(256). /* IP1:PORT[,IP2:PORT] [,...] */ 10 INCOM-USER-NAME PIC X(64). 10 INCOM-PASSWORD PIC X(64). 10 INCOM-WORKSPACE PIC X(64). 10 INCOM-ADAPTER-NAME PIC X(64). 10 INCOM-SCHEMA-FILE-NAME PIC X(256). 10 INCOM-ENC-KEY-NAME PIC X(64). 10 INCOM-ENC-KEY-VALUE PIC X(256). 10 INCOM-INTERACTION-NAME PIC X(64). 10 INCOM-DW-FLAGS PIC S9(8) COMP SYNC. 10 INCOM-INP-FORMAT PIC S9(8) COMP SYNC. 10 INCOM-EXEC-INPUT. 15 INCOM-XML-BUFF. 20 INCOM-XML-ILEN PIC S9(8) COMP SYNC.
01
INCOM-XML-INTER-OUTREC-NAME PIC X(64). *====>>> CHANGE ??? TO LEN SPECIFIED IN INCOM-XML-ILEN 20 INCOM-XML-INPUT PIC X(???). 15 INCOM-PARAM-BUFF REDEFINES INCOM-XML-BUFF. 20 INCOM-PARAM-COUNT PIC S9(8) COMP SYNC. 20 INCOM-PARAM-VALUE-LEN PIC S9(8) COMP SYNC. 20 INCOM-PARAM-INT-OUTREC-NAME PIC X(64). *====>>> CHANGE ?? TO COUNT SPECIFIED IN INCOM-PARAM-COUNT 20 INCOM-PARAM-NAME-VALUE OCCURS ?? TIMES. 25 INCOM-PARAM-NAME PIC X(32). *====>>> CHANGE ?? TO LEN SPECIFIED IN INCOM-PARAM-VALUE-LEN 25 INCOM-PARAM-VALUE PIC X(??). 01 COMM-DATA-BUFF-OUTPUT REDEFINES COMM-DATA-BUFF. 05 05 05 COMM-OUT-STATUS COMM-OUT-LENGTH COMM-OUT-DATA PIC S9(8) COMP SYNC. PIC S9(8) COMP SYNC. PIC X(4992)
20
77 COMLEN PIC S9(4) COMP SYNC VALUE +5000. 77 API-INTERFACE PIC X(8) VALUE 'ATYDC3GL'. CALL API-INTERFACE USING COMM-DATA-BUFF COMLEN.
where: COMM-DATA-BUFF: The buffer with the interaction details. COMLEN: The size of the buffer. This value is also used to determine the size of the output string. Thus make sure the value is big enough for the expected output. The first time the CALL is performed, it will do a one-time fetch and a call. Thereafter, it will do only a call. To release the module just before termination of the calling program, write the following line of code: CANCEL API-INTERFACE. After defining the buffer and calling the ATYDC3GL transaction, compile and move the COBOL program to the IMS/TM program library (such as IMS.PGMLIB).
The first four bytes specify the size of the output. The following bytes make up the XML output.
If parameters were specified for the input and the result is success, the output is formatted as follows:
85-37
The next 32 bytes specify the name of the output attribute. The next bytes (to the exact length specified for the input string in the) specify the output value. The following bytes repeat the last two entries until all the output is specified.
86
JCA Client Interface
This section includes the following topics:
Overview Outbound Connections JCA Client Interface Attunity JCA Enhancements JCA Logging Mechanism JCA Sample Program
Overview
The J2EE Connector architecture (JCA) provides a Java technology solution to the problem of connectivity between the many application servers and today's enterprise information systems (EIS). To achieve a standard system-level connectivity between application servers and EISs, the J2EE Connector architecture defines a standard set of system-level contracts between an application server and EIS. The resource adapter implements the EIS-side of these system-level contracts. A resource adapter is a system-level software driver used by an application server or an application client to connect to an EIS. By plugging into an application server, the resource adapter collaborates with the server to provide the underlying mechanisms, the transactions, security, and connection pooling mechanisms. For information on the JCA versions supported by AIS, see Attunity Integration Suite Supported Systems and Resources.
Outbound Connections
This section includes the following topics:
Creating a Connection
Connecting to AIS from a JCA Application Server requires a creation and configuration of a ManagedConnectionFactory instance.
A ManagedConnectionFactory instance is a factory of both ManagedConnection and EIS-specific connection factory instances, providing methods for matching and creation of ManagedConnection instance. ManagedConnection instance represents a physical connection to the underlying EIS, and provides access to the XAResource and LocalTransaction interfaces. The XAResource interface is used by the transaction manager to associate and dissociate a transaction with the underlying EIS resource manager instance and to perform two-phase commit (2PC) protocol. The LocalTransaction interface is used by the application server to manage local transactions. This should be done by the following steps:
Example 861 Creating a connection
AttuManagedConFactory mcf = new AttuManagedConFactory(); //Set ManagedConenctionFactory properties mcf.set(); AttuConnectionFactory cf = (AttuConnectionFactory)mcf.createConnectionFactory(); javax.resource.cci.Connection con = cf.getConnection();
setEncryptionKeyValue(String keyValue) setEncryptionKeyName(String keyName) setFakeXa(String isFakeXa) setFirewallProtocol (String name) setKeepAlive(String keepAlive) setLogger(CoreLogger logger)
Table 861 (Cont.) ConnectionFactory Parameters Parameter setLogLevel(String logLevel) Description Sets the log level. It can be set to one of the following:
1: ACX log level set to INFO, Application log level set to FATAL. 2: ACX log level set to FATAL, Application log level set to DEBUG. 3: ACX log level set to DEBUG, Application log level is set to FATAL. 4: ACX log level set to INFO, Application log level set to FATAL. 5: ACX log level set to INFO, Application log level set to FATAL. 6: ACX log level set to INFO, Application log level set to FATAL.
Sets the log writer. Sets the network XML protocol. The valid values are text for the old protocol, binary for the latest. If not set, the default (binary) is used. Sets the password for connecting to Attunity daemon/server. Must be called if Attunity daemon/server requests user authentication. This parameter is deprecated and should not be used. The default is set to true. The port number where Attunity daemon/server is running. Must be called if Attunity daemon/server is running on a non-default port. Sets the Attunity Queue adapter for inbound events (for JCA 1.0 only). Sets the Attunity Queue workspace for inbound events (for JCA 1.0 only). The server name, IP address or the Attunity daemon/server where the requested EIS resides. A flag indicating an addition of a namespace to the output response XML. The namespace is added with the following format: xmlins=\"noNamespace://* + adapterName + "\ The default is set to false.
setUserName(String userName)
The user name for connecting to Attunity daemon/server. Must be called if Attunity daemon/server requests user authentication. Sets the Attunity workspace where the EIS resides. If not set, the default Navigator workspace is used.
setWorkspace(String newWorkspace)
Table 862 Attunity Class AttuAdapterMd AttuConnection AttuConnectionFactory AttuConnectionManager AttuConnectionMd AttuConnectionSpec AttuConRequestInfo AttuConstants AttuDom AttuDomImpl AttuDomRecord AttuDomWriter AttuEventConnection AttuInteraction AttuInteractionSpec
Supported JCA Interfaces JCA Interface Implemented javax.resource.cci.resourceAdapterMetadata javax.resource.cci.Connection javax.resource.cci.ConnectionFactory javax.resource.spi.ConnectionManager javax.resource.cci.ConnectionMetadata javax.resource.cci.ConnectionSpec, Serializable javax.resource.spi.ConnectionRequestInfo, Serializable An internal class. An interface for all XML-based objects. Implements the AttuDom interface. javax.resource.cci.Record. This class extends the original JCA Record class. An internal class. An internal class. javax.resource.cci.Interaction javax.resource.cci.InteractionSpec. This class extends the original JCA InteractionSpec class and adds some enhancements. The additional methods are:
setInteractionVerb(String verb): Sets the verb mode of interaction with an EIS instance (sync_send, sync_send_ receive, sync_receive). getInteractionVerb(): Returns the mode of interaction with an EIS instance (sync_send, sync_send_receive, sync_receive). setExecutionTimeout(String sTimeout): Sets the number of milliseconds an interaction will wait for an EIS to execute the specified function. getExecutionTimeout(): Returns the execution timeout. setAdapterName(String adapterName): Sets the adapter that will execute the specified function. getAdapterName(): Returns the adapter name if it is set on the interactionSpec. Otherwise, it returns NULL. setFunctionName(String name): Sets the function name. getFunctionName(): Returns the function name.
javax.resource.spi.LocalTransaction and javax.resource.cci.LocalTransaction An internal class, implementing the log4j logger. javax.resource.spi.ManagedCOnnection javax.resource.spi.ManagedConnectionFactory javax.resource.spi.ManagedConnectionMetadata javax.resource.cci.MappedRecord An internal class, common interface for all metadata objects. javax.resource.cci.RecordFactory
Table 862 (Cont.) Supported JCA Interfaces Attunity Class AttuTrHandle AttuXAResource AttuXid JCA Interface Implemented An internal class. javax.transaction.xa.XAResource javax.transaction.xa.Xid
Attunity Metadata
In addition to classes required for the JCA implementation, Attunity JCA provides the extensions for handling metadata required by an application adapter. The following types of metadata objects are provided:
Table 863 Object Name AttuConnectionMd Attunity Enhancement Objects Description This class has been extended to provide metadata-related interactions, records, fields and enumerations, which exist in an application adapter. Metadata information returned from records metadata request includes transitive-clause of all referenced records and enumerations. Enumerations cant be retrieved separately. The instance of the class is created through the AttuConnection.getMetaData() method. AttuEnumMd Describes the metadata of the schema enumeration (a set of name and value pairs). The instance of the class is created through the following steps:
1. 2.
AttuConnection.getMetadata(): Returns an AttuConnectionMd object. AttuConnectionMd.getRecordsMd(Element schemaEl, Vector enumsMd): Returns a vector (enumsMd) with a separate object for every "enumeration" in a schema.
AttuInteractionMd
Describes the metadata of an interaction object. The instance of the class is created through AttuConnection.getInteractionMd(String[] names, int type) where names is an array of interaction names. Describes the metadata of a record field. The field type can be categorized as primitive (int, boolean, etc...), XML (DOMs text or element), record or enumeration. A records structure and enumeration values are defined in the EIS schema and can be accessed through the AttuConnectionMd object. The instance of the class is accessed through AttuRecordMd.getFieldsMd(). Describes the metadata of a record object. The record metadata is built according to the W3C DOM tree describing it. The instance of the class is created through the following steps:
1. 2.
AttuFiledMd
AttuRecordMd
AttuConnection.getMetaData(): Returns an AttuConnectionMd object. AttuConnectionMd.getRecordsMd(): Returns an array of metadata objects. Each object contains metadata of records.
Table 863 (Cont.) Attunity Enhancement Objects Object Name AttuResourceMd Description Describes the metadata for the application adapter. The instance of the class is created through AttuConnectionMd.getResourceMd(String[] names). Where names is an array of resource names. If "null", then metadata of the currently connected adapter is returned (as the first element is the array). The instance of the class is created through the following steps:
1. 2.
AttuConnection.getMetaData(): Returns an AttuConnectionMd object. AttuConnectionMd.getResourceMd(String[] names): Getsmetadata for specified resources. This should be used when an ACX adapter is connected. If a non-ACX adapter is connected, it is possible to get its metadata by passing "null" to the function.
Returns a list of resource/records/interactions/events metadata objects for an application adapter with a live connection. Where:
type: The required metadata object type (adapter, record, interaction or event). mask: A wildcard (*,%) for the names maxResultItems optional parameter. If positive, it limits the number of names that are returned. startItemName: This optional parameter specifies an item name staring from which items are to be returned. If "null", items following the first one are returned.
Returns the AttuDom object of the full resources/records/interactions/events metadata objects according to the type requested. Where:
type: The required item type (adapter, interaction, record, schema, all, event, w3cSchema, wsdl, dtd). names: An array of string objects. A list of names which metadata is required for. For adapter, schema, all, w3cSchema, wsdl, or dtd types, the names parameter is ignored. In these cases, metadata for the currently connected resource is returned.
Attunity Record
The following classes extends the original JCA Record classes and adds some enhancements:
Table 864 Object Name AttuDomRecord Attunity RECORDS Enhancement Objects Description This object implements the javax.resource.cci.Record interface. Additional methods are:
getDom(): Returns the DOM record content representation. setDom(Element content): Sets the record content specified by the DOM. SetTextXml (String xml): Sets all XML as input including the mappedRecord roots element.
Table 864 (Cont.) Attunity RECORDS Enhancement Objects Object Name AttuMappedRecord Description This object implements the javax.resource.cci.MappedRecord interface. Additional method:
Samples
Example 862 Sample code of using the getMetadataList method
AttuConnectionMd cm = (AttuConnectionMd)con.getMetaData(); String[] name = cm.getMetadataList(adapter, null, 0, null); for (int i = 0; i < names.length; i++) { System.out.println("name = " + names[i]); } Example 863 name = query name = DEMO name = calc Example 864 Sample code of using the getMetadataItem method Sample output for the getMetadataList method
AttuConnectionMd cm = (AttuConnectionMd)con.getMetaData(); String[] names = {"WSDL (W3c)"}; AttuDom attuDom = cm.getMetadataItem(wsdl, names); //Printing the output XML if (attuDom.getDom() != null) { coreDOMWriter domW = new CoreDOMWriter(false); String szXml = domW.toXMLString(attuDom.getDom()); System.out.println(szXml); } Example 865 Sample output for each input for the getMetadataItem method
type: adapter
<getMetadataItemResponse> <adapter name='query' description='Attunity Connect Query Adapter' version='1.0' type='query' operatingSystem='INTEL-NT' vendor='Attunity Ltd.' transactionLevelSupport='2PC' authenticationMechanism='basic-password' maxActiveConnections='0' maxIdleTimeout='600' maxRequestSize='32000' connectionPoolingSize='0' poolingTimeout='0'/> </getMetadataItemResponse>
... </getMetadataItemResponse>
connectionPoolingSize='0' poolingTimeout='0'> <interaction name='callProcedure' description='Call a stored procedure' mode='sync-send-receive' input='callProcedure' output='multipleResultset'> </interaction> ... <schema name='query' version='1.00> <enumeration name='outputFormat'> <item name='attributes' value='0'/> <item name='elements' value='1'/> <item name='msado' value='2'/> <item name='xml' value='3'/> </enumeration> ... </schema> </adapter> </getMetadataItemResponse>
<wsdl:portType name='queryPortType'> <wsdl:operation name='callProcedure'> <wsdl:input message='tns:callProcedureRequest' name='callProcedureRequest'/> <wsdl:output message='tns:callProcedureResponse' name='callProcedureResponse'/> </wsdl:operation> ... </wsdl:portType> </wsdl:definitions> </getMetadataItemResponse>
All the above objects implement the base AttuMdItem and the AttuDom interfaces.
Example 866 A sample code of using the Dom Record method
The following sample demonstrates using the Attunity JCA "Ordersys" adapter, (supplied as part of AIS). The full sample is provided with AIS installation. This sample executes the following steps:
A managedConnection Factory request. A connection factory request. A connection request. An interaction request. Invokes the interaction. Extracts the interaction response information as an XML document (using the Record methods). Places a new order using a MappedRecord object.
* legacy adapter in a non-managed (2-tier) mode. * * Prerequisites: * This program requires that the sample Ordersys adapter DLL is installed * in "Connect" with the adapter name 'orders'. * */ import java.io.*; import java.util.Vector; import javax.resource.*; import javax.xml.parsers.*; import com.attunity.adapter.*; import com.attunity.adapter.core.*; import com.attunity.adapter.core.acp.*; import org.w3c.dom.*; import com.attunity.adapter.*; public class OrdersSample { // Operational parameters for this sample static String ATTC_SERVER = "localhost"; static String ATTC_PORT = ""; static String ATTC_ADAPTER = "orders"; public static void main(String[] args) // throws ResourceException,java.io.IOException { if (args.length > 0) { String machine = args[0]; ATTC_SERVER = machine.substring(0, machine.indexOf(":")); int portStart = machine.indexOf(":"); if (portStart >= 0) ATTC_PORT = machine.substring(portStart+1, machine.length()); } PrintWriter printWriter = new PrintWriter(System.out); // Step 1. //-------------------------------------------------------------------System.out.println( "Step 1. Acquire a Managed connection factory and configure it"); AttuManagedConFactory mcf = new AttuManagedConFactory(); try { mcf.setLogWriter(printWriter); mcf.setEisName(ATTC_ADAPTER); mcf.setServerName(ATTC_SERVER); mcf.setPortNumber(ATTC_PORT); // Username and password might be required, depending on // the server settings mcf.setUserName(null); mcf.setPassword(null); } catch (ResourceException re) { System.out.println("Error setting up the Managed connection factory:"); System.out.println(re.getMessage()); re.printStackTrace();
return; } // Step 2. //-------------------------------------------------------------------System.out.println( "Step 2. Acquire a Connection factory and set it up"); //ConnectionFactory cf; AttuConnectionFactory cf; try { //Attu cf = (AttuConnectionFactory)mcf.createConnectionFactory(); cf.setLogWriter(printWriter); cf.setTimeout(20000); } catch (ResourceException re) { System.out.println("Error setting up the Connection factory:"); System.out.println(re.getMessage()); re.printStackTrace(); return; } // Step 3. //-------------------------------------------------------------------System.out.println( "Step 3. Get an adapter connection from the connection factory"); javax.resource.cci.Connection con; try { con = cf.getConnection(); } catch (ResourceException re) { System.out.println("Error getting an Adapter connection:"); System.out.println(re.getMessage()); re.printStackTrace(); return; } // Step 4. //-------------------------------------------------------------------System.out.println( "Step 4. Get an interaction from the connection"); javax.resource.cci.Interaction interaction; try { interaction = con.createInteraction(); } catch (ResourceException re) { System.out.println("Error creating an Adapter interaction:"); System.out.println(re.getMessage()); re.printStackTrace(); return; } // Step 5. // // The input to the findOrder interaction is an XML document in the // folowing shape: // // <findOrder> // <ORDER_ID>1</ORDER_ID> // </findOrder> // //-------------------------------------------------------------------System.out.println(
"Step 5. Set up the findOrder interaction input and invoke interaction"); javax.resource.cci.RecordFactory rf; javax.resource.cci.MappedRecord findOrderOut; try { AttuInteractionSpec ispec = new AttuInteractionSpec("findOrder"); //cf.getRecordFactory(); rf = cf.getRecordFactory(); //rf=new RecordFactory(); javax.resource.cci.MappedRecord findOrderIn = rf.createMappedRecord("findOrder"); //rf.createMappedRecord("findOrder"); // Find order with ORDER_ID = 1 findOrderIn.put("ORDER_ID", "1"); findOrderOut = (javax.resource.cci.MappedRecord)interaction.execute(ispec, findOrderIn); } catch (ResourceException re) { System.out.println("Error preparing/calling the 'findOrder' interaction:"); System.out.println(re.getMessage()); re.printStackTrace(); return; } // Step 6. // // The output of findOrder is an XML document in the folowing shape: // // <findOrderResponse> // <ORDER ORDER_ID="1" ORDERED_BY="Jim Bo" N_LINES="2"> // <ADDRESS // ADDRESSEE="Jim Bo & Sons, LLC." // STREET="Fits Road" // CITY="Oukalaka" // ZIP="33212" // STATE="NH" // COUNTRY="USA" /> // <LINES LINE_NO="1" ITEM_NAME="Knife" QUANTITY="5" ITEM_PRICE="1.2" /> // /> // </ORDER> // </findOrderResponse> // //-------------------------------------------------------------------System.out.println( "Step 6. Extract the response information as an XML document"); CoreDomRecord domOrder = (CoreDomRecord) findOrderOut; CoreDOMWriter domWriter = new CoreDOMWriter(false); String xmlOrder; try { xmlOrder = domWriter.toXMLString(domOrder.getDom()); } catch (ResourceException re) { System.out.println("Error writing response to XML:"); System.out.println(re.getMessage()); <LINES LINE_NO="2" ITEM_NAME="Fork" QUANTITY="5" ITEM_PRICE="0.9"
re.printStackTrace(); return; } System.out.println("Response as XML is:"); System.out.println(xmlOrder); // Step 7. // // record.get("@attr") - retrieves an attribute value // record.get("#") - retrieves an attribute value //-------------------------------------------------------------------System.out.println( "Step 7. Extract the response information - e.g., to print it"); javax.resource.cci.MappedRecord order = (javax.resource.cci.MappedRecord) findOrderOut.get("#ORDER"); if (order == null) System.out.println("\tNo Order information was found"); else { System.out.println("\tOrderID\t" + (String)order.get("@ORDER_ID") ); System.out.println("\tOrderedBy\t" + (String)order.get("@ORDERED_BY") ); javax.resource.cci.MappedRecord address = (javax.resource.cci.MappedRecord) order.get("#ADDRESS"); if (address == null) System.out.println("\tNo address information was found"); else { System.out.println("\tAddress information:"); System.out.println("\t\tAddressee\t" + (String)address.get("@ADDRESSEE") ); System.out.println("\t\tStreet\t" + (String)address.get("@STREET") ); System.out.println("\t\tCity\t" + (String)address.get("@CITY") ); System.out.println("\t\tZip\t" + (String)address.get("@ZIP") ); System.out.println("\t\tState\t" + (String)address.get("@STATE") ); System.out.println("\t\tCountry\t" + (String)address.get("@COUNTRY") ); } Vector lines = (Vector) order.get("#LINES[]"); if (lines == null) System.out.println("\tNo Order lines information was found"); else { for (int i = 0; i < lines.size(); i++) { javax.resource.cci.MappedRecord line = (javax.resource.cci.MappedRecord) lines.get(i); System.out.println("\tLineNo\t" + (String)line.get("@LINE_NO") ); System.out.println("\t\tItemName\t" + (String)line.get("@ITEM_ NAME") ); System.out.println("\t\tQuantity\t" + (String)line.get("@QUANTITY") ); System.out.println("\t\tItemPrice\t" + (String)line.get("@ITEM_PRICE") ); } }
} // Step 8. //-------------------------------------------------------------------System.out.println( "Step 8. Place a new order using an XML string:"); xmlOrder = "<placeOrder>\n" + "<ORDER ORDERED_BY='Winnie The Pooh'>\n" + " <ADDRESS\n" + " ADDRESSEE='Forrest woods'\n" + " STREET='Dry Lane'\n" + " CITY='South Mountain'\n" + " ZIP='12345'\n" + " STATE='N/A'\n" + " COUNTRY='Legend'/>\n" + " <LINES LINE_NO='1' ITEM_NAME='Honey' QUANTITY='5' ITEM_PRICE='8.2' />\n" + " <LINES LINE_NO='2' ITEM_NAME='Blueberries Jam' QUANTITY='' ITEM_ PRICE='10.9' />\n" + " <LINES LINE_NO='2' ITEM_NAME='Ant Hill' QUANTITY='1' ITEM _PRICE='29.9' />\n" + "</ORDER>\n" + "</placeOrder>\n"; System.out.println(xmlOrder); javax.resource.cci.MappedRecord placeOrderOut; try { AttuInteractionSpec ispec = new AttuInteractionSpec("placeOrder"); javax.resource.cci.MappedRecord placeOrderIn = rf.createMappedRecord("placeOrder"); // Set input record from the XML string ((CoreDomRecord)placeOrderIn).setTextXml(xmlOrder); placeOrderOut = (javax.resource.cci.MappedRecord)interaction.execute(ispec, placeOrderIn); } catch (ResourceException re) { System.out.println("Error preparing/calling the 'placeOrder' interaction:"); System.out.println(re.getMessage()); re.printStackTrace(); return; } } }
To activate the Attunity JCA logging 1. Extract the log4j jar file provided with the Attunity JCA product (inside the attunityResourceAdapter.zip file) under the lib directory.
2. 3.
Include the log4j jar file in your application classpath so that logging methods can find the required classes. Extract the log4j.properties file from the zip file and put it in your application classpath. When you add this file to the classpath, ensure it appears before the Attunity Resource Adapter jars. You can make modifications to this file according to your specific requirements, based on the following guidelines:
log4j can log messages with the following priorities: debug: Writes debugging messages which should not be printed when the application is in production. info: Writes messages similar to the "verbose" mode of many applications. warn: Writes warning messages to the log. error: Writes application error messages to the log. fatal: Writes critical messages to the log.
4.
In the log4j.properties file, set "log4j.rootCategory=<LOG_LEVEL>", which instructs log4j to ignore messages with priority less than <LOG_LEVEL>
### This file has to be located in the same directory ### as QuerySample.class (the class running the "main()" method). ### Use one appenders to log to a file (it is possible to use more appenders, ### to log to console, for example). log4j.rootCategory=debug log4j.additivity.com.attunity.connect.acx=false log4j.category.com.attunity.connect.acx=DEBUG, logFile log4j.category.com.attunity.connect.jca=DEBUG, logFile
###This appender writes to a file log4j.appender.logFile=org.apache.log4j.RollingFileAppender log4j.appender.logFile.File=D:\\QuerySample.log ##The PatternLayout defaults to %m%n which means print your-supplied message and a newline log4j.appender.logFile.layout=org.apache.log4j.PatternLayout ### ConversionPattern: How to format each log message (What information to include). ### %p Outputs the message priority. ### %t Outputs the thread making the log request. ### %c Outputs the name of the category associated with the log request. ### %m Outputs the message itself, %n is newline. log4j.category.com.attunity.connect.jca.appender.logFile.layout.ConversionPattern= %p %m %d{ISO8601} %n log4j.category.com.attunity.connect.acx.appender.logFile.layout.ConversionPattern= %p %m %d{ISO8601} %n
#log4j.appender.logFile.layout.ConversionPattern= %p %m
%d{ISO8601} %n
The IP address of the daemon or server. The port number where the daemon/server is running (press Enter for the default port). The user name to connect to the daemon/server (press Enter when the daemon/server doesnt request user authentication). The password used to connect to the daemon/server (press Enter when the daemon/server doesnt request user authentication). An SQL query (e.g: SELECT * from disam:nv_dept).
Note:
When working with the query interaction, the SQL statement must be a SELECT statement.
A connection request. The query execution. Prints the results to the console. Closes the connection.
/* * * This sample demonstrates the usage of the "Connect" JCA * query adapter in a non-managed (2-tier) mode. * * Prerequisites: * This program uses the default query adapter in "Connect". * * THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY * KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR * PURPOSE. * */ import javax.resource.*; import java.io.*; import java.util.Vector; import org.w3c.dom.*; import com.attunity.adapter.*; import com.attunity.adapter.core.*;
public class QuerySample { public QuerySample() { } public static void main(String[] args) throws ResourceException,java.io.IOException { AttuManagedConFactory mcf = new AttuManagedConFactory();
// Ask user for server, user name and password information configureEis(mcf); String sSql = askUser("Enter the SELECT statement for execution: "); AttuConnectionFactory cf = (AttuConnectionFactory)mcf.createConnectionFactory(); //----------------------------------try { javax.resource.cci.Connection con = cf.getConnection(); javax.resource.cci.Interaction interaction = con.createInteraction(); // To execute the query we use "query" interaction AttuInteractionSpec iSpeq = new AttuInteractionSpec("query");
javax.resource.cci.RecordFactory rf = cf.getRecordFactory(); javax.resource.cci.MappedRecord queryRecord = rf.createMappedRecord("query"); queryRecord.put("##text", sSql); javax.resource.cci.Record oRec = interaction.execute(iSpeq, queryRecord); Element outEl = ((CoreDomRecord)oRec).getDom(); CoreDOMWriter domW = new CoreDOMWriter(false); String xml = domW.toXMLString(outEl); System.out.println("got back " + xml); System.out.println("now using the get functions of the Record interface"); /* Here we get an array of sub elements named record */ Vector recordV = (Vector)((CoreMappedRecord)oRec).get("#record[]"); if (recordV == null || recordV.isEmpty()) { System.out.println("No sub elements named record"); return; } /* If the sql was select * from nv_dept and the output columns * are dept_budget && dept_id here we print them . */
for (int objInd = 0; objInd < recordV.size(); objInd++) { CoreMappedRecord record = (CoreMappedRecord)recordV.get(objInd); String dept_budget = (String)record.get("@dept_budget"); String dept_id = (String)record.get("@dept_id"); System.out.println("dept_budget is " + dept_budget); System.out.println("dept_id is " + dept_id); } interaction.close(); con.close(); } catch (ResourceException ex) { System.out.print("Exception in QuerySample: " + ex.getMessage()); ex.printStackTrace(); throw ex; } } /* * Configure EIS we are working with. * Ask user for server, user name and password information */ static private void configureEis(AttuManagedConFactory mcf) throws java.io.IOException, ResourceException { System.out.println(); System.out.println(); System.out.println("This sample demonstrates the work against 'query' EIS"); System.out.println("====================================================="); System.out.println(); System.out.println(); // The sample demonstrates the work with "query" EIS mcf.setEisName("query"); String sServer = askUser("Please enter the IP of the daemon or server: "); String sPort = askUser("Please enter the port number where daemon/server is running (ENTER for default): "); int iPort; // Use default port if(sPort.length() == 0) sPort = "";
String sUser = askUser("Please enter the user name to connect the daemon/server: "); String sPassword = askUser("Please enter the password to connect the daemon/server: "); mcf.setServerName(sServer); mcf.setPortNumber(sPort); mcf.setUserName(sUser); mcf.setPassword(sPassword);
} /* * Prints the question onto screen and returns typed answer */ static private String askUser(String sQuestion) throws java.io.IOException { InputStreamReader isr = new InputStreamReader(System.in); char inBuf[] = new char[1000]; String sAnswer; System.out.print(sQuestion); isr.read(inBuf, 0, 999); System.out.println(); sAnswer = new String(inBuf); sAnswer = sAnswer.trim(); return sAnswer; } }
87
JDBC Client Interface
This section includes the following topics:
Overview Connection Data Types JDBC API Conformance JDBC Client Interface JDBC Sample Program
Overview
JDBC is a Java programming interface allowing external access to SQL database manipulation and update commands. It enables the integration of SQL calls into a general programming environment by providing library routines which interface with the database. The JDBC driver provides support to allow Java applets, servlets and applications, using the JDK version 1.3 or higher, to access data sources. Using the JDBC driver, the user writes a Java program, which interacts with a database. Using standard library routines, the user should open a connection to a database, and then use JDBC to send an SQL code to the database, and process the results that are returned. When the results are done, the user should close the connection. All supported data sources can be accessed from Java applications. Such an approach has to be contrasted with the precompilation route taken with embedded SQL, which is converted to the host language code (C/C++). Call level interfaces do not require precompilation therefore avoid some of the problems of Embedded SQL. The result is increased portability and a cleaner client-server relationship. The following figure shows how Attunity AIS interacts with JDBC:
Connection
This section includes the following topics:
Creating a Connection
Before a database can be accessed, a connection must be opened between the client program and the database (server).
Note:
This connection (using connection string) does not enable you to access data sources directly via the JDBC 2 data Source interface functionality. The method for accessing data directly is described in Accessing Data Sources Directly.
Loading the vendor specific driver: This step is performed to ensure portability and code reuse. AIS JDBC driver is loaded using the following code snippet:
Class.forName("com.attunity.jdbc.NvDriver");
2.
Making the connection: Once the driver is loaded and ready for a connection to be made, the user may create an instance of a connection object using the following code snippet:
Connection con = DriverManager.getConnection(url, username, password);
Where:
url: The URL for the AIS daemon. username: The username needed to connect to the AIS daemon. password: The password needed to connect to the AIS daemon.
Connection String
The connection string for the getConnection method has the following syntax:
87-2 AIS User Guide and Reference
Where:
Parameter username:password Description The username/password needed to connect to the AIS daemon/server. If anonymous access is allowed on the remote machine, then these parameters are optional. If you dont specify a user name and password, and anonumous access is not allowed, then the "user=someUser" and "password=somePwd" tokens are used to access the computer. Note: The user id of the computer you are accessing must be the same as the user profile ID. machine port The IP address where AIS daemon runs. The port that the daemon listens to. If omitted, then the default, 2551, is used. If you specify encryption_protocol in the connection string, then you must also specify the port number. encryption_protocol The protocol used for encrypting network communications. RC4 and Des3 protocols are supported. Note: The value for the encryption protocol is case sensitive. If you specify encryption_protocol, then you must also specify a port number and the encryptionKey parameter. workspace The daemons workspace. The default is Navigator.
Parameter parameter
addDefaultSchema: (1/0) Specifies that a schema shows a default owner name (public) if the data source does not natively support owners. The default is set to 1. DefTdpName: The name of the data source which is accessed by this connection by default. Tables specified in SQL statements are assumed to be from this data source. If this argument is not specified, then SYS is the default. For tables from any other data source you must prefix each table name with the name of the data source, using the datasource:tablename format. encryptionKey: Establishes encryption of client/server network communication from a Java thin client. Note: If you specify encryption_protocol in the connection string, then you must specify this parameter. This parameter can have one of the following attributes: resource: The name associated with the encryption password and which the daemon on the remote server looks up. If this resource entry is not specified, the daemon on the server machine uses the name of the user account that is accessing this remote machine. password: The password is required in order to pass or access encrypted information over the network. A password entry surrounded by curly braces (as in ({password}) is assumed to be in hexadecimal format. Thus {456ACF} is interpreted as 0x456ACF, and {TDX} is not a legal password but TDX is
firewallProtocol Log
The firewall protocol used (if available). Currently, fixedNat is supported. Specifies the logging level. The following logging levels are available:
0: No (the default). 1: JDBC API logging. 2: NAV API logging. 3: JDBC and NAV APIs logging.
LogFile
Specifies the log file. This parameter is relevant only when the Log parameter value is other than zero. The log file name can include the following tokens, which are replaced with the appropriate values:
%T: Specifies the date the file was created. %I: Specifies the sequence number of the current connection within the session. If neither %T nor %I are specified, a new log for this connection overwrites the existing log. If LogFile is not specified and Log is, then all output log information is delegated to DriverManager.
Notes:
1. 2.
Description Specifies the maximum number of simultaneous connections to this data source. The default is set to zero. Specifies the maximum number of active SQL statements that can run against this data source. The default is set to zero. Specifies that the schema shows tables only of the default data source, as if only one data source is defined. The default is set to 1, indicating single tdp mode. Specifies that commit/rollback are always processed in auto commit mode turned off. Setting this parameter to 1, indicates that when commit/rollback APIs are called, and auto commit mode is off, they are processed only if the transaction is not empty (executes were performed under this transaction). The default is set to 0. Specifies whether all SQL statements that do not return rowsets during this connection will pass directly to the native RDBMS data source parameter, without any parsing normally performed by the Query Processor. Setting this parameter to 1 enables passthru mode and causes Attunity Connect to open the connection in single data source mode. This parameter can be used only if the back-end data source is an SQL-based driver. SQL executed in passthru mode behave the same as individual passthru queries specified with the TEXT={{}} syntax; however, there is no way to override passthru mode for a particular query. Use passthru mode to issue queries that perform special processing not supported in Attunity Connect, such as ALTER TABLE and DROP INDEX. Note: It is not recommended using this option since it impacts on every DDL SQL statement, even if only some statements were intended.
OneTdpMode
OptimizeEmptyTrans
Passthru
Password
Specifies the password required in order to decrypt an encrypted user profile on the server. This parameter is used in conjunction with the User parameter. When set to 1, this parameter returns the data source name as part of the schema name for use with multi data source connections. The default is set to 0. When set to 1, this parameter returns the data source name as part of the schema name for use with multi data source connections. The default is set to 0. When set to 1, this parameter returns the data source name as part of the schema name for use with multi data source connections. The default is set to 0. When set to 1, a ResultSetMetadata object is created during the program execution. When set to 0, no metadata object is created, therefore metadata creation is disabled. This is useful when performance considerations are imported and the user program knows the resultset metadata. Then default is set to 1. Specifies the codepage to use when converting text BLOBs. This parameter controls the BLOB codepage as returned from the server. If not specified, the default codepage is used (UTF-8).
QualifyOwner
QualifySchema
QualifyTable
DescribeResultSet
BlobCodePage
Parameter StreamMode
Description A flag for the internal performance enhancing getRows method. It is activated when only when the resultSet parameter is set to forward-only and read-only. The default is set to 0. Specifies the name of a user profile in the repository on a server. The user profile controls access to remote machines and data sources.
User
2.
Specify the methods for the data source object, using the following syntax:
ds.method
Where ds is the name of the data source object, as specified in the previous step. For example, the following specifies the server and port for a connection:
ds.setServerName("osf.acme.com"); ds.setPortNumber(8888);
Note:
The methods available for the data source object are described in JDBC API Conformance.
4.
Data Types
Attunity JDBC driver supports the standard JDBC data type conversion rules between an application using Java data types and a data source using SQL types. These rules apply to JDBC methods on the ResultSet class (retrieving SELECT statement results as Java types) and on the PrepareStatement class (sending Java types as SQL statement input parameters). The data type information is divided into the following tables:
Java and JDBC types mapped to specific SQL types. Conversions between Java object types and target SQL types.
java.math.BigDecimal java.math.BigDecimal NUMERIC DECIMAL boolean byte short int long float double byte[] boolean Integer Integer Integer long float double byte[] BIT TINYINT SMALLINT INTEGER BIGINT REAL DOUBLE FLOAT BINARY VARBINARY LONGVARBINARY DATE TIME TIMESTAMP LONGVARCHAR LONGVARBINARY
A blank entry in this column indicates that Attunity Connect cannot properly process data corresponding to the listed Java and JDBC types, from existing data sources only. You cannot use SQL to create such columns. Attunity Connect allows you to retrieve or modify TEXT (LONGVARCHAR) and IMAGE (LONGVARBINARY) fields, with certain restrictions. The restrictions are due primarily to the support for BLOBs available in the underlying data sources, and may vary from one data source to another (for further details, refer to the PreparedStatement interface). Attunity Connect does not support reading or writing to the JDBC type BIGINT. You can read other data types and convert the data to the Java type long using the getLong method; however, the data must be converted back to its stored data type using the appropriate setXXX method prior to updating the data source.
String java.math.BigDecimal Boolean Integer Long Float Double byte[] java.sql.Date java.sql.Time java.sql.Timestamp
Table 873 (Cont.) Java Object Types and Target SQL types Mapping TINYINT X SAMLLINT X INTEGER X FLOAT X DOUBLE X NUMERIC X CHAR X VARCHAR X TEXT X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X BINARY X X IMAGE X X X DATE X
Supported Interfaces Supported Classes DataSource Properties ConnectionPool Data Source and XADatasource Interface Properties Connection Pooling Properties
Supported Interfaces
The JDBC driver supports the interfaces and methods listed in the following table:
Supported Interfaces and Methods Supported Method absolute acceptChanges afterLast beforeFirst cancelRowDelete cancelRowInsert cancelRowUpdates clone createCopy createShared clearWarnings close deleteRow execute findColumn first getArray getAsciiStream getBigDecimal getBinaryStream getBoolean getByte getBytes getChapter getCharacterStream getConcurrency getDate getDouble getFetchDirection getFetchSize getFloat getInt getLong getMetaData getObject getReader getRef getRow getShort getShowDeleted getStatement getString getTime getTimestamp getType getUnicodeStream getWarnings getWriter insertRow isAfterLast isBeforeFirst isFirst isLastlast moveToCurrentRow moveToInsertRow next previous populate Limitations The following methods are not supported:
getBlob getClob
Table 874 (Cont.) Supported Interfaces and Methods Supported Interface CachedRowSet (continued) Supported Method refreshRow relative release restoreOriginal rowDeleted rowInserted rowUpdated setFetchDirection setFetchSize setReader setShowDeleted setWriter toCollection updateAsciiStream updateBigDecimal updateBinaryStream updateBoolean updateByte updateBytes updateCharacterStream updateDate updateDouble updateFloat updateInt updateLong updateNull updateObject updateRow updateShort updateString updateTime updateTimestamp wasNull <none> clearWarnings close commit createStatement getAutoCommit getCatalog getMetaData getTransactionIsolation getWarnings isClosed isReadOnly nativeSQL prepareCall prepareStatement rollback setAutoCommit setCatalog setReadOnly setTransactionIsolation1 connectionClosed connectionErrorOccurred getPooledConnection setPooledConnection setLogWriter getLogWriter The setLoginTimeout method is not supported. Limitations
CallableStatement Connection
ConnectionEventListener ConnectionPoolDatasource
Table 874 (Cont.) Supported Interfaces and Methods Supported Interface DatabaseMetaData Supported Method allProceduresAreCallable allTablesAreSelectable dataDefinitionCausesTransaction Commit dataDefinitionIgnoredIn Transactions doesMaxRowSizeIncludeBlobs getBestRowIdentifier getCatalogs getCatalogSeparator getCatalogTerm getColumns getCrossReference getDatabaseProductName getDatabaseProductVersion getDefaultTransactionIsolation getDriverName getDriverVersion getDriverMajorVersion getDriverMinorVersion getExportedKeys getExtraNameCharacters getIdentifierQuoteString getImportedKeys getIndexInfo getMaxBinaryLiteralLength getMaxCatalogNameLength getMaxCharLiteralLength getMaxColumnNameLength getMaxColumnsInGroupBy getMaxColumnsInIndex getMaxColumnsInOrderBy getMaxColumnsInSelect getMaxColumnsInTable getMaxConnections getMaxCursorNameLength getMaxIndexLength getMaxProcedureNameLength getMaxRowSize getMaxSchemaNameLength getMaxStatementLength getMaxStatements getMaxTableNameLength getMaxTablesInSelect getMaxUserNameLength getNumericFunctions getPrimaryKeys getProcedureColumns getProcedures getProcedureTerm getSchemas getSchemaTerm getSearchStringEscape getSQLKeywords getStringFunctions getSystemFunctions getTables getTableTypes getTimeDateFunctions getTypeInfo Limitations All other methods for the DatabaseMetaData interface return information about a data source based on Attunity metadata, not the backend metadata. For example, the method getTypeInfo returns the SQL data type names (BINARY, CHAR, VARCHAR, TEXT, NUMERIC, TINYINT, SMALLINT, INTEGER, FLOAT, DOUBLE, IMAGE, DATE, TIME and TIMESTAMP) rather than a DBMS-specific data type such as LONG (Oracle) or SCALED BYTE (Rdb).
Table 874 (Cont.) Supported Interfaces and Methods Supported Interface DatabaseMetaData (continued) Supported Method getURL getUserName isCatalogAtStart isReadOnly nullsAreSortedHigh nullsAreSortedLow nullsAreSortedAtStart nullsAreSortedAtEnd nullPlusNonNullIsNull storesLowerCaseIdentifiers storesLowerCaseQuotedIdentifiers storesMixedCaseIdentifiers storesMixedCaseQuotedIdentifiers storesUpperCaseIdentifiers storesUpperCaseQuotedIdentifiers supportsAlterTableWithAddColumn supportsAlterTableWithDropColumn supportsANSI92EntryLevelSQL supportsANSI92IntermediateSQL supportsANSI92FullSQL supportsCatalogsInData Manipulation supportsCatalogsInIndex Definitions supportsCatalogsInPrivilege Definitions supportsCatalogsInProcedure Calls supportsCatalogsInTableDefinitions supportsColumnAliasing supportsConvert supportsCoreSQLGrammar supportsCorrelatedSubqueries supportsDataDefinitionAndData ManipulationTransactions supportsDataManipulation TransactionsOnly supportsDifferentTable CorrelationNames supportsExpressionsInOrderBy supportsExtendedSQLGrammar supportsFullOuterJoins supportsGroupBy supportsGroupByUnrelated supportsGroupByBeyondSelect supportsIntegrityEnhancement Facility supportsLikeEscapeClause supportsLimitedOuterJoins supportsMinimumSQLGrammar supportsMixedCaseIdentifiers supportsMixedCaseQuotedIdentifiers supportsTableCorrelationNames supportsMultipleResultSets supportsMultipleTransactions supportsNonNullableColumns supportsOpenCursorsAcrossCommit supportsOpenCursorsAcrossRollback Limitations
Table 874 (Cont.) Supported Interfaces and Methods Supported Interface DatabaseMetaData (continued) Supported Method supportsOpenStatementsAcross Commit supportsOpenStatementsAcross Rollback supportsOrderByUnrelated supportsOuterJoins supportsPositionedDelete supportsPositionedUpdate supportsSchemasInDataManipulation supportsSchemasInIndexDefinitions supportsSchemasInPrivilege Definitions supportsSchemasInProcedureCalls supportsSchemasInTableDefinitions supportsSelectForUpdate supportsStoredProcedures supportsSubqueriesInComparisons supportsSubqueriesInExists supportsSubqueriesInIns supportsSubqueriesInQuantifieds supportsTableCorrrelationNames supportsTransactionIsolationLevel supportsTransactions supportsUnion supportsUnionAll usesLocalFiles usesLocalFilePerTable getConnection getLoginTimeout setLogWriter getLogWriter The following methods are supported: getActiveSize(): returns the number of connections in use. getDefaultMinPoolSize(): returns the default min pool size getDefaultMaxPoolSize: returns the default max pool size.getPoolSize(): returns the number of pool connections in the pool. These connections are available for reuse. acceptsURL connect getMajorVersion getMinorVersion getPropertyInfo jdbcCompliant getConnection close addConnectionEventListener removeConnectionEventListener The SetLoginTimeout is not supported. Limitations
DataSource2
Driver
PooledConnection
Table 874 (Cont.) Supported Interfaces and Methods Supported Interface PreparedStatement Supported Method addBatch clearBatch clearParameters close execute executeBatch executeQuery executeUpdate getMetaData setAsciiStream setBigDecimal setBinaryStream setBoolean setByte setBytes setDate setDouble setFloat setInt setLong setNull setObject setShort setString setTime setTimestamp setUnicodeStream Limitations
To insert or update TEXT and IMAGE fields (JDBC data types LONGVARCHAR and LONGVARBINARY, respectively), you must pass the data as input streams to a PreparedStatement object. Use the method setAsciiStream to set the value for a TEXT field, then call the method executeUpdate to perform an SQL INSERT or UPDATE. Use the method setBinaryStream to set the value for an IMAGE field, then call the method executeUpdate to perform an SQL INSERT or UPDATE. Additional restrictions on the retrieval or modification of TEXT and IMAGE fields may vary from one data source to another, depending on the support for BLOBs that is available in the underlying data source.
Referenceable
getReference
Table 874 (Cont.) Supported Interfaces and Methods Supported Interface ResultSet Supported Method absolute afterLast beforeFirst cancelRowUpdates clearWarnings close deleteRow findColumn first getAsciiStream getBigDecimal getBinaryStream getBoolean getByte getBytes getChapter getCharacterStream getConcurrency getDate getDouble getFetchDirection getFetchSize getFloat getInt getLong getMetaData getObject getRow getShort getStatement getString getTime getTimestamp getType getUnicodeStream getWarnings insertRow isAfterLast isBeforeFirst isFirst isLast last moveToCurrentRow moveToInsertRow next previous refreshRow relative rowDeleted rowInserted rowUpdated setFetchDirection updateAsciiStream updateBigDecimal updateBinaryStream updateBoolean updateByte updateBytes Limitations
Chapter Support: The getObject method returns a ResultSet if the type column type is java.sql.type.OTH ER and the type name is CHAPTER. Scrollable resultsets: Scrollable resultsets are supported with the JDBC driver. The type must be set to TYPE_ SCROLL_ INSENSITIVE or an error occurs. The following methods are not supported: getArray getBlob getClob setFetchSize. The following methods are only supported in JDBC version 2: absolute afterLast beforeFirst cancelRowUpdates clearWarnings deleteRow first getCharacter Stream getConcurrency getFetchDirection getFetchSize getRow getStatement getType insertRow isAfterLast isBeforeFirst isFirst isLast last moveToCurrentRow moveToInsertRow previous refreshRow relative rowDeleted rowInserted rowUpdated setFetchDirection updateAsciiStream updateBigDecimal updateBinary Stream updateBoolean
Table 874 (Cont.) Supported Interfaces and Methods Supported Interface ResultSet (continued) Supported Method updateCharacterStream updateDate updateDouble updateFloat updateInt updateLong updateNull updateObject updateRow updateShort updateString updateTime updateTimestamp wasNull Limitations updateByte updateBytes updateCharacter Stream updateDate updateDouble updateFloat updateInt updateLong updateNull updateObject updateRow updateShort updateString updateTime updateTimestamp
ResultSetMetadata
getCatalogName getColumnCount getColumnDisplaySize getColumnLabel getColumnName getColumnType getColumnTypeName getPrecision getScale getSchemaName getTableName isAutoIncrement isCaseSensitive isChapter isCurrency isDefinitelyWritable isNullable isReadOnly isSearchable isSigned isWritable
Table 874 (Cont.) Supported Interfaces and Methods Supported Interface RowSet Supported Method absolute afterLast beforeFirst cancelRowUpdates clearWarnings close deleteRow findColumn first getAsciiStream getBigDecimal getBinaryStream getBoolean getByte getBytes getChapter getCharacterStream getConcurrency getDate getDouble getFetchDirection getFetchSize getFloat getInt getLong getMetaData getObject getRow getShort getStatement getString getTime getTimestamp getType getUnicodeStream getWarnings insertRow isAfterLast isBeforeFirst isFirst isLastlast moveToCurrentRow moveToInsertRow next previous refreshRow relative rowDeleted rowInserted rowUpdated setFetchDirection setFetchSize updateAsciiStream updateBigDecimal updateBinaryStream updateBoolean updateByte Limitations Chapter Support: The getObject method returns a RowSet if the type column type is java.sql.type.OTHER and the type name is CHAPTER. Scrollable rowsets: The type must be set to TYPE_SCROLL_ INSENSITIVE or an error occurs. The following methods are not supported: getArray getBlob getClob getRef
Table 874 (Cont.) Supported Interfaces and Methods Supported Interface RowSet (continued) Supported Method updateBytes updateCharacterStream updateDate updateDouble updateFloat updateInt updateLong updateNull updateObject updateRow updateShort updateString updateTime updateTimestamp wasNull addBatch clearBatch clearWarnings close execute executeBatch executeQuery executeUpdate getMaxFieldSize getMaxRows getMoreResults getQueryTimeout getResultSet getUpdateCount getWarnings setMaxRows getXAResource getXAConnection getLoginTimeout setLogWriter getLogWriter commit end forget prepare recover rollback start isSameRM getTransactionTimeout The setLoginTimeout method is not supported. The following methods are not supported: cancel setCursorName setEscapeProcessing setMaxFieldSize setQueryTimeout3 Limitations
Statement
XAConnection XADataSource
XAResource
2 3
Isolation level dynamic changes are supported for specific data sources only. The change takes effect after a transaction is started. Also see DataSource Properties. You can use the daemon Call Timeout parameter on the server machine. However, setting this parameter will impact all client requests. Also, the server process will continue to run, even after the client has timed out.
Supported Classes
The JDBC driver also supports all of the fully implemented classes in the JDK 1.3 release or higher, listed in the following table:
Table 875
JDBC Classes Supported Methods getDataSize getIndex getParameter getRead getTransferSize toString valueOf deregisterDriver getConnection getDriver getDrivers getLoginTimeout getLogStream println registerDriver setLoginTimeout setLogStream <none> Note: There are no methods defined in the JDBC API for the DriverPropertyInfo class
date driverManager
driverPropertyInfo
SQLException
getSQLState getErrorCode getNextException setNextException getNextWarning setNextWarning toString valueOf after before equals getNanos setNanos toString valueOf <none> Notes:
types
There are no methods defined in the JDBC API for the Types class. See Data Types (JDBC and Java Type Mapping) for more information about data type mapping in the JDBC driver.
DataSource Properties
The JDBC driver supports standard properties for the DataSource (including the DataSource interface that provides connection pooling), ConnectionPoolDataSource, and XADatasource interfaces, listed in the following table:
Table 876 Property Name databaseName dataSourceName description password portNumber serverName user Type
DataSource Properties Supported Methods setDatabaseName getDatabaseName setDataSourceName getDataSourceName setDescription getDescription setPassword getPassword setPortNumber getPortNumber setServerName getServerName setUser getUser Description The name of a particular database on a server. The logical data source name. A description of this data source. The users data source password. The port that the daemon listens to. The default value is 2551. The data source server name. The users account name.
addDefaultSchema boolean
connectionString string
Table 877 (Cont.) ConnectionPool, Data Source and XADatasource Properties Property Name logLevel maxConnections maxStatements oneTdpMode passThruMode qualifySchema Type int int int boolean boolean boolean Supported Methods setLogLevel getLogLevel setMaxConnections getMaxConnections setMaxStatements getMaxStatements setOneTdpMode isOneTdpMode setPassThruMode isPassThruMode setQualifySchema isQualifySchema setWorkspace getWorkspace Description The level of logging/tracing. The maximum number of active connections. The maximum number of active statements. Sets the data source to multi/single mode. Sets the Pass Thru mode. When set to true, a schema returns the data source name as part of the schema/owner name. The daemons workspace (the default is Navigator).
workspace
string
minPoolSize
string
Table 879 (Cont.) Supported JDBC Interfaces Attunity JDBC Class NvDataSourceFactory NvDataSourceInt NvDriver NvDriverCoreBase NvPoolDataSource NvPooledConnection NvPreparedStatement NvResultSet NvResultSetMetadata NvRow NvRowSet NvRowSetListener NvRowSetMetadata NvScollableResultSet NvSerialBlob NvSerialClob NvSQLReconnectException NvSQLWarning NvStatement NvUpdateableResultSet NvXAConnection NvXADataSource NvXAException NvXAResource NvXid JDBC Interface Implemented javax.naming.spi.ObjectFactory Extended javax.sql.DataDource The driver implementation class. java.sql.Driver javax.namingReferenceable and java.io.Serializable. Addionally, it implements the NvDataSourceInt class. javax.sql.PooledConnection java.sqlPreparedStatement java.sql.ResultSet java.sqlResultSetMetadata java.io.Serializable and java.lang.Cloneable javax.sql.RowSet javax.sql.RowSetListener and java.io.Serializable javax.sql.RowSetMetadata and java.io.Serializable java.sql.ResultSet java.sql.Blob and java.io.Serializable and java.lang.Cloneable java.sql.Clob and java.io.Serializable and java.lang.Cloneable Extended java.sql.SQLException Extended java.sql.SQLWarning java.sql.Statement java.sql.ResultSet javax.sql.XAConnection javax.sql.XADataSource and java.io.Serializable Extended javax.transaction.xa.XAException javax.transaction.xa.XAResource javax.transaction.xa.Xid and java.io.Serializable
Creates a JDBC connection. Creates a prepareStatement object and sets the SQL query. Executes the query and gets the results (if any). Prints the results to the console or to a file, according to the user specification. Closes the open objects (PrepareStatement, ResultSet, Connection).
You need to provide the following parameters before the JDBC driver starts the process:
JDBC Client Interface 87-23
A user name to connect the daemon/server. Press Enter in case the Attunity daemon/server doesnt request authorization. A password to connect the daemon/server. Press Enter in case the Attunity daemon/server doesnt request authorization. An SQL query (e.g SELECT * from disam:nv_dept)
Note:
If the data source name was not specified at the data source name request, then it must be linked to the table name in the SQL query, separated with : (a colon).
/** * Title: SimpleJDBC * Description: SimpleJDBC to work with Attunity * Copyright: * Company: * @author * @version 1.0 */ import java.sql.*; import java.io.*; public class SimpleJDBC { public static void main(String args[]) { accessEns(); } private static boolean accessEns() { Connection con = null; ResultSet rs = null; PreparedStatement ps = null; int rowCount = 0; try { //Initialize the JDBC driver Class.forName("com.attunity.jdbc.NvDriver"); } catch(Exception ex) { System.out.println("failed to initialize the jdbc driver. The error msg is: \n" + ex.getMessage()); return false; } try { String url = "jdbc:attconnect://localhost;DefTdpName=Disam;"; String sUser = askUser("Please enter the user name to connect the daemon/server or press <Enter> for anonymous access: ");
String sPassword = askUser("Please enter the password to connect the daemon/server or press <Enter> for anonymous access: "); con = DriverManager.getConnection(url,sUser,sPassword); String sQuery = askUser("Enter the SELECT statement for execution: "); ps = con.prepareStatement(sQuery); rs = ps.executeQuery(); while (rs.next()) { rowCount++; String name = rs.getString(2); System.out.println("name = " + name); } System.out.println("The total rows read = " + rowCount); ps.close(); rs.close(); con.close(); System.out.println("SUCCESSS - END OF THE PROGRAM!!!"); return true; } catch(SQLException ex) { System.out.println("failed to execute the db query. The error msg is: \n" + ex.getMessage()); return false; } catch(Exception ex) { System.out.println("Exception !!!!!!!!!: " + ex.getMessage()); return false; } } /* * Prints the question onto screen and returns typed answer */ static private String askUser(String sQuestion) throws java.io.IOException { InputStreamReader isr = new InputStreamReader(System.in); char inBuf[] = new char[1000]; String sAnswer; System.out.print(sQuestion); isr.read(inBuf, 0, 999); System.out.println(); sAnswer = new String(inBuf); sAnswer = sAnswer.trim(); return sAnswer; } }
88
ODBC Client Interface
This section contains the following topics:
Connection ODBC Client Interface ODBC API Conformance Platform Specific Information Environment Variables
Connection
This section includes the following topics:
Creating an ODBC Connection Defining a DSN Defining a File DSN Connection String Parameters
Passing the DSN name, and the username and password (if required) to the application. Using the SQLDriverConnect method and providing one of the following in the connect string:
Driver=Attunity Connect Driver FileDSN=absolute_path_of_File_DSN You can add additional connection string parameters, separated with a semi colon (;). See Connection String Parameters.
(On Windows platforms) DSN=name_of_DSN where name_of_DSN is a user or system DSN. Refer to Defining a DSN for details.
Defining a DSN
Connecting to AIS Server from an ODBC application requires that you set up a Data Source Name (DSN). This section describes the ODBC Setup Wizard, which is used to define the properties for a DSN. The Attunity ODBC DSN setup supports 32-bit and 64-bit (x64 and 64-bit Itanium) Windows platforms. It can run on Windows XP and Windows Vista.
Note:
file. To open the DSN setup wizard 1. From the Start menu, select Control Panel.
2. 3. 4. 5. 6.
Open Administrative Tools. Double-click Data sources (ODBC). Select the type of DSN you want to define (a User, System or File DSN). Click Add. The Create New Data Source screen is displayed. Select Attunity Connect Driver from the list and click Next if you are defining a File DSN or User or System DSN). The Opening Page of the Attunity Connect ODBC Setup Wizard is displayed.
Name: Enter a name to identify the DSN. Description: You can enter a description for the DSN. This is optional. Server location: Select or enter a location where the Attunity Server you are working with is located. If you want to work on a specific port, enter the port number after the server name in the following format: server:port number. You can leave this field blank if you ar e working on a local server.
Ping server: Click this button to ping the server that is selected in the Server location field. The ping result is displayed in a separate window.
If you do not enter a server, the Local Authentication Page is displayed. If you enter a server location, the Remote Server Authentication Page is displayed.
User profile: Select a user profile from the list. The user profile list is taken from the user profiles that you defined for the local machine. For more information on defining a user profile, see User Profiles. If you do not enter a user profile, the default NAV profile is used. Password: The password is entered as part of the User Profile. If you want to save the password setting select the Save password check box. It is more secure to leave this check box cleared. Important: The password will not be encrypted. It is sent through the system as is.
Test Login: Click this button to try and log in to the local machine with the credentials that are entered on this page.
After you enter the information on this page, click Next to go to the Local Binding Information Page.
Binding: Select the binding that you want to use from the list. The binding list is taken from the bindings that you defined for the local machine. For more information on defining a binding, see Binding Configuration. Default data source: Select a data source from the list. The data source list is taken from the data sources that you defined for the selected binding. For more information on defining a data source, see Data Sources. You can select the following: Single data source (for schema): When you select this check box, only the default data source selected is displayed in the ODBC schema. Use this if your ODBC tool cannot handle a large catalog case or to save system resources. Virtual Database: This is automatically selected if the data source you selected is a virtual database. Batch Update passthru: Select this to bypass the query processor and send queries directly to the backend database.
Test data source: Click this to run a test on the data source. The DSN setup tries to access the data source and displays the first table. The test information is displayed in a separate window.
After you enter the information on this page, click Next to go to the Advanced Settings Page.
Login ID: Enter the login ID for the user that is accessing the server on the remote machine. Leave this information blank to allow anonymous log in to the server. Password: Enter the password for the user in that is accessing the server on the remote machine. Leave this information blank to allow anonymous log in to the server. If you want to save the password setting select the Save password check box. It is more secure to leave this check box clear. Important: The password will not be encrypted. It is sent through the system as is.
User Encryption: Select this check box if you want to use encryption. If this option is selected, enter the following information: Key name: Enter the name of the encryption password that the daemon on the server machine looks up. Key value: Enter the value for the encryption key.
Test Login: Click this button to try and log in to the remote machine with the credentials that are entered on this page.
After you enter the information on this page, click Next to go to the Remote Server Binding Page.
Server Workspace: From the list, select the workspace from the server where you are working that you want to use. The list is taken from the bindings that you defined for the remote machine. For more information on defining a binding, see Adding and Editing Workspaces. Default data source: Select a data source from the list. The data source list is taken from the data sources that you defined on the remote machine. For more information on defining a data source, see Data Sources. Local language: Select a language code page to use with the data source. The list is determined by the Windows computer available language settings. You can select the following: Use UTF-8 encoding for strings: Select this if you want to use UTF-8 encoding with the data source. If this is selected, you cannot select a different language. English will always be used. Single data source (for schema): When you select this check box, only the default data source selected is displayed in the ODBC schema. Use this if your ODBC tool cannot handle a large catalog case or to save system resources. Use remote query processor only: Select this to use an AIS query processor on a remote machine. Batch Update passthru: Select this to bypass the query processor and send queries directly to the backend database.
Test data source: Click this to run a test on the data source. The DSN setup tries to access the data source and displays the first table. The test information is displayed in a separate window.
After you enter the information on this page, click Next to go to the Advanced Settings Page.
Log file name: The name of the log file. General trace: Select this to include the general trace and time trace elements in the log file. Produce log to debug output: Select this check box to turn on the invoke debugger. This debug option is available in the debugger output window or through other free utilities. This is helpful in troubleshooting IIS and ODBC applications. Use Threading: This turn on threading. The default is no threading because using AIS threading may cause some problems when using the ODBC environment. Setting name: Select environment properties that you want to expose from the list. Click Add to add them to the environment. The selected properties are displayed in the table in the middle of this page. To remove a property from the environment, select it from the table, and click Remove. For information on these properties, see Environment Properties.
After you enter the information on this page, click Next to go to the Final Page.
Final Page
The following figure shows the ODBC Setup Wizard Final page. This page displays the configuration file with the configurations you entered in this wizard.
Figure 887 Final Page
On this page, you can select the format to display the configuration. Select the format from the Display configuration as list. You can select one of the following:
You can use this page to review the configurations. If you need to make changes, click Back and make the changes you need. You can also manually edit the configuration in any text editor. After you select the format you are working with, click Copy to clipboard. Open your text editor and paste the contents into a new file. Make your changes and save the file in the correct location. After you finish checking the configuration and are finished entering information in this wizard, click Finish to close the wizard and save all of your settings.
All the AIS connection string parameters (\binding, BindURL, Database, defaulttdp, DSNPasswords, etc.).
Environment parameters that override the values in the binding environment on the client (thin ODBC client). This is done by specifying the full environment parameter path. For example, debug/generalTrace=true. Location: Optional. In case of a thin ODBC client, specifies the thin ODBC client installation location. LocalQp: A boolean parameter. When set to true, indicates that the thin ODBC client works in localQp mode and not remoteQp, which is the default.
Notes:
Location, localQp and environment parameters are relevant ONLY for the thin ODBC client. Location and localQp parameters can also be specified in the connection string.
File DSN
Example 881
The following is an example of a File DSN, followed by code using the DSN. File DSN (located in c:\OdbcThin\DSNs\myfiledsn.dsn):
[ODBC] DRIVER=Attunity Connect Driver BindURL:panter.attunity.co.il:2551 LocalQp=true
Sample code:
/* Allocate Environment Handle */ rc = SQLAlloEnv (&hEnv); /* allocate connection handle */ rc = SQLAllocConnect (hEnv, &hConn); /* Connect */ strcpy(ConnString, "FileDSN=c:\\OdbcThin\\DSNs\myfiledsn.dsn;"); rc = SQLDriverConnect (hConn, NULL, ConnString, ConnString, szCompleteConnStr, 355, NULL, SQLDRIVER_NOPROMPT);
name: The name of the binding settings in the local repository. This provides access to all data sources defined in this binding configuration. See Editing Bindings. XML format: The binding settings in XML format. This version of the parameter defines specific data sources either locally or on a remote machine and eliminates the need to define local binding settings in the repository. Only the data sources specified for the binding are accessed. If you want to access the data sources in all the binding settings on a remote machine, use the BindURL parameter (see below).
The settings include the following: * * name: The name of a data source defined in the binding. See Editing Bindings. type: The driver used to access the data source if it resides on the client machine, or the value REMOTE if the data resides on a remote machine. If the value is REMOTE, the binding on the remote machine is updated with the values of name, connect, and Datasource and Config properties. See Editing Bindings. * connect: If the type value is a driver, this value is the connection information to the data source. If the type value is REMOTE, this value is the address of the remote machine where the data source resides and the workspace on that machine (if the default workspace is not used). * Configuration properties: Properties specific to the data source. For details, see the specific driver.
Connection string in XML format
Example 882
The following sample shows a connection to a local, demo DISAM data source:
Binding="<?xml version=1.0 encoding iso-8859-1?> <navobj> <datasource> <datasource name=demo type=add-disam readOnly=true> <config newFileLocation=D:\disam audit=true/> </datasource> </datasources> </navobj>
BindURL=[attconnect://][username:password@]host[:port][/workspa ce][&...][|...]: Specifies an AIS Server to connect to and whose data sources, defined in the binding settings on this server, are available. This parameter eliminates the need to define a local binding with entries for data sources on a server. If you want to access only a subset of the data sources on the server, use the Binding parameter (see above).
attconnect:// An optional prefix to make the URL unique when the context is ambiguous. username:password@ : An optional user ID/password pair for accessing the AIS Server. host: The TCP/IP host where the daemon resides. Both numeric form and symbolic form are accepted.
ODBC Client Interface 88-11
port: An optional daemon port number. This item is required when the daemon does not use the Sun RPC portmapper facility. workspace: An optional workspace to use. If omitted, the default workspace (Navigator) is used. & Multiple BindURLs may be specified, using an ampersand (&) as separator. Spaces between the BindURLs are not allowed. If one of the machines listed is not accessible, the connect string fails. | Multiple BindURLs may be specified, using an OR symbol (|) as separator. Spaces between the BindURLs are not allowed. The connect string succeeds as long as one of the machines listed is accessible.
A data source name may appear multiple times (for example, in the local and remote bindings). AIS resolves this ambiguity by using the first definition of any DSN and disregarding any subsequent definitions. Thus, if a DSN called SALES appears in the local binding and via the BindURL parameter, the local definition is used. When using BindURL, AIS binds upon initialization to all of the DSNs defined for the binding regardless of which DSNs are actually used (note that this may result in decreased performance). For each server specified in the BindURL connect string item, AIS automatically adds a remote machine (dynamically in memory) called BindURLn with n=1,2,, according to the order of the elements in the BindURL value. For multiple BindURLs, use the following syntax to specify a remote Query Processor to use: BindURLn=[attconnect://]. where n is the number of the BindURL specifying the remote machine whose Query Processor you want to use.
Example 883
BindURL Strings
The following string shows an AIS Server running on nt.acme.com using the Prod workspace and logging on as minny (password mouse).
BindURL=minny:mouse@nt.acme.com/prod
The following string shows an AIS Server running on nt.acme.com using the default workspace (Navigator), using port 8888 and an anonymous login.
BindURL=nt.acme.com:8888
Database: The name of a virtual database that this connection accesses. (The virtual database presents a limited view to the user of the available data such that only selected tables from either one or more data sources are available, as if from a single data source.1 For more information, see Using a Virtual Database). If set, only the virtual database can be accessed using this connect string. This property is equivalent to the Virtual Database option in the definition of a DSN (see Defining a DSN).
Attunity Federate provides the ability to view multiple data sources as a single federated data source
DefTdpName=data source: The name of the single data source you want to access as the default using this connection. Tables specified in SQL statements are assumed to be from this data source. If this parameter is not specified, then SYS is the default. For tables from any other data source, you must prefix each table name with the name of the data source, using the format: data source:tablename. Attunity Connect opens the connection in single data source mode (unless explicitly overridden by setting OneTdpMode=0, see below). This property is equivalent to the Default Data Source option in the definition of a DSN (see Defining a DSN).
DSNPasswords=data_source|machine_ alias=username/password[&data_source|machine_ alias=username/password[&]]: User profile information (username and password) granting access to a data source or remote machine via this connection. As an alternative to storing usernames and passwords in the user profile, this parameter allows you to dynamically supply one or more pairs of username and password values, with each pair assigned to a particular data source or remote machine. where:
data_source: A data source name defined in the binding configuration. machine_alias: A machine alias defined in the binding configuration. username/password: a pair of user ID and password values needed in order to access the indicated data source.
LocalQp=1|0 : Specifies that the ODBC client works in local QP mode (1) and not remote QP (0, which is the default). OneTdpMode=1|0 : Specifies whether you are working in single (1) or multiple (0) data source mode. You must explicitly set a value for OneTdpMode as well as setting a value for DefTdpName (see above), for Attunity Connect to work in single data source mode. Otherwise, the connection is opened to allow access to multiple data sources. This property is equivalent to the Single option in the definition of a DSN (see Defining a DSN).
Passthru=1|0 : Specifies whether all SQL statements that do not return rowsets during this connection will pass directly to the native RDBMS data source parameter, without any parsing normally performed by the Query Processor. Specifying 1 enables passthru mode and causes Attunity Connect to open the connection in single data source mode. This parameter can be used only if the backend data source is SQL-based. SQL executed in passthru mode behaves the same as individual PASSTHRU queries specified with the TEXT={{}} syntax; however, there is no way to override passthru mode for a particular query. Use passthru mode to issue queries that perform special processing not supported in Attunity Connect, such as ALTER TABLE and DROP INDEX. This property is equivalent to the Passthru option in the definition of a DSN (see Defining a DSN).
Note: Attunity does not recommend using this option, since it impacts on every DDL SQL statement, even if only some statements were intended.
PWD=password: Specifies the password required in order to access the user profile. For details, see Managing a User Profile in Attunity Studio. QpTdpName=server machine: Specifies the remote machine where query processing will take place. The name of this remote machine is defined in the binding configuration. SecFile=filespec: The name of an user profile other than the default (NAV). The SecFile entry is supported for backward compatibility only. As of Attunity Connect version 3.x, the UID parameter (described below) is used instead of SecFile.
UID=userID: Specifies the name of a user profile in the repository. If the user profile is not specified, the default user profile (NAV) is used.
Supported Interfaces ODBC Schema Rowsets ODBC Data Types Supported Options
Supported Interfaces
Attunity Connect supports the following ODBC interfaces:
SQLAllocEnv SQLFreeEnv SQLAllocConnect SQLFreeConnect SQLDisconnect SQLDriverConnect SQLAllocStmt SQLPrepare SQLNumParams SQLBindParameter SQLSetCursorName SQLGetCursorName SQLExecDirect SQLExecute SQLParamData SQLPutData SQLCancel
SQLTables SQLColumns SQLStatistics SQLSpecialColumns SQLProcedures SQLProcedureColumns SQLNumResultCols SQLBindCol SQLDescribeCol SQLColAttributes SQLFetch SQLGetData SQLRowCount SQLGetInfo SQLGetTypeInfo SQLSetConnectOption SQLGetConnectOption SQLSetStmtOption SQLGetStmtOption SQLTransact SQLExtendedFetch SQLGetFunctions SQLFreeStmt SQLError SQLMoreResults SQLDataSources SQLNativeSql SQLParamOptions SQLPrimaryKeys SQLForeignKeys SQLSetPos
SQL_SMALLINT SQL_TINYINT SQL_INTEGER SQL_DOUBLE2 SQL_REAL SQL_NUMERIC SQL_LONGVARBINARY (treated as a BLOB) SQL_VARCHAR SQL_LONGVARCHAR (treated as a BLOB) SQL_CHAR SQL_DATE3 SQL_TIME SQL_TIMESTAMP SQL_BINARY
Attunity Connect enables you to retrieve or modify SQL_LONGVARCHAR and SQL_ LONGVARBINARY fields, with certain restrictions. The restrictions are due primarily to the support for BLOBs available in the underlying data sources, and may vary from one data source to another. For specific details about the various data sources, see the specific driver. For example, data sources that support BLOBs may or may not support random positioning within a stream (as with the Seek method), and may or may not allow operations on partial "pieces" of a BLOB. This table lists a suggested mapping between ODBC data types and C and COBOL data types.
Table 881 Mapping Between ODBC, C, and COBOL Data Types C Data Types SQL-C-CHAR COBOL Data Type Bytes
2 3
Since the double and real data types have limited accuracy, arithmetic operations involving two doubles or two reals may be incorrect. This type is reported as "Not Supported" to the ODBC Driver Manager. However, in existing data sources, columns of this type are processed properly.
Table 881 (Cont.) Mapping Between ODBC, C, and COBOL Data Types ODBC Data Type SQL-NUMERIC (full word, no decimal point) SQL-NUMERIC (with decimal point) SQL-INTEGER SQL-SMALLINT SQL-REAL SQL-DOUBLE SQL-DATE (YYYY-MM-DD) C Data Types SQL-C-LONG SQL-C-DOUBLE SQL-C-LONG SQL-C-SHORT SQL-C-FLOAT SQL-C-DOUBLE SQL-C-DATE COBOL Data Type PIC S9(09)COMP COMP-2 PIC S9(09)COMP PIC S9(04)COMP COMP-1 COMP-2 PIC S9(04)COMP PIC 9(04)COMP PIC 9(04)COMP SQL-DATE SQL-TIME SQL-C-CHAR SQL-C-TIME PIC X(10) PIC 9(04)COMP PIC 9(04)COMP PIC 9(04)COMP SQL-TIME (HH:MM:SS) SQL-TIMESTAMP SQL-C-TIMESTAMP PIC S9(04)COMP PIC 9(04)COMP PIC 9(04)COMP PIC 9(04)COMP PIC 9(04)COMP PIC 9(04)COMP PIC 9(04)COMP SQL-TIMESTAMP (YYYY-MM-D HH:MM:S) SQL-VARCHAR SQL-LONGVARCHAR SQL-BINARY SQL-C-CHAR SQL-C-CHAR SQL-C-CHAR SQL-C-BINARY PIC X(23) PIC X(nnn) PIC X(nnn) PIC X(nnn) PIC 9(nnn) SQL-VARBINARY SQL-LONGVARBINARY SQL-TINYINT N/A N/A SQL-C-SHORT N/A N/A PIC S9(04) COMP N/A N/A 2 23 nnn nnn nnn 16 SQL-C-CHAR PIC X(08) 8 10 6 Bytes 4 8 4 2 4 8 6
Supported Options
Attunity Connect supports the following additional fInfoType displayed in the following table:
SQLGetInfo fInfo Types Data Type SQL_INFO__START Description Returns the default data source type. For example, if the default data source is an ORACLE data source, SQLGetInfo(fIinfoType = 1000) returns the string ORACLE.
Attunity Connect supports the following additional fOption displayed in the following table:
Table 883 fOption 1002 Additional fOption Types Data Type Long Description Returns TRUE if the field is a BLOB; otherwise FALSE.
Minimum Requirements of an ODBC Provider Asynchronous Execution General Information Conformance Information SQL Syntax Information
The following table lists the ODBC 2.5 APIs that are implemented by AIS Server on a Windows platform: Non-Windows Platforms: The following APIs are not implemented by the ODBC Driver manager (except for SQLGetFunctions).
Table 884 ODBC APIs Implemented on Windows Platform Conformance Level Core Core See Support for Non-C Applications on Platforms Other than Windows. Core Core Level 2 Core Core Level 1 Core Level 2 Core Core
ODBC Function SQLAllocConnect SQLAllocEnv COBOLSQLAllocEnv SQLAllocStmt SQLBindCol SQLBindParameter SQLCancel SQLColAttributes SQLColumns SQLConnect SQLDataSources SQLDescribeCol SQLDisconnect
Table 884 (Cont.) ODBC APIs Implemented on Windows Platform ODBC Function SQLDriverConnect SQLDrivers SQLError SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLForeignKeys SQLFreeConnect SQLFreeEnv SQLFreeStmt SQLGetConnectOption SQLGetCursorName SQLGetData SQLGetFunctions SQLGetInfo SQLGetStmtOption SQLGetTypeInfo SQLMoreResults SQLNumParams SQLNumResultCols SQLParamData SQLPrepare SQLPrimaryKeys SQLProcedureColumns SQLProcedures SQLPutData SQLRowCount SQLSetConnectOption SQLSetCursorName SQLSetParam SQLSetPos SQLSetStmtOption SQLSpecialColumns SQLStatistics SQLTables Conformance Level Level 1 Level 2 (implemented only in ODBC Driver Manager) Core Core Core Level 2 Core Level 2 Core Core Core Level 1 Core Level 1 Level 1 (implemented only in ODBC Driver Manager) Level 1 Level 1 Level 1 Level 2 Level 2 Core Level 1 Core Level 2 Level 2 Level 2 Level 1 Core Level 1 Core Core Level 2 Level 1 (partial) Level 1 Level 1 Level 1
Table 884 (Cont.) ODBC APIs Implemented on Windows Platform ODBC Function SQLTransact Conformance Level Core
ODBC Function SQLAllocConnect SQLAllocEnv SQLAllocStmt SQLBindCol SQLBindParameter SQLColumns SQLConnect SQLDescribeCol SQLDisconnect SQLConnect SQLError SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLForeignKeys SQLFreeConnect SQLFreeEnv SQLFreeStmt SQLGetConnectOption SQLGetData SQLGetFunctions1 SQLGetInfo SQLGetTypeInfo SQLNumParams SQLNumResultCols SQLParamData SQLPrepare SQLPrimaryKeys SQLProcedureColumns
Recommended if used by the back-end data source. Recommended if used by the back-end data source.
Table 885 (Cont.) ODBC APIs: Minimum Requirements of ODBC Provider ODBC Function SQLProcedures SQLPutData SQLRowCount2 SQLSetConnectOption3 SQLSetStmtOption4 SQLStatistics SQLTables SQLTransact
1
On a Windows platform: There is no custom implementation for this function. Attunity Connect uses the ODBC Administrator implementation, which checks for the presence of an API in a driver DLL header. The ODBC driver supplies stubs that return SQL_ERROR for all non-implemented APIs, so SQLGetFunctions returns all APIs as supported. On non-Windows platforms: There is a custom implementation for this function. 2 Unavailable for SELECT statements (returns pcrow = -1). For batch update queries, pcrow=0 indicates that there was no data to update/delete and pcrow=n indicates that n rows were affected. 3 Attunity Connect supports the following options: SQL_ACCESS_MODE, SQL_AUTOCOMMIT, SQL_TXN_ISOLATION (the supported vparams of this option is SQL_TXN_READ_COMMITTED), SQL_CURRENT_QUALIFIER (available only on a DSN in single data source mode). 4 Attunity Connect supports the following options: SQL_BIND_TYPE SQL_MAX_ROWS: Effective only in SELECT statements. SQL_CONCURRENCY: The supported vparams of this option are: SQL_CONCUR_READ_ONLY: Executes the query in read only mode. SQL_CONCUR_LOCK: Executes the query in pessimistic lock mode. SQL_CONCUR_VALUES: Executes the query in optimistic lock mode. SQL_CONCUR_ROWVER: (unsupported) Changed to SQL_CONCUR_VALUES SQL_CURSOR_TYPE: The supported vparams of this option are: SQL_CURSOR_FORWARD_ONLY SQL_CURSOR_STATIC SQL_CURSOR_KEYSET_DRIVEN: Changed to SQL_CURSOR_STATIC. SQL_CURSOR_DYNAMIC: Changed to SQL_CURSOR_STATIC. SQL_ROWSET_SIZE SQL_ASYNC_ENABLE: This option is supported only on Windows platforms.
Asynchronous Execution
Attunity Connect supports asynchronous execution enabling a query to be cancelled during execution. If more than one query is active on the same server, these queries might also be cancelled along with the query for which the cancel was issued.
General Information
This table displays the general information configured to access AIS Data sources through ODBC:
Table 886 General Information for Accessing Attunity Data Sources via ODBC Returns 0x0250
Table 886 (Cont.) General Information for Accessing Attunity Data Sources via ODBC Information Type SQL__NAME Returns On Windows: ODNAV32.DLL Non-Windows: ODNAVSHR SQL_DBMS_NAME "Attunity Connect"
Conformance Information
This table displays the conformance information configured to access AIS Data sources via ODBC:
Table 887 Conformance Information for Accessing Attunity Data Sources via ODBC Returns 0x0250 SQL_OSC_NOT_COMPLIANT SQL_OSC_CORE
Support for Non-C Applications on Platforms Other than Windows ODBC Client Interface Under CICS (z/OS Only) Sample Programs
SQLBrowseConnect SQLColAttributes SQLConnect SQLDataSources SQLDescribeCol SQLDriverConnect SQLDrivers SQLError SQLGetConnectOption SQLGetCursorName SQLGetInfo SQLNativeSql SQLSetConnectOption
Make sure that the CICS Socket Interface is enabled. You can enable this interface by issuing the following CICS command:
EZAO START CICS4
To use the CICS ODBC Interface Follow the steps below to set up use of the CICS ODBC Interface:
1. 2.
Copy the COBOL or C program to a CICS DFHRPL library. Set up CICS resource definitions for the COBOL or C program and transaction. The following JCL can be used as a template:
//ATTCSD JOB 'ATTUNITY','CSD',MSGLEVEL=1,NOTIFY=&SYSUID //STEP1 EXEC PGM=DFHCSDUP,REGION=512K, // PARM='CSD(READWRITE),PAGESIZE(60),NOCOMPAT' //STEPLIB DD DSN=<HLQ1>.SDFHLOAD,DISP=SHR //DFHCSD DD UNIT=SYSDA,DISP=SHR,DSN=<HLQ2>.CSD //OUTDD DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD *
Refer to the TCP/IP V3R2 For MVS: CICS Sockets Interface Guide. If you are not sure if the system is configured with the Socket Interface, try running the EZAC transaction. If the transaction produces a screen, you should be able to run the EZAO startup transaction. If not, see if the transaction has been defined in a group that has not been installed, for example: CEDC V TRANS(EZAC) G(*). If it is defined in a group, install that group and try running EZAO again. If not, you have to configure CICS as outlined in the above manual.
*/********************************************************************/ */* ATTUNITY ODBC CICS Definitions */ */* */ */********************************************************************/ *---------------------------------------------------------------------* * Note: Install GROUP(ATT) - CEDA IN G(ATT) * * If you are re-running this, you can uncomment the DELETE command. * *---------------------------------------------------------------------* * * Start ATTUNITY ODBC RESOURCES: * * DELETE GROUP(ATT) DEFINE PROGRAM(ATTCICSD ) GROUP(ATT) LANGUAGE(C) DATALOCATION(ANY) DE(Attunity ODBC DLL) DEFINE PROGRAM(<PROG> ) GROUP(ATT) LANGUAGE(<LANG>) DATALOCATION(ANY) DE(Attunity ODBC) DEFINE TRANSACTION(<ATTTRAN>) GROUP(ATT) PROGRAM(<PROG> ) TASKDATAL(ANY) DE(Attunity ODBC TRAN ID) LIST GROUP(ATT) * * End ATTUNITY ODBC RESOURCES * /* // 3.
Modify the JCL, as follows: * * * * * * Change the JOB card to suit the site. Change <HLQ1> to point to the CICS SDFHLOAD library. Change <HLQ2> to point to the CICS CSD dataset. Change <LANG> to the LE370 for COBOL or C for C. Change <PROG> to the COBOL or C program name. Change <ATTTRAN> to the CICS transaction name.
From CICS, install the ATT group, by issuing the following command:
CEDA IN G(ATT)
4.
Compile the COBOL or C program and link it to the NAVROOT.FIXLIB(ATTCICSS) member where NAVROOT is the high-level qualifier where AIS is installed. Move the compiled and linked module to a CICS LOAD library. For COBOL programs only: Write, as part of the program, include definitions for the COBOL ODBC interface to match the C definitions found in the attcicsh.h include file (supplied as part of the mainframe kit, in NAVROOT.INCLUDEH.H).
5. 6.
Sample Programs
AIS provides a C and COBOL sample program as a template for incorporating the CICS ODBC interface into an existing C or COBOL application. The samples are open programs which use ODBC. They accept two input parameters: SERVER and SQL.
Where:
USER:PASSWORD@ : An optional user ID/password pair for accessing the AIS. IP: The TCP/IP host where the daemon resides. Both numeric form and symbolic form are accepted. PORT: The daemon port number. This item is required when the daemon does not use the Sun RPC portmapper facility. WORKSPACE: An optional workspace to use. If omitted, the default workspace (Navigator) is used. LOG: The details that are logged:
IRPC: Generates a message in the log for each RPC operation. ODBC: Generates a message in the log for each ODBC operation. SOCKETS: Generates a message in the log for each socket operation. ALL: Generates a message in the log for each RPC, ODBC and socket operation.
CICS_QUEUE_NAME: The name of queue for output which is defined under CICS when tracing the output of the program. When not defined, the default CICS queue is used.
The SQL parameter is any valid SQL statement. There must be a space or a new line between the SERVER and the SQL parameters. Examples
ATYC SERVER=194.90.22.113:2551;LOG=ALL; SQL=SELECT * FROM NAVDEMO:NATION; ATYC is a transaction that uses the C sample.
ATCO SERVER=194.90.22.113:2551; SQL=insert into navdemo:nation values(26, 'TIMOR', 3, 'Gained independence in 2002'); ATCO is a transaction that uses the COBOL sample.
Environment Variables
The following parameters define aspects of how Attunity Connect works with ODBC applications:
enableAsyncExecuting: Enables asynchronous execution. forceQualifyTable: The catalog and table name are reported together as a single string (as DS:table_name). maxActiveConnections: The maximum number of connections that an ODBC or OLE DB application can make through Attunity Connect. The default is 0, indicating that the maximum is not set.
Note:
The greater the number of connections possible, the faster the application can run. However, other applications will run slower and each connection is counted as a license, restricting the total number of users who can access data through Attunity Connect concurrently. This is particularly the case when using MS Access as a front-end, since MS Access allocates more than one connection whenever possible.
maxActiveStatements: The value retuned for the infoType of the ODBC SQL GetInfo API. The default is 0, indicating that there is no limit on the number of active statements. procedureReturnValueName: The name of the return value parameter of a stored procedure. The default is RETURN_VALUE.
89
OLE DB (ADO) Client Interface
This section includes the following topics:
Overview Methods and Properties ADO Connect String Optimizing ADO ADO Schema Recordsets OLE DB Data Types OLE DB Properties
Overview
OLE DB is Microsoft's low-level interface to data across the organization including relational and non-relational databases, e-mail and file systems. OLE DB is an open specification designed to build on the success of ODBC, by providing an open standard for accessing all sorts of data.
Table 891 (Cont.) ADO Objects, Methods, and Properties Object Connection Methods Supported BeginTrans Close CommitTrans Execute Open OpenSchema RollbackTrans Properties Supported Attributes ConnectionString ConnectionTimeout CursorLocation DefaultDatabase IsolationLevel Mode Provider State Version Error Description HelpContext HelpFile NativeError Number Source SQLState Field AppendChunk GetChunk ActualSize Attributes DefinedSize Name NumericScale Optimize OriginalValue Precision Type Value Parameter Append AppendChunk Delete Item Refresh Attributes Count Direction Name NumericScale Precision Size Type Value UnderlyingValue Properties Not Supported CommandTimeout
Table 891 (Cont.) ADO Objects, Methods, and Properties Object Property Methods Supported Item Refresh Properties Supported Attributes Count Name Type Value Version RecordSet2 AddNew CancelUpdate Clone Close CompareBookmarks Delete GetRows GetString Move MoveFirst MoveLast MoveNext MovePrevious Open NextRecordset Requery Save Supports Update UpdateBatch
1
AbsolutePosition ActiveConnection BOF Bookmark CacheSize CursorLocation CursorType DataMember DataSource EditMode EOF Filter LockType MarshalOptions RecordCount Sort Source State Status StayInSync
You must qualify the command text with the data source name (for example, oCmd.CommandText = sqlsrv:storedproc0). The following methods are not supported: CancelBatch, Next, Resync.
Notes The setting for the CacheSize property (indicating the number of records from an ADO Recordset object that are cached locally) should be equivalent to the value of the <oledb maxHRows> AIS Server environment property. The smaller of the two is used in practice. For example, if the ADO CacheSize property is set to 100 and the <oledb maxHRows> environment property set to 50, only 50 rows are retrieved at a time.
AIS returns cursor type adOpenStatic when adOpenKeyset or adOpenDynamic is specified for the CursorType property. AIS returns adXactReadCommitted for the IsolationLevel property. This property is read-only.
where UDL_filename is the full path of the UDL file. Alternatively, you can use the following format:
connection.Open "provider=AttunityConnect [;parameter=value[;parameter=value]...]"
The following connect string specifies AIS Server as the data provider and uses all the AIS Server defaults (such as the location of binding information and the default user profile).
connection.Open "provider=AttunityConnect"
The following connect string additionally specifies both the binding and the user profile:
connection.Open "provider=AttunityConnect; binding=production; User ID=QAsmith;password=asdfaa"
Binding=name|XML_format: Specifies the data source connection information. Where: name: The name of the binding configuration in the local repository. This provides access to all data sources defined in this binding configuration. For more information, see Binding Configuration. XML format: The binding configuration in XML format. This parameter defines specific data sources and eliminates the need to define a local binding configuration in the repository. Only the data sources specified for the binding are accessed. If you want to access the data sources in all the binding configurations on a remote machine, use the BindURL parameter (see below). The settings include the following:
name: The name of a data source. For more information, see Binding Configuration.
type: The driver used to access the data source if it resides on the client machine, or the value REMOTE if the data resides on a remote machine. If the value is REMOTE, the binding on the remote machine is updated with the values of name, data source type and configuration properties. connect: If the type value is a driver, this value is the connection information to the data source. If the type value is REMOTE, this value is the address of the remote machine where the data source resides and the workspace on that machine (if the default workspace is not used). Configuration properties: Properties specific to the data source driver. For details, see the specific data source driver.
Sample Connection
Example 892
The following shows a connection to a local demo DISAM data source, via ADO:
connection.Open "provider=AttunityConnect; Binding="<?xml version=1.0 encoding=iso-8859-1?> <navobj><datasources><datasource name=demo type=add-disam readOnly=true><config newFileLocation=D:\disam audit=true/> </datasource></datasources></navobj>""
BindURL=[attconnect://][username:password@]host[:port][/workspa ce][&...][|...]: Specifies an AIS Server and which data sources, defined in a binding configuration on this server, are available. This parameter eliminates the need to define a local binding with entries for data sources on a server. If you want to access only a subset of the data sources on the server, use the Binding parameter (see above). The settings include the following:
attconnect:// An optional prefix to make the URL unique when the context is ambiguous. username:password@: An optional user ID/password pair for accessing the AIS Server. host: The TCP/IP host where the daemon resides. Both numeric form and symbolic form are accepted. port: An optional daemon port number. This item is required when the daemon does not use the Sun RPC portmapper facility. workspace: An optional workspace to use. If omitted, the default workspace (Navigator) is used. & Multiple BindURLs may be specified, using an ampersand (&) as separator. Spaces between the BindURLs are not allowed. If one of the machines listed is not accessible, the connect string fails. | Multiple BindURLs may be specified, using an OR symbol (|) as separator. Spaces between the BindURLs are not allowed. The connect string succeeds as long as one of the machines listed is accessible.
A data source name may appear more than once. AIS resolves this ambiguity by using the first definition of any DSN and disregarding any subsequent definitions. Thus, if a DSN called SALES appears in the local binding and via the BindURL parameter, then the local definition is used. When using BindURL, AIS Server binds upon initialization to all of the DSNs defined for the binding regardless of which DSNs are actually used. (Note that this may result in decreased performance.) For each server specified in the BindURL connect string item, AIS Server automatically adds a remote machine (dynamically in memory) called BindURLn with n=1,2,, according to the order of the elements in the BindURL value. For multiple BindURLs, use the following syntax to specify a remote Query Processor to use: BindURLn=[attconnect://]. where n is the number of the BindURL specifying the remote machine whose Query Processor you want to use.
Example 893
The following string shows an AIS Server running on nt.acme.com using the default workspace (Navigator), the portmapper and an anonymous login.
ADO connection.Open "provider=AttunityConnect;BindURL=nt.acme.com"
The following string shows an AIS Server running on nt.acme.com using the Prod workspace and logging on as minny (password mouse).
BindURL=minny:mouse@nt.acme.com/prod
The following string shows an AIS Server running on nt.acme.com using the default workspace (Navigator), using the port 8888 and an anonymous login.
BindURL=nt.acme.com:8888
Database: The name of a virtual database that this connection accesses. The virtual database presents a limited view to the user of the available data such that only selected tables from either one or more data sources are available, as if from a single data source. For more information, see Using a Virtual Database. If set, only the virtual database can be accessed using this connect string.
defaulttdp=data source: The name of the single data source you want to access as the default using this connection. Tables specified in SQL statements are assumed to be from this data source. If this parameter is not specified, SYS is the default; for tables from any other data source, you must prefix each table name with the name of the data source, using the format data source:tablename. Specifying defaulttdp is equivalent to setting the DefaultDatabase property in ADO or the Default Data Source option in a UDL connecting to AIS Server.
DSNPasswords=data_source|machine_ alias=username/password[&data_source|machine_
alias=username/password[&]]: User profile information (username and password) granting access to a data source or remote machine via this connection. As an alternative to storing usernames and passwords in the user profile, this parameter allows you to dynamically supply one or more pairs of username and password values, with each pair assigned to a particular data source or remote machine. where:
data_source: A data source name defined in the binding configuration For more information, see Binding Configuration. machine_alias: A machine alias defined in the binding configurationFor more information, see Binding Configuration. username/password: A pair of user ID and password values needed in order to access the indicated data source.
Env-prop=value[,Env-prop=value[,Env-prop=value]...]: Environment values that override the values in the binding environment on the client. where Env-prop is the name of the environment property. For information on these parameters see Environment Properties. Example3
Example 894
The following string sets the value of the noHashJoin parameter to true, disabling the hash join mechanism during query optimization.
<optimizer noHashJoin="true"/>
Operating_Mode=1|0: Specifies whether all SQL statements that do not return rowsets during this connection will pass directly to the native RDBMS data source parameter, without any parsing normally performed by the Query Processor. Specifying 1 enables passthru mode and causes AIS to open the connection in single data source mode. This parameter can be used only if the backend data source is an SQL-based driver. SQL executed in passthru mode behave the same as individual passthru queries specified with the TEXT={{}} syntax; however, there is no way to override passthru mode for a particular query. Use passthru mode to issue queries that perform special processing not supported in AIS, such as alter table and drop index.
Note: Attunity does not recommend using this option, since it impacts on every DDL SQL statement, even if only some statements were intended.
Also see For all SQL During a Session. Specifying operating_mode is equivalent to setting the passthru option in a UDL used to connect to AIS Server. Also refer to Passthru SQL.
Password=password: Specifies the password required in order to access the user profile. For more information, see Managing a User Profile in Attunity Studio.
When using ADO, to prompt the user for the correct password via a dialog box, use the ADO adPromptAlways attribute of the Properties method, as follows: connection.Properties("Prompt")=adPromptAlways Specify this line before the Open method. When the user tries to connect, a dialog box requesting the password is always displayed.
SecFile=filespec: The name of an user profile other than the default (NAV). The SecFile entry is supported for backwards compatibility only. As of AIS version 3.x, the User ID parameter (described below) is used instead of SecFile.
User ID=userID: Specifies the name of a user profile in the repository. If the user profile is not specified, the default user profile (NAV) is used.
Optimizing ADO
By reusing the same ADO command, you save time needed to create the ADO object, making execution faster. To reuse commands you must use a transaction as an envelope around the commands. You can reuse commands for INSERT and SELECT statements whenever SQL is repeated, with different parameter values for each iteration of the SQL. Reusing commands for UPDATE and DELETE statements works only with non-relational data sources. The following code shows how to reuse code to insert rows into a table. Two methods are shown: the first method inserts rows via parameters and the second method uses constants. The second method is translated internally to be the same as the first method and is thus a little slower. Using either method is a matter of preference. Using constants works only for INSERT statements and not for SELECT statements.
Dim Dim Dim Dim conn As ADODB.Connection com As ADODB.Command dept_id(10) As String dept_budget(10) As Double for the new rows "DP11" "DP12" "DP13" "DP14" "DP15" "DP16" = = = = = = 11 22 33 44 55 66
On Error GoTo Error_Handler Set conn = New ADODB.Connection conn.Provider = "AttunityConnect" conn.Open NOTE: 1. It is important to use a transaction in order
to enable the reuse. 2. All the ADO commands to reuse must be created within this transaction. conn.BeginTrans Two methods for efficient insertion of rows. Each method inserts 3 rows in a loop to the dept table 1. Same command, reusing executed state, using parameters. =========================================================== Set com = New ADODB.Command Set com.ActiveConnection = conn com.CommandType = adCmdText We set the command text once and reuse it. com.CommandText = "insert into dept values (?,?)" com.Parameters.Append com.CreateParameter("p0", adChar, adParamInput, 4) com.Parameters.Append com.CreateParameter("p1", adDouble, adParamInput, 0) Insert 3 new rows For i = 1 To 3 com.Parameters(0) = dept_id(i) com.Parameters(1) = dept_budget(i) com.Execute There is no need to create a new command or even to set text again in every iteration. Next i cleanup Set com = Nothing 2. Same command, reusing executed state, using constants. ========================================================= Set com = New ADODB.Command Set com.ActiveConnection = conn com.CommandType = adCmdText We dont create a new command for every iteration, just set the new command text Insert additional 3 new rows For i = 4 To 6 com.CommandText = "insert into dept values (" & dept_id(i) & "," &dept_budget(i) & ")" com.Execute Next i cleanup Set com = Nothing Finish
conn.CommitTrans conn.Close Exit Sub Error_Handler: If conn.Errors.count > 0 Then MsgBox conn.Errors.Item(0).Source & " : " & conn.Errors.Item(0).Description End If conn.RollbackTrans conn.Close End Sub
adSchemaCatalogs adSchemaColumns adSchemaForeignKeys adSchemaIndexes adSchemaPrimaryKeys adSchemaProcedures adSchemaProcedureColumns adSchemaProviderTypes adSchemaStatistics adSchemaTables
DBTYPE_I1 DBTYPE_UI1 DBTYPE_I2 DBTYPE_I4 DBTYPE_R4 DBTYPE_R8 DBTYPE_STR DBTYPE_WSTR DBTYPE_BYTE DBTYPE_NUMERIC DBTYPE_DECIMAL DBTYPE_DBDATE
DBTYPE_DBTIME DBTYPE_DBTIMESTAMP
The following table lists the mapping between Attunity AIS data types and ADO data types:
Table 892 AIS Datatype ID DT_TYPE_B_ DT_TYPE_BU_ DT_TYPE_W_ DT_TYPE_L_ DT_TYPE_WU_ DT_TYPE_F_ DT_TYPE_G_ DT_TYPE_STRING_ DT_TYPE_CSTRING_ DT_TYPE_VT_ DT_TYPE_FIXED_CSTRING_ DT_TYPE_VT4_ DT_TYPE_STR_TIME_ DT_TYPE_STR_DATE_ DT_TYPE_STR_DATETIME_ DT_TYPE_PADDED_STR_TIME DT_TYPE_PADDED_STR_DATE_ DT_TYPE_PADDED_STR_DTAETIME_ DT_TYPE_VAR_UNICODE1_ DT_TYPE_VAR_UNICODE2_ DT_TYPE_VAR_UNICODE4_ DT_TYPE_UNICODE_STRING_ DT_TYPE_UNICODE_CSTRING_ DT_TYPE_Z_ DT_TYPE_VB1_ DT_TYPE_VB2_ DT_TYPE_VB4_ DT_TYPE_NUMERIC_CSTRING_ DT_TYPE_Q_ DT_TYPE_OLE_NUMERIC_ DT_TYPE_NRO_ DT_TYPE_LU_ DT_TYPE_NLO_ AIS and ADO Data Type Mapping AIS Datatype Name int1 uint1 int2 int4 uint2 single double string cstring varstring fixed_cstring varstring4 str_time str_date str_datetime padded_str_time padded_str_date padded_str_datetime varunicode1 varunicode2 varunicode4 unicode_string unicode_cstring unspecified varbunary1 varbinary2 varbinary4 numeric_cstring int8 ole_numeric numstr_s uint4 numstr_nlo OLE DB Datatype DBTYPE_I1 DBTYPE_UI1 DBTYPE_I2 DBTYPE_I4 DBTYPE_I4 DBTYPE_R4 DBTYPE_R8 DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_STR DBTYPE_WSTR DBTYPE_WSTR DBTYPE_WSTR DBTYPE_WSTR DBTYPE_WSTR DBTYPE_BYTES DBTYPE_BYTES DBTYPE_BYTES DBTYPE_BYTES DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_NUMERIC
Table 892 (Cont.) AIS and ADO Data Type Mapping AIS Datatype ID DT_TYPE_NL_ DT_TYPE_NR_ DT_TYPE_OLE_DECIMAL_ DT_TYPE_ODBC_DATE_ DT_TYPE_BD400_TIME_ DT_TYPE_ODBC_TIME_ DT_TYPE_DB400_DATETIME_ DT_TYPE_ODBC_TIMESTAMP_ DT_TYPE_TIME_ DT_TYPE_OLE_DATE_ DT_TYPE_DB400_DATE_ AIS Datatype Name numstr_nl numstr_nr ole_decimal odbcDate db400_time time db400_datetime timestamp apt_time ole_date db400_date OLE DB Datatype DBTYPE_NUMERIC DBTYPE_NUMERIC DBTYPE_DECIMAL DBTYPE_DBDATE DBTYPE_DBTIME DBTYPE_DBTIME DBTYPE_DBTIMESTAMP DBTYPE_DBTIMESTAMP DBTYPE_DBTIMESTAMP DBTYPE_DBTIMESTAMP DBTYPE_DBTIMESTAMP
The drivers for specific data providers map the data source-specific data types to the above data types. SQL data types are supported through the CREATE TABLE statement. The data type conversion rules are documented in the OLE DB Programmer's Reference. You can retrieve or modify text and image fields, with certain restrictions. The restrictions are due primarily to the support for BLOBs available in the underlying data sources, and may vary from one data source to another. For example, data sources that support BLOBs may or may not support random positioning within a stream (as with the SEEK method), and may or may not allow operations on partial "pieces" of a BLOB. The following restrictions of the implementation of text and image fields apply to the OLE DB interface:
IStream:CopyTo and IStream:Clone are not supported. For data providers that support IStream::Seek functionality, the STREAM_ SEEK_END parameter value is not supported. Transacted BLOBs are not supported.
Table 893 (Cont.) Supported OLE DB Interfaces and Methods Interface ILockBytes (OLE) Methods Flush ReadAt SetSize Stat WriteAt IMultipleResults IOpenRowset IPersist (OLE) IRowset GetResult OpenRowset GetClassID AddRefRows GetData GetNextRows ReleaseRows RestartPosition IRowsetChange DeleteRows InsertRow SetData IRowsetIdentity IrowSetInfo IsSameRow GetProperties GetReferenceRowset GetSpecification IRowsetLocate Compare GetRowsAt GetRowsByBookmark Hash IRowsetUpdate GetOriginalData GetPendingRows GetRowStatus Undo Update ISequentialStream Read Write ISessionProperties GetProperties SetProperties IStream (OLE) Read Seek SetSize Stat Write ISupportErrorInfo InterfaceSupportsErrorInfo
Table 893 (Cont.) Supported OLE DB Interfaces and Methods Interface ITransaction Methods Abort Commit GetTransactionInfo ITransactionJoin ITransactionLocal JoinTransaction StartTransaction
OLE DB Properties
This section lists the supported OLE DB properties. These properties belong to one of the following categories:
DBPROPSET_DBINIT initialization properties. DBPROPSET_DATASOURCE data source properties. DBPROPSET_DATASOURCEINFO data source information properties. DBPROPSET_SESSION session properties. DBPROPSET_ROWSET rowset properties.
Initialization Properties
The DBPROPSET_DBINIT property set contains the properties listed below. Providers can define additional initialization properties.
Table 894 Property Name DBPROP_AUTH_PASSWORD DBPROP_AUTH_USERID DBPROP_INIT_DATASOURCE DBPROP_INIT_MODE DBPROP_INIT_TIMEOUT DBPROP_INIT_HWND DBPROP_INIT_PROVIDERSTRING DBPROP_INIT_PROMPT DBPROP_INIT_OLEDBSERVICES DBPROP_INIT_CATALOG Initialization Properties Permission Read/Write Read/Write Read/Write Read/Write Read/Write Read/Write Read/Write Read/Write Read/Write Read/Write "SYS" 999 0 0 "" DBPROMPT_NOPROMPT 0xffffffff "" Default
Table 896 (Cont.) Data Source Information Properties Property Name DBPROP_PREPAREABORTBEHAVIOR DBPROP_PREPARECOMMITBEHAVIOR DBPROP_PROCEDURETERM DBPROP_PROVIDERFILENAME DBPROP_PROVIDEROLEDBVER DBPROP_PROVIDERVER DBPROP_QUOTEDIDENTIFIERCASE DBPROP_ROWSETCONVERSIONONCOMMAND DBPROP_SCHEMATERM DBPROP_SCHEMAUSAGE DBPROP_SQLSUPPORT Permission Default Read Read Read Read Read Read Read Read Read Read Read DBPROPVAL_CB_reserve DBPROPVAL_CB_reserve "STORED_PROCEDURE" "NAV32.DLL" "2.0" "04.60.0000" DBPROPVAL_IC_SENSITIVE TRUE "OWNER" 0 DBPROPVAL_Sql_ANSI92_ENTRY DBVPROPVAL_SQL_ODBC_MINIMUM DBPROPVAL_SQL_ODBC_MINIMUM DBPROP_STRUCTUREDSTORAGE Read DBPROPVAL_Ss_ISTREAM DBPROPVAL_SS_ISEQUENTIALSTREAM DBPROP_SUBQUERIES Read DBPROPVAL_SQ_CORRELATEDSUBQUERIES DBPROPVAL_SQ_COMPARISON DBPROPVAL_SQ_EXISTS DBPROPVAL_SQ_IN DBPROPVAL_SQ_QUANTIFIED DBPROP_SUPPORTEDTXNDDL DBPROP_SUPPORTEDTXNISOLEVELS DBPROP_SUPPORTEDTXNISORETAIN DBPROP_TABLETERM Read Read Read Read DBPROPVAL_TC_ALL DBPROPVAL_TI_READCOMMITTED DBPROPVAL_TR_DONTCARE "TABLE"
Session Properties
The DBPROPSET_SESSION property set contains the following property:
Table 897 Property Name DBPROP_SESS_AUTOCOMMITISOLEVELS Session Properties Permission Read Default DBPROPVAL_TI_READCOMMITTED
Rowset Properties
The DBPROPSET_ROWSET property set contains the properties listed below. Providers can define additional rowset properties:
Table 898 Property Name DBPROP_ABORTPREERVE DBPROP_BLOCKINGSTORAGEOBJECT Rowset Properties Permission Read Read Default FALSE FALSE
Table 898 (Cont.) Rowset Properties Property Name DBPROP_BOOKMARKS DBPROP_BOOKMARKSKIPPED DBPROP_BOOKMARKTYPE DBPROP_CANFETCHBACKWARD DBPROP_CANHOLDROWS DBPROP_CANSCROLLBACKWARD DBPROP_CHANGEINSERTEDROWS DBPROP_COLUMNRESTRICT DBPROP_COMMANDTIMEOUT DBPROP_COMMITPRESERVE DBPROP_DEFERRED DBPROP_DELAYSTORAGEOBJECTS DBPROP_IMMOBILEROWS DBPROP_LITERALBOOKMARKS DBPROP_LITERALIDENTITY DBPROP_MAXOPENROWS DBPROP_MAXPENDINGROWS DBPROP_MAXROWS DBPROP_MEMORYUSAGE DBPROP_ORDEREDBOOKMARKS DBPROP_MULTIPLEPARAMSETS DBPROP_MULTIPLERESULTS DBPROP_MULTIPLESTORAGEOBJECTS DBPROP_MULTITABLEUPDATE DBPROP_OLEOBJECTS DBPROP_ORDERBYCOLUMNSINSELECT DBPROP_OUTPUTPARAMETERAVAILABILITY DBPROP_PERSISTENTIDTYPE DBPROP_PREPAREABORTBEHAVIOR DBPROP_PREPARECOMMITBEHAVIOR DBPROP_PROCEDURETERM DBPROP_PROVIDERFILENAME DBPROP_PROVIDEROLEDBVER DBPROP_PROVIDERVER DBPROP_QUOTEDIDENTIFIERCASE DBPROP_ROWSETCONVERSIONONCOMMAND DBPROP_SCHEMATERM Permission Read/Write Read Read Read Read Read/Write Read Read Read/Write Read Read Read/Write Read Read/Write Read Read Read Read Read Read/Write Read Read Read Read Read Read Read Read Read Read Read Read Read Read Read Read Read Default FALSE FALSE DBPROPVAL_BMK_NUMERIC FALSE TRUE FALSE TRUE TRUE 0 FALSE FALSE FALSE TRUE FALSE TRUE 100 100 0 0 FALSE FALSE DPPROPVAL_MR_SUPPORTED TRUE FALSE DPPROPVAL_OO_BLOB FALSE DBPROPVAL_OA_NOTSUPPORTED DBPROPVAL_PT_NAME DBPROPVAL_CB_reserve DBPROPVAL_CB_reserve "STORED_PROCEDURE" "NAV32.DLL" "2.0" "04.60.0000" DBPROPVAL_IC_SENSITIVE TRUE "OWNER"
Table 898 (Cont.) Rowset Properties Property Name DBPROP_SCHEMAUSAGE DBPROP_SQLSUPPORT Permission Read Read Default 0 DBPROPVAL_Sql_ANSI92_ENTRY DBVPROPVAL_SQL_ODBC_MINIMUM DBPROPVAL_SQL_ODBC_MINIMUM DBPROP_STRUCTUREDSTORAGE Read DBPROPVAL_Ss_ISTREAM DBPROPVAL_SS_ISEQUENTIALSTREAM DBPROP_SUBQUERIES Read DBPROPVAL_SQ_CORRELATEDSUBQUERIES DBPROPVAL_SQ_COMPARISON DBPROPVAL_SQ_EXISTS DBPROPVAL_SQ_IN DBPROPVAL_SQ_QUANTIFIED DBPROP_SUPPORTEDTXNDDL DBPROP_SUPPORTEDTXNISOLEVELS DBPROP_SUPPORTEDTXNISORETAIN DBPROP_TABLETERM Read Read Read Read DBPROPVAL_TC_ALL DBPROPVAL_TI_READCOMMITTED DBPROPVAL_TR_DONTCARE "TABLE"
Specific Properties
Attunity AIS includes the following specific properties:
Table 899 Property Name ISGPROP_DEFTDP_TYPE1 ISGPROP_PASSTHROUGH_MODE2 Specific Properties Permission Read Read/Write NULL string Default
Notes:
The ISGPROP_DEFTDP_TYPE property returns the default data source type. For example, if the default data source is an ORACLE data source, then this property returns the string "ORACLE". The ISGPROP_PASSTHROUGH_MODE property sets the AIS Query Processor to passthru mode. For more information, see Passthru SQL.
90
XML Client Interface
This section contains the following topics:
Overview of the XML Client Interface ACX Verbs Setting XML Transports for AIS
ACX Request and Response Documents Connection Verbs Transaction Verbs The Execute Verb Metadata Verbs The Ping Verb The Exception Verb
XML request and response documents can be passed between the application and AIS via the TCP/IP or (over the web) HTTP transport.
ACX Verbs
This section contains the following:
Connection Verbs Transaction Verbs The Execute Verb Metadata Verbs The Ping Verb The Exception Verb
Request Document
The general format for an ACX request document is as follows:
<?xml version="1.0" ?> <acx type="request" id="request_id"> ...acx_verbs... </acx>
The id attribute is used for matching the ACX document with its response document. The server does not use the id attribute value other than in sending it back along with the response document.
Response Document
The general format of an ACX response document is as follows:
<?xml version="1.0" ?> <acx type="response" href="request_id"> ... </acx>
The href attribute is used for matching the ACX response document with its request document (matching with the id attribute).
Connection Verbs
ACX defines XML format for the following verbs that handle the connect and connection context for an ACX request:
The Connect Verb The setConnection Verb The disconnect Verb The reauthenticate Verb The cleanConnection Verb
Transient Connections Transient connections are created for use within a single ACX request. A transient connection is disconnected when an ACX request ends, or when the connection context changes (that is, with the connect, setConnection or disconnect verbs).
Persistent Connections Persistent connections can persist across multiple ACX requests or connection context changes. Persistent connection are disconnected upon an explicit disconnect verb or when a connection idle timeout expires.
where:
adapter (string): Name of adapter with which to associate the connection. You can use the following syntax to set this adapter to run on a particular workspace:
<connect adapter="workspace/adapter_name" ... />
where:
workspace: The name of the workspace where the adapter runs. adapter_name: The name of the adapter.
idleTimeout (number): A per-connection client idle timeout setting (seconds). If the client does not use the connection for the specified amount of time, the connection will be disconnect by the server and its associated resources released. This setting is limited by the server side maximum idle connection timeout setting. This parameter represents a common behavior within application servers limiting the amount of time a resource can be tied up by a client. persistent (boolean): Persistent connection indication. If True, a persistent connection is created. Otherwise a transient connection is created. The default is False. passwordAuthenticator: The authentication information required by the resource adapter of the client that created the connection. The kind of authentication information required by the resource adapter is returned as a part of the resource adapter metadata. The definition for the authentication information used for passwordAuthenticator is shown above within the syntax.
90-3
Response The connect verb matching response is only generated for a persistent connection. It is defined as follows:
<connectResponse connectionId="connection_id" idleTimeout="idle_timeout" />
where:
connectionId (string): A connection ID value representing the newly created connection. idleTimeout (number): The actual idle timeout (seconds) in effect for the new connection. This is determined by the server, possibly overriding the setting on the client.
client.noSuchResource: The requested adapter (or workspace) is not available on the server. server.redirect: The resource adapter is available on a different server whose details are given. The same ACX request should be directed at that server. The scope of the redirection is only guaranteed for its first use. This means that if you get a redirect, you should connect to the named server and use it. Once you work with the socket and hold it, you can continue to connect to the server (assuming you used a persistent connection). Later on, connecting to the redirected server may or may not work. In many cases, once you get a physical connection, you maintain it open and open a new one only if the connection is dropped (for example, by a connection idle timeout), at which time you will need to ask the daemon for a new one.
Example
<?xml version="1.0" encoding="UTF-8"?> <acx type="request" id="try0001"> <connect adapter="adapter_name"> <passwordAuthenticator username="scott" password="tiger"/> </connect> </acx>
where: connectionId (string): A connection ID value, returned by a persistent previous connect verb. The setConnection verb does not generate a response. Exceptions The following exceptions may result from a setConnection verb:
client.noSuchConnection: The given connection is either invalid (was not acquired via a connect verb) or represents a timed out connection. server.internalError: An error occurred on the server. *: Other, adapter specific, setConnection exceptions.
Example
<?xml version="1.0" encoding="UTF-8"?> <acx type="request" id="try001"> <connect adapter="adapter_name" persistent="true"> <passwordAuthenticator username="scott" password="tiger"/> </connect> </acx> <?xml version="1.0" encoding="UTF-8"?> <acx type="response" href="try001"> <connectResponse connectionID="39275569"/> </acx> <?xml version="1.0" encoding="UTF-8"?> <acx type="request"> <setConnection connectionID="39275569"/> </acx>
The disconnect verb does not generate a response. Exceptions The following exceptions may result from a disconnect verb: server.internalError: An error occurred on the server.
90-5
authentication). Once the reauthentication succeeds, the connection's client is authorized based upon the authenticated identity established. Syntax
<reauthenticate> <passwordAuthenticator username="username" password="password" /> </reauthenticate>
where:
username: The username of the new client of the connection. password: The password of the new client of the connection.
The reauthenticate verb does not generate a response. Exceptions The following exceptions may result from a reauthenticate verb:
client.authenticationError: The given authentication information is not valid. server.notImplemented: The adapter does not support reauthentication. server.internalError: An internal error has occurred.
Note that the adapter may forget the authentication information upon a cleanConnection verb. This behavior is reflected in the adapter metadata. The cleanConnection verb does not generate a response.
Transaction Verbs
The ACX transaction verbs are used in the following scenarios:
Non-transacted operation: The adapter works in auto-commit mode. Work is committed immediately and automatically upon execution. This operation mode is the default operation mode when no transaction verbs are used, or with the setAutoCommit verb setting auto-commit to True. Local transaction operation: With auto-commit set to False, the first interaction starts a transaction that lasts until an explicit commit (using the transactionCommit verb) or an explicit rollback (using the transactionRollback verb) occurs. All interactions performed in between are made as a part of that transaction. Note that 'local' is used here to indicate the scope of the transaction, rather than its location - using ACX, the local transaction may be running on a remote machine.
Distributed transaction operation: The ACX adapter participates in a distributed transaction by exposing the appropriate XA methods. In this scenario, the responsibility for invoking the different ACX verbs is divided between the application component (performing the interactions) and the application server (which, by means of the transaction manager, manages the transaction and performs the 2-phase-commit protocol).
The setAutoCommit Verb The transactionStart Verb The transactionPrepare Verb The transactionCommit Verb The transactionRollback Verb The transactionRecover Verb The transactionForget Verb The transactionEnd Verb
where:
autoCommit (boolean): New auto-commit mode of the connection. If set to True, each interaction immediately commits once executed. The auto-commit mode must be turned off if multiple interactions need to be grouped into a single transaction and committed or rolled back as a unit. When auto-commit is reset and no global transaction is in progress, any interaction starts a local transaction. The client is required to use transactionCommit or transactionRollback at the appropriate time to commit or rollback the transaction. The auto-commit mode is True by default and is reset if a distributed (global) transaction is started.
The setAutoCommit verb does not generate a response. Exceptions The following exception may result from a setAutoCommit verb: server.internalError: An error occurred on the server.
</transactionStart>
where:
xid: A global transaction identifier, automatically assigned. If not given (or empty), the transaction is assumed to be local. The xid comprises the following:
formatID (number): Specifies the format of the xid. globalTransactionID (hex string): Defines the transaction ID. The value must be less than 128. branchQualifier (hex string): Defines the transaction branch. The value must be less than 128.
state (string): The state of the given xid. May be "join", "resume" or empty. If the state is empty the it assumed that the transaction is new.
The transactionStart verb does not generate a response. Exceptions The following exceptions may result from a transactionStart verb:
INTRANS: A transaction is already started. UNKXID: An unknown xid was specified with transaction state of "join" or "resume". INTERR: An internal error has occurred.
where: xid: The global transaction identifier passed by the transactionStart xid. The transactionPrepare verb does not generate a response. Exceptions The following exceptions may result from a transactionPrepare verb:
NOTRANS: No matching global transaction is started. UNKXID: An unknown xid was specified. INTERR: An internal error has occurred.
Syntax
<transactionCommit onePhase=one_phase> <xid formatID="id" globalTransactionID="id_string" branchQualifier="branch_string" /> </transactionCommit>
where:
onePhase (boolean): Specifies that the resource adapter should use a one-phase commit protocol to commit the work done on the client's behalf. onePhase is applicable only when the transaction is a global transaction and includes a 1-phase commit data source. If true, this option may be used by the transaction manager to optimize its distributed transaction processing. xid: The global transaction identifier passed by the transactionStart xid.
The transactionCommit verb does not generate a response. Exceptions The following exceptions may result from a transactionCommit verb:
NOTRANS: No matching global transaction is started. UNKXID: An unknown xid was specified. INTERR: An internal error has occurred.
where: xid: The global transaction identifier passed by the transactionStart xid. The transactionRollback verb does not generate a response. Exceptions The following exceptions may result from a transactionRollback verb:
NOTRANS: No matching global transaction is started UNKXID: An unknown xid was specified. INTERR: An internal error has occurred.
90-9
where:
maxResultItems (number): Indicates the maximum number of XIDs to return. If omitted or zero, all XIDs are returned. If specified, and the number of items is equal to or greater than this number, exactly this number of items will be returned. scanOption (string): Indicates the XID scanning operation to be done. It may be "start" (in which XID are returned from the first one), "end" (where the scan is terminated and nothing is returned) or it may be "next" or omitted, meaning that the scan should continue from the point it reached in the last recover call.
The matching response is defined as: <transactionRecoverResponse xid="xid" /> where: xid: The global transaction identifier passed by the transactionStart xid. Exceptions The following exceptions may result from a transactionRecover verb: INTERR: An internal error has occurred.
where: xid: The global transaction identifier passed by the transactionStart xid. The transactionForget verb does not generate a response. Exceptions The following exceptions may result from a transactionForget verb:
UNKXID: An unknown xid was specified. INTERR: An internal error has occurred.
where:
state (string): The state of the given xid. May be "success", "suspend" or "fail". The default is success. xid: A global transaction identifier (required).
The transactionEnd verb does not generate a response. Exceptions The following exceptions may result from a transactionEnd verb:
NOTRANS: No matching global transaction is started. UNKXID: An unknown xid was specified. INTERR: An internal error has occurred.
where:
interactionName (string): Name of interaction to execute. You can omit the interactionName if it is identical to input_record (defined below). interactionMode (string): Describes the nature and direction of the interaction. input_record: Represents the interaction input information as an XML element (with whatever content). The type of input-record is determined by the interaction definition in the adapter schema. If the interaction_name value is not given, the interaction name is assumed to be the same as input_record name, while its attributes and content are determined by the interaction input type.
where: Represents the interaction result as an XML element (with whatever content). The element name must match the interaction output record (and so do the attributes and content).
Metadata Verbs
ACX defines XML format for the following verbs that handle metadata operations for an ACX request:
Or
<getMetadataItem type="item_type"> <name>item1_name</name> <name>item2_name</name> ... </getMetadataItem>
where:
type (string): Indicates the kind of item for which metadata is needed. Supported item types are:
adapter: Provides information about a given adapter (or the currently connected adapter). interaction: Provides information about a given interactions. schema: Returns the complete resource schema. record: Returns a sub-schema containing the definition of the requested records.
name (string): Indicates the particular item(s) for which metadata is needed, or a wildcard (using *,%) for getting metadata of multiple items.
The adapter response. For information, see The Adapter Response. The interaction response. For details, see The Interaction Response.
The Adapter Response The <adapter> response provides information on a particular adapter.
<getMetadataItemResponse> <adapter name="xsd:Name" description="xsd:string" version="xsd:string" type="xsd:Name" operatingSystem="xsd:string" transactionLevelSupport="0|1|2" authenticationMechanism="basic-password" maxActiveConnections="xsd:integer" maxIdleTimeout="xsd:integer"
where:
name (string): Name of the adapter. description (string): Description of the adapter. version (string): Version of the adapter. type (string): The type of the adapter, as specified in the adapter definition. operatingSystem (string): Operating system on which the adapter runs. transactionLevelSupport (number): Indicates the transaction support level:
0: no transactions support (0PC) 1: simple transactions support (1PC) 2: distributed transaction support (2PC).
authenticationMechanism (string): "basic-password" for authentication based on username/password. In a future release support will be provided for "kerbv5", for Kerberos version 5 based authentication.
maxActiveConnections (number): The maximum number of concurrent connections supported by the adapter. This number may or may not be enforced by the adapter but it serves as an indication for the effective number of concurrent connections from the adapter's point of view. The client can use this number to optimize its configuration. maxIdleTimeout (number): An ACX connection to an adapter is terminated after the specified idle timeout expires (in seconds). maxRequestSize (number): ACX requests are restricted in their size to prevent draining of the server system resources. Default limit of request size is 65536 (64KB). This parameter specifies the maximum request size in bytes. connectionPoolingSize (number): Size of connection pool maintained at the server. poolingTimeout (number): Time in seconds a connection is pooled before it is destroyed. supportsReauthentication (Boolean): Indication of whether or not the adapter supports reauthentication.
The Interaction Response The <interaction> response provides information on a particular interaction.
<getMetadataItemResponse> <interaction name="xsd:Name" description="xsd:string" mode="sync-send|sync-send-receive| sync-receive|async-send| async-send-receive" input="xsd:Name"
where:
name (string): Name of the interaction. description (string): Description of the interaction. interactionVerb (string): Describes the nature and direction of the interaction. mode (string): The nature and direction of the interaction. input (string): The name of the record (from the adapter schema) used for input to the interaction. output (string): The name of the record (from the adapter schema) produced by the interaction.
The schema Response The <schema> response describes the input and output of the interactions.
<getMetadataItemResponse> <schema name="xsd:Name" version="xsd:integer" defaultNotDisplayed="xsd:boolean" open="xsd:boolean" > <record|enumeration|variant /> </schema> </getMetadataItemResponse>
where:
name (string): Name of the interaction. version (string): Version of the schema definition. defaultNotDisplayed (Boolean): When True, data items having their respective default values are omitted from the XML document. open (Boolean): When True, the XML to native transformation does not throw an exception about unknown elements or attributes: they are ignored. record|enumeration|variant: Multiple record, variant and enumeration definitions can appear in any order.
where:
name (string): Empty or a wildcard (using *,%) for reducing the names returned on the list. Note that the entries are not necessarily returned in alphabetical order of the item-names. However, there must be some sort of order,
even if it is entirely internal to the adapter (for example, items might be returned in a list ordered an internal ID value).
type (string) Indicates the kind of item for which listing is needed. Supported item types are:
adapter: Useful when interacting with resource dispenser which provides connections or redirections to multiple resources. interaction: List of interactions of the currently connected resource. record: List of records of the currently connected resource.
maxResultItems (number): Indicates the maximum number of result items that are returned. If the number of items is greater than or equal to the number specified in this parameter, exactly this number of items must be returned. startItemName (string): Indicates an item name starting from which items are to be returned. If empty or not given, all items from the first one (inclusive) are returned.
Response The matching response is described below. Note that the list returned might be affected by the authorization of the requester.
<getMetadataListResponse type="item_type" > <name>xsd:Name</name> <name>xsd:Name</name> ... </getMetadataListResponse>
where:
type (string): The type of items whose names were returned. The following are valid values:
Response The response provides information about an active adapter accessed via the <ping> verb.
<pingResponse name="xsd:Name" description="xsd:string" version="xsd:string" type="xsd:Name" operatingSystem="xsd:string" XML Client Interface 90-15
vendor="xsd:string"> </pingResponse>
where:
name (string): Name of the adapter the ping accessed. description (string): Description of the adapter. version: The version number of the adapter. operatingSystem: The operating system on which the adapter runs. vendor: The vendor of the adapter.
</exception>
where:
origin (string): The origin of the exception. The origin string has the following format: adapter.interaction[.location]. Where adapter is the adapter type, interaction is the interaction name and location is an optional location within the interaction. name (string): The exception name. The exception name has the following format: who.what where who isclient if the exception resulted from a client fault, or server if the exception resulted from a server fault. It is important to use one of the common exception names that appear in the table below so that applications can consistently identify common exceptions and handle them. info (string (array)): Zero or more text strings containing a readable description of the exception (the texts are ordered from the general to the specific). application-exception (record): An application specific exception element. The elements tag identifies the schema record defining the exception element structure.
The following table lists common error names and their meaning. Specific adapters can include their own error names. Errors starting with client indicate that the client side was probably responsible for the error. Errors starting with server indicate that the server side was probably responsible for the error
Table 901 Common Error Names Description The authentication information provided with the request is not valid. Exception occurred because the ACX XML request verb was given without an active connection context. A connection has timed out or was otherwise dropped (for example, the server was stopped between requests). The requested interaction is not available on the current adapter. The adapter referred to in the request does not exist on the server. The request sent by the client had semantic errors. The ACX XML request sent by the client had XML parsing errors. An internal error on the server. Additional information is provided to explain the exception. No automatic handling is expected is this case. A feature requested is not implemented in the current release. The server to which the request was referred cannot handle the request and it should be issued to the server named in the <info> element. A resource limit was reached on the server. The same request may succeed later on.
client.noSuchConnection
server.notImplemented server.redirect
server.resourceLimit
Table 901 (Cont.) Common Error Names Exception Name server.xmlError Description An XML parsing error was found in a server response
Send the XML, in which the first 4 bytes specify the length of the document and the remainder is the XML itself. The length format is defined as a signed 32-bit integer in network format (big-endian). If the response from the remote machine includes server.redirect, it also includes the following: <info>ip:port</info> where:
ip: The IP address of a remote machine to which you redirect the XML. port: The port on the remote machine through which the connection is made.
Open a new connection and send the XML to this ip:port location.
where:
URL_address: The address of the remote machine. port: The port through which the connection is established.
Example
dev=osf.acme.com:2551 prod=sun.acme.com:2551 3.
Create the object having the name defined in step 2, and within the object define the functions xml-form, which takes as a parameter the location of the nvNsapi.ini file:
<object name="nvNsapi.dll"> Service fn="url-line-req-xml" </object>
4.
Part XIV
Appendixes
This part contains the following appendixes:
NAVDEMO - Attunity Demo Data Attunity SQL Syntax National Language Support (NLS) COBOL Data Types to Attunity Data Types Glossary
A
NAVDEMO - Attunity Demo Data
This section includes the following topics:
NAVDEMO Overview
Attunity AIS includes demo data on every platform where it is installed, called NAVDEMO. The demo database includes the following tables:
Customer: This table lists details of customers who order parts. Supplier: This table lists details of suppliers of parts. Partsupp: This table lists details of parts supplied. TPart: This table lists details of parts that can be ordered. Torder: This table lists details of orders. Lineitem: This table lists details of a specific part in an order. Nation: This table lists details of the countries where customers and suppliers live. Region: This table lists details of the regions where customers and suppliers live.
NAVDEMO Database
All installations of Attunity Server include a demo database. You can use this database for training, benchmarking and demonstrations. The demo database structure is shown in the following figure:
The columns and data types of each of these tables are listed below. The annotations for primary keys and foreign references are for clarification only and do not specify any implementation requirements such as integrity constraints.
NAVDEMO Tables
This section describes each NAVDEMO table, its column names and data types.
TPART Table
The following table lists the TPART table columns and data types:
Table A1 TPART Table Columns and Data Types Data Type integer variable text, size 55 fixed text, size 25 fixed text, size 10 variable text, size 25 integer fixed text, size 10 decimal variable text, size 23 Comment Primary Key
Column Name P_PARTKEY P_NAME P_MFGR P_BRAND P_TYPE P_SIZE P_CONTAINER P_RETAILPRICE P_COMMENT
SUPPLIER Table
The following table lists the SUPPLIER table columns and data types:
Table A2 Column Name S_SUPPKEY S_NAME SUPPLIER Table Columns and Data Types Data Type integer variable text, size 25 Comment Primary Key
Table A2 (Cont.) SUPPLIER Table Columns and Data Types Column Name S_ADDRESS S_NATIONKEY S_PHONE S_ACCTBAL S_COMMENT P_RETAILPRICE P_COMMENT Data Type variable text, size 40 integer fixed text, size 15 decimal variable text, size 101 decimal variable text, size 23 Foreign reference to N_NATIONKEY Comment
PARTSUPP Table
The following table lists the PARTSUPP table columns and data types:
Table A3 Column Name PS_PARTKEY PS_SUPPKEY PS_AVAILQTY PS_SUPPLYCOST P_COMMENT PARTSUPP Table Columns and Data Types Data Type integer integer integer decimal variable text, size 199 Comment Foreign reference to P_PARTKEY Foreign reference to S_SUPPKEY
CUSTOMER Table
The following table lists the CUSTOMER table columns and data types:
Table A4 Column Name C_CUSTKEY C_NAME C_ADDRESS C_NATIONKEY C_PHONE C_ACCTBAL C_MKTSEGMENT C_COMMENT CUSTOMER Table Columns and Data Types Data Type integer variable text, size 25 variable text, size 40 integer fixed text, size 15 decimal fixed text, size 10 variable text, size 117 Foreign reference to N_NATIONKEY Comment Primary Key
TORDER Table
The following table lists the TORDER table columns and data types:
Table A5 Column Name O_ORDERKEY O_CUSTKEY O_ORDERSTATUS O_TOTALPRICE O_ORDERDATE O_ORDERPRIORITY O_CLERK O_SHIPPRIORITY O_COMMENT
TORDER Table Columns and Data Types Data Type integer integer fixed text, size 1 decimal date variable text, size 15 variable text, size 15 integer variable text, size 79 Comment Primary Key Foreign reference to C_CUSTKEY
LINEITEM Table
The following table lists the LINEITEM table columns and data types:
Table A6 Column Name L_ORDERKEY L_PARTKEY L_SUPPKEY L_LINENUMBER L_QUANTITY L_EXTENDEDPRICE L_DISCOUNT L_TAX L_RETURNFLAG L_LINESTATUS L_SHIPDATE L_COMMITDATE L_RECEIPTDATE L_SHIPINSTRUCT L_SHIPMODE L_COMMENT LINEITEM Table Columns and Data Types Data Type integer integer integer integer integer decimal decimal decimal fixed text, size 1 fixed text, size 1 date date date variable text, size 25 variable text, size 10 variable text, size 44 Comment Foreign reference to O_ORDERKEY Foreign reference to P_PARTKEY Foreign reference to S_SUPPKEY
NATION Table
The following table lists the NATION table columns and data types:
NATION Table Columns and Data Types Data Type integer fixed text, size 25 integer variable text, size 152 Foreign reference to R_REGIONKEY Comment Primary Key. 25 nations are populated
REGION Table
The following table lists the REGION table columns and data types:
Table A8 Column Name R_REGIONKEY R_NAME R_COMMENT REGION Table Columns and Data Types Data Type integer variable text, size 25 variable text, size 152 Foreign reference to R_REGIONKEY Comment Primary Key. 5 regions are populated
B
Attunity SQL Syntax
This section describes SQL statements which include enhancements specific to AIS. The syntax used to describe the SQL statements is described in Syntax Diagrams Describing SQL. The following SQL statements are specific to Attunity Connect:
SELECT Statement FROM Clause WHERE Clause GROUP BY and HAVING Clause ORDER BY Clause Set Operators on SELECT Statements
SELECT XML Statement Batch Update Statements INSERT Statement UPDATE Statement DELETE Statement
TABLE, INDEX CREATE and DROP Statements CREATE TABLE Statement DROP TABLE Statement CREATE INDEX Statement
Stored Procedure Statements CREATE PROCEDURE Statement DROP PROCEDURE Statement CALL Statement
GRANT Statement Transaction Statements BEGIN Statement COMMIT Statement ROLLBACK Statement
Constant Formats Expressions Functions Aggregate Functions Conditional Functions Data Type Conversion Functions Date and Time Functions Numeric Functions and Arithmetic Operators String Functions
Parameters Search Conditions and Comparison Operators Passthru Query Statements (bypassing Query Processing)
Required items appear on the main path. Keywords are shown in uppercase and must be typed as shown. Variables are shown in lowercase. Syntax that is described in detail elsewhere is displayed in angled brackets (<>):
A choice between items appears as a stack. If an entry is shown on the main path, you must include an item in the stack:
An optional choice between items appears as a stack below the main path. Default values are shown in bold:
An option to repeat a part of the syntax appears as an arrow returning to the left. Any syntax included between the beginning and end of the returning arrow follows the normal syntax rules for that part of the syntax diagram:
Punctuation marks, parentheses, arithmetic operators and other symbols must be entered as part of the syntax.
SELECT Statement
The SELECT statement retrieves a rowset from one or more data sources.
Figure B1 SELECT Statement Syntax
DISTINCT: The query retrieves only unique rows. Null values are considered equal for the purposes of this keyword: only one is selected no matter how many the query encounters. table: A specific table whose columns are retrieved. All columns are retrieved in the order they appear in the tables specified in the FROM clause (for example, T1.* specifies all columns in table T1). col: A specific column in the table is retrieved. (<select>): A nested SELECT statement used to flatten a hierarchical rowset. <expr>: Expressions are constants, functions, or any combination of column names, constants, and functions connected by arithmetic operators and listed in the order in which you want to see them. {<select>}: A nested SELECT statement reflecting a parent-child relationship. The result of the nested SELECT statement is represented by a single column, which must be identified using an alias. alias: A new name for this output column of the retrieved rowset. This new name is used to represent any resulting rowsets and can be referenced in any of the SELECT statement clauses (WHERE, GROUP BY, etc.).
Note:
An alias can be specified either as an identifier or as a constant. For example: select n_name as a ... where the alias is an identifier, or, select n_name as a ... where the alias is a constant.
OPTIONS(FORCE ORDER): The query optimizer orders the tables in the same order as they appear in the FROM clause. FOR UPDATE: Records are locked as they are retrieved (pessimistic locking mode). This option can be applied only to the main SELECT statement. OPTIMIZE m ROWS: The optimization strategy is selected to ensure that the first m rows are returned as quickly as possible. Optimization is set to First Row optimization and overrides any value specified for the <optimizer goal> parameter in the AIS Server environment. This option can be applied only to the main SELECT statement.
Example B1 SELECT title, type, price FROM titles WHERE price > 9.99 ORDER BY title OPTIMIZE 5 ROWS
FROM Clause
The FROM clause specifies which sources (such as tables, rowsets and stored procedures) are used in the SELECT statement.
Figure B2 FROM Clause Syntax
ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Notes:
ds can be omitted for the default data source. You can specify the default source as part of the connect string. For HP NonStop Platforms: Fully qualified table names must be delimited by quotes (").
owner: A table owner. If you need to define different owners for the tables, define a data source for each owner and access the tables of the data source in the same way that you access multiple data sources in a single query.
The following SQL statement retrieves information about employees from the EMPLOYEE table, on the Ora1 database. The table owner name is WHITE:
SELECT * FROM Ora1:white.employee
Notes:
You can assign a default owner with the owner property in the binding configuration. Using Attunity Studio, you specify this property in the Default table owner field in the Advanced tab, which is displayed by right-clicking the specific data source, selecting Edit data source and choosing the Advanced tab. You cannot perform schema or catalog functions for a specific owner.
table: The name of the table or view that includes the columns to retrieve. The order in which the tables or views appear is not significant (the logical query execution order may be changed by the query optimizer) except when <join> includes a left outer join (LOJ).
Notes:
Example B4 table Code Sample SELECT * FROM Table1, Table2 WHERE Table1.col1 = Table2.col2
table->chapter: The identifier for data that is stored in a data source such that it can be represented hierarchically (such as information stored in arrays in RMS). For more information and examples see Hierarchical Queries.
view: The name of a view on one or more data sources. For details, see CREATE VIEW Statement. synonym: The name of a synonym (alias) for a table, view or stored procedure. For details, see CREATE SYNONYM Statement. stored_prc: The name of an AIS procedure. The procedure must return a resultset for this option to be valid. For details, see CREATE PROCEDURE Statement.
Note:
Example B5 stored_prc Code Samples select * from T1,stored_proc1 Q1 where Q1.col1=T1.col2 and Q1.col3<T1.col4
<passthru>: See Passthru Query Statements (bypassing Query Processing). param: Specifies values for the stored_prc or <passthru> parameters. The number of values supplied must match exactly the number of parameters defined in the stored procedure or passthru query. If there are no parameters, no values need to be supplied; however, the parentheses () following the name are still required. See CREATE PROCEDURE Statement and Passthru Query Statements (bypassing Query Processing).
alias: An alias used either for clarity or to distinguish the different roles played in a self-join or a subquery.
Note:
For stored procedures, views and passthru queries the alias is mandatory if the rowset name is to be used as a column qualifier elsewhere in the query.
Example B6 alias Code Sample SELECT pub_name, title_id FROM publishers pu, titles t WHERE t.pub_id = pu.pub_id
Note:
Once an alias is specified, the columns can be referenced only using the alias (or if the name is not ambiguous without any identifier).
<hint>: The optimization strategy you want used instead of the optimization strategy selected by the query optimizer. If you specify more than one strategy, the optimizer uses the strategy from this list that is most efficient. If you specify strategies that you dont want used, the optimizer doesnt use any of the strategies from this list. Only specify a hint in the SQL if you have checked the optimization strategy used with the Attunity Connect Query Analyzer. Attunity recommends using hints only when advised by Attunity Support.
Note: If you specify optimization strategies that cannot be satisfied, the query execution fails. The query optimizer creates a number of possible optimization strategies. Only after these strategies have been generated is the best strategy selected from the list of available strategies, based either on any hints specified or on what the optimizer evaluates as the best strategy.
WITH: The designated optimization strategy should be used. WITHOUT: The designated optimization strategy should not be used. SCAN: Indexes are ignored and the data is scanned according to its physical order. INDEX: The index specified by indname is used to seek for specific values in the WHERE clause or, if WITHOUT is specified, the index is ignored for the specific values. INDEXSCAN: The index specified by indname is used to seek for all values or, if WITHOUT is specified, the index is ignored.
indname: The name or an ordinal of an index. n: The number of segments in the index that should be used. Specifying a value of zero (0) is equivalent to specifying INDEXSCAN. FIRST: The left table in the join strategy. This table will be the first table in the optimized tree (on the left side). LAST: The table will be the last table in the optimized tree.
Example B7 <hint> Code Sample 1 SELECT * FROM T1 <ACCESS(INDEX(emp_prim, 2))> WHERE key = 323 or key = 512
ON <cond>: A condition determining the results of the <join>. The condition is used as part of the FROM clause when a join keyword is used (see below). See Search Conditions and Comparison Operators.
Note: The condition can be included in the WHERE clause instead of in the FROM clause, without impacting the results.
<join>: A join between successive tables. <join> has the following format:
Joins can be used only with columns containing scalar values and with aggregate-free expressions. The joins are processed left-to-right, each pair of joined tables becoming in effect a single data source for the next join connector. , (comma): A standard cross join.
Note: Search conditions cannot be used (see Search Conditions and Comparison Operators).
ONE_TO_ONE: Each row in the left rowset has one and only one matching row in the right rowset. ONE_TO_MANY: Each row in the left rowset may have more than one matching row in the right rowset, while each row in the right rowset has exactly one matching row in the left rowset. MANY_TO_ONE: Each row in the right rowset may have more than one matching row in the left rowset, while each row in the left rowset has exactly one matching row in the right rowset.
MANY_TO_MANY: A row in either rowset may have more than one matching row in the other rowset.
Note:
If one of the above modifiers is used in executing a join, it directly influences whether a result row is updateable. The modifier is not considered during query optimization.
In cases where an ON condition is replaced by a WHERE condition, inner joins and cross joins are equivalent, as in the following example:
FROM T1 JOIN T2 ON T1.c1 = T2.c2 FROM T1, T2 WHERE T1.c1 = T2.c2
The exception to this equivalence occurs when the join is under the right branch of an LOJ. Such cases generate two different optimization strategies, which produce different results. The following queries, for example, generate different results:
Select * from nv_dept d LOJ (nv_emp e JOIN nv_sal s ON e.emp_id = s.emp_id) ON d.dept_id=e.dept_id Select * from nv_dept d LOJ (nv_emp e, nv_sal s) ON d.dept_id=e.dept_id where e.emp_id = s.emp_id
Example B9 JOIN Sample 1 SELECT * FROM Table1 JOIN Table2 ON Table1.col1 = Table2.col2 WHERE...
Example B10 JOIN Sample 2 SELECT * FROM Table1, Table2 INNER JOIN Table3 WHERE...
Use parentheses to change the order in which the joins are processed. For example:
SELECT * FROM (Table1, Table2) INNER JOIN Table3 WHERE...
Example B12 JOIN Sample 4 SELECT * FROM Table1 ONE_TO_MANY JOIN Table2 Attunity SQL Syntax B-9
LOJ: The join includes all rows from the left rowset regardless of whether there is a matching row in the right rowset. These joins are called left outer joins. Every row from the left rowset is first matched (using the ON <cond>) with rows from the right rowset, or with null values if there are no matching rows in the right rowset; the predicates from the WHERE clause are then applied to filter the result.
Note:
Search conditions (ON <cond>) must be used (see Search Conditions and Comparison Operators). LOJ is evaluated before commas. Parentheses may be used to affect the grouping of the data sources. The keywords LEFT JOIN or LEFT OUTER JOIN can be used instead of LOJ to improve readability. For conformity with ODBC format you can use {OJ source LEFT OUTER JOIN source ON <cond>}.
Example B13 LOJ Samples SELECT * FROM Table1, Table2 LOJ Table3 ON Table2.col1 = Table3.col3 WHERE...
The following join, lists all authors whose last name starts with R or greater, and retrieves all the publishers (if any) in their city:
SELECT au_fname, au_lname, pub_name FROM authors LOJ publishers ON authors.city = publishers.city WHERE au_lname >= R
ROJ: The join includes all rows from the right rowset regardless of whether there is a matching row in the left rowset. These joins are called right outer joins (ROJ). Every row from the right rowset is first matched (using the ON <cond>) with rows from the left rowset, or with null values if there are no matching rows in the left rowset; the predicates from the WHERE clause are then applied to filter the result.
Note:
Search conditions (ON <cond>) must be used (see Search Conditions and Comparison Operators). ROJ is evaluated before commas. Parentheses may be used to affect the grouping of the data sources. The keywords RIGHT JOIN or RIGHT OUTER JOIN can be used instead of ROJ to improve readability. For conformity with ODBC format you can use {OJ source RIGHT OUTER JOIN source ON <cond>}.
Example B14 ROJ Samples SELECT * FROM Table1, Table2 ROJ Table3 ON Table2.col1 = Table3.col3 WHERE...
The following join lists all authors whose last name starts with R or greater, and retrieves all the publishers (if any) in their city. This example produces the same result as the example for a left outer join above. Note that in this ROJ example the FROM clause lists publishers before authors. In the LOJ example, authors are listed before publishers.
SELECT au_fname, au_lname, pub_name FROM publishers ROJ authors ON authors.city = publishers.city WHERE au_lname >= R
NESTEDJOIN: Forces the query optimizer to use a nested join strategy when joining the tables. For general details about forcing a specific optimization strategy, see <hint>, above.
Example B15 NESTEDJOIN Sample SELECT * FROM Table1, Table2 LOJ <NESTEDJOIN> Table3 ON Table1.col1 = Table3.col3 WHERE...
SEMIJOIN: Forces the query optimizer to use a semi-join strategy when joining the tables. For general details about forcing a specific optimization strategy, see <hint>, above. HASHJOIN: Forces the query optimizer to use a hash join strategy when joining the tables. For general details about forcing a specific optimization strategy, see <hint>, above.
WHERE Clause
The WHERE clause sets the search conditions for filtering rows in a SELECT, UPDATE, or DELETE statement.
Figure B5 WHERE Clause Syntax
<cond>: The search condition. The syntax for the search conditions is described on Search Conditions and Comparison Operators.
Note:
If more than one search condition is used in a single statement, the conditions need to be connected with AND or OR.
Parameters can be specified in the WHERE clause. For more information, see Parameters. Identifiers in the where clause in a subquery can come from the higher level (a level which includes the nested query). Subqueries nest a SELECT statement inside a WHERE clause or another subquery.
B-11
The following subquery returns a list of the types of books published by each publisher. The main query selects the names of those publishers who publish at least one Business title:
Example B16 WHERE Clause Sample 1 SELECT DISTINCT pub_name FROM publishers WHERE 'business' IN (SELECT type FROM titles WHERE pub_id = publishers.pub_id)
Example B17 WHERE Clause Samples WHERE advance * 2 > total_sales * price WHERE phone NOT '415%' (finds all rows in which the phone number does not begin with 415) WHERE advance < 5000 OR advance IS NULL WHERE (type = 'business' OR type = 'psychology') AND advance > 5500 WHERE total_sales BETWEEN 4095 AND 12000 WHERE state IN ('CA', 'IN', 'MD') WHERE total_sales > ? (a parameter is used) WHERE au.last_name LIKE 'R%' AND EXISTS (SELECT * FROM pubs WHERE au.city = pubs.city)
<expr>: Expressions are constants, functions, or any combination of column names, constants, and functions connected by arithmetic operators.
Note:
In certain circumstances (dictated by the data source) a GROUP BY clause may return an error if it contains more than eight columns.
The GROUP BY clause cannot reference a constant expression it returns an error prior to execution. For example, the following returns a syntax error:
SELECT * FROM employee GROUP BY 3*7
Column names and expressions that do not appear in the list of columns after the SELECT keyword can be used in GROUP BY and HAVING clauses. For example:
SELECT pub_id, SUM (advance), AVG(price) FROM titles GROUP BY city HAVING SUM(advance) > 15000 AND AVG(price) < 10
This query groups the results by the cities of the various publishers.
select_num: The ordinal number of the column to group the results by from the list of columns after the SELECT keyword. alias: An alias for an output column specified in the list of columns retrieved by the query. HAVING <cond> : Search conditions for the grouping. The search conditions must be aggregate expressions (they cannot include subqueries). For more information see, Search Conditions and Comparison Operators.
The following example calculates the average advance and the sum of the sales for each type of book:
SELECT type, AVG(advance), SUM(total_sales) FROM titles GROUP BY type
The following example groups the results by a combination of type and pub_id:
SELECT type, pub_id, AVG(advance), SUM(total_sales) FROM titles GROUP BY type, pub_id
The following example displays the results for groups matching the conditions in the HAVING clause:
SELECT pub_id, SUM (advance), AVG(price) FROM titles GROUP BY pub_id HAVING SUM(advance) > 15000 AND AVG(price) < 10 AND pub_id > '0700'
ORDER BY Clause
The ORDER BY clause returns query results sorted by the specified columns.
B-13
<expr>: Expressions are constants, functions, or any combination of column names, constants, and functions connected by arithmetic operators.
Example B19 ORDER BY Clause Code Sample SELECT emp_id, emp_name FROM employee ORDER BY emp_name
The query results are sorted by emp_name, in ascending order. Column names and expressions that do not appear in the list of columns after the SELECT statement can be used in an ORDER BY clause. For example:
SELECT title, type, price FROM titles WHERE price > 9.99 ORDER BY author_id
This query orders the results by the authors of the books that are retrieved.
select_num: The ordinal number of the column to order the results by from the list of columns after the SELECT keyword.
Example B20 ORDER BY Clause Code Sample SELECT emp_id, emp_name FROM employee ORDER BY 2
alias: An alias for an output column specified in the list of columns retrieved by the query. ASC : Sorts the query results by ascending order. DESC: Sorts the query results in descending order.
Additional Information
ORDER BY can be used to display query results in a meaningful order. Without an ORDER BY clause you cannot control the order in which query results are returned. With ORDER BY, null values may come before or after all others. Sorting is carried out inside Attunity Connect or inside a data source containing some of the data, as determined by the query optimizer.
Since different data sources use different strategies regarding the ordering of nulls, the null order is unpredictable. However, for any one query, nulls are always either sort first or sort last.
ORDER BY cannot be used in subqueries and queries with child rowsets. ORDER BY can be used in the main (unnested) part of a query and in queries that use nested SELECT statements to reflect parent-child relationships.
Example B21 ORDER BY Clause Code Samples SELECT title, type, price FROM titles WHERE price > 9.99 ORDER BY title SELECT title AS BookName, type AS Mytype FROM titles ORDER BY 2 SELECT Dept, Max(Sal) FROM Sal GROUP BY Dept ORDER BY 2 SELECT Firstname, Lastname FROM Authors ORDER BY (Lastname || Firstname)
The following query returns an error since ORDER BY is used in the nested query:
SELECT emp_name, (select salary FROM E -> salary ORDER BY 1) FROM employee E
When a statement includes an INTERSECT operator with other set operators and parentheses are not used to enforce an order of operations, the INTERSECT operation is performed first. The other set operators are performed as they appear in the query, from left to right.
B-15
<select>: A SELECT statement that is non-hierarchical.The SELECT statement may be scrollable but cannot be updateable (and the query can be run only in read-only mode).
Note:
When the ORDER BY clause is included within a SELECT statement itself, rather than applied to the result of the set operations, this clause may specify either the name or ordinal number of one of the columns.
Each SELECT statement involved in the set operation must return the same number of columns. The columns in the same position of the returned queries must be of the same data type or coercible, although they may be of different lengths. All the returned data of a particular column will have the size of the longest item in the column (shorter column values are padded, as necessary). For example, when handling character data of different lengths, all returned results are the length of the largest character data returned, with the other results padded to this length. The set operation statement takes the names and data types from the first SELECT statement. If a column is NULL, the data type for this column in the next table of the statement is used.
Note:
When you combine tables with different structures (as when some tables have missing columns and different data types), you can use dummy columns and convert functions, as in the following:
select n_name, n_regionkey from nation union select r_name, convert (null,int) from region order by 1;
UNION: Returns the rows of the <select> statements, discarding any duplicate rows. UNION ALL: Returns all the rows returned by the <select> statements, including duplicate rows. INTERSECT : Returns rows common to both result sets returned by the <select> statements, discarding duplicate rows. MINUS: Returns rows that appear only in the first <select> statement, discarding duplicate rows. <order by>: Returns the combined query results of the set operation sorted by the specified column. You can order the results only by the ordinal number of a column of the rows returned by the statement. <limit to>: Limits the number of rows returned in the retrieved rowset.
Note:
The LIMIT TO syntax is useful in test and prototype environments. For the <order by> or <limit to> clauses to apply only the final <select> statement, rather than to the combined results of the union, you must explicitly group the <order by> or <limit to> with the final <select> as follows:
<select> union (<select> <order by>) <select> union (<select> <limit to>)
Example B22 Set Operators Code Samples select n_name from nation union select r_name from region (select c_name from customer union select s_name from supplier) intersect select n_name from nation
Note that the result of this query is different from the following:
select c_name from customer union select s_name from supplier intersect select n_name from nation
In this case, the INTERSECT operator is applied before the UNION operator.
The XML keyword can be changed in the binding environment properties, by specifying another name for the keyword. This is done by setting the xmlFieldName property.
B-17
ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Note: ds can be omitted for the default data source. You can specify the default data source as part of the connect string.
For HP NonStop platforms, fully qualified table names must be delimited by quotes (")
owner: A table owner. table: The specific table whose columns are retrieved. <cond>: Search conditions. LIMIT TO m ROWS: Only m rows of the result rowset are retrieved.
Example B23 SELECT XML Code Sample SELECT XML FROM navdemo:nation where n_nationkey=3
INSERT Statement
The INSERT statement adds to one base table one row of data or the results of another query.
Figure B10 INSERT Statement Syntax
ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Note: ds can be omitted for the default data source. You can specify the default data source as part of the connect string.
For HP NonStop platforms, fully qualified table names must be delimited by quotes (").
table: The name of the table containing rows to be inserted. The maximum length for a table name is 64.
Note: If the table contains a field with data type BLOB or CLOB, you must define a unique index for the table before you can insert data into the table. For details of creating an index, see CREATE INDEX Statement.
chapter: The identifier for data that is stored hierarchically in a data source (for example, information stored in arrays in RMS). See Hierarchical Queries. column: The name of a column in the table. A column needs to be present only if the expressions specified do not match in order or in count the columns of the table. The columns must be in the same order and count as the values.
Note:
<select>: The data returned by a SELECT statement is copied to the table. See SELECT Statement.
Note:
Make sure that the data types of data retrieved by the SELECT statement match the data types of the columns inserted in the table.
Example B24 <select> from INSERT Code Sample INSERT INTO ORACLE:table1 SELECT * FROM DISAM:table2
VALUE <constant>.
UPDATE Statement
The UPDATE statement updates rows in one or more of base tables. No result rowset object is returned to the user. The base tables affected must each be updateable, or the operation fails. A table is updateable only if for each row in the base table there is at most one corresponding row in the retrieved rowset and according to updateability rules described below. Note that within this limitation, Attunity Connect supports updateable joins.
B-19
ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Note: ds can be omitted for the default data source. You can specify the default data source as part of the connect string.
For HP NonStop platforms, fully qualified table names must be delimited by quotes (").
You can assign a default owner with the owner property in the binding configuration. Using Attunity Studio, you specify this property in the Default table owner field in the Advanced tab, which is displayed by right-clicking the specific data source, selecting Edit data source and then choosing the Advanced tab.
table: The name of the table containing rows to be updated. chapter: The identifier for data that is stored hierarchically in a data source (for example, information stored in arrays in RMS). <hint>: The optimization strategy you want used instead of the optimization strategy selected by the query optimizer. If you specify more than one strategy, the optimizer uses the strategy from this list that is most efficient. If you specify strategies that you dont want used, the optimizer doesnt use any of the strategies from this list.
Note:
If you specify optimization strategies that cannot be satisfied, the query execution fails. The query optimizer creates a number of possible optimization strategies. Only after these strategies have been generated is the best strategy selected from the list of available strategies, based either on any hints specified or on what the optimizer evaluates as the best strategy.
Only specify a hint in the SQL if you have checked the optimization strategy used with the Attunity Connect Query Analyzer. Attunity recommends using hints only when advised by Attunity Support.
B-20 AIS User Guide and Reference
WITH: The designated optimization strategy should be used. WITHOUT: The designated optimization strategy should not be used. SCAN: Indexes are ignored and the data is scanned according to its physical order. INDEX: The index specified by indname is used to seek for specific values in the WHERE clause or, if WITHOUT is specified, the index is ignored for the specific values. INDEXSCAN: The index specified by indname is used to seek for all values or, if WITHOUT is specified, the index is ignored. indname: The name or an ordinal of an index. n: The number of segments in the index that should be used. Specifying a value of zero (0) is equivalent to specifying INDEXSCAN. FIRST: The leftmost table in the join strategy. This table will be the first table in the optimized tree (on the left side). LAST: The table will be the last table in the optimized tree.
ON <cond>: A condition determining the results of the <join> (see below). For full details see Search Conditions and Comparison Operators. <join>: A join between successive tables. <join> has the following format: , (comma): A standard cross join.
Note: Search conditions cannot be used (see Search Conditions and Comparison Operators).
ONE_TO_ONE: Each row in the left rowset has one and only one matching row in the right rowset. ONE_TO_MANY: Each row in the left rowset may have more than one matching row in the right rowset, while each row in the right rowset has exactly one matching row in the left rowset. MANY_TO_ONE: Each row in the right rowset may have more than one matching row in the left rowset, while each row in the left rowset has exactly one matching row in the right rowset. MANY_TO_MANY: A row in either rowset may have more than one matching row in the other rowset.
Note:
If one of the above modifiers is used in executing a join, it directly influences whether a result row is updateable. The modifier is not considered during query optimization.
B-21
In cases where an ON condition is replaced by a WHERE condition, inner joins and cross joins are equivalent, as in the following example:
FROM T1 JOIN T2 ON T1.c1 = T2.c2 FROM T1, T2 WHERE T1.c1 = T2.c2
The exception to this equivalence occurs when the join is under the right branch of an LOJ. Such cases generate two different optimization strategies, which produce different results. The following queries, for example, generate different results: LOJ: The join includes all rows from the left rowset regardless of whether there is a matching row in the right rowset. These joins are called left outer joins. Every row from the left rowset is first matched (using the ON <cond>) with rows from the right rowset, or with null values if there are no matching rows in the right rowset; the predicates from the WHERE clause are then applied to filter the result.
Note:
Search conditions (ON <cond>) must be used (see Search Conditions and Comparison Operators). LOJ is evaluated before commas. Parentheses may be used to affect the grouping of the data sources. The keywords LEFT JOIN or LEFT OUTER JOIN can be used instead of LOJ to improve readability. For conformity with ODBC format you can use {OJ source LEFT OUTER JOIN source ON <cond>}.
ROJ: The join includes all rows from the right rowset regardless of whether there is a matching row in the left rowset. These joins are called right outer joins (ROJ). Every row from the right rowset is first matched (using the ON <cond>) with rows from the left rowset, or with null values if there are no matching rows in the left rowset; the predicates from the WHERE clause are then applied to filter the result.
Note:
Search conditions (ON <cond>) must be used (see Search Conditions and Comparison Operators). ROJ is evaluated before commas. Parentheses may be used to affect the grouping of the data sources. The keywords RIGHT JOIN or RIGHT OUTER JOIN can be used instead of ROJ to improve readability. For conformity with ODBC format you can use {OJ source RIGHT OUTER JOIN source ON <cond>}.
NESTEDJOIN: Forces the query optimizer to use a nested join strategy when joining the tables. For general details about forcing a specific optimization strategy, see <hint>, above. SEMIJOIN: Forces the query optimizer to use a semi-join strategy when joining the tables. For general details about forcing a specific optimization strategy, see <hint>, above. HASHJOIN: Forces the query optimizer to use a hash join strategy when joining the tables. For general details about forcing a specific optimization strategy, see <hint>, above.
Note:
If the join includes a relational data source, it is recommended to have an index defined, otherwise Attunity Connect generates a virtual unique index from all the columns in the table.
SET column: The name of a column in the table. A column needs to be present only if the expressions specified do not match in order or in count the columns of the table. The columns must be in the same order and count as the values.
Note: A SET clause that includes an expression col1=col2 is supported only if col1 and col2 are from the same updateable table.
value: The value to be assigned to the specified column: it may be any scalar-valued expression valid in a WHERE clause. WHERE <cond>: See WHERE Clause.
Updateability rules (described below) determine how to include more than one table in an UPDATE statement.
Additional Information
Expressions for SET and WHERE clauses are evaluated prior to any actual updates, and the order of the column assignments in the SET clause is not significant.
Updateability Rules
It is not semantically meaningful to specify UPDATE Table1, Table2,... since it assumes a Many-to-Many join between Table1 and Table2, making neither table updateable. If more than one table is involved, join modifiers such as One-to-One or Many-to-One must be used, and at least one table must be at the opposite end of a -To-One join and thus be updateable.
B-23
The table on the right side of a left outer join or the left side of a right outer join is not updateable. A SET clause that includes an expression col1=col2 is supported only if col1 and col2 are from the same updateable table.
DELETE Statement
The DELETE statement deletes rows in one or more base tables. No result rowset object is returned to the user. The base tables affected must each be updateable, or the operation fails.
Figure B13 DELETE Statement Syntax
ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Note: ds can be omitted for the default data source. You can specify the default data source as part of the connect string.
For HP NonStop platforms, fully qualified table names must be delimited by quotes (").
You can assign a default owner with the owner property in the binding configuration. Using Attunity Studio, you specify this property in the Default table owner field in the Advanced tab, which is displayed by right-clicking the specific data source, selecting Edit data source and then choosing the Advanced tab.
table: The name of the table containing rows to be deleted. chapter: The identifier for data that is stored hierarchically in a data source (for example, information stored in arrays in RMS). <hint>: The optimization strategy you want used instead of the optimization strategy selected by the query optimizer. If you specify more than one strategy, the optimizer uses the strategy from this list that is most efficient. If you specify strategies that you dont want used, the optimizer doesnt use any of the strategies from this list.
Note: If you specify optimization strategies that cannot be satisfied, the query execution fails. The query optimizer creates a number of possible optimization strategies. Only after these strategies have been generated is the best strategy selected from the list of available strategies, based either on any hints specified or on what the optimizer evaluates as the best strategy.
Only specify a hint in the SQL if you have checked the optimization strategy used with the Attunity Connect Query Analyzer. Attunity recommends using hints only when advised by Attunity Support.
Figure B14 <hint> Syntax
WITH: The designated optimization strategy should be used. WITHOUT: The designated optimization strategy should not be used. SCAN: Indexes are ignored and the data is scanned according to its physical order. INDEX: The index specified by indname is used to seek for specific values in the WHERE clause or, if WITHOUT is specified, the index is ignored for the specific values. INDEXSCAN: The index specified by indname is used to seek for all values or, if WITHOUT is specified, the index is ignored. indname: The name or an ordinal of an index. n: The number of segments in the index that should be used. Specifying a value of zero (0) is equivalent to specifying INDEXSCAN. FIRST: The leftmost table in the join strategy. This table will be the first table in the optimized tree (on the left side). LAST: The table will be the last table in the optimized tree.
Example B25 <hint> Code Samples SELECT * FROM T1 <ACCESS(INDEX(emp_prim, 2))> WHERE key = 323 or key = 512 SELECT * FROM T1 <ACCESS(WITHOUT SCAN), LAST>
ON <cond>: A condition determining the results of the <join> (see below). For full details see Search Conditions and Comparison Operators. <join>: A join between successive tables. <join> has the following format:
B-25
ONE_TO_ONE: Each row in the left rowset has one and only one matching row in the right rowset. ONE_TO_MANY: Each row in the left rowset may have more than one matching row in the right rowset, while each row in the right rowset has exactly one matching row in the left rowset. MANY_TO_ONE: Each row in the right rowset may have more than one matching row in the left rowset, while each row in the left rowset has exactly one matching row in the right rowset. MANY_TO_MANY: A row in either rowset may have more than one matching row in the other rowset.
Note:
If one of the above modifiers is used in executing a join, it directly influences whether a result row is updateable. The modifier is not considered during query optimization.
In cases where an ON condition is replaced by a WHERE condition, inner joins and cross joins are equivalent, as in the following example:
FROM T1 JOIN T2 ON T1.c1 = T2.c2 FROM T1, T2 WHERE T1.c1 = T2.c2
The exception to this equivalence occurs when the join is under the right branch of an LOJ. Such cases generate two different optimization strategies, which produce different results. The following queries, for example, generate different results: LOJ: The join includes all rows from the left rowset regardless of whether there is a matching row in the right rowset. These joins are called left outer
joins. Every row from the left rowset is first matched (using the ON <cond>) with rows from the right rowset, or with null values if there are no matching rows in the right rowset; the predicates from the WHERE clause are then applied to filter the result.
Note:
Search conditions (ON <cond>) must be used (see Search Conditions and Comparison Operators). LOJ is evaluated before commas. Parentheses may be used to affect the grouping of the data sources. The keywords LEFT JOIN or LEFT OUTER JOIN can be used instead of LOJ to improve readability. For conformity with ODBC format you can use {OJ source LEFT OUTER JOIN source ON <cond>}.
ROJ: The join includes all rows from the right rowset regardless of whether there is a matching row in the left rowset. These joins are called right outer joins (ROJ). Every row from the right rowset is first matched (using the ON <cond>) with rows from the left rowset, or with null values if there are no matching rows in the left rowset; the predicates from the WHERE clause are then applied to filter the result.
Note:
Search conditions (ON <cond>) must be used (see Search Conditions and Comparison Operators). ROJ is evaluated before commas. Parentheses may be used to affect the grouping of the data sources. The keywords RIGHT JOIN or RIGHT OUTER JOIN can be used instead of ROJ to improve readability. For conformity with ODBC format you can use {OJ source RIGHT OUTER JOIN source ON <cond>}.
NESTEDJOIN: Forces the query optimizer to use a nested join strategy when joining the tables. For general details about forcing a specific optimization strategy, see <hint>, above. SEMIJOIN: Forces the query optimizer to use a semi-join strategy when joining the tables. For general details about forcing a specific optimization strategy, see <hint>, above. HASHJOIN: Forces the query optimizer to use a hash join strategy when joining the tables. For general details about forcing a specific optimization strategy, see <hint>, above.
Note:
If the join includes a relational data source, it is recommended to have an index defined, otherwise Attunity Connect generates a virtual unique index from all the columns in the table.
SET column: The name of a column in the table. A column needs to be present only if the expressions specified do not match in order or in count the columns of the table. The columns must be in the same order and count as the values.
B-27
Note: A SET clause that includes an expression col1=col2 is supported only if col1 and col2 are from the same updateable table.
value: The value to be assigned to the specified column: it may be any scalar-valued expression valid in a WHERE clause. WHERE <cond>: See WHERE Clause.
Updateability rules (described below) determine how to include more than one table in an UPDATE statement.
Additional Information
Expressions (particularly aggregates in subqueries) are evaluated prior to any actual delete operations.
Updateability Rules
It is not semantically meaningful to specify DELETE Table1, Table2,... since it assumes a Many-to-Many join between Table1 and Table2, making neither table undeletable. If more than one table is involved, join modifiers such as One-to-One or Many-to-One must be used, and at least one table must be at the opposite end of a -To-One join and thus be deletable.
The CREATE TABLE Statement. The DROP TABLE Statement. The CREATE INDEX Statement.
This statement is valid for all supported data sources except ADABAS, DBMS, and VSAM under CICS.
ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Note: ds can be omitted for the default data source. You can specify the default data source as part of the connect string.
For HP NonStop platforms, fully qualified table names must be delimited by quotes (").
table: The name of the table to be created. The maximum allowed length for a table name is 64. column: A column in the table. data type: The data type for the column, which can be one of the following: Char[(m)]. The default value for m is 1 [Char] varchar(m) Tinyint Smallint Integer Numeric[(p[,s])]. The default value of p (precision) is 10 and s (scale) is 0 Float Double Date Time Timestamp (consisting of date and time components for use as a timestamp) Text (a text large object) Image (a binary large object)
The following table lists the data types which are mapped to the data source data types by the relevant driver:
Table B2 Relational DB2 Informix Ingress II (Open Ingres) Data Types Mapping Non-relational ADABAS CISAM DBMS (Open VMS only) Generic Flat Files ODBC OLE DB-FS (Flat FIle System)
B-29
Table B2 (Cont.) Data Types Mapping Relational Oracle Rdb SQL/MP (HP NonStop only) SQL Server Sybase Non-relational DISAM Enscribe IMS/DB (z/OS only) RMS (Open VMS only) VSAM under CICS and VSAM (z/OS only) Generic OLE DB SQL (Relational) Text-Delimited File
NULL: Null values are allowed for the column (this is the default). NOT NULL: Null values are not allowed for the column.
The following SQL statement creates a table named EMPLOYEE, on the Ora1 data source. The name of the table owner is WHITE.
CREATE TABLE Ora1:white.employee (emp_num integer NOT NULL, emp_name varchar(20))
For HP NonStop platforms, an explicit CATALOG clause must be added to the CREATE statement, otherwise it is assumed that the current subvolume is the catalog.
Example B27 CREATE TABLE Statement for HP NonStop Platforms
To execute the following statement, issue it directly to the data source using a passthru query, with the text={{query}} syntax.
create table $d0117.nssdata.ET_md0(PLANT_CODE SMALLINT not null, DEPARTMENT_CODE SMALLINT not null, FACILITY_NO INTEGER not null, PRODUCTION_DATE DATE not null,DELAYTIMESUMALLCMT FLOAT, DELAYEVENTSSUMALLC INTEGER, primary key(PLANT_CODE, DEPARTMENT_CODE, FACILITY_NO, PRODUCTION_DATE)) CATALOG $d0117.nssdata
This statement is valid for all supported data sources except ADABAS and DBMS.
ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Note: ds can be omitted for the default data source. You can specify the default data source as part of the connect string.
For HP NonStop platforms, fully qualified table names must be delimited by quotes (").
table: The name of the table to be deleted. If this name is the name of a synonym, then the table which the synonym refers to is dropped.
The following SQL statement deletes the EMPLOYEE table from the Ora1 data source. The table owner name is WHITE.
DROP TABLE Ora1:white.employee
B-31
UNIQUE: The entries in the index will be unique. index_name: The name of the index to be created. The maximum length for an index name is 64. ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Note: ds can be omitted for the default data source. You can specify the default data source as part of the connect string.
For HP NonStop platforms, fully qualified table names must be delimited by quotes (").
You can assign a default owner with the owner property in the binding configuration. Using Attunity Studio, you specify this property in the Default table owner field in the Advanced tab, which is displayed by right-clicking the specific data source, selecting Edit data source and then choosing the Advanced tab.
table: The name of the table the index is created for. column: The columns (segments)constituting the index.
Example B29 CREATE INDEX Statement Code Sample CREATE INDEX empname ON employee(last_name, first_name)
VIEW Statements
This section describes the following SQL VIEW statements:
Note:
In Attunity Studio, views can only be defined using the Virtual data source and the Virtual driver.
A view cannot accept parameters. You cannot create a view in a single session after dropping a view with the same name.
ds: The name of the data source of type Virtual. This enables you to specify a location for the view other than the default data source. If you do not want to use the default SYS data source, define a data source of type Virtual and specify the name of this data source as the ds value when you create the view. For information about defining a Virtual data source, see Virtual Data Source.
Notes:
To create a view on the back-ene database, issue the CREATE VIEW statement directly to the data source using a passthru query, with the text={{query}} syntax. You may want to store views in a location other than the SYS data source for organizational reasons and because storing a large number of views in SYS can degrade performance.
view_name: The name used to identify the view. The maximum length for a view name is 64. <select>: A SELECT statement. For the syntax, see SELECT Statement.
Note:
Duplicate column names are not allowed when creating a view. You must use an alias for a duplicate column name. For example the following view returns an error:
create view v1 as select d.dept_id COL1, e.dept_id from disam:nv_dept d, disam:nv_emp e where e.dept_id = d.dept_id
All columns in a view are returned unqualified. For example, the columns returned from the previous view are: COL1 and dept_id.
Example B30 CREATE VIEW Statement Code Sample create view1 as select * from T2,T3 where T2.col5=T3.col6 and T2.col7>T3.col8
B-33
This view is stored in the current default data source or in the SYS data source if no default data source was set. To use this view if no default data source is set, issue the following statement:
select * from sys:view1 where view1.col1=T1.col2 and view1.col3<T1.col4
Note:
You do not need to supply an alias if the rowset name is used as a column qualifier elsewhere in the query (as in this example).
ds: The name of the data source other than the default data source, where the view is located. view_name: The name of the view to be deleted. The view is dropped from the repository and not from the back-end data source. To drop a view of the back-end database, issue the DROP VIEW statement using a passthru query with the text={{query}} syntax.
Note:
The CREATE PROCEDURE Statement The DROP PROCEDURE Statement The CALL Statement
Support for stored procedures native to particular data sources is described per data source.
Attunity Connect procedures. An Attunity Connect procedure is a user-written DLL that returns a rowset. The returned rowset is handled in the same way that data from any data source is handled. For details about Attunity Connect procedures, see Procedure Data Sources.
Note: When you access a stored procedure in a SELECT statement, you must use parentheses after the stored procedure, even when you do not supply the parameters.
A stored query is a SELECT statement that accesses a data source or another stored procedure. You create a stored query with the CREATE PROCEDURE statement. This statement creates a query that can be used later in the FROM clause of an SQL query, or wherever a subquery can be specified. Stored procedures can have parameters (specified in the WHERE clause of the SELECT statement), and can be used only for data retrieval operations.
Figure B21 CREATE PROCEDURE Statement Syntax
ds: The name of the data source of type Virtual. This enables you to specify a location for the stored procedure other than the default data source. If you do not want to use the default SYS data source, define a data source of type Virtual and specify the name of this data source as the ds value when you create the stored procedure. For information about defining a Virtual data source, see Virtual Data Source.
Note:
To create a stored query on the back-end data source, issue the CREATE PROCEDURE statement directly to the data source using a passthru query with the text={{query}} syntax. You may want to store a procedure in a location other than the SYS data source for organizational reasons. Also, storing a large number of views in SYS can degrade performance.
stored_proc: The name used to identify the stored procedure. The maximum length for a procedure name is 64. <select>: A SELECT statement. For the syntax, see SELECT Statement.
B-35
Duplicate column names are not allowed when creating a stored procedure. You must use an alias for a duplicate column name. For example the following stored procedure returns an error:
create procedure sp1 as select d.dept_id, e.dept_id from disam:nv_dept d, disam:nv_emp e where e.dept_id = d.dept_id
All columns in a stored procedure are returned unqualified. For example, the columns returned from the previous stored procedure are: COL1 and dept_id.
Example B31 CREATE PROCEDURE Code Sample 1
This stored procedure is stored in the SYS data source if no default data source is set. To use this stored procedure, you include SYS as the ds specification in the query accessing the stored procedure. You can execute the procedure with a value for the parameter as follows:
CALL sys:P1(20)
This stored procedure is stored in the SYS data source if no default data source is set. To use this stored procedure, you include SYS as the ds specification in the query accessing the stored procedure. The following query joins the EMPLOYEE table with sp_salaries, retrieving information on employee salaries:
select* from emp,sys:sp_salaries(emp.emp_id)
Note:
You must supply an alias if the rowset name is used as a column qualifier elsewhere in the query (as in this example).
ds: The name of the data source other than the default data source, where the stored query is located. stored_proc: The name of the stored procedure to be deleted. The stored procedure is dropped from the repository and not from the back-end data source.
Note:
To drop a stored query of a back-end database, issue the DROP PROCEDURE statement directly to the data source using a passthru query with the text={{query}} syntax.
CALL Statement
The CALL statement executes a stored procedure and returns a rowset. A stored procedure can be:
Stored queries, created with a CREATE PROCEDURE statement, cannot be called using a CALL statement.
?=: Retrieves the return value from the stored procedure. ds: The name of the data source where the stored procedure is created. The ds entry is determined by the type of stored procedure you are calling:
B-37
For a stored procedure native to a specific data source, specify the data source name as it is defined in the binding configuration. For an Attunity Connect procedure, specify the data source name defined for the Attunity Connect procedure in the binding configuration.
You can assign a default owner with the owner property in the binding configuration. Using Attunity Studio, you specify this property in the Default table owner field in the Advanced tab, which is displayed by right-clicking the specific data source, selecting Edit data source and then choosing the Advanced tab.
stored_proc: The name of the stored procedure being called. param: A list of parameters.
The following rules apply also to passing parameters to Attunity Connect procedures (procedures are described in Procedure Data Source (Application Connector):
The number of values supplied must match exactly the number of parameters defined in the stored procedure. If the stored procedure has no parameters, no values need to be supplied; however, the parentheses () following the name of the stored procedure are still required. If several values are specified, they must be separated by commas. You can specify values for parameters positionally or by name. When specified positionally, you list the values in the order expected by the data source or Attunity Connect procedure. This format is always valid. Specifying the values by name is valid only if the stored procedure defined named parameters; in this case, the values may be specified in the form parameter_ name = value, separated by commas. The order in which the values are specified is not significant. These two formats for specifying values cannot be mixed in any single invocation of a stored procedure.
A value may be a literal or an expression. As an extension of standard ANSI 92 SQL, you can specify, as values, expressions involving columns of tables that appeared previously in the FROM list. For example, the following is valid where V is a parameterized stored procedure and col1 is a column of table A:
SELECT * FROM A, V(A.col1)
This creates an implicit join between A and V: for each row of A, the current value of col1 is used to compute a new row based on the stored procedure V. For this join to be valid, A must appear before V in the FROM list.
Example B34 CALL Statement Code Sample
Synonym Statements
This section describes the following SQL synonym statements:
You cannot create a synonym in a single session after dropping a synonym with the same name.
A synonym can be used to implement a virtual data source. A virtual data source presents a view to the user such that only selected tables from one or more data sources are available, as if from a single data source. You populate a virtual data source by defining synonyms for the tables, views, and stored procedures you want the virtual data source to make available. For details about virtual databases see Using a Virtual Database.
Figure B24 CREATE SYNONYM Statement Syntax
ds: The data source name as specified in the binding configuration. Specify for this ds entry the name of the virtual data source (if it is not the default).
Note:
You can specify the default data source as part of the connect
string.
synonym_name: The name of the synonym to be created. The name must not be the name of an existing table or synonym. ds: The data source name as specified in the binding configuration. This ds entry is the data source where the table referenced by the virtual data source resides.
B-39
You can assign a default owner with the owner property in the binding configuration. Using Attunity Studio, you specify this property in the Default table owner field in the Advanced tab, which is displayed by right-clicking the specific data source, selecting Edit data source and then choosing the Advanced tab.
table: The name of a table for which the synonym is created. The name cannot be the name of an existing synonym. The synonym can be used as if it is the table.
Note:
If the table does not exist, the synonym will automatically refer to the table when it is created.
view: The name of the existing view for which the synonym is created. synonym: The name of an existing synonym, which this new synonym references. You can only specify this option if creating a virtual data source entry.
Example B35 CREATE SYNONYM Statement Code Sample create synonym vdb1:emp for sybase:employees
This stores the emp synonym referencing the Sybase employees table with the virtual data source vdb1.
You cannot create a synonym in a single session after dropping a synonym with the same name.
ds: The name of the data source other than the default internal SYS data source, where the synonym is located. synonym_name: The name of the synonym to be deleted. The synonym is dropped from the repository and not from the back-end data source.
GRANT Statement
The GRANT statement grants all the permissions for a table to a specified user.
Note: The data source being accessed must support the GRANT statement.
Figure B26 GRANT Statement Syntax
user: The user who subsequently has all permissions on the specified table. ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Note:
ds can be omitted for the default data source. You can specify the default data source as part of the connect string.
For HP NonStop platforms, fully qualified table names must be delimited by quotes (").
table: The name of the table for which permissions are granted.
Transaction Statements
This section describes the following SQL transaction statements:
BEGIN Statement
The BEGIN statement starts a transaction on all data sources, which continues until a ROLLBACK or COMMIT statement is executed.
Note: For an XML data source, the BEGIN statement causes the table data to be stored in memory.
B-41
COMMIT Statement
The COMMIT statement commits a transaction.
Note:
For an XML data source, the COMMIT statement releases the table data from the memory.
ROLLBACK Statement
The ROLLBACK statement aborts a transaction.
Figure B29 ROLLBACK Statement Syntax
Constant Formats
The following table lists the supported constant formats:
Table B3 Constant Formats Example 124234 123.34 12E-3 The weather is sunny
Constant Format nnnnnn (long constant) 123.34 (double constant) 12E-3 abcde (string constant) NULL (NULL constant) Hexadecimal
0x1AB5
Expressions
An expression is a combination of one or more constants, literals, column names, parameters, subqueries and functions, connected by operators, that returns a single value. The components of an expression may mix data types, within the constraints of the supported coercions. You can use the arithmetic operators in expressions, as listed in the following table:
Table B4 Symbol + * /
These arithmetic operators can be used on all Attunity data types where the value contains only numeric values.
Operator Precedence
Operators have the following precedence levels, where 1 is the highest level and 5 is the lowest:
1. 2. 3. 4. 5.
When all operators in an expression are of the same level, the order of execution is from left to right. You can change the order of operation with parentheses the most deeply nested expression is then handled first.
Functions
Functions are typically used in expressions. Functions take one or more arguments and return a single value. All functions can be used with the ODBC format {fn function(value)}. This section describes the following SQL functions:
Aggregate Functions Conditional Functions Data Type Conversion Functions Date and Time Functions Numeric Functions and Arithmetic Operators String Functions
B-43
Aggregate Functions
The aggregate functions generate summary values that appear as new columns in the query results. Aggregate functions can be used in the select list of a query or subquery or in a HAVING clause. Aggregate functions often appear in a statement that includes a GROUP BY clause. The aggregate functions, their individual syntax, and the results they produce are described in the following table. The expression is computed once for every qualifying input row.
Table B5 Aggregate Functions
Result Returns the average (over the input rows) of the values in expr.
ALL: Applies the function to all values (the default). DISTINCT: Eliminates duplicate values before applying AVG.
COUNT([ALL|DISTINCT} expr)
ALL: Applies the function to all values (the default). DISTINCT: Returns the number of unique non-null values. COUNT: Can be used with all data types except text and image. Null values are ignored. COUNT (column_name): Returns a value of 0 on empty tables, on columns that contain only null values, and on groups that contain only null values.
COUNT(*)
Returns the number of qualifying input rows in this group. All rows are counted, regardless of any null values. The number of rows returned must be less than 2,147,483,647 or the wrong value is returned.
MAX(expr)
Returns the highest value (among the input rows) of the values in expr. With character columns, MAX finds the highest value in the sort sequence. Null values are ignored. Returns the lowest value (among the input rows) of the values in expr. With character columns, MIN finds the lowest value in the sort sequence. Null values are ignored. Returns the total (over the input rows) of the values in expr. SUM can be used only on numeric (integer or floating point) data types. Null values are ignored.
MIN(expr)
SUM([ALL|DISTINCT] expr)
ALL: Applies the function to all values (the default). DISTINCT: Eliminates duplicate values before applying SUM.
Additional Information
Aggregate functions can be used in: The list of values to be retrieved as specified after the SELECT keyword. A HAVING clause of a SELECT statement.
When a list of values to be retrieved, as specified after the SELECT keyword, includes an aggregate, all the columns must either have aggregate functions applied to them or be in the GROUP BY list. Aggregate functions can be applied to all the rows in a table, in which case they produce a single value, a scalar aggregate. Aggregate functions can also be applied to all the rows that have the same value in a specified column or expression (using the GROUP BY and, optionally, the HAVING clause), in which case they produce a value for each group, a vector aggregate. The results of the aggregate functions are shown as new columns.
Note:
The following example calculates the average advance and the sum of the total sales for all history books. Both functions produce a single summary value for all the retrieved rows. The aggregates are computed over the entire titles table, and are not broken into groups.
SELECT AVG(advance), SUM(total_sales) FROM titles WHERE type = history
Used with a GROUP BY clause, both aggregate functions produce single values for each group, rather than for the entire table. The following example produces summary values for each type of book:
SELECT type, AVG(advance), SUM(total_sales) FROM titles GROUP BY type
The following example finds the number of different cities in which authors live:
SELECT COUNT(distinct city) FROM authors
The following example lists the book types in the titles table but eliminates the types that include one or no books:
SELECT type FROM titles GROUP BY type HAVING count (*) > 1
The following example groups the titles table by publishers and includes only those groups of publishers who have paid more than $25,000 in total advances and whose average book price is more than $15:
SELECT pub_id, SUM(advance), AVG(price) FROM titles GROUP BY pub_id HAVING SUM(advance) > 25000 AND AVG(price) > 15
Conditional Functions
The supported conditional functions are listed and described in the following table:
Table B6 Conditional Functions
Result Compares expr to each search value, one at a time. If expr is equal to search, the function returns the corresponding result. If no match is found, the function returns default, or NULL if the ELSE statement is omitted. The data types of search1searchN must be comparable to the data type of expr and are converted to this data type if necessary. The data types of result1resultN must be the same (including the same precision and scale for non-atomic data types except for strings). For strings, every result is padded to have the same length as the longest result. The data type returned by this function is that of result. Evaluates the conditions in the order in which they appear. Returns the corresponding result for the first condition that evaluates to TRUE. The data types of result1resultN must be the same (including the same precision and scale for non-atomic data types except for strings). For strings, every result is padded to have the same length as the longest result. The data type returned by this function is that of result.
Conditional Function CASE expr when search1 then result1 when search2 then result2 ... When searchN then resultN [else default] END CASE when condition1 then result1 when condition then result2 ... When conditionN then resultN [else default] END
B-45
Note: Use the CONVERT function (see Data Type Conversion Functions to ensure that the data types match). For example, if the expression involves multiplying an integer by a numeric, the result can be a double, causing an error. In this type of situation, convert all values to double before applying the CASE statement.
Example B37 Conditional Function Code Samples
Char[(m)]. The default value of m is 1. [Char] varchar(m) Tinyint Smallint Integer Numeric[(p[,s])]. The default value of p (precision) is 10 and s (scale) is 0. Float Double Date Time Timestamp expression cannot be a BLOB. The converted expression is delegated to the data source for processing whenever possible. Note that data sources handle strings differently and therefore the result of converting an expression to a string can be different per data source.
Notes:
Returns the expression converted to the specified target data type and does not issue the query to the data source for processing. The valid data types are the same as for the CONVERT function, listed above.
Date Format
Any of the following forms are valid:
You can use a hyphen (-) or a slash (/) as a separator (for example, dd/mm/yy[yy]). If you are using characters (JAN, FEB, MAR, etc.) to denote the month, use the format dd-mmm-yy[yy]. When using the format dd-mm-yy or dd-mmm-yy, the year2000Policy parameter in the environment settings determines the century (1900 or 2000). For details, refer to the YEAR2000_POLICY parameter in the Miscellaneous Category for the Environment Properties.
Time Format
hh:mm:ss[.f]: The placeholder f represents billionths of a second, and can be up to nine characters long.
Timestamp Format
Timestamp functions use string representations of timestamps, which combine the date and time formats described above. The supported date functions are listed in the following table:
Table B8 Date Functions
Result Accepts string designation of the date, prefixed by d. For example: select * from ORD where datefield = {d 01-01-03} Returns the present value of SQL_DATE. {t time string} Accepts string designation of the time, prefixed by t. This is equivalent to the TO_TIME function. Returns the current value of SQL_TIME. {ts timestamp string} Accepts string designation of the date and time, prefixed by ts. This is equivalent to the TO_DATE function. Returns the present value of SQL_TIMESTAMP. ADD_MONTHS(date, n) Accepts a date and integer (n) and returns the date plus n months. If date is the last day of the month or if the resulting month has fewer days than the day component of date, the result is the last day of the resulting month. Otherwise, the result has the same day component as the date.
B-47
Returns the current date as SQL_TIME data type. Returns the current day and time as SQL_TIMESTAMP data type.
Returns a date value equal to the date plus the number of dateparts. DATEDIFF(datepart, date1, date2) Accepts two dates and one of the following for datepart:
Returns the number of datepart boundaries drossed between the two dates (date1 and date2). DAY(expression) DAYNAME(date) DAYOFWEEK(date) DAYOFYEAR(date) LAST_DAY(date) LEAPYEAR(date) HOUR(expression) MINUTE(expression) MONTH(expression) MONTHNAME(date) Accepts a date or timestamp expression and returns the day part of the expression as SQL_INTEGER data type. Accepts a date or timestamp expression and returns the name of the day for the input date. Accepts a date or timestamp expression and returns the number of the day in the week for the input date (Sunday is 1, Monday is 2, ...). Accepts a date or timestamp expression and returns the number of days since the beginning of the year. Accepts a date and returns the date of the last day of the month that contains date. Accepts a date or timestamp expression and returns 1 if the year is a leap year and 0 if it isnt. Accepts a time or timestamp expression and returns the hour part of the expression as SQL_INTEGER data type. Accepts a time or timestamp expression and returns the minute part of the expression as SQL_INTEGER data type. Accepts a date or timestamp expression and returns the month part of the expression as SQL_INTEGER data type. Accepts a date or timestamp expression and returns the name of the month.
NEXT_DAY(date, char)
where the comparison operator can be one of =, <, >, <=, >=, <>. Comparisons are done to the level of seconds (milliseconds are ignored).
B-49
Table B9
Numeric Functions
Result Returns the absolute value of expression. Returns the smallest integer value bigger than or equal to expression. Returns e to the power of expression. Returns the biggets integer value less than or equal to expression. Returns the base 10 logarithm of expression. Returns the natural logarithm of expression. Returns the remainder of a/b. This function converts the given expression to a long data type and returns a long data type.
Returns Pi to 14 decimal places. Returns expressionx to the power of expressiony. Returns expressionx rounded to expressiony places to the right of the decimal point. If expressiony is negative, returns expressionx rounded to the nearest ten to the power of expressiony. For example: ROUND(153.193, 1) = 153.2 ROUND(153.193, -2) = 200 The ROUND function is similar to the TRUNC function (described below). expressiony is converted to a lond data type.
SIGN(expression)
Returns the square root of expression.. Returns the result of the trigonometric function.
SIN, ASIN, SINH COS, ACOS, COSH TAN, ATAN, TANH Returns expressionx truncated to expressiony places to the right of the decimal point. If expressiony is negative, returns expressionx truncated to the nearest ten to the power of expessiony. For example: TRUNC(153.193, 1) = 153.1 TRUNC(153.193, -2) = 100) The TRUNC function is similar to the ROUND function, always rounding down. TRUNC(n, 0) is equivalent to FLOOR(n).
TRUNC(expressionx, expressiony)
All functions (except for the MOD function) convert the given expression to a double data type and return a double data type.
String Functions
The supported string functions are listed in the following table:
Table B10
String Functions
Result Returns the ASCII value of the first character. On EBCDIC computers, returns the EBCDIC value. expression is converted to a string data type. This function applies to single byte character sets.
CHR(expression)
Returns the characrter with the ASCII value of expression. On EBCDIC computers, returns the EBCDIC value. expression is converted to a string data type.
Returns the number of bytes (as SQL_INTEGER) of string. Returns a cstring with length equal to expr2, padded by spaces to the left. expr2 must evaluate to a non-negative long. If expr2 is less than the length of expr1, the first characters are returned. If expr2 is a long constant, the returned the cstring maximum size equals the expr1 size. Otherwise, the size is 2000. expression is converted to a string data type. For example: LPAD(abcd, 5) = abcd LPAD(abcd, 3) = abc Compare with RPAD(), below.
Returns a cstring without leading spaces. The length of this cstring is equal to the length of expression. Returns the number of characters (as SQL_INTEGER) of graphic_string. Searches for presence of substring in graphic_string. If substring exists, a numeric value is returned indicating the position (in characters) of substring in graphic_string. If substring is not found, 0 is returned. Returns a substring of graphic_string, i characters from the beginning of graphic_string and ending j characters later or at the end of the graphic_ string, if no j is specified. Searches a substring in a string. If substring exists, a value indicating the position (in bytes) of substring in string is returned. 0 indicates no substring is found. Returns a cstring of length equal to expr2, padded by spaces to the right. expr2 must evaluate to a non-negative long. If expr2 is less than expr1, the first characters are returned. If expr2 is a long constant, the returned cstring has a maximum size equal to the size of expr1. Otherwise, the size is 2000. expression is converted to a string data type. For example: RPAD(abcd, 5) = abcd RPAD(abcd, 3) = abc Compare with LPAD(), above.
POSITION(substring IN string) 1
RPAD(expr1, expr2)
RTRIM(expression)
Returns a cstring without trailing spaces. The length of this cstring is equal to the length of expression. expression is converted to a string data type. Compare with LTRIM() above.
Returns a substring of string, offset i bytes from the beginning of string and ending j bytes later or at the end of the string, if j is not specified.
B-51
When using the POSITION function against Ingres or Ingres II, the POSITION function is translated into the Ingres and Ingres II LOCATE function. This function returns the first position of the specified string. If the string is not found the maximum size of the field plus one is returned. Thus, when the POSITION function is used with the MAX function and the specified string is not found in all the rows, or when it is used with the MIN function and the string specified is not found in any of the rows, the result is the size of the field plus one.
Note:
Parameters
A parameter is used like a constant and may be used anywhere a literal value is valid, except in a list of retrieved data after a SELECT keyword. A value must be assigned to the parameter before the query is executed. A parameter is specified either by a colon followed by the parameter name (for example: WHERE col1 = :param1) or by a question mark (WHERE col1 = ?) A parameter prefixed by a colon can be assigned values by position or name. A parameter prefixed by a question mark can only be assigned values by position. Although an ODBC API does not support keywords for passing parameter values to a statement prior to execution, you can still use passthru queries calling Attunity Connect procedures specifying parameter values by keywords. See Passthru Query Statements (bypassing Query Processing) and CREATE PROCEDURE Statement.
Note:
query.
NOT: Negates any logical expression or keywords such as LIKE, NULL, BETWEEN, and IN. <expr>: An expression is a combination of one or more constants, literals, column names, parameters, subqueries and functions, connected by operators, that returns a single value. The components of an expression may mix data types, within the constraints of the supported coercions. A comparison between a string and a numeric value is performed according to the numeric order, and not the string order. To perform a string comparison, make sure that both sides of the comparison are string values or place single quotes () around the numeric value.
Comparing 100 with 5 produces a different result when comparing numbers or strings: 100 is greater than 5 but 100 is less than 5. To convert a numeric value to a string value, use the CONVERT function. See Data Type Conversion Functions. Comparison operators are:
=, <, >, <=, >=, <>
B-53
Notes:
When comparing data of type SQL_CHAR or SQL_VARCHAR, the operator < means closer to the beginning of the alphabet and the operator > means closer to the end of the alphabet. For the purposes of comparison, trailing blanks are ignored for data of type SQL_CHAR but are significant for SQL_VARCHAR. When the data types are mixed, the coercion is always to SQL_ CHAR, and trailing blanks are ignored. Literals are also considered to be of type SQL_VARCHAR. For example, SQL_VARCHAR with a value Dirk is not the same as a value Dirk . When comparing dates, < means earlier and > means later.
Single quotes must be placed around character and date data used with a comparison operator. For example:
= Bennett > 94609
AND: Joins two conditions and returns results when both conditions are true. OR: Joins two conditions and returns results when either condition is true.
Note: When both AND and OR are used in a statement, OR is evaluated after AND. Use parentheses to change the order of execution.
NULL: Use to search for null values (or for all values except null values). For example:
WHERE advance < 5000 OR advance IS NULL
An expression with an arithmetic operator evaluates to NULL if any of the operands are null. Null values in tables or views being joined never match each other.
BETWEEN: Denotes the beginning of an inclusive range of values. The keyword AND denotes the end of a range of values. For example:
WHERE val BETWEEN x AND y
Note:
If the first value specified is greater than the second value, no rows are returned.
IN: Specifies whether a given value matches any one of a list of expressions (all of which must be of the same data type) or is included among the values retrieved by the subquery (<select>). IN <select>: A SELECT statement (subquery). For the syntax, see SELECT Statement. The maximum number of nested SELECT statements is 10. The SELECT statement can return only one column (multiple rows can be returned).
Note:
string: A string of characters or an expression that evaluates to a string of characters (for example, CONCAT(firstname,lastname)). LIKE: The character string is a matching pattern for columns of data type SQL_ CHAR or SQL_VARCHAR. For example:
WHERE FAMILY_NAME LIKE JOHNSON
<expr>: An expression. When the expression is a string of characters and wildcards, it must be enclosed in quotes. <expr> can include the following wildcard characters: % (percent symbol): A string of zero or more characters. _ (underscore): A single character.
Note: <expr> must include at least one character and less than 256 characters.
char: An escape character used to search for literal occurrences of wildcard characters. The following example defines and uses the pound sign (#) as an escape character:
WHERE 10%DIS LIKE 10#%D% ESCAPE #
EXISTS <select>: Tests for the existence of at least one row in the rowset from the nested SELECT statement (subquery).
Note: The EXIST <select> syntax can be used only in a WHERE clause.
The following example retrieves the names of publishers who have published mathematics books:
SELECT DISTINCT pub_name FROM publishers WHERE EXISTS (SELECT * FROM titles WHERE pub_id = publishers.pub_id AND type = mathematics)
ALL <select>: True when at least one row retrieved by the nested SELECT statement (subquery) matches the expression specified as the first operand. The SELECT statement can return only one column.
Notes:
The ALL <select> syntax can be used only in a WHERE clause. If neither ALL or ANY is specified, then the subquery can return only a single row.
The following example retrieves the books that commanded an advance greater than the largest advance paid by CompMath Publishers:
B-55
SELECT A.title FROM titles A WHERE advance > ALL (SELECT advance FROM titles B, publishers WHERE B.pub_id = publishers.pub_id AND pub_name = CompMath Publishers)
ANY <select>: True when any value retrieved by the nested SELECT statement (subquery) matches the expression specified as the first operand. The SELECT statement can return only one column.
Notes:
The ANY <select> syntax can be used only in a WHERE clause. If neither ANY or ALL is specified, then the subquery can return only a single row.
The following example retrieves the authors who live in the same city as some publisher:
SELECT au_lname, au_fname FROM authors WHERE city = ANY (SELECT city FROM publishers)
Example B42 Search Condition Code Samples WHERE advance * 2 > total_sales * price WHERE phone NOT LIKE 415% /* finds all rows in which the phone number does not begin with 415 */ WHERE advance < 5000 OR advance IS NULL WHERE (type = business OR type = psychology) AND advance > 5500 WHERE total_sales BETWEEN 4095 AND 12000 WHERE state IN (CA, IN, MD) WHERE au.last_name LIKE R% AND EXISTS (SELECT * FROM pubs WHERE au.city = pubs.city)
The SQL syntax for a retrieval passthru query is part of the FROM clause:
ds: The data source name for a table as specified in the binding configuration, when this is not the default data source.
Note: ds can be omitted for the default data source. You can specify the default data source as part of the connect string.
.For Rdb, prefix all table names in the query with the data source name specified in the binding configuration.
For HP NonStop Platforms, append the words BROWSE ACCESS at the end of the query, when specifying a query to a HP NonStop SQL/MP data source (if the query is not within a transaction).
param: Specifies values for the parameters required by the passthru query. The number of values supplied must match exactly the number of parameters defined in the passthru query. If the passthru query has no parameters, no values need to be supplied; however, the parentheses () following the name are still required. If several values are specified, they must be separated by commas. If the parameter value is supplied externally to the query (for example, with the APPEND method on the Parameter object in ADO or using a setXXX method in JDBC), specify a question mark (?) in the parameter value list. You specify parameters positionally, in the order expected by the passthru query. A value may be a literal or an expression. As an extension of standard ANSI 92 SQL, you can specify, as values, expressions involving columns of tables that appeared previously in the FROM list. For example, the following is valid where col1 is a column of table A:
SELECT * FROM A, TEXT={{parameterized passthru query}}(A.col1)
This creates an implicit join between A and the passthru query: for each row of A, the current value of col1 is used to compute a new row based on the passthru query. For this join to be valid, A must appear before the passthru query in the FROM list.
alias: You must supply an alias if the rowset name is to be used as a column qualifier elsewhere in the query.
Attunity SQL Syntax B-57
Note:
An alias is supported only for retrieval passthru queries (as part of a SELECT statement).
A non-returning result:
SELECT * FROM disam:nation, rdbms:TEXT={{SELECT * FROM customer WHERE c_nationkey = ? AND c_custkey = ?}}(7,100)
Where disam and rdbms are data sources specified in the binding configuration. The SQL to the rdbms data source is issued directly to this data source, bypassing the Query Processor.
Reserved Keywords
The reserved keywords are listed in the following table:
Table B11 ACCESS ALL AND ANY AS ASC AVG BEGIN BETWEEN BY CALL CASE COMMIT CONVERT COUNT CREATE CURRENT DATEADD DATEDIFF DELETE DESC DISTINCT Reserved Keywords GRANT GROUP HASJOIN HAVING IN INDEX INDEXSCAN INNER INSERT INTERSECT INTERVAL INTO IS JOIN LAST LEFT LIKE LIMIT LOJ MANY_TO_MANY MANY_TO_ONE MAX OPTIMIZE OPTIONS OR ORDER OUTER OUTPUT PROC PROCEDURE QUERY RIGHT ROJ ROLLBACK ROWS SELECT SEMIJOIN SET SOME STRING SUM SYNONYM TABLE TEXT
Table B11 (Cont.) Reserved Keywords DISTINCTROW DROP ELSE END ESCAPE EXEC EXISTS FIRST FOR FORCE FROM MIN MINUS MYWHERE NAV_COVERT NESTEDJOIN NOT NULL OF ON ONE_TO_MANY ONE_TO_ONE THEN TO TRANSACTION UNION UNIQUE UPDATE VALUES VIEW WHEN WHERE WITH WITHOUT
B-59
C
National Language Support (NLS)
The main aspect of the National Language Support in AIS is the recognition of the different characters associated with a language and the way they are encoded in various operating systems and data sources. For each supported language, a special definition file called 'a codepage file' is supplied where all the language related information is stored. For complex languages such as Chinese, Japanese and Korean, a special library is also provided where specific conversion rules are implemented. As a distributed product that accesses heterogeneous data sources on varied platforms, AIS offers seamless conversion of text between the different character encodings used on the different platforms. Examples of such automatic conversion include:
Conversion between ASCII based encoding on open systems and EBCDIC based encoding on IBM mainframes and AS/400 machines Conversions to and from Unicode for Java, COM and .NET APIs Conversions to and from Unicode for databases that store data in Unicode Conversions between different encodings of the same language used on different platforms Conversions of legacy data stored using old character encodings (e.g., 7-bit encoding) into the current platform encoding standard
Getting this kind of seamless NLS support requires the proper setting of the codepage definitions according to the kind of encoding in use in the various data sources and platforms. This section discusses the different encoding schemes in use, the codepage definitions required and other NLS related aspects, and contains information on the following topics:
Codepage Terminology Basic NLS Settings Globally Setting Language at the System Level Working with Multiple Languages (UTF Codepage) NLS and XML and Java Encoding NLS Support at the Field Level Special Daemon Language Considerations Support for 7-Bit Codepages SQL Functions For Use With Graphic Strings
Codepage Terminology
The following terminology is used to describe codepages.
Single-byte codepages
In a single-byte codepage, each character is represented by a single byte value, that is, a number between 1 and 255, inclusive. Single-byte codepages are typical of Western languages. For example, in the ISO-8859-1 (Latin) codepage, the character 'A' is represented by the single byte value of 65, whereas in the US-EBCDIC codepage (or in the IBM-037 codepage), the same character is represented by the single-byte value of 193.
Multi-byte codepages
In a multi-byte codepage, some or all of the characters are represented by more than one byte value. Multi-byte codepages are typical in complex languages such as Chinese, Japanese and Korean.
Unicode codepages
Unicode is a universal numbering of all known characters, with each character identified by a unique number - its codepoint. Unicode has several encoding schemes, of which AIS supports UTF-8 and, to a lesser extent, UCS-2. Since the product uses 8-bit characters, the only Unicode encoding that qualifies as a 'codepage' is the UTF-8 encoding. The product supports UCS-2 in its Unicode-based APIs (Java and .NET) and in its data sources (via special Unicode data types).
Customized codepages
The NLS support of AIS can be customized to add new languages and codepages not currently supported as well as to introduce special conversion cases. The customization involves editing special codepage source files and building .cp files from them using the NAV_UTIL program. Exact details of how to customize codepages can be found in an e-Resolve knowledge base article on this subject.
Open the Bindings list and right-click on the NAV binding. Select Edit Binding. Open the Misc category and fill in the language parameter with the desired language code from NLS Language Codes. Save the change. New servers will use the language selected.
When a language is selected, a default codepage is automatically used based on the language and the platform. The following table summarizes the languages, their codes and their codepages.
Table C1
NLS Language Codes Alternative Codepages ASCII Platforms (Default) ISO-8859-15 EBCDIC Platforms (Default) IBM1140 (EBCDIC based unless noted otherwise) IBM037, IBM500, IBM1148, IBM1047, ISO-8859-1 (ASCII based)
English UK
ENUK
Windows-125 2
ISO-8859-15
IBM1146
French
FRE
Windows-125 2
ISO-8859-15
IBM1147
Latin International
LAT
Windows-125 2
ISO-8859-15
IBM1148
Spanish
SPA
Windows-125 2
ISO-8859-15
IBM1145
German
GER
Windows-125 2
ISO-8859-15
IBM1141
Table C1 (Cont.) NLS Language Codes Alternative Codepages ASCII Platforms (Default) ISO-8859-15 EBCDIC Platforms (Default) IBM1140 (EBCDIC based unless noted otherwise) IBM037, IBM500, IBM1148, IBM1047, ISO-8859-1 (ASCII based) Italian ITL Windows-125 2 ISO-8859-15 IBM1144 IBM280, IBM037, IBM500, IBM1140, IBM1148, IBM1047, ISO-8859-1 (ASCII based) Greek Russian1 Turkish2 Hebrew Arabic Japanese GRK RUS TUR HEB ARA JPN Windows-125 3 Windows-125 1 Windows-125 4 Windows-125 5 Windows-125 6 SJIS ISO-8859-7 ISO-8859-5 ISO-8859-9 ISO-8859-8 ISO-8859-6 VMS Machine - VMS-JP SUN Machine - EUC-JP (Solaris) All non VMS/SUN Machines SJIS Chinese Simplified Chinese Traditional Korean
1
IBM1025 IBM1026 -
IBM939
Russian users who use ANSI 1251 Cyrillic as their Windows codepage must
edit the RUS.TXT file and compile it to RUS.CP using the NAV_UTIL CODEPAGE. A RUS.TXT Example is shown below.
2
To work with solutions in Attunity Studio, when using Turkish, add the -nl en switch to the Target path in the Attunity Studio shortcut properties. For example: "C:\Program Files\Attunity\Studio1\studio.exe -nl en"
RUS.TXT Example
The following is an example of the RUS.TXT file that must be included to usethe ANSI 1251 Cyrillic code page.
; The setting of MS_WIN_CP depends on the Windows' Russian codepage ; set in the Regional Settings Control Panel screen: ; ; For "1251 - (ANSI - Cyrillic)" use: ;MS_WIN_CP = 1251 ; ; For "8595 - (ISO 8859-5 Cyrillic)" use: MS_WIN_CP = 28595
When there are many different binding definitions, this method can save the need to define the language for each one. When upgrading from old versions (before V4.1). In the past, server definitions could be saved in a local language. Currently, server definitions are always saved in UTF-8 encoding. Without this setting, there may be a problem loading an old environment definition, since the server may not recognize its codepage before the loading of the environment is complete.
Note:
This option overrides the language and codepage specified in the environment definition making it impossible to change language settings from Studio. This may interfere with the proper working of the system in some scenarios (e.g., when a particular server workspace needs to be set to use UTF-8 encoding).
To set the language at the system level Define an environment variable by the name ACLANG with a value based on the following pattern:
<language>:<codepage>
For example:
FRE:F8EBCDIC297
The environment variable should be defined in an appropriate place, in accordance with the operating system in use.
There may be cases in which some of your existing data is encoded differently, for example with 7-bit encoding. AIS allows you to specify which fields are encoded differently by using the NLS_STRING data type. Data fields of this type are converted from the alternate encoding to the main encoding that you set in the procedure To set the language at the system level for your environment, when read from the database, and converted back to the alternate encoding when writing to the database. In default configuration, we fully support working with tables with names and metadata in the machine codepage but, this configuration is NOT multilingual i.e. only one codepage should be used in all bindings. To work with more than one language (supported on ASCII based machines, only), the NAV environment codepage should be set to UTF-8. In this case, objects (Tables, Procedures, Stored Procedures, Views, and Synonyms) that have names with non-Latin characters are not supported. To change the NAV environment codepage to 'UTF-8' use nav_util edit env acadmin and set codepage=UTF-8 under Misc. To define the nlsString codepage 1. In Studio, navigate to the Design perspective.
2. 3.
In the Configuration view, right-click the machine with the binding configuration you want to set. Under Bindings, select the your binding configuration. Note: NAV is the default binding.
4.
Right-click the binding configuration and choose Edit Binding. The environment properties are listed in the Properties tab. nlsString is set under the misc group.
5.
In the Value field for the nlsString property, specify the codepage to be used for non-UTF-8 encoding.
declares its encoding to be ISO-8859-1 (ISO Latin). AIS generally recognizes all accepts its codepage names as valid XML encoding names. However, only codepages of the current language (as configured) are recognized. In addition, common XML alias names are accepted for most codepages. For Java, there is also a known set of encoding names recognized by Java components. The list of common encoding as of version 1.4.2 of the Java 2 Standard Edition can be found at: http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html
To handle such cases, AIS defines a special string type called nls_String. Strings in the database that are defined as nls_Strings are converted automatically to the system codepage when they are read from the database, and are converted back from the system codepage when they are written to the database. To use this data type, change the tables to use this data type rather than STRING and then tell the product which encoding to use for NLS strings. This involves two steps:
1. 2.
Defining the data type of a field as nlsString. Specifying the nlsString parameter of the environment setting.
In the Configuration view, right-click the data source, and select Edit Metadata. The Metadata tab opens with the selected data source displayed in the Configuration view.
2. 3.
Select the table that contains the field, right-click and choose Edit. In the Columns tab, select the field and specify nlsString as the data type.
To define the nlsString environment properties Note: The language and codepage is set using Studio, in the Design perspective.
1. 2. 3.
In the Configuration view, click the machine with the binding configuration you want to set. Under Bindings, select the relevant binding configuration. Right-click the binding configuration and select Edit Binding. The environment properties are listed in the Properties tab. The nlsString property is set under the misc group.
4.
In the Value field for the nlsString property, specify the name of the codepage and, optionally, a comma and whether the character set reads from right to left (as in Middle Eastern character sets). The default is false (read from left to right).
Examples
Specifying the following in the Value field defines a Japanese EUC 16 bit code page:
JA16EUC
Specifying the following in the Value field defines an Israeli standard 960 7-bit Latin/Hebrew (ASCII 7-bit), where the character set reads from right to left:
IW7IS960,true
A special case exists where the daemon must be set to work in a specific language. This happens when XML-based clients (e.g., JCA, NETACX, COMACX) send XML documents encoded in codepages other than UTF-8, ISO-8859-1 or US-EBCDIC. In such a case, the daemon must be instructed to load the language definition that contains the codepage that appears in the requests. To define the daemon language
Note:
1. 2. 3. 4.
In the Configuration view, click the machine with the daemon you want to set. Under Daemons, select the daemon configuration. Right-click the daemon configuration and select Edit Daemon. In the Default language field in the Daemon Control tab, choose the language.
In the Design perspective Configuration view, click the computer with the binding configuration you want to set. Under Bindings, select the relevant binding configuration. Right-click the binding configuration and select Edit binding. The environment properties are listed in the Properties tab. The language and codepage properties are already set. The property to set here is the nlsString property under the misc group.
4.
In the Value field for the nlsString property fill in the 7-bit codepage name.
For 7-bit Hebrew, specify IW7IS960 followed by a comma and true, since the character set reads from right to left: IW7IS960,true. For the Japanese JA16EBCDIC930 codepage, specify JA16EBCDIC.
These functions use characters instead of bytes when executing the function. In addition, the TO_GRAPHIC data type conversion function is available to convert a single byte string to a double byte graphic string.
D
COBOL Data Types to Attunity Data Types
The following table shows how data the mapping between Attunity data types and COBOL data types.
Table D1 COBOL to Attunity Data Type Conversion Storage Mode NOIBMCOMP Fraction al ADD Data Type Y scaled_int1 or string according to the number of digits. Note: See Footnote 1 for all int data types. N int or string according to the number of digits. See footnote 1 at the end of this table. IBMCOMP Y scaled_int See footnote 1 at the end of this table. N int See footnote 1 at the end of this table. Other Y scaled_int See footnote 1 at the end of this table. N int See footnote 1 at the end of this table.
Table D1 (Cont.) COBOL to Attunity Data Type Conversion COBOL Date COMP-6 Type COBOL Flavor Switch BINARY-CHAR Storage Mode Fraction al ADD Data Type int See footnote 1 at the end of this table. BINARY-SHORT int See footnote 1 at the end of this table. BINARY-LONG int See footnote 1 at the end of this table. BINARY-DOUBLE int See footnote 1 at the end of this table. COMP AS 400 Other Y decimal scaled_int See footnote 1 at the end of this table. N int See footnote 1 at the end of this table. COMP-1 COMP-2 COMP-3 COMP-4 Y single dfloat (double)
2
COMP-5
MICROFOCUS
NOIBMCOMP
scaled_int or string according to number of digits See footnote 1 at the end of this table.
Table D1 (Cont.) COBOL to Attunity Data Type Conversion COBOL Date COMP-6 Type COBOL Flavor Switch Storage Mode Fraction al ADD Data Type N int or string according to the number of digits See footnote 1 at the end of this table. IBMCOMP Y scaled_int See footnote 1 at the end of this table. N int See footnote 1 at the end of this table. Other Y scaled_int See footnote 1 at the end of this table. N int See footnote 1 at the end of this table. COMP-6 MICROFOCUS COMP-6 (1) NOIBMCOMP Y scaled_int or string according to the number of digits See footnote 1 at the end of this table. N intv or string according to the number of digits scaled_int See footnote 1 at the end of this table. N int See footnote 1 at the end of this table. COMP-6 (2) Other decimal
3
IBNCOMP
Table D1 (Cont.) COBOL to Attunity Data Type Conversion COBOL Date COMP-6 Type COBOL Flavor Switch COMP-X MICROFOCUS Storage Mode Fraction al ADD Data Type Y scaled_int or string according to the number of digits See footnote 1 at the end of this table. N int or string according to the number of digits See footnote 1 at the end of this table. Other Y scaled_int See footnote 1 at the end of this table. N int See footnote 1 at the end of this table. FLOAT-SHORT FLOAT-LONG FLOAT-EXTENDED INDEX single dfloat dfloat int See footnote 1 at the end of this table. SIGN [IS] LEADING See footnote 3 at the end of this table.
4
NATIVE-4
NATIVE-8
PACKED -DECIMAL
decimal
Table D1 (Cont.) COBOL to Attunity Data Type Conversion COBOL Date COMP-6 Type COBOL Flavor Switch POINTER Storage Mode Fraction al ADD Data Type int See footnote 1 at the end of this table. POINTER-64 int See footnote 1 at the end of this table.
1
The actual data type can be a signed or unsigned integer, and its size depends on the size that describes the COBOL data type (for example, int1, int3, uint1, uint4) A PIC clause that does not contain a format character (S),(+), or, (-) and the COBOL flavor is z/OS, maps to unsigned_decimal, otherwise, it maps to decimal. A PIC clause that contains the format character (.), maps to string. A PIC clause that does not contain the format character (.) and the COBOL flavor is HP NonStop, maps to numstr_lse, and all other COBOL flavors map to numstr_nlo. A PIC clause that contains the format character (.), maps to numstr_bdn. A PIC clause that does not contain the format character (.), maps to numstr_nl.
When mapping COBOL data types not listed in the above table, Attunity Connect maps PIC clauses containing the format characters X, B, A, or N map to string. To determine the size of the Attunity string, allow one character for each COBOL X, B, or A format character and two characters for each COBOL N format character. All other data types that define only a PIC clause, are mapped according to the following rules:
A PIC clause containing a format character (+), (-), or (S) and the PIC clause:
Contains the format character (.), it maps to string. Does not contain the format character (.) and the COBOL flavor is HP NonStop, it maps to numstr_tse while other COBOL flavors map to numstr_s.
A PIC clause not containing a format character (+), (-) or, (S) and the PIC clause:
Contains the format character (.), it maps to string. Does not contain the format character (.), it maps to string numstr_u.
E
Editing XML Files in Attunity Studio
In many cases you must manually edit the metadata to configure parts of a solution or composition. Metadata is created in XML format. You define aspects of a solution by changing the values of the elements and attributes of the XML files that belong to the solution. Attunity Studio provides a graphical interface where you can define the various aspects of a solution. This interface lets you make changes easily without having to manually edit the XML file.
Machines, for more information see Setting up Machines. Bindings, for more information see Setting up Bindings in Attunity Studio. Daemons, for more information see Defining Daemons at Design Time. Users, for more information see User Profiles and Managing a User Profile in Attunity Studio.
When you open an XML file, a graphical representation of the file is opened in the editor. The editor displays the elements and attributes in the file in the first column and their corresponding values in the second column. Each entry has an icon that indicates whether the entry is an element or an attribute. Click the Source tab to view the file in its native format. The following figure is an example of the editors view of an XML file.
Figure 901 XML Graphical Display
E-1
To edit an XML file in Attunity Studio 1. In the Design perspective, open the Navigator view.
2. 3. 4. 5. 6.
In the Navigator view, find the item with the XML file that you want to edit. This can be a machine, binding, daemon, or user. Right-click the item and select Open as XML. A graphical list of the files elements and attributes opens in the editor. Find the element or attribute (property) that you want to change. Click in the right column next to the property you are changing and edit or add the value. Save the file, then select it again in the Project Explorer and press F5 to refresh. The XML file is updated automatically.
Remove Objects Add DTD Information Edit Namespaces Add Elements and Attributes Replace an Element
Remove Objects
You can delete an element, attribute, or other object from the XML file. To remove an object 1. Right-click an object from the list in the editor.
2.
Select Remove.
Figure E1
2.
Enter the information requested in the dialog box. The following table describes the Add DTD Information dialog box.
Add DTD Information Description The name of the XML root element. The value in this field is the Public Identifier. It is used to associate the XML file (using an XML catalog entry) with a DTD file by providing a hint to the XML processor. Click Browse to select an XML catalog entry from a list. An XML Catalog entry contains two parts, a Key (which represents a DTD or XML schema) and a URI (which contains information about a DTD or XML schema's location). Select the catalog entry you want to associate with your XML file.
Table E1 Field
System ID
The value in this field is the DTD the XML file is associated with. You can change the DTD the file is associated with by editing this field. The XML processor will try to use the Public ID to locate the DTD, and if this fails, it will use the System ID to find it. Click Browse to select a system ID. You can this in two ways:
Select the file from the workbench. In this case, update the with the import dialog box. Select an XML catalog entry.
3.
Save the file, then select it again in the Project Explorer and press F5 to refresh. The XML file is updated automatically.
Edit Namespaces
You can make changes to the namespaces associated with an element or attribute. To edit namespaces 1. Right-click an element or attribute and select Edit namespaces. The Edit Schema Information dialog box opens.
E-3
Figure E2
2.
1. 2.
To add a new namespace From the Schema Information dialog box, click Add. The Add Namespace Definitions dialog box opens. Select one of the following:
Select from registered namespaces. This selection is available when the dialog box opens. Select from the list of registered namespaces and then click OK. If no registered namespaces are available, the list is empty. Specify new namespace. Enter the information described in the following table:
New Namespace Description The prefix is added to all qualified elements and attributes in the XML file. The namespace of the XML file. The location of the XML schema of the XML file. An XML Catalog ID or a URI can be entered in this field. Click Browse to search for the schema you want You can this in two ways:
Select the schema from the workbench. In this case, update the with the import dialog box. Select an XML catalog entry.
The Namespace Name and Prefix fields are be filled with the appropriate values from the schema (you must leave the fields blank for this to occur). Note: If you are creating an XML file from an XML schema, you cannot change the Namespace Name or Location Hint values.
To edit a namespace 1. From the Schema Information dialog box, click Edit.
2.
Add Attribute to add an attribute under the selected element. Add Child to add another element under the selected element Add Before to add another element above the selected element Add After to add another element below the selected element
Note:
The InFocus Design Studio XML editor is Context sensitive to InFocus schemas. This means that when adding elements and attributes to an XML file with an InFocus schema, you can select an element or attribute from a list of the possible values (depending on the schema definition). This list is available as a submenu.
3.
Provide a name for the element or attribute if required. You may also be able to select the element from a submenu. The element or attribute will be added to the file. Save the file, then select it again in the Project Explorer and press F5 to refresh. The XML file is updated automatically.
4.
Replace an Element
You can replace an element with another legal element. To replace an element 1. Right-click an element from the list in the editor.
2. 3. 4.
Select Replace with. Select an element from the submenu. Only legal elements are available. The original element is replaced with the selected element.
E-5
Glossary
ACX Attunity XML protocol. ACX is used as the network protocol between the application connectivity client (e.g. .NET or JCA program) and the AIS server. The verbs and the concept of the ACX protocol are the foundation of Attunitys application connectivity. Adapter Binding An instance of an Application Adapter in the Binding. The relationship between the application adapter and the adapter binding is the same as the one between a data source Driver and the Data Source definition in the binding. In Attunity terminology, often used interchangeably with Application Adapter or simply adapter. Adapter Definition The Metadata object that corresponds to an Application Adapter instance. ADD Attunity Data Dictionary, which includes Metadata for Data Sources and Applications. Agent A special type of Application Adapter that provides the changed information for CDC. For example, a DB2 CDC agent is the software component that reads changes from the DB2 log and provides them to a CDC consumer. Application Legacy software within an enterprise to which connectivity is required for various purposes. Application Adapter A software component that provides connectivity to an application. Adapters are a part of the AIS application connectivity framework which includes the ACX protocol and interfaces like JCA, .NET, COM and XML. They are analogous to Data Source Drivers in the data access sphere. ATMI Application to Transaction Monitor Interface
Glossary-1
Backend Database
ATMI supports a programming interface that offers procedural library-based programming using a set of C or COBOL procedures. ATMI also provides an interface for communication, transaction, and data buffer management. The ATMI interface and BEA Tuxedo system implement the X/Open distributed transaction processing (DTP) model for transaction processing. Backend Database The Data Source to which you connect via Attunity Connect. In a client-server data access scenario, the server database being accessed is commonly referred to as the backend database. Binding An assemblage of Application Adapters and Data Sources. Every Workspace has a definition as to which binding it works with. Bindings include data sources, application adapters and environments/Events, with the first two being the most important. BLOB A BLOB (Binary Large Object) is a large file, typically an image or sound file, that must be handled in a special way because of its size. Captured Data Source The data source being monitored for changes. CDC Change Data Capture Enables updates to tables to be captured for additional processing. The change capture mechanism polls the database using a specified query and when a change is encountered that meets initial criteria, the relevant data is written to an Event Queue, where it can then be further processed. Change Data Source A data source where change records from the CDC agent are stored. Change Router A server component that reads events from a CDC agent on a back-end and fills them up in a Staging Area. Change Table (Change File) The tables in a change data source. There is one change table per captured table in the captured data source. Chapter A chapter is an OLE DB term, denoting a group of rows within a hierarchical rowset. The chapter constitutes a collection of children of some row and column in a parent rowset (and is meaningful only in the context of the parent rowset). The column in the parent rowset is called a chapter column and contains a chapter identifier. The columns name is also the name identifying the child rowset, which is meaningful only in the context of the parent rowset. An ADO Recordset is equivalent to an OLE DB chapter. In ADO you refer to a child Recordset. In ODBC and JDBC, Attunity Connect provides functionality to enable support for chapters.
Glossary-2
Data Source
ChapView A sample program provided with AIS. It is installed on Windows. Intended to demonstrate the use of Chapters within ADO programs, but also useful to test SQL statements against AIS Data Sources. Client Interface A set of functions, classes, interfaces and rules through which an Application communicates with a software component. AIS supports standard client interfaces for applications, namely ODBC, OLEDB/ADO, JDBC, JCA, and ACX. Client Machine A client machine is a machine running an application that calls Attunity Connect via one of its standard Client Interfaces such as ODBC, OLEDB/ADO, JDBC, JCA or ACX. A Machine that can supply data to other machines is called a server, and a machine that requests data from a server is a client. Note that a Server Machine can also be a client of other servers. CLOB A CLOB (character large object) value can be up to two giga-characters long. A CLOB is used to store unicode character-based data, such as large documents in any character set. The length is given in number characters for both CLOB, unless one of the suffixes K, M, or G is given, relating to the multiples of 1024, 1024*1024, 1024*1024*1024 respectively. Length is specified in characters (unicode) for CLOB. Connect String A string containing connection properties that are passed to a Client Interface such as ODBC, OLEDB/ADO, JDBC, JCA, and ACX when creating a data or application access connection. There are various types of connection strings, depending on the client interface you are trying to use and the target system. Attunity Connect defines connection strings for the client interfaces that it supports. Connection Pooling A cache of connections maintained in memory so that the connections can be reused when future requests are received. Connection pooling is handled by the Daemon, by setting a number of parameters, including the server mode (making the Server Process reusable) and the number of available servers. Daemon The daemons main function is to house the assemblage of Workspaces. A series of daemons can be made available. The default is called IRPCD. Workspaces are underneath daemons in the Attunity Studio tree. Data Source Data access within AIS is divided into data sources. A data source can be of type Oracle, VSAM, etc., etc. The division into data sources is sometimes defined by the Backend Database; for example, connecting to a specific Oracle database. In other cases, the division into data sources is more a design decision, for example in the grouping of logically related VSAM files.
Glossary-3
Data Type
Data Type A data type in a programming language is a set of data with values having predefined characteristics. Examples of data types are: integer, floating point unit number, character, string, and pointer. Usually, a limited number of such data types come built into a language. The language usually specifies the range of values for a given data type, how the values are processed by the computer, and how they are stored. Database Adapter A special Application Adapter in which the underlying Application is the AIS Query Processor. Driver A software component that connects to a particular data source interface. For example, an Oracle driver is the software component that translates internal AIS calls to the OCI interface. In Attunity terminology, often used interchangeably with Data Source. ETL Extract, Transform, Load. Three database functions that are combined into one tool to pull data out of one Data Source and place it in another. Event An interaction of type async-send. It can be used in Event Queues and in CDC. Event Queue A software component that provides persistent storage of Events to allow delivery to consuming applications in a decoupled manner. Extended ADD An ADD repository used in conjunction with a non-ADD-based data source. As such, it does not store the Metadata itself, but rather augments information. For example, Extended ADD is commonly used for storing cardinality information for NonStop SQL and Adabas-Predict. Another example is virtual tables or virtual views for arrays within Adabas-Predict. File Pool Cacheing of file handles in a pool to reduce the amount of open/close operations on files. File pools are used in conjunction with File-system Data Sources, such as RMS, Enscribe, DISAM, etc. File-system Data Source In AIS terms, any data source that does not accept SQL commands is considered a file-system data source. Some examples include Adabas, DISAM, VSAM, DBMS, etc. See also Relational Data Source. Interaction The most basic unit of activity against an Application. An Adapter Definition is comprised of a set of interactions and the Schemas that describe their input and output.
Glossary-4
NAV.SYN
IRPCD The default Daemon. Isolation Level Describes the degree to which the data being updated is visible to other transactions. Lock A lock is a mechanism for controlling access to something. In databases, locks are often used so that multiple programs or threads of a program can share a resource, for example, access to a file for updating it, on a one-at-a-time basis. Typically, a lock is of temporary duration and when the resource is no longer required, it is freed for locking and use by the next sharer in a queue. LOJ Left Outer Join. An SQL operation that requests data from two tables where the results returned are those columns that are common to both tables. In addtion all the columns from the first or left table are also included. In this manual any outer join is described by the term LOJ. In a right outer join the common columns and those in the second table are returned. An inner join operation returns only the common columns. Machine A computer system being used as either the client or server in a data access, application access or CDC scenario. Metadata The term metadata is used both in conjunction with data access and/or application access scenarios. In data access, metadata is comprised of table definitions, including columns, datatypes, indexes, cardinality, file locations, etc. In application access, metadata is comprised of interactions, input records, output records and their respective columns and datatypes. Metadata can either be generated and stored within AIS (see ADD), or can be dynamically retrieved from any backend system that provides metadata. Oracle database is an example of a backend system that holds its own metadata; VSAM data source is an example of a backend system that uses the AIS data dictionary (ADD) to store metadata. Native File System Some AIS-supported platforms include a file system which is native to the machine. Examples of such native file systems are VSAM for MVS, RMS for OpenVMS and Enscribe for HP NonStop. AIS uses the native file system of the machine whenever possible, e.g. physical NOS storage and NAVDEMO files. On machines that do not have a native file system, AIS uses DISAM files. NAV The name of the default Binding. NAV.SYN The external AIS syntax file. When accessing Relational Data Sources, the Attunity Query Processor generates SQL in the syntax of the backend Relational Data Source. In order to do so, AIS maintains a set of internal syntax definitions for all supported relational data sources. The NAV.SYN syntax file provides a means of creating new syntax definitions. In the following circumstances you can control the way the SQL is generated:
Glossary-5
NAV_UTIL
When the features supported by the version of the Backend Database are different from the support provided by Attunity Connect for that database. When the backend data source is accessed using either the ODBC or OLESQL generic Drivers. The set of SQL features sent by default to the backend data source is minimal; those that are normally supported by all relational data sources. This is because any flavor of SQL can be supported by the backend database.
NAV_UTIL The AIS command line interface, with its own collection of commands. The commands include troubleshooting utilities and Metadata utilities. All of the commands run from the NAV_UTIL Command Line Utility (or NAVCMD on IBM z/OS systems). NAVDEMO Every AIS installation includes a NAVDEMO data source. This data source can be used for installation verification, or for demo purposes. The tables in the NAVDEMO data source are based on TPCD standard tables. The tables in the NAVDEMO data source are implemented using the machines native file system. Navigator The name of the default Workspace. NAVROOT The root directory where AIS is installed. An environment variable named NAVROOT points to this directory. NOS Native Object Store. This is the name of the physical persistent storage for all AIS definitions, including Bindings, Daemons, ADD Metadata, Adapter Definitions, etc. These are all stored in NOS files. Every AIS installation has at least one NOS repository, called SYS. The SYS NOS stores all definitions with the exception of ADD metadata, which is stored in separate NOS repositories. NOS is implemented over the Native File System of each platform. Ownership Ownership in relational databases relates to the three-part standard table naming: catalog.owner.table.The owner usually represents the database user who created the table. So, for example, if the user scott creates a table emp then the table is really called scott.emp (scott can call this table just emp but other users must prefix the table name with the owner). Passthru Passthrough (or Passthru) is not a relational database term. This is an AIS term that usually means that the SQL statement that the user provides is passed as-is to the underlying database without being parsed by Attunity Connect. Passthru is used in cases where one wants to use a special feature or syntax in the underlying database that Attunity Connect does not support. Passthru mode can be associated with a connection or can be used with a special SQL syntax:
select * from datasource:text{{ some database specific query }})()
Glossary-6
Resource Manager
Prestarted Server A prestarted server is a process which is started when the Daemon starts and kept in a pool. Prestarted servers are immediately available for use by new client processes, saving initialization time. Instead of starting a new Server Process each time one is requested by a client, the client receives a process from the pool of available processes. When the client finishes processing, this server process either dies or, if reusable servers have been set, is returned to the pool of available servers. Process In Attunity terminology, a process is an execution context in which the program code runs. You can have more than one process running the same program. In MVS terminology, a process is equivalent to a task. Query Processor An AIS software component at the core of every data access scenario. The query processor accepts SQL requests from client applications/tools and works in conjunction with query optimizer to devise and implement an access strategy for executing the SQL request. The query processor is distributed by design so that an SQL request may be implemented by a group of query processors on several machines working in tandem. Query Optimizer An AIS software component that is used in choosing an efficient access strategy for a given client SQL request. The AIS Query Optimizer is a cost-based optimizer. It attaches a cost to every potential access strategy according to indexes, cardinality, etc. It then chooses the access strategy with the lowest cost. Referential Integrity Referential integrity is a feature provided by Relational Data Source management systems (RDBMS) that prevents users or applications from entering inconsistent data. Most RDBMS have various referential integrity rules that you can apply when you create a relationship between tables. Relational Data Source In Attunity terminology, relational Data Sources refer to any Backend Database which supports SQL. The most common such data sources are Oracle, SQL Server and DB2. Repository AIS holds information internally in the repository. There are two types of repository: a general repository and a repository per Data Source.
General repository: Also referred to as the SYS repository. Stores all AIS definitions, such as Bindings, Daemons, Adapter Definitions, User Profiles, remote machines, etc. Data source repository: A data source repository can exist for every Data Source. For ADD-based data sources, this repository includes full metadata describing the tables, columns, indexes, etc. For non-ADD-based data sources (e.g. relational data sources) the repository can include extended information, such as cardinality. Such a repository is referred to as Extended ADD.
Resource Manager A software component that is responsible for updating and working with resources such as databases and remote systems.
Glossary-7
Reusable Server
Reusable Server Once the client processing finishes, the server Process does not die and can be used by another client, reducing startup times and application startup overhead. This mode does not have the high overhead of Single Client mode since the servers are already initialized. However, this server mode may use a lot of server resources, since it requires as many server processes as concurrent clients. Schema Part of an adapter definition. The schema is a collection of record definitions referenced by interactions within the Adapter Definition. Server Machine A Machine that can supply data to other machines is called a server. The Query Processor and the inter-machine communications components are generally present on every one of the machines in an AIS network. The Attunity Connect interface programs to the specific Data Sources and Applications generally reside on the same machine as the respective data sources and applications. Single Client Each client receives a dedicated Server Process. The account in which a server process runs is determined either by the client login information or by the specific server Workspace. This mode enables servers to run under a particular user account and isolates clients from each other (since each receives its own process). However, this server mode incurs a high overhead due to process startup times and may use a lot of server resources, since it requires as many server processes as concurrent clients. SQL SQL (Structured Query Language) is a standard interactive and programming language for getting information from and updating a database. Although SQL is both an ANSI and an ISO standard, many database products support SQL with proprietary extensions to the standard language. Queries take the form of a command language that lets you select, insert, update, find out the location of data, and so forth. There is also a programming interface. Staging Area An AIS software component that temporarily stores change events that are read from a journal, making them available for consumption by SQL and XML clients. The staging area is always located on a UNIX or Windows platform machine. Stored Procedure A precompiled collection of transact-SQL statements, stored under a name and processed as a unit that you can call from within another transact-SQL statement or from a client application. Stream A sequence of change events that are read from a given Data Source. See also CDC. Stream Context See Stream Position.
Glossary-8
Virtual Table
Stream Position A reference to a specific change event in a Stream. See also CDC. Sync Point A Stream Position of the last change event in a committed Transaction. A sync point is considered to be a safe point to pause in the processing of a change stream. It is typically used to synchronize the reading of change events of different tables; changes from all tables are read up until the selected sync point. Transaction A set of operations that, as a group, either succeed or fail. Transaction Manager A software component that coordinates the committing of Transactions across multiple Resource Managers. Trigger A set of Structured Query Language (SQL) statements that automatically "fires off" an action when a specific operation, such as changing data in a table, occurs. A trigger consists of an event (an INSERT, DELETE, or UPDATE statement issued against an associated table) and an action (the related procedure). Triggers are used to preserve data integrity by checking on or changing data in a consistent manne Two-phase Commit Also known as 2PC. A protocol for reliably committing changes across multiple systems, even in the case of network failures or node failures. In the protocol, a Transaction Manager calls each participating Resource Manager, first to prepare to commit the changes, and then to actually commit them. These two phases allow the transaction manager to get a commitment from all participating resource managers that they will be able to actually commit the changes. Once all participating resource managers agree to commit, the transaction manager asks each one to commit them. User The person or program acting as a client. User Profile The user profile enables you to provide user name password pairs to access Applications, Data Sources and Server Machines from the Client Machine at runtime without being prompted to supply this information. Upon installation, a default user profile called NAV is created. This user profile is used whenever a client connects without providing a user name. Virtual Table One of the ways that Attunity Connect exposes an array for SQL access. Using virtual tables, one can view arrays within a table as if they were separate tables. Virtual tables have full SQL functionality.
Glossary-9
Virtual View
Virtual View One of the ways that Attunity Connect exposes an array for SQL access. Virtual views enhance performance on joins between a table and an array within it by implementing the join at retrieval time rather than at query processing time. Workspace A logical pool of servers. A server is the smallest service unit managed by the Daemon. Every server belongs to a specific workspace. What a workspace does depends on its Binding. A workspace defines the server processes and environment that is used for the communication between the client and the Server Machine for the duration of the client request. A workspace definition includes the Data Sources and Application Adapters that can be accessed as well as various environment variables.
Glossary-10
Index
See alsoCDC Glossary Def, F-1 Application Adapter Definition Adapter Element, 17-2 Enumeration Element, 17-5 Field Element, 17-7 Interaction Element, 17-3 Overview, 17-1 Record Element, 17-5 Schema Element, 17-4 Variant Record Element, 17-6 Application Adapter Glossary Def, F-1 Array Handling Overview, 7-1 Arrays, 7-1 ATMI Glossary Def, F-1 Attunity Data Dictionary Glossary Def, F-1 Attunity XML Protocol Glossary Def, F-1 Attunity Studio backing up and restoring metadata, 29-3 Axis servlet, 9-3
A
ACX Glossary Def, F-1 ACX Protocol, 15-5 Adapter Database, 69-1 Query, 70-1 Tuxedo, 68-1 Adapter Binding Glossary Def, F-1 Adapter Definition Glossary Def, F-1 ADD Glossary Def, F-1 ADD Syntax, 5-23 adding a daemon, 4-2 adding workspaces, 4-12 Agent Glossary Def, F-1 aggregate functions HAVING clause, B-44 AIS backing up, 29-1 AIS Server data backing up and restroring, 29-3 Application Glossary Def, F-1 Application Access, 15-2 Flow, 15-4 Application Access Flow, 15-4 Application Access Solution, 15-1 Application Adapter, 15-4 CICS, 63-1 COM, 64-1 Definition, 15-4 HP NonStop Pathway, 67-1 IMS/TM, 65-1 Legacy Plug, 66-1 Metadata Example, 15-4 Tuxedo, 68-1 application adapter defaulttdp, 70-16
B
Backend Database Glossary Def, F-2 Backing up, 29-1 AIS Server data, 29-3 AIS Server installation, 29-1 AIS Server metadata, 29-2 Attunity Studio metadata, 29-3 server scripts, 29-3 Basic Import Utility Using the BASIC import utility, 38-1 Binding, 3-1 Glossary Def, F-2 Client Configuration Properties Sample Server Syntax binding configuration, selecting the, 4-24
Index-1
Binding Configuration, 3-1 Binding Syntax, 3-6 BLOB Glossary Def, F-2
C
Captured Data Source Glossary Def, F-2 CDC Glossary Def, F-2 Agent components, 20-2 Change Data Capture Glossary Def, F-2 Change Data Source Glossary Def, F-2 Change File Glossary Def, F-2 Change Router Glossary Def, F-2 Change Table Glossary Def, F-2 Chapter Glossary Def, F-2 ChapView Glossary Def, F-3 CICS Application Adapter, 63-1 CICS Application Adapter Configuration Properties, 63-3 Configuring, 63-4 Defining, 63-3 Installing, 63-3 Overview, 63-1 Setting up metadata, 63-5 Transaction Support, 63-2 CICS Procedure Data Types, 62-6 CICS Procedure Data Source, 62-1 Configuration Properties, 62-2 Configuring, 62-7 Defining, 62-6 Installing, 62-6 Security, 62-5 Setting up metadata, 62-8 Transaction Support, 62-4 CISAM Data Types, 41-2 CISAM Data Source, 41-1 Configuration Properties, 41-1 Configuring, 41-4 Defining, 41-3 Installing, 41-3 Setting up metadata, 41-5 Client Binding, 3-2 Client Interface Glossary Def, F-3 Client Machine Glossary Def, F-3 CLOB
Glossary Def, F-3 COM Application Adapter, 64-1 Registering the application, 64-3 COM Application Adapter, 64-5 Data Types, 64-1 Defining, 64-3 Defining Interactions, 64-3 Overview, 64-1 Configuration Binding Configuration Parameters CICS Procedure Data Source, 62-2 Database Adapter, 69-2 HP NonStop Pathway Application Adapter, IMS/TM Application Adapter, 65-2 Legacy Plug Application Adapter, 66-1 Procedure Data Source (Application Connector), 61-2 Configuration Properties CICS Application Adapter, 63-3 OLEDB-SQL Data Source driver, 50-4 Tuxedo Application Adapter, 68-2 Configuring CICS Application Adapter, 63-4 CICS Procedure Data Source, 62-7 CISAM Data Source, 41-4 Database Adapter, 69-5 DB2 Data Source, 40-10 DBMS Data Source, 42-22 DISAM Data Source, 41-4 Enscribe Data Source, 43-5 HP NonStop Pathway Application Adapter, IMS/DB DBCTL Data Source, 45-14 IMS/DB DBDC Data Source, 45-16 IMS/DB DLI Data Source, 45-12 IMS/TM Application Adapter, 65-3 Ingres Data Source, 47-7 Legacy Plug Application Adapter, 66-2 ODBC Data Source, 48-8 Oracle RDB Data Source, 52-11 Procedure Data Source (Application Connector), 61-10 RDBSQL Data Source, 52-11 RMS Data Source, 53-4 Sybase Data Source, 56-6 Text Delimited File Data Source, 57-2 Virtual Data Source, 58-4 Connect String Glossary Def, F-3 Connecting the Axis servlet, 9-3 Connection Pooling Glossary Def, F-3 creating procedure metadata, 6-37 Creating SQL Queries for the Database Adapter, 69-21
67-2
67-3
D
Daemon
Index-2
Glossary Def, F-3 daemon configuration, 4-10 daemon configuration, 4-10, 4-11 daemon status daemons status, 4-10 daemons, 4-1 adding, 4-2 configuration, 4-11 definition, 4-1 editing, 4-3 shutting down, 4-11 Data Source Glossary Def, F-3 Installing, 52-10 Data Source Metadata, 5-1 ADD Supported Data Types, 5-15 ADD Syntax, 5-23 data source metadata, 6-1 Data Sources CICS Procedure, 62-1 CISAM, 41-1 DB2, 40-1 DBMS, 42-1 DISAM, 41-1 Enscribe, 43-1 IMS, 45-1 Ingres, 47-1 ODBC, 48-1 OLEDB-FS, 49-1 OLEDB-SQL, 50-1 Oracle RDB, 52-1 Procedure (Application Connector), 61-1 RDBSQL, 52-1 RMS, 53-1 Sybase, 56-1 Text Delimited File, 57-1 Virtual, 58-1 Data Type Glossary Def, F-4 Data Types CICS Procedure, 62-6 CISAM, 41-2 COM Application Adapter, 64-1 DB2 Data Source, 40-7 DBMS, 42-3 DISAM, 41-2 Ingres, 47-5 ODBC, 48-4 OLEDB-FS, 49-3 OLEDB-SQL, 50-3 Oracle RDB, 52-9 Procedure Data Source (Application Connector), 61-7 RDBSQL, 52-9 RMS, 53-3 Sybase, 56-3 Tuxedo Application Adapter, 68-3 Database Adapter, 69-1
Glossary Def, F-4 Configuration Properties, 69-2 Configuring, 69-5 Configuring Interactions, 69-5 Creating SQL Queries, 69-21 Defining, 69-4 Installing, 69-4 Interaction Parameters, 69-4 Metadata, 69-2 Overview, 69-1 Transaction Support, 69-4 Databases Virtual, 23-1 DB2 Data Source Configuration Properties, 40-2 Configuring, 40-10 Data Types, 40-7 Defining, 40-8 Functionality, 40-1 Security, 40-7 Setting up meatadata, 40-4 Transaction Support, 40-4 DBMS Data Types, 42-3 DBMS Data Source, 42-1 Configuration Properties, 42-3 Configuring, 42-22 Defining, 42-21 Error Codes, 42-15 Installing, 42-21 Setting up metadata, 42-23 Virtual Columns, 42-5 Defining CICS Application Adapter, 63-3 CISAM Data Source, 41-3 COM Application Adapter, 64-3 Database Adapter, 69-4 DB2 Data Source, 40-8 DBMS Data Source, 42-21 DISAM Data Source, 41-3 Enscribe Data Source, 43-4 HP NonStop Pathway Application Adapter, IMS/DB DBCTL Data Source, 45-13 IMS/DB DBDC Data Source, 45-16 IMS/DB DLI Data Source, 45-11 IMS/TM Application Adapter, 65-3 Ingres Data Source, 47-6 Legacy Plug Application Adapter, 66-2 ODBC Data Source, 48-6 OLEDB-FS Data Source, 49-4 OLEDB-SQL Data Source, 50-4 Procedure Data Source, 61-10 RDBSQL Data Source, 52-10 RMS Data Source, 53-3 Sybase Data Source, 56-5 Text Delimited File Data Source, 57-2 Virtual Data Source, 58-3 Defining a Virtual Database Defining an adapter as a Web service, 9-3 Defining Data Types, 64-5
67-2
Index-3
design time, 4-1 disabling a workspace workspaces disabling, 4-25 DISAM Data Types, 41-2 DISAM Data Source, 41-1 Configuration Properties, 41-1 Configuring, 41-4 Defining, 41-3 Installing, 41-3 Setting up metadata, 41-5 Driver Glossary Def, F-4 Drivers CICS Procedure, 62-1 CISAM, 41-1 DB2, 40-1 DBMS, 42-1 DISAM, 41-1 Enscribe, 43-1 IMS, 45-1 Ingres, 47-1 ODBC, 48-1 OLEDB-FS, 49-1 OLEDB-SQL, 50-1 Oracle RDB, 52-1 Procedure (Application Connector), 61-1 RDBSQL, 52-1 RMS, 53-1 Sybase, 56-1 Text Delimited File, 57-1 Virtual, 58-1
F
File Pool Glossary Def, F-4 Data Source (File-system) Glossary Def, F-4 File-system Data Source Glossary Def, F-4
G
Glossary, F-1
H
Handling Arrays, 7-1 HAVING clause aggregate functions, B-44 HP NonStop Pathway Application Adapter, 67-1 HP NonStop Pathway Application Adapter Configuration Parameters, 67-2 Configuring, 67-3 Defining, 67-2 Installing, 67-2 Overview, 67-1 Setting up metadata, 67-4 Transaction Support, 67-1
I
import COBOL, 6-14 Importing Metadata Using a Standalone Utility, 5-3 Using Attunity Studio, 5-2 importing metadata, 6-14, 43-7 Importing Procedure Metadata, 5-5 importing procedure metadata, 6-37 IMS Data Source, 45-1 Configuration Properties, 45-7 Setting up metadata, 45-18 IMS/DB DBCTL Data Source Configuring, 45-14 Defining, 45-13 Installing, 45-13 IMS/DB DBDC Data Source Configuring, 45-16 Defining, 45-16 Installing, 45-16 IMS/DB DLI Data Source Configuring, 45-12 Defining, 45-11 Installing, 45-11 IMS/TM Application Adapter, 65-1 IMS/TM Application Adapter Configuration Parameters, 65-2 Configuring, 65-3 Defining, 65-3
E
editing a daemon, 4-3 Daemon Control tab, 4-3 Daemon Logging tab, 4-5 Daemon Security tab, 4-8 editing workspaces, 4-15 Enscribe Data Source, 43-1 Configuration Properties, 43-2 Configuring, 43-5 Defining, 43-4 Installing, 43-4 Setting up metadata, 43-6 Environment Properties, 3-12 Error Codes DBMS Data Source, 42-15 ETL Glossary Def, F-4 Event Glossary Def, F-4 Event Queue Glossary Def, F-4 Extended ADD Glossary Def, F-4 Extended Metadata, 5-4 Extract, Transform, Load
Index-4
Installing, 65-3 Overview, 65-1 Setting up metadata, 65-4 Transaction Support, 65-1 Ingres Data Types, 47-5 Ingres Data Source, 47-1 Configuration Properties, 47-3 Configuring, 47-7 Defining, 47-6 Installing, 47-6 Installing CICS Application Adapter, 63-3 CICS Procedure Data Source, 62-6 CISAM Data Source, 41-3 Database Adapter, 69-4 DBMS Data Source, 42-21 DISAM Data Source, 41-3 Enscribe Data Source, 43-4 HP NonStop Pathway Application Adapter, IMS/DB DBCTL Data Source, 45-13 IMS/DB DBDC Data Source, 45-16 IMS/DB DLI Data Source, 45-11 IMS/TM Application Adapter, 65-3 Ingres Data Source, 47-6 Legacy Plug Application Adapter, 66-2 ODBC Data Source, 48-6 Procedure Data Source (Application Connector), 61-10 RDBSQL Data Source, 52-10 RMS Data Source, 53-3 Sybase Data Source, 56-5 Text Delimited File Data Source, 57-2 Virtual Data Source, 58-3 Interaction Glossary Def, F-4 Interaction Parameters Database Adapter, 69-4 Interactions as Web services, 9-7 IRPCD Glossary Def, F-5 IRPCDCMD REXX script, 37-21 Isolation Level Glossary Def, F-5
Legacy Plug Application Adapter, 66-1 Legacy Plug Application Adapter Configuration Parameters, 66-1 Configuring, 66-2 Defining, 66-2 Installing, 66-2 Overview, 66-1 Setting up metadata, 66-3 Lock Glossary Def, F-5 logging level, 21-20 LOJ Glossary Def, F-5
M
67-2 Machine Glossary Def, F-5 Managing Metadata, 5-3 managing procedure metadata, 6-37 Mapfiles using, 38-1 Master password, 37-22 Metadata, 5-1, 5-5 Glossary Def, F-5 AIS Server backing up, 29-2 backing up, 29-2 Caching Native Metadata, 5-4 Extending, 5-4 for DataSources, 5-1 For Virtual Databases Importing, 5-2 Importing Procedure Managing, 5-3 Procedure metadata, 6-1 data source metedata, 6-1 general table information, 6-2 import wizard, 6-14 importing, 6-14, 43-7 procedure metadata, 6-36 table columns configuration, 6-4 table index, 6-8 table statistics, 6-9 tabs, 6-2 Metadata Definition Tuxedo Application Adapter, 68-5 metadata import wizard, 6-14 metadata tabs, 6-2 Metadata, Definition Defining for CICS Application Adapter, 63-5 Defining for CICS Procedure Data Source, 62-8 Defining for CISAM Data Source, 41-5 Defining for DB2 Data Source, 40-4 Defining for DBMS Data Source, 42-23 Defining for DISAM Data Source, 41-5 Defining for Enscribe Data Source, 43-6 Defining for HP NonStop Pathway Application
J
JCA Connecting to AIS Server, 86-1 ConnectionFactory parameters, 86-2 Logging mechanism, 86-15 Metadata enhancement objects, 86-5 Overview, 86-1 RECORD enhancement classes, 86-6 Supported interfaces, 86-3
L
Languages, 3-25
Index-5
Adapter, 67-4 Defining for IMS Data Source, 45-18 Defining for IMS/TM Application Adapter, 65-4 Defining for Legacy Plug Application Adapter, 66-3 Defining for Procedure Data Source (Application Connector), 61-11 Defining for RMS Data Source, 53-5 Defining for Text Delimited File Data Source, 57-3 Tuxedo Application Adapter, 68-2
Data Types, 52-9 Oracle RDB Data Source, 52-1 Configuration Properties, 52-6 Configuring, 52-11 SQL Capabilities, 48-2, 51-6, 52-4 Ownership Glossary Def, F-6
P
Passthrough Glossary Def, F-6 Passthru Glossary Def, F-6 Predefined interactions query adapter, 70-2 Predict Glossary Def, F-6 Prestarted Server Glossary Def, F-7 Procedure Data Source, 61-1 Configuration Properties, 61-2 Configuring, 61-10 Data Types, 61-7 Defining, 61-10 Installing, 61-10 Security, 61-7 Setting up metadata, 61-11 Transaction Support, 61-7 Procedure Metadata procedure metadata, 6-36 ceate manually, 6-37 importing, 6-37 managing, 6-37 Procedure Metadata Statements, 5-6 Process Glossary Def, F-7 Properties, 3-12
N
Native File System Glossary Def, F-5 Native Metadata Caching, 5-4 Native Object Store (NOS) Glossary Def Native Object], F-6 NAV Glossary Def, F-5 NAV_UTIL Glossary Def, F-6 using, 37-2 NAV_UTIL Command Line Utility, 37-1 NAV_UTIL Options, 37-2 NAVDEMO Glossary Def, F-6 Navigator Glossary Def, F-6 NAVROOT Glossary Def, F-6 NAV.SYN Glossary Def, F-5 NOS Glossary Def, F-6
O
ODBC Data Types, 48-4 ODBC Data Source, 48-1 Configuration Properties, 48-3 Configuring, 48-8 Defining, 48-6 Installing, 48-6 OLE DB IMAGE fields, 89-12 TEXT fields, 89-12 OLEDB-FS Data provider requirements, 49-1 Functionality, 49-2 OLEDB-FS Data Source, 49-1 Configuration Properties, 49-3 OLEDB-FS Data source Defining, 49-4 OLEDB-SQL Data provider requirements, 50-1 Functionality, 50-2 Oracle RDB
Q
Queries Managing over large tables, 71-1 Query Adapter, 70-1 Metadata, 70-1 Overview, 70-1 Transaction Support, 70-2 Query adapter interactions, 70-2 usage, 70-16 Query Analyzer, 36-1 icons, 36-4 toolbar, 36-3 Query analyzer generating a plan for SQL statements, 36-2 optimization plan, 36-5 SQL statement plan, 36-2 viewing the execution Plan, 36-2 query application adapter defaulttdp, 70-16
Index-6
Query Governor, 71-1 Query Optimizer Glossary Def, F-7 Query Processor Glossary Def, F-7
R
RDBSQL Data Types, 52-9 RDBSQL Data Source, 52-1 Configuration Properties, 52-6 Configuring, 52-11 Defining, 52-10 Installing, 52-10 SQL Capabilities, 48-2, 51-6, 52-4 Referential Integrity Glossary Def, F-7 Data Source (Relational) Glossary Def, F-7 Relational Data Source Glossary Def, F-7 Repository Glossary Def, F-7 Resource Manager Glossary Def, F-7 Restoring server scripts, 29-3 Reusable Server Glossary Def, F-8 RMS Data Types, 53-3 RMS Data Source, 53-1 Configuration Properties, 53-2 Configuring, 53-4 Defining, 53-3 Installing, 53-3 Setting up metadata, 53-5
Glossary Def, F-8 SQL utility connecting to AIS Server, 32-2 Modifying data in a recordset, 32-4 specifying and executing queries, 32-2 using the, 32-1 working with chapters, 32-4 Staging Area Glossary Def, F-8 Statements Procedure Metadata Stored Procedure Glossary Def, F-8 Stored Procedures In Virtual Databases Stream Glossary Def, F-8 Stream Context Glossary Def, F-8 Stream Position Glossary Def, F-9 Supported Languages, 3-25 Sybase Data Types, 56-3 Sybase Data Source, 56-1 Configuration Properties, 56-2 Configuring, 56-6 Defining, 56-5 Environment variables, 56-7 Installing, 56-5 Sync Point Glossary Def, F-9 Synonyms Creating in Virtual Databases
T
Text Delimited File Data Source, 57-1 Configuration Properties, 57-1 Configuring, 57-2 Defining, 57-2 Setting up metadata, 57-3 Transaction Glossary Def, F-9 Transaction Manager Glossary Def, F-9 Transaction Support CICS Application Adapter, 63-2 CICS Procedure Data Source- CICS Procedure Data Source Two-phase commit, 62-4 Data Source Capabilities, 30-3 Data Sources That Do Not Support Transactions, 30-3 Data Sources with One-Phase Commit Capability, 30-3 Data Sources with Two-Phase Commit Capability, 30-4 Database Adapter, 69-4 DB2 Data Source, 40-4
S
Schema Glossary Def, F-8 Security CICS Procedure Data Source, 62-5 Procedure Data Source (Application Connector), 61-7 selecting a binding configuration, 4-24 Server backing up, 29-1 Binding restore installation, 29-1 Server Binding, 3-1 Server Machine Glossary Def, F-8 Server scripts backing up, 29-3 Setting up the system for Web services, 9-1 Single Client Glossary Def, F-8 SQL
Index-7
HP NonStop Pathway Application Adapter, 67-1 IMS/TM Application Adapter, 65-1 in application adapters, 15-6 in applications, 15-6 OLEDB-FS, 49-3 OLEDB-SQL, 50-3 Overview, 30-1 Procedure Data Source (Application Connector), 61-7 Query Adapter, 70-2 Recovery, 30-7 Stand-alone Transaction Coordinator, 30-2 Tuxedo Application Adapter, 68-2 Trigger Glossary Def, F-9 Tuxedo Application Adapter, 68-1 Tuxedo Application Adapter Checking environment variables, 68-3 Configuration Properties, 68-2 data types, 68-3 Defining, 68-3 Metadata, 68-2 Overview, 68-1 Setting up metadata, 68-5 Transaction Support, 68-2 Two-phase Commit Glossary Def, F-9 2PC Glossary Def, F-9
Using Virtual Table Glossary Def, F-9 Virtual View Glossary Def, F-10
W
Web Services, 9-1 prerequisites, 9-1 Web services advanced connection settings map, 9-6 pooling, 9-5 advanced connections settings general, 9-5 connecting the Axis servlet, 9-3 defining an adapter as a Web service, 9-3 logs, 9-10 preparing the system, 9-1 selecting interactions, 9-7 undeploying, 9-9 viewing deployed Web services, 9-9 Web services wizard, 9-2 Working with parameterized queries, 32-3 Workspace Glossary Def, F-10 Workspace server mode, 4-20 workspaces adding, 4-12 editing, 4-15 general tab, 4-16 Server Mode tab, 4-19 WS Security tab, 4-22
U
Undeploying Web services, 9-9 User Glossary Def, F-9 User Profile Glossary Def, F-9 Using SQL utility, 32-1 the Query analyzer, 36-1 Using a Virtual Database, 23-8 Using Arrays, 7-1
X
XML Protocol, 15-5
V
Viewing deployed Web services, 9-9 Views In Virtual Databases Virtual Data Source, 58-1 Configuration Properties, 58-1 Configuring, 58-4 Defining, 58-3 Installing, 58-3 Virtual Database, 23-1 Creating Synonyms for Creating Views in Defining Defining Strored Procedures for Defining Tables in
Index-8