Dynamics ODBC REFERENCE Release 5.5a

Transcription

1 Dynamics ODBC REFERENCE Release 5.5a

2 Copyright Manual copyright 1999 Great Plains Software, Inc. All rights reserved. This document may not, in whole or in any part, be copied, photocopied, reproduced, translated, transmitted or reduced to any electronic medium or machine-readable form without prior consent, in writing, from Great Plains Software, Inc. Unless otherwise noted, all names of companies, products, street addresses, and persons contained herein are fictitious and are used solely to document the use of this product. Trademarks Dexterity is a trademark of Great Plains Software, Inc. Dynamics is a trademark of Great Plains Software, Inc. Great Plains Software and the Great Plains Logo are registered trademarks of Great Plains Software, Inc. Other company or product names mentioned may be trademarks or registered trademarks of their respective holders. Warranty Great Plains disclaims any warranty regarding the sample code contained in this documentation, including the warranties of merchantability and fitness for a particular purpose. Limitation of liability Information in this document is subject to change without notice. Neither Great Plains nor anyone else who has been involved in the creation, production or delivery of this documentation shall be liable for any indirect, incidental, special, exemplary or consequential damages, including but not limited to any loss of anticipated profit or benefits, resulting from the use of this documentation or sample code.

3 Contents Introduction...2 What s in this manual... 2 Symbols and conventions... 2 Product support... 3 Part 1: Basics... 6 Chapter 1: Dynamics and ODBC... 7 Using ODBC... 7 Selecting an ODBC driver... 7 Chapter 2: Data Storage in Dynamics... 9 Tables in the Dynamics database... 9 Working with the Dynamics database Part 2: Pervasive ODBC Driver Chapter 3: Introduction to Pervasive ODBC Terminology...15 Overview of Pervasive ODBC Pervasive.SQL configurations Chapter 4: Installation Chapter 5: Setting Up a Data Source Creating a Pervasive.SQL database Creating the data source Chapter 6: Testing a Data Source Chapter 7: Troubleshooting General errors ODBCDP32.DLL error Status error #238 or Combined_1 error Status error #517 or # Unable to view big text fields in Microsoft Query Editing the Record Notes Master table ODBC REFERENCE i

4 Part 3: Merant ODBC Driver...32 Chapter 8: Introduction to Merant ODBC Terminology Overview of Merant ODBC Pervasive.SQL configurations Chapter 9: Installation Chapter 10: Setting Up a Data Source Chapter 11: Testing a Data Source Chapter 12: Troubleshooting Using joins in Crystal Reports Part 4: FairCom ODBC Driver...52 Chapter 13: Introduction to FairCom ODBC Terminology Overview of FairCom ODBC Chapter 14: Installation Chapter 15: Setting Up a Data Source - Browse Method Creating a data source - browse method Testing a data source - browse method Chapter 16: Setting Up a Data Source - Script Method Creating a data source - script method Testing a data source - script method Chapter 17: Troubleshooting Testing information Microsoft Access table limit Incorrect paths using browse method with FairCom Server Using right-outer joins in Crystal Reports Using inner-joins in Crystal Reports Creating File DSNs Index...75 Documentation Comment Form...77 ii ODBC REFERENCE

5 INTRODUCTION

6 Introduction Welcome to the Dynamics ODBC Reference. This manual contains information about using Open Database Connectivity (ODBC) drivers to access data in Dynamics. What s in this manual The Dynamics ODBC Reference is designed to provide general information about accessing data with ODBC, as well as provide information for specific ODBC drivers. The manual is divided into the following parts: Part 1, Basics, introduces ODBC and describes how data is stored in Dynamics. Part 2, Pervasive ODBC Driver, describes how to use the Pervasive ODBC driver to access Pervasive.SQL (Btrieve) data. Part 3, Merant ODBC Driver, describes how to use the Merant ODBC driver to access Pervasive.SQL (Btrieve) data. Part 4, FairCom ODBC Driver, describes how to use the FairCom ODBC driver to access c-tree and FairCom Server data. Symbols and conventions To help you use this documentation more effectively, we ve used the following symbols and conventions within the text to make specific types of information stand out. Symbol Description The light bulb symbol indicates helpful tips, shortcuts and suggestions. Warnings indicate situations you should be aware of. Margin notes summarize important information. Margin notes call attention to critical information, and direct you to other areas of the documentation where a topic is explained. 2 ODBC REFERENCE

7 INTRODUCTION Convention Chapter 6, Testing a Data Source Overview of ODBC GENDDF.PDF Open Database Connectivity (ODBC) TAB or ALT+M Description Quotation marks indicate a chapter name. Italicized type indicate a section name. Words in uppercase indicate a file name. Acronyms are spelled out the first time they re used. Small capital letters indicate a key or a key sequence. Product support Technical support for accessing Dynamics data with ODBC drivers can be accessed using the following methods. Telephone support Great Plains Technical Support at (800) between 8:00 a.m. and 5:00 p.m. Central Time, Monday through Friday. International users can contact Great Plains Technical Support at (701) Internet Technical Support can also be contacted via Internet at dyntools@greatplains.com. ODBC REFERENCE 3

8 4 ODBC REFERENCE

9 PART 1: BASICS

10 Part 1: Basics Use this part of the manual to begin learning about ODBC and how data is stored in Dynamics. The information is divied into the following chapters: Chapter 1, Dynamics and ODBC, describes how data in Dynamics can be accessed using ODBC. Chapter 2, Data Storage in Dynamics, describes how data is stored in Dynamics tables. After you review these chapters, refer to the appropriate part of the manual that describes the ODBC driver you intend to use. 6 ODBC REFERENCE

