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) [email protected] 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

61 PSEUDO COLUMN EDIT Option A pseudo column is an M expression that has an associated SQL key word and domain. We refer to them as pseudo columns because they are either a constant or a single column belonging to a global which isn t mapped as a table. The global isn t mapped as a table because it contains only one record. Pseudo columns are used so that queries can reference information that does not depend on a particular row (e.g., system constants such as today s date). This allows the expression to be referenced by the key word in SQL commands. The expression may be any valid M expression. The key word must be a valid SQL_IDENTIFIER and must be distinct from all other key words. The domain indicates the format of the value returned by evaluating the expression. KB Systems provides you with several pseudo columns so you can obtain system constants such as the job ID, the user group name, today s date. To view these default pseudo columns, press [list] from the text area in the SQL text window and select PSEUDO COLUMN. The pseudo column report (CONFIGURATION/ REPORTS/ PSEUDO COLUMN PRINT) produces a list of the pseudo columns that you have defined. 50 KB_SQL Database Administrator s Guide

62 Add If you are trying to do something in KB_SQL that you know can be done easily in M, try using a pseudo column. The pseudo column is a symbol representing some M expression, key word, or function. After you define a pseudo column, it can be referenced anywhere a column name can be used. To create a new pseudo column, enter the name in the Pseudo Column Name window. The Add window will appear after you press [enter]. Select YES to add the pseudo column. Or, you may press [list] from the Pseudo Column Name window to display existing function names in the selection window, and then press [insert] to add a new function. Pseudo Column Name Edit Delete If you want to edit a pseudo column, enter the name in the Pseudo Column Name window and press [enter], or press [list] to view a list of all pseudo columns. Highlight the pseudo column that you want to edit and press [enter]. Consider the effect of changing the definition of the pseudo column. You should review all queries that use the pseudo column to determine if the code will be adversely affected. If you want to delete a pseudo column, highlight its name in the selection window and press [delete]. Any query that references the pseudo column will need to be modified. Chapter 3: Configuring KB_SQL for Your Site 51

63 Pseudo Column Information You can define a pseudo column for any commonly referenced M expression. Typical examples include the process number, current directory, and principal device identifier. One of the benefits of pseudo columns is that they enable separate sites to run the same query. In this example, the same query is being distributed to various states throughout the country. You must create a pseudo column which contains the state code for the current state. Each state receives a different global from which the value of the pseudo column is obtained. Name: character (30) Each pseudo column must have a name to identify it within the SQL syntax. The name must be a valid SQL_IDENTIFIER. Description: character (60) Provide a description for the pseudo column. Domain: character (30) [list] Enter a domain to determine how the result value of the pseudo column is to be stored. 52 KB_SQL Database Administrator s Guide

64 Length: integer (3) The maximum length for the result of the pseudo column. This prompt will be asked only for those domains with variable length. It will not be asked for values of 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. M Expression: character (30) The M expression is the M code that returns the pseudo column value. For our example, the ^WHO global contains customer profile information. The second piece of the ^WHO global is the state abbreviation. Chapter 3: Configuring KB_SQL for Your Site 53

65 SITE EDIT Option Use this procedure when you first install KB_SQL or after you install a new version of the product. Some of the changes made through this procedure will not be evident until you exit and restart the system. Some of the parameters are used when users first log on to KB_SQL. Other parameters help to enforce the standards and conventions of the organization. Site Name Site name: character (30) The site name appears in the top center of your screen. The site name can be referenced in queries using the SYS_NAME parameter. After you supply the site name, the Site Options menu will appear. 54 KB_SQL Database Administrator s Guide

66 Site Options ADDRESS INFO Option The pseudo columns for the system name and address are available for reference in user queries. The system name will appear on the top line of the display for all interactive procedures. Each line of the site address can be referenced as a pseudo column. These columns as well as the site name column, SYS_NAME, are often referenced in the header of user queries. Chapter 3: Configuring KB_SQL for Your Site 55

67 Site Address Information Address line 1: character (40) The first line of the site address (e.g., South Michigan Ave). Address line 2: character (40) The second line of the site address (e.g., Suite 500). Address line 3: character (40) The third line of the site address (e.g., Lansing, MI 48917). Address line 4: character (40) The fourth line of the site address (e.g., (512) ). Four lines are made available to accommodate lengthy addresses. Be sure to include the full street address, city, state, and postal code. The fourth line is sometimes used for the site phone number. 56 KB_SQL Database Administrator s Guide

68 DEFAULT INFO Option KB_SQL is designed to allow you to share data between multiple systems, including M and other applications. The default export and import functions use standard host file formats for the transfer of data. These facilities run on all implementations of M across all hardware configurations. If your M runs in a stand-alone environment, you can still take advantage of the export and import facilities. Simply define a default file format, an export method, and an import method that use globals instead of host files. Site Default Information Default file format: character (20) [list] This default file type for host operating system files is used if you do not specify a file type using the FORMAT parameter. Refer to Format and Parameters Within a Set Statement in the KB_SQL Syntax Guide for more information regarding the FORMAT parameter. Chapter 3: Configuring KB_SQL for Your Site 57

69 Delimiter: character (3) This value is used to delimit columns in the query result when you save the query results to a data file using the DELIMITED format. Enter this value as the ASCII value of the character desired. For example, to delimit using Control-A, specify 1 as the delimiter. This will place a $CHAR(1) between columns in the result set. Export method: character (30) [list] This export method is used instead of the default format for the file type being used in the SELECT command. Import method: character (30) [list] This import method is used instead of the default format for the file type being used in the INSERT command. Date output: character (20) [list] You can specify the default display format for date values. The list includes those output formats for the DATE data type that are supported by the KB_SQL date conversion utility. Refer to Chapter 11: Miscellaneous Interfaces for more details on the SQL0DT routine. Date input: character (3) [list] You can also specify the default input format for dates. KB_SQL supports the United States, European, and Canadian formats for date inputs. Be sure that your output and input formats are consistent. That is, if you select DMY as an input format, you should display dates with the day first, followed by the month and year. Otherwise, the date conversion utility will report errors in your date input values. Time output: character (20) [list] You can specify the default display format for times. The list includes those output formats for the TIME data type that are supported by the KB_SQL date conversion utility. Refer to Chapter 11: Miscellaneous Interfaces for more details on the SQL0TM routine. 58 KB_SQL Database Administrator s Guide

70 Moment separator: character (5) KB_SQL supports a MOMENT data type that is a time stamp, complete with date and time. The format of these values is determined by the output formats specified for dates and times. The date is separated from the time by the '@' character. You can specify another character string if you wish. For example, to have dates display as '03/30/61 at 10:30 AM', you would specify ' at ' as the moment separator. This has implications on how your moment input values will be processed. Refer to Chapter 11: Miscellaneous Interfaces for more details on the SQL0TS routine. Moment time first? YES/NO By default, KB_SQL displays the date portion first, followed by the separator, then the time portion. Answer YES to reverse this order. This has implications on how your moment input values will be processed. Refer to Chapter 11: Miscellaneous Interfaces for more details on the SQL0TS routine. Default for COMMIT prompt? YES/NO This determines the default value for the Commit? prompt. Enter NO to force the user to enter YES to save the changes. Show search/select statistics? YES/NO Answer YES to see the number of records searched and selected for each query run. Compare this value to the access plan cost estimate. Show data access plan? YES/NO Answer YES to see the data access plan prior to the building routines during query compiles. This provides pseudo code for the query process. Auto select if one match? YES/NO Answer YES if selection windows should pick a single matching entry without user confirmation. Answer NO if you wish to confirm all selections even if there is only one match. Chapter 3: Configuring KB_SQL for Your Site 59

71 Perform ROW commit? YES/NO Answer YES if you want to allow INSERT, UPDATE, and DELETE commands to skip rows that contain errors. Otherwise, answer NO. The ANSI SQL standard is to discard all changes and return an error message should an INSERT, UPDATE, or DELETE encounter an error. By answering YES to this prompt you ignore this standard at the site level, allowing the commands to reject any rows with errors and process the remaining rows. The site level setting may be overridden in the SQL Editor by setting SET ROW_COMMIT to either YES or NO. Show DBA status window at startup? YES/NO A YES answer will display the System Status window each time a DBA or MGR user logs on to the system. Answer NO if you do not wish to display this screen at startup. Default SearchPatternEscape character: character (3) This is a metacharacter used by ODBC SQL Catalog functions. It must be a printable character or an ASCII value. Password expire days: integer (3) Enter the default number of days after which passwords will expire. This number will be used to set the expiration date for user passwords at time of creation and on password renewal. Password warning days: integer (3) Enter the default number of days after which the user will be warned of an upcoming password expiration date. The default is 14 days. Note: 1.) Use of these password features is completely optional. If you do not want passwords to expire, do not enter anything in the field. 2.) The User Group Member List report shows the expiration date for users that have the value set. ANSI INFO Option 60 KB_SQL Database Administrator s Guide

72 Site ANSI Information Return null for expressions that contain null? YES/NO Answer YES if any expression that includes null should return a null result. Answer NO if null values should be treated using the M interpretation of null as the empty string. Include null values in group and order clauses? YES/NO The result of a query with an ORDER BY or GROUP BY clause is a table with the primary keys specified in the clause. If any key value is null, the associated row will not be included in the result. Answer YES if null values should be included. Sort nulls as ASCII value: integer (3) If null values are included in the ORDER BY or GROUP BY clauses, they will normally be grouped together at the top or bottom of the result. Use the value 127 (rub out) to have null entries last, 32 (space) to have null entries first. System delimiter ASCII value: integer (3) If your site has an integrated data dictionary, you may use a standard delimiter. If so, the global mapping process can be greatly accelerated. For example, if all of your globals use the tilde character (126) as the delimiter, enter 126 for the system delimiter. When mapping globals, all piece references can be entered as integer values to be interpreted as the n-th piece of the data. Chapter 3: Configuring KB_SQL for Your Site 61

73 Maximum length for SQL identifiers: integer (2) The ANSI standard for SQL states that the maximum length of the SQL identifier is 18 characters. KB_SQL will support an identifier of up to 30 characters in length. Consider readability versus efficiency of input. Maximum length for sort keys: character (60) This is largely dependent on your M implementation. If your M implementation has a significant limitation on the length of array subscripts, enter that length here. The truncation may cause some variations in result sorting. For example, if you sort by a long description field, the sort key value will be the first n-characters of the description. Default transaction isolation level: integer (1) Use this prompt to indicate which isolation level to use: 0 (zero) for READ UNCOMMITTED, 1 for READ COMMITTED, or 2 for REPEATABLE READ. These levels are explained in the KB_SQL Programmer s Reference Guide. This value can be overridden by the ISOLATION_LEVEL parameter. 62 KB_SQL Database Administrator s Guide

74 M INFO Option Site M Information Default global name: character (10) The M global prefix for all tables created via the CREATE TABLE command. This global name will be used for any table created for a schema where the global prefix is not defined. Default base routine: character (10) [list] The base routine that is used for the compiled query routines. This base routine will be used for queries compiled by members of any user group where the user group base routine is not defined. Host file end-of-row terminator: character (10) Enter a string of characters to indicate the end of each row of data output to host files. The default value will be the! string. Max routine size: integer (5) This is largely dependent on your M implementation. A safe estimate to use is 90% of the largest routine size allowed by your implementation of M. Consider portability issues versus optimum performance. Chapter 3: Configuring KB_SQL for Your Site 63

75 Max global data length: integer (10) Enter an integer value that represents the maximum number of characters that may be stored as a data value in a global. M Functions? YES/NO If compiled query routines can take advantage of the $FNumber, $Get, $Query, and $Name M functions, answer YES. If you answer NO, the compiled routines will simulate the function. M Commands? YES/NO Answer YES if your M implementation supports the Merge command and the Set $Extract(...)=value syntax. Otherwise, answer NO. Protected variable list: character (65) Enter a list of variable names separated by commas. These variables will be preserved in all kill and exclusive kill commands. We will not kill these variables on entry or exit of KB_SQL. However, we cannot ensure that these variables will not be used internally by KB_SQL. Therefore, we recommend that your list of variables be in the user-defined range of SQLA* variable names. Routine alter/save execute: character (65) Use this prompt to call a program. The program will affect the M code that KB_SQL generates from your queries. The program will be executed after KB_SQL resolves all soft tag references and other compile time variables. You will receive a local array to which you can add code and then save. If you take responsibility for saving the routine, you must kill the local array before returning to the caller. If you encounter an error, you should return the SQLERR variable. If you don t save the routine, KB_SQL will save it using the logic in SAVE^SQL0RI. You are responsible for the format of any lines that you insert in the local array. All routine lines are of the form: [tag]<space><mcode>. The routine array is in the format: RTN=Name of routine RTN(0)=Number of routine lines RTN(n)=Routine line #n 64 KB_SQL Database Administrator s Guide

76 DATE/TIME LIMITS Option Site Date/Time Limits Delete transaction logs after: days integer (2) Enter the number of days that the old transaction log data will be available for review. Typical values will be 7-28 days. As DBA, you should balance storage costs against the benefit for review. Log-off users after: seconds integer (5) Enter the number of seconds to wait for a user s response. Typical values will be seconds (10-20 minutes). If no key is pressed, the system will respond as if the user pressed the [undo] key. Timeout in SQL Editor after: seconds integer (5) Enter the number of seconds to wait before the SQL Editor times out. When the SQL Editor times out, it acts as if you pressed [undo]. Chapter 3: Configuring KB_SQL for Your Site 65

77 Perform halt check after: rows character (4) While a query is executing, interrupts are checked after processing of 1000 rows of data. You can increase this number to minimize checking, or decrease this number for more frequent checking. If you find that many queries need to be interrupted prior to completion, it is preferable to lower the halt check. Maximum number of keys: character (2) This applies to the number of primary keys that can be saved in a result set without causing M errors for exceeding the maximum allowed subscript size. If you encounter errors of this type, you can specify a threshold number of primary keys. If an excess of keys is discovered during the query plan time, the query build will use a safe algorithm to avoid the problem with exceeding the maximum allowed subscripts. Display warning if estimated cost exceeds: integer (10) Display error if estimated cost exceeds: integer (10) These two prompts are valuable for avoiding runaway queries. Sometimes a query may ask for things that just don t make sense, or that require an exhaustive search of the database. If you want, you can restrict the number of rows that can be searched. Two different thresholds can be set, one for a warning, and another that will produce an error message and abort the query build process. Lower query priority after: seconds integer (5) This prompt assumes that your implementation of M allows for job priority to be manipulated. If a query has been running longer than (n) seconds, the LOWER PRIORITY execute will be invoked. Typical values will be between 60 and 600 seconds. 66 KB_SQL Database Administrator s Guide

78 Change job to low priority execute: character (65) This prompt is enabled only if you have entered a value for the Lower query priority after prompt. Enter the executable M code that will lower the priority of an active process. This code will be executed for any query that runs longer than the value you set for the Lower query priority after prompt. Change job back to original priority execute: character (65) This prompt is enabled only if you have entered a value for the Lower query priority after prompt. Enter the executable M code that will return the status of a query to normal priority. This code will be executed for any query whose priority has been lowered, and has completed processing. Chapter 3: Configuring KB_SQL for Your Site 67

79 ACCESS PLAN INFO Option Plan Information The following parameters are supplied to allow you to customize the access planner to match the unique requirements of your site. The table and index density values will typically be set to 1, 2, or 3. A value of 2 or 3 implies that a single M block contains many rows of all table or index globals at your site. We recommend that you use the default values unless directed otherwise by KB Systems technical staff. Default table density: character (20) [list] Enter a value if you plan to use the density of tables as a factor in the query access planning function. Numeric input will be interpreted directly as the relative density, number of entries per physical block, of the table. String input will invoke a selection window of fuzzy density values. Default index density: character (20) [list] Enter a value if you plan to use the density of indices as a factor in the query access planning function. Numeric input will be interpreted directly as the relative density, number of entries per physical block, of the table. String input will invoke a selection window of fuzzy density values. Default average distinct: character (20) [list] 68 KB_SQL Database Administrator s Guide

80 If no statistics are entered for a table or index, this value will be used as the average number of distinct values. The value can be numeric or a predefined character string (fuzzy size) value. Predicate reduction factor: character (3) [list] Typically, all predicates other than equals will reduce the cost of searching a primary key by a factor of 2, or half. You may wish to bias this default to 3 (thirds), 4 (quarters) or some other meaningful fraction. Order by reduction factor: integer (3) This number is applied to the query planning cost for queries that can use index tables to satisfy an ORDER BY clause. The goal is to have the planner use an index table if it matches exactly to the ORDER BY specification. Enable quickview feature: YES/NO This prompt lets you turn the quickview feature on or off. If this feature is turned off, and you run a query with a view, the view definition must be expanded by the translator before the view columns can be referenced. For queries with large views (views with 50 or more columns), this can take a considerable amount of time. When you set this prompt to YES, this feature performs on-the-fly expansion of view columns when and if they are referenced. This can reduce the time necessary to translate queries that reference large views by 50% or more. There are some limitations to your query if you want to use the quickview feature: P The SELECT statement can reference only column names. P P The query cannot contain a GROUP BY clause, a HAVING clause, or functions. The view definition cannot contain table aliases or column aliases. Chapter 3: Configuring KB_SQL for Your Site 69

81 Fail prepares with Cartesian Products? YES/NO Answer YES if you want queries that contain Cartesian products to return an error message. Otherwise, answer NO. Fail prepares without table statistics? YES/NO Answer YES if you want queries that reference tables without distribution statistics to return an error message. Otherwise, answer NO. 70 KB_SQL Database Administrator s Guide

82 BACKGROUND TASKS Option Background Task Information This window provides a central point to control issues related to the background processing of queries. Run queries in background? YES/NO If YES, anytime you run a query to a printer, the job will be performed as a background task. How many queues: integer (2) This number specifies how many background task queues can be active at any time. This number corresponds to an M process, one for each queue. Allow multiple jobs per user? YES/NO If YES, a user will be able to run multiple queries simultaneously. Otherwise, all queries run by a user will be processed on a first-in-first-out basis. Chapter 3: Configuring KB_SQL for Your Site 71

83 Prompt for start date/time? YES/NO Answer YES if you want all query runs, whose output is not directed to the screen, to prompt for a start date and time. Otherwise, answer NO. Variables to be preserved: character (65) Specify any special variables that need to be passed to the background process. Note that query and site-specific variables are already included. You need to specify only the additional variables that will be needed by background jobs. Initial execute code: character (65) If desired, you can specify M code to be executed before processing each query. Terminal execute code: character (65) If desired, you can specify M code to be executed after processing each query. 72 KB_SQL Database Administrator s Guide

84 Queue manager override code: character (65) If desired, you can specify M code to be performed each time a query is executed in background mode. This code is executed while the job is still in the foreground, and overrides KB_SQL queue manager operation. This code should be used to invoke the site-specific queue manager, replacing the KB_SQL queue manager. The following variables may be referenced to setup the site-specific queue manager task: JOBD = Start date ($H format). The query should be run on the specified date. JOBQ = query name (30 characters). JOBR = reoccurring query flag. This is based on the $H M function. If SQLR is between 0 and 6, then the query should be run each time $H#7=SQLR. SQLR=0 means every Thursday. SQLR=4 means every Monday. If SQLR=7, then the query should be run every day. JOBT = Start time (in seconds). JOBV(variable) = "" This array lists the local variables that will be needed at query execution time. These variables and the corresponding values must be preserved by the site queue manager. JOBX = M execute. This code is usually of the format DO ^ROUTINE and should be executed by the queue manager to run the query. Note: If you use a site-specific queue manager, background tasks will not appear in the HALT QUERY option s Select Task window. Chapter 3: Configuring KB_SQL for Your Site 73

85 PAGE LAYOUT Option Page Layout Parameters Left margin: integer (1) Enter the number of blank characters to print at the left margin. (See diagram on next page.) The default is zero (0). When printing on 3-hole paper for binders, you may wish to use a left margin to avoid printing too close to the holes. Right margin: integer (3) Enter the maximum width of the data across the page. (See diagram on next page.) The default right margin is 80 characters from the left edge of the page. Wide reports (printed in landscape mode) will require a value greater than 80. Top margin: integer (1) Enter the number of blank lines printed at the top of each page. The default is zero (0). Bottom margin: integer (1) 74 KB_SQL Database Administrator s Guide

86 Enter the number of blank lines to print at the bottom of each page. The default is zero (0). This ensures that sufficient space remains at the perforation for continuous feed printers. Default spacing between columns: integer (2) Enter the default number of spaces to print between columns. The default is two (2). You may wish to add more spacing for some reports. Margins and spacing Top Left aaaa bbbb cccc dddd column space Right Bottom Show 'End of Report' message? YES/NO Answer YES to display a message at the end of each report. Display dash line in header? YES/NO Answer YES to print a line of dashes in the report header. Display page numbers in header? YES/NO Chapter 3: Configuring KB_SQL for Your Site 75

87 Answer YES to include the page number in the report header. Note that the page number will not be printed on the first page. Show 'Nothing to Print' message? YES/NO Answer YES to print the message 'Nothing to Print' on your report when there are no results to print. Custom header code execute? character (65) Each site can specify logic to replace the standard KB_SQL report header text. The M code can include the parameters {N} query name, {L} left margin, and {R} right margin. Any change to this logic will take effect on subsequent query compiles. The following sample code will print the query name centered on the page: W?{R}-{$L(N)},"{N}" 76 KB_SQL Database Administrator s Guide

88 SERVER INFO Option Our default communication method is the TCP/IP protocol. This is currently the only protocol you can use to connect to a server from a Windows workstation. If you want to use the KB_SQL engine to access your M data from ODBC-compliant Windows applications, you must also install the KB_SQL ODBC Driver in addition to configuring your TCP/IP protocol. For these installation instructions, refer to the KB_SQL ODBC Driver Install Guide. Server Information System name= Displays the name of the system. Edit list of available schemas? YES/NO To add a new schema or delete one that has been linked to the system, answer YES. Otherwise, answer NO. Note: Schemas will not be accessible if they are not linked. Chapter 3: Configuring KB_SQL for Your Site 77

89 Prefix for stored query routines: character (4) 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: integer (4) 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. 78 KB_SQL Database Administrator s Guide

