Table Of Contents. KB_SQL ODBC Driver What's New? Understanding ODBC Driver Installation and Setup... 9

Transcription

1 KBSODBCDriver

2

3 Table Of Contents KB_SQL ODBC Driver... 1 What's New?... 3 Understanding ODBC... 7 Driver Installation and Setup... 9 Server and Network Configuration Server Info Network Configuration TroubleShooting Starting the Server Starting the Server Stopping the Server Stopping the Server Simulating ODBC with QUICK^SQL Managing ODBC Data Sources Data Sources Tracing ODBC Calls Tracing_on_the_Client Tracing_on_the_Server Connection Pooling Windows Applications Programming Considerations ODBC API Calls iii

4 KBSODBCDriver M Programming ActiveX Data Objects (ADO) Appendixes A - Escape Sequences B - Connection Options C - Error Messages D - Info Types E - Data Types Index iv

5 KB_SQL ODBC Driver KB_SQL ODBC Driver The KB_SQL ODBC Driver allows you to connect your M database to a world of applications. This document describes the ODBC solution in the context of the KB_SQL Server product provided by Knowledge Based Systems, Inc. For more information about ODBC, please see the Microsoft documentation available at For questions about KB_SQL, please see the documentation available at To report a problem, or to get technical support, licensed users should have their database administrator contact KBS technical support at support@knowledgebasedsys.com. 1

6

7 What's New? Changes in this Release The KB_SQL ODBC Driver for KB_SQL Version 4 is a completely new and updated driver designed to work with the latest applications from Microsoft, including Microsoft Office97 and Office2000. ODBC SDK 3.51 Driver and server compatibility File data source names Silent configuration options Connection pooling Safe threads Multi-row fetch Custom network support Character set translation ODBC SDK 3.51 The version 4.0 KB_SQL ODBC driver has been updated to be compliant with Microsoft s latest SDK for 32-bit ODBC Drivers. Numerous performance and flexibility improvements have been made to the driver. Connection pooling Connection pooling enables an application to use a connection from a pool of established connections. If a connection has already been created and placed in a pool, an application can use that connection without performing the entire connection process. Re-using connections from the pool can increase performance since applications can save the overhead involved in making a connection. This is especially significant for middle-tier applications that connect over a network or in a situation where the application repeatedly connects and disconnects (e.g. Internet applications). Enabling Connection Pooling Connection pooling can be used by an ODBC application if the application calls SQLSetEnvAttr with the SQL_ATTR_CONNECTION_POOLING attribute. In order to enable connection pooling with KB_SQL s ODBC driver, it will be necessary to enable 3

8 KBSODBCDriver the feature and set the timeout value via the ODBC administrator. This timeout value determines the period of time which an inactive connection is removed from the pool. Driver and server compatibility We will continue to support older versions of the KB_SQL ODBC Driver that work in the ODBC version 2.x mode. This has been accomplished by physically separating the two versions of the Server API code, including the stored procedures for catalog functions. Please note that the older version of the stored procedures and SQL catalogue tables have been renamed. Version 2.x stored procedures and SQL catalogue tables all end with A (for example, SQL_SP_COLUMNSA). Please note that although older drivers can be used with the new server, using the older drivers will prohibit the use of new server features (for example, the LONG data type). In addition, because KBS will not be providing bug fixes for older releases, we strongly urge upgrading to the latest driver. Special Note About the 16-bit Driver Please note that no new development has been performed on the 16-bit ODBC driver. The 16-bit driver is currently in maintenance mode using Microsoft ODBC SDK Although applications using the 16-bit ODBC driver will continue to work, they will not be able to take advantage of any new features. File data source names We now support the dynamic creation of file data source names from the ODBC Administrator and Microsoft Office applications. Previous versions of the product required that file data source names be created manually. File DSNs can be shared on network drives and can simplify workstation configuration. Silent configuration options The product now supports DSN-less connections. This feature provides the ability to connect to a remote data source without having to create a data source in the ODBC Administrator, thus simplifying application distribution. Safe threads For customers that are using, or are interested in using multi-threaded applications such as Microsoft Transaction Server, Internet Information Server, and Java, version 4.0 fully supports safe threads. KB_SQL version 4.0 fully supports safe threads so that applications can use the same handle on more than one thread. In a multi-threaded environment, it is possible for each thread to have independent data. However, it is also possible for multiple threads to share data. In this situation, the different threads must cooperate in accessing the data. Multi-row fetch 4

9 What's New? We now support SQLExtendedFetch and SQLFetchScroll. In ODBC 3.0, SQLFetchScroll has replaced SQLExtendedFetch. These calls allow an application to retrieve multiple records at one time thus reducing the number of calls between the application and the driver. Custom network support Version 4 separates the client, network, and setup API functions so that each can be developed independently. Because the components are separated, customers have the option to develop custom network interface modules based on their networking or security conventions. Contact KBS technical support for more information on how you could implement a custom network module. Character set translation Prior to this release, ANSI to OEM character translation was performed on the server side by specifying the translation rules in the site global. With version 4.0, character set translation is performed on the driver side. To implement the character set translation, it will be necessary to specify the appropriate translation DLL for the data source name via the ODBC Administrator. 5

10

