Advantage Data Transformer

Transcription

1 Advantage Data Transformer Generic ODBC Interface Guide r2.2 A E

2 This documentation and related computer software program (hereinafter referred to as the "Documentation") is for the end user's informational purposes only and is subject to change or withdrawal by Computer Associates International, Inc. ("CA") at any time. This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part, without the prior written consent of CA. This documentation is proprietary information of CA and protected by the copyright laws of the United States and international treaties. Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this documentation for their own internal use, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the license for the software are permitted to have access to such copies. This right to print copies is limited to the period during which the license for the product remains in full force and effect. Should the license terminate for any reason, it shall be the user's responsibility to return to CA the reproduced copies or to certify to CA that same have been destroyed. To the extent permitted by applicable law, CA provides this documentation "as is" without warranty of any kind, including without limitation, any implied warranties of merchantability, fitness for a particular purpose or noninfringement. In no event will CA be liable to the end user or any third party for any loss or damage, direct or indirect, from the use of this documentation, including without limitation, lost profits, business interruption, goodwill, or lost data, even if CA is expressly advised of such loss or damage. The use of any product referenced in this documentation and this documentation is governed by the end user's applicable license agreement. The manufacturer of this documentation is Computer Associates International, Inc. Provided with "Restricted Rights" as set forth in 48 C.F.R. Section , 48 C.F.R. Sections (c)(1) and (2) or DFARS Section (c)(1)(ii) or applicable successor provisions Computer Associates International, Inc. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

3 Contents Chapter 1: Database Profiles 5 Database Profiles Description... 5 Use Database Profiles... 5 Create a Database Profile... 5 Use Connection Parameters in Profiles... 6 Connection Parameter Fields... 6 Chapter 2: Communication Handlers Introduction 9 What are Communications Handlers?... 9 Summary of Handlers... 9 Profile Handles Parameters Case Sensitivity Return Values CONNECT Purpose Syntax Comments Examples SEND Purpose Syntax Comments Examples LOAD Purpose Syntax Comments Examples STORE Purpose Syntax Comments Examples DISCONNECT Purpose Syntax Contents iii

4 Examples Chapter 3: Data Type Conversions 27 Data Type Overview Microsoft Access ODBC Data Type Tables Data Type Conversions in Data Transfers Data Type Conversions in Table Creations Loading Access Data into Advantage Data Transformer Storing Access Data from Advantage Data Transformer dbase ODBC Data Type Tables Data Type Conversions in Data Transfers Data Type Conversions in Table Creations Loading dbase Data into Advantage Data Transformer Storing dbase Data from Advantage Data Transformer TEXT ODBC Data Type Tables Data Type Conversions in Data Transfers Data Type Conversions in Table Creation Loading TEXT ODBC Data into Advantage Data Transformer Storing TEXT ODBC Data from Advantage Data Transformer Generic ODBC SQL Data Type Tables Data Type Conversions in Data Transfers Loading Generic ODBC SQL Data into Advantage Data Transformer Storing Generic ODBC SQL Data from Advantage Data Transformer Appendix A: Return Values for Communication Handlers 43 Generic Return Values Index 47 iv Generic ODBC Interface Guide

5 Chapter 1: Database Profiles Advantage Data Transformer moves data from a source database to a destination database. The source and destination databases are typically different types. This guide describes the information that is needed to access data in a specific source or destination database, or using a particular driver. This chapter introduces database profiles, interfaces, communications handlers, and the Profile Editor connection parameters used by Advantage Data Transformer to access the data formats covered by this guide. Database Profiles Description A database profile (also called a profile) is an object containing database connection information and identifies the Advantage Data Transformer interface used to establish a connection to a source or destination database. A profile can contain connection information such as a database name and login information. An Advantage Data Transformer interface is a set of executable modules that implement the script function calls interacting with a database. The interface is responsible for converting these common script functions into database-specific code. The interface allows you to access different database types using a common set of functions, called communications handlers. Each database type has a corresponding interface that allows scripts to access that database. A profile is associated with a specific database type by selecting the corresponding interface type in the Profile Editor. For more information about the set of common database access functions, see the chapter "Communications Handlers." Use Database Profiles Use profiles to: Create a data transfer Enable a communications handler in a script Create a Database Profile To create a profile, use the Script Manager, Profile Editor. For more information about creating a profile, see the online help in the Script Manager. Database Profiles 5

6 Use Connection Parameters in Profiles Use Connection Parameters in Profiles This section describes a subset of database profile fields containing connection parameter values used for logging on to the database covered by this guide. Note: As an alternative, you can also define and override these connection parameter values by using the CONNECT communications handler in a script. Connection Parameter Fields The following table describes the profile fileds you use to provide connection parameter values to a database through an ODBC driver: Profile Field Action Corresponding CONNECT Handler Parameter Interface Tab Select interface Select the interface from the following: Access/Microsoft ODBC Driver For an Access database. dbase/microsoft ODBC Driver For a dbase database. Text file/microsoft ODBC Driver For a text (flat) file. Generic ODBC For a database or text (flat) file. 6 Generic ODBC Interface Guide

7 Use Connection Parameters in Profiles Profile Field Action Corresponding CONNECT Handler Parameter Server/Database Tab Select server Select database Enter connection/ form information Select the server from the following: The name of the ODBC data source defined to point to the Access database (as defined with the ODBC Data Source Administrator and using a Microsoft Access ODBC driver). The name of the ODBC data source defined to point to the dbase database (as defined with the ODBC Data Source Administrator and using a Microsoft dbase ODBC driver). The name of the ODBC data source defined to point to a text (flat) file (as defined with the ODBC Data Source Administrator and using a Microsoft Text ODBC driver). The name of the ODBC data source defined to point to a database or text (flat) file (as defined with the ODBC Data Source Administrator and using a third-party vendor ODBC driver). Leave blank. Leave blank. #SERVER Database Profiles 7

8 Use Connection Parameters in Profiles Profile Field Action Corresponding CONNECT Handler Parameter Login Tab Enter login name Enter password Enter the user ID needed for accessing a database. Note: Advantage Data Transformer access rights are the same as those associated with the specified user ID. Enter the password associated with the user ID above. #LOGIN #PASSWORD 8 Generic ODBC Interface Guide

9 Chapter 2: Communication Handlers Introduction This chapter describes the communications handlers (functions) that let the Advantage Data Transformer Server interact with the database or data format covered by this guide. What are Communications Handlers? Communications handlers (or simply handlers) provide a common function set that enables the Server to interact with different databases or data formats. Handlers establish and terminate connections, issue queries and other commands, and move data to and from a database or other data repository. A particular interface converts these common script functions into databasespecific code. The common function set includes: CONNECT, SEND, LOAD, STORE, and DISCONNECT. Note: For more information on communications handlers, see the Advantage Data Transformer Script Language Reference. Summary of Handlers Note: Some differences and limitations may exist between different databases using the ODBC interface. This is due to different levels of support offered by the underlying ODBC drivers. The Server provides five communications handlers for the ODBC interface. This chapter lists them in the order that they typically appear in a script. Handler Purpose CONNECT SEND LOAD STORE DISCONNECT Connects to a database. Issues a query or other command to a database. Copies data queried from one or more source tables to an instance of a structure. Copies data from a structure instance to a destination table. Disconnects from a database. Communication Handlers Introduction 9

10 Profile Handles Profile Handles Each communications handler references a database profile. Profiles are referenced through a profile handle. Declare a profile handle with a DEF statement. The following example declares a profile handle named dest_profile. The dest_profile handle identifies an Advantage Data Transformer database profile named sales_2005. The database profile, sales_2005, must be created in a separate step using the Profile Editor, and the appropriate database connection information must be specified. Dest_profile is then referenced by a CONNECT handler (which takes no parameters in this example, so it uses the information specified in the profile, sales_2005 to complete the connection): DEF dest_profile AS PROFILE = "sales_2005"... CONNECT dest_profile () Note: For more information about profile handles, see the Advantage Data Transformer Script Language Reference. Parameters Communications handlers can take zero (0) or more parameters. A parameter, identified by a pound sign (#), is expressed as a name followed by a value. This LOAD handler has two parameters, #DATA and #BIND_RANGE_CHECK: LOAD dest_profile (#DATA struct, #BIND_RANGE_CHECK_RANGE_CHECK_WARNING) Enclose a handler s parameters in parentheses and separate them by commas. List parameters in any order. The constant _RANGE_CHECK_WARNING is defined in the Advantage Data Transformer code fragment, RangeCheckCodes. If you do not specify any parameters for a handler, you still have to include the parentheses, as in this example: DISCONNECT dest_profile () Case Sensitivity Parameter names are not case-sensitive. 10 Generic ODBC Interface Guide

11 Return Values Return Values All communications handlers return an integer value that indicates whether the operation succeeded or failed: A zero (0) indicates success. A negative value indicates a warning. A positive value indicates failure. Advantage Data Transformer provides a predefined code fragment named HandlerReturnCodes that assigns these integers to constants that are more descriptive. For example, _IPRET_SUCCESS is the predefined constant that represents 0. For more information about other values and their corresponding constants, see the appendix Return Values for Communications Handlers. CONNECT Purpose Establishes a connection to a database through its ODBC driver. Syntax CONNECT profile_handle (#SERVER string, #LOGIN string, #PASSWORD string, #AUTO_COMMIT Boolean, #ROW_BUFFERS integer, #QUERY_CATALOG Boolean) Parameter profile_handle Description The database profile handle previously declared in your script. Declare a profile handle with the DEF statement. Communication Handlers Introduction 11

12 CONNECT Parameter #SERVER string Description The name of the ODBC data source that the Server will use for loading or storing data. If this parameter is not specified, the Server uses the server name specified in the profile. Enter or modify the name in the Server/Database tab of the Profile Editor in the Advantage Data Transformer Script Manager. #LOGIN string The user ID needed to access the database. The access rights for the Server are the same as those associated with this user ID. If this parameter is not specified, the Server uses the login information specified in the profile. You can enter or modify this ID, called a login name, in the Login tab of the Profile Editor in the Script Manager. #PASSWORD string The password associated with the database user ID. A password may also exist in the profile. You can enter or modify this password in the Login tab of the Profile Editor in the Script Manager. #AUTO_COMMIT Boolean A value that controls whether Advantage Data Transformer automatically commits each STORE operation to the database. Valid values are: TRUE Automatically commit modifications to the database following each STORE operation. FALSE Commit modifications to the database only when a SEND or STORE handler is called with the #COMMIT TRUE parameter. This is the default setting. Note: These values are not case-sensitive. 12 Generic ODBC Interface Guide

13 CONNECT Parameter #ROW_BUFFERS integer Description The number of data rows you want placed in a buffer for STORE and LOAD operations. Use row buffering to limit network traffic. This setting becomes the default for the life of the connection to this profile handle. The default is one row. In addition, #ROW_BUFFERS must be changed to 1 in a STORE operation that uses this profile handle when you have set #MODE to these settings: _DELETE_MODE, _INS_THEN_UPD, or _UPD_THEN_INS. #QUERY_CATALOG Boolean A value that controls how the Server obtains a database s column descriptions for the target table during STORE operations. This setting becomes the default for the life of the connection to this profile handle. Valid values are: TRUE Query the database s catalogs to get the column descriptions. Unless you are prohibited from performing queries against the database s catalogs, you should use this value. FALSE Use an SQL query to get the column descriptions. With this method, the Server may perform a table scan, but it does not need access to database catalogs. However, you may experience degraded performance during the STORE operation with this value. This is the default setting. Communication Handlers Introduction 13

14 CONNECT Comments Controlling Transactions If a CONNECT parameter value is defined both in a profile and as a CONNECT parameter in your script, the value in the script takes precedence. Note: If the profile has login and password information but the CONNECT handler in the script has a parameter value overriding only the login (#LOGIN), the Server does not use the password information from the profile. You must specify the new login s password, too, using the #PASSWORD parameter. If the new login does not have a password or has a blank password, include the #LOGIN parameter and do not include the #PASSWORD parameter in the CONNECT handler. You control database transactions with a combination of the following parameters: #AUTO_COMMIT parameter of the CONNECT handler #COMMIT parameter of the STORE handler #COMMIT and #ROLLBACK parameters of the SEND handler #COMMIT and #ROLLBACK parameter of the DISCONNECT handler If the CONNECT handler is called with #AUTO_COMMIT TRUE, then Advantage Data Transformer automatically commits every modification to the database. Each successful SEND and STORE transaction is committed regardless of how their #COMMIT and #ROLLBACK parameters are set. If the CONNECT handler is called with #AUTO_COMMIT FALSE, to commit any modifications to the database, you should specify #COMMIT TRUE in the STORE or SEND handlers. Note: While the DISCONNECT handler with #COMMIT TRUE automatically attempts to commit outstanding transactions, do not rely on this method. If the Server has difficulty disconnecting from the database, transactions may or may not be committed. This depends on how the database handles the data. 14 Generic ODBC Interface Guide

15 SEND Examples The following example provides access to the ODBC data source named Generic. Automatic commitment of transactions is disabled. CONNECT dest_profile (#SERVER "Generic", #AUTO_COMMIT FALSE) If the value for the #SERVER parameter is included in the definition of the profile referenced by dest_profile and you want to use it, write the CONNECT handler this way: CONNECT dest_profile (#AUTO_COMMIT FALSE) SEND Purpose Sends SQL commands to a database. The database s SQL engine performs the commands and, in the case of SELECT statements, prepares the Server to retrieve the resulting data (through the LOAD handler). Syntax SEND profile_handle (#QUERY string, #COMMIT Boolean, #ROLLBACK Boolean) Parameter profile_handle Description The database profile handle previously declared in your script. Declare a profile handle with the DEF statement. Note: You must execute a CONNECT statement before executing the SEND command. #QUERY string The SQL commands you want to send. The string can be a literal value, a constant, or a variable. You must enclose literal values in double quotes. Communication Handlers Introduction 15

16 SEND Parameter #COMMIT Boolean Description A value that controls whether the Server commits all outstanding database modifications before executing the query. Valid values are: TRUE Commit outstanding modifications to the database before executing the query. FALSE Do not commit outstanding modifications to the database before executing the query. This is the default setting. Note: These values are not case-sensitive. Note: If #AUTO_COMMIT is TRUE in the CONNECT handler, then the STORE handler commits all modifications, regardless of the value of this #COMMIT parameter. #ROLLBACK Boolean A value that controls whether the Server rolls back all outstanding database modifications before executing the query. Valid values are: TRUE Rollback modifications to the database before executing the query. FALSE Do not rollback modifications to the database before executing the query. This is the default setting. Note: These values are not case-sensitive. Note: If #AUTO_COMMIT is TRUE in the CONNECT handler, then the STORE handler commits all modifications. No outstanding modifications remain to be rolled back. 16 Generic ODBC Interface Guide

17 LOAD Comments If the #COMMIT parameter is TRUE, the Server executes the #COMMIT parameter before any others. If the #QUERY parameter is an empty string and the #COMMIT or #ROLLBACK parameter is TRUE, then the outstanding modifications to the database are committed or rolled back and the SEND handler returns _IPRET_SUCCESS. If both the #COMMIT and #ROLLBACK parameters are TRUE, then the SEND handler returns _IPRET_PARM_CONFLICT. The Microsoft ODBC TEXT driver does not support use of the SQL DELETE and SQL UPDATE commands with the SEND handler. Examples This first example sends a SELECT statement to the database through the SEND handler. Here, the SELECT statement is expressed as a literal: SEND source_profile (#QUERY "select from q3sales") This next example sends the same SELECT statement through the q3sales_query variable: DEF q3sales_query AS STRING q3sales_query = "select from q3sales"... SEND source_profile (#QUERY q3sales_query) This example commits all outstanding modifications made to the database since the start of the script or the last commit: SEND source_profile (#QUERY, #COMMIT TRUE) LOAD Purpose Loads data from a source database into a script structure instance (or element in an array of structure instances). After you use the SEND handler to send a SELECT statement to the source database, use the LOAD handler to load the returned data into the structure instance. Communication Handlers Introduction 17

18 LOAD Syntax LOAD profile_handle (#DATA structure_instance_name, #RANGE_CHECK Boolean) Parameter profile_handle Description The database profile handle previously declared in your script. Declare a profile handle with the DEF statement. Note: A CONNECT and a SEND of a query must be performed prior to executing the LOAD. #DATA structure_instance_name The structure instance (or element in an array of structure instances) where the Server places data retrieved from the database. #RANGE_CHECK Boolean A value indicating whether the Server checks the data type of each value being returned. If range checking is enabled and the returned value has a data type that allows a wider range of values than the corresponding Advantage Data Transformer data type, the range check fails. The corresponding Advantage Data Transformer data type is the data type of the structure field being loaded with the data. Note: For more information, see the Advantage Data Transformer Script Language Reference for the value range of each Data Transformer data type. Valid values are: TRUE Range-checking enabled. If an attempt is made to load an out-of-range data type, an error occurs and LOAD stops executing. This is the default setting. FALSE Range-checking disabled. If an attempt is made to load an out-of-range data type, no error occurs and LOAD completes the load operation. However, numeric data may lose precision, and text may be truncated. Note: These values are not case-sensitive. 18 Generic ODBC Interface Guide

19 STORE Comments The LOAD handler is usually followed by the STORE handler. After LOAD moves a row of returned data into the structure instance, STORE moves the row out of the structure instance and into the destination table. LOAD and STORE move one data row at a time. Consequently, LOAD and STORE are typically used with a flow-control statement (such as a DO WHILE loop). For details about flow-control statements, see the Advantage Data Transformer Script Language Reference Guide. The table columns returned by a query must correspond to the fields in the structure instance as to number, position, and data type. Otherwise, the LOAD operation fails. When the Server loads data, it converts ODBC data types to comparable Advantage Data Transformer data types. See the Data Type Conversions chapter for details. Examples In this example, the LOAD handler loads one data row at a time into the structure instance named struct_inst. The STORE handler then writes the data from the structure instance to the q3sales table. DO WHILE ( LOAD source_profile ( #DATA struct_inst, #RANGE_CHECK FALSE) = _IPRET_SUCCESS ) STORE dest_profile ( #DATA struct_inst, #TABLE "q3sales", #CREATE FALSE, #UPDATE TRUE, #MAP_TYPE TRUE ) LOOP Notice that the DO WHILE loop continues executing LOAD and STORE until the LOAD operation fails (that is, until there are no more rows to load). STORE Purpose Moves data from a loaded structure instance (or element in an array of structure instances) into a table or file, depending on the target database. Communication Handlers Introduction 19

20 STORE Syntax STORE profile_handle (#DATA structure_instance_name, #TABLE string, #CREATE Boolean, #MAP_TYPE Boolean, #MODE integer, #ROW_BUFFERS integer, #QUERY_CATALOG Boolean, #COMMIT Boolean) Parameter profile_handle Description The database profile handle previously declared in your script. Declare a profile handle with the DEF statement. Note: You must execute a CONNECT statement before executing the STORE command. #DATA structure_instance_name #TABLE string The structure instance (or element in an array of structure instances) that holds the data row to be stored. The table where the data is stored. The table name must be valid in the target database. #CREATE Boolean A value that specifies whether the Server should create a table if one does not exist. Valid values are: TRUE Create a table if the table specified in the #TABLE parameter does not exist. FALSE Do not create the table. This is the default setting. Note: These values are not case-sensitive. Note: #CREATE should only be TRUE when #UPDATE is FALSE. #MODE Integer For more information #MODE Integer, see the Note following this section. 20 Generic ODBC Interface Guide

21 STORE Parameter #MAP_TYPE Boolean Description A value that indicates how the Server handles the situation where storing a field results in some data loss (text truncation or loss of precision). Data loss can occur when the database does not support a data type comparable to the Advantage Data Transformer data type of the field being stored. Valid values are: TRUE Where possible, force conversion to a usable ODBC data type, even if the conversion results in precision loss or text truncation. FALSE Do not force conversion to a data type that results in precision loss or text truncation. If a data type mismatch occurs, the STORE handler returns the communication error, _IPRET_UNSUPPORTED_TYPE. This is the default setting. Note: These values are not case-sensitive. #ROW_BUFFERS integer The number of data rows you want sent to the database with one call. The STORE handler places each row in the buffer. Once the buffer is filled, the Server makes the database call. Use row buffering to limit network traffic. If you specified #ROW_BUFFERS in the CONNECT handler for the profile handle used in this STORE handler, that setting is the default. Otherwise, the default is one row. Note: #ROW_BUFFERS must be changed to 1 in a STORE operation that uses this profile handle when you have set #MODE to these settings: _DELETE_MODE, _INS_THEN_UPD, or _UPD_THEN_INS. #QUERY_CATALOG Boolean A value that controls how the Server obtains a database s column descriptions for the target table during a STORE operation. Valid values are: TRUE Query the database s catalogs to get the column descriptions. Unless you are prohibited from performing queries against the database s catalogs, you should use this value. Communication Handlers Introduction 21

22 STORE Parameter Description FALSE Use an SQL query to get the column descriptions. With this method, the Server may have to perform a table scan, but it does not need access to database catalogs. However, you may experience degraded performance during the STORE operation with this value. This is the default setting. If #QUERY_CATALOG was specified in the CONNECT handler for the profile handle used in this STORE handler, that setting is the default. #COMMIT Boolean A value that controls whether the Server commits all outstanding database modifications after executing the STORE operation. Valid values are: TRUE Commit outstanding modifications to the database after executing the STORE operation. This is the default setting. FALSE Do not commit outstanding modifications to the database after executing the STORE operation. Note: These values are not case-sensitive. Note: If #AUTO_COMMIT is TRUE in the CONNECT handler, then the STORE handler commits all modifications, regardless of the value of this #COMMIT parameter. 22 Generic ODBC Interface Guide

23 STORE Note: #MODE_Integer A value that indicates what action you want this STORE operation to perform. You must create at least one UPDATEKEY field in the destination structure definition for all actions except inserting data. These fields tend to correspond to primary keys in the destination table, but they do not have to. The Server uses UPDATEKEY fields to locate rows that you want to update or delete. If a value in an UPDATEKEY field matches the value in the corresponding column of a row in the destination table, the Server performs the specified action. An UPDATEKEY field does not have to be unique. Note: Define UPDATEKEY fields when declaring the structure definition. For information about structure definitions, see the Advantage Data Transformer Script Language Reference. For information about the UPDATEKEY parameter, refer to the online help in the Script Manager. Descriptive values for this parameter appear in the predefined code fragment named MiscellaneousCodes. We recommend including this fragment in your script. (See the online help in the Script Manager for instructions.) These are the constants listed in MiscellaneousCodes for this parameter: _INSERT_MODE-Insert new rows into a destination table. If the Server cannot insert a row-for example, the row is already there-an error occurs. The integer value assigned to this constant is 1. This is the default setting. Inserting involves either creating a table if none exists (#CREATE must be TRUE) or adding new rows to an existing table. If the destination structure instance contains UPDATEKEY fields, the Server ignores them. _UPDATE_MODE-Update existing rows in a destination table. If the Server cannot update a row-for example, the row does not exist-a warning occurs. The integer value assigned to this constant is 2. The Server locates an existing row by searching for values in key field(s). Note: When you use this setting, the destination must already exist. _DELETE_MODE-Delete rows from the destination table. If the Server cannot delete a row, an error occurs. The integer value assigned to this constant is 3. The Server locates rows to delete by searching for values in key field(s). _INS_THEN_UPD-Insert new rows into an existing destination table. If the Server cannot insert a row-for example, the row is already there-it updates that row. If the Server cannot update the row, a warning occurs. The integer value assigned to this constant is 4. The Server can only perform updates if UPDATEKEY fields exist in the destination structure. Note: You cannot create new tables with this setting. Communication Handlers Introduction 23

24 STORE _UPD_THEN_INS-Update existing rows in a destination table. If the Server cannot update a row-for example, the row does not exist-it inserts a row instead. If the Server cannot insert a row, an error occurs. The integer value assigned to this constant is 5. The Server locates an existing row by searching for values in UPDATEKEY field(s). Note: These constants are not case-sensitive. Note: For _INS_THEN_UPD and _UPD_THEN_INS, there are times when the Server cannot attempt to perform any action, and an error occurs. Examples include: The fields in the destination structure do not correspond to the table's fields by data type and/or number. Values in structure fields are not valid in the corresponding table's fields. Comments The STORE handler usually follows the LOAD handler. After LOAD moves a row of returned data into the structure instance, STORE moves the row out of the structure instance and into the destination table. LOAD and STORE move one data row at a time. Consequently, LOAD and STORE are typically used with a flow-control statement (such as a DO WHILE loop). For details about flow-control statements, see the Advantage Data Transformer Script Language Reference. If the table specified in the #TABLE parameter already exists and the STORE handler is called with #UPDATE FALSE, then the fields in the source structure instance must correspond to the table s columns by number or position and then by data type. However, the #MAP_TYPE parameter provides some flexibility with data types. See the Data Type Conversions chapter for details. If the table specified in the #TABLE parameter does not exist and the #CREATE parameter is TRUE, the Server creates the destination table. It uses the structure instance specified in the #DATA parameter to create the column names and descriptions in the table. The Server uses the field names in the structure instance as the names of the table columns and converts the field s Advantage Data Transformer data types to equivalent ODBC data types. See the Data Type Conversions chapter for details. If you are using the Microsoft ODBC TEXT driver, be aware that an error occurs if the STORE handler s #UPDATE parameter is set to TRUE. 24 Generic ODBC Interface Guide

25 DISCONNECT Examples In this example, the LOAD handler loads one data row at a time into the structure instance named struct_inst. The STORE handler then writes the data from the structure to the q3sales table. DO WHILE ( LOAD source_profile ( #DATA struct_inst, #RANGE_CHECK FALSE) = _IPRET_SUCCESS) STORE dest_profile ( #DATA struct_inst, #TABLE "q3sales", #CREATE FALSE, #UPDATE TRUE, #MAP_TYPE TRUE, #COMMIT TRUE) LOOP Notice that the DO WHILE loops continues executing LOAD and STORE until the LOAD operation fails (that is, until there are no more rows to load). DISCONNECT Purpose Terminates a database connection. Syntax DISCONNECT profile_handle (#COMMIT Boolean, #ROLLBACK Boolean) Parameter profile_handle Description The database profile handle previously declared in your script and used in a CONNECT statement. Declare a profile handle with the DEF statement. Communication Handlers Introduction 25

26 DISCONNECT Parameter #COMMIT Boolean Description A value that controls whether the Server commits all outstanding database modifications before disconnecting from the database. Valid values are: TRUE Commit outstanding modifications to the database before disconnecting from the database. FALSE Do not commit outstanding modifications to the database before disconnecting from the database. Uncommitted transactions may be lost. This is the default setting. Note: If #AUTO_COMMIT is TRUE in the CONNECT handler, then the STORE handler commits all modifications, regardless of the value of this #COMMIT parameter. #ROLLBACK Boolean A value that controls whether the Server rolls back all outstanding database modifications before disconnecting from the database. Valid values are: TRUE Roll back modifications to the database before disconnecting from the database. FALSE Do not roll back modifications to the database before disconnecting from the database. This is the default setting. Note: These values are not case-sensitive. Note: If #AUTO_COMMIT is TRUE in the CONNECT handler, then the STORE handler commits all modifications. No outstanding modifications remain to be rolled back. Examples This example commits modifications and terminates the connection to the database referenced by the dest_profile handle: DISCONNECT dest_profile (#COMMIT TRUE) 26 Generic ODBC Interface Guide

27 Chapter 3: Data Type Conversions This chapter describes data type conversions between Advantage Data Transformer and the data formats covered by this guide. Data Type Overview Before Advantage Data Transformer can manage data, it must convert the data into data types. The software performs the following conversions: From a source table data type to a Advantage Data Transformer data type. In a LOAD operation, data is moved from a source table (or file) to a structure instance. For a successful data type conversion, the structure instance field data types must correspond to the source table or file data types. Advantage Data Transformer data types can be assigned to the fields in a structure instance automatically (by the software in a data transfer or from a script generated from a Mapper program) or manually (by declaring the structure definition in a script). From an Advantage Data Transformer data type to a destination table data type. In a STORE operation, data is moved from a structure instance to a destination table or file. For data type conversions to be successful, the data types of the fields in the structure instance must correspond to the data types in the destination table or file. Even if the STORE operation deletes data from a destination table, the structure instance field data types must correspond to the destination table data types. As with the LOAD operation, Advantage Data Transformer data types can be assigned to the fields in a structure instance automatically or manually. Note: You can use the same structure instance in LOAD and STORE operations as long as the Advantage Data Transformer data types in the structure instance match the data types in both the source and destination tables. Advantage Data Transformer also converts data types when it creates a destination table. The data types that the Server assigns to the columns in the new table correspond to the Advantage Data Transformer data types in the source structure instance. Data Type Conversions 27

28 Microsoft Access ODBC Data Type Tables From one Advantage Data Transformer data type to another. If a source table data type and a destination table data type do not correspond to the same Advantage Data Transformer data type, you may have to convert data from one Advantage Data Transformer data type to another. For example, consider the following data types in sample ZIP Code columns in source and destination tables: Source Column Data Type Advantage Data Transformer Data Type Destination Column Data Type NUMBER INT - - STRING TEXT (or VARCHAR) Advantage Data Transformer does not automatically convert between INT and STRING data types. If you do not explicitly convert these, a runtime error occurs. Note: For information about converting between Advantage Data Transformer data types, see the CONVERT function in the online help for the Advantage Data Transformer Script Manager. Microsoft Access ODBC Data Type Tables The tables in this section define the valid conversions between Advantage Data Transformer and Microsoft Access ODBC data types. Data Type Conversions in Data Transfers Advantage Data Transformer performs these conversions automatically. Access Source Data Type byte short long counter single double Advantage Data Transformer Data Type TINYCARD SMALLINT INT CARD SMALLFLOAT FLOAT 28 Generic ODBC Interface Guide

29 Microsoft Access ODBC Data Type Tables Access Source Data Type currency bit datetime text(n), char(n) long text memo varbinary(n) binary(n) long binary ole Advantage Data Transformer Data Type MONEY BOOLEAN DATETIME VARSTRING STRING VARBINARY BINARY Data Type Conversions in Table Creations Advantage Data Transformer performs these conversions when creating a table in a destination database. The table can be created in a script or a data transfer. Advantage Data Transformer Data Type TINYCARD SMALLINT INT CARD SMALLFLOAT FLOAT DECIMAL MONEY BOOLEAN DATETIME VARSTRING STRING VARBINARY Access Destination Data Type byte short long long single double double currency bit datetime long text long text long binary Data Type Conversions 29

30 Microsoft Access ODBC Data Type Tables Advantage Data Transformer Data Type BINARY Access Destination Data Type long binary Loading Access Data into Advantage Data Transformer Use this table to create a structure definition for loading rows from an Access table into Advantage Data Transformer. For each field in the structure, you assign the Advantage Data Transformer data type that best corresponds to the data type of the Access column. Note: If an Advantage Data Transformer data type supports an Access source type, an asterisk () appears in the right column. If an Advantage Data Transformer data type supports an Access source type with restrictions, a footnote number appears in that column. See the table footnotes for specific information regarding conversion support. Advantage Data Transformer Data Type Access Source Data Type Conversion Supported? TINYINT TINYCARD SMALLINT SMALLCARD INT CARD SMALLFLOAT FLOAT byte short long byte short long byte short long byte short long byte short long byte short long single double single double Generic ODBC Interface Guide

31 Microsoft Access ODBC Data Type Tables Advantage Data Transformer Data Type Access Source Data Type Conversion Supported? MONEY currency BOOLEAN bit DATE datetime DATETIME datetime BYTE WORD DWORD OWORD QWORD VARSTRING STRING VARBINARY(n) BINARY byte short long byte short long byte short long byte short long byte short long text (n) char (n) varchar text (n) char (n) varchar longtext binary (n) varbinary longbinary binary (n) varbinary longbinary ole Data Type Conversions 31

32 Microsoft Access ODBC Data Type Tables Conversion Support Notes: Conversion is supported. 1. If #RANGE_CHECK is TRUE, the following communication error occurs: Range Check Failed. 2. If #RANGE_CHECK is TRUE and the range test fails, the following communication error occurs: Range Check Failed. Storing Access Data from Advantage Data Transformer Use this table to create a structure definition for storing rows into an Access table from Advantage Data Transformer. For each field in the structure, you assign the Advantage Data Transformer data type that best corresponds to the data type of the Access column where the data is being moved. Note: If a Advantage Data Transformer data type supports an Access destination type, an asterisk () appears in the right column. If a Advantage Data Transformer data type supports an Access destination type with restrictions, a footnote number appears in that column. See the table footnotes for specific information regarding conversion support. Advantage Data Transformer Data Type Access Destination Data Type Conversion Supported? TINYINT byte 1 TINYCARD byte SMALLINT short SMALLCARD short 1 INT long CARD long 1 SMALLFLOAT single FLOAT double DECIMAL double MONEY currency BOOLEAN bit DATE datetime 1 TIME datetime 1 DATETIME datetime 32 Generic ODBC Interface Guide

33 dbase ODBC Data Type Tables Advantage Data Transformer Data Type Access Destination Data Type Conversion Supported? BYTE binary (n) WORD binary (n) DWORD binary (n) OWORD binary (n) QWORD binary (n) VARSTRING char (n) 2 STRING longtext VARBINARY(n) binary (n) BINARY longbinary Conversion Support Notes: Conversion is supported. 1. STORE with #MAP_TYPE FALSE fails. 2. n is less than or equal to 255. dbase ODBC Data Type Tables The tables in this section define the valid conversions between Advantage Data Transformer and dbase ODBC data types. Data Type Conversions in Data Transfers Advantage Data Transformer performs these conversions automatically. dbase Source Data Type numeric logical date char(n) memo Advantage Data Transformer Data Type FLOAT BOOLEAN DATE VARSTRING STRING Data Type Conversions 33

34 dbase ODBC Data Type Tables Data Type Conversions in Table Creations Advantage Data Transformer performs these conversions when creating a table in a destination database. The table can be created in a script or a data transfer. Advantage Data Transformer Data Type FLOAT DECIMAL BOOLEAN DATE VARSTRING STRING dbase Destination Data Type numeric numeric logical date memo memo Loading dbase Data into Advantage Data Transformer Use this table to create a structure definition for loading rows from a dbase table into Advantage Data Transformer. For each field in the structure, you assign the Advantage Data Transformer data type that best corresponds to the data type of the dbase column. Note: If a Advantage Data Transformer data type supports a dbase source type, an asterisk () appears in the dbase column. If a Advantage Data Transformer data type supports a dbase source type with restrictions, a footnote number appears in that column. See the table footnotes for specific information regarding conversion support. dbase Source Data Type Advantage Data Transformer Data Type NUMERIC LOGICAL DATE CHAR(n) MEMO FLOAT 1 DECIMAL MONEY BOOLEAN DATE VARSTRING(n) 2 34 Generic ODBC Interface Guide

35 dbase ODBC Data Type Tables dbase Source Data Type STRING 2 Conversion Support Notes: Conversion is supported. 1. If #RANGE_CHECK is TRUE, the following communication error occurs: Range Check Failed. 2. If #RANGE_CHECK is TRUE and the range test fails, the following communication error occurs: Range Check Failed. Storing dbase Data from Advantage Data Transformer Use this table to create a structure definition for storing rows into a dbase table from Advantage Data Transformer. For each field in the structure, you assign the Advantage Data Transformer data type that best corresponds to the data type of the dbase column where the data is being moved. Note: If an Advantage Data Transformer data type supports a dbase destination type, an asterisk () appears in the dbase column. If an Advantage Data Transformer data type supports a dbase destination type with restrictions, a footnote number appears in that column. See the table footnotes for specific information regarding conversion support. dbase Destination Data Type Advantage Data Transformer Data Type NUMERIC LOGICAL DATE CHAR(n) MEMO FLOAT DECIMAL MONEY BOOLEAN DATE VARSTRING(n) 1 STRING 2 Data Type Conversions 35

36 TEXT ODBC Data Type Tables Conversion Support Notes: Conversion is supported. 1. n is less than or equal to n is less than or equal to 254. TEXT ODBC Data Type Tables The tables in this section define the valid conversions between Advantage Data Transformer and TEXT ODBC data types. Data Type Conversions in Data Transfers Advantage Data Transformer performs these conversions automatically. TEXT Source Data Type INTEGER FLOAT DATETIME CHAR(n) LONGCHAR Advantage Data Transformer Data Type INT FLOAT DATETIME VARSTRING(n) STRING Data Type Conversions in Table Creation Advantage Data Transformer performs these conversions when creating a table in a destination database. The table can be created in a script or a data transfer. Advantage Data Transformer Data Type INT FLOAT DECIMAL DATETIME VARSTRING(n) TEXT Destination Data Type INTEGER FLOAT FLOAT TIMESTAMP LONGCHAR 36 Generic ODBC Interface Guide

37 TEXT ODBC Data Type Tables Advantage Data Transformer Data Type STRING TEXT Destination Data Type LONGCHAR Loading TEXT ODBC Data into Advantage Data Transformer Use this table to create a structure definition for loading rows from a source table into Advantage Data Transformer. For each field in the structure, you assign the Advantage Data Transformer data type that best corresponds to the data type of the source column. Note: If a Advantage Data Transformer data type supports a TEXT source type, an asterisk () appears in the TEXT column. If a Advantage Data Transformer data type supports a TEXT source type with restrictions, a footnote number appears in that column. See the table footnotes for specific information regarding conversion support. TEXT Source Data Type Advantage Data Transformer Data Type INTEGER FLOAT DATETIME CHAR(n) LONGCHAR TINYINT 1 TINYCARD 1 SMALLINT 1 SMALLCARD 1 INT FLOAT DECIMAL MONEY DATE 1 TIME 1 DATETIME VARSTRING(n) 1 STRING Data Type Conversions 37

38 TEXT ODBC Data Type Tables Conversion Support Notes: Conversion is supported. 1. If #RANGE_CHECK is TRUE, the following communication error occurs: Range Check Failed. Storing TEXT ODBC Data from Advantage Data Transformer Use this table to create a structure definition for storing rows into a destination table from Advantage Data Transformer. For each field in the structure, you assign the Advantage Data Transformer data type that best corresponds to the data type of the destination column where the data is being moved. Note: If an Advantage Data Transformer data type supports a TEXT destination type, an asterisk () appears in the TEXT column. If an Advantage Data Transformer data type supports a TEXT destination type with restrictions, a footnote number appears in that column. See the table footnotes for specific information regarding conversion support. TEXT Destination DataType Advantage Data Transformer Data Type INTEGER FLOAT DATETIME CHAR(n) LONGCHAR TINYINT 1 TINYCARD 1 SMALLINT 1 SMALLCARD 1 INT CARD 1 FLOAT 2 DECIMAL 1 MONEY 1 BOOLEAN 1 DATE 1 DATETIME 1 VARSTRING(n) 3 STRING 4 38 Generic ODBC Interface Guide

39 Generic ODBC SQL Data Type Tables Conversion Support Notes: Conversion is supported. 1. STORE with #MAP_TYPE FALSE fails. 2. The driver restricts the scale to two positions. 3. n is less than or equal to Microsoft ODBC TEXT driver supports only 64,000 characters. Data may be truncated. Generic ODBC SQL Data Type Tables The tables in this section define the valid conversions between Advantage Data Transformer and generic ODBC SQL data types. Data Type Conversions in Data Transfers Advantage Data Transformer performs these conversions automatically. Note: These conversions may not be appropriate for the database you are using because the database may not support some of the data types of the ODBC driver. We recommend generating a script from the Mapperand adjusting the data types for appropriate conversions if needed. Advantage Data Transformer Data Type TINYINT TINYCARD SMALLINT SMALLCARD INT CARD SMALLFLOAT FLOAT DECIMAL MONEY BOOLEAN ODBC SQL Data Type sql_tinyint sql_tinyint sql_smallint sql_smallint sql_integer sql_integer sql_real sql_float sql_char sql_float sql_bit Data Type Conversions 39

40 Generic ODBC SQL Data Type Tables Advantage Data Transformer Data Type DATE TIME DATETIME BYTE WORD DWORD QWORD OWORD VARSTRING(n) STRING VARBINARY(n) BINARY ODBC SQL Data Type sql_date sql_time sql_timestamp sql_binary sql_binary sql_binary sql_binary sql_binary sql_char sql_longvarchar sql_varchar sql_varbinary sql_binary sql_longvarbinary Loading Generic ODBC SQL Data into Advantage Data Transformer Use this table to create a structure definition for loading rows from a source table into Advantage Data Transformer. For each field in the structure, you assign the Advantage Data Transformer data type that best corresponds to the data type of the source column. ODBC SQL Source Data Type sql_tinyint sql_smallint sql_integer sql_real sql_double sql_float sql_decimal sql_numeric sql_bit Advantage Data Transformer Data Type TINYINT SMALLINT INT SMALLFLOAT FLOAT DECIMAL (p,s) BOOLEAN 40 Generic ODBC Interface Guide