KB_SQL Database Administrator s Guide Version 4

Transcription

1 KB_SQL Database Administrator s Guide Version 4

2 1995, 1999 by KB Systems, Inc. All rights reserved. KB Systems, Inc., Herndon, Virginia, USA. Printed in the United States of America. No part of this manual may be reproduced in any form or by any means (including electronic storage and retrieval or translation into a foreign language) without prior agreement and written consent from KB Systems, Inc., as governed by United States and international copyright laws. The information contained in this document is subject to change without notice. KB Systems, Inc., does not warrant that this document is free of errors. If you find any problems in the documentation, please report them to us in writing. KB Systems, Inc. 585 Grove Street, Suite 201 Herndon, Virginia Voice (703) FAX (703) kbsys@kbsystems.com WWW KB_SQL is a registered trademarks of KB Systems, Inc. MUMPS is a registered trademark of the Massachusetts General Hospital. All other trademarks or registered trademarks are properties of their respective companies.

3 Table of Contents Preface vii Purpose vii Audience vii Conventions Used in this Manual viii The Organization of this Manual x Additional Documentation xii Chapter 1: An Overview of the KB_SQL User Groups and Menus The Database Administrator The System Manager The User Chapter 2: Essential Globals and Routines The Essential Globals The Essential Routines The Demonstration Globals Chapter 3: Configuring KB_SQL for Your Site BASE ROUTINE EDIT Option EXPORT METHOD EDIT Option FUNCTION EDIT Option IMPORT METHOD EDIT Option PSEUDO COLUMN EDIT Option KB_SQL Database Administrator s Guide iii

4 SITE EDIT Option START DATE EDIT Option REPORTS Option Chapter 4: Managing Devices..... DEVICE TYPE EDIT Option..... LOGICAL DEVICE EDIT Option..... REPORTS Option..... Supplying Input Translation Routines..... Printing Strategies Chapter 5: Applying Security Measures..... Security for Users..... Security for User Groups..... Security Levels..... Views and Security..... Using the Default Security..... Customizing Security..... Eliminating Security..... Integrating Security Systems..... GROUP EDIT Option..... USER EDIT Option..... PUBLIC PRIVILEGES Option..... REPORTS Option Chapter 6: Utilities..... COMPILE ALL QUERIES Option iv KB_SQL Database Administrator s Guide

5 EXPORT Option..... HALT QUERY Option..... IMPORT Option..... JOB WATCH Option..... LOCK STATUS Option..... Calculating Table Statistics..... STATISTICS Option..... REPORTS Option..... TRANSACTION LOGS Option Chapter 7: System Status Chapter 8: KB_SQL s Version Information Chapter 9: Transferring Data Dictionary Objects..... Transfer Objects and Methods..... Transfer Combinations..... The Transfer Utility Chapter 10: External Interfaces..... Running Compiled Query Routines..... Using RUN^SQL..... Using RUNQ^SQL..... Using Your Own Device Selection and Device Control..... Compiling SQL Statements into Routines..... Saving SQL Statements as a Query..... Compiling a Set of Query Definitions..... KB_SQL Database Administrator s Guide v

6 Deleting a Query Definition..... Compiling a Set of Query Definitions..... Compiling Statistics for a Set of Tables Chapter 11: Miscellaneous Interfaces..... The SQL Routine..... The SQL0H Routine..... The SQL0CHK Routine..... The SQL0DT Routine..... The SQL0FC Routine..... The SQL0GI Routine..... The SQL0RI Routine..... The SQL0TM Routine..... The SQL0TS Routine Appendix A: Integrity Check..... Appendix B: The Handling of Null Values..... A-1 B-1 Index I-1 vi KB_SQL Database Administrator s Guide

7 Preface Purpose The KB_SQL Database Administrator s Guide contains information about maintenance procedures for KB_SQL. This document is designed to help the database administrator (DBA) use the KB_SQL procedures effectively to ensure good performance and consistent operation of the system. Audience The manual is written for the database administrator of the KB_SQL system. The material is directed to those persons responsible for the smooth ongoing operation of the system. Experienced users and programmers will find this information helpful in the basic implementation of the system and for integrating the system with existing applications. We expect you to be familiar with M, the relational database model, and SQL. For those who want to increase their understanding of these topics, we have provided a list of publications in the Additional Documentation section of this preface. We also suggest that you review Lesson 1: The Basics in the KB_SQL SQL Reference Guide to become familiar with the functions of the interface. KB_SQL Database Administrator s Guide vii

8 Conventions Used in this Manual To help you locate and identify material easily, KB Systems uses the following style conventions throughout this manual. [key] Key names appear enclosed in square brackets. Example: To save the information you entered, type Y and press [enter]. {compile-time variables} References to compile-time replacement variables are enclosed in curly braces. The names are case sensitive. Example: {BASE} italics Italics are used to reference prompt names (entry fields) and terms that may be new to you. All notes are placed in italics. Example: The primary key of the table is defined as the set of columns that is required to retrieve a single row from the table. Windows The manual includes many illustrations of windows. Window names are highlighted by a double underline. viii KB_SQL Database Administrator s Guide