11 Understanding ODBC What is ODBC? ODBC (Open Database Connectivity) is a standard interface developed by Microsoft for accessing data from different kinds of SQL database management systems. See for additional information. What does this mean to the M Community? This means that you can use many of the Windows applications already on your desktop to get to your M data. With the KB_SQL Server together with the KB_SQL ODBC Driver, you can now use the Microsoft Office programs including Excel, Word, and Access or any ODBC-compliant Windows application to access your M data. You have many more choices for data access and reporting of your M application data. How does it work? The KB_SQL ODBC Architecture consists of six main components: your Windows application programs the ODBC Driver Manager the KB_SQL ODBC Driver networking software (TCP/IP) the KB_SQL Server Interface the KB_SQL Engine and relational data dictionary The KB_SQL ODBC Architecture Resident on your workstation, the client side, you need your Windows applications, the ODBC Driver Manager, the KB_SQL ODBC Driver, and the networking software. Your Windows applications can be any ODBC-compliant Windows application. They can be commercial off-the-shelf products like Microsoft s Excel and Visual Basic or custom applications. Microsoft provides The ODBC Driver Manager component. Its primary function is to load the driver. If it is not resident on your system at the time you install the KB_SQL ODBC Driver, the setup program, on your installation disk, will install it for you. The KB_SQL ODBC Driver enables any ODBC-compliant Windows application to access data from your KB_SQL RDBMS. The driver must be accessible to each workstation that wants to use Windows applications to access the KB_SQL Server. You can install the driver on as many workstations as you like. Access to 7

12 KBSODBCDriver your M data is limited only by your KB_SQL license, which determines the number of concurrent users. Networking software is necessary to communicate between the Driver and Server. The KB_SQL ODBC Driver requires TCP/IP networking software. On your server, you need to install KB_SQL Server and you need to have your M globals mapped as SQL tables into a SQL data dictionary. If you have any previous version of KB_SQL, this has already been done. The KB_SQL Server Interface encapsulates the Server API and Network Library M, and exposes the KB_SQL Engine to the client. Benefits of KB_SQL ODBC You are free to select the application that is most appropriate for the task at hand. At any point in time, you can choose to use either the EZQ or SQL Editors that come packaged with KB_SQL, or you can select from many ODBC-compliant Windows applications. You can continue to access your M data from a terminal or choose a workstation that has access to a KB_SQL ODBC Driver. KB_SQL ODBC simplifies application development. You can write a single application that can be used to extract data from many different databases, permitting maximum interoperability and portability of the application. With KB_SQL ODBC, accessing M is like accessing any other RDBMS. Actually, the fact that you may be accessing different types of databases concurrently is transparent to you. 8

13 Driver Installation and Setup Before you begin Before installing the KB_SQL ODBC Driver, there are a couple of items to note. Is the Server installed and configured? Do you know the Server configuration parameters for the Hostname (or IP address), and listening port? Can you ping the Server using the Hostname (or IP address)? If running WindowsNT, do you have Administrator privileges? Driver Installation Step 1: Launch the KB_SQL ODBC Driver Installer. Step 2: Accept the terms of the license agreement. After accepting the terms, the installer will update your system with the KB_SQL ODBC Driver and other ODBC Components. 9

14 KBSODBCDriver Default Data Source Create a The installer continues, allowing you to create a Data Source as part of the installation. Step 4: Give the Data Source a name and description. Step 5: Specify the Network parameters. 10

15 Driver Installation and Setup Step 6: Specify a Code Page Translator Step 7: Congratulations! 11

16 KBSODBCDriver 12

17 Server and Network Configuration Server Info ServerInfo Prefix for stored query routines Maximum number of stored queries Allow connections Trace API calls Edit network configuration Server initial execute Server user initial execute Prefix for stored query routines Assign a name to the holding place for the last x number of queries run. For example, if you enter XA, the Server API allocates routine names starting with XA1 up to the maximum number of stored queries specified. Maximum number of stored queries 13

18 KBSODBCDriver Enter the number of queries that you want held in the stored queries buffer on the server. The value you supply is a matter of storage space versus processor resources. Assigning a large number requires more storage capacity but less processing time. Conversely, assigning a smaller number requires less space to store queries, but causes more processing by the SQL engine. Here s why: As the Server API receives each SQL command, it checks the stored queries buffer for the command s corresponding M routine. If it finds the M routine, it simply runs it. If it doesn t, it has to use the SQL engine to translate the command into one or more M routines. The M routine and corresponding SQL command are then stored and assigned a routine name using the base routine prefix. If you specify a large number, say 999, many commands can be processed before having to reuse a stored query for another command. When the maximum number has been reached, KB_SQL reuses the oldest stored query to store the next query s M routine and corresponding SQL command. You may clear the stored queries buffer of all routine names by invoking the RL^SQL tag. Allow connections Answer YES to accept connections to the server. Answer NO if you want to refuse connections. Note that the server will not start if the system lock is set. (Refer to the UTILITIES\LOCK STATUS option.) If the server is running and you want to stop allowing connections, first invoke the STOP^SQL0SVR function. Then set this prompt to NO. Regardless of the setting of this prompt, the server can always be run in foreground useful for testing purposes when you don t want the server to be started in background. If the server is not running when you set this value to YES, you still have to start the server. It is n ot automatically started. To start the server, see the instructions for starting and stopping the KB_SQL Server later in this chapter. Trace API calls Answer YES if you want to track information about the dialog between the server and clients. This creates a log that you can view by using the SQL Editor to run the SQL_ API_SERVER_TRACE query, or by using the tag VIEW^SQL0SVR. Edit network configuration Answer YES if you want to edit TCP/IP defaults or host information. The TCP/IP Defaults window will appear. A discussion of this process begins on the next page. Server initial execute 14

19 Server and Network Configuration Enter the M code that will instantiate any variables that are required by your application during the runtime execution of queries. Server user initial execute Enter the M code that will validate and/or establish the username (SQLUNAME) and password (SQLUAUTH) variables referenced during the connection to the server. Network Configuration NetworkInfo n general, the network information you are required to provide consists of the TCP/IP host and port information. Depending on your M implementation type, you might be required to provide alternate ports. TCP/IP Defaults TCP/IP Host Definition TCP/IP Port Defintion TCP/IP Defaults 15

20 KBSODBCDriver Timeout for read Enter the number of seconds after which a READ command commands should timeout and check error status (default = No timeout) Maximum length Enter the maximum size of an M string value in this of M string implementation (default = 511). Output buffer size Enter the output buffer size in bytes (default = 2048). Input buffer size Enter the input buffer size in bytes (default = 2048). TCP/IP Host Definition Host name Enter the TCP/IP hostname for the server. IP address Enter the internet protocol address for the server. If your system uses dynamic ip address allocation, enter the host name in this field. Description Enter a brief description of this server. Local host? Enter YES if you are describing the server on which KB_SQL is running. Enter NO if you are documenting another server. TCP/IP Port Definition 16

21 Server and Network Configuration Port number Port server? The port number is expected to be in the range of Answer YES if this is the published port for connecting to this server. Answer NO if this is an alternate port to be used internally. TroubleShooting Network Troubleshooting Troubleshooting network connections can be challenging due to complex configurations. However, we've found that most of the errors related to KB_SQL have been incorrectly configured servers. It is easy to check the configuration of your server using our built-in testing tool, TEST^SQL0TCP. In general, we try to include useful information in error message displays. As for networking errors, we try to include the Windows Sockets (WinSock) error code as part of the message. If you see Connection Refused, you probably need to check that your server is started. If you receive the error No Route to Host, you might have specified a host address incorrectly. Using TEST^SQL0TCP VMS Cluster Issues Using TEST^SQL0TCP There are low-level TCP/IP testing tools available through KBS technical support. If you think you are having network trouble, please call us. 17

22 KBSODBCDriver Starting with KB_SQL v3.6, we provide a simple utility to test the configuration of your Server and Network. The TEST^SQL0TCP utility will attempt connections from your Server back to itself, and keep trying connections until it fails. For example: >D TEST^SQL0TCP KB_SQL Server Connect Test Server Name or Address: // Port Number : 6500// UserName : DBA PassWord : Connecting to (6500) Error in connect: 0579: TCP/IP Timeout in Open As the error message implies, the attempt to connect has timed out. The most likely cause is that the server is not started. >D START^SQL0SVR >W $D(SQLERR) 0 This attempt to start the server is successful, as it does not return an error in the SQLERR variable. Now, try the connect test again. >D TEST^SQL0TCP KB_SQL Server Connect Test Server Name or Address: // Port Number : 6500// UserName : DBA PassWord : Connecting to (6500) Connected to #1: TCP 5~ ~ Connecting to (6500) Connected to #2: TCP 6~ ~ Connecting to (6500) Connected to #3: TCP 7~ ~ Connecting to (6500) Connected to #4: TCP 8~ ~ Connecting to ( 6500) Connected to #5: TCP 9~ ~ Connecting to (6500) Connected to #6: TCP 10~ ~ Connecting to (6500) Connected to #7: TCP 11~ ~ Connecting to (6500) Connected to #8: TCP 12~ ~ Connecting to (6500) Error in connect: [S1000] (139): [Knowledge Based Systems, Inc.][Server API][V4.0]SQLConnect: Exceeded KB_SQL V4.0 license limit 18

23 Server and Network Configuration Disconnecting #8: TCP 12~ ~ Disconnecting #7: TCP 11~ ~ Disconnecting #6: TCP 10~ ~ Disconnecting #5: TCP 9~ ~ Disconnecting #4: TCP 8~ ~ Disconnecting #3: TCP 7~ ~ Disconnecting #2: TCP 6~ ~ Disconnecting #1: TCP 5~ ~ Notice that it gets 8 connections before it encounters an error. It shows that this attempt to connect is rejected because it would exceed the current limit of your license. This is the error that you want to get in this context. It ensures that everything is working. If you get other errors, it is helpful to pass on the information to our technical support. Currently, the most common problem with connecting is that the Server is not started. We recommend adding START^SQL to your system startup logic. The second most common problem is for those M types that require alternate ports (ISM, DSM, and others), that not enough are configured. We always recommend configuring at least as many ports as you have connections on your license. Configuring more doesn't hurt either. VMS Cluster issues On VMS clusters, it gets very tricky when starting an M process to listen for connections. The M database has a single definition of the local host. One or more nodes can access the database. Starting the listener from a node other than the one identified in the local host setting can have confusing consequences. One way of preventing this problem is to disable the auto startup feature using Site Edit. Another way is to add code to the Server StartUp Execute to test whether the current node matches the local host definition. If it doesn't, then the Server should not be allowed to start. Simply return an error in SQLERR. Starting the Server Starting the Server There are several methods available for starting the KB_SQL Server. You may start it either in the foreground for analysis and debugging purposes or in the background for a multi-user production environment. Foreground Options Background Options Foreground You may run the KB_SQL Server in foreground during configuration until you are satisfied that you are able to connect and process client requests. The following foreground options are available: 19