90 You may clear the stored queries buffer of all routine names by invoking the RL^SQL tag. Allow connections? YES/NO 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 the background. If the server is not running when you set this value to YES, you still have to start the server. It is not automatically started. See the KB_SQL ODBC Driver Install Guide for instructions on how to start the server. Trace API calls? YES/NO 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? YES/NO 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: character (60) Enter the M code that will instantiate any variables that are required by your application during the runtime execution of queries. Chapter 3: Configuring KB_SQL for Your Site 79

91 Server user initial execute: character (60) Enter the M code that will validate and/or establish the username (SQLUNAME) and password (SQLUAUTH) variables referenced during the connection to the server. IMPORTANT: Type YES at the COMMIT? prompt to save your changes. If you answered YES to the Edit network configuration prompt, the TCP/IP Defaults window appears. You do not need to specify values for these prompts. Do so only if you want to overwrite the defaults. TCP/IP Defaults Timeout for read commands: integer (3) If you do not specify a timeout, all TCP/IP reads will be indefinite. The value of specifying a timeout depends greatly on how the TCP/IP support is implemented by your M vendor. Maximum length of M string: integer (5) When writing messages using TCP/IP, the product attempts to minimize the number of M WRITE operations by packaging the message into the fewest number of WRITE commands as possible. Therefore, if you specify a larger value for this prompt, you can reduce the number of TCP/IP I/O operations and improve the performance of the interface. The default is 511. Output buffer size: integer (5) 80 KB_SQL Database Administrator s Guide

92 (This prompt applies to M/SQL only.) If the value of the output buffer can be controlled by your implementation of M, you may want to experiment with supplying different values for this prompt. TCP/IP is a stream protocol that is fully buffered, so most of the optimizations are done at lower levels. The default is Input buffer size: integer (5) (This prompt applies to M/SQL only.) If the value of the output buffer can be controlled by your implementation of M, you may want to experiment with supplying different values for this prompt. TCP/IP is a stream protocol that is fully buffered, so most of the optimizations are done at lower levels. The default is After supplying values in the TCP/IP Defaults window, the Select, Insert, Delete TCP Hosts window appears. If you press [enter] to edit the highlighted host or press [insert] to add a new host, the TCP Host Information window appears. This window lets you define local and remote hosts. TCP Host Information Host name: character (30) Enter your computer s TCP/IP host name. IP address: character (20) Enter the Internet address for your computer. Chapter 3: Configuring KB_SQL for Your Site 81

93 Description: character (50) Enter a brief description for this TCP/IP host. Local host? YES/NO Answer YES if your computer is the local host. If it is a remote host, answer NO. After you supply values for the prompts in the TCP Host Information window, the Select, Insert, Delete Ports window appears. You should have one port for each user license in addition to a port server. For example, a 24-user license should have 24 alternate ports and at least one port server. Note: MSM does not require alternate ports. Select, Insert, Delete Ports 82 KB_SQL Database Administrator s Guide

94 TCP Ports Port number: integer (5) The port numbers are not significant. However, in order to avoid conflict with the O/S or a TCP/IP service, do not use numbers less than 5000 and do not specify a port number that is used by some other TCP/IP service. Check with your network administrator for a range of ports that is available to you. Port server? YES/NO You must have at least one port server. If this is the published port (the port number that is known as the one listening for ODBC connections), answer YES. If you answer YES, this port number should be entered in your ODBC data source configuration. For all other ports, which are considered alternate ports, you should answer NO. Note: To create a report that shows the definition and status of the TCP ports, use the SQL Editor to run the online query SQL_TCP_PORTS. Chapter 3: Configuring KB_SQL for Your Site 83

95 CUSTOM LOGIC Option KB_SQL has designed several hooks with which you can customize the operating environment to fit your needs. Each of these executes can include either in-line or external M code references. Each execute will look for particular input variables depending on the context. Each will check for an error in the variable SQLERR after execution of the code. Custom Logic #1 Note: Select the MORE option to see another menu of custom logic. Select the EXIT option to return to the Custom Logic #1 window. Custom Logic #2 84 KB_SQL Database Administrator s Guide

96 USER ID Option This execute can be used to determine the user s password without prompting the user at sign on time. This execute can also be used to disable the KB_SQL security system by having all users sign on using the DBA password. DEVICE INFO Option Determine interactive device type execute: character (65) The device type execute can be used in single user systems to permanently identify the device type. This will prevent the system from prompting for the device type at each sign on. Chapter 3: Configuring KB_SQL for Your Site 85

97 It is possible to override the default device management provided by KB_SQL in order to use device management features already supported by your applications. The device selection execute lets you use your existing device subsystem to identify your output device. The device open execute allows you to specify how to open the selected output device. The device close execute is used to reset and close the output device. Note: This is an all-or-nothing choice, if you use any of these options (select, open, or close) you must use all of the options. Also, if you enter open or close execute code at the site level, any code that you enter for the logical or physical device definitions will not take affect. (Open and close execute code for the logical and physical device definitions can be entered by selecting the TERMINALS/PRINTERS option.) Custom device selection execute: character (65) In order to use this feature properly you should perform an exclusive NEW command to preserve and protect KB_SQL variables. If a device is selected, you must use the variable SQLOD (other device) to identify the device and any related device parameters. This SQLOD variable must be set to a non-null value. If output should be directed to the current I/O device, the SQLOD variable should be set to NULL. If the query should run in the background, you must set the variable SQLBG to a true value. Otherwise, the SQLBG variable should be set to NULL. The SQLOD variable is the default device related variable that will be preserved by the background queue manager, so it is important to include all information that the open and close logic will require. The device select logic should also set the logical input function KIF equal to 1. If the device selection logic overwrites part of the SQL window, the SQLWIN variable should be set to NULL to cause the SQL window to be repainted after the device selection. 86 KB_SQL Database Administrator s Guide

98 Custom device open execute: character (65) This logic should perform any open and use logic necessary to use the output device specified by SQLOD. This logic must also preserve the current values of KO(4), KO(27) and KFL when running in the foreground. This logic must also set the KO(4), KO(27) and KFL variables to appropriate values for the output device. Custom device close execute: character (65) This logic should reset and perform any close logic necessary to use the output device specified by SQLOD. This logic must also reset the KO(4), KO(27) and KFL values to their previous state (before the device open logic). Example This example routine has three entry points: ^DEVICE for device selection; OPEN^DEVICE for device open; and CLOSE^DEVICE for device close. The corresponding site custom logic would be: DEVICE SELECT: DEVICE OPEN: DEVICE CLOSE: D SELECT^DEVICE D OPEN^DEVICE D CLOSE^DEVICE Variables SQLOD = other device information (must be set to a non-null value to execute the open and close logic) SQLBG = background job (must evaluate to true to run in background) SQLWIN = SQL window status (true means SQL window is O.K., false causes SQL window to be repainted) KO(4) = write page feed execute, usually "W #" KO(27) = interactive flag, 1 for CRTs and 0 for printers KFL = form length, usually 24 for CRTs and 60 for Chapter 3: Configuring KB_SQL for Your Site 87

99 printers Routine KIF = logical input function (just set to 1 in device selection) DEVICE SELECT OPEN CLOSE ; Custom device select/open/close example ; S KY=19,KX=1 X KO(2) R "Output to device:",sqlod ; device selected I SQLOD?1.N S SQLBG=1 ; no device selected E S (SQLOD,SQLBG)="" ; SQLWIN causes window to be refreshed S SQLWIN="",KIF=1 Q ; ; O SQLOD U SQLOD ; for foreground jobs, save old values S KO(4)="W #",KO(27)=0,KFL=60 I '$D(KO) Q S SQLOD(4)=KO(4),SQLOD(27)=KO(27),SQLOD("KFL")=KFL Q ; ; C SQLOD ; for foreground jobs, reset old values I $D(SQLOD)\10=0 Q S KO(4)=SQLOD(4),KO(27)=SQLOD(27),KFL=SQLOD("KFL") K SQLOD Q 88 KB_SQL Database Administrator s Guide

100 VARIABLE CHECK Option This execute can be used to ensure that all host variable references use a valid format. This example ensures that all variables start with the client name range prefix 'SQLA'. HOST FILE NAME Option This execute can be used to ensure that all host file name references use a valid format. The execute logic will usually be dictated by the host operating system file naming standards. ROUTINE NAME Option Whenever the user is allowed to enter an M routine name (e.g., through the SQL Editor), this execute will ensure that a valid format is used. This prevents users from overwriting routines already in use. This example ensures that all routine names start with the client name range 'SQLA'. Chapter 3: Configuring KB_SQL for Your Site 89

101 DBA SIGNON Option The DBA SIGNON option provides a free-form text field in which you may enter an M execute to set the programming flag or display usage statistics each time a DBA user signs on. If the variable SQLERR contains an error text, the value will be displayed and the sign on will be aborted. USER SIGNON Option The USER SIGNON option provides a free-form text field in which you may enter M execute to display system messages or check the system status each time a non-dba user signs on. If the variable SQLERR contains an error text, the text will be displayed and the sign on will be aborted. 90 KB_SQL Database Administrator s Guide

102 LOG ERROR Option Enter M code to be executed for all errors trapped by the system. This logic will be performed after the KB_SQL error log has been updated. CHECK QUERY Option Enter M code to be executed whenever the system checks to see if a query object is available. Chapter 3: Configuring KB_SQL for Your Site 91

103 COMMIT PROMPT Option Enter M code to be executed in place of the standard Commit? prompt. If the variable SQLERR is defined, KB_SQL will roll back all pending changes. Warning: If the code you enter contains a syntax error or M error, you won t be able to save any future changes until you correct the code. However, you can t use this option to change or delete the code. You must return to the M prompt and kill the ^SQL(1, 3, 19) global, and then use this option to enter the correct code. SET PROCESS ID Option You must ensure that each SQLJOB value is unique across all systems. If you are working in an environment in which $J is not a unique identifier, and if your operating system does not have a feature for making unique identifiers, you can use the SET PROCESS ID option. We suggest you incorporate the system name as part of the Job ID. 92 KB_SQL Database Administrator s Guide

104 RUN CHECK Option This is a string of executable M code that will be performed each time the query halt check is performed. This code can be used to check site-specific information and halt the query execution by setting the SQLERR variable to a literal message. The query halt check is performed once for each page printed or after a specific number of rows have been searched. You can control how often to perform the check by setting the Perform halt check after rows prompt in the Site Date/Time Limits window. STATS HALT CHECK Option This executable code is used to stop the statistics compile process. It is executed every n rows where n is determined by the system value for the query HALT_CHECK parameter. (The HALT_CHECK parameter is discussed in the KB_SQL Syntax Guide.) The code must include the SQLERR variable. If the code returns an SQLERR, the statistics compile process terminates gracefully. A situation in which you may want to use this option would be when the process is running in background and you need to take the system down for maintenance. Chapter 3: Configuring KB_SQL for Your Site 93

105 GENERATE ROUTINE Option When KB_SQL generates M routines, it assigns unique names to the routines. Each routine name consists of a prefix, a counter, and a suffix. In order to generate unique routine names, we use an algorithm to determine the next available routine name based on a counter variable. The GENERATE ROUTINE option lets you enter M code to generate your own unique routine suffix to be used for M routine names. Our default algorithm is illustrated below. Prefixes can be assigned by using the CONFIGURATION/BASE ROUTINE EDIT option. JOB COMMAND Option The JOB COMMAND option allows you to enter M code to start a background process according to the special rules of your system. The variable RTN contains the routine reference return SQLERR with a textual message in case of an error. 94 KB_SQL Database Administrator s Guide

106 START DATE EDIT Option Use this procedure to create custom start date and time values for the background queue manager. When you select the START DATE EDIT option, the selection window shown below appear. It contains system-supplied values for running background jobs every day and any day of the week. You can add new start dates by pressing [insert]. Select, Insert, Delete SQL Custom Start Dates Chapter 3: Configuring KB_SQL for Your Site 95

107 Start Date Information Name: character (30) Each start date must have a name. The name must be a valid SQL_IDENTIFIER. You will reference the name when defining values for the background queue manager. Description: character (60) Provide a description for the start date. M Execute (set D=date, T=time) The variables D (date) and T (time) are used to customize start date logic. When the query is executed, the D value is null, and the T value is set to the start time, or a suitable default (not null). The logic should set D to an appropriate base date value. Since all start dates are assumed to be reoccuring, after the query is executed, the logic is called again with D set to the previous start date, and T set to the previous start time. The logic should adjust the D and T values as appropriate. If the logic sets either D or T to null, the query will be deleted from the queue and it will not be rescheduled. 96 KB_SQL Database Administrator s Guide

108 REPORTS Option Use this procedure whenever you need a hard copy printout of base routine, function, pseudo column, or site definitions. These reports are valuable reference documents for your organization. In particular, the site report should be available to the DBA at all times. Select REPORTS Chapter 3: Configuring KB_SQL for Your Site 97

109 Report Parameters Print Base Routines Some of the reports let you limit the report to only certain definitions. You can enter a starting and ending point for the definitions, or you can accept the default (A through ZZZ). Assigning an Output Device After KB_SQL generates the report, the Print on Device window appears. Press [enter] to view the report on your monitor, or press [list] and select from the list of output devices. Print on Device 98 KB_SQL Database Administrator s Guide

110 BASE ROUTINE PRINT Option This report lists all base routines showing the current and maximum counter values. Any user groups that are using the base routines are listed as well. EXPORT METHOD PRINT Option This report lists all predefined export methods, including pre-process, row, and post-process execute logic. FUNCTION PRINT Option This report lists all site-defined functions showing the parse routine, the run routine, and the result domain. A copy of this report, as well as the function calculation code, should always be available to the DBA. IMPORT METHOD PRINT Option This report lists all predefined import methods, including pre-process, row, and post-process execute logic. Chapter 3: Configuring KB_SQL for Your Site 99

111 PSEUDO COLUMN PRINT Option This report lists all site-defined pseudo columns showing the M expression and the result domain. A copy of this report should always be available to the DBA. To obtain a listing of the pseudo columns supplied by KB Systems: use the SQL Editor, position the cursor in the SQL text area, and press [list]. SITE PRINT Option This report shows all of the values entered in the SITE EDIT procedure. A copy should be available to the DBA at all times. This report should be printed for verification after every update of KB_SQL. START DATE PRINT Option This report prints the custom start dates for the background queue manager. The name, description, and M code for each start date value is included on the report. 100 KB_SQL Database Administrator s Guide

112 4 Managing Devices KB_SQL is designed to run on all M platforms and to support many different types of input and output devices. However, in order for KB_SQL to support your device types, you might have to define a custom driver. You can define your physical device types (printers, consoles, etc.) and assign attributes to them by selecting the DEVICE TYPE EDIT option from the TERMINALS/PRINTERS menu. You can assign each device a logical device name, by selecting the LOGICAL DEVICE EDIT option. You must assign logical names to each physical device so that each individual device will have its own unique name. Keep in mind that any open or close execute code that you specify at the site level overrides any code that you enter for the logical or physical device definitions. Chapter 4: Managing Devices 101

113 DEVICE TYPE EDIT Option Select TERMINALS/PRINTERS You can use the DEVICE TYPE EDIT option to define device characteristics to the system. Definitions for input devices will include box drawing codes, device attributes, logic for cursor positioning, and more. Output devices will often have open and close execute code to set and reset printer characteristics. Select, Insert, Delete Device Type After you select your device type, the Device Type Options window appears. 102 KB_SQL Database Administrator s Guide

114 Device Type Options TYPE INFO Option Device Type Name: character (30) Each device type must have a name. You will reference the name when defining logical devices and when transferring device type definitions. Routine: character (10) Chapter 4: Managing Devices 103

115 Each device type can have a routine designated as a place holder for initialization, termination, and input translation logic. This routine will be transferred when the device type is transferred. Description: character (60) Provide a description for the device type. Class: character (20) [list] Most printers will be classified as output only. Interactive devices that can perform cursor positioning and clearing logic are considered smart. The ROLL_UP device type is interactive, not smart. Sequence: integer (4) This prompt is not accessible. It applies only to subtypes. Refer to the section on the SUBTYPES option. BOX CODES Option Smart device types will use the full-featured KB_SQL windowing environment. You can specify the ASCII character for each of the window components. This example uses the graphic characters for the box outline. You can use simple characters such as the dash and vertical bar for character-based terminals. 104 KB_SQL Database Administrator s Guide

116 Box Drawing Codes The Window Box Codes Box UC Left Box UC Right Box Horizontal Prefix Box Vertical Box LC Left Box LC Right Chapter 4: Managing Devices 105

117 ATTRIBUTES Option These attributes are currently used only for smart device types, not for printers. Each execute will be characteristic of your M implementation. Note: The sample code is for illustrative purposes only and does not necessarily apply to your device type. Device Attributes Bold ON/OFF The executes for turning on the bold attribute will often be escape sequences. 106 KB_SQL Database Administrator s Guide

118 Echo ON/OFF The logic for setting echo will sometimes require using the current device with an implementation specific parameter. Graphics ON/OFF If defined, the graphics on execute will be performed before and after writing the box drawing codes. Warning Bell The bell will be sounded in all error and warning messages. Note that the bell is not required, and can be left undefined. Chapter 4: Managing Devices 107

119 POSITION & CLEAR Option You must supply logic for performing a number of cursor movements and clear operations. Each execute will be characteristic of your M implementation. These executes will often reference the row (KX) and column (KY) variables. Note that the upper-left corner of the screen is considered (1,1). Note: The sample code is for illustrative purposes only and does not necessarily apply to your device type. Position & Clear Position Cursor 108 KB_SQL Database Administrator s Guide

120 Position Cursor & Clear Screen Position Cursor & Clear Line Clear Entire Screen (or Pagefeed) This execute must be defined for all printer devices. Note: If you use a special escape sequence to execute a pagefeed or linefeed, make sure the $Y and $X variables get reset as part of the execute. Chapter 4: Managing Devices 109

121 Clear Entire Screen from Cursor Clear Line from Cursor 110 KB_SQL Database Administrator s Guide

122 KEY TOPS Option Key Tops KB_SQL uses a predefined set of input functions. You can control which key will perform a specific input function. The actual key top will depend on the brand of keyboard that you are using and the preferences of your users. Note: Do NOT use the greater than (>) or less than (<) symbols in a key top name. Chapter 4: Managing Devices 111

123 SUBTYPES Option KB_SQL allows you to use a single physical device in several different modes. For example, a highly functional dot matrix printer can be used to print reports in draft, normal, and letter quality. A laser printer can be used in portrait and landscape modes. Some terminals and PC consoles running a terminal emulator can run in wide (132-column) mode. By defining subtypes, you can allow a single device name to be used for multiple device type modes. If you have not defined any subtypes, the Add Subtypes window will appear when you select the SUBTYPES option. Select YES to add a subtype. Otherwise, if subtypes exist, the Select, Insert, Delete selection window will appear. You can press [insert] to add a new subtype, or select the subtype you wish to edit. If you want to delete a subtype, highlight it and press [delete]. Device Type Options (for subtypes) 112 KB_SQL Database Administrator s Guide

124 TYPE INFO Option (for Subtypes) Subtype of... Name: character (30) Each device subtype must have a name. You will reference the name when defining logical devices and when transferring device subtype definitions. Routine: character (10) Each device subtype can have a routine designated as a place holder for initialization, termination, and input translation logic. This routine will be transferred when the device subtype is transferred. Description: character (60) Provide a description for the device subtype. Class: character (20) [list] Most printers will be classified as output only. Interactive devices that can perform cursor positioning and clearing logic are considered smart. The ROLL_UP device type is interactive, not smart. Sequence: integer (4) Using this prompt, you can specify the order in which subtypes appear in the selection window. For example, assign the most frequently used subtype a sequence number of 1, and it will appear first in the selection window of device subtypes. (See note on next page.) Note: If you assign a sequence number to a subtype, you must assign sequence numbers to all the subtypes for that device type. If you do Chapter 4: Managing Devices 113

125 not assign sequence numbers to any of the device type s subtypes, the subtypes will appear in the selection window in alphabetical order. CUSTOM LOGIC Option This section includes a variety of device type functions. Each one will be characteristic of your M implementation and the device type. Printers will often use the open and close executes. Smart device types will include logic for performing a single character read, interpreting input functions, and for setting terminal colors. Note: The sample code is for illustrative purposes only and does not necessarily apply to your device type. Device Executes OPEN EXECUTE Option 114 KB_SQL Database Administrator s Guide

126 This execute can open the current port variable (KCP) with device type specific parameters. This execute will often set the form length (KFL) and the form width (KFW) variables. IMPORTANT: Any open execute code entered using the CONFIGURATION/SITE EDIT/CUSTOM LOGIC/DEVICE INFO option will override this code. Set Device Parameters when Opened Chapter 4: Managing Devices 115

127 CLOSE EXECUTE Option This execute will be performed before the device is closed. For smart device types that modify character interpretation tables, you can reset the device (KCP) at this point. IMPORTANT: Any close execute code entered using the CONFIGURATION/SITE EDIT/CUSTOM LOGIC/DEVICE INFO option will override this code. Reset Device Parameters when Closed 116 KB_SQL Database Administrator s Guide

128 SINGLE CHARACTER READ Option For smart device types you must supply logic for performing a single character read in the query editor and other text windows. This logic receives the input in the variable (A), and returns the input function (KIF) variable. Read One Character into Variable 'A' DETERMINE INPUT FUNCTION Option This logic typically invokes a routine to perform input function translation. If possible, the logic calls the routine only if a special terminator is detected. Determine Input Function and Translate Chapter 4: Managing Devices 117

129 SET COLORS Option You can specify how to set the foreground (KVCF) and background (KVCB) colors. This logic is characteristic of your M implementation. Each user can have their own color preferences. Refer to the SECURITY menu s USER EDIT option. Set Foreground (KVCF) and Background (KVCB) Colors 118 KB_SQL Database Administrator s Guide

130 LOGICAL DEVICE EDIT Option You can define a logical device by assigning a name to the combination of a physical I/O port and a device type. Once defined, all users may reference that combination by the logical device name. In general, no two devices should share the same physical port address. Also, each logical device in a physical device type group will have access to the same device subtypes (e.g., landscape, portrait) that you assigned to the physical device. In the selection window shown below, the DBA has defined three logical device types (ACCOUNTING_PRINTER, ADMIN_PRINTER, and LAB_PRINTER). Each of these logical device types is assigned to a different physical device type. This is not always the case. Often a site will have the same physical device (e.g., a laserjet printer) at several locations. And each device at each location must be given a unique logical device name. Select, Insert, Delete Device Chapter 4: Managing Devices 119