9 Prompt: data type (length) [key] The manual includes information about all of the system prompts. Each prompt will include the data type, length, and any special keys allowed. If the prompt is followed by a colon (Prompt:), you may enter a value for the prompt. If a prompt is followed by an equal sign (Prompt= ), it is for display purposes only. If the prompt is followed by a question mark (Prompt?), you can enter a value of YES or NO. ^GLOBAL All M global names will be prefixed by the '^' character. Tag^Routine All M routine references will appear as tag^routine. Menu Option/Menu Option/Menu Option A string of options shows you the sequence in which you must select the options in order to arrive at a certain function. Each menu s option is separated by a slash (/). Example: DATA DICTIONARY/REPORTS/SCHEMA PRINT KB_SQL Database Administrator s Guide ix

10 The Organization of this Manual Chapter 1: An Overview of the KB_SQL User Groups and Menus describes each user group and the menu options to which they have access. KB_SQL is delivered with three user groups. Chapter 2: Essential Globals and Routines describes the globals and routines that are essential to the operation of KB_SQL. It also lists the demonstration globals used for the KB_SQL tutorials. Chapter 3: Configuring KB_SQL for Your Site walks you through the procedures that KB_SQL provides for site configuration. Chapter 4: Managing Devices describes the process of defining your site s logical and physical devices. Instructions for developing your own input translation routines and guidelines for using different types of printers and printing arrangements are also provided. Chapter 5: Applying Security Measures discusses the security levels that you can apply. Chapter 6: Utilities describes several utility procedures for maintaining the system. Chapter 7: System Status explains the system status window and options. Chapter 8: KB SQL s Version Information shows you how to view site-specific information. Chapter 9: Transferring Data Dictionary Objects offers guidelines and examples for interfacing KB_SQL to your existing set of application software. It includes a description of the transfer utility that can be used to distribute information between multiple KB_SQL systems. x KB_SQL Database Administrator s Guide

11 Chapter 10: External Interfaces shows how to compile and run queries outside of the standard KB_SQL interface. Chapter 11: Miscellaneous Interfaces provides information on some of the internal functions used by KB_SQL. Appendix A: Integrity Check explains the Integrity Check procedure which you can use to evaluate the integrity of the KB_SQL tables. Appendix B: The Handling of Null Values describes how KB_SQL handles null values. Error Messages ********** Earlier versions of this manual listed error messages in a separate appendix. Error messages are now available by running the SQL_ERROR_LIST query. KB_SQL Database Administrator s Guide xi

12 Additional Documentation This DBA guide is the primary reference document for the database administrator. The following publications are recommended to all users of KB_SQL. Database: A Primer, C.J. Date, Addison-Wesley Publishing Company, An Introduction to Database Systems, C.J. Date, Addison-Wesley Publishing Company, Volume I - 3rd edition, 1981, and Volume II - 1st edition, A Visual Introduction to SQL, J. Harvey Trimble, Jr. and David Chappell, John Wiley & Sons, Inc., Lan Times Guide to SQL, James R. Groff and Paul N. Weinberg, Osborne McGraw-Hill, Additional materials are available from KB Systems, Inc. which provide a user s perspective of the system. KB_SQL EZQ Reference Guide KB_SQL SQL Reference Guide KB_SQL Syntax Guide KB_SQL SQL Pocket Guide These documents provide self-paced tutorials as well as detailed reference information for your users. xii KB_SQL Database Administrator s Guide

13 1 An Overview of the KB_SQL User Groups and Menus KB_SQL is shipped with three default user groups: DBAS, SYS_MGRS, and USERS. This chapter discusses the menu options, passwords, and responsibilities of each group. To create your own user groups and users, refer to Chapter 5: Applying Security Measures. At the end of this chapter, we discuss issues that you need to address to help your users obtain the most benefit from the SQL Editor and EZQ Editor tutorials. User Group DBAS SYS_MGRS USERS Description The database administrator has a comprehensive understanding of the Information System, the data dictionary, and the user requirements. The system manager has a detailed understanding of the daily operations of the Information System. The user has a specialized understanding of a particular information area within the Information System. 2 KB_SQL Database Administrator s Guide

14 The Database Administrator (DBA) The database administrator (DBA) and system manager (SysMgr) are responsible for the KB_SQL system maintenance. The DBA may be a single person or a team of people, each with different skills and expertise. The DBA is responsible for mapping existing M globals into the data dictionary, defining terminals and printers, and establishing security to ensure that users have access to the information that they need. In addition to these basic functions, the DBA is responsible for customizing the system to meet the special needs of the users. The DBA usually has a good understanding of the client s business. This understanding includes knowing the objectives of the client software applications and knowing the internal database design that supports the client applications. Because of this level of expertise, the DBA is granted the DBA privileges for the system. All individuals with the DBA privileges have unrestricted access to all functions provided by the system. They can access all tables and queries in the system. We recommend that every installation identify a DBA to serve as the liaison between KB Systems, Inc. and the system users. The DBA is the primary source of information about the users needs and expectations. By communicating directly with the technical support staff of KB Systems, the DBA can provide users with the best services. Chapter 1: An Overview of the KB_SQL User Groups and Menus 3