11 Chapter 1: Dynamics and ODBC This chapter describes how you can use ODBC to access data in Dynamics. It also explains how to determine which ODBC driver you should use. Using ODBC ODBC Drivers allow applications such as Crystal Reports, Microsoft Access or Microsoft Visual Basic to access data directly in Dynamics tables. Any ODBC-compliant applications can read Dynamics data. Depending on the ODBC driver used, they may also be able to add or update data in Dynamics tables. Selecting an ODBC driver Several ODBC drivers can be used with Dynamics. The drivers you can use depend on the database manager you have chosen to use for Dynamics. Use the information in this section to decide which ODBC driver you should be using to access Dynamics data. Pervasive.SQL (Btrieve) If you are using the Pervasive.SQL (Btrieve) database manager to manage your Dynamics data, you can use either the Pervasive ODBC driver or the Merant ODBC driver. Pervasive This driver is included with Pervasive.SQL. Great Plains recommends that you use this driver to access data. If you encounter problems using the Pervasive ODBC driver, you may want to consider using the ODBC driver from Merant instead. Merant In certain special cases, particularly with earlier versions of Pervasive.SQL (Btrieve), users experienced difficulties accessing data with the Pervasive ODBC driver. Some users chose to switch to the Merant ODBC driver. If you experience problems with the Pervasive ODBC driver, you may want to use the Merant driver. c-tree or FairCom Server If you are using the c-tree database manager or the FairCom Server, you must use the FairCom ODBC driver. Keep in mind that the FairCom ODBC driver is read-only. You won t be able to change data in Dynamics tables. ODBC REFERENCE 7

12 8 ODBC REFERENCE

13 Chapter 2: Data Storage in Dynamics To effectively use ODBC drivers to access data in Dynamics, you need to understand how Dynamics stores data. This chapter contains information about the following topics: Tables in the Dynamics database Working with the Dynamics database Tables in the Dynamics database To work with the Dynamics database, you need to know some specific information about tables in the database. This section describes the following: Table names Table types Table groups You can use Dynamics Table Descriptions window to find the names of tables. Table names Each Dynamics table has three names: a display name, a technical name and a physical name. The display name is the name you see in a Dynamics window, such as Rebuild or Pathnames. The technical name is used internally to refer to the table. You will use a table s technical name when you refer to it with ODBC. The physical name is the name under which the table is stored by the operating system or database. The following table lists three names for one of the tables in Dynamics that stores account category information. Display name: Technical name: Physical name: Account Category Master GL_Account_Category_MSTR GL00102 ODBC REFERENCE 9

14 PART 1 BASICS Types of tables Most of the Dynamics information you ll need to access using ODBC will be stored in one of the following types of tables. Knowing which type of table contains the information you want will help you find the data you need. Setup tables contain all the default settings and module options you ve specified in the setup windows for each series. Master tables contain all the permanent data about your business. These may include information about accounts, vendors, customers, items, and so on. Work tables contain unposted batches of transactions entered using windows that can be opened using the Transactions button on the tool bar. These transactions are temporary and can be changed or deleted until they are posted to an open table. Open tables contain posted transactions for the current year, of which some may be unpaid. Information in open tables is moved to history tables when the transactions are paid. History tables contain paid transactions, or transactions from a previous year. Table groups A table group is a group of logically-related tables. For example, a customer master table, a customer address table and a customer history table all compose a table group. Every table in Dynamics is part of a table group. The table types described in the previous section setup, master, work, open and history are actually table groups. These table groups are actually composed of information stored in several separate tables. For example, the General Ledger Transaction Work Table is a table group, made up of the following three tables: Transaction Work (GL_TRX_HDR_WORK) Transaction Amounts Work (GL_TRX_LINE_WORK) Transaction Clearing Amounts Work (GL_TRX_Clearing_WORK) 10 ODBC REFERENCE

15 CHAPTER 2 DATA STORAGE IN DYNAMICS Technical table names are shown above in parentheses. General information about each transaction, such as the audit trail code and date, are stored in the Transaction Work (GL_TRX_HDR_WORK) table, and transaction amounts are stored in the Transaction Amounts Work (GL_TRX_LINE_WORK) or Transaction Clearing Amounts Work (GL_TRX_Clearing_WORK) table, depending upon whether you ve entered a standard transaction or a clearing transaction. Transaction Work table Transaction Amounts Work table Transaction Clearing Amounts Work table Transaction Work table group In some cases, a table group will contain only one table. In System Manager, for example, every table group is made up of a single table with the same name as the table group. Working with the Dynamics database Keep in mind the following points when you work with tables in the Dynamics database. Update related tables together Knowing which tables make up a table group is important when you update data in Dynamics using ODBC. Related or shared information must be updated together or Dynamics won t process data correctly. In addition to the related information stored in table groups, you may need to update other related information in Dynamics. For example, in order to create an entry in the Transaction Work table group, a batch number needs to be applied to the new transaction. The Posting Definitions Master (Batch_Headers) table contains the information that describes a batch, which will need to be updated, or at least accessed, when updating information in the Transaction Work table group. ODBC REFERENCE 11

16 PART 1 BASICS You can use Dynamics Table Descriptions window and the information in the Software Development Kit (SDK) manual to learn about integrating with tables in Dynamics. Make backups, or use sample data If you re going to use ODBC to manipulate your own accounting data, always make a complete backup before you begin. We recommend that you use the lesson company when creating ODBC integrations before using them with your own data. Test thoroughly Always test your ODBC integration thoroughly, not only by running it and updating Dynamics tables, but by manipulating the data within Dynamics afterward by posting it, printing reports or performing other transactions. Use a sample transaction To understand how Dynamics stores data, you may want to create a sample transaction with Dynamics (for instance, a new General Ledger transaction). Then examine the various tables involved in the transaction. This will help you learn how tables are updated for the transaction. 12 ODBC REFERENCE

17 PART 2: PERVASIVE ODBC DRIVER

18 Part 2: Pervasive ODBC Driver Use this part of the manual to learn about the Pervasive ODBC driver. The information is divided into the following chapters: Chapter 3, Introduction to Pervasive ODBC, introduces the Pervasive ODBC driver. Chapter 4, Installation, describes how to install the Pervasive ODBC driver. Chapter 5, Setting Up a Data Source, explains how to create a data source using the Pervasive ODBC driver. Chapter 6, Testing a Data Source, describes how to test a new data source. Chapter 7, Troubleshooting, provides information about troubleshooting the Pervasive ODBC driver. 14 ODBC REFERENCE