131 Device Definition (The values supplied in the example above apply to MSM only.) Device name: character (30) This is the logical device name. This is how the user will refer to the device. Description: character (30) Provide a description for the device. Device type: character (30) [list] Select from a list of defined physical device types. Depending on your site, you may have several logical device names that refer to the same physical device type. Host device: character (30) This is the physical I/O port or network address of this device. In general, no two devices will share the same port unless it is a shared device as shown by our example. Foreground only? NO/YES Enter YES if this device can be used only for foreground processing. An example is an attached or slave printer. 120 KB_SQL Database Administrator s Guide

132 Custom device open execute: character (65) Enter code to specify how to open this logical device. In this example, the code instructs the spooler to print on queue lp2 instead of the default print queue. IMPORTANT: Any open execute code entered using the CONFIGURATION/SITE EDIT/CUSTOM LOGIC/DEVICE INFO option will override this code. Custom device close execute: character (65) Enter code to specify how to close this logical device. If you do enter open execute code and do not enter close execute code, KB_SQL will close the host device. In this example, the code closes the spooler. IMPORTANT: Any close execute code entered using the CONFIGURATION/SITE EDIT/CUSTOM LOGIC/DEVICE INFO option will override this code. Chapter 4: Managing Devices 121

133 REPORTS Option When you select the REPORTS option, the Select Reports window appears. Select REPORTS 122 KB_SQL Database Administrator s Guide

134 DEVICE TYPE PRINT Option This report lists the device type definitions that fall within the range that you specify in the Print Device Specifications window. Print Device Specifications The following data is included on the report. P P P P Box drawing codes Attributes Custom logic Key tops LOGICAL DEVICE PRINT Option This report lists the names of the defined logical devices that fall within the range that you specify in the Print Device Names window. The report shows the name, the device type, the host port, and whether or not the device can be used only for foreground processing. Print Device Names Chapter 4: Managing Devices 123

135 Supplying Input Translation Routines One of the primary objectives of KB_SQL is to preserve both the software and hardware investments of our clients. One way that we accomplish this objective is by using only ANSI Standard MUMPS (M) so that KB_SQL can run on all vendor implementations of the language. Another way is by using a limited set of input and output functions that you define. You also supply the code behind these functions. The code must follow the rules and guidelines presented in this manual. Interactive Device Types For the purposes of this discussion, terminals and personal computer consoles are considered interactive device types, capable of receiving and transmitting information in character format. Users interact with KB_SQL through the use of a keyboard. Internally, KB_SQL looks for standard input function codes to determine the action desired by the user. In order to provide successful communication, you must supply an input translation routine. The input translation routine maps keyboard inputs into KB_SQL input functions using logic that is specific to both the M implementation and the device type. 124 KB_SQL Database Administrator s Guide

136 Input Functions Through the use of standard input function codes, KB_SQL can interpret keyboard input commands for all types of interactive device types. Code Function enter skip help list up down right left copy insert delete first last pgup pgdn undo exit rubout tab backtab bol eol mark Description standard entry, accept input save edits and go to next window display on-line help documentation display a list of valid entries for selection move cursor up one row move cursor down one row move cursor right one column move cursor left one column copy marked text to clipboard insert text or new row delete text or current row move to the first position in the window move to the last position in the window display previous page display next page roll back edits to current window and go to previous window roll back edits to procedure and exit to menu delete current character and move cursor left one column move cursor right to next tab position move cursor left to previous tab position move cursor to beginning of line/text move cursor to end of line/text mark text block for editing Chapter 4: Managing Devices 125

137 Input Function Translation Each of the input function codes corresponds to a sequence of one or more keyboard actions. For example, a personal computer might use the function keys F1 thru F10 for the more frequently used functions. A terminal, such as the VT100, might use a combination of the control key with a mnemonic character, such as control-i for the [insert] function. Some simple, limited function device types, such as ROLL_UP, use special characters of input to specify input functions. The input function key tops allow you to specify a brief key sequence identifier to be used as a reminder to the users. In addition, you must provide a translation routine to map the input from a particular terminal into the appropriate input function code. The style of each input translation routine will vary depending on the device type, the M implementation, and your preferences. Standard Device Drivers The specific details about keyboard actions can be found in the reference manual for your particular device type. The M programming reference for your implementation must also be consulted for specific information about device handling. The combination of data can then be combined to produce an M routine that will translate keyboard actions into KB_SQL input functions. 126 KB_SQL Database Administrator s Guide

138 ROLL_UP Device Type To illustrate the basics of device input translation, consider first the ROLL_UP device type. This basic device type will work with all implementations of M and with all interactive device types. Although simple, it provides a gentle introduction to the basic concepts. The following table shows the basic information required for the ROLL_UP device type input translation. The key description is the documentation that will be presented to the user by the [keys] function. Function Code Key Sequence Key Description enter 1 enter enter skip 2 *S skip: *S help 3 *H help: *H list 5 *L list: *L up 6 *UA up: *UA down 7 *DA down: *DA insert 11 *I insert: *I delete 12 *D delete: *D pgup 15 *PU pgup: *PU pgdn 16 *PD pgdn: *PD keys 17 *K keys: *K undo 20 *U undo: *U exit 21 *X exit: *X This device type uses key sequences to indicate the input function. The translation routine would be called whenever the input value contains the asterisk (*) character. The translation routine would map the key sequence to return the appropriate input function code. Chapter 4: Managing Devices 127

139 VT100 Device Type The input functions for the VT100 terminal are specified in a different manner from the ROLL_UP device type. Special function keys and control characters are used to indicate input functions. Function Code Key Sequence Key Description enter 1 return enter skip 2 PF4 skip:pf4 help 3 PF1 help:pf1 list 5 PF2 list:pf2 up 6 up_arrow up down 7 down_arrow down insert 11 ctrl_i insert: ctrl_i delete 12 ctrl_e delete: ctrl_e pgup 15 ctrl_p pgup: ctrl_p pgdn 16 ctrl_n pgdn: ctrl_n keys 17 ctrl_k keys: ctrl_k undo 20 PF3 undo: PF3 exit 21 ctrl_u exit: ctrl_u In order to determine which control sequence is entered by the user, the input translation routine must handle input terminators other than the [enter] key. Each M vendor provides a method for handling terminators. In addition, some require that you specify a list of valid terminators when the device is opened. 128 KB_SQL Database Administrator s Guide

140 INPUT Translation Checklist By answering the following questions for each device type, you will have a good idea how to proceed with the definition of a translation routine. How does your M implementation handle input terminators? You must be able to recognize when special functions have been requested. Advanced device types will often use input terminators. Each implementation handles terminators differently. This logic will be used in the M execute used to determine input function. P DTM: $ZIOT'=13 P MSM: $ZB#256'=13 P ISM: $C($ZB)'=13 Does your M implementation perform input translation? If you want to use the KB_SQL translation method you must disable any translation methods provided by the vendor. This logic will be used in the initialization for the device type. P DTM: USE $I:IXXLATE=0 How does your M implementation recognize input terminators? Some implementations require that all valid terminators be specified when opening the device. This logic will be used in the initialization for the device type. P DSM: USE $I:TERM=$C(1,5,6,7,8,9,11,12,13,14,16,21,22,23,26) P MSM: USE $I:(0::::262144::::$C(0,13,27)) Chapter 4: Managing Devices 129

141 The Translation Routine The typical input translation routine has sections for the functions outlined below. String Read The string read is typically used in value windows. The determine input function execute determines if any special input has been entered and invokes the input translator. This sample code is typical of the determine input function execute: IF <special terminator> THEN DO <string read translation>. P User input is in the variable N. P P Input terminators are available in vendor-specific variables. The routine should return the input function in the variable KIF. Invalid function keys should be reported as follows: P Set input function (KIF) = 0 and quit. 130 KB_SQL Database Administrator s Guide

142 Single Character Read Single character reads are typically used by menus and menu bars. The input translator is invoked directly for character values not in the range of or for values greater than 127. P User input is in the variable A. P P The routine should return the input function in the variable KIF. Invalid function keys should set KIF=0 and quit. The input handler will handle the error from there. Initialization This execute can be used to set device parameters for use within KB_SQL. The form length (KFL) and form width (KFW) variables should be set for output device types. The current port (KCP) variable can be referenced for OPEN/USE commands. Termination This execute can be used to reset device parameters before closing the device. The current port (KCP) variable can be referenced. Chapter 4: Managing Devices 131

143 Translation Routine Examples You can write translation routines many ways. Several default device type translation routines are delivered with your system. The following vendor-specific routines show you how a translator routine can be written. Although several translation routines come standard with KB_SQL, it is your responsibility to determine the most appropriate method of input translation for each client site. ROLL_UP SQLDRU ; device - roll up (all) NEW A,B SET B=$L(N,"*"),A=$P(N,"*",B) IF A'?1.2A Q SET A=$P($T(@A),";",3) IF A SET KIF=A,N=$P(N,"*",1,B-1) Q S ;;2;skip H ;;3;help L ;;5;list UA ;;6;up DA ;;7;down I ;;11;insert D ;;12;delete PU ;;15;pgup PD ;;16;pgdn K ;;17;keys U ;;20;undo X ;;21;exit determine input function: IF N["*" DO ^SQLDRU 132 KB_SQL Database Administrator s Guide

144 DSM VT100 SQLDVV1 ; KB_SQL DSM VT100 ; single character read I A=13 S KIF=1 Q 0 I A'=27 S KIF=$P("1,,,,12,13,24,3,11,,17,14,... 29,16,,15,,,,,21,10,22,,,26",",",A) Q R *A:1 I A=79 R *A:1 S KIF=$P("3,5,20,2",",",A-79) Q I A=91 R *A:1 S KIF=$P("6,7,8,9",",",A-64) Q EX R *A:1 Q IN N A S A=$ZB#256 X:KO KO(9) D 0 X:KO KO(10) Q INIT S KFL=23,KFW=80 U KCP:(NOLINE:NOESCAPE:WIDTH=0:TYPE:... TERM=$C(1,5,6,7,8,9,11,12,13,14,16,21,22,23,26)) Q TERM Q Chapter 4: Managing Devices 133

145 Printing Strategies KB_SQL provides a method for using printers and other output devices. All devices must be defined through the LOGICAL DEVICE EDIT procedure as the named combination of a physical I/O port and a device type. The system provides a print spool for processing query runs as background jobs. Multiple subtypes can be defined for a device type. This feature allows a single device to be used in several printing modes. 134 KB_SQL Database Administrator s Guide

146 Using Subtypes, Emulation, and Spooling You can define device type subtypes for any device type that can support different styles of interaction. For example, some printers can perform in landscape and portrait mode, using draft, normal, and letter quality print. If subtypes are defined, device selection is a two-step process. In the Print on Device window below, the PRINTER device is a laser printer that has subtypes for portrait and landscape modes using compressed and normal print. After selecting the PRINTER device, you can then select the subtype (or mode) desired. Print on Device Chapter 4: Managing Devices 135

147 Subtype Examples First, define the base characteristics of the printer as a device type. For each subtype, enter only those characteristics that are different from the base set. In many cases, the subtype definition will have different initial execute code to send a set of printer commands to the printer. This example shows how a single output device can be used in multiple modes. Note how each device type sends a string of escape sequences to the printer and that each execute sets the form length (KFL) and form width (KFW) variables. Subtype Letter_Quality 1_Inch_Labels Normal Subtype Portrait_Letter Portrait_ Compressed Landscape_Letter Landscape_ Compressed Subtypes for HP_LASERJET_II Initial Execute W *27,"&l7.27C",*27,"(sp10H" S KFL=60,KFW=77 W *27,"(8U",*27,"(s0p16.66H8.5v0s0b0T",*27,"&l88p8D",*27,"&a10L" S KFL=80,KFW=120 W *27,"&l10",*27,"(s0p10H" S KFL=44,KFW=105 W *27,"&l1o5.45C",*27,"(s0p16.66H" S KFL=62,KFW=180 Subtypes for EPSON_LQ Initial Execute W *27,*120,1 S KFW=80,KFL=60 W *27,"C",*6,*27,2 S KFL=6,KFW=35 W *27,"P",*27,2,*27,"CB" S KFL=60,KFW= KB_SQL Database Administrator s Guide

148 Terminal Emulators If you use communications software to allow personal computers to act as terminals on a host system, you are familiar with the concept of terminal emulation. Most of these packages can allow the PC to share data with the host system, either through serial communication or through a virtual connection. With the appropriate hardware, some communications packages will allow the following functions: P P P P P Print 132 column reports on your terminal. Download data from your host system to a PC. Upload data from a PC to your host system. Send reports to a fax machine. Print to attached printer. The additional functions that can be performed will depend on the capabilities of the communications package. The download and upload functionality can be a powerful tool that helps end users retrieve and analyze their data. You may wish to review the sections on EXPORT and IMPORT methods for sharing data between a PC and host system. Also, refer to the SERVER INFO option if you plan to connect to a server from a Windows workstation. Chapter 4: Managing Devices 137

149 Using the Print Spool The KB_SQL print spool can be used to process query runs as background jobs. This feature allows query requests to be scheduled for processing on a future date and time, or at a later time on the same day. In order to use this feature, use the CONFIGURATION/SITE EDIT/BACKGROUND TASKS procedure to indicate that query runs should be performed in the background. Also specify the maximum number of background jobs. Any future queries must include the parameters START_DATE and START_TIME to schedule processing of the output. For example, the following query is scheduled to run at 2:00 AM of the next morning. SET START_DATE = TODAY+1 SET START_TIME = '2:00 AM' SELECT... FROM... WHERE... When KB_SQL places a query in the print queue, it checks periodically to see if the date and time have been reached. When the query is finished processing, KB_SQL removes the print task from the print queue. You can use the UTILITIES/HALT QUERY procedure to cancel a report request. 138 KB_SQL Database Administrator s Guide

150 The KB_SQL print spool handles regularly scheduled tasks as well as one-time tasks. Examples: To run a task every day, include the following statement in your query: SET START_DATE='ALL' To run a task on Fridays, include the following statement in your query: SET START_DATE='FRIDAY' Chapter 4: Managing Devices 139

151 140 KB_SQL Database Administrator s Guide

152 5 Applying Security Measures Database security is one of the DBA s most important responsibilities. By applying security measures, you ensure that your users have the necessary permissions needed to be successful with KB_SQL. One of the major benefits of using KB_SQL is that users can reference and manipulate their data; therefore, you should be careful to apply security measures only when necessary. Unless the information is potentially intimidating or dangerous for a particular user group, the data should be accessible to all. KB_SQL provides a grouping mechanism to help manage the security process, allowing many users to share common access requirements. Security also protects the database against unauthorized disclosure, alteration, or destruction. KB_SQL lets you use views and the authorization commands, GRANT and REVOKE, to ensure a secure database. Chapter 5: Applying Security Measures 141

153 Security for Users A user is an individual who is authorized to use KB_SQL. Every user must have a unique name and password, and all users belong to a user group. For example, an accounts payable clerk named Paul Smith might be defined as follows. P P P Name= SMITH_PAUL Password = PSM User Group = AP Security for User Groups A user group associates one or more users with a common job class or organizational role. Users within a user group perform similar tasks and require access to the same information. All users in a group will have access to the same procedures, queries, and tables. For example, separate user groups might be defined for accounts payable, accounts receivable, payroll, and personnel. P P P P Group = AP Group = AR Group = PAY Group = PER The security system is responsible for enforcing the rules specified by the organization through the DBA. The rules are made known to the system through the GRANT and REVOKE statements. When a query is compiled, all referenced tables and SQL commands will be checked for authorization. The user of the query must have the appropriate authority to execute the query or else the system will reject the request with a message. 142 KB_SQL Database Administrator s Guide

154 Security Levels KB_SQL lets you control access at several levels. P P P System and Procedures SQL Command Qualifications Table and Query Privileges System and Procedures A valid user password is required to log on to KB_SQL. The password is supposedly known only to the system, the DBA, and to the user. Without a password, unauthorized individuals cannot access the system. Once the user is identified, a menu of accessible options is displayed for selection. SQL Command Qualifications A qualification is required to execute each SQL command. Certain user groups will be allowed only to view data. More experienced users may be allowed to select, update, and delete data. Still other groups may be allowed to create new tables and to control security. The DBA is qualified for all commands. Select Command Novice x Experienced x Advanced x DBA x Create/Drop x Insert/Update/Delete x x x Grant/Revoke x x Chapter 5: Applying Security Measures 143

155 Table and Query Privileges While a qualification provides a user the right to use a particular SQL command, a privilege applies to a specific table or query. In order to execute a SQL command, a user must be qualified to use the command, and the user must have the associated privileges on all referenced tables. A privilege is an authorization that allows members of a user group to access and manipulate a specified table or query within the SQL system. By default, a table or query is available to the DBA and all users in the group of the user that created the table or query. Through privileges, a table or query can be protected from modification by unauthorized users. You can give any or all user groups access to any or all tables and queries. The GRANT statement is used to give access. The REVOKE statement is used to restrict access. All operations apply to all members of the user group. When privileges are granted, the DBA can also give the privilege to GRANT privileges on the associated table. Consider the SQL statement: GRANT ALL ON employees TO managers WITH GRANT OPTION This command gives the users in the managers group all privileges on the employees table. The users in the managers group could now grant privileges on the employees table to other user groups. 144 KB_SQL Database Administrator s Guide

156 Table Privileges By default, a table is accessible by all members in the user group of the creator of the table. You can customize the rules of access to a table. Command SELECT INSERT UPDATE DELETE Description Retrieve rows of data from this table Add new rows of data to this table Modify existing rows of data in this table Delete rows of data from this table Examples: GRANT select ON employees TO new_users REVOKE insert, update, delete ON employees FROM new_users GRANT select ON employees TO PUBLIC GRANT select ON projects TO managers WITH GRANT OPTION Chapter 5: Applying Security Measures 145

157 Query Privileges By default, a query is accessible to the DBA and to all members in the same user group as the creator of a query. You can customize the rules of access to a query. Command SELECT UPDATE Description View, print, or run this query Modify or delete this query Examples: GRANT select ON QUERY my_emps TO managers REVOKE update ON QUERY my_emps FROM new_users 146 KB_SQL Database Administrator s Guide

158 Views and Security In a relational database, all operations on tables produce a result that is also a table. A view is a virtual table a representation of the data stored in one or more tables. Views are defined using the SQL command, CREATE VIEW. Once defined, the view looks like any other table to the user. KB_SQL supports the definition and use of views for retrieval purposes. Views can simplify the user s perception of the database and provide a powerful complement to the security function. The view mechanism can be used to hide sensitive data from unauthorized users. Views can limit the user s perception of a particular database to certain rows, certain columns, or a combination of rows and columns. Views created to provide security on tables will effectively create a logical table that is a subset of rows, columns, or both, from a base table. By eliminating restricted columns from the column list and by providing the proper predicates in the WHERE clause, you can create views to allow access to only those portions of a table that each user is allowed to access. If any component of a view is modified, any query that references the view will be recalculated the next time the query is requested. This ensures that views are always synchronized with the database and the security systems. Chapter 5: Applying Security Measures 147

159 View Examples A Row Subset Users of this view will see rows of task data that are for the laboratory project. CREATE VIEW lab_tasks (LAB_TASK, LAB_TASK_STATUS) AS SELECT task, status FROM tasks WHERE proj_no = 200 A Column Subset Users of this view will see all rows of employee data except the salary column. CREATE VIEW emp_view (EMP_NAME, EMP_NUMBER, EMP_MGR) AS SELECT name, emp_ssn, manager FROM employees 148 KB_SQL Database Administrator s Guide

160 A Row-and-Column Subset Users of this view will see rows of employee data for the manager KING, except the salary column. CREATE VIEW king_emp_view (KING_EMP_NAME, KING_EMP_NUMBER) AS SELECT name, emp_ssn FROM emp_view WHERE manager = ' ' A Statistical Summary This view shows how to include a function value as a column in a view. CREATE VIEW mgr_avg_salary (MGR_NAME, MGR_AVG_SAL) AS SELECT manager, avg(salary)) FROM employees GROUP BY manager Chapter 5: Applying Security Measures 149

161 The USER Key Word This view shows how to use the USER key word to produce a table of employees that work for this user. CREATE VIEW my_emps (MY_EMP_NAME, MY_EMP_NO, MY_EMP_SAL) AS SELECT NAME, EMP_SSN, SALARY FROM employees WHERE manager@name = USER 150 KB_SQL Database Administrator s Guide

162 Using the Default Security When KB_SQL is first installed, three user groups and five users are defined. Refer to Chapter 1 for an explanation of each user groups menu options. The DBAS user group has a single user, DBA, with the password of SHARK. This user has all privileges and authorizations. As DBA, you may decide to change the password for this user, but you may not delete the user. The SYS_MGRS user group has a single user, MGR, with the password of MGR. Users in this group can access all tables, views, and queries but not all menu options. In addition, the SysMgr is restricted from parts of procedures that allow the entry or modification of M code. The third user group, USERS, has three users: USER, EZQ, and RUN. The USERS user group comes defined with privileges to access only the demonstration tables, views, and queries. The USER user will have access to the SQL Editor and to the EZQ Editor only. The EZQ user will have access to the EZQ Editor only. The RUN user will be able to execute compiled queries, but will not be able to edit or create queries. Note: PUBLIC is a special pseudo user group also supplied with KB_SQL. If you assign privileges to PUBLIC, all users will have those privileges. Refer to the PUBLIC PRIVILEGES Option section in this chapter for more information. Chapter 5: Applying Security Measures 151

163 Customizing Security Many M installations already have an existing user identification and security system. These installations generally prefer to avoid a redundant password question when the KB_SQL options are invoked. Conversely, some installations are either single user systems or have no requirement for user security within the KB_SQL system. Through the CONFIGURATION/SITE EDIT/CUSTOM LOGIC/USER ID procedure, KB_SQL allows you to enter custom M code to determine the user at sign on time. Eliminating Security In this example, all users will sign on as the DBA, using the SHARK password. This is often desirable on a single user system where unauthorized access is not an issue. Integrating Security Systems This example uses a site-defined routine %USER to map from the client security system into KB_SQL. This situation is often preferred so that KB_SQL can appear as an integral part of the client software. 152 KB_SQL Database Administrator s Guide