15 SHARK: The DBA Password To sign onto the system with full DBA privileges use the SHARK password. Use SHARK to sign on, then create a secret password for yourself and delete the SHARK password. The DBA Menu Select DBA OPTIONS The SQL EDITOR option gives you access to the SQL Editor. Refer to the KB_SQL SQL Reference Guide and the KB_SQL Syntax Guide. The EZQ EDITOR option gives you access to the EZQ Editor. Refer to the KB_SQL EZQ Reference Guide. CONFIGURATION Option 4 KB_SQL Database Administrator s Guide

16 CONFIGURATION has its own menu of options. These options let you customize the implementation of KB_SQL. Select CONFIGURATION BASE ROUTINE EDIT allows you to specify the naming conventions for generated query routines. EXPORT METHOD EDIT allows you to customize standard methods for downloading data from SQL tables. FUNCTION EDIT allows you to create user functions that can be used within KB_SQL. IMPORT METHOD EDIT allows you to customize standard methods for uploading data into SQL tables. PSEUDO COLUMN EDIT allows you to give names to system constants that might be used in queries. SITE EDIT allows you to maintain a profile of a particular installation of KB_SQL. START DATE EDIT allows you to create custom start date and time values for the background queue manager. Chapter 1: An Overview of the KB_SQL User Groups and Menus 5

17 REPORTS corresponds to the reports that you may generate for each of the CONFIGURATION options. DATA DICTIONARY Option DATA DICTIONARY has its own menu of options. These options, which are discussed in the KB_SQL Data Dictionary Guide, allow you to create a relational view of an existing set of M application globals. Select DATA DICTIONARY The MAP EXISTING GLOBALS procedure defines tables, primary keys, foreign keys, and indexes. The DOMAIN EDIT procedure allows you to describe various data storage strategies to KB_SQL. KEY FORMAT EDIT is used to describe primary key formats when key values are stored differently from non-key values (e.g., a descending date). OUTPUT FORMAT EDIT is used to describe various display formats. The SCHEMA EDIT procedure allows for a logical grouping of tables, either by function, by user, or by application. 6 KB_SQL Database Administrator s Guide

18 REPORTS corresponds to the reports that you may generate for each of the DATA DICTIONARY options. TERMINALS/PRINTERS Option TERMINALS / PRINTERS has its own menu of options. These options allow you to control the many different types of input and output devices. Select TERMINALS/PRINTERS DEVICE TYPE EDIT allows you to define device characteristics. LOGICAL DEVICE EDIT allows you to assign a logical device. REPORTS corresponds to the reports that you may generate for each of the TERMINALS / PRINTERS options. Chapter 1: An Overview of the KB_SQL User Groups and Menus 7

19 SECURITY Option SECURITY has its own menu of options. These options allow you to control access to KB_SQL procedures, tables, and queries. Select SECURITY GROUP EDIT allows you to assign collective privileges to users who have similar information requirements. USER EDIT allows you to define an individual user of KB_SQL. PUBLIC PRIVILEGES allows you to maintain privileges on tables and queries that are available to all users. REPORTS corresponds to the reports that you may generate for each of the SECURITY options. 8 KB_SQL Database Administrator s Guide

20 UTILITIES Option UTILITIES has its own menu of options. These options include various procedures that you might use in the regular maintenance of KB_SQL. Select UTILITIES COMPILE ALL QUERIES is useful when you need to compile a large number of queries. EXPORT and IMPORT allow the transfer of various objects such as tables, queries, functions, pseudo columns, and device types between different KB_SQL systems. HALT QUERY stops queries running in the background. JOB WATCH shows who is using KB_SQL and what they are doing. LOCK STATUS lets you set or reset system-wide locks. This is in place of using the SYSLOCK^SQL routine. Chapter 1: An Overview of the KB_SQL User Groups and Menus 9

21 STATISTICS creates volume and distribution statistics for the tables in the data dictionary. REPORTS and TRANSACTION LOGS correspond to the reports and logs that you may generate for each of the UTILITIES options. SYSTEM STATUS Option SYSTEM STATUS displays a summary of the current status of your system. 10 KB_SQL Database Administrator s Guide

22 VERSION INFORMATION Option VERSION INFORMATION displays information about the customer and the KB_SQL product. KB_SQL Version Information Chapter 1: An Overview of the KB_SQL User Groups and Menus 11

23 The DBA s Responsibilities to the End User The DBA plays a very important role in the introduction of the EZQ and SQL Editors in a user environment. The DBA must manage the expectations of the users against the capabilities of the application. A clear understanding of these expectations will help avoid frustrating the users and overwhelming the DBA with support requests the reasons for implementing the report writer in the first place. First, it is important to expect that the end users will need some training on the database of their organization. Translation of what they know about the data into the relational database world can take some time. The users will become more capable as they understand more about schemas, tables, columns and other database concepts. It is important to start out slowly, with simple data requests. The DBA should meet with the users to determine their information processing needs and to evaluate their experience levels. This preparation will produce simple, useful views that the users can work with to satisfy their basic information analysis requirements. By using views, the DBA can shield the user from some difficult concepts such as joins, foreign keys, and subqueries. A view looks like a simple table that includes all the data that they need. 12 KB_SQL Database Administrator s Guide