19 Chapter 3: If you are upgrading from Btrieve 6.15 to Pervasive.SQL, be sure you have used Dynamics Utilities to update all of your Btrieve tables. Introduction to Pervasive ODBC This chapter contains information about using the Open Database Connectivity (ODBC) driver from Pervasive Software to access Dynamics data. It covers using version 7.5 of the ODBC driver used with Pervasive.SQL ODBC drivers for earlier versions of Pervasive.SQL are not discussed. Information is divided into the following sections: Terminology Overview of Pervasive ODBC Pervasive.SQL configurations Terminology Several terms specific to Pervasive.SQL and ODBC drivers are used in this documentation. You may want to familiarize yourself with them before continuing. Btrieve A term previously used to describe one of the database managers used by Dynamics. The term has been replaced by Pervasive.SQL. Data Source The data a user wants to access and the information needed to get to that data. Database A concept in Pervasive.SQL that indicates a group of related Pervasive.SQL tables. When you access data using the Pervasive.SQL ODBC drivers, you are accessing the tables in a specific database. DDFs Acronym for Data Dictionary Files. DDFs are special files that describe the structure of Pervasive.SQL tables. DDFs are used when you create a database that contains the set of Pervasive.SQL tables you want to access through ODBC. DSN A file that stores the information necessary to connect to a particular ODBC data source. ODBC Acronym for Open DataBase Connectivity, a standard database access method developed by Microsoft Corporation. ODBC makes it possible to access an application s data, regardless of the database used to manage the data. Pervasive.SQL A database package from Pervasive Software. In earlier releases of Dynamics, this database package was known as Btrieve. ODBC REFERENCE 15

20 PART 2 PERVASIVE ODBC DRIVER Overview of Pervasive ODBC The following illustration shows how an ODBC-compatible application such as Microsoft Query can access Dynamics tables that are managed by Pervasive.SQL. ODBC-compatible application Driver Manager Pervasive ODBC Driver Data Source Database DDFs for Dynamics Dynamics data managed by Pervasive.SQL. One unique feature of the Pervasive ODBC driver is that it requires you to create a database to access Pervasive.SQL tables through ODBC. This database is created based on DDFs (Data Dictionary Files). DDFs store information about the structure of Pervasive.SQL tables. DDF files for Dynamics tables are created using a tool called the DDF Generator. This tool is included with Dynamics. Documentation for using the DDF Generator can be found in the GENDDF.PDF file, typically located in the same directory as the other Dynamics documentation files. 16 ODBC REFERENCE

21 CHAPTER 3 INTRODUCTION TO PERVASIVE ODBC Pervasive.SQL configurations Two configurations of Pervasive.SQL are available for Dynamics: Pervasive.SQL Workstation and Pervasive.SQL Server. Pervasive.SQL Workstation In this configuration, all Pervasive.SQL components and Dynamics data tables are stored on the local workstation. If you want to use ODBC drivers with this configuration, they must also be installed on the client. In the Pervasive.SQ L Workstation configuration, all Pervasive components and Dynamics data are located on the workstation. Pervasive.SQL Server In this configuration, the database engine components and Dynamics data tables are stored on the server. The Pervasive.SQL requesters are installed on each client. To use ODBC drivers with this configuration, you must install the drivers on each client machine that will be using them. The Pervasive.SQ L requesters are installed on each workstation. If a workstation will be accessing data through ODBC, the Pervasive ODBC driver must be installed as well. In the Pervasive.SQ L Server configuration, the database engine components and Dynamics data are located on the server. Server Clients ODBC REFERENCE 17

22 18 ODBC REFERENCE

23 Chapter 4: Installation This chapter describes how to install the Pervasive.SQL ODBC driver. Depending on the installation option you chose when you installed Pervasive.SQL, you may not need to complete this procedure. If you chose the Typical installation when you installed Pervasive.SQL, the ODBC driver has already been installed. If you need to install the Pervasive.SQL ODBC driver on a client machine, complete the following procedure. 1. Run SETUP.EXE. The SETUP.EXE file needed to install the Pervasive.SQL client components is typically located in the \PVSW\Clients\Win\ directory on the machine that is acting as the Pervasive.SQL server. Click Next to continue. ODBC REFERENCE 19

24 PART 2 PERVASIVE ODBC DRIVER 2. Indicate where to install the client components. If you don t want to install the client components in the default location, click Browse to specify a different location. Click Next to continue. 3. Complete the installation. Follow the instructions provided by the Pervasive.SQL installer to complete the installation. 4. Review the Read Me file. When the installation is complete, indicate whether you want to review the Read Me file. 20 ODBC REFERENCE

25 Chapter 5: Setting Up a Data Source Once the Pervasive ODBC driver is installed, you must set up a data source. The data source allows you to define specific details about the data you will be accessing with the ODBC driver. Information about setting up a data source is divided into two sections: Creating a Pervasive.SQL database Creating the data source Creating a Pervasive.SQL database Before you can create a data source, a database that contains the tables you will be accessing must be set up in Pervasive.SQL. In Pervasive.SQL, a database specifies a group of related Pervasive.SQL tables. For Dynamics, you will typically create one Pervasive.SQL database that contains all of the tables in Dynamics. It is not necessary to create a separate Pervasive.SQL database each time you create an ODBC data source for Dynamics. You will need to generate DDFs before creating the Pervasive.SQL database. For information about generating DDFs, refer to the DDF Generator manual. To create the Pervasive.SQL database for Dynamics, perform the following steps: 1. Start the Pervasive.SQL Control Center. If you are using Pervasive.SQL Server, you will typically run the Pervasive.SQL Control Center on the machine that is acting as the server. If you are running Pervasive.SQL Workstation, run the Pervasive.SQL Control Center on the machine on which you installed Pervasive.SQL. 2. Open the Pervasive.SQL Configuration Utility. Choose Configuration Utility from the Center menu to open the Pervasive.SQL Configuration Utility. 3. Open the Maintain Named Database window. Choose Maintain Named Database from the Settings menu to open the Maintain Named Database window. ODBC REFERENCE 21

26 PART 2 PERVASIVE ODBC DRIVER 4. Create a new database. Click Create to create a new database and open the Create Named Database window, shown in the following illustration. 5. Specify the characteristics of the database. Specify the following items for the new database: Database Name This is the name the new database will be given. Typically, this will be Dynamics. Dictionary Location This is the location of the DDF files that were created for Dynamics. The DDFs are typically located in the same directory as the company s data you will be accessing. The path you specify will also appear in the Data File Locations list. Be sure the Integrity Enforced option is marked. Click OK to finish creating the database. Close the Maintain Named Database window and the Pervasive.SQL Control Center. 22 ODBC REFERENCE