164 GROUP EDIT Option The GROUP EDIT option lets you create, edit, and delete user groups. It also lets you assign privileges to more than one user at a time. When you add a new user (using the USER EDIT option), you assign the user to a user group. Each group will have a unique name, a routine set, and a default schema. The user group is the foundation for all of the security functions in KB_SQL. Add You may wish to create separate user groups for each class of employees having similar responsibilities. The complexity of security management increases with the number of user groups. Be sure to carefully evaluate the need before creating too many groups. To add a new user group, select GROUP EDIT from the Select SECURITY window. At the Group Name window, either type in the name of the new group or press [list] to view the existing group names in the Select, Insert, Delete User Group window. Chapter 5: Applying Security Measures 153

165 Group Name If you entered a new name at the User group prompt, the Add User Group window will appear. Select YES and press [enter]. The Group Information window will then appear for you to provide information about this user group. If you pressed [list] to view existing user groups, you may press [insert] to add a new user group. The Group Information window will appear. Add User Group Group Information User group: character (30) Each user group must be given a unique name. 154 KB_SQL Database Administrator s Guide

166 Query base routine: character (5) [list] Select a base routine prefix to be used for all M routines generated for queries by this user group. If entered, this value will override the default base routine specified in the SITE EDIT procedure. Default schema: character (30) [list] You are required to enter a default schema. This will be the schema for any unqualified table or view names in queries that are prepared (compiled) by users in this user group. All table, index, and view definitions for this user group will be stored with this schema. This schema can be overridden for a particular query by using the SET SCHEMA statement. It can be overridden for a particular table or view by using the schema_name prefix. Edit Changing a user group definition will have implications on all queries, tables, and procedures that are referenced by members of that group. Edits to group definitions should be carefully controlled and limited if possible. To edit a user group, either type the name of the user group in the Group Name window or press [list] and the Select, Insert, Delete User Group window will display the list of existing user groups. Highlight the user group you wish to edit and press [enter]. The Group Information window will appear. Select, Insert, Delete User Group Chapter 5: Applying Security Measures 155

167 Delete Any user group may be deleted, as long as no users are currently assigned to that group. To delete a user group, either type the name of the user group in the Group Name window or press [list] and the Select, Insert, Delete User Group window will display the list of existing user groups. Highlight the user group you wish to delete and press [delete]. The Group Information window will appear with the Commit? prompt below it. Type Y and press [enter] if you wish to delete this user group. Privileges As part of the process of adding or editing a user group, you may assign new privileges or view or revoke existing privileges to tables, views, and queries. After you complete the Group Information window, the Object Types window will appear. (This window will not appear if you are editing the DBA user group because the DBA has privileges to everything by default.) Object Types The Object Types window contains objects (queries, tables, and views) to which privileges are linked. When you assign privileges to these objects, you are assigning the privileges to all users in the current user group. 156 KB_SQL Database Administrator s Guide

168 Viewing/Changing Query Privileges If you select the Queries object type, you are presented with a value window in which you can specify a range of query names whose privileges you wish to view/change. If you do not specify a range of names, all the queries will be listed in the selection window. Query Names From name: character (30) Specify the name of the first query (alphabetically) whose privileges you want to view. Thru name: character (30) Specify the name of the last query (alphabetically) whose privileges you want to view. Chapter 5: Applying Security Measures 157

169 Select SQL Query The selection window lists all the queries in the specified range, and shows the status of the queries privileges. Queries can have select, update, and with_option privileges. Tables and views can have select, insert, update, delete, and with_option privileges. 158 KB_SQL Database Administrator s Guide

170 After selecting a query from the selection window, you are presented with the Current Privileges window. Current Privileges Query name: character (30) The name of the query may not be changed. Select (run)? YES/NO If you want to extend run privileges to this user group, type Y and press [enter]. Update (edit)? YES/NO If you want to extend update privileges to this user group, type Y and press [enter]. W/ option? YES/NO If you want this user group to be able to grant its privileges to other user groups, type Y and press [enter]. Chapter 5: Applying Security Measures 159

171 Viewing/Changing Table or View Privileges If you select the Tables or Views object type, you are presented with a value window in which you can specify the schema name and the range of tables (views) whose privileges you wish to view/change. If you do not specify a schema, the selection window will show all the tables (views) defined in the data dictionary that fall within the range specified. If you do not specify a range of names, the selection window will show all the tables (views) for the schema specified. Table Names Schema name: character (30) [list] Specify the name of the schema whose table(s) you want to grant privileges. You may press [list] to select from a list of schema names. From table name: character (30) Specify the name of the first table (alphabetically) to whom you want to grant privileges. Thru table name: character (30) Specify the name of the last table (alphabetically) to whom you want to grant privileges. 160 KB_SQL Database Administrator s Guide

172 The Select SQL Table window will display the tables (views) you specified in the Table Names window. To select a table (view), highlight its name and press [enter]. The Current Privileges window will appear. Select SQL Table Chapter 5: Applying Security Measures 161

173 Current Privileges Note: Tables and views can have select, insert, update, delete, and with_option privileges. Name: character (30) The name of the table may not be changed. Select? YES/NO If you want this user group to be able to select rows from the table, type Y and press [enter]. Insert? YES/NO If you want this user group to be able to insert rows into the table, type Y and press [enter]. 162 KB_SQL Database Administrator s Guide

174 Update? YES/NO If you want this user group to be able to update rows in the table, type Y and press [enter]. Delete? YES/NO If you want this user group to be able to delete rows in the table, type Y and press [enter]. W/ option? YES/NO If you want this user group to be able to grant its privileges on this table to other user groups, type Y and press [enter]. Chapter 5: Applying Security Measures 163

175 USER EDIT Option Add The USER EDIT procedure can be used to insert, update, and delete user-specific information. Use care when assigning user names and passwords. The user information will be stored throughout the system in system and transaction files to provide a security audit trail. If you have not defined any users, the Add User window will appear. Select YES to add a user. Otherwise, if users exist, the Select, Insert, Delete selection window will appear. You can press [insert] to add a new user, or select the user you wish to edit. If you want to delete a user, highlight it and press [delete]. Add a user record for each individual that is going to use KB_SQL. This provides a method of tracking activity in the system. The DBA should control the assignment of user names and passwords and keep a list of all active users. 164 KB_SQL Database Administrator s Guide

176 Edit Delete User definitions can be edited if necessary. Any changes will be reflected in future transactions executed by the user. All former transactions by the user will reflect the old values of user information. If a user was entered by mistake, that user may be deleted. All former transactions by the user will remain on file until the transaction logs are deleted. User Information User name: character (30) Each user should have a unique name. This will support the tracking mechanisms in the system. Group: character (30) [list] Each user must belong to a group. The group determines the table and query privileges for the user. This user definition will include command qualifications for the SQL commands that can be used to operate on those tables and queries. Chapter 5: Applying Security Measures 165

177 Password: character (30) Each user should have a unique password. The password should be used exclusively by the user for which it was created. KB_SQL allows user passwords to be encrypted. Encryption provides an additional level of security against unauthorized access to your database. Please contact your technical support representative for more information on this option. Password expires on: date Enter the date after which this user password will become invalid. After that date, the user will not be allowed access to the system. If nothing is entered, the password will not expire. Allow renewal after expiration? YES/NO Enter YES to let the user access the system after the current password expires and enter a new password. Enter NO if this password must be renewed by the DBA. When the user attempts to login with an expired password, a message box (shown below) will appear. If the user is allowed to renew the password, the prompts shown on the next page will appear, allowing the user to change the password, confirm the change, and save the new password. The new password is valid for the number of days specified in the Site Default s Password expire days prompt; if no value is specified in this prompt, the password is valid indefinitely. 166 KB_SQL Database Administrator s Guide

178 Change User Password New Password: character (20) Enter your new password. Confirm Password: character (20) Enter your new password again to confirm the change. If the user is not allowed to renew their password, the following message box will be displayed. When users attempt to enter the system during the days prior to the expiration of the password, they will see the following message. Users will have the opportunity to change the password at this time, if the DBA has allowed them to renew the password. Chapter 5: Applying Security Measures 167

179 EZQ only? YES/NO For non-dba users, this question determines if the user will sign on directly to the EZQ procedure. Edit queries? YES/NO Answer NO if this user can only print or run queries. Answer YES if this user has qualifications for editing queries. Programmer? YES/NO Answer YES if this user is an M programmer or has equivalent skills. The system will hide certain information from users who are not identified as programmers. Limit search: integer (6) In a multiuser environment, it is often necessary to limit the number of rows that each query will search, thus limiting the resource requirements of that query. Select: integer (6) As a report is being developed, the number of entries selected can often be limited to a single page worth of data. This allows the user to format the query without retrieving the entire query result. 168 KB_SQL Database Administrator s Guide

180 Use colors? YES/NO Answer YES if the user has a color monitor. You can customize the foreground and background colors for all of the KB_SQL windows. A sample color scheme is shown on the following page. In order for the new color scheme to take effect, the users for whom you have changed the colors must exit and restart KB_SQL. Window Colors Chapter 5: Applying Security Measures 169

181 SQL Command Qualifications The SQL command qualifications can be controlled by the DBA to ensure that users are authorized to execute only those SQL commands for which they have been certified. The DBA can perform all SQL commands. By default, users with the programmer status can manipulate the tables, but not make direct changes to the data dictionary. Also, new users are allowed to select data for viewing only. If you want to extend additional command privileges to users, you must type Y next to the appropriate command in the Command Qualifications window. Command Qualifications 170 KB_SQL Database Administrator s Guide

182 PUBLIC PRIVILEGES Option If you want all users to have access to a query, table, or view, use the PUBLIC PRIVILEGES option. When you assign public privileges, you assign the privileges to all users in all user groups. This saves you from applying the same privileges to several user groups. WARNING: Please be careful when granting PUBLIC permissions. For security reasons, we suggest that you do not grant PUBLIC permissions to the User table. If your passwords are not encrypted and you grant PUBLIC permissions to the User table, then everyone s password is public knowledge. Encrypting your passwords adds another level of security. To encrypt your password, you must be in programming mode to set the site-level encrypt flag. Please contact your software vendor or KB Systems for more information on encrypting passwords. After selecting the PUBLIC PRIVILEGES option, the Object Types window appears. Object Types Chapter 5: Applying Security Measures 171

183 The Object Types window contains objects to which privileges are linked. Select the object (query, table, or view) to which you want to assign privileges. The process of modifying public privileges is the same as the process of modifying user group privileges. Therefore, refer to the GROUP EDIT Option section for detailed instructions on this process. Note: Each user s privileges is a combination of the set of privileges that you assign to the user s user group and to the PUBLIC user. If a user s user group does not have a certain privilege, but the PUBLIC user group does have that privilege, then the user will have that privilege. 172 KB_SQL Database Administrator s Guide

184 REPORTS Option Use this procedure whenever you need to print the definitions of one or more users, user groups, members, table privileges, or query privileges. Use the Select REPORTS window to select the category of definition to be reported. Select REPORTS Chapter 5: Applying Security Measures 173

185 You can define the range of definitions included in the report by indicating beginning and ending values. The value window shown below appears when you select the GROUP PRINT option. Print User Groups After you define your range, the Print on Device window appears. Press [enter] to view the report on your monitor, or press [list] and select from the list of output devices. Print on Device 174 KB_SQL Database Administrator s Guide

186 GROUP PRINT Option This option prints all user group information for the range you specify. MEMBER PRINT Option This option prints a listing of user groups, with the members of each group, for the range you specify. QUERY PRIVILEGES Option This option prints a list of queries and the privileges allowed, including select and update, for the range you specify. TABLE PRIVILEGES Option This option prints a list of tables and its privileges, including select, insert, update, and delete, for the range you specify. PUBLIC QUERY PRIVILEGES Option This option prints a list of queries and the privileges allowed, including select and update, for the PUBLIC user group. Chapter 5: Applying Security Measures 175

187 PUBLIC TABLE PRIVILEGES Option This option prints a list of tables and the privileges specified, including select, insert, update, and delete, for the PUBLIC user group. USER PRINT Option This option prints all user information, color preferences, and SQL command qualifications for the range you specify. 176 KB_SQL Database Administrator s Guide

188 6 Utilities KB_SQL contains several utility procedures which are useful for maintaining the system. These utilities allow you to stop a query which is running in the background or on a remote device, import and export SQL objects, compile all queries, set system-wide locks, compile table statistics, and print the transaction logs. Chapter 6: Utilities 177

189 Select UTILITIES COMPILE ALL QUERIES Option Use this option whenever a system update has been completed or when you have made some significant changes to the data dictionary. If you do not respond YES to any of the prompts in the Query Compile window, all Data Manipulation Language queries (SELECT, INSERT, UPDATE, DELETE) will be compiled. The COMPILE ALL QUERIES option includes row level locking to ensure the integrity of the database. If the file to be compiled is not available, you will be given the choice either to wait for the object to become available or to skip the object. 178 KB_SQL Database Administrator s Guide

190 Query Compile Recompile only edited queries? YES/NO If you want to compile only those queries that are currently marked as edited, answer YES at this prompt. Select specific queries? YES/NO If you want to select specific queries, answer YES at this prompt. The Recompile Query window will appear. Chapter 6: Utilities 179

191 Recompile Query Query name: character (30) [list] At this window you can press [list] to view all queries and select from the list the query that you want to recompile. Or you can use the selection criteria explained on the following page. You can select as many queries as you wish. Each time you select a query or range of queries, KB_SQL will display at the bottom of the screen the number of queries selected. It will also tabulate the total number of queries and show that number in the Recompile Query window. Start recompile? YES/NO When you are ready to start the recompile process, type YES. 180 KB_SQL Database Administrator s Guide

192 Selection Criteria A multiple range of queries can be compiled in a single session. Use the standard wild card selection method outlined below. P P P Enter <query_name> to select a single query. Enter <partial match>* to select all queries that match the letters supplied. Enter <from_query_name>:<thru_query_name> to select all queries that fall within the range. In the example below, 32 queries that begin with the letters DEMO have been selected to be recompiled. Stopping the Process During each query compile, KB_SQL will display a series of messages. If you need to halt the compilation process, you may press any key. You will be given the chance to resume or end the process. Stop Recompile Chapter 6: Utilities 181

193 Messages When the process is complete, a message window displays the number of queries successfully compiled and the total compile time. Certain queries may not be compiled. For example, if the query has invalid syntax or unresolved SQL object names, it will not be compiled. A message is created for any query that cannot be compiled. You can review this list of messages by running the COMPILE QUERY LOG report (UTILITIES/TRANSACTION LOGS/COMPILE QUERY LOG). If you abort the compilation process, the queries that were not compiled are not included in the list. 182 KB_SQL Database Administrator s Guide

194 EXPORT Option The EXPORT option copies all relevant data to a host file. That file can be used for backup purposes or to update another system. After the file has been saved, it may be transferred to another system to be imported. The EXPORT option includes row level locking to ensure the integrity of the database. If the file to be exported is not available, you are given the choice to either wait for the object to become available or skip the object. When transferring to a file, the file must be undefined or you must respond YES to the Replace if exists prompt in the Output to File window. This ensures that an existing file is not overwritten. Select EXPORT Note: Other transfer methods, which you perform outside of the KB_SQL environment, are discussed in Chapter 9: Transferring Data Dictionary Objects. Chapter 6: Utilities 183

195 DEVICE TYPE, FUNCTION, and PSEUDO COLUMN Options If you select DEVICE TYPE the Export Device Types window will appear. The windows and process are similar if you select FUNCTION or PSEUDO COLUMN. Export Device Types Export device types edited after: date (mm/dd/yy) To export device types that have been edited after a particular date, enter a date value. Export all device types? YES/NO If you want to export all defined device types, type Y and press [enter]. The Output to File window will appear. If you answer NO, the Device Type Name window will appear. 184 KB_SQL Database Administrator s Guide

196 Device Type Name Device type name: character (30) [list] Supply a valid SQL object name, or press [list] and select from the list of existing device types, or use the following wild card selection method: P Enter <device_type_name> to select a single device type. P P Enter <partial match>* to select all device types that match the letters supplied. Enter <from_device_type_name>:<thru_device_type_name> to select all device types that fall within the range. After you are finished selecting your device types, press [enter] at the Device type name prompt and the cursor will fall to the Filename prompt in the Output to File window. Chapter 6: Utilities 185

197 Output to File Filename: character (60) Enter the name of the file that will receive the contents of this export. The file name must be consistent with your host system naming conventions. Replace if exists? YES/NO Answer YES is you wish to overwrite an existing file. Otherwise, answer NO. 186 KB_SQL Database Administrator s Guide

198 QUERY Option If you select the QUERY option, the Select Queries window will appear. Select Queries Select queries edited after: date (mm/dd/yy) To export queries that have been edited after a particular date, enter a date value. Select all queries? YES/NO If you want to export all defined queries, type Y and press [enter]. Otherwise, if you want to select specific queries to export, type N and press [enter]. The Select Query window will appear for you to type the query s name. Chapter 6: Utilities 187

199 Select Query Query name: character (30) [list] Supply a valid query name, or press [list] to select from a list of queries, or you can use the following wild card selection method: P P P Enter <query_name> to select a single query. Enter <partial match>* to select all queries that match the letters supplied. Enter <from_query_name>:<thru_query_name> to select all queries that fall within the range. After you are finished selecting your queries, press [enter] at the Query name prompt and the Output to File window will appear. 188 KB_SQL Database Administrator s Guide

200 Ouput to File Filename: character (60) Enter the name of the file that will receive the contents of this export. The file name must be consistent with your host system naming conventions. Replace if exists? YES/NO Answer YES if you wish to overwrite an existing file. Otherwise, answer NO. Chapter 6: Utilities 189

201 TABLE Option If you select the TABLE option, the Select Table window will appear. Select Table Select tables edited after: date (mm/dd/yy) To export tables that have been edited after a particular date, enter a date value. Schema name: character (30) [list] Specify the schema name in which the tables are defined. Select all tables? YES/NO If you want to export all defined tables, type Y and press [enter]. Otherwise, if you want to select specific tables to export, type N and press [enter]. The Select Table window will appear for you to type the table s name. 190 KB_SQL Database Administrator s Guide

202 Select Table Table name: character (30) [list] Supply a valid table name, or press [list] to select from a list of tables, or you can use the following wild card selection method: P Enter <table_name> to select a single table. P Enter <partial match>* to select all tables that match the letters supplied. P Enter <from_table_name>:<thru_table_name> to select all tables that fall within the range. After you are finished selecting your tables for that schema, press [enter]. The cursor will move to the Schema name prompt. You may select another schema (and then tables to export) or you can press [enter] and the Output to File window will appear. Chapter 6: Utilities 191

203 Output to File Filename: character (60) Enter the name of the file that will receive the contents of this export. The file name must be consistent with your host system naming conventions. Replace if exists? YES/NO Answer YES if you wish to overwrite an existing file. Otherwise, answer NO. 192 KB_SQL Database Administrator s Guide

204 HALT QUERY Option Select Task This option is available only if your system allows background tasks. Use this procedure whenever you need to stop a query which is running in the KB_SQL print spool. Halt Query will set, or reset, the halt flag for a query running in the background. The compiled query routine will check the halt flag during the searching and printing portions of the procedure. If the halt flag is set, the query will stop executing. Halt Query From the Select Task window, select the task that you want to halt. Note: P If the flag is set to YES and then reset to NO before the query checks the flag, the query will not halt. P Once a query is halted, it cannot be resumed. P The HALT QUERY procedure cannot be used to stop queries running interactively on a terminal. P To halt a query that is running on your terminal, strike any key and you will be allowed to stop the query. Chapter 6: Utilities 193

205 IMPORT Option The IMPORT option may be controlled by the DBA to allow or disallow overwrites. All imports are performed at the logical level using the object name. No two SQL objects may have the same name. If this situation occurs, the import object will be skipped unless overwrites are allowed. Each import transaction will create one or more messages that can be reviewed using the IMPORT MESSAGES PRINT procedure. The IMPORT option includes row level locking to ensure the integrity of the database. If the file to be imported is not available, you are given the choice to either wait for the object to become available or skip the object. Note: Other transfer methods, which you perform outside of the KB_SQL environment, are discussed in Chapter 9: Transferring Data Dictionary Objects. Select IMPORT 194 KB_SQL Database Administrator s Guide

206 Note: Please inform your users that if EZQ queries are imported to a system that does not have the associated source table, the user will be prompted to enter a new table name. If the system has the source table but the table has different internal numbers, the EZQ Editor will transparently resync the query to the table the first time the query is referenced by the EZQ Editor. Import TABLE Each import option will give you the ability to replace existing data with new data. Answer YES to replace any existing object with an object that is imported. Answer NO to skip the import of defined objects. When importing a table, if you answer YES to the Overwrite? prompt, the Preserve Old Statistics window will appear. Chapter 6: Utilities 195

207 Preserve Old Statistics Preserve table statistics? YES/NO This window gives you the option to keep your existing table s statistics. Answer YES to insert the statistics for the existing table into the import file. Answer NO and the statistics (if any) from the import file will be used. Host File Name Host file name: character (60) Specify the file name where the data is stored. 196 KB_SQL Database Administrator s Guide

208 JOB WATCH Option This procedure allows you to see which users are running in KB_SQL. As DBA, you can choose to terminate a user process. This procedure is also useful to clear processes that remain after an uncontrolled abort. For example, if a user performs a system reboot without exiting KB_SQL, the JOB WATCH might think that the user is still working. Select, Delete SQL User Job As DBA, your job will always show as if you are running in the JOB WATCH procedure. You can select any other entry from the selection window to indicate that you want to delete the job. The Delete Job window will appear. After you delete the job, information about the job will be removed from KB_SQL. If you delete a job, the next time the job checks its status, it will recognize that it has been removed, and gracefully exit. Note: This is not the same as removing an M process. Only the information pertinent to KB_SQL is removed. Also, if the job that you want to remove does not appear in the job watch window, you can use the UNDO^SQL entry point (see Chapter 11) to clear the job from the system. Chapter 6: Utilities 197