24 Tutorial Issues The tutorials in the KB_SQL EZQ Reference Guide and the KB_SQL SQL Reference Guide can be valuable tools in the user certification process. We recommend that all users work through the appropriate tutorial. Using simple tables and report requests, the tutorials illustrate the fundamentals of each editor. For optimal performance, the following checklist should be reviewed before requesting users to complete the tutorials. 1. Check security issues. { Assign user codes as needed. { Ensure that the users have select access to the Employees, Projects, and Tasks tables. { Ensure that no extra columns are available in any of the tables. { Suggest a naming convention for the tutorial examples (e.g., prefix query names with their initials). 2. Check the following site edit parameters. { Set SHOW_COST, SHOW_PLAN, SHOW_STATS and AUTO_SELECT to NO { Set Include NULL values in order by/group = YES 3. Make it interesting. { Set up a follow-up session using data that is more meaningful to the user group. 4. Allow sufficient time. { Some people will need 3-4 hours to complete a tutorial. { Schedule time to use a quiet work area, away from telephones and other distractions. Chapter 1: An Overview of the KB_SQL User Groups and Menus 13

25 The User Profile Checklist Above all, it is important for the DBA to know the characteristics of the users that will be using the EZQ and SQL Editors. The following checklist will help you begin to organize your users and determine their training needs. What types of users do you have? { decision makers { department heads { directors { analysts { clerks How would you expect those users to interact with the system? { fully formatted reports { tables of data for analysis { combination How often would the system be accessed? { several times a day { several times a week { several times a month How much training will be necessary? { KB_SQL training { EZQ training { Database training Will the M data be used by other application products? { Spread sheets: Lotus 1-2-3, EXCEL { Databases: RBASE, DBASE, PARADOX 14 KB_SQL Database Administrator s Guide

26 The System Manager (SysMgr) The system manager, or SysMgr, plays a very important role. Unlike the DBA who has a comprehensive understanding of the corporate computing environment, the system manager may have very specialized knowledge. The system manager is often the person or persons who manage the daily operation of KB_SQL as one of many applications running at a customer site. The SysMgr is presented with a limited view of the KB_SQL system. Like the DBA, the SysMgr has privileges on all tables, views, and queries. Unlike the DBA, the SysMgr cannot modify table definitions or M code. You will notice that the SysMgr menu does not include menu options for several procedures that are to be used by the DBA only. KB_SQL comes with a SYS_MGRS user group complete with a SysMgr user. Users in this group can access all tables, views, and queries but not all menu options. In addition, the SysMgr can be restricted from parts of procedures that allow the entry or modification of M code. Note: Any user can be a programmer. Only programmers can access certain input fields in which they can enter/modify M code. To designate a user as a programmer, use the SECURITY/USER EDIT procedure. MGR: The SysMgr Password To sign onto the system with system manager privileges use the MGR password. Use MGR to sign on, then create a secret password to be used by the system manager and delete the MGR password. Chapter 1: An Overview of the KB_SQL User Groups and Menus 15

27 The System Manager Menu Even though the Select SYSTEM MANAGER OPTIONS menu displays the same menu options as the Select DBA OPTIONS menu, some of the menu options limit the system manager to only certain procedures. Select SYSTEM MANAGER OPTIONS The SQL EDITOR option gives you access to the SQL Editor. Refer to the KB_SQL SQL Reference Guide and the KB_SQL Syntax Guide. The EZQ EDITOR option gives you access to the EZQ Editor. Refer to the KB_SQL EZQ Reference Guide. 16 KB_SQL Database Administrator s Guide

28 CONFIGURATION Option The system manager is limited to the SITE EDIT procedure. DATA DICTIONARY Option The system manager can not change the data dictionary and has access only to the TABLE PRINT and VIEW PRINT report options. If the system manager selects VIEW PRINT, the Print View List window appears in which the system manager may enter a range of views to be printed. If the system manager selects TABLE PRINT, the Print Tables window appears. Schema name: character (30) The Schema name is optional. If entered, the table range is limited to those tables within this schema. Chapter 1: An Overview of the KB_SQL User Groups and Menus 17

29 From table name: character (30) The From table name designates the first table (alphabetically) that you want to include in this report. Thru table name: character (30) The Thru table name designates the last table (alphabetically) that you want to include in this report. Print globals? YES/NO If you want to print the M data structures from which the tables obtain their data, answer YES; otherwise, answer NO. Break at table? YES/NO If you want the report to start a new page when it encounters a new table, answer YES; otherwise, answer NO. TERMINALS / PRINTERS Option System managers can not define or modify device types. They do have access to the LOGICAL DEVICE EDIT procedure and can print reports of the device type definitions and the defined logical devices. 18 KB_SQL Database Administrator s Guide

30 SECURITY Option The SECURITY option provides the system manager with the same capabilities as the DBA s SECURITY option. UTILITIES Option The UTILITIES option provides the system manager with most of the same capabilities as the DBA s UTILITIES option. The system manager is not able to assign fuzzy sizes or fuzzy densities to tables. SYSTEM STATUS Option This option displays the same information as does the DBA s SYSTEM STATUS option. VERSION INFORMATION Option This option displays the same information as does the DBA s VERSION INFORMATION option. Chapter 1: An Overview of the KB_SQL User Groups and Menus 19

31 The User Unlike the DBA who is responsible for the comprehensive understanding of the environment and the SysMgr who is responsible for ensuring smooth daily operation, the user is concerned only with retrieving information from the database. Users may use the EZQ Editor to write reports on those tables that they have privileges to see. Some users may also use the SQL Editor for complete SQL capabilities and for additional customization of their reports. KB_SQL comes with a USERS user group complete with a user defined as USER, with a password of USER. The USERS user group comes defined with the privileges to access only the demonstration tables, views, and queries. You can also assign KB_SQL users an EZQ or RUN password depending on the privileges you want to extend to them. Password USER EZQ RUN Description Password for all SQL and EZQ users other than DBAs and system managers Password for users of the EZQ Editor only Password for users who only run queries; these users do not create or edit queries 20 KB_SQL Database Administrator s Guide

32 The USER Password Menu This user may select either the EZQ EDITOR or the SQL EDITOR option. This user can then insert, edit, delete, or run queries. The EZQ Password Menu This user is not given a selection window; instead the user is shown the Select Query window in the EZQ Editor. This user can insert, edit, delete, and run queries in EZQ. The RUN Password Menu This user can choose to run any of the queries to which he has access, regardless of how the query was developed (i.e., through the EZQ Editor or through the SQL Editor). Note: A query will not be available to the user unless the developer of the query compiles it. Chapter 1: An Overview of the KB_SQL User Groups and Menus 21

33 2 Essential Globals and Routines KB_SQL is delivered in M (MUMPS) and is designed to run on your existing hardware and software platforms. Your license is specific to the M type requested when you ordered the software the product cannot be moved using routine and global copy methods. All programs and globals delivered with KB_SQL start with the SQL prefix. This chapter lists the globals and routines essential to the operation of KB_SQL. This chapter is designed to act as a map so that technical support personnel can quickly identify routines and globals by their function. 22 KB_SQL Database Administrator s Guide

34 The Essential Globals The following globals are essential to the operation of KB_SQL. The ^SQL global will always exist. The temporary globals will be created and deleted as needed by the system. If you are running multiple copies of KB_SQL on a network, you can keep the ^SQL global on the server, with all other temporary globals on the client systems. Consult your system administration guide provided by your M vendor for more detailed information. P - Persistent globals Global Name ^SQL ^SQLCUR ^SQLEX ^SQLIC ^SQLIN ^SQLIX ^SQLJ ^SQLL and ^SQLCK ^SQLP ^SQLQ ^SQLRD ^SQLS ^SQLT ^SQLXQ Description The KB_SQL data dictionary P Temporary data for cursor-saved ESQL queries Temporary global used by the export utility Info from last Integrity Check P Temporary global used by text editor Temporary global used by the import utility Temporary global for transaction related data Globals used for locking only Temporary global used for parsing, planning, and building Global used for locking only Temporary data for queries processed through API Temporary global for M code build data Default location for user tables P Temporary global used by queries for sorting Chapter 2: Essential Globals and Routines 23

35 The Essential Routines Routine SQL SQL0* SQLA*,SQLB* SQLD* SQLF* SQLG* SQLI* SQLR* SQLU* SQLK*, SQLV* SQLW* SQLX* SQLOS SQLOC Description The sign on routine Implementation-specific routines Reserved for customer use SQL standard device drivers SQL data dictionary filers SQL compiler SQL data dictionary integrity check routines SQL reports SQL procedures SQL internal subroutines SQL windows SQL default base routine prefix External interface to Server API External interface to Client API Any modifications that you make to these routines (except the SQLA and SQLB routines) can be overwritten by an update of the system. Therefore, if you must change one of these routines, use a client-specific naming convention so that your changes will not be lost. 24 KB_SQL Database Administrator s Guide

36 The Demonstration Globals A set of demonstration data is included with the system. The SQL_TEST schema includes the EMPLOYEES, PROJECTS, TASKS, and CHARGES tables. The data for these tables is included in the globals listed below. The data for these globals can be restored from the DEMO.DAT file. The data dictionary information is found in the DEMO.DB file. A set of demonstration queries is in the DEMO.Q file. Global ^SQLCHG ^SQLEMP ^SQLEMPN ^SQLPROJ Description Charge data Employee data Employee name index Project and Task data This information is referenced by the KB_SQL tutorials, examples, and illustrations. The content is intentionally simple so as to promote easy understanding. Your database will be more complex. The demonstration tables, views, and queries can provide you with the fundamentals that you can then apply to your own situation. Chapter 2: Essential Globals and Routines 25

37 3 Configuring KB_SQL for Your Site We realize that each site is unique with different needs and requirements; therefore, we have designed KB_SQL so that you may customize it for your site. We provide you with the tools to add new features and modify the system to best satisfy your site s requirements and your users needs. Some modifications are as simple as changing a value from NO to YES. Other changes require some M code or perhaps an M routine. All of the changes are managed by the options available in the CONFIGURATION menu. When you make a change or add a new feature, the changes that you make are indistinguishable to the user from the built-in features provided with KB_SQL. Although it does not happen often, our changes to variable or program names may cause conflicts with your custom code. If this does happen, KB_SQL s update documentation will alert you. 26 KB_SQL Database Administrator s Guide

38 Note: All M code executes and device type executes in this chapter are for illustrative purposes only. Chapter 3: Configuring KB_SQL for Your Site 27

39 BASE ROUTINE EDIT Option Add KB_SQL uses base routines to assign names to the M routines that it generates to perform your queries. Typical base routine prefixes will be 1-4 alpha characters in length and allow between 9 and 999 base routines. The combination of prefix and maximum number can not exceed seven characters. Creating multiple base routines will allow different user groups to produce queries with different routine prefixes. Note: To control which routine suffixes are allocated, refer to the CONFIGURATION/SITE EDIT/CUSTOM LOGIC/GENERATE ROUTINE option. After you select the BASE ROUTINE EDIT option, the Select, Insert, Delete selection window will appear. You can press [insert] to add a base routine, or select the base routine you wish to edit. If you want to delete a base routine, highlight it and press [delete]. Adding a new base routine is as easy as deciding on a prefix and how many different routines to allow. You can use the generic SQLX prefix or a prefix specific to a site or group. Some research should be done to ensure that there are no routines in conflict with the new prefix. It is usually best to keep base routines distinct and uniform in length. For example, use two character prefixes such as AA, AB, AC, etc. 28 KB_SQL Database Administrator s Guide

40 Edit Editing the base routine prefix is not recommended. If M routines have been allocated for queries, you should make sure that no conflicts will result from the change. We also recommend that you do not decrement the maximum number of routines for a base routine. Delete You can delete a base routine as long as no user group or site is linked to it. You should be sure to clean up any M routines that may be defined with the obsolete prefix. Base Routine Information Routine prefix: character (4) The routine base can be 2-4 characters. Once defined, this base routine will be used to generate unique M routine names for queries. Maximum counter: integer (3) You can specify a maximum number of routines for this base. If the maximum is reached, and all routine names are in use, the system will not generate any more routines with this prefix. Note: The combined sizes of the routine prefix and the maximum counter should not be greater than seven characters. This allows for one extra character that KB_SQL may need to uniquely identify the routine for the query. Chapter 3: Configuring KB_SQL for Your Site 29

41 Current: integer (3) The current number of queries with this prefix. This is a display field only. Description: character (60) Provide a description for this base routine. Sample Configuration A typical configuration will have a base routine allocated for use by the entire site, with additional base routines for certain user groups. In the sample configuration below, the site has dedicated all routines starting with the characters AA for KB_SQL queries. User groups A and B each have their own prefixes, BA and BB respectively. User group C creates queries using the site prefix. The configuration allows for 999 different queries in the AA prefix, 99 different queries in the BA prefix and 99 queries in the BB prefix. Group_A Base_BA (99) Group_B Base_BB (99) Group_C Base_AA (999) Site 30 KB_SQL Database Administrator s Guide

42 Routine Name Assignment As queries are deleted, the query routine name is placed on a list of free routines. When a new query is created, the query will use a routine name from the free list before attempting to create a new one. If the maximum number of query routine names are currently in use, a message will be displayed. If this happens, you may decide to increase the maximum number of routines for the affected prefix. A routine name is assigned to each query the first time the query is compiled. Deleting these queries will add the unused routines to a list of free routines. The actual query name is composed of the base routine prefix and a numeric counter. The diagram on the next page illustrates how routines are allocated for the following sequence of events: 1. A user in GROUP_C creates QUERY_1 that requires 1 routine. 2. A user in GROUP_C creates QUERY_2 that requires 2 routines. 3. A user in GROUP_A creates QUERY_3 that requires 1 routine. 4. A user in GROUP_B creates QUERY_4 that requires 3 routines. Chapter 3: Configuring KB_SQL for Your Site 31

43 M routine name for query QUERY PGM BASE QUERY_1 1 AA QUERY_2 1 AA 2 AA QUERY_3 1 BA QUERY_4 1 BB 2 BB 3 BB COUNTER M ROUTINE(S) AA1 AA2 AA2A BA1 BB1 BB1A BB1B 32 KB_SQL Database Administrator s Guide

44 EXPORT METHOD EDIT Option KB_SQL provides you with a set of standard formats for transferring data. These standard formats may be all that you ever need in your environment. (Refer to the Format and Method entries in the KB_SQL Syntax Guide for more information on using these standard formats.) If you need a custom format, the EXPORT METHOD option lets you create your own. To designate a specific export method in a query, include the METHOD parameter before the SELECT statement. (You may also specify a custom method as your site s default. Refer to the SITE EDIT option.) Note: As an alternative to exporting data to be used in another application, you may want to consider using KB_SQL s ODBC feature which lets you use Windows applications directly to access your M data. The KB_SQL ODBC Driver Install Guide gives you instructions for making this possible. If you have not defined any export methods, the Add window will appear when you select the EXPORT METHOD EDIT option. Select YES to add an export method. Otherwise, if export methods do exist, the Select, Insert, Delete selection window will appear. You can press [insert] to add an export method, or select the export method you wish to edit. If you want to delete an export method, highlight it and press [delete]. Chapter 3: Configuring KB_SQL for Your Site 33

45 The example that follows shows you how to use the capture mode of a terminal emulator to create a data file on your PC with data from your host system. Export Method Name: character (30) [list] The export method name can be referenced in a SQL statement that directs output to a file using a custom format. Description: character (60) Provide a description for the export method. Prompt for file? YES/NO By default, the system will prompt for a filename to receive the data output from the query. Answer NO if you do not require a filename for your export method. Show rows inserted? YES/NO By default, the system will display a message indicating the number of rows output by the query. Answer NO if you wish to suppress this message. Must run in foreground? YES/NO If this prompt is set to YES, any query that uses the method will not be allowed to run in the background. 34 KB_SQL Database Administrator s Guide

46 In this example, after you supply information in the Export Method window, KB_SQL prompts you to enter logic to turn on capture mode, execute the transfer, and terminate capture mode. Note: The code in the following windows is sample code as it applies to our PROCOMM example. Pre Process Execute This example executes a page feed, turns off echo, hangs for one second, then transmits an escape sequence. The terminal emulator recognizes the escape sequence and responds by turning on capture mode. (This code is for illustrative purposes only.) Row Execute As the system formats each row for output, this execute simply writes the row variable (ROW) followed by a linefeed. (This code is for illustrative purposes only.) Chapter 3: Configuring KB_SQL for Your Site 35

47 End of File Check Execute This prompt can contain an M execute that checks if the end-of-file condition has been met. If this condition is met, the prompt sets SQLERR="End of File Reached". The end-of-file condition means the export has exceeded some finite limit (i.e. the space available on a floppy disk), and represents an error condition. In the example below, the export contains more than 99, 999 rows. Post Process Execute When all rows have been transferred, this execute terminates capture mode, hangs for one second, restores echo mode, writes a page feed, and sets the refresh window variable (SQLWIN). (This code is for illustrative purposes only.) 36 KB_SQL Database Administrator s Guide

48 FUNCTION EDIT Option Functions are used to extend the SQL syntax by allowing an M routine to be invoked from within a query expression. A function can be used as a column reference in any SQL statement. Functions can be very valuable for using your existing M routines that perform applicationspecific operations. For example, you may have an M subroutine in a financial application that calculates a price for a given item. Instead of duplicating the complex logic each time you need the calculation to be performed, you can define a function that calls the subroutine. Any query that wants to use the logic can then reference this function. When you select the FUNCTION EDIT option, the Function Name window appears. You may press [list] to display existing function names or enter the name of the function. If you enter a new function name, the Add window appears. Select YES to add the function. Otherwise, if you pressed [list] from the Function Name window, a selection window appears. You can press [insert] to add a function, or select the function you wish to edit. If you want to delete a function, highlight it and press [delete]. Chapter 3: Configuring KB_SQL for Your Site 37

49 Function Name Add Edit Delete You need to follow some simple steps to define and use a function. First, once a need is established, determine the number and type of input variables. Then determine the type and format of the return variable. After you specify these parameters, using this procedure, any query can reference the function. Be sure to determine the potential effect of any change to a function definition. If the function has been widely used, you may decide that a new function is required. If not yet implemented or if the definition is incorrect, simply change the definition and compile the affected queries. As in the case of editing a function definition, you must evaluate the potential effect of deleting the function. Any queries that use the function will require modification. Note: The following examples are for a user-defined function that gets the first transaction record for a given date. 38 KB_SQL Database Administrator s Guide

50 Function Information Name: character (30) Each function must have a name to identify it within the SQL syntax. The name must be a valid SQL_IDENTIFIER. Note: An SQL_IDENTIFIER is a name, starting with a letter (A-Z), followed by letters, numbers (0-9), or underscores '_'. The last character in the name cannot be an underscore. The length of the name must not exceed 30 characters. Description: character (60) Provide a description for the function. Syntax: character (65) Provide the syntax for the function. Parse check routine: character (20) This routine checks if the correct number of arguments have been included in the function reference. If possible, use the standard entry points in the SQL0FC routine. See Chapter 11 for details. Chapter 3: Configuring KB_SQL for Your Site 39

51 Result domain: character (30) [list] The result domain determines how the result value is to be formatted for display. For example, our TX_FIRST function returns a value that qualifies as an integer value, with a maximum length of ten characters. Many functions will return a result in either INTEGER or CHARACTER format. Length: integer (3) Enter the maximum length for the result value. Note that this prompt is asked only for domains with variable length. It will not be asked for the DATE, TIME, or FLAG domains. Scale: integer (1) For numeric data types, you must also enter the number of integers to the right of the decimal point. Inline function: YES/NO Any user-defined function can be specified as in-line. By default, a function is implemented as a call to an external M routine. If in-line is indicated, the code for the function will be placed in the generated query routine. In many cases, this can have a positive effect on performance. Example #1, #2, #3: character (60) You can provide up to three examples of how to use the function. If you indicate that this function be specified as in-line, the Compile-time M Code window will appear for you to enter the code for this function. In the example below, note the use of the curly braces around the VALUE terms. When specifying an in-line function, these braces specify variables that will be replaced with their contents at query build time. For functions that are not in-line, the VALUE terms are still used, but without curly braces. Their contents are evaluated at runtime. 40 KB_SQL Database Administrator s Guide

52 Compile-time M Code Runtime Routine Runtime routine: character (20) The runtime routine is used to calculate the result of the function using the value array. Use routine names that do not conflict with the KB_SQL routine names or your generated query routines. This prompt will display if you enter NO at the Inline function prompt. Chapter 3: Configuring KB_SQL for Your Site 41

53 The purpose of the runtime routine is to return the desired value based on the values of the specified arguments. The query will set up each argument value in a subscripted variable VALUE, with the variable VALUE equal to the number of arguments. Your runtime routine should also return the result value in the variable VALUE. For example, a function which allows two arguments might call your runtime routine with the following data: P VALUE = 2 P VALUE(1) = 1st argument P VALUE(2) = 2nd argument Your runtime routine will perform any necessary calculations, then return the function result in the same VALUE variable. For example, consider the following simple function for age calculation. P Name= AGE P Parse Routine= A2^SQL0FC P Run Routine= AGE^SQLAFUN P Result Domain= integer (3) The run routine AGE^SQLAFUN might look like this: SQLAFUN AGE ; Site functions ; S VALUE=VALUE(2)-VALUE(1)\ Q 42 KB_SQL Database Administrator s Guide

54 How to Use a Function To create a new function you must provide the function name, an optional parse check routine, a runtime routine, and a result domain. The function name must be a valid SQL_IDENTIFIER. The parse routine is the name of an M routine that checks the validity of the input values. The runtime routine is an M routine that computes the value of the result. The result domain is a domain that corresponds to the result value. A site-defined function can be used anywhere a KB_SQL function can be used. For example, consider how you might use a function for AGE calculation. Function: AGE(Date_of_birth,comparison_date) SELECT name, sex, AGE(birth_date,today) FROM patients WHERE AGE(birth_date,today) BETWEEN 18 and 65 Chapter 3: Configuring KB_SQL for Your Site 43

55 Parse Check Routine The purpose of the parse check routine is to determine if the function reference is valid (e.g., the correct number of arguments is specified). The parser will decompose the function into a set of internal structures. Although it is possible for the parse check routine to determine the composition of each expression, the parse check routine is most useful because it can determine if the correct number of arguments was specified. The M routine SQL0FC is available for your use. It contains the following subroutines that will check for a required number of arguments and return an error message if not correct. 44 KB_SQL Database Administrator s Guide

56 SQL0FC - Function parse check routine Tag Description A1 A12 A13 A2 A23 A3 A34 A4 I2 1 argument required 1-2 arguments 1-3 arguments 2 arguments required 2-3 arguments 3 arguments required 3-4 arguments 4 arguments required 2 integer arguments required TEST(A) TEST(A) or TEST(A,B) TEST(A) or TEST(A,B) or TEST(A,B,C) TEST(A,B) TEST(A,B) or TEST(A,B,C) TEST(A,B,C) TEST(A,B,C) or TEST(A,B,C,D) TEST(A,B,C,D) Example TEST(N,M) where N, M are both integers Chapter 3: Configuring KB_SQL for Your Site 45

57 IMPORT METHOD EDIT Option KB_SQL allows you to populate tables using the INSERT command. This command can be used to read data using a particular import format. KB_SQL provides you with a set of standard formats for importing data. (Information on using these standard formats is provided in the KB_SQL Syntax Guide.) However, you may need to import data that is not in one of these standard formats, or you may want to import data from another source other than a host file. For these instances you can create your own custom import method using the IMPORT METHOD EDIT option. If you have not defined any import methods, the Add window will appear. Select YES to add an import method. Otherwise, if import methods do exist, the Select, Insert, Delete selection window will appear. You can press [insert] to add an import method, or select the import method you wish to edit. If you want to delete an import method, highlight it and press [delete]. The following example shows how to use an M global as a data source. 46 KB_SQL Database Administrator s Guide

58 Import Method Name: character (30) [list] The import method name can be referenced in a SQL statement that inserts rows from a file using a custom format. Description: character (60) Provide a description for the import method. Prompt for file? YES/NO By default, the system will ask for a filename to retrieve the data. Answer NO if your import method does not require a filename. Show rows inserted? YES/NO By default, the system will display the number of rows inserted into the table. Answer NO if you wish to suppress this message. Must run in foreground? YES/NO If this prompt is set to YES, any query that uses this method will not be allowed to run in the background. After you supply the values in this window, you will be prompted to enter logic to start the process, execute the transfer, and terminate the process. Note: The code in the following windows is sample code as it applies to our FROM_GLOBAL example. Chapter 3: Configuring KB_SQL for Your Site 47

59 Pre Process Execute This execute initializes a row counter variable (SQLACTR) and determines the maximum number of rows (SQLAMAX) that are defined in the global. Notice that the variable SQLFILE is used as a subscript in the transfer global. (This code is for illustrative purposes only.) Row Execute The row execute will increment the counter variable and return the row variable. (This code is for illustrative purposes only.) Note: When importing from a text file, it is possible to have a null row in the middle of a file (not necessarily at the end). The INSERT query will continue to process after receiving a ROW=null, and will stop only when it receives a SQLERR=437 (end-of-file error). The Row Execute logic must set the SQLERR=437 when the end-of-file occurs. 48 KB_SQL Database Administrator s Guide

60 End of File Check Execute This prompt can contain an M execute that checks if the end-of-file condition has been met. If the condition is met, the prompt will set SQLERR="End of File Reached". The end-of-file condition means all of the rows have been processed and the statement has successfully completed. The sample check below is automatically setup for all existing import methods and is backwards compatible. Post Process Execute This execute sets a date and time stamp in the transfer global. (This code is for illustrative purposes only.) Chapter 3: Configuring KB_SQL for Your Site 49