24 KBSODBCDriver 1. Output to Screen Command: >D ^SQL0SVR Description: This command is for general configuration, analysis and debugging. Sample Output: Waiting for client connection... KBSGetInfoShort("1010","23") = (0,"2") KBSGetInfoShort("1010","24") = (0,"2") SQLAllocStmt("1010") = (0,"2007") SQLPrepare("2007","select * from employees") = (0,"1") SQLNumResultCols("2007") = (0,"4") SQLDescribeCol("2007","1") = (0,"EMP_SSN","12","11","0","0") SQLDescribeCol("2007","2") = (0,"NAME","12","15","0","0") SQLDescribeCol("2007","3") = (0,"SALARY","2","5","2","1") SQLDescribeCol("2007","4") = (0,"MANAGER","12","11","0","1") SQLExecute("2007") = (0) KBSRowsetFrame("2007","1","20480") = (100,"48"," ","JOHNSON","9"," ",... SQLFreeStmt("2007","0") = (0) SQLFreeStmt("2007","0") = (0) SQLDisconnect("1010") = (0) 2. Output to File Command: >D FILE^SQL0SVR("[FILE NAME]") Example: >D FILE^SQL0SVR("c:\temp\svrtrace.log") Description: This command is used to capture the output from a client/kb_sql Server interaction for analysis, debugging, or submittal to KBS Technical Support. 3. Output to Printer Command: >OPEN %DEV USE %DEV DO ^SQL0SVR CLOSE %DEV Example: >O 3 U 3 D ^SQL0SVR C 3 Description: This command is used to capture output from a client/kb_sql Server interaction for analysis, debugging, or submittal to KBSs Technical Support. 4. Without Error Trapping Command: DO NOTRAP^SQL0SVR Description: This option turns off KB_SQL error trapping. When a hard M error is 20

25 Server and Network Configuration encountered, the server will stop and the error will be displayed in the native format for your M implementation Note: The foreground server options are intended only for analysis or debugging purposes. As it allows only a single connection, it is not appropriate for a multi-user environment. Background If you have answered Yes to Allow Connections? in Site Edit/Server Info and your KB_SQL Server is properly configured, you may start the server simply by logging into KB_SQL as a DBA or System Manager. You may also type: >D START^SQL0SVR at the M prompt. This command line option allows you to start KB_SQL Server during the startup of your M system or other times without the requirement to log into KB_SQL. If, for some reason, the Server fails to start, the variable SQLERR may be trapped and be used to determine the reason for failure. Stopping the Server Stopping the Server You may need to stop the KB_SQL Server for various reasons (shutting down M, system maintenance, etc.) You may stop the KB_SQL Server with the following command: D STOP^SQL0SVR This command may be called from procedures such as Shutdown, etc. Note: It is important to understand that this command does not affect current connections to the KB_SQL Server. It does, however, prevent any new connections from being established. As some applications require multiple database connections for operation, it is best to ensure that everyone is logged off before stopping the KB_SQL Server. You may check current connection status by choosing Connections on the System Status menu. 21

26

27 Simulating ODBC with QUICK^SQL Using QUICK^SQL The Quick SQL Editor (QUICK^SQL) is a KB_SQL query interface that lets you use Windows Notepad to enter your SQL statements, save the statements as a text file, and execute the file from the QUICK utility. Queries executed from this interface take the same path as a query created from an ODBC application. Because of this you can use this editor to simulate queries from ODBC applications. The Quick SQL Editor is also a valuable tool for testing stored procedures and parameterized queries. >D QUICK^SQL Password: Enter SQL Command GO Execute command STOP Exit RESET Clear command CALL procedure() Call stored Read commands from file -->SELECT NAME, PROJECT FROM PROJECTS -->GO NAME PROJECT GREEN PHARMACY ROBERTS LABORATORY ROBERTS MEDICAL RECORDS GREEN ACCOUNTING (4 rows) 23

28

29 Managing ODBC Data Sources Data Sources Data Source Types There are two types of data sources: machine data sources and file data sources. Although both contain similar information about the source of the data, they differ in the way this information is stored. Because of these differences, they are used in somewhat different manners. Data Description source User These are local to a computer, and can only be used by the current user. User DSN data sources are registered in the HKEY_CURRENT_USER registry subtree. System These are local to a computer, rather than dedicated to a user. The system, or DSN any user having privileges, can use a data source set up with a system data source. System DSNs are registered in the HKEY_LOCAL_MACHINE registry subtree. File These are file-based sources that can be shared between all users that have the DSN same drivers installed, and so have access to the database. These data sources need not be dedicated to a user or local to a computer. File data sources do not have a data source name, as user or system data sources do; they are identified by a file name with a DSN extension. User and system data sources are collectively known as machine data sources because they are local to a computer. Each of these data sources has a tab in the ODBC Administrator that is dedicated to that type. File DSN File data sources are stored in a file and allow connection information to be used repeatedly by a single user or shared among several users. When a File DSN is used, the Driver Manager makes the connection to the data source using the information in a.dsn file. This file can be manipulated like any other file. A File DSN does not have a data source name, as does a machine data source, and is not registered to any one user or machine. A File DSN streamlines the connection process, because the.dsn file contains the connection string that would otherwise have to be built for a call to the SQLDriverConnect function. Another advantage of the.dsn file is that it can be copied to any machine, so that identical data sources can be used by many machines as long as they have the appropriate driver installed. A File DSN can also be shared by applications. 25

30 KBSODBCDriver A shareable File DSN can be placed on a network and used simultaneously by multiple applications. A file DSN can also be unshareable. An unshareable.dsn file resides on a single machine and points to a machine data source. Unshareable File data sources exist mainly to allow the easy conversion of machine data sources to File DSN so that an application can be designed to work solely with File DSNs. When the Driver Manager is sent the information in an unshareable File DSN, it connects as necessary to the machine data source that the.dsn file points to. Example Here is an example of a File DSN for a KB_SQL connection. Note that the file is typically stored in the default path provided by Microsoft, but the file can be stored anywhere including on a networked drive. C:\Program Files\Common Files\ODBC\Data Sources\KBSQL.DSN [ODBC] DRIVER=KB_SQL ODBC 32-bit Driver UID=DBA SERVER=KB_SQL MaximumString=220 CommunicationBuffer=20 Network=C:\WINNT\System32\kbnet32.dll Setup=C:\WINNT\System32\kbset32.dll TCP_PORT=6500 HOST= Tracing ODBC Calls Tracing API Calls One of the best ways to understand what is going on when an application uses an ODBC connection to a remote data source is to trace the conversations. There are several conversations going on. The client-side-trace refers to the tracing of the conversation between the application and the ODBC Driver Manager. The server-side-trace refers to the tracing of the conversation between the KB_SQL ODBC Driver and the KB_SQL Server. In general, the server-side trace is the most useful to KBS support and is also the easiest to interpret. The client-side trace is a secondary source of information. It can be challenging to interpret -- let us help you. Tracing_on_the_Client Tracing on the Client The ODBC Driver Manager has a trace facility that allows the sequence of function calls made by an ODBC application to be recorded and transcribed into a log file. Tracing is 26

31 Managing ODBC Data Sources performed by a trace DLL that captures calls between the application and the Driver Manager, and the Driver Manager and the driver. This method of tracing replaces the tracing performed by the ODBC 2.x Driver Manager and the tracing performed in ODBC 2.x by ODBC Spy. Enabling tracing Certain situations call for examination of the conversational exchange between the application and the driver manager. This can be accomplished using the tracing option provided by Microsoft. Sample trace output The trace file can be large and its contents are not intuitive. However, these details are invaluable to KBS technical support representatives when trying to diagnose application 27

32 KBSODBCDriver behaviors. Tracing_on_the_Server Tracing on the Server In developing your own custom Windows applications for use with your KB_SQL database, you may find it necessary from time to time to view the interaction between your application and the KB_SQL Server. All communication between ODBC-compliant applications and KB_SQL occurs in sequences of function calls. These function calls may be recorded and reported on for both informative and debugging purposes. The following sections will describe the enabling of the API Trace feature and the viewing of the output of an API Trace session. Enabling the API Trace Feature Viewing the API Trace Interpreting the API Trace Enabling the API Trace Feature 1. Sign on to KB_SQL as DBA or System Administrator. 2. Choose SYSTEM STATUS. 28

33 Managing ODBC Data Sources 3. Choose SERVER INFO. 4. Choose TRACE OPTIONS. 5. Select ENABLE TRACING. Caution: The API Trace feature is intended for informative and debugging purposes only. It is not intended to be run in a production environment. If it is necessary to use the trace, we recommend turning it on right before you use it and turning it off immediately afterwards. Viewing the API Trace 1. Sign on to KB_SQL. 2. Choose SYSTEM STATUS. 3. Choose SERVER INFO. 4. Choose TRACE OPTIONS. 5. Select VIEW TRACE. 29

34 KBSODBCDriver Interpreting the API Trace Upon running the SQL_API_SERVER_TRACE query, you will see a screen describing the connection information for the most recent KB_SQL Server connection. Following this information is the sequence of function calls from the client application to the KB_SQL Server, ordered from earliest to last. There are a number of sources you may use in helping you to determine the functionality behind each of these function calls: The online query SQL_API_LIST. This query lists all ODBC API functions supported by KB_SQL with a brief description of each. See ServerAPI functions for an overview of the KB_SQL ODBC Architecture as well as a detailed description of all currently supported function calls. The Microsoft ODBC 2.0 Programmer s Reference and SDK Guide. This is the definitive work on the ODBC specification. KBS recommends this book to anyone involved in developing and deploying ODBC-compliant applications. Connection Pooling Connection pooling Connection pooling enables an application to use a connection from a pool of established connections. If a connection has already been created and placed in a pool, an application can use that connection without performing the entire connection process. Re-using 30

35 Managing ODBC Data Sources connections from the pool can increase performance since applications can save the overhead involved in making a connection. This is especially significant for middle-tier applications that connect over a network or in a situation where the application repeatedly connects and disconnects (e.g. Internet applications). Enabling Connection Pooling Connection pooling can be used by an ODBC application if the application calls SQLSetEnvAttr with the SQL_ATTR_CONNECTION_POOLING attribute. In order to enable connection pooling with KB_SQL s ODBC driver, it will be necessary to enable the feature and set the timeout value via the ODBC administrator. This timeout value determines the period of time which an inactive connection is removed from the pool. 31

36

37 Windows Applications Overview of Windows Applications Using Windows Applications with KB_SQL is just as it is for using Windows applications with any oth er SQL Data Source. See the documentation for the specific Windows application for more information about working with SQL Data Sources. Microsoft Access Connecting Connecting from Microsoft Access to your M system is easy using the KB_SQL ODBC Driver. The connection will be attempted based on a decision made within Access, typically during t he file linking process. You are able to use any of the connection types and you will be e xpected to log in with your KB_SQL username and password. Save password During the connection process, you will have the option of saving your username and password with the Access database information. This would allow you to reopen the database and reconnect to the server without having to reenter your username and password information. Note also that this capability can be disabled by correctly configuring the MsysConf table on the server. Contact KB Systems technical support for more information. S hould I import or link a table? M icrosoft Access provides two cho ices for using data from an external source: Import the M data into a new Microsoft Access table in the current database. Leave the data in the M database and use it in its current format without importing it -- this is called linking. If you know you will use your data o nly in Microsoft Access, you should import it. Microsoft Access generally works faster with its own tables, and if you need to, you can modify the imported table to meet your needs just like any other table created in Microsoft Access. One of the key considerations here is the volume of data and the security issues related to removing a copy from the server. These issues should be considered with your a pplication vendor or information systems department representative. If the data you want to use is also being updated by a program other than Microsoft Access, you should link it. Using this approach, the current methods of updating, managing, and sharing the data can rem ain in place, and you can use Microsoft Access to work with the data as well. For example, you can create queries, forms, and reports that use the external data, combine external data with the data in Microsoft Access tables, and even view and edit the external data while others are using it in the original program. Recordsets: Dynasets and Snapshots 33

38 KBSODBCDriver Microsoft Access uses the JET (Joint Exchang e Technology) Engine to manage database interactions. The JET Engine is a powerful query processor with many features, including the intelligence to perf orm distributed queries across multiple data sources. The results of queries run through JE T are stored in record se ts. These record sets can be of two types: Dynasets or Snapshots. For the most part, you will probably want snapshots as these are designed purely for retrieval and reporting purposes. If you are doing updates, dynasets will allow you to update rows on the remote data source. Data types Microsoft Access has its own set of data types. These types are mapped onto the ODBC types which are themselves mapped on to the data types supported on the data source. This can lead to confusion. The documentation for Microsoft Access is your best guide to understanding why the data appears different in an Access database than it does when you look at the same data on the server. Microsoft Query Connecting Connecting from Microsoft Query to your M s ystem is easy using the KB_SQL ODBC Driver. As of Microsoft Office97, MSQuery w as biased towards the use of file DSNs. This limitation is removed with Microsoft Office97 Service Pack #2. You are able to use any of the connection types and you will be expected to log in with your KB_SQL username and password. GetExternalData The option to use MSQuery from Excel and Word is dependent on your installation. The MSQuery component is not installed by default. If it is not available to you, check with your system administrator. Return Data to Excel Assum ing you have the option installed for ge tting external data, the obvious next step is to return the data to Excel. The rules for saving the data, query, and password information are all controlled by the Microsoft applications. Please check with the application documentation if you have questions about how data is returned. Data types M icrosoft Query has its own set of data types. These types are mapped onto the ODBC types which are also mapped to the data types supported on the data source. This can lead to confusion. The documentation for Microsoft Query, Excel, or Word is your best guide to understanding why the data appears differen t in a Microsoft Office application than it does when you look at the same data on the server. 34

39 Programming Considerations Architecture Accessing the KB_SQL Engine from Windows The KB_SQL Client API can be accessed as a dynamic link library (DLL) from Windows via C or Visual Basic. A Windows programming paradigm, the DLL allows one copy of a set of functions to be accessed by multiple applications. In Visual Basic, the Server API is accessed directly through the KB_SQL ODBC Driver. The ODBC Driver Manager is not involved. Again, TCP/IP provides your connection to the Server API. Expectations: Experience with Windows programming, DLLs, Windows applications, and gateways Statement Execution The KB_SQL API supports two methods of statement execution: the direct method (usi ng the SQLExecDirect function) and the prepare/execute method (using the SQLPrepare and SQLExecute functions). When an SQL statement is prepared it is sent to the server, parsed, and optimized. This is the ideal method for statements that are executed repeatedly, each time with different parameter values. An application should prepare a statement for execution if any of the following are true: The application will repeatedly execute the statement. The application needs information about the result set before executing the statement. An application can execute a statement directly if both are true: The application will execute the statement only once. The application does not need information about the result set before executing the statement Parameters An application can send parameters at statement execution time by calling the following functions: SQLBindParameter specifies the SQL data type of the parameters and reserves storage location for each parameter. SQLPutData sends data value for the parameter to the driver. 35

40 KBSODBCDriver Using data-at-execution parameters is useful for applications handling long data. See also Parameter_Markers Parameter Markers Parameter markers in a prepared SQL statement are placeholders for parameter values that ar e supplied by an application. Parameter markers are delimited by question marks. Using parameter markers in an SQL statement lets you execute the statement repeatedly with different values. This is a more efficient alternative to coding literal values in an applica tion, and changing the application each time the parameters change. To use parameter markers, the application must first call the SQLBindParameter function to bind a storage area to a parameter marker. Then the application must place the parameter s value in the storage location. Examples of using parameter markers are found in the Stored Procedures section of this chapter. See also Parameters Stored Procedures The KB_SQL Server API supports the use of stored procedures as a collection of precompiled SQL statements residing on the server. An application can call a procedure in place of an SQL statement. Stored procedures help to increase performance and consistency when performing repetitive tasks because they are compiled the first time they are executed. When executed again, subsequent run time is much shorter than for the equivalent set of stand-alone statements. Stored procedures simplify application development because you can repeatedly change them without modifying and compiling the application. Stored procedures can be created for permanent or temporary use. Temporary Stored Procedures KB_SQL creates a stored procedure for every set of SQL statements that are submitted from client applications. These procedures are available for use by all server queries for as long as the procedure is in the buffer of stored queries on the server. The query text is stored under a name where nnn represents the number of the query relative to the number of stored queries allowed. IMPORTANT: DBA users can copy the definition of a server query into a new query, but server queries should not be modified in any way. Permanent Stored Procedures KB_SQL can make any stored procedure permanent so that it will always be available regardless of the size of the stored query buffer. This type of procedure is desirable for use within custom applications. It allows the application to be developed independently of the server-side SQL statements. Only the calling parameters and result set must stay constant. Otherwise, the stored procedure can be modified as needed without affecting the client application. Steps to create a permanent stored procedure 1. Create a query that returns a result set in the ODBC format. SET CLIENT=ODBC 36

41 Programming Considerations This parameter is automatically inserted into SQL statement buffers sent from client applications. Setting STORED_PROCEDURE implicitly sets the CLIENT type. 2. Indicate that the procedure is permanent. SET STORED_PROCEDURE=YES This makes the query take on the characteristics of a stored procedure until you remove the setting. This query will appear in the result set for the SQLProcedures function. 3. Give names to input parameters (optional). SET PARAMETERS='name,city,state' You can choose to specify names for parameter markers in any query. This acts as documentation, and is accessible in the result of the SQLProcedureColumns function. Note that setting PARAMETERS implicitly sets the CLIENT type and STORED_PROCEDURE indicators. Running a stored procedure Replace the SQL statements in your application with the ODBC escape clause syntax for calling a stored procedure. Syntax {call procedure-name[(parameter[,parameter...])]} Example Replace: Select Name, Position, Salary, Comments From Employees Where EmpDept =? With: {call DeptEmps(?)} The? represents a parameter marker, in this case used to receive the department identifier. Rules Users must have SELECT privileges on the stored procedure query. The stored procedure query must be compiled in order to show in SQLProcedures, SQLProcedureColumns, or to be executed. The server will require that the number of parameters in the reference must match the number in the procedure definition. Parameter values can be specified as all literals, or all parameter markers, but not a mix. For example: Legal {call xyzproc(?,?)} {call xyzproc('abc','123') Illegal {call xyzproc(?)} -- 2 parameters required {call xyzproc('abc',?)} -- Cannot mix types 37

42 KBSODBCDriver If the parameters or the result set changes, you would have to respecify your application. Otherwise, changes can be made to the logic on the server side by editing and recompiling the query. Testin g stored procedures You may test stored procedures by using the sample routine SQLJ13. This program will let yo u enter the ODBC syntax for calling the procedure. Example >{call xyzproc(?,?)} >go Use the Execute SQL option in MSQuery to invoke a stored procedure. Note that this interface does not have a mechanism for collecting input parameters, so you must supply the values as string literals. Example {call xyzproc('abc','123')} ODBC API Calls Functions KB_SQL API Function Summary Belo w are the KB_SQL API functions, grouped by type of task, including a brief description of the purpose of each function. For more information about the syntax and semantics of each function, consult the alphabetical reference section of this chapter. Task Connecting to a data source Function Name SQLAllocEnv Purpose Obtains an environment handle. An environment handle can be used for one or more connections. SQLAllocConnect Obtains a connection handle. A connection handle can be used for one or more statements. SQLConnect Connects to a specific driver by data source name, user ID, and password. SQLDriverConnect* Connects to a specific driver by connection string or invokes driver display connection dialog boxes. Obtaining information about a driver and data SQLGetInfo Returns information about a specific driver and data source. source SQLGetTypeInfo Returns information about supported 38

43 Programming Considerations Setting and retrieving driver options data types. SQLGetFunctions Returns supported driver functions. SQLSetConnectOption Sets a connection option. SQLGetConnectOption Returns the value of a connection option. SQLSetStmtOption Sets a statement option. SQLGetStmtOption Returns the value of a statement option. Preparing SQL requests Submitting requests KBSStatement Inserts partial SQL statements. SQLAllocStmt Allocates a statement handle. SQLPrepare Prepares an SQL statement for later execution. SQLBindParameter Assigns storage for a parameter in an SQL statement. SQLGetCursorName Returns the cursor name associated with a statement handle. SQLSetCursorName Specifies a cursor name. SQLDescribeParam Returns the description of a parameter marker associated with a prepared SQL statement. SQLExecute Executes a prepared statement. SQLExecDirect Executes a statement. SQLNativeSql Returns the SQL command text as translated by the server. SQLNumParams Returns the number of parameters in an SQL statement. SQLParamData* Used in conjunction with SQLPutData to supply parameter data at execution time. SQLPutData Send part or all of a data value for a parameter. Retrieving Results and information about results SQLRowCount Returns the number of rows affected by an insert, update, or delete request. SQLNumResultCols SQLDescribeCol SQLColAttributes SQLBindCol Returns the number of columns in the result set. Describes a column in the result set. Describes attributes of a column in the result set. Assigns storage for a result column and 39

44 KBSODBCDriver specifies the data type. SQLFetch Returns a result row. SQLGetData Returns a specific column value from a statement cursor. Retrieving Results SQLError Returns additional error or status and information about information. results (continued) Obtaining information SQLColumnPrivileges Returns a list of columns and associated about the data privileges for the specified table. source s system tables (catalog functions) SQLColumns Returns a list of column names in specified tables. SQLForeignKeys Returns information about the foreign keys for a table. SQLPrimaryKeys Returns the list of column name(s) that comprise the primary key for a table. SQLProcedures Returns the list of procedure names stored in a specific data source. SQLSpecialColumns Returns information about the optimal set of columns that uniquely identifies a row in a specified table, or the columns that are automatically updated when any value in the row is updated by a transaction. SQLStatistics Returns statistics about a single table and the list of indexes associated with the table. SQLTablePrivileges Returns a list of tables and the privileges associated with each table. SQLTables Returns the list of table names stored in a specific data source. Terminating a statement SQLFreeStmt SQLCancel Ends statement processing and closes any associated cursors, discarding pending results, and optionally, frees all resources associated with the statement handle. Cancels an SQL statement. SQLTransact Commits or rolls back a transaction. Terminating a SQLDisconnect Closes the connection. connection SQLFreeConnect Releases the connection handle. SQLFreeEnv Releases the environment handle. 40

45 Programming Considerations For information on using the ODBC API functions from other programming languages, see th e Microsoft ODBC Software Development Kit and Programmer's Reference. M Programming Overview_M_Programming KB_SQL API Function Reference The following pages describe each KB_ SQL API function in alphabetic order. Each function is defined as an M programming language function. Descriptions may include some or all of the following items: Arguments Returns Syntax Examples Notes Options Result set Related functions Add SQL access to your M routines. KB_SQL provides SQL access to M data. You can choose to leverage this power for reporting, data browsing, updating, or any combination. With the KB_SQL API functions, you can encapsulate your SQL references in your M programs. This combination allows you to leverage your M programming skills with a well-defined, controlled interface to the data using SQL. A Word about Variable Names. Variable names shown in the following functions are used for illustrative purposes only. KB_SQL reserves the letters SQL for use as the first three letters of our variable names. We suggest you use variable name conventions suitable to your operation. KBSStatement Inserts part of an SQL command into the SQL input buffer. Arguments Statement handle [SQLHSTMT] SQL command [SQLTEXT] Returns Return code [SQLCODE] Syntax SQLCODE=$$KS^SQLOS(SQLHSTMT,SQLTEXT) Example 41

46 KBSODBCDriver S SQLCODE=$$KS^SQLOS(SQLHSTMT, SQLTEXT) I SQLCODE'=0 D Error G:SQLCODE<0 Discon Notes This function can be used to insert partial SQL commands to the SQL server. Its purpose is to support SQLPrepare. Splits should occur on a space or punctuation character. A special subroutine, SPLIT^SQLK4, may be invoked to automate this process For example, suppose X contains a long line (375 characters), thus exceeding the default limitation of 255 bytes M imposes on strings. X SELECT COL1, COL2, COL3, COL4, COL5, COL6, COL7, COL8, COL9, COL10, COL11, COL12, COL13, COL14, COL15, COL16, COL17, COL18, COL19, COL20, COL21, COL22, COL23, COL24, COL25, COL26, COL27, COL28, COL29, COL30, COL31, COL32, COL33, COL34, COL35, COL36, COL37, COL38, COL39, COL40 FROM TABLE WHERE COL1 = 100 AND (COL2 = 200) ORDER BY COL3 You can invoke the SPLIT^SQLK4 subroutine to decompose the line into smaller segments. It attempts to split first on a space boundary, followed by one of several punctuation characters. >D SPLIT^SQLK4 X( 0) 7 X(1) SELECT COL1, COL2, COL3, COL4, COL5, COL6, COL7, X(2) COL8, COL9, COL10, COL11, COL12, COL13, COL14, X(3) COL15, COL16, COL17, COL18, COL19, COL20, COL21, X(4) COL22, COL23, COL24, COL25, COL26, COL27, COL28, X(5) COL29, COL30, COL31, COL32, COL33, COL34, COL35, X(6) COL36, COL37, COL38, COL39, COL40 FROM TABLE WHERE X(7) COL1 = 100 AND (COL2 = 200) ORDER BY COL3 Now, you simply call KBSStatement for each entry in X(n). Wh en using this function, you must still invoke the SQLPrepare function. Typically, this invocation occurs in the last segment of the SQL command text. For example, assume X is very long. Below you see a sequence of typical statements from the subroutine s point of entry through the call to SQLPrepare. >D SPLIT^SQLK4 >S N=X(0) Note: X(0) contains the count of elements. >F I=1:1:N-1 DO >. SQLCODE=$$ KS^SQLOS(SQLHSTMT,X(I)) I SQLCODE'=0 G Error >S SQLCODE=$$ P^SQLOS(SQLHSTMT,X(N)) Note: If you perform your own split logic, make sure you adhere to all of the rules observed by the SPLIT^SQLKI subroutine. SQLAllocConnect 42