209 LOCK STATUS Option The SYSLOCK^SQL routine can be accessed from the DBA UTILITIES menu by selecting the LOCK STATUS Option. The Select System-Wide Lock window then appears from which you can view the status of the locks and select a lock to set. Select System-Wide Lock Highlight the lock you wish to set and press [enter]. The Lock Status window will appear. BACKGROUND QUEUE Option Set to YES to restrict the use of the background task manager. COMPILE QUERIES Option Set to YES to restrict the use of the UTILITIES/COMPILE ALL QUERIES option. 198 KB_SQL Database Administrator s Guide

210 DICTIONARY LOCK Option DICTIONARY LOCK is automatically set to YES when someone is accessing the GROUP EDIT or the PUBLIC PRIVILEGES option of the DBA s Security menu. DICTIONARY LOCK is also automatically set to YES when either a CREATE, ALTER, DROP, GRANT, or REVOKE statement is being executed. You can use the SYSLOCK^SQL routine to reset DICTIONARY LOCK to NO in the event of a network failure. You can also use SYSLOCK^SQL to determine whose activity has caused the lock to be set to YES. STATISTICS Option Set to YES to restrict the use of the UTILITIES/COMPILE STATISTICS option. SYSTEM Option Set to YES to keep all users off the system. This is useful when you need to perform system upgrades. If set to YES no one can sign on to KB_SQL. You cannot reset the system lock using this option. You must use the SYSLOCK^SQL routine. USER Option Set to YES to restrict the USERS user group from access to KB_SQL. Chapter 6: Utilities 199

211 Lock Status Locked? YES/NO To lock, type YES; to unlock, type NO. Reason: character (60) Enter a reason for setting the lock. 200 KB_SQL Database Administrator s Guide

212 Calculating Table Statistics The KB_SQL query access planner uses statistical information about tables to determine the best path for each SQL request. The most basic statistic is the average number of entries for a primary key. This number is used in a calculation that determines the overall cost of traversing a particular table. There are four ways of defining the table statistics: in the Primary Key definition, using the DEFAULT STATISTICS routine, using the COMPILE STATISTICS option, or using the MANUAL STATISTICS option. The last two options are selected from the UTILITIES/STATISTICS menu. You may choose to use one or more of these methods to provide table statistics for use by the KB_SQL query access planner. It is not as important which method is chosen as it is to understand the various options and when to use them. The query access planner will produce efficient queries if the table statistics are accurate. Using the PRIMARY KEY Definition The PRIMARY KEY definition component of the MAP GLOBALS procedure lets you enter the average number of values for that key. This method allows the entry of numeric as well as fuzzy values. It produces statistics of the same accuracy as the MANUAL STATISTICS procedure. Using the DEFAULT STATISTICS Routine The DEFAULT STATISTICS routine [SQL0FS] lets you generate default statistics based on estimates of the approximate size of tables. Given an approximate total entries value (10,000 to 100,000,000) and the number of primary keys (n), this utility will assign each primary key an equivalent number of values based on the (n)th root of the total. Chapter 6: Utilities 201

213 This method lets you generate approximate statistics for a specified table (or tables) without a detailed understanding of the database. Using the COMPILE STATISTICS Option The COMPILE STATISTICS option will generate accurate numbers by actually traversing a specified table (or tables) and counting the number of values defined. This method produces the best statistics for a single environment. You must consider the value of having accurate statistics against the resources required to generate the numbers. The COMPILE STATISTICS option includes row level locking to ensure the integrity of the database. If the file to be compiled is not available, you will be given the choice either to wait for the object to become available or to skip the object. Using the MANUAL STATISTICS Option The MANUAL STATISTICS option lets you input the average number of entries for each primary key of a specified table (or tables). This method allows the entry of numeric as well as fuzzy values. It produces statistics that are approximations based on your knowledge of the volume and distribution of data in your tables. The MANUAL STATISTICS option includes row level locking to ensure the integrity of the database. If the file to be compiled is not available, you will be given the choice either to wait for the object to become available or to skip the object. 202 KB_SQL Database Administrator s Guide

214 STATISTICS Option Use this procedure whenever you need to calculate accurate statistics, or manually set statistics, for one or more tables in the database. (See the discussion on the previous pages about choosing the best method for calculating statistics.) The database statistics that specify the distribution of data are used by the query optimizer to calculate an efficient access strategy for your queries. Consistent and accurate statistics can help to ensure the effective calculation of access plans by the query optimizer. The STATISTICS option offers two methods for collection of the necessary statistics: an automatic compile method (COMPILE STATISTICS) and a manual entry method (MANUAL STATISTICS). Select STATISTICS Chapter 6: Utilities 203

215 COMPILE STATISTICS Option The COMPILE STATISTICS procedure calculates the total number of rows in a table, plus the average number of entries for each primary key of a table. This information is used during the query planning process to determine the most efficient access strategy. It is very important to provide accurate statistics for the query planner. The more accurate the numbers are, the more effective the planner will be in determining how to execute your queries. Compile Statistics Sample size: integer (10) When you need to calculate statistics on a large table with a primary key that consists of more than one column and you do not want to do a complete run due to time or processing constraints, you can hasten the process by supplying a sample size (number of rows). The statistics procedure will calculate statistics for the sample size and compute statistics for the entire table based on the statistics of the sample size. Using a sample size is not as accurate as scanning the entire table, but it is a savings in processing time. We recommend a sample size of at least Special options? YES/NO Several special options can be used to customize the compile statistics procedure. Enter YES if you would like the Special Options window to appear. Schema name: character (30) [list] 204 KB_SQL Database Administrator s Guide

216 Enter a schema name or press [list] to view a list of all defined schemas. Compile all tables? YES/NO If you want to compile all tables in the schema, type Y and press [enter]. Otherwise, if you want to select specific tables to compile, type N and press [enter]. A window will appear for you to type the table s name or you may press [list] to view a list of tables. Special Options Compile only tables in use by queries? YES/NO Enter YES to limit the calculation to those tables that have been referenced by queries. Compile only tables without statistics? YES/NO Enter YES to limit the calculation to those tables that have never had statistics compiled. Compile tables with statistics older than: date (mm/dd/yy) Limit the calculation to those tables that have not had statistics compiled since a specified date. The COMPILE STATISTICS procedure displays the name of the table for which statistics are being compiled. When the procedure finishes, a message window displays the number of tables for which statistics were Chapter 6: Utilities 205

217 successfully compiled. You can then run the COMPILE STATISTICS LOG report (UTILITIES/TRANSACTION LOGS/COMPILE STATISTICS LOG) for a summary of the actions performed by the procedure. FUZZY DENSITY EDIT Option Each table can be assigned a density factor. This factor is used by the query optimizer as a tiebreaker between tables with similar access cost values. The density factor is related to how many rows of the table are packed into an average global block. Assuming that a densely packed index structure is more efficiently traversed than a sparse base table, you may choose to create a bias towards using the index. For fuzzy density values a large number means that the table is densely packed and is a good access path. If you have not defined any fuzzy densities, the Add window will appear. Select YES to add a fuzzy density. Otherwise, if they do exist, the Select, Insert, Delete selection window will appear. You can press [insert] to add a new fuzzy density, or select the fuzzy density you wish to edit. If you want to delete an entry, highlight it and press [delete]. 206 KB_SQL Database Administrator s Guide

218 Select, Insert, Delete Fuzzy Density Fuzzy Density Information Name: character (10) Supply a name for logical reference to the fuzzy density value. Description: character (60) Supply a description that will identify this entry. Density: integer (10) Enter a numeric value that represents the average number of rows per physical M data block for this fuzzy density value. Chapter 6: Utilities 207

219 FUZZY SIZE EDIT Option Give a name to a number that represents the relative size of a table. For fuzzy size values, a large number translates into a high cost for the table during the query access path planning process. If you have not defined any fuzzy sizes, the Add window will appear. Select YES to add a fuzzy size. Otherwise, if they do exist, the Select, Insert, Delete selection window will appear. You can press [insert] to add a new fuzzy size, or select the fuzzy size you wish to edit. If you want to delete an entry, highlight it and press [delete]. Select, Insert, Delete Fuzzy Size 208 KB_SQL Database Administrator s Guide

220 Fuzzy Size Information Name: character (10) Supply a name for logical reference to the fuzzy size value. Description: character (60) Supply a description that will identify this entry. Size: integer (10) Enter a numeric value that represents the average number of distinct values for the first primary key which is equal to the number of primary key values in the table. Chapter 6: Utilities 209

221 MANUAL STATISTICS Option This procedure allows you to enter approximate values for the table density and the average number of distinct entries of each primary key in a table. The system accepts numeric input or key words such as small, medium, and large, as site-defined approximate statistics. These fuzzy values can help ensure consistent classifications of your tables while reducing the errors caused by data entry. Manual Table Statistics Table density: character (10) list You may enter a numeric or a fuzzy density value. Avg distinct: character (10) list You may enter a numeric or a fuzzy size value. 210 KB_SQL Database Administrator s Guide

222 REPORTS Option The system includes several reports that may be useful to you in managing KB_SQL. Select REPORTS You can define the range for the Query Directory and Query Print reports by indicating beginning and ending values. After you define your range, the Print on Device window appears. Press [enter] to view the report on your monitor, or press [list] and select from the list of output devices. Chapter 6: Utilities 211

223 FUZZY DENSITY PRINT Option This report produces a list of all fuzzy density values in name order. FUZZY SIZE PRINT Option This report produces a list of all fuzzy size values in name order. INTEGRITY CHECK ERRORS Option This report lists the errors from the last integrity check. QUERY DIRECTORY Option This report produces a list of query names that match a user-specified range. QUERY PRINT Option This report produces a list of query definitions for query names that match a user-specified range. 212 KB_SQL Database Administrator s Guide

224 TRANSACTION LOGS Option A transaction log is maintained by KB_SQL for all import, query, table, and view transactions. You can use the TRANSACTION LOGS option to print the information in the log files. This information is provided as an audit trail of user transactions. Select TRANSACTION LOGS COMPILE QUERY LOG Option This report produces a summary of the actions performed by the COMPILE ALL QUERIES procedure (DBA Options/ UTILITIES/COMPILE ALL QUERIES). The following message types may be included: Query translation error, Query translation message, Query modifies data dictionary. COMPILE STATISTICS LOG Option This report produces a summary of the actions performed by the COMPILE STATISTICS procedure (DBA Options/ UTILITIES/STATISTICS). Chapter 6: Utilities 213

225 ERROR LOG PRINT Option This report produces a list of all KB_SQL errors that have occurred in a user-specified date range. IMPORT TRANSACTIONS Option This report produces a listing of all import transactions for a user-specified date range. A sample of import messages is included. P <object> imported P <object> imported and overwritten P <object> not imported (reason) QUERY TRANSACTIONS Option This report produces a listing of all query transactions for a user-specified date range. The following data is included on the report: P date, time, user P query name P type (CREATE, ALTER, COMPILE, RUN, DROP) P total processing time P number of records searched P number of records selected 214 KB_SQL Database Administrator s Guide

226 TABLE TRANSACTIONS Option This report produces a listing of all table transactions for a user-specified date range. The following data is included on the report: P date, time, user P table name P type (CREATE, ALTER, DROP) VIEW TRANSACTIONS Option This report produces a listing of all view transactions for a user-specified date range. The following data is included on the report: P date, time, user P view name P type (CREATE, ALTER, DROP) Chapter 6: Utilities 215

227 216 KB_SQL Database Administrator s Guide

228 7 System Status T he SYSTEM STATUS option shows a summary of the current status of the system. When you select this option, the System Status window appears which gives you a summary of your system s activities. 217 KB_SQL Database Administrator s Guide

229 System Status If you answer YES to the Examine system status prompt, the System Status Options menu appears. System Status Options 218 KB_SQL Database Administrator s Guide

230 Connections Displays active server connections. Query Queue Lists those queries that are in the background execute queue. Statistics Queue Displays table statistics queue. Exceptions Displays hard M errors. Locks Displays system lock status. Query Transactions Displays query transaction summary. Table Transactions Displays table and view transaction summary. 219 KB_SQL Database Administrator s Guide

231 220 KB_SQL Database Administrator s Guide

232 8 KB_SQL s Version Information The VERSION INFORMATION option provides you with site-specific information about your version of KB_SQL. When you select this option, the KB_SQL Version Information window appears. The pr ompt values are supplied by KB Systems. 221 KB_SQL Database Administrator s Guide

233 KB_SQL Version Information The build number is the release number of this version. It confirms that you have received the final release and not a prerelease of this version. 222 KB_SQL Database Administrator s Guide

234 KB_SQL can transfer several types of data dictionary objects. This allows you to coordinate the development of the system among multiple sites. The export procedures can transfer tables, table statistics, queries, device types, functions, and pseudo columns. The export files use a standard format regardless of M implementation or hardware platform. This allows data to be transferred in a mixed environment. This chapter discusses programmatic transfer methods. Transfer methods available through the KB_SQL user interface are discussed in Chapter 6: Utilities. Chapter 9: Transferring Data Dictionary Objects 223

235 Transfer Objects and Methods The following objects can be exported from KB_SQL using any of the transfer methods listed below. Object Function Table Query Pseudo column Device type Stats # Description Transfer user-defined functions Transfer schema and table definitions including all table indexes, columns, primary keys, foreign keys, domains, output formats, and key formats that are referenced by the table Transfer SQL statements (no EZQ data) Transfer pseudo column definitions Transfer device type definitions and device function routines Transfer table distribution statistics 224 KB_SQL Database Administrator s Guide

236 Transfer Methods KB_SQL provides the following transfer methods. Choose the most appropriate transfer method for your software environment. TO_UCI Method TO_FILE FROM_FILE TO_GLOBAL FROM_GLOBAL FROM_GLOBAL _MULTI # Description Export object definitions to a host file Import object definitions from host file Export object definitions to global Import object definitions from global Export object definitions across data sets Import object definitions from global using multiple steps Chapter 9: Transferring Data Dictionary Objects 225

237 Transfer Combinations The following objects can be transferred using the indicated methods. Object File Global UCI TO FROM TO FROM MULTI Function x x x x x Table x x x x x (1) x Query x x x x x Pseudo column x x x x x Device type x x Stats x x (1) Multiple sets of table definitions can be transferred using the multi-load option. After the intermediate transfers are completed, you must use the transfer method FROM_GLOBAL_MULTI to cleanup and finalize the operation. 226 KB_SQL Database Administrator s Guide

238 The Transfer Utility All transfers done from outside of the KB_SQL environment require you to define certain variables and to invoke the XFER^SQL program entry point. The transfer utility will perform the requested action, using the following temporary variables and globals. Variable SQLDTYPE SQLERR SQLFILE SQLJOB SQLML SQLOW SQLSA SQLTITLE SQLUCI SQLUCIB SQLUCIC SQLUCIL SQLUCIL(#) SQLUSER SQLXTM SQLXTO Globals ^SQLEX ^SQLIX Description Current device type Error message (if defined) Complete filename Process identifier ($JOB) Multi-load flag (for table import only) Overwrite flag (1=overwrite, 0=skip) Save all (1=all, 0 = use ^SQLEX list) Description for import message table (char 60) Data set (UCI) name Transfer from data set (UCI) Executable code to change data set (UCI) # of UCI/ID s to transfer into Data set (UCI) name User s password Transfer method Transfer object Temporary global for list of export objects Temporary global for import image Chapter 9: Transferring Data Dictionary Objects 227

239 Transfer Examples The transfer utility is designed to allow you to integrate the transfer of KB_SQL object definitions into an existing strategy for software distribution. Consider the following examples. Example #1: Exporting Tables to a File This example shows how to transfer all demonstration tables in the SQL_TEST schema to a host file. ; Export DEMO tables K S SQLUSER="SHARK" D INI^SQL I $D(SQLERR) W!,SQLERR Q S SQLFILE="C:\TEMP\TEST.DD" S SQLSA="" S SQLXTO="TABLE" S SQLXTM="TO_FILE" K ^SQLEX(SQL(1),"TABLE") ; get schema id S K3=$O(^SQL(3,-1,"SQL_TEST",0)) ; get tables S K4=0 F S K4=$O(^SQL(4,-3,K3,K4)) Q:'K4 DO. S ^SQLEX(SQL(1),"TABLE",K4)="" D XFER^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q 228 KB_SQL Database Administrator s Guide

240 Example #2: Exporting Query Definitions to a File This example shows how to transfer all of the demonstration queries to a host file. ; Export DEMO queries to file K S SQLUSER="SHARK" D INI^SQL I $D(SQLERR) W!,SQLERR Q S SQLSA="" K ^SQLEX(SQL(1),"QUERY") S A="DEMO" F S A=$O(^SQL(155,-1,A)) Q:A'?1"DEMO".E DO. S K155=$O(^(A,0)). S ^SQLEX(SQL(1),"QUERY",K155)="" S SQLXTO="QUERY" S SQLXTM="TO_FILE" S SQLFILE="C:\TEMP\TEST.Q" D XFER^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q Chapter 9: Transferring Data Dictionary Objects 229

241 Example #3: Importing Tables From a File This example imports table definitions from a host file. ; Import DEMO tables from file K S SQLUSER="SHARK" D INI^SQL I $D(SQLERR) W!,SQLERR Q S SQLOW="" S SQLXTO="TABLE" S SQLXTM="FROM_FILE" S SQLFILE="C:\TEMP\TEST.DD" D XFER^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q Example #4: Importing Queries From a File This example imports query definitions from a host file. ; Import DEMO queries from file K S SQLUSER="SHARK" D INI^SQL I $D(SQLERR) W!,SQLERR Q S SQLOW="" S SQLXTO="QUERY" S SQLXTM="FROM_FILE" S SQLFILE="C:\TEMP\TEST.Q" D XFER^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q 230 KB_SQL Database Administrator s Guide

242 This chapter is intended for those with M programming experience. It discusses a variety of methods, external to the KB_SQL interfaces, for performing KB_SQL query and table functions, including: P P P P P P P P P Running a query routine with the KB_SQL device selection interface. Running a query routine without the KB_SQL device selection interface but with KB_SQL device control. Running a query routine without either the KB_SQL device selection interface or the KB_SQL device control. Compiling an array of SQL statements into an M routine. Saving an array of SQL statements as a KB_SQL query. Compiling a KB_SQL query. Deleting a KB_SQL query. Compiling a set of queries. Compiling statistics for a set of tables. Chapter 10: External Interfaces 231

243 Running Compiled Query Routines Generally, you will use one of KB_SQL s standard user interfaces (the SQL Editor or EZQ Editor) to build and execute your query. In some situations, you may want to execute a query routine directly, or through another interface like your own application s menu. This section discusses three alternate external methods that KB_SQL provides for running compiled queries. Once a query has been compiled into a set of M routines, those routines are an independent unit. After you define a few environment variables, the routine can be called directly from your application. You can set up a subroutine to call compiled KB_SQL reports from your current application menu system. The required input variables vary depending on how you select an output device. The output includes the following variables: Variable SQLERR SQLSEA SQLSEL SQLPAGE Description Error message (if defined) Number of rows searched Number of rows selected Number of pages output Variable SQLUSER SQLCODE User password Returns status information Description 232 KB_SQL Database Administrator s Guide

244 The DDLI interface requires that you supply the following variables: Chapter 10: External Interfaces 233

245 Using RUN^SQL The RUN^SQL entry point lets you run compiled queries external to the KB_SQL interface, but has KB_SQL taking responsibility for device control, prompting for device selection, and prompting for user input. The routine below runs the query DEMO_SELECT_ALL. The Print on Device window will appear for the user to supply the output s destination. Instead of hard coding the values as in the example below, you could make this routine more useful by passing in variables for the query name, device type, and password. A complete table of input and output variables is listed below the program. ; Run query using standard device selection K S SQLQNAME="DEMO_SELECT_ALL" S SQLDTYPE="VT220" S SQLUSER="USER" D RUN^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q Variable SQLDTYPE SQLJOB SQLQNAME SQLQUERY SQLUSER Description Device type name Process ID Query name Query ID User password Example VT220 $JOB DEMO_SELECT_ALL Query internal ID USER Note: You can use the query name or the query id, whichever is easier for your interface. 234 KB_SQL Database Administrator s Guide

246 Using RUNQ^SQL The RUNQ^SQL entry point provides a non-interactive interface for running compiled queries. It uses KB_SQL s device controls but lets you supply the device selection. Rules The SQLUSER and SQLQNAME variables are required. The SQLDEV variable is either a logical device name or zero (0) by convention for the current device. You must supply SQLDTYPE as the interactive device type. If desired, you can provide SQLDTYP2 as a subtype. If SQLDEV is non-zero, it is expected to be a defined logical device. From that definition, KB_SQL can determine the base device type. Examples In this example, SQLDEV is the logical device name or '0' (for current device). SQLDTYPE is the interactive device type. SQLDTYP2 is the subtype of SQLDEV. S SQLUSER="SHARK" S SQLDTYPE="MSM_VT200" S SQLQNAME="DEMO_SELECT_ALL" S SQLDEV="PRINTER_HPIIP" S SQLDTYP2="PORTRAIT_COMPRESSED" D RUNQ^SQL I $D(SQLERR) W!,*7,SQLERR Chapter 10: External Interfaces 235

247 This example runs a query with output directed to the screen. Because the value for SQLDEV is zero, SQLDTYPE is used to supply the device type and SQLDTYP2 is used to supply the subtype. S SQLUSER="SHARK" S SQLQNAME="DEMO_SELECT_ALL" S SQLDEV="0" S SQLDTYPE="VT220" S SQLDTYP2="132_COLUMN" D RUNQ^SQL I $D(SQLERR) W!,*7,SQLERR 236 KB_SQL Database Administrator s Guide

248 Using Your Own Device Selection and Device Control You can call a compiled query directly without using either KB_SQL s device control or device selection. This method is ideal for running production reports from your menu system. Because KB_SQL does not prompt you for any information, you must supply all information that is required by the query to run including device management and required input variables, and some or all of the following variables. Variable JOB KDATE KTIME SQLFILE SQLTO Description Background job ID Run date (external) Run time (external) Output to filename Read time out (seconds) Example JOB_ID or "NO SPOOL" "03/30/61" "9:00 AM" host filename 600 = 10 minutes Rules KDATE, KTIME, SQLTO are required variables. Output to file requires SQLFILE with full host file name. Output using background job requires the variable JOB as either a valid JOB_ID from ^SQL(216), or "NO SPOOL", or 0 (zero). Chapter 10: External Interfaces 237

249 Saving SQL Statements as a Query This feature, which uses the SAVE^SQL entry point, allows you to use an alternative user interface to generate SQL statements, and then save them as a KB_SQL query. ; sample routine to compile SQL statements ; into routines K D INI^SQL K ^SQLIN(SQL(1)) S INPUT=2 S ^SQLIN(SQL(1),1)="select name, salary" S ^SQLIN(SQL(1),2)="from employees" ; Query name S SQLQNAME="TEMP_QUERY" ; Query description comment S SQLQDESC="Example query" D SAVE^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q The example above uses the query name TEMP_QUERY. You should use query names that do not conflict with other query names in your environment. Note: This method ONLY creates the query definition the query definition is not compiled. Chapter 10: External Interfaces 241

250 Compiling a Query Definition This feature, which uses the COMPILE^SQL entry point, allows you to use an alternative user interface to compile an existing KB_SQL query. The following example compiles the query named TEMP_QUERY. It returns the routine name in the variable SQLRTN. ; Compile a stored query definition K D INI^SQL S SQLQNAME="TEMP_QUERY" D COMPILE^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q 242 KB_SQL Database Administrator s Guide

251 Deleting a Query Definition This feature, which uses the DELETE^SQL entry point, allows you to use an alternative user interface to delete a stored query definition. This example deletes the query named TEMP_QUERY. ; Delete a stored query definition K D INI^SQL S SQLQNAME="TEMP_QUERY" D DELETE^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q Chapter 10: External Interfaces 243

252 Compiling a Set of Query Definitions The standard interface to the query compile option is the UTILITIES\COMPILE ALL QUERIES menu option. If you want an alternate method to compile queries, use the BC^SQL entry point. It includes row level locking to ensure the integrity of the database. If the system encounters a lock failure, the system will wait for the object to become available. This example compiles all of the demonstration queries. ; Compile a set of queries K D INI^SQL S SQLXCT="QUERIES" S SQLRC=0 S SQLRE=0 K ^SQLEX(SQL(1),"QUERY") S A="DEMO" F S A=$O(^SQL(155,-1,A)) Q:A'?1"DEMO".E DO. S K155=$O(^(A,0)). S QN=$P(^SQL(155,K155,1),"~",2). S ^SQLEX(SQL(1),"QUERY",QN,K155)="" D BC^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q Special options can be controlled by setting the following control variables. Variable SQLRE SQLRC Description Compile only edited queries Compile ALL queries Example S SQLRE=1 S SQLRC=1 244 KB_SQL Database Administrator s Guide

253 Compiling Statistics for a Set of Tables The standard interface to the compile statistics option is the UTILITIES\STATISTICS\COMPILE STATISTICS menu option. If you want an alternate method for performing compile statistics, use the BC^SQL entry point. It includes row level locking to ensure the integrity of the database. If the system encounters a lock failure, the system will wait for the object to become available. This example compiles statistics for all tables in the SQL_TEST schema. ; Compile statistics for a set of tables K D INI^SQL S SQLXCT="STATISTICS" S SQLSS=0 ; get schema id S K3=$O(^SQL(3,-1,"SQL_TEST",0)) ; get tables S K4=0 F S K4=$O(^SQL(4,-3,K3,K4)) Q:'K4 DO. S TN=^SQL(4,K4,2). S ^SQLEX(SQL(1),"TABLE",TN,K4)="" D BC^SQL I $D(SQLERR) W!,SQLERR D END^SQL Q Special options can be controlled by setting the following control variable. Variable SQLSS Sample Size Description Example S SQLSS=1000 Chapter 10: External Interfaces 245

254 11 Miscellaneous Interfaces This section illustrates some of the internal routines used by the KB_SQL product. Illustrations are provided so that you can understand how the system works. IMPORTANT: These routines are part of the KB_SQL product and can be changed at our discretion from one release to another. The following routines are illustrated: P P P P P P P P P SQL SQL0H SQL0CHK SQL0DT SQL0FC SQL0GI SQL0RI SQL0TM SQL0TS These illustrations can be most useful when building user functions, and building custom output formats based on DATE, TIME, or MOMENT (time stamp) data type values. The following examples and discussions expect that you have M programming experience. 246 KB_SQL Database Administrator s Guide

255 The SQL Routine The SQL routine is central to the operation of KB_SQL. The routine includes entry points that are referenced internally as well as directly by you. Most of these entry points require that you set the user and device type variables (SQLUSER and SQLDTYPE). Entry Point ^SQL BC^SQL COMP^SQL COMPILE^SQL DELETE^SQL DNAME^SQL DTYPE^SQL EM^SQL END^SQL EP^SQL ER^SQL INI^SQL NOTRAP^SQL RESET^SQL RQM^SQL Description The starting point for KB_SQL Performs compile statistics or recompiles queries (See example in Chapter 10.) Compiles an array of SQL text into an M routine (See example in Chapter 10.) Compiles an existing KB_SQL query (See example in Chapter 10.) Deletes an existing KB_SQL query (See example in Chapter 10.) Views/edits logical device names Views/edits device type definitions Displays error message in box Drops all process information (See example in Chapter 10.) (Also, see INI^SQL.) Starts embedded program manager menu Displays error message on last line of window Defines process-specific information (See example in Chapter 10.) (Also, see END^SQL.) Starts menu system with error trapping disabled Rolls back all incomplete transactions (All users must be off the KB_SQL system.) Restarts the Queue Manager Chapter 11: Miscellaneous Interfaces 247

256 Entry Point RUN^SQL RUNQ^SQL SAVE^SQL SQLJOB^SQL START^SQL STOP^SQL SYSLOCK^SQL UNDO^SQL XFER^SQL Description Runs a query from outside the KB_SQL environment (See example in Chapter 10.) Provides a non-interactive interface for running compiled queries (See example in Chapter 10.) Saves an array of SQL text into a KB_SQL query (See example in Chapter 10.) Sets the process id variable (SQLJOB) Starts the system, including background functions. Stops the system, including background functions. Views/edits the status of system locks (See Chapter 6: Utilities.) Rolls back a single transaction (See Chapter 6: Utilities.) Transfer utility entry point. Passes in variables to specify transfer object and transfer method (See Chapter 9: Transferring Data Dictionary Objects.) 248 KB_SQL Database Administrator s Guide

257 SQL Entry Points ^SQL This entry point is used to start KB_SQL. The same entry point can be used from direct mode or from within a menu system. > D ^SQL If you are calling KB_SQL from a menu system, you should preserve your required variables. Refer to the SITE EDIT option in Chapter 3 for instructions on how to preserve variables for reference within KB_SQL. BC^SQL This entry point is used to perform compile statistics or to recompile queries. It includes row level locking to ensure the integrity of the database. If the system encounters a lock failure, the system will wait for the object to become available. COMP^SQL This entry point is used to compile an array of SQL commands into an executable M routine. Once compiled, the routine can be invoked just like any other M routine. COMPILE^SQL Chapter 11: Miscellaneous Interfaces 249

258 This entry point is used to compile an existing KB_SQL query. DELETE^SQL This entry point is used to delete an existing KB_SQL query. DNAME^SQL When there are no working device types on the system, you can use this tag to define a logical device name. Otherwise, we recommend using the LOGICAL DEVICE EDIT procedure (Refer to Chapter 4). DTYPE^SQL When there are no working device types on the system, you can use this tag to define a device type. Otherwise, we recommend using the DEVICE TYPE EDIT procedure (Refer to Chapter 4). ER^SQL This entry point can be used to convert a numeric error code to the corresponding message text. NOTRAP^SQL 250 KB_SQL Database Administrator s Guide

259 This entry point can be used to start KB_SQL without error trapping logic. It is useful in situations where details of an M error are hidden by KB_SQL error traps; use this entry point to get more details about the error. For example, use this entry point if you want to see the variables in the symbol table at the time the error occurred. > K > D NOTRAP^SQL RESET^SQL ****** IMPORTANT EXTERNAL ROUTINE ****** KB_SQL maintains a transaction log for all activities. If the M system crashes, or is shut down unexpectedly, transactions can be left in an incomplete state. To ensure that there are no incomplete transactions in KB_SQL, you can run the RESET^SQL procedure. Query and table entries will remain locked until cleared by running this procedure. Before running reset, you should be sure that no other users are actively using KB_SQL. Otherwise, the reset procedure will roll back the transactions in progress. > K > S SQLUSER="SHARK",SQLDTYPE="ROLL_UP" > D RESET^SQL > I $D(SQLERR) W $C(7),!,SQLERR > Q Chapter 11: Miscellaneous Interfaces 251

260 RQM^SQL This entry point can be used to restart the queue manager. If you suspect that the background queue manager is not active, you can invoke this entry point. > K > S SQLUSER="SHARK",SQLDTYPE="ROLL_UP" > D RQM^SQL > I $D(SQLERR) W $C(7),!,SQLERR > Q Note: We suggest that you add the RESET^SQL and RQM^SQL routines to your Initial Program Load (IPL) logic. Every time you reboot your system, these entry points can be called to roll back any incomplete transactions and to restart the queue manager if necessary. RUN^SQL This entry point can be used to run an existing KB_SQL query. It supports prompting for input values through the READ command. RUNQ^SQL This entry point can be used to run an existing KB_SQL query. It uses KB_SQL s device controls, but lets you supply the device selection. SAVE^SQL This entry point can be used to save an array of SQL commands as a KB_SQL query. See also COMP^SQL. 252 KB_SQL Database Administrator s Guide

261 SQLJOB^SQL This entry point sets up the process variable SQLJOB, which is expected to be a unique job identifier. > D SQLJOB^SQL START^SQL This entry point starts the system. It initiates background functions such as table statistics compile and the background queue manager. > D START^SQL STOP^SQL This entry point shuts down the system. The system lock is set on to keep all users off the system. If a query is running in background, it will continue to completion. (You will need to use the UTILITIES/HALT QUERY option to terminate the query.) > D STOP^SQL Chapter 11: Miscellaneous Interfaces 253

262 SYSLOCK^SQL ****** IMPORTANT EXTERNAL ROUTINE ****** This entry point can be used to view and edit the status of the system locks. > K > S SQLUSER="SHARK",SQLDTYPE="ROLL_UP" > D SYSLOCK^SQL > I $D(SQLERR) W $C(7),!,SQLERR > Q For an explanation of each lock and how to edit them, refer to the LOCK STATUS option. XFER^SQL Use this entry point to initiate a transfer of a KB_SQL object. Object types include tables, queries, device types, pseudo columns, and functions. This entry point includes row level locking to ensure the integrity of the database. If the system encounters a lock failure, the system will wait for the object to become available For more information on transferring data dictionary objects, refer to Chapter KB_SQL Database Administrator s Guide

263 The SQL0H Routine The SQL0H routine includes several functions that are executed differently depending on the implementation of M. Information on these entry points is provided here in case you need to use these functions as part of your KB_SQL system. Tag in Routine CLOSE^SQL0H IL^SQL0H IUL^SQL0H JOB^SQL0H LC^SQL0H OPEN^SQL0H READ^SQL0H RS^SQL0H TRAP^SQL0H UC^SQL0H Description Close host file Incremental lock of global reference Incremental unlock of global reference Start a background job Lowercase conversion Open host file for write Open host file for read Reverse sort for character values Error trap Uppercase conversion Chapter 11: Miscellaneous Interfaces 255

264 SQL0H Entry Points These entry points fall into four basic categories: host file I/O, row locking, query tools, and system tools. Host File I/O Entry points are provided to OPEN a new file, READ an existing file, and to CLOSE a file. These entry points are used internally by the system. The SQL0RI (routine import) routine is a good example of how the READ and CLOSE entry points are used. CLOSE^SQL0H This entry point will close a host file port using the SQLFPORT variable. The SQLFPORT variable is defined by either the READ or OPEN entry point. > D CLOSE^SQL0H OPEN^SQL0H > S SQLFILE="A:DEMO.Q" > D OPEN^SQL0H > I $D(SQLERR) W $C(7),!,SQLERR > Q READ^SQL0H > S SQLFILE="A:DEMO.Q" > D READ^SQL0H > I $D(SQLERR) W $C(7),!,SQLERR > Q 256 KB_SQL Database Administrator s Guide

265 Row Locking Entry points are provided to perform incremental and non-incremental locking. The LOCK and UNLOCK entry points are used for adding and deleting single-threaded locks. The IL and IUL entry points are used for adding and deleting multi-threaded locks. IL^SQL0H This entry point performs an incremental lock. The variable GBL contains a valid global reference. If desired, the variable GBL(1) can be used to specify the number of seconds to attempt the lock. The variable FAIL will be set to true (1) if the lock is unsuccessful. The following example attempts to lock the column table using ^SQL(7). > S GBL="^SQL(7)" > D IL^SQL0H > I $D(SQLERR) W $C(7),!,SQLERR IUL^SQL0H This entry point is complementary to the IL^SQL0H entry point. It will incrementally unlock a global reference. This example unlocks the column table. > S GBL="^SQL(7)" > D IUL^SQL0H > Q Chapter 11: Miscellaneous Interfaces 257

266 Query Tools Several entry points are included to perform tasks required by queries. For example, the RS, LC, and UC entry points are used for reverse sorting, and for formatting character strings in lower or uppercase. LC^SQL0H This entry point can be called to convert a value to lowercase. > S ONE="THIS IS A TEST" > D LC^SQL0H > ; TWO="this is a test" > Q RS^SQL0H This entry point can be called to convert a string into a value that will sort in reverse order. > S ONE="ABCDE" > D RS^SQL0H > ; TWO="?????" to collate in reverse UC^SQL0H This entry point can be called to convert a value to uppercase. > S ONE="this is a test" > D UC^SQL0H > ; TWO="THIS IS A TEST" > Q 258 KB_SQL Database Administrator s Guide

267 System Tools The remaining tools are used throughout KB_SQL. JOB^SQL0H This entry point will start a background job using the variable RTN. In the following example, a background job will be started at tag GO of the XYZ routine. > S RTN="GO^XYZ" > D JOB^SQL0H > I FAIL S SQLERR="Unable to start job "_RTN W $C(7),!,SQLERR > Q TRAP^SQL0H This entry point can be called to set an error trap. For example, KB_SQL can set and clear error traps, while users branch between menu options. The following example specifies GO^ROUTINE as the starting point and ERR^ROUTINE as the error trap point. Any errors encountered will be trapped to the ERR tag. > S SQLTRAP(0)="ERR^ROUTINE" > S SQLTRAP(1)="GO^ROUTINE" > G TRAP^SQL0H > ; > GO<TAB>; entry point > ; > ERR<TAB>; error processing point > Q Chapter 11: Miscellaneous Interfaces 259

268 The SQL0CHK Routine The SQL0CHK routine is one of a small number of routines needed to execute a compiled query. Some of the code that was included in each compiled query routine has been moved to this routine. The SQL0DT Routine This is the standard date conversion utility. Variables are converted from base format ($H) to a number of predefined external formats. Variables The following variables are referenced by the date conversion routine. Variable Name KDE KDF KDI Description External date value Format code Internal date value in $H format 260 KB_SQL Database Administrator s Guide

269 Entry Points The following entry points are called to convert dates. Entry Point DC^SQL0DT DE^SQL0DT DI^SQL0DT Description Current date value > D DC^SQL0DT > W "Today's external date is ",KDE Convert internal to external > S KDI=$H+1 > D DE^SQL0DT > W "Tomorrow's external date is ",KDE Convert external to internal > S KDE="T+1" > D DI^SQL0DT > W "Tomorrow's internal date is ",KDI Chapter 11: Miscellaneous Interfaces 261

270 Valid Input Formats The date conversion routine accepts many types of user inputs. For example, use T as a shortcut for today s date. Refer to the SITE EDIT option for information about how to set the default input method for dates. Input MM/DD/YY[YY] T (1) T [+-]n DD MM/DD (2) Complete date, including month, day, and year > S KDE="03/30/61" > D DI^SQL0DT > W KDI Today > S KDE="T" > D DI^SQL0DT > W KDI Today plus/minus n-days > S KDE="T+2" > D DI^SQL0DT > W KDI Description Day only, default to current year and month > S KDE="15" > D DI^SQL0DT > W "The internal date for the 15th of this month is: ",KDI Month and day only, default to current year > S KDE="03/30" > D DI^SQL0DT > W "The internal date for the 30th of March of this year is: ",KDI (1) T, t, TODAY, and today are valid shortcut input methods for today. (2) The position of the day and month is determined by the default input format for dates as specified in the SITE EDIT Option section in Chapter KB_SQL Database Administrator s Guide

271 Output Formats There are many default output formats for dates. See the table below for a listing of these default formats. Format DD Month, YYYY DD MON, YYYY DD/MM/YY DD/MM/YYYY DDMMYYYY MM/DD/YY MM/DD/YYYY MMDDYYYY MON MON DD, YYYY MON YYYY Month Month DD, YYYY Month YYYY YYYY YYYYMM YYYYMMDD Code Example 30 March, MAR, /03/61 30/03/ /30/61 03/30/ MAR Mar 30, 1961 MAR 1961 March March 30, 1961 March Chapter 11: Miscellaneous Interfaces 263

272 Custom Output Formats You can create your own formats by using the OUTPUT FORMAT EDIT procedure (DATA DICTIONARY/OUTPUT FORMAT EDIT). For example, to format dates as DD-MM-YYYY: > S KDI={BASE},KDF=3 D DE^SQL0DT S {EXT}=$E(KDE,7,8)_"-"_$E(KDE,5,6)_"-"_$E(KDE,1,4) Date Domain Conversions This logic can be useful when creating date domains in the DOMAIN EDIT procedure (DATA DICTIONARY/DOMAIN EDIT). The following examples illustrate how to specify domain conversion logic for dates stored as YYMMDD. Use the DI entry point to convert one of your stored values to the base format for the date data type. Note the use of KDF=3 for the YYYYMMDD format. The following code will get you started. > S KDE=$E({INT},7,8)_"-"_$E({INT},5,6)_"-"_$E({INT},3,4 D DI^SQL0DT S {BASE}=KDI Use the DE entry point to convert from the base format into your stored format. > S KDI={BASE},KDF=3 D DE^SQL0DT S {INT}=$E(KDE,3,8) 264 KB_SQL Database Administrator s Guide

273 The SQL0FC Routine This routine has several entry points designed to be called by functions during the parsing process. See the FUNCTION EDIT option in Chapter 3 for more information on the use of the parse check routine. Note: The functions listed are for illustration purposes only. These functions may or may not be defined on your system. Entry Point A1^SQL0FC A12^SQL0FC A13^SQL0FC A2^SQL0FC A23^SQL0FC A3^SQL0FC A34^SQL0FC A4^SQL0FC I2^SQL0FC 1 argument required LENGTH(NAME) 1-2 arguments RPAD(NAME) RPAD(NAME,'*') 1-3 arguments EXTRACT(NAME) EXTRACT(NAME,3) EXTRACT(NAME,1,20) 2 arguments required MINIMUM(X,Y) 2-3 arguments FIND(NAME,'X') FIND(NAME,'X',10) Description 3 arguments required AREA(LENGTH,WIDTH,HEIGHT) 3-4 arguments DRG(DX,AGE,SEX) DRG(DX,AGE,SEX,OTHER) 4 arguments required TIME(MILES,STOPS,MPH,STOPTIME) 2 integer arguments required ANGLE(HEIGHT,SLOPE) Chapter 11: Miscellaneous Interfaces 265

274 The SQL0GI Routine This routine will restore a global that was saved in the KB_SQL global transfer format. ; Global save on <date> at <time> ; KB_SQL <version> name-1st value-1st name-2nd value-2nd... name-last value-last <NULL> <EOF> This routine can be used to restore a global that was saved in the KB_SQL global transfer format as described above. > D ^SQL0GI Filename: A:SQLGBL.2 Or, for automatic loading: > S SQLFILE="A:SQLGBL.2" > D AUTO^SQL0GI 266 KB_SQL Database Administrator s Guide

275 The SQL0RI Routine This routine will restore a set of M routines that was saved in the KB_SQL routine transfer format. To build your own routine export file, follow the format below. ; Routine save on <date> at <time> ; KB_SQL <version> routine name line #1 line #2.. line #N <NULL> routine name line #1 line #2.. line #N <NULL> <NULL> <EOF> To run SQL0RI: > D ^SQL0RI Filename: A:SQLRTN.2 Or, for automatic loading: > S SQLFILE="A:SQLRTN.2" > D AUTO^SQL0RI Chapter 11: Miscellaneous Interfaces 267

276 The SQL0TM Routine This is the standard time conversion utility. Variables are converted from base format ($H) to and from a number of predefined external formats. Component Hours Minutes Seconds Military AM/PM Code HH MM SS Example HH HH:MM HH:MM.SS HH:MM24 HH:MM12 Format HH HH:MM.SS12 HH:MM12 HH:MM24 HH24 HHMM.SS24 HHMM24 MM SS Example 3 PM 10:30.15 AM 10:30 AM 14: Description Hours in 12-hour format Hours, Minutes, and Seconds in 12-hour format Hours and Minutes in 12-hour format Hours and Minutes in 24-hour format Hours in 24-hour format Hours, Minutes, and Seconds in 24-hour format Hours and Minutes in 24-hour format Minutes since midnight Seconds since midnight 268 KB_SQL Database Administrator s Guide

277 The SQL0TS Routine This routine performs conversions for the MOMENT data type. The moment format is converted using the date and time conversion routines, SQL0DT and SQL0TM. Variables The following variables are used by the moment conversion routine. Variable Name KME KMF KMFT KMI Description External moment value Date and time separator, default is If true, format with time first Internal moment value in $H format Chapter 11: Miscellaneous Interfaces 269

278 Entry Points The following entry points are called to convert moment values. Entry Point MC^SQL0TS ME^SQL0TS MI^SQL0TS Description Current moment value > D MC^SQL0TS > W "Today's external date is ",KME Convert internal to external > S KMI=$H+1_",3600" > D ME^SQL0TS > W "Tomorrow at 6:00 AM is ",KME Convert external to internal > S KME="T+1@1:30 PM" > D MI^SQL0TS > W "Tomorrow at 1:30 PM is ",KMI 270 KB_SQL Database Administrator s Guide

279 Valid Input Formats The moment conversion routine accepts the following as valid input formats. Note that all date and time formats are accepted according to the rules specified by the date and time conversion routines. Input Description Complete date and time > S KME="03/30/61@1:30 PM" > D MI^SQL0TS > W KMI Date only, default to current time > S KME="T" > D MI^SQL0TS > W KMI Time only, default to current date > S KME="@1:30 PM" > D MI^SQL0TS > W KMI Chapter 11: Miscellaneous Interfaces 271

280 A The Integrity Check KB_SQL contains many tables of information. These tables include the definitions of your data dictionary objects, queries, devices, and more. Many precautions are taken to preserve the integrity of these table structures during normal operation of the system. The most significant measure is accomplished by our transaction rollback feature. Working in combination with the error trap functions provided by your M vendor, KB_SQL ensures that any software errors are handled properly, so that the table structures remain intact. Sometimes things happen that cannot be handled by either error trapping or our transaction rollback feature. It may be that your system does not have error trapping, in which case you might want to take steps to ensure the system integrity on your own. Even if you have error trapping, certain software errors and system aborts can leave the system in an incorrect state. If a system abort occurs, the system manager can run a RESET^SQL to rollback any incomplete user transactions. The Integrity Check evaluates the integrity of the KB_SQL tables at a particular point in time. This utility provides another measure of protection to ensure the correct management of the KB_SQL tables that contain your information. The Integrity Check entry points are listed on the following page. Appendix A: The Integrity Check A-1

281 Tag^Routine CHECK^SQLI AUTO^SQLI DEL^SQLI FIX^SQLI VIEW^SQLI Description Run integrity check interactively. Run integrity check without user interaction. Delete status information from the most recent integrity check. Fix the errors reported by the most recent integrity check. View status of the most recent integrity check. KB_SQL manages system integrity in several ways: 1. M error traps are used to ensure that software errors are handled properly. 2. User transactions are buffered to allow for rollback of unwanted changes using the [undo] function. 3. The RESET^SQL procedure allows the system manager to rollback any incomplete user transactions that were left in an invalid state. 4. The Integrity Check identifies and fixes any discrepancies in the KB_SQL table definitions. If you are ever unsure of the degree of integrity of your system tables, you can follow the steps outlined in this document. If you need help interpreting an Integrity Check error log file, contact your technical support representative. Note to System Managers: The KB_SQL Integrity Check verifies the integrity of the tables in the ^SQL global. If you suspect that data has been damaged due to a hardware failure or system crash, you must ensure that the M database is intact before running the Integrity Check. A-2 KB_SQL Database Administrator s Guide

282 Integrity Checking The following table gives a summary of the conditions checked by the Integrity Check. For each check there is a corresponding action and an error category. The category corresponds to the SUMMARY section of the Integrity Check global (^SQLIC). Unless specifically noted, the Integrity Check will automatically fix all errors that are discovered. Check Indexes for base table row Base table row for index Base table foreign keys Base table required columns Base table row locks Data nodes = null Flag value 1 or null Action Add index table row(s) Drop index table row(s) Set column to null Record as a follow-up issue Unlock base table row Remove data node Set column to null Category ADD DROP FKEY REQD* LOCK NDN FLAG * The Integrity Check cannot automatically fix errors in this category. Use the VIEW^SQLI option to get more information about the missing column value. You can then decide to either add the missing information or delete the object using the DEL^SQLI option. Appendix A: The Integrity Check A-3

283 Starting the Integrity Check The Integrity Check can be run for one, several, or all tables in the data dictionary. The error log can be built as a global or as a host system file. You may start the Integrity Check either with or without user interaction. To start an integrity check with user interaction: > DO CHECK^SQLI You may be asked to supply a device type and password. The following prompts will appear: When sending output from the Integrity Check to a file, the file must be undefined. If the file is defined, the process will abort with an error indicating that the file exists with data. You can choose to overwrite the file by including the array setting SQLX("FILE_OVERWRITE"). To view help documentation for these prompts, type? and press [enter]. Type ^ ([shift+6]) and press [enter] to return to the previous question. However, if you want to return to the previous question at the Commit? prompt, type N and then ^ before pressing [enter]. A-4 KB_SQL Database Administrator s Guide

284 To start the integrity check without user interaction: > DO AUTO^SQLI Use this option when you want to check a single table or set of tables. The following variables are referenced. Required Variables SQLUSER SQLDTYPE Description A valid user password is required for all users on KB_SQL. Only DBA and SYS_MGR users can run the Integrity Check. If SQLUSER is not defined, the Integrity Check will attempt to determine the user at runtime. A valid device type is required to use KB_SQL. If SQLDTYPE is not defined, the Integrity Check will attempt to determine the device type at runtime. Appendix A: The Integrity Check A-5

285 Customizing the Integrity Check These optional parameters can be specified prior to calling the Integrity Check starting point. You can use these parameters to customize the checking to meet the specific needs of your customers. For example, if your maintenance procedure invokes our Integrity Check, you may want to use the SQLX("SILENT") variable to suppress messages that the Integrity Check would normally display on the screen. Variable SQLFILE=filename SQLT=# SQLT(#) SQLX("ABORT_CHECK")= SQLX("JOB")= SQLX("NO_AUTO_FIX")= SQLX("FILE_OVERWRITE")= SQLX("NO_LOCK")= SQLX("NO_RESET")= SQLX("SILENT") SQLX("START_TABLE")=# Description Store the error log information in a host system file. Check only this one table. Check only the table #s included in this array. Execute M code to perform interrupt checking. The Integrity Check will abort if the variable SQLERR is defined. Process in background. Perform checking only. Do not fix any errors found by the check. Overwrites an existing file for output from the Integrity Check Allow other users in KB_SQL during the Integrity Check. Do not run the RESET^SQL utility as a prerequisite for the check. Suppresses output normally displayed on your screen. Start checking with this table_id. A-6 KB_SQL Database Administrator s Guide

286 The most reliable check is the total check of all tables. You should understand that customizing the Integrity Check can actually create errors in your system, especially if you run the check or the fix while other users are in KB_SQL. Examples This example starts the Integrity Check as a background job, using a host file for the error log. > K > S SQLUSER="DBAPASSWORD" > S SQLDTYPE="VT100" > S SQLX("JOB")="" > S SQLFILE="E:\TEMP\SQLERR.CHK" > D AUTO^SQLI > I $D(SQLERR) W *7,"Error: ",SQLERR > Q Note: The user and device type are always required. You also can start the Integrity Check for a set of tables. The following example starts the Integrity Check for the SQL_QUERY (155) and SQL_QUERY_LINE (156) tables as a foreground job. > K > S SQLUSER="DBAPASSWORD" > S SQLDTYPE="VT100" > S SQLFILE="E:\TEMP\SQLERR.CHK" > S SQLT(155)="",SQLT(156)="" > D AUTO^SQLI > I $D(SQLERR) W *7,"Error: ",SQLERR > Q Appendix A: The Integrity Check A-7

287 Fixing Errors By default, the Integrity Check will fix all errors that are encountered as part of the checking process. The Integrity Check includes a fix procedure, FIX^SQLI. This process will programmatically fix bad index rows. Errors that involve missing required columns may need further examination. To view the error log, select the UTILITIES/REPORTS/INTEGRITY CHECK ERRORS option or use the following M command: > D VIEW^SQLI KB_SQL Integrity Check Started 07/25/96@10:46 AM, finished N/A Printed on 07/25/96 at 10:49 AM Type Table or Column # errors ADD SCHEMA index -1 2 TABLE index -1 1 TABLE index -8 1 DROP TABLE index -1 1 TABLE index -8 1 End> *** NOTE: REQD errors can not be automatically fixed *** Page 1> A-8 KB_SQL Database Administrator s Guide

288 To start the fix process: > D FIX^SQLI Any errors remaining after the fix need further examination. You can choose to fix the error manually or just delete the row. If you are unsure, please call your technical support representative. To delete a bad row: > D DEL^SQLI The following variables are referenced: P SQLT table number P SQLR row number P SQLERR is returned if the delete is not successful Example: > K > S SQLUSER="SHARK" > S SQLDTYPE="DTM_PC_CONSOLE" > S SQLT=155 ; the SQL_QUERY table > S SQLR=1020 ; row number (query_id) > D DEL^SQLI > I $D(SQLERR) W *7,"Error: ",SQLERR > Q Appendix A: The Integrity Check A-9

289 System Lockout No other users can be using KB_SQL while the Integrity Check is running. In addition, only one job can be running the Integrity Check at any one time. While the Integrity Check is running, no users will be able to log on to KB_SQL. You can use the SYSLOCK^SQL utility to view the status of the Integrity Check. By setting the System Lock to Available, you can effectively abort the check. Incomplete Transactions No incomplete transactions should be defined while the Integrity Check is running. The RESET^SQL utility will be run as a prerequisite to running the check procedure. Understanding Errors Errors found by the Integrity Check can be saved to a global or to a host file. If desired, you can review this file before running the FIX^SQLI process to evaluate the potential impact of the cleanup. If you have questions, fax a copy of the error file to your technical support representative for advice and guidance. A-10 KB_SQL Database Administrator s Guide

290 Scheduling The Integrity Check looks at all tables in the data dictionary. Depending on the size of your data dictionary, you may wish to run the check as a background job. Either way, you can interrupt the check while it is running. You can decide how often to run the Integrity Check based on the status of your data dictionary. In the early phases you might want to run it more often than in later phases when less data dictionary activity is taking place. Appendix A: The Integrity Check A-11

291 The ^SQLIC("CHECK") Global The Integrity Check uses the ^SQLIC global to store information about the checking process. The more important sections of the global are outlined below. ^SQLIC("CHECK") This section is initialized each time the Integrity Check is run. ^SQLIC("CHECK","ERROR_LOG")=<error_count> ^SQLIC("CHECK","ERROR_LOG",<error_#>)=<text> This section gives you the total number of errors and then lists each error number and its corresponding text. This section includes executable M code to add/drop indexes and make other database corrections. It is referenced by the FIX logic. ^SQLIC("CHECK","SUMMARY",<type>)=<count> This section gives you a summary of errors by type. Types include index adds, drops, required columns, fkey columns, and others. ^SQLIC("CHECK","SUMMARY",<type>,<gblref>)=<count> This section provides more detail for the summary. The global reference indicates which particular index table structure was added or dropped. ^SQLIC("CHECK","WORKING")=#;TableName This level stores the number and name of the table that is currently being checked. A-12 KB_SQL Database Administrator s Guide

292 B The Handling of Null Values According to ANSI SQL The null value is a special scalar value that is intended to mean information missing (e.g., value unknown or value does not apply ). The representation of nulls is the empty string and is distinct from all known (i.e., non-null) values. Nulls are treated by arithmetic and scalar comparison operators as follows: Let A and B be database objects. If A is null, then each of the expressions +A and -A evaluates to null. If A is null or B is null or both A and B are null, then each of the following expressions evaluates to null. A+B A-B A*B A/B A B Appendix B: The Handling of Null Values B-1

293 Let A and B be comparable database objects. If A is null or B is null or both A and B are null, then (in the context of a WHERE or HAVING clause) each of the following expressions evaluates to the unknown truth-value (i.e., not true and not false). If a predicate includes a null value, the associated row will not be included in the query result. A=B A<>B A<B A<=B A>B A>=B Two special predicates, <value> IS NULL and <value> IS NOT NULL, are provided for testing to see whether a given value is defined. According to KB_SQL KB_SQL allows you to control how null values are handled. By default, KB_SQL is configured to be consistent with the ANSI SQL definition. Expressions that include a null value will return a null result. You can choose to treat the value as the empty string. This would treat null values in a manner consistent with M logic rules. This makes KB_SQL more like M, but may frustrate seasoned SQL users. B-2 KB_SQL Database Administrator s Guide

294 Null values are included in grouped or ordered results. You can specify which ASCII character to use when including nulls in grouped and ordered results. This usually means collating nulls at the top (space) or bottom (delete) of an ordered result. If you choose, null values can be excluded from grouped and ordered results. This again makes the system more like M. Each site must consider their goals concerning the use of ANSI SQL as a generic database interface language versus a custom language for reporting. We advise customers to stay with the ANSI SQL definition wherever possible to stay open and portable as much as possible. Appendix B: The Handling of Null Values B-3

295 B-4 KB_SQL Database Administrator s Guide

296 INDEX ^ ^SQL entry point, 246, 248 ^SQL global, 22 ^SQLCHG global, 24 ^SQLCK global, 22 ^SQLCUR global, 22 ^SQLEMP global, 24 ^SQLEMPN global, 24 ^SQLEX global, 22, 227 ^SQLIC global, 22 ^SQLIN global, 22 ^SQLIX global, 22, 227 ^SQLJ global, 22 ^SQLL global, 22 ^SQLP global, 22 ^SQLPROJ global, 24 ^SQLQ global, 22 ^SQLRD global, 22 ^SQLS global, 22 ^SQLT global, 22 ^SQLXQ global, 22 A A1^SQL0FC entry point, 264 A12^SQL0FC entry point, 264 A13^SQL0FC entry point, 264 A2^SQL0FC entry point, 264 A23^SQL0FC entry point, 264 A3^SQL0FC entry point, 264 A34^SQL0FC entry point, 264 A4^SQL0FC entry point, 264 ACCESS PLAN INFO option, 68 Add Subtypes window, 112 Add User Group window, 154 ADDRESS INFO option, 55 Address line 1 prompt, 56 Address line 2 prompt, 56 Address line 3 prompt, 56 Address line 4 prompt, 56 Allow connections prompt, 79 Allow multiple jobs per user prompt, 71 Allow renewal after expiration prompt, 166 ANSI INFO option, 60 API calls trace, 79 ATTRIBUTES option, 106 AUTO^SQLI, A-2 Auto select if one match prompt, 59 Avg distinct prompt, 210 B Background colors setting, 118 Background job starting, 258 Background queue manager start date values for, 95, 96 BACKGROUND QUEUE option, 198 Background Task Information window, 71 BACKGROUND TASKS option, 71 BASE ROUTINE EDIT option, 4, 27 Base Routine Information window, 28 Base routine prefixes, 27 BASE ROUTINE PRINT option, 99 Base routines, 27 adding, 27 deleting, 28 editing, 28 sample configuration, 29 BC^SQL, 243, 244, 246, 248 Bold ON/OFF windows, 106 Bottom margin prompt, 75 Box codes, 105 BOX CODES option, 104 Box Drawing Codes window, 105 Break at table prompt, 17 Buffer size input, 81 output, 81 Build number prompt, 222 C Cartesian products handling of queries with, 70 Change job back to original priority execute prompt, 67 Change job to low priority execute prompt, 67 Change User Password window, 167 CHECK^SQLI, A-2 CHECK QUERY option, 91 Class prompt in Device Type window, 104 in Subtype of window, 113 Clear Entire Screen (or Pagefeed) window, 109 Clear Entire Screen from Cursor window, 110 Clear Line from Cursor window, 110 Index I-1

297 INDEX Clear operations supplying logic for, 108 Clearing jobs, 197 Clients and server dialog between, 79 CLOSE^SQL0H, 254, 255 CLOSE EXECUTE option, 116 Colors setting, 118, 169 Command Qualifications window, 170 COMMIT PROMPT option, 92 COMP^SQL, 239, 246, 248 COMPILE^SQL, 241, 246, 249 Compile-time M Code window, 41 COMPILE ALL QUERIES option, 8, 178 Compile all tables prompt, 205 Compile only tables in use by queries prompt, 205 Compile only tables without statistics prompt, 205 COMPILE QUERIES option, 198 COMPILE QUERY LOG option, 213 COMPILE STATISTICS LOG option, 213 COMPILE STATISTICS option, 202, 204 Compile Statistics window, 204 Compile tables with statistics older than prompt, 205 Compiled query executing a, 259 Compiling queries related messages, 182 selecting, 181 stopping the process, 181 Compiling statistics, 244 Configuration menu options, 4 CONFIGURATION option, 25 for DBA, 4 for sysmgr, 16 Confirm password prompt, 167 Connecting to the server, 79 Cost of query error/warning if exceeds, 66 Current Privileges window, 159, 162 Current prompt, 29 Cursor movements supplying logic for, 108 Custom device close execute prompt, 87 in Device Definition window, 121 Custom device open execute prompt, 87 in Device Definition window, 121 Custom device selection execute prompt, 86 Custom header code execute prompt, 76 Custom Logic #1 window, 84 Custom Logic #2 window, 84 CUSTOM LOGIC option, 84, 114 Customizing KB_SQL, 25 D Data exporting it, 33 importing it, 46 Data access plan showing, 59 Data dictionary menu options, 5 Data dictionary objects transferring, 223 DATA DICTIONARY option for DBA, 5 for sysmgr, 16 Database administrator see DBA DATE/TIME LIMITS option, 65 Date conversion routine, 259, 260 see also SQL0DT routine Date conversion utility, 259 DATE data type output formats for, 58 Date domain conversions, 263 Date input prompt, 58 Date output prompt, 58 Dates output formats for, 262 prompting for, 72 setting the start date, 138 specifying display formats for, 58 specifying input formats for, 58 valid input formats, 270 DBA menu, 3 DBA password, 3 DBA responsibilities, 2 I-2 KB_SQL Database Administrator s Guide

298 INDEX DBA SIGNON option, 90 DC^SQL0DT entry point, 260 DE^SQL0DT entry point, 260 Default average distinct prompt, 69 Default base routine prompt, 63 Default file format prompt, 57 Default for COMMIT prompt prompt, 59 Default global name prompt, 63 Default index density prompt, 68 DEFAULT INFO option, 57 Default schema prompt in Group Information window, 155 Default SearchPatternEscape character prompt, 60 Default spacing between columns prompt, 75 DEFAULT STATISTICS routine, 201 Default table density prompt, 68 Default transaction isolation level prompt, 62 DEL^SQLI, A-2, A-3 DELETE^SQL, 242, 246, 249 DELETE command rejecting error rows, 60 Delete Job window, 197 Delete prompt, 163 Delete transaction logs after: days prompt, 65 Deleting jobs, 197 Delimiter prompt, 58 Demonstration globals, 24 Density prompt, 207 Description prompt in Base Routine Information window, 29 in Device Definition window, 120 in Device Type window, 104 in Export Method window, 34 in Function Information window, 39 in Fuzzy Density Information window, 207 in Fuzzy Size Information window, 209 in Import Method window, 47 in Pseudo Column Information window, 52 in Subtype of window, 113 in TCP Host Information window, 82 Determine Input Function and Translate window, 117 DETERMINE INPUT FUNCTION option, 117 Determine interactive device type execute prompt, 85 Device_Type object, 226 transferring, 224, 226 Device Attributes window, 106 Device close execute, 86 Device control using your own, 236 Device Definition window, 120 Device Executes window, 114 DEVICE INFO option, 85 Device name prompt, 120, 135 Device open execute, 86 Device selection using your own, 236 Device selection execute, 86 Device type attributes, 106 DEVICE TYPE EDIT option, 6, 101, 102 Device type name prompt, 185 Device Type Name window, 185 Device Type Options (for subtypes) window, 112 Device Type Options window, 103 DEVICE TYPE PRINT option, 123 Device type prompt, 120 Device type subtypes defining, 135 Device Type window, 103 Device types support of, 101 DI^SQL0DT entry point, 260 DICTIONARY LOCK option, 199 Display dash line in header prompt, 75 Display error if estimated cost exceeds prompt, 66 Display page numbers in header prompt, 76 Display warning if estimated cost exceeds prompt, 66 DNAME^SQL, 246, 249 DOMAIN EDIT option, 5 Index I-3

299 INDEX Domain prompt in Pseudo Column Information window, 52 Downloading data, 4, 33 DTYPE^SQL, 246, 249 E Echo ON/OFF windows, 107 Edit list of available schemas prompt, 77 Edit network configuration prompt, 79 Edit queries prompt, 168 EM^SQL, 246 Enable quickview feature prompt, 69 Encrypting passwords, 171 END^SQL, 246 End of File Check Execute window and the Export Method Edit option, 36 and the Import Method Edit option, 49 Entry points, 248, 251 for SQL0DT routine, 260 for SQL0FC routine, 264 for SQL0H routine, 254 for SQL0TS routine, 269 see also SQL entry points EP^SQL, 246 ER^SQL, 246, 249 ERROR LOG PRINT option, 214 Error rows rejecting, 60 Error trap setting, 258 Errors display of M, 219 trapped by the system, 91 Examine system status prompt, 218 Example in Function Information window, 40 Exceptions display of, 219 Export device types, 184 examples of, 228, 229 functions, 184 pseudo columns, 184 queries, 187 query output, 33, 34 tables, 190 Export all device types prompt, 184 Export and import functions in a stand-alone environment, 57 Export device types edited after prompt, 184 Export Device Types window, 184 EXPORT METHOD EDIT option, 4, 33 EXPORT METHOD PRINT option, 99 Export method prompt, 58 Export Method window, 34 Export methods defining them, 33 EXPORT option, 8, 183 Export strategies, 223 EZQ Editor the DBA s role in introducing it to users, 11 EZQ EDITOR option, 3 EZQ Editor tutorial, 12 EZQ only prompt, 168 EZQ password, 19 EZQ password menu, 20 EZQ queries importing, 195 F Fail prepares with Cartesian Products prompt, 70 Fail prepares without table statistics prompt, 70 Filename prompt for exporting a device type, 186 for exporting a query, 189 for exporting a table, 192 FIX^SQLI, A-2, A-8 Foreground colors setting, 118 Foreground only prompt, 120 Formatting character strings, 257 FROM_GLOBAL_MULTI TRANSFER method, 226 From name prompt in Query Names window, 157 From table name prompt in Print Tables window, 17 in Table Name window, 160 I-4 KB_SQL Database Administrator s Guide

300 INDEX FUNCTION EDIT option, 4, 37 Function Information window, 39 Function Name window, 38 FUNCTION PRINT option, 99 Functions adding, 38 deleting, 38 editing, 38 transferring, 224, 226 using, 43 FUZZY DENSITY EDIT option, 206 Fuzzy Density Information window, 207 FUZZY DENSITY PRINT option, 212 FUZZY SIZE EDIT option, 208 Fuzzy Size Information window, 209 FUZZY SIZE PRINT option, 212 G GENERATE ROUTINE option, 94 Globals demonstration, 24 essential to operation of KB_SQL, 22 for transfer utility, 227 printing, 17 restoring them, 265 transferring them, 226 GRANT statement, 142, 144 Granting privileges examples of, 145, 146 Graphics ON/OFF windows, 107 GROUP EDIT option, 7, 153 Group Information window, 154 Group Name window, 154 GROUP PRINT option, 175 Group prompt, 165 H Halt check, 66, 93 HALT QUERY option, 8, 193 Halt Query window, 193 Header, 75, 76 Host device prompt, 120 Host file end-of-row terminator prompt, 63 Host file I/O, 255 HOST FILE NAME option, 89 Host File Name window for Import option, 196 Host name prompt, 81 Hosts defining, 81 How many queues prompt, 71 I I2^SQL0FC entry point, 264 IL^SQL0H, 254, 256 Import data to tables, 46 examples of, 230 IMPORT METHOD EDIT option, 4, 46 IMPORT METHOD PRINT option, 99 Import method prompt, 58 Import Method window, 47 IMPORT option, 8, 194 Import strategies, 223 Import TABLE window, 195 IMPORT TRANSACTIONS option, 214 Include null values in group and order by clauses prompt, 61 INI^SQL, 246 Initial execute code prompt, 72 Inline function prompt in Function Information window, 40 Input buffer size prompt, 81 Input function codes, 126 Input function translation, 117 Input functions, 125 translating them, 126 INPUT translation checklist, 129 Input translation routine examples of, 132, 133 initialization, 131 single character read, 131 string read, 130 supplying, 124 termination, 131 INSERT command, 46 rejecting error rows, 60 Insert prompt, 162 Integrity Check, A-1 customizing it, A-6 scheduling it, A-11 starting it, A-4, A-5 suppressing messages, A-6 INTEGRITY CHECK ERRORS option, 212 Interactive device types, 124 Internal routines, 245 Index I-5

301 INDEX IP address prompt, 81 Isolation level, 62 IUL^SQL0H, 254, 256 J JOB^SQL0H, 254, 258 JOB COMMAND option, 94 Job priority, 67 JOB variable, 236 JOB WATCH option, 8, 197 JOBD variable, 73 JOBQ variable, 73 JOBR variable, 73 JOBT variable, 73 JOBV variable, 73 JOBX variable, 73 K KB_SQL restricting access to, 141 using locks to restrict access to, 199 KB_SQL user interface calling a query directly, 236 KB_SQL Version Information window, 10, 222 KDATE variable, 236 KDE variable, 259 KDF variable, 259 KDI variable, 259 KEY FORMAT EDIT option, 5 KEY TOPS option, 111 Key Tops window, 111 Keys max. number of, 66 KFL variable, 88 KIF variable, 88 KME variable, 268 KMF variable, 268 KMFT variable, 268 KMI variable, 268 KO(27) variable, 87 KO(4) variable, 87 KTIME variable, 236 L LC^SQL0H, 254, 257 Left margin prompt, 74 Length prompt in Function Information window, 40 in Pseudo Column Information window, 53 Limit search prompt, 168 Limits search, 168 select, 168 Local host prompt, 82 Local hosts defining, 81 LOCK entry points, 256 LOCK STATUS option, 8, 198 Lock Status window, 200 Locked prompt, 200 Locks, 198, 199, 253 display of, 219 Log-off users after: seconds prompt, 65 LOG ERROR option, 91 LOGICAL DEVICE EDIT option, 6, 101, 119 LOGICAL DEVICE PRINT option, 123 Lower query priority after: seconds prompt, 66 Lowercase M formatting in, 257 M Commands Merge prompt, 64 Set $Extract prompt, 64 M errors display of, 219 M Execute window, 96 M Expression prompt in Pseudo Column Information window, 53 M Functions $FNumber prompt, 64 $Get prompt, 64 $Name prompt, 64 $Query prompt, 64 M INFO option, 63 M process removing, 197 M routines restoring them, 266 M string max. length of, 80 MANUAL STATISTICS option, 202, 210 Manual Table Statistics window, 210 MAP EXISTING GLOBALS option, 5 Margins, 74, 75 Max global data length prompt, 64 Maximum counter prompt, 28 Maximum length for sort keys prompt, 62 Maximum length for SQL identifiers prompt, 62 Maximum length of M string prompt, 80 I-6 KB_SQL Database Administrator s Guide

302 INDEX Maximum number of keys prompt, 66 Maximum routine size prompt, 63 Maximum stored queries prompt, 78 MC^SQL0TS entry point, 269 ME^SQL0TS entry point, 269 MEMBER PRINT option, 175 MGR password, 14 MI^SQL0TS entry point, 269 MOMENT data type perform conversions for, 268 Moment separator prompt, 59 Moment time first prompt, 59 Moment values converting, 269 Must run in foreground prompt in the Export Method window, 34 in the Import Method window, 47 N Name prompt in Current Privileges window, 162 in Device Type window, 103 in Export Method window, 34 in Function Information window, 39 in Fuzzy Density Information window, 207 in Fuzzy Size Information window, 209 in Import Method window, 47 in Pseudo Column Information window, 52 in Start Date Information window, 96 in Subtype of window, 113 Network configuration editing, 79, 80 New password prompt, 167 NOTRAP^SQL, 246, 250 Null values, 61 handling of, Appendix B O Object Types window, 156, 171 OPEN^SQL0H, 254, 255 OPEN EXECUTE option, 115 Order by reduction factor prompt, 69 Output buffer size prompt, 81 Output device assigning one, 98 OUTPUT FORMAT EDIT option, 5 Output to File window for exporting a device type, 186 for exporting a query, 189 for exporting a table, 192 P PAGE LAYOUT option, 74 Page Layout Parameters window, 74 Parse check routine, 44 Parse check routine prompt in Function Information window, 39 Password, 143 assigning to a user, 166 encrypting, 171 for DBA, 3 for EZQ users, 20 for SysMgr, 14 for USERS user group, 19 Password expire days prompt, 60, 166 Password expires on prompt, 166 Password prompt, 166 Password warning days prompt, 60 Perform halt check after: rows prompt, 66 Perform halt check after rows prompt, 93 Perform ROW commit prompt, 60 Plan Information window, 68 Populating tables, 46 Port number prompt, 83 POSITION & CLEAR option, 108 Position & Clear window, 108 Position Cursor & Clear Line window, 109 Position Cursor & Clear Screen window, 109 Position Cursor window, 108 Index I-7

303 INDEX Post Process Execute window, 36, 49 Pre Process Execute window, 35, 48 Predicate reduction factor prompt, 69 Prefix of routine, 27, 28 Prefix for stored query routines prompt, 78 Preserve Old Statistics window, 196 Preserve table statistics prompt, 196 Primary key definition for calculating statistics, 201 Print Base Routines window, 98 Print Device Names window, 123 Print Device Specifications window, 123 Print globals prompt, 17 Print on Device window, 135 for Configuration reports, 98 for Security reports, 174 for Utility reports, 211 Print Query Directory window, 211 Print spool, 138 Print Tables window, 16 Print User Groups window, 174 Printing strategies, 134 Priority changing, 67 lowering, 66 Privileges changing them, 160 granting and revoking, 144 granting to all users, 172 listing, 173 to queries, 146, 158 to tables, 145, 158 to views, 147, 158 viewing them, 160 Programmer designating a user as a, 14, 168 Programmer prompt, 168 Prompt for file prompt in Export Method window, 34 in Import Method window, 47 Prompt for start date/time prompt, 72 Protected variable list prompt, 64 Pseudo column adding, 51 definition of, 50 deleting, 51 editing, 51 transferring, 224, 226 PSEUDO COLUMN EDIT option, 4, 50 Pseudo Column Information window, 52 Pseudo Column Name window, 51 PSEUDO COLUMN PRINT option, 100 Public privileges modifying, 172 warning for, 171 PUBLIC PRIVILEGES option, 7, 171 PUBLIC QUERY PRIVILEGES option, 175 PUBLIC TABLE PRIVILEGES option, 176 PUBLIC user, 171 Q Qualifications, 143 Query privileges, 146 running in background, 238 running on a terminal, 237 scheduling the processing of, 138 stopping the execution of, 193 transferring, 224, 226 Query base routine prompt, 155 Query Compile window, 179 Query definition compiling, 241 compiling a set of, 243 creating, 240 deleting, 242 QUERY DIRECTORY option, 212 Query halt check, 93 Query name prompt in Current Privileges window, 159 in Recompile Query window, 180 in Select Query window, 188 Query Names window, 157 Query object availability of, 91 QUERY PRINT option, 212 I-8 KB_SQL Database Administrator s Guide

304 INDEX Query priority, 66 Query privileges, 158 changing, 157 viewing, 157 QUERY PRIVILEGES option, 175 Query queue display of, 219 Query routines assigning names, 30 running compiled routines, 232 running them, 233 Query transactions display of, 219 QUERY TRANSACTIONS option, 214 Queue manager override code prompt, 73 Quickview feature, 69 R READ^SQL0H, 254, 255 Read One Character into Variable 'A' window, 117 Reason prompt, 200 Recompile only edited queries prompt, 179 Recompile Query window, 180 Rejecting rows with errors, 60 Remote hosts defining, 81 Replace if exists prompt, 186, 189, 192 Report parameters for CONFIGURATION reports, 98 REPORTS option in CONFIGURATION menu, 5, 97 in DATA DICTIONARY menu, 6 in SECURITY menu, 7, 173 in TERMINALS/PRINT ERS menu, 6, 122 in UTILITIES menu, 9, 211 RESET^SQL, 246, 250, A-10 Reset Device Parameters when Closed window, 116 Result domain prompt in Function Information window, 40 Return null for expressions that contain null prompt, 61 Reverse sorting, 257 REVOKE statement, 142, 144 Revoking privileges examples of, 145, 146 Right margin prompt, 74 ROLL_UP device type, 127 input translation, 127 Routine alter/save execute prompt, 64 ROUTINE NAME option, 89 Routine names assigning prefix for, 78 Routine prefix prompt, 28 Routine prompt in Device Type window, 104 in Subtype of window, 113 Routines SQL0CHK, 259 SQL0DT, 259 SQL0FC, 264 SQL0GI, 265 SQL0H, 254 SQL0RI, 266 SQL0TM, 267 SQL0TS, 268 table of essential ones, 23 Row commit setting at query level, 60 setting at site level, 60 Row Execute window, 35, 48 Row level locking and the MANUAL STATISTICS option, 202 when compiling queries, 178 when compiling statistics, 202 when exporting, 183 when importing, 194 Row locking, 256 RQM^SQL, 247, 251 RS^SQL0H, 254, 257 RUN^SQL, 233, 247, 251 RUN CHECK option, 93 RUN password, 19 RUN password menu, 20 Run queries in background prompt, 71 Running a KB_SQL query routine, 233 on a printer in background, 238 on a terminal, 237 RUNQ^SQL, 234, 247, 251 Runtime routine prompt, 41 Runtime Routine window, 41 S Sample size prompt, 204 Index I-9

305 INDEX SAVE^SQL, 240, 247, 251 Scale prompt in Function Information window, 40 in Pseudo Column Information window, 53 Scheduling tasks, 139 SCHEMA EDIT option, 6 Schema name prompt in Compile Statistics window, 205 in Print Tables window, 16 in Select Table window, 190 in Table Names window, 160 Security, 141 customizing it, 152 eliminating it, 152 for the DBA, 151 for the system manager, 151 for the users, 151 integrating it, 152 Security levels, 143 SQL command qualifications, 143 system and procedures, 143 table and query privileges, 144 SECURITY option for DBA, 7 for sysmgr, 18 Select, Delete SQL User Job window, 197 Select, Insert, Delete Device Type window, 102 Select, Insert, Delete Device window, 119 Select, Insert, Delete Fuzzy Density window, 207 Select, Insert, Delete Fuzzy Size window, 208 Select, Insert, Delete Ports window, 82 Select, Insert, Delete SQL Custom Start Dates window, 95 Select, Insert, Delete TCP Hosts window, 81 Select, Insert, Delete User Group window, 155 Select/Open/Close example, 87, 88 Select (run) prompt, 159 Select all queries prompt, 187 Select all tables prompt, 190 Select CONFIGURATION window, 4 Select DATA DICTIONARY window, 5 Select DBA OPTIONS window, 3 Select Device Type window, 135 Select EXPORT window, 183 Select IMPORT window, 194 Select prompt in Current Privileges window, 162 in User Information window, 168 Select queries edited after prompt, 187 Select Queries window, 187 Select Query window, 20, 188 Select REPORTS window for CONFIGURATION option, 97 for SECURITY option, 173 for TERMINALS/PRINT ERS option, 122 for UTILITIES option, 211 Select SECURITY window, 7 Select specific queries prompt in Query Compile window, 179 with export option, 183 Select SQL Query window, 158 Select SQL Table window, 161 Select STATISTICS window, 203 Select System-Wide Lock window, 198 Select SYSTEM MANAGER OPTIONS window, 15 Select Table window, 190, 191 Select tables edited after prompt, 190 Select Task window, 193 Select TERMINALS/PRINTERS window, 6, 102 Select TRANSACTION LOGS window, 213 Select UTILITIES window, 8, 178 Sequence prompt in Device Type window, 104 in Subtype of window, 113 Server allowing connections to, 79 Server and clients I-10 KB_SQL Database Administrator s Guide

306 INDEX dialog between, 79 SERVER INFO option, 77 Server Information window, 77 Server initial execute prompt, 79 Server user initial execute prompt, 80 SET $EXTRACT(...)=value syntax, 64 SET COLORS option, 118 Set Device Parameters when Opened window, 115 Set Foreground (KVCF) and Background (KVCB) Colors window, 118 SET PROCESS ID option, 92 SHARK password, 3 Show 'End of Report' message prompt, 75 Show 'Nothing to Print' message prompt, 76 Show data access plan prompt, 59 Show DBA status window at startup prompt, 60 Show rows inserted prompt, 34, 47 Show search/select statistics prompt, 59 Single character read, 131 SINGLE CHARACTER READ option, 117 Site-specific queue manager setting up the, 73 Site Address Information window, 56 Site ANSI Information window, 61 Site Date/Time Limits window, 65 Site Default Information window, 57 SITE EDIT option, 4, 54 Site M Information window, 63 Site name prompt, 54 Site Name window, 54 Site Options window, 55 SITE PRINT option, 100 Size prompt, 209 Smart device types, 104 attributes for, 106 Sort keys max. length of, 62 Sort nulls as ASCII value prompt, 61 Sorting reverse, 257 Special options prompt, 204 Special Options window, 205 SQL compiling SQL into M routines, 239 SQL_IDENTIFIER definition of, 39 SQL command qualifications, 143, 170 SQL Editor the DBA s role in introducing it to users, 11 SQL EDITOR option, 3 SQL Editor tutorial, 12 SQL entry points ^SQL, 248 BC^SQL, 248 COMP^SQL, 248 COMPILE^SQL, 249 DELETE^SQL, 249 DNAME^SQL, 249 DTYPE^SQL, 249 ER^SQL, 249 NOTRAP^SQL, 250 RESET^SQL, 250 RQM^SQL, 251 RUN^SQL, 251 RUNQ^SQL, 251 SAVE^SQL, 251 SQLJOB^SQL, 252 START^SQL, 252 STOP^SQL, 252 SYSLOCK^SQL, 198, 253 XFER^SQL, 253 SQL routine, 23 see also SQL entry points SQL0* routine, 23 SQL0CHK routine, 259 SQL0DT routine, 259 creating date domains, 263 custom output formats, 263 entry points, 260 output formats, 262 valid input formats, 261 SQL0FC routine, 44, 45, 264 entry points, 264 SQL0GI routine, 265 SQL0H entry points, 255 CLOSE^SQL0H, 255 IL^SQL0H, 256 IUL^SQL0H, 256 JOB^SQL0H, 258 LC^SQL0H, 257 OPEN^SQL0H, 255 READ^SQL0H, 255 RS^SQL0H, 257 TRAP^SQL0H, 258 UC^SQL0H, 257 SQL0H routine, 254 SQL0RI routine, 266 SQL0TM routine, 267 SQL0TS routine, 268 Index I-11

307 INDEX entry points, 269 valid input formats, 270 SQLA*,SQLB* routine, 23 SQLBG variable, 86, 87 SQLCODE variable, 232 SQLD* routine, 23 SQLDTYPE variable, 227, 233, A-5 SQLERR variable, 227, 232 SQLF* routine, 23 SQLFILE variable, 227, 236, A-6 SQLFPORT variable, 255 SQLG* routine, 23 SQLI* routine, 2 SQLIC global, A-12 SQLJOB^SQL, 247, 252 SQLJOB variable, 227, 233 setting a unique value for, 92 SQLK* routine, 23 SQLML variable, 227 SQLOC routine, 23 SQLOD variable, 86, 87 SQLOS routine, 23 SQLOW variable, 227 SQLPAGE variable, 232 SQLQNAME variable, 233 SQLQUERY variable, 233 SQLR* routine, 23 SQLRC variable, 243 SQLRE variable, 243 SQLSA variable, 227 SQLSEA variable, 232 SQLSEL variable, 232 SQLSS variable, 244 SQLT variable, A-6 SQLTITLE variable, 227 SQLTO variable, 236 SQLU* routine, 23 SQLUAUTH variable validating it, 80 SQLUCI variable, 227 SQLUCIB variable, 227 SQLUCIC variable, 227 SQLUCIL(#) variable, 227 SQLUCIL variable, 227 SQLUNAME variable validating it, 80 SQLUSER variable, 227, 232, 233, A-5 SQLV* routine, 23 SQLW* routine, 23 SQLWIN variable, 86, 87 SQLX variable, A-6 SQLX* routine, 23 SQLXTM variable, 227 SQLXTO variable, 227 Standard device drivers, 126 START_DATE parameter, 138 START^SQL, 247, 252 START_TIME parameter, 138 Start date prompting for, 72 START DATE EDIT option, 5, 95 Start Date Information window, 96 START DATE PRINT option, 100 Start query at time prompt, 72 Start query on date prompt, 72 Start recompile prompt, 180 Start time prompting for, 72 Statistics alternate method for compiling, 244 calculating, 201 compile, 202, 204, 206 default, 201 manual, 202, 210 preserving, 196 showing, 59 see also Table statistics STATISTICS option, 9, 199, 203 Statistics queue display of, 219 STATS HALT CHECK option, 93 Stats object transferring, 224, 226 STOP^SQL, 247, 252 Stop Recompile window, 181 Stored procedure specifying maximum number, 78 String read, 130 Subtype of... window, 113 Subtypes defining them, 112, 135 examples of, 136 SUBTYPES option, 112 Syntax prompt in Function Information window, 39 SYSLOCK^SQL, 8, 198, 247, 253, A-10 SysMgr password, 14 System delimiter ASCII value prompt, 61 System locks, 198, 253 display of, 219 System manager password, 14 responsibilities of, 14 System manager menu, 15 System name prompt, 77 SYSTEM option, 199 SYSTEM STATUS option, 217 for DBA, 9 I-12 KB_SQL Database Administrator s Guide

308 INDEX for sysmgr, 18 System Status Options window, 218 System Status window, 60,218 T Table populating, 46 privileges, 145 transferring, 224, 226 Table density prompt, 210 Table name prompt in Select Table window, 191 Table Names window, 160 Table privileges changing them, 160 viewing them, 160 TABLE PRIVILEGES option, 175 Table statistics calculating, 201 choosing a method for calculating, 201 handling of tables without, 70 preserving, 196 Table transactions display of, 219 TABLE TRANSACTIONS option, 215 TCP/IP defaults, 80 editing, 79, 80 TCP/IP Defaults window, 79, 80 TCP Host Information window, 81 TCP Ports window, 83 listing, 83 Terminal emulators, 137 Terminal execute code prompt, 72 TERMINALS/PRINTERS option for DBA, 6 TERMINALS / PRINTERS option for sysmgr, 17 Terminate jobs, 197 Thru name prompt in Query Names window, 157 Thru table name prompt in Print Tables window, 17 in Table Name window, 160 Time prompt for starting, 72 setting the start time, 138 specifying display format for, 58 valid input formats, 270 Time conversion utility, 267 TIME data type output formats for, 58 Time output prompt, 58 Time stamp, 59 Timeout for read commands prompt, 80 Timeout in SQL Editor after: seconds prompt, 65 Top margin prompt, 74 Trace API calls prompt, 79 TRANSACTION LOGS option, 213 Transfer combinations, 226 Transfer methods, 224, 225 Transfer utility, 227 example of, 228 Transferring data, 33 Transferring objects, 223, 224 TRAP^SQL0H, 254, 258 Tutorial issues, 12 TYPE INFO option, 103 TYPE INFO option (for subtypes), 113 U UC^SQL0H, 254, 257 UNDO^SQL entry point, 197, 247 UNLOCK entry points, 256 Update (edit) prompt, 159 UPDATE command rejecting error rows, 60 Update prompt, 163 Uploading data, 4 Uppercase formatting in, 257 Use colors prompt, 169 User adding, 164 definition of, 142 deleting, 165 editing, 165 USER EDIT option, 7, 164 User functions creating, 4 User group adding, 153, 154 DBAS, 1, 2 definition, 142 deleting, 156 editing, 155 privileges, 156, 157 security for, 142 SYS_MGRS, 1, 14 USERS, 1, 19 User group prompt, 154 USER ID option, 85 User information Index I-13

309 INDEX adding, 164 User Information window, 165 User name prompt, 165 USER option, 199 USER password, 19 USER password menu, 20 USER PRINT option, 176 User profile checklist, 13 USER SIGNON option, 90 User table and PUBLIC permissions, 171 Utilities menu options, 8 UTILITIES option for DBA, 8 for sysmgr, 18 V VARIABLE CHECK option, 89 Variables for transfer utility, 227 Variables to be preserved prompt, 72 VERSION INFORMATION option, 221 for DBA, 10 for sysmgr, 18 View definition of, 147 examples of, 148, 149, 150 privileges, 147 use of, 11 View privileges changing them, 160 viewing them, 160 VIEW TRANSACTIONS option, 215 VIEW^SQLI, A-2, A-3 VT100 device type input functions for, 128 W W/ option prompt, 159 in Current Privileges window, 163 Warning Bell window, 107 Wild card selection method for selecting queries, 181 Window box codes, 105 Window Colors window, 169 X XFER^SQL, 227, 247, 253 I-14 KB_SQL Database Administrator s Guide