27 CHAPTER 5 SETTING UP A DATA SOURCE Creating the data source To set up a data source, perform the following steps: 1. Open the ODBC Data Source Administrator. Data sources are set up using the ODBC Data Source Administrator, which is accessed by double-clicking the 32bit ODBC control panel. 2. Create a new User DSN. In the ODBC Data Source Administrator window, click the User DSN tab, then click Add. ODBC REFERENCE 23

28 PART 2 PERVASIVE ODBC DRIVER 3. Select the Pervasive Software ODBC driver. In the list of drivers, select the Pervasive Software ODBC driver. Depending on what components you installed, you may see two Pervasive ODBC drivers listed. Choose Pervasive ODBC Client Interface if you are connecting to another machine that is acting as the Pervasive.SQL Server. Choose Pervasive ODBC Engine Interface if you are using Pervasive.SQL Workstation, or are setting up a data source on the same machine that is acting as the Pervasive.SQL Server. Click Next to continue. 24 ODBC REFERENCE

29 CHAPTER 5 SETTING UP A DATA SOURCE 4. Enter the client setup information. The ODBC Setup window will appear, allowing you to enter setup information for the ODBC data source. The following illustration shows this window when setting up an ODBC data source using the Pervasive Client Interface driver. Enter a Data Source Name and Description that appropriately describe the data source you are creating. 5. Select the Pervasive.SQL server. This step is necessary only if you are using the Pervasive ODBC Client Interface driver. In the Address field, enter the machine name of the system that is acting as the Pervasive.SQL server. 6. Select the Pervasive.SQL data source. To access data using the Pervasive ODBC drivers, you must select a database that has been set up for Pervasive.SQL. If you are using the Pervasive ODBC Client Interface, you can view a list of databases available on the Pervasive.SQL server you specified by clicking Get DNS List. The Data Source Name drop-down list will be filled with the names of the databases that have been set up for Pervasive.SQL. If you are using the Pervasive ODBC Engine Interface, the dropdown list will already contain the names of the databases that have been set up for Pervasive.SQL. ODBC REFERENCE 25

30 PART 2 PERVASIVE ODBC DRIVER If the database you want to use does not exist, you can click Create to create a new database. Great Plains recommends that you create the database for Dynamics using the procedure described in the previous section, Creating a Pervasive.SQL database on page 21. If you attempt to create a new database on the Pervasive.SQL server, you will be required to log in as a user who has administrative privileges for the machine running Pervasive.SQL. When you create a database, you must specify the set of DDFs that will be used to indicate which tables will be included in the database. For more information about creating databases, refer to the Pervasive.SQL documentation. 7. Test the connection (optional). Click Test to verify that a connection can be made to the Pervasive.SQL data. Click OK to finish setting up the data source. 26 ODBC REFERENCE

31 Chapter 6: Testing a Data Source Once you have set up a data source, we recommend that you test it with Microsoft Query. Microsoft Query is a general-purpose data retrieval tool that comes with Microsoft Office and with Microsoft SQL Server. Use the following procedure to test an ODBC data source. If you encounter problems setting up a data source, refer to Chapter 7, Troubleshooting, for more information about resolving problems. 1. Launch Microsoft Query. Testing by Great Plains indicates that version 8.0e or later of Microsoft Query is required to properly access data sources you have created. 2. Create a new query. To create a new query, choose New from the File menu. The Choose Data Source window will appear. 3. Select a data source. Be sure the Use the Query Wizard option is not marked. In the list of data sources, select the data source you created and click OK. The Add Tables window will appear. ODBC REFERENCE 27

32 PART 2 PERVASIVE ODBC DRIVER 4. Select the tables to use for the query. In the Add Tables window, select each table you want to use for the query and click Add. When you have finished, click Close. 5. Specify the columns to include in the query. Double-click the column names or drag column names from the list to the data area at the bottom of the window. Double-click the * to add all of the columns from the table. If the data in the columns appears as you expect, the ODBC driver is set up correctly. You should be able to use it with other applications such as Crystal Reports. 28 ODBC REFERENCE

33 Chapter 7: Troubleshooting If you encounter problems setting up or using the Pervasive.SQL ODBC driver, use the information in this chapter to help you resolve the problems. General errors If you receive errors trying to connect to Pervasive.SQL tables, try the following: Generate DDFs with both the Combine Segments and Drop Combined Fields options unmarked. Generate DDFs with the Combine Segments option marked and the Drop Combined Fields option unmarked. Generate DDFs with both the Combine Segments and Drop Combined Fields options marked. Use the Merant (formerly known as Intersolv) ODBC driver for Btrieve. Contact DynamicTools Support if you have any further questions. The remaining sections in this chapter describe specific errors or problems you may encounter. ODBCDP32.DLL error When creating a data source name (DSN) on a Windows NT 4.0 workstation with Service Pack 3 installed, you may receive a General Protection Fault (GPF) in ODBCCP32.DLL or the following error message: An error occurred while Windows was working with the Control Panel file ODBCCP32.CPL. A workaround is to apply Microsoft s Office 97 Service Release 1. ODBC REFERENCE 29

34 PART 2 PERVASIVE ODBC DRIVER Status error #238 or Combined_1 error When attempting to view some tables in Dynamics you may receive error #238: The named index does not exist. Specific tables affected include GL00100 (Account Master) or UPR00100 (Payroll Master). This error typically occurs when you generate DDFs with both the Combine Segments and Drop Combined Fields options unmarked. Testing by Great Plains has found that regenerating the DDFs with both of these options marked will allow you to view the GL00100 table. With the UPR00100 table, you may receive the following message: Invalid field definition COMBINED_1 in definition of index or relationship. Try the various combinations of segment combining options when creating DDFs. Refer to the section titled General errors for more information. Status error #517 or #248 You may not be able to view some tables in Dynamics. You will receive the following messages: You must include a FROM clause in the SELECT statement (#517) and/or The specified size is invalid for the defined data type (#248). Refer to the section titled General errors for a list of possible solutions. Unable to view big text fields in Microsoft Query You may not be able to view a field that is defined to be a big text data type in Microsoft Query. Errors may include Status Error #207: The field does not exist in the dictionary or #261: A variable length column must be defined last in a view or table definition. Editing the Record Notes Master table You will not be able to create new records in the Record Notes Master table (SY03900). You will receive the Status Error #353: The data definition includes an inconsistency. 30 ODBC REFERENCE

35 PART 3: MERANT ODBC DRIVER

36 Part 3: Merant ODBC Driver Use this part of the manual to learn about the Merant ODBC driver. The information is divided into the following chapters: Chapter 8, Introduction to Merant ODBC, introduces the Merant ODBC driver. Chapter 9, Installation, describes how to install the Merant ODBC driver. Chapter 10, Setting Up a Data Source, explains how to create a data source using the Merant ODBC driver. Chapter 11, Testing a Data Source, describes how to test a new data source. Chapter 12, Troubleshooting, provides information about troubleshooting the Merant ODBC driver. 32 ODBC REFERENCE

37 Chapter 8: If you are upgrading from Btrieve 6.15 to Pervasive.SQL, be sure you have used Dynamics Utilities to update all of your Btrieve tables. Introduction to Merant ODBC This chapter contains information about using the Open Database Connectivity (ODBC) driver from Merant Software to access Dynamics data. It covers using version 3.5 of the ODBC driver. Information is divided into the following sections: Terminology Overview of Merant ODBC Pervasive.SQL configurations Terminology Several terms specific to Pervasive.SQL and ODBC drivers are used in this documentation. You may want to familiarize yourself with them before continuing. Btrieve A term previously used to describe one of the database managers used by Dynamics. The term has been replaced by Pervasive.SQL. Data Source The data a user wants to access and the information needed to get to that data. DDFs Acronym for Data Dictionary Files. DDFs are special files that describe the structure of Pervasive.SQL tables. DDFs for Dynamics tables are used by the Merant ODBC driver. DSN A file that stores the information necessary to connect to a particular ODBC data source. ODBC Acronym for Open DataBase Connectivity, a standard database access method developed by Microsoft Corporation. ODBC makes it possible to access an application s data, regardless of the database used to manage the data. Pervasive.SQL A database package from Pervasive Software. In earlier releases of Dynamics, this database package was known as Btrieve. ODBC REFERENCE 33

38 PART 3 MERANT ODBC DRIVER Overview of Merant ODBC The following illustration shows how an ODBC-compatible application such as Microsoft Query can access Dynamics tables that are managed by Pervasive.SQL. ODBC-compatible application Driver Manager Merant ODBC Driver Data Source DDFs for Dynamics Dynamics data managed by Pervasive.SQL. One unique feature of the Merant ODBC driver is that it requires DDFs (Data Dictionary Files) to access Pervasive.SQL tables. DDFs store information about the structure of Pervasive.SQL tables. DDF files for Dynamics tables are created using a tool called the DDF Generator. This tool is included with Dynamics. Documentation for loading and using the DDF Generator can be found in the GENDDF.PDF file, typically located in the same directory as the other Dynamics documentation files. 34 ODBC REFERENCE

39 CHAPTER 8 INTRODUCTION TO MERANT ODBC Pervasive.SQL configurations Two configurations of Pervasive.SQL are available for Dynamics: Pervasive.SQL Workstation and Pervasive.SQL Server. Pervasive.SQL Workstation In this configuration, all Pervasive.SQL components and Dynamics data tables are stored on the local workstation. If you want to use ODBC drivers with this configuration, they must also be installed on the client. In the Pervasive.SQ L Workstation configuration, all Pervasive components and Dynamics data are located on the workstation. Pervasive.SQL Server In this configuration, the database engine components and Dynamics data tables are stored on the server. The Pervasive.SQL requesters are installed on each client. To use ODBC drivers with this configuration, you must install the drivers on each client machine that will be using them. The Pervasive.SQ L requesters are installed on each workstation. If a workstation will be accessing data through ODBC, the ODBC driver must be installed as well. In the Pervasive.SQ L Server configuration, the database engine components and Dynamics data are located on the server. Server Clients ODBC REFERENCE 35

40 36 ODBC REFERENCE

41 Chapter 9: Installation This chapter describes how to install the Merant ODBC driver. To install the Merant ODBC driver, complete the following procedure. 1. Run SETUP.EXE. The SETUP.EXE file needed to install the Merant OBDC driver is located on the second Dynamics CD. Click Next to continue. 2. Indicate the type of installation. Choose Licensed or Evaluation. When prompted, enter the appropriate registration information. Click Next to continue. ODBC REFERENCE 37

42 PART 3 MERANT ODBC DRIVER 3. Indicate the product to install. Choose the Single Driver workstation installation. Click Next to continue. 4. Verify the registration information. Verify the registration information supplied and click Yes to continue. 5. Acknowledge the license agreement. Click Yes to continue. 6. Verify driver requirements. If necessary, verify that all system requirements to use this ODBC driver are met. Click Next to continue. 38 ODBC REFERENCE

43 CHAPTER 9 INSTALLATION 7. Select the type of installation. Choose to perform a typical installation. Click Next to continue. 8. Indicate where to install the ODBC driver. If you don t want to install the ODBC driver in the default location, click Browse to specify a different location. Click Next to continue. ODBC REFERENCE 39

44 PART 3 MERANT ODBC DRIVER 9. Indicate the components to install. Both the drivers and Microsoft Data Access Components (MDAC) should be installed. Click Next to continue. 10. Specify installation options. Typically, you should to replace existing drivers and create default data sources. Click Next to continue. 40 ODBC REFERENCE

45 CHAPTER 9 INSTALLATION 11. Indicate where to place items on the Start menu. If you don t want to use the default name, specify another. Click Next to continue. The driver will be installed. 12. Indicate whether you want to view the Readme or configure ODBC drivers. Click Finish to complete the installation. ODBC REFERENCE 41

46 42 ODBC REFERENCE

47 Chapter 10: Setting Up a Data Source Once the Merant ODBC driver is installed, you must set up a data source. The data source allows you to define specific details about the data you will be accessing with the ODBC driver. You will need to generate DDFs before setting up a data source. For information about generating DDFs, refer to the DDF Generator manual. To set up a data source, perform the following steps: 1. Open the ODBC Data Source Administrator. Data sources are set up using the ODBC Data Source Administrator, which is accessed by double-clicking the ODBC control panel. 2. Create a new File DSN. In the ODBC Data Source Administrator window, click the File DSN tab, then click Add. ODBC REFERENCE 43

48 PART 3 MERANT ODBC DRIVER 3. Select the Merant ODBC driver. In the list of drivers, select the Merant ODBC driver. Click Next to continue. 4. Specify the filename for the file data source. Enter the filename for the file data source. Click Browse to easily indicate a specific location. Click Next to continue. 44 ODBC REFERENCE

49 CHAPTER 10 SETTING UP A DATA SOURCE 5. Finish creating the data source. Click Finish to complete creating the data source. Close the ODBC Data Source Administrator window. 6. Edit the File DSN. It is necessary to edit the File DSN you just created to indicate where the DDFs are located for Dynamics. To edit the File DSN, use a text editor such as Windows Notepad. The File DSN can be found in the location you specified in step 4. Add the following line to the end of the File DSN: DB=location where location is the complete path to the DDFs for Dynamics. An example is shown in the following illustration. Add this line to the File DSN Be sure to save the changes to the File DSN. ODBC REFERENCE 45

50 46 ODBC REFERENCE

51 Chapter 11: Testing a Data Source Once you have set up a data source, we recommend that you test it with Microsoft Query. Microsoft Query is a general-purpose data retrieval tool that comes with Microsoft Office and with Microsoft SQL Server. Use the following procedure to test an ODBC data source. If you encounter problems setting up a data source, refer to Chapter 12, Troubleshooting, for more information about resolving problems. 1. Launch Microsoft Query. 2. Create a new query. To create a new query, choose New from the File menu. The Choose Data Source window will appear. 3. Select a data source. Be sure the Use the Query Wizard option is marked. In the list of data sources, select the data source you created and click OK. 4. Use the Query Wizard to select the columns to use for the query. Select the columns you want to include in the query. Click Next to continue. ODBC REFERENCE 47

52 PART 3 MERANT ODBC DRIVER 5. Specify additional options for the query. Complete the remaining steps in the Query Wizard to specify additional options for the query. When the wizard has finished, the results of the query will be displayed. If the data in the columns appears as you expect, the ODBC driver is set up correctly. You should be able to use it with other applications such as Crystal Reports. 48 ODBC REFERENCE

53 Chapter 12: Troubleshooting If you encounter problems setting up or using the Merant ODBC driver, use the information in this chapter to help you resolve the problems. Using joins in Crystal Reports If you encounter problems creating joins in Crystal Reports, you may need to update the P2SODBC.DLL used by Crystal Reports. You can find this file in the ODBCREGS.ZIP archive, included with Dynamics. You can also download the archive from the Seagate Software web site ( Follow the instructions included with the archive. ODBC REFERENCE 49

54 50 ODBC REFERENCE

55 PART 4: FAIRCOM ODBC DRIVER

56 Part 4: FairCom ODBC Driver Use this part of the manual to learn about the FairCom ODBC driver. The information is divided into the following chapters: Chapter 13, Introduction to FairCom ODBC, introduces the FairCom ODBC driver. Chapter 14, Installation, describes how to install the FairCom ODBC driver. Chapter 15, Setting Up a Data Source - Browse Method, explains how to use the browse method to set up a data source. Chapter 16, Setting Up a Data Source - Script Method, explains how to use the script method to set up a data source. Chapter 17, Troubleshooting, provides information about troubleshooting the FairCom ODBC driver. 52 ODBC REFERENCE

57 Chapter 13: Introduction to FairCom ODBC This chapter contains information about using the Open Database Connectivity (ODBC) driver from FairCom Corporation to access Dynamics data. It covers using version 3.9 of the the ODBC driver to access c-tree data for Dynamics 5.10 and later. ODBC drivers for earlier versions of Dynamics are not discussed. This version of the FairCom ODBC driver is read-only. You will not be able to write data to FairCom tables using this ODBC driver. Information is divided into the following sections: Terminology Overview of FairCom ODBC Terminology Several terms specific to FairCom and ODBC drivers are used in this manual. You may want to familiarize yourself with them before continuing. Data Dictionary A file (CTSYSCAT.FCS) that stores information about the name and location of FairCom tables. This file is used by the FairCom ODBC driver when accessing data. Data Source The data a user wants to access and the information needed to get to that data. DSN A file that stores the information necessary to connect to a particular ODBC data source. ODBC Acronym for Open DataBase Connectivity, a standard database access method developed by Microsoft Corporation. ODBC makes it possible to access an application s data, regardless of the database used to manage the data. Script Name Database A file that contains a list of tables to be accessed, along with the complete path to each table. This file is used to create the data dictionary file used by the FairCom ODBC driver. If you use the script method of specifying the tables to access, you will create the script name database file manually. ODBC REFERENCE 53

58 PART 4 FAIRCOM ODBC DRIVER Overview of FairCom ODBC The following illustration shows how an ODBC-compatible application such as Microsoft Query can access Dynamics c-tree tables. ODBC-compatible application Driver Manager FairCom ODBC Driver Script Name Database Data Source Data Dictionary (CTSYSCAT.FCS) Dynamics c-tree or FairCom Server data. The FairCom ODBC driver requires a script name database file that contains the names and complete paths to the tables you want to access. You can build the script name database file manually, or you can have the FairCom ODBC driver build it for you. The information in this file is then converted into a data dictionary file named CTSYSCAT.FCS that is used by the FairCom ODBC driver when accessing data. It is possible that the data dictionary file (CTSYSCAT.FCS) may become out of synch with the data in the script name database file. This can cause problems accessing FairCom data tables through ODBC. If this occurs, delete the CTSYSCAT.FCS file. It will be re-created automatically when the ODBC driver is accessed. 54 ODBC REFERENCE

59 Chapter 14: Installation This chapter describes how to install the FairCom ODBC drivers. To install them, complete the following procedure. 1. Run SETUP.EXE. The SETUP.EXE file needed to install the FairCom ODBC driver is located on the second Dynamics CD. Click Next to continue. 2. Read the license agreement. After you have read the license agreement, mark the check box at the bottom of the window. Click Next to continue. ODBC REFERENCE 55

60 PART 4 FAIRCOM ODBC DRIVER 3. Indicate where to install sample files. Several sample files are installed with the FairCom ODBC driver. These include sample script name database files you can use as examples when setting up the ODBC driver. If you don t want to install the sample files in the default location, click Browse to specify a different location. Click Next to continue. 4. Complete the setup. The ODBC driver will be installed. Click Finish to begin installing components. 56 ODBC REFERENCE

61 CHAPTER 14 INSTALLATION During the installation, the following message may be displayed. This message indicates a component is already in use. If you receive this message, be sure that no other applications are running in the background. Shut down other applications, then click Retry. 5. Finish the setup. Click Finish to exit the installation. ODBC REFERENCE 57

62 58 ODBC REFERENCE

63 Chapter 15: Setting Up a Data Source - Browse Method Once the FairCom ODBC driver is installed, you can set up a data source. The data source allows you to define specific details about the data you will be accessing with the ODBC driver. You can use two methods to set up a data source for the FairCom ODBC driver: Browse method This method allows you to create the contents of the script name database file by simply selecting actual c-tree tables you want to use. Great Plains recommends the browse method for users who haven t configured ODBC data sources before. Script method This method requires you to create the script name database file manually. We recommend the script method for more advanced users. This is also the preferred method for creating a data source that accesses information on a FairCom Server. Creating a data source - browse method To create a data source using the browse method, perform the following steps: 1. Open the ODBC Data Source Administrator. Data sources are set up using the ODBC Data Source Administrator, which is accessed by double-clicking the 32bit ODBC control panel. ODBC REFERENCE 59

64 PART 4 FAIRCOM ODBC DRIVER 2. Create a new User DSN. In the ODBC Data Source Administrator window, click the User DSN tab. Then click the Add button. 3. Select the FairCom ODBC driver. In the list of drivers, select the FairCom ODBC driver. Click Finish to continue. 60 ODBC REFERENCE

65 CHAPTER 15 SETTING UP A DATA SOURCE - BROWSE METHOD 4. Name the data source. Enter a name for the data source. Typically, the name indicates the source or type of data that is being accessed. You may also want to enter an appropriate description for the data source. 5. Specify the script name database file. In the Script Name field, enter the following value: Script Name *.dat This indicates that the browse method will be used to create the script name database file. When you have finished, the window should resemble the following illustration. 6. Adjust the number of files that can be opened concurrently (optional). The default value of 200 should be adequate for most users. 7. Indicate the driver to use. If you are accessing c-tree data locally, choose Multi-User (non-server). If you are accessing data on a FairCom Server, choose TCP/IP. Great Plains does not recommend using the browse method of setting up an ODBC data source if you re accessing data on a FairCom Server. Use the script method instead. ODBC REFERENCE 61

66 PART 4 FAIRCOM ODBC DRIVER 8. Specify additional settings (optional). Click Options to display additional options for the ODBC driver. Column Order This option specifies whether columns are displayed in the order they appear in the table, or are sorted alphabetically. Data Dictionary Path This option specifies the location of the CTSYSCAT.FCS file, which is typically located in C:\OTREE. Table s max number of columns This option specifies the maximum number of columns that can be supported by a specific table. The current maximum is 5000, but some ODBC applications limit this value to 256 or 300. c-tree Plus Debug If marked, this option produces a log file named CTODBC.LOG, containing debug information. 9. Finish setting up the data source. Click OK to finish setting up the data source. Click OK to close the ODBC Data Source Administrator. Testing a data source - browse method Once you have set up a data source using the browse method, we recommend testing it with Microsoft Query. Microsoft Query is a generalpurpose data retrieval tool that comes with Microsoft Office and Microsoft SQL Server. Use the following procedure to test the ODBC data source. 1. Launch Microsoft Query. 2. Create a new query. To create a new query, choose New from the File menu. The Choose Data Source window will appear. 62 ODBC REFERENCE

67 CHAPTER 15 SETTING UP A DATA SOURCE - BROWSE METHOD 3. Select a data source. In the list of data sources, select the appropriate data source. You may have to use the Browse button to find the data source you created. Be sure the Use the Query Wizard option is not marked. Once you have selected a data source, click OK. The following dialog box will appear: 4. Indicate you want to browse to select the tables to use. Click Yes to indicate that you want to browse to select tables that will be available for the query. A new script name database file (OTREE.DB) will be created based on the tables you select. The following dialog will appear: 5. Select the tables you want available for the query. Use the dialog to navigate to the directory that contains the c-tree data tables you want to make available for the query. The tables you select will be included in the script name database file. ODBC REFERENCE 63

68 PART 4 FAIRCOM ODBC DRIVER You can select multiple tables by holding down the SHIFT key while you select them. To select non-contiguous tables, hold down the CTRL key as you select them. You can select tables from only one directory at a time. In the previous illustration, tables from only the Sales directory could be added to the script name database file. In Step 7 of this procedure, you will have the opportunity to select additional tables in other directories. Click OK when you have finished selecting tables from the current directory. 6. Indicate whether to append to or replace the existing script name database file. The following dialog will be displayed. Click Yes if you want to append to the existing database file. Click No if you want to replace the existing file. 7. Indicate whether you want to select additional tables. The following message will be displayed, asking whether you want to select additional tables. If you want to select additional tables, click Yes. Otherwise, click No. Once you ve created the OTREE.DB file, you can add additional tables to it by repeating this procedure and choosing to append to the existing file. If you repeat this procedure without appending to the file, the OTREE.DB file will be replaced. 64 ODBC REFERENCE

69 CHAPTER 15 SETTING UP A DATA SOURCE - BROWSE METHOD 8. Select the tables to use for the query. In the Add Tables window, select each table you want to use for the query and click Add. When you have finished, click Close. 9. Specify the columns to include in the query. Double-click the column names or drag column names from the list to the data area at the bottom of the window. Double-click the * to add all of the columns from the table. If the data in the columns appears as you expect, the ODBC driver is set up correctly. You should be able to use it with other applications such as Crystal Reports. ODBC REFERENCE 65

70 66 ODBC REFERENCE

71 Chapter 16: Setting Up a Data Source - Script Method With the script method, you manually create the contents of the script name database file. This is more flexible than the browse method for setting up a data source. Creating a data source - script method To create a data source using the script method, perform the following steps: 1. Create the script name database file. Use a text editor such as Windows Notepad to create the script name database file. The name for this file should have the form: database.db, where database is up to 8 characters. Typically, this file will be placed in the C:\OTREE directory. 2. Create an entry for each table. The script name database file should include an entry for each table that you will be accessing with ODBC. Each entry has the following form: alias path The alias is the name that will be associated with the table. It shouldn t contain spaces. For c-tree files stored locally or in a network location, the path is the complete path to the table as seen by the client. For c-tree files stored on a FairCom Server, the path is the location of the table as seen on the server, not as seen by the client machine. For optimal performance, limit the number of tables listed in the database file to no more than 50. The following are sample entries for a script name database file: Data files on local hard drive: GL_Budget Finance_YTD_Trx Customers c:\dynamics\two_inc\finance\gl00200.dat c:\dynamics\two_inc\finance\gl20000.dat c:\dynamics\two_inc\sales\rm00101.dat Data files on shared network drive: GL_Budget Finance_YTD_Trx Customers f:\dynamics\two_inc\finance\gl00200.dat f:\dynamics\two_inc\finance\gl20000.dat f:\dynamics\two_inc\sales\rm00101.dat ODBC REFERENCE 67

72 PART 4 FAIRCOM ODBC DRIVER Data files on a FairCom Server: GL_Budget Finance_YTD_Trx Customers c:\dynamics\two_inc\finance\gl00200.dat c:\dynamics\two_inc\finance\gl20000.dat c:\dynamics\two_inc\sales\rm00101.dat Notice the path used for files on the FairCom Server is that as seen on the FairCom Server machine, not as seen from the client machine. Sample database (.DB) files for the Dynamics lesson company were installed in the C:\OTREE\GPS directory when you installed the FairCom ODBC driver. You can use these samples as templates when creating your own database file. 3. Open the ODBC Data Source Administrator. Data sources are set up using the ODBC Data Source Administrator, which is accessed by double-clicking the 32bit ODBC control panel. 4. Create a new User DSN. In the ODBC Data Source Administrator, click the User DSN tab. Then click the Add button. 68 ODBC REFERENCE

73 CHAPTER 16 SETTING UP A DATA SOURCE - SCRIPT METHOD 5. Select the FairCom ODBC driver. In the list of drivers, select the FairCom ODBC driver. Click Finish to continue. 6. Name the data source. Enter a name for the data source. Typically, the name indicates the source or type of data that is being accessed. You may also want to enter an appropriate description for the data source. 7. Specify the name of the script name database file. In the Script Name field, enter the name of the script name database file you created. For this example, the DYNDATA.DB file is being used. Typically, the script name database file will be located in the C:\OTREE directory. If you want to use a script name database file in another location, click the Options button and enter the location of the database file in the Data Dictionary field. ODBC REFERENCE 69

74 PART 4 FAIRCOM ODBC DRIVER 8. Adjust the number of files that can be opened concurrently (optional). The default value of 200 should be adequate for most users. 9. Indicate the driver to use. If you are accessing c-tree data locally, choose Multi-User (non-server). If you are accessing data on a FairCom Server, choose TCP/IP. If you chose TCP/IP, enter the name of the FairCom Server in the Server Name field. The name should have the form: server_name~@host_name where server_name is the name of the FairCom Server, and host_name is the TCP/IP name of the machine on which the FairCom Server is located. For example, if the FairCom Server was named CTServer and the machine s TCP/IP name was res.gps.com, the entry in the Server Name field would be: CTServer~@res.gps.com If the host name doesn t work, you may need to replace it with the numeric TCP/IP address of the machine that is running the FairCom Server. The tilde (~) is necessary to indicate that the Dynamics version of the FairCom Server is being used 10. Specify additional settings (optional). Click Options to display additional options for the ODBC driver. Column Order This option specifies whether columns are displayed in the order they appear in the table, or are sorted alphabetically. Data Dictionary Path This option specifies the location of the CTSYSCAT.FCS file, which is typically located in C:\OTREE. Table s max number of columns This option specifies the maximum number of columns that can be supported by a specific table. The current maximum is 5000, but some ODBC applications limit this value to 256 or 300. c-tree Plus Debug If marked, this option produces a log file named CTODBC.LOG, containing debug information. 70 ODBC REFERENCE

75 CHAPTER 16 SETTING UP A DATA SOURCE - SCRIPT METHOD 11. Finish setting up the data source. Click OK to finish setting up the data source. Click OK to close the ODBC Data Source Administrator. Testing a data source - script method Once you have set up a data source using the script method, we recommend testing it with Microsoft Query. Microsoft Query is a generalpurpose data retrieval tool that comes with Microsoft Office and Microsoft SQL Server. Use the following procedure to test the ODBC data source. 1. Launch Microsoft Query. 2. Create a new query. To create a new query, choose New from the File menu. The Choose Data Source window will appear. 3. Select a data source. In the list of data sources, select the appropriate data source and click OK. You may have to use the Browse button to find the data source you created. Be sure the Use the Query Wizard option is not marked. 4. Select the tables to use for the query. In the Add Tables window, select each table you want to use for the query and click Add. When you have finished, click Close. ODBC REFERENCE 71

76 PART 4 FAIRCOM ODBC DRIVER If no tables are displayed in the Add Tables window, it is likely that the script name database file can t be found. Be sure it has the correct name and is in the appropriate directory. If a specific table can t be accessed, check the path for the table in the script name database file. 5. Specify the columns to include in the query. Double-click the column names or drag column names from the list to the data area at the bottom of the window. Double-click the * to add all of the columns from the table. If the data in the columns appears as you expect, the ODBC driver is set up correctly. You should be able to use it with other applications such as Crystal Reports. 72 ODBC REFERENCE