KB_SQL Database Administrator Guide A Guide for the Database Administrator of KB_SQL
© 1988-2019 by Knowledge Based Systems, Inc. All rights reserved. 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.
Knowledge Based Systems, Inc. 43053 Midvale Court Ashburn, Virginia 20147
KB_SQL is a registered trademark of Knowledge Based Systems, Inc.
MUMPS is a registered trademark of the Massachusetts General Hospital.
All other trademarks or registered trademarks are properties of their respective companies. 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 ...... 1 The Database Administrator ...... 2 The System Manager ...... 14 The User ...... 19
Chapter 2: Essential Globals and Routines ...... 21 The Essential Globals ...... 22 The Essential Routines ...... 23 The Demonstration Globals ...... 24
Chapter 3: Configuring KB_SQL for Your Site ...... 25 BASE ROUTINE EDIT Option ...... 27 EXPORT METHOD EDIT Option ...... 33 FUNCTION EDIT Option ...... 37 IMPORT METHOD EDIT Option ...... 46
KB_SQL Database Administrator’s Guide iii PSEUDO COLUMN EDIT Option ...... 50
4 KB_SQL Database Administrator’s Guide SITE EDIT Option ...... 54 START DATE EDIT Option ...... 95 REPORTS Option ...... 97
Chapter 4: Managing Devices ...... 101 DEVICE TYPE EDIT Option ...... 102 LOGICAL DEVICE EDIT Option ...... 119 REPORTS Option ...... 122 Supplying Input Translation Routines ...... 124 Printing Strategies ...... 134
Chapter 5: Applying Security Measures ...... 141 Security for Users ...... 142 Security for User Groups ...... 142 Security Levels ...... 143 Views and Security ...... 147 Using the Default Security ...... 151 Customizing Security ...... 152 Eliminating Security ...... 152 Integrating Security Systems ...... 152 GROUP EDIT Option ...... 153 USER EDIT Option ...... 164 PUBLIC PRIVILEGES Option ...... 171 REPORTS Option ...... 173
Chapter 6: Utilities ...... C KB_SQL Database Administrator’s Guide iii OMPILE ALL QUERIES Option ...... 177 178
6 KB_SQL Database Administrator’s Guide
EXPORT Option ...... 183 HALT QUERY Option ...... 193 IMPORT Option ...... 194 JOB WATCH Option ...... 197 LOCK STATUS Option ...... 198 Calculating Table Statistics ...... 201 STATISTICS Option ...... 203 REPORTS Option ...... 211 TRANSACTION LOGS Option ...... 213
Chapter 7: System Status ...... 217
Chapter 8: KB_SQL’s Version Information ...... 221
Chapter 9: Transferring Data Dictionary Objects ...... 223 Transfer Objects and Methods ...... 224 Transfer Combinations ...... 226 The Transfer Utility ...... 227
Chapter 10: External Interfaces ...... 231 Running Compiled Query Routines ...... 232 Using RUN^SQL ...... 233 Using RUNQ^SQL ...... 234 Using Your Own Device Selection and Device Control ...... 236 Compiling SQL Statements into Routines ...... 239 Saving SQL Statements as a Query ...... 240 Compiling a Set of Query Definitions ...... 241
KB_SQL Database Administrator’s Guide 5
Deleting a Query Definition ...... 242 Compiling a Set of Query Definitions ...... 243 Compiling Statistics for a Set of Tables ...... 244
Chapter 11: Miscellaneous Interfaces ...... 245 The SQL Routine ...... 246 The SQL0H Routine ...... 254 The SQL0CHK Routine ...... 259 The SQL0DT Routine ...... 259 The SQL0FC Routine ...... 264 The SQL0GI Routine ...... 265 The SQL0RI Routine ...... 266 The SQL0TM Routine ...... 267 The SQL0TS Routine ...... 268
Appendix A: Integrity Check ...... A-1 Appendix B: The Handling of Null Values ...... B-1
Index ...... I-1
6 KB_SQL Database Administrator’s Guide 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 7 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 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 9 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 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 11 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, 1983.
An Introduction to Database Systems, C.J. Date, Addison-Wesley Publishing Company, Volume I - 3rd edition, 1981, and Volume II - 1st edition, 1983.
A Visual Introduction to SQL, J. Harvey Trimble, Jr. and David Chappell, John Wiley & Sons, Inc., 1989.
Lan Times Guide to SQL, James R. Groff and Paul N. Weinberg, Osborne McGraw-Hill, 1994.
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 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 Description The database administrator has a comprehensive DBAS understanding of the Information System, the data dictionary, and the user requirements. SYS_MGRS The system manager has a detailed understanding of the daily operations of the Information System. The user has a specialized understanding of a USERS particular information area within the Information System.
13 KB_SQL Database Administrator’s Guide
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 SH ARK: 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 OPTION S
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.
CON FIGURATION Option
4 KB_SQL Database Administrator’s Guide CONFIGURATION has its own menu of options. These options let you customize the implementation of KB_SQL.
Select CON FIGURATION
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
REPORTS corresponds to the reports that you may generate for each of the CONFIGURATION options.
DATA DICTION ARY 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 D ATA D ICTION ARY
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
REPORTS corresponds to the reports that you may generate for each of the DATA DICTIONARY options.
TERMIN ALS/ PRIN TERS 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 TERMIN ALS/ PRIN TERS
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 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 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 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 VERSION IN FORMATION 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 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 overwhelmingthe 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 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 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 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 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 MAN AGER OPTION S
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 CON FIGURATION Option
The system manager is limited to the SITE EDIT procedure.
DATA DICTION ARY 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 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.
TERMIN ALS / PRIN TERS 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 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 IN FORMATION 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 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 Description USER Password for all SQL and EZQ users other than DBAs and system managers EZQ Password for users of the EZQ Editor only RUN Password for users who only run queries; these users do not create or edit queries
20 KB_SQL Database Administrator’s Guide 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 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 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 Description P ^SQL The KB_SQL data dictionary ^SQLCUR Temporary data for cursor-saved ESQL queries ^SQLEX Temporary global used by the export utility P ^SQLIC Info from last Integrity Check ^SQLIN Temporary global used by text editor ^SQLIX Temporary global used by the import utility ^SQLJ Temporary global for transaction related data ^SQLL and ^SQLCK Globals used for locking only ^SQLP Temporary global used for parsing, planning, and building ^SQLQ Global used for locking only ^SQLRD Temporary data for queries processed through API ^SQLS Temporary global for M code build data P ^SQLT Default location for user tables ^SQLXQ Temporary global used by queries for sorting
Chapter 2: Essential Globals and Routines 23 The Essential Routines
Routine Description SQL The sign on routine SQL0* Implementation-specific routines SQLA*,SQLB* Reserved for customer use SQLD* SQL standard device drivers SQLF* SQL data dictionary filers SQLG* SQL compiler SQLI* SQL data dictionary integrity check routines SQLR* SQL reports SQLU* SQL procedures SQLK*, SQLV* SQL internal subroutines SQLW* SQL windows SQLX* SQL default base routine prefix SQLOS External interface to Server API SQLOC 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 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 Description ^SQLCHG Charge data ^SQLEMP Employee data ^SQLEMPN Employee name index ^SQLPROJ 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 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
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 BASE ROUTIN E EDIT Option
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].
Add
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 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 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 Routine N ame 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 M routine name for query QUERY PGM BASE COUNTER M ROUTINE(S) QUERY_1 1 AA 1 AA1 QUERY_2 1 AA 2 AA2 2 AA 2 AA2A QUERY_3 1 BA 1 BA1 QUERY_4 1 BB 1 BB1 2 BB 1 BB1A 3 BB 1 BB1B
32 KB_SQL Database Administrator’s Guide EXPORT METH OD 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
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 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 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 FUN CTION 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 application- specific 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 Function N ame
Add
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.
Edit
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.
Delete
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 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 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 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 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 ; Site functions ; AGE S VALUE=VALUE(2)-VALUE(1)\365.25 Q
42 KB_SQL Database Administrator’s Guide H ow 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 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 SQL0FC - Function parse check routine Tag Description Example A1 1 argument required TEST(A) A12 1-2 arguments TEST(A) or TEST(A,B) A13 1-3 arguments TEST(A) or TEST(A,B) or TEST(A,B,C) A2 2 arguments required TEST(A,B) A23 2-3 arguments TEST(A,B) or TEST(A,B,C) A3 3 arguments required TEST(A,B,C) A34 3-4 arguments TEST(A,B,C) or TEST(A,B,C,D) A4 4 arguments required TEST(A,B,C,D) I2 2 integer arguments TEST(N,M) required where N, M are both integers
Chapter 3: Configuring KB_SQL for Your Site 45 IMPORT METH OD 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 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 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 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 PSEUD O 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 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 N ame
Edit
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.
Delete
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 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 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 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 N ame
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 Site Options
ADD RESS IN FO 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 Site Address Information
Address line 1: character (40) The first line of the site address (e.g., 10000 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) 333-0201).
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 DEFAULT IN FO 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 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 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 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.
AN SI IN FO Option
60 KB_SQL Database Administrator’s Guide Site AN SI 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 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 M IN FO 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 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]
64 KB_SQL Database Administrator’s Guide 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 600-1200 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 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 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 ACCESS PLAN IN FO 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 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 The query cannot contain a GROUP BY clause, a HAVING clause, or functions. P The view definition cannot contain table aliases or column aliases.
Chapter 3: Configuring KB_SQL for Your Site 69 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 BACKGROUN D 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 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 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 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 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 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 SERVER IN FO 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
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 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 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 (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 2048. 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 2048.
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 H ost 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 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, D elete Ports
82 KB_SQL Database Administrator’s Guide 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 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 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 IN FO 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 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 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: D SELECT^DEVICE DEVICE OPEN: D OPEN^DEVICE DEVICE CLOSE: 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 printers KIF = logical input function (just set to 1 in device selection)
Routine
DEVICE ; Custom device select/open/close example ; SELECT 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 ; ; OPEN 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 ; ; CLOSE 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 VARIABLE CH ECK 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'.
H OST FILE N AME 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.
ROUTIN E N AME 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 DBA SIGN ON 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 SIGN ON 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 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.
CH ECK 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 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 RUN CH ECK 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 H ALT CH ECK 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 GEN ERATE ROUTIN E 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 COMMAN D 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 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 Start D ate 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 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 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 BASE ROUTIN E PRIN T 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 METH OD PRIN T Option
This report lists all predefined export methods, including pre-process, row, and post-process execute logic.
FUN CTION PRIN T 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 METH OD PRIN T 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 PSEUD O COLUMN PRIN T 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 PRIN T 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 PRIN T 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.
Chapter 4: Managing Devices 100 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.
100 KB_SQL Database Administrator’s Guide DEVICE TYPE EDIT Option
Select TERMIN ALS/ PRIN TERS
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 D evice Type Options
TYPE IN FO 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 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 Box D rawing 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 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 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 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 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 Clear Entire Screen from Cursor
Clear Line from Cursor
110 KB_SQL Database Administrator’s Guide KEY TOPS Option
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. Key Tops
Chapter 4: Managing Devices 111 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 TYPE IN FO 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 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 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 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 D evice Parameters when Closed
116 KB_SQL Database Administrator’s Guide SIN GLE CH ARACTER 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'
DETERMIN E IN PUT FUN CTION 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 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 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 D evice D efinition
(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 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 REPORTS Option
When you select the REPORTS option, the Select Reports window appears. Select REPORTS
122 KB_SQL Database Administrator’s Guide DEVICE TYPE PRIN T 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 Box drawing codes P Attributes P Custom logic P Key tops
LOGICAL DEVICE PRIN T 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 N ames
Chapter 4: Managing Devices 123 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 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 Description 1 enter standard entry, accept input 2 skip save edits and go to next window 3 help display on-line help documentation 5 list display a list of valid entries for selection 6 up move cursor up one row 7 down move cursor down one row 8 right move cursor right one column 9 left move cursor left one column 10 copy copy marked text to clipboard 11 insert insert text or new row 12 delete delete text or current row 13 first move to the first position in the window 14 last move to the last position in the window 15 pgup display previous page 16 pgdn display next page 20 undo roll back edits to current window and go to previous window 21 exit roll back edits to procedure and exit to menu 22 rubout delete current character and move cursor left one column 23 tab move cursor right to next tab position 24 backtab move cursor left to previous tab position 25 bol move cursor to beginning of line/text 26 eol move cursor to end of line/text 29 mark mark text block for editing
Chapter 4: Managing Devices 125 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 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 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 IN PUT 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.
H ow 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
H ow 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 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
Invalid function keys should be reported as follows: P Set input function (KIF) = 0 and quit.
130 KB_SQL Database Administrator’s Guide 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 32-126 or for values greater than 127.
P User input is in the variable A. P The routine should return the input function in the variable KIF. P 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 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 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 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 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 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.
Subtypes for HP_LASERJET_II Subtype Initial Execute Portrait_Letter W *27,"&l7.27C",*27,"(sp10H" S KFL=60,KFW=77 Portrait_ W *27,"(8U",*27,"(s0p16.66H8.5v0s0b0T" Compressed ,*27,"&l88p8D",*27,"&a10L" S KFL=80,KFW=120 Landscape_Letter W *27,"&l10",*27,"(s0p10H" S KFL=44,KFW=105 Landscape_ W *27,"&l1o5.45C",*27,"(s0p16.66H" Compressed S KFL=62,KFW=180 Subtypes for EPSON_LQ Subtype Initial Execute Letter_Quality W *27,*120,1 S KFW=80,KFL=60 1_Inch_Labels W *27,"C",*6,*27,2 S KFL=6,KFW=35 Normal W *27,"P",*27,2,*27,"CB" S KFL=60,KFW=80
136 KB_SQL Database Administrator’s Guide 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 Print 132 column reports on your terminal. P Download data from your host system to a PC. P Upload data from a PC to your host system. P Send reports to a fax machine. P 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 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 ...
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 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
140 KB_SQL Database Administrator’s Guide 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 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 Name= SMITH_PAUL P Password = PSM P User Group = AP
Security for User Groups
A user group associates one or more users with a common job class or organizationalrole. 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 Group = AP P Group = AR P Group = PAY P 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 Security Levels
KB_SQL lets you control access at several levels.
P System and Procedures P SQL Command Qualifications P 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.
Command Novice Experienced Advanced DBA Select x x x x Create/Drop x Insert/Update/Delete x x x Grant/Revoke x x
Chapter 5: Applying Security Measures 143 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 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 Description SELECT Retrieve rows of data from this table INSERT Add new rows of data to this table UPDATE Modify existing rows of data in this table DELETE 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 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 Description SELECT View, print, or run this query UPDATE 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 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 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 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 = '203-12-9509'
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 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 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 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 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 Group N ame
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 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 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 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 N ames
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 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 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 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 N ames
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 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 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 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 USER EDIT Option
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
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 Edit
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.
Delete
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 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 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 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 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 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 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 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 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 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 GROUP PRIN T Option
This option prints all user group information for the range you specify.
MEMBER PRIN T 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 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 PRIN T 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 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 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 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 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 Selection Criteria
A multiple range of queries can be compiled in a single session. Use the standard wild card selection method outlined below.
P Enter
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 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 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 DEVICE TYPE, FUN CTION , and PSEUD O 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 D evice Type N ame
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
P Enter
P Enter
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 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 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 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 Enter
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 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 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 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
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 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 H ALT QUERY Option
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. Select Task
From the Select Task window, select the task that you want to halt. Halt Query
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 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 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 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.
H ost File N ame
Host file name: character (60) Specify the file name where the data is stored.
196 KB_SQL Database Administrator’s Guide 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 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.
BACKGROUN D 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 DICTION ARY 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 Lock Status
Locked? YES/NO To lock, type YES; to unlock, type NO. Reason: character (60) Enter a reason for setting the lock.
Chapter 6: Utilities 201 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.
YouI 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.
200 KB_SQL Database Administrator’s Guide 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 MAN UAL 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 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 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 1000. 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 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 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 DEN SITY 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 Select, Insert, D elete Fuzzy D ensity
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 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 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 MAN UAL 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 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 FUZZY DEN SITY PRIN T Option
This report produces a list of all fuzzy density values in name order.
FUZZY SIZE PRIN T Option
This report produces a list of all fuzzy size values in name order.
IN TEGRITY CH ECK 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 PRIN T 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 TRAN SACTION 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 TRAN SACTION 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 ERROR LOG PRIN T Option
This report produces a list of all KB_SQL errors that have occurred in a user-specified date range.
IMPORT TRAN SACTION S Option
This report produces a listing of all import transactions for a user-specified date range. A sample of import messages is included. P
QUERY TRAN SACTION S 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 TABLE TRAN SACTION S 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 TRAN SACTION S 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
216 KB_SQL Database Administrator’s Guide
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 I.
217 KB_SQL Database Administrator’s Guide 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 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
220 KB_SQL Database Administrator’s Guide
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 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
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 Transfer Objects and Methods
The following objects can be exported from KB_SQL using any of the transfer methods listed below.
Object # Description Function 1 Transfer user-defined functions Table 2 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 Query 3 Transfer SQL statements (no EZQ data) Pseudo column 4 Transfer pseudo column definitions Device type 5 Transfer device type definitions and device function routines Stats 10 Transfer table distribution statistics
224 KB_SQL Database Administrator’s Guide Transfer Methods
KB_SQL provides the following transfer methods. Choose the most appropriate transfer method for your software environment.
Method # Description TO_FILE 1 Export object definitions to a host file FROM_FILE 2 Import object definitions from host file TO_GLOBAL 3 Export object definitions to global FROM_GLOBAL 4 Import object definitions from global TO_UCI 5 Export object definitions across data sets FROM_GLOBAL 6 Import object definitions from global using _MULTI multiple steps
Chapter 9: Transferring Data Dictionary Objects 225 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 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 Description SQLDTYPE Current device type SQLERR Error message (if defined) SQLFILE Complete filename SQLJOB Process identifier ($JOB) SQLML Multi-load flag (for table import only) SQLOW Overwrite flag (1=overwrite, 0=skip) SQLSA Save all (1=all, 0 = use ^SQLEX list) SQLTITLE Description for import message table (char 60) SQLUCI Data set (UCI) name SQLUCIB Transfer from data set (UCI) SQLUCIC Executable code to change data set (UCI) SQLUCIL # of UCI/ID’s to transfer into SQLUCIL(#) Data set (UCI) name SQLUSER User’s password SQLXTM Transfer method SQLXTO Transfer object Globals ^SQLEX Temporary global for list of export objects ^SQLIX Temporary global for import image
Chapter 9: Transferring Data Dictionary Objects 227 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 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 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
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 Running a query routine with the KB_SQL device selection interface.
P Running a query routine without the KB_SQL device selection interface but with KB_SQL device control.
P Running a query routine without either the KB_SQL device selection interface or the KB_SQL device control.
P Compiling an array of SQL statements into an M routine.
P Saving an array of SQL statements as a KB_SQL query.
P Compiling a KB_SQL query.
P Deleting a KB_SQL query.
P Compiling a set of queries.
P Compiling statistics for a set of tables.
Chapter 10: External Interfaces 231
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 Description SQLERR Error message (if defined) SQLSEA Number of rows searched SQLSEL Number of rows selected SQLPAGE Number of pages output
Variable Description SQLUSER User password SQLCODE Returns status information
232 KB_SQL Database Administrator’s Guide The DDLI interface requires that you supply the following variables:
Chapter 10: External Interfaces 233 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 Description Example SQLDTYPE Device type name VT220 SQLJOB Process ID $JOB SQLQNAME Query name DEMO_SELECT_ALL SQLQUERY Query ID Query internal ID SQLUSER User password 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 Using RUN Q^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 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 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 Description Example JOB Background job ID JOB_ID or "NO SPOOL" KDATE Run date (external) "03/30/61" KTIME Run time (external) "9:00 AM" SQLFILE Output to filename host filename SQLTO Read time out (seconds) 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
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 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 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 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 Description Example SQLRE Compile only edited queries S SQLRE=1 SQLRC Compile ALL queries S SQLRC=1
244 KB_SQL Database Administrator’s Guide 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 Description Example SQLSS Sample Size S SQLSS=1000
Chapter 10: External Interfaces 245 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 SQL P SQL0H P SQL0CHK P SQL0DT P SQL0FC P SQL0GI P SQL0RI P SQL0TM P 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 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 Description ^SQL The starting point for KB_SQL BC^SQL Performs compile statistics or recompiles queries (See example in Chapter 10.) COMP^SQL Compiles an array of SQL text into an M routine (See example in Chapter 10.) COMPILE^SQL Compiles an existing KB_SQL query (See example in Chapter 10.) DELETE^SQL Deletes an existing KB_SQL query (See example in Chapter 10.) DNAME^SQL Views/edits logical device names DTYPE^SQL Views/edits device type definitions EM^SQL Displays error message in box END^SQL Drops all process information (See example in Chapter 10.) (Also, see INI^SQL.) EP^SQL Starts embedded program manager menu ER^SQL Displays error message on last line of window INI^SQL Defines process-specific information (See example in Chapter 10.) (Also, see END^SQL.) NOTRAP^SQL Starts menu system with error trapping disabled RESET^SQL Rolls back all incomplete transactions (All users must be off the KB_SQL system.) RQM^SQL Restarts the Queue Manager
Chapter 11: Miscellaneous Interfaces 247
Entry Point Description RUN^SQL Runs a query from outside the KB_SQL environment (See example in Chapter 10.) RUNQ^SQL Provides a non-interactive interface for running compiled queries (See example in Chapter 10.) SAVE^SQL Saves an array of SQL text into a KB_SQL query (See example in Chapter 10.) SQLJOB^SQL Sets the process id variable (SQLJOB) START^SQL Starts the system, including background functions. STOP^SQL Stops the system, including background functions. SYSLOCK^SQL Views/edits the status of system locks (See Chapter 6: Utilities.) UNDO^SQL Rolls back a single transaction (See Chapter 6: Utilities.) XFER^SQL 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 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 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.
DN AME^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.
N OTRAP^SQL
250 KB_SQL Database Administrator’s Guide 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 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.
RUN Q^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 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 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 9.
254 KB_SQL Database Administrator’s Guide 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 Description CLOSE^SQL0H Close host file IL^SQL0H Incremental lock of global reference IUL^SQL0H Incremental unlock of global reference JOB^SQL0H Start a background job LC^SQL0H Lowercase conversion OPEN^SQL0H Open host file for write READ^SQL0H Open host file for read RS^SQL0H Reverse sort for character values TRAP^SQL0H Error trap UC^SQL0H Uppercase conversion
Chapter 11: Miscellaneous Interfaces 255 SQL0H Entry Points
These entry points fall into four basic categories: host file I/O, row locking, query tools, and system tools.
H ost 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 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 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 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
Chapter 11: Miscellaneous Interfaces 259 The SQL0CH K 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 Description KDE External date value KDF Format code KDI Internal date value in $H format
260 KB_SQL Database Administrator’s Guide Entry Points
The following entry points are called to convert dates.
Entry Point Description DC^SQL0DT Current date value > D DC^SQL0DT > W "Today's external date is ",KDE DE^SQL0DT Convert internal to external > S KDI=$H+1 > D DE^SQL0DT > W "Tomorrow's external date is ",KDE DI^SQL0DT Convert external to internal > S KDE="T+1" > D DI^SQL0DT > W "Tomorrow's internal date is ",KDI
Chapter 11: Miscellaneous Interfaces 261 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 Description MM/DD/YY[YY] Complete date, including month, day, and year > S KDE="03/30/61" > D DI^SQL0DT > W KDI T (1) Today > S KDE="T" > D DI^SQL0DT > W KDI T [+-]n Today plus/minus n-days > S KDE="T+2" > D DI^SQL0DT > W KDI DD 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 (2) MM/DD 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 3.
262 KB_SQL Database Administrator’s Guide Output Formats
There are many default output formats for dates. See the table below for a listing of these default formats.
Format Code Example DD Month, YYYY 11 30 March, 1961 DD MON, YYYY 10 30 MAR, 1961 DD/MM/YY 8 30/03/61 DD/MM/YYYY 9 30/03/1961 DDMMYYYY 15 30031961 MM/DD/YY 0 03/30/61 MM/DD/YYYY 1 03/30/1961 MMDDYYYY 16 3301961 MON 7 MAR MON DD, YYYY 2 Mar 30, 1961 MON YYYY 6 MAR 1961 Month 14 March Month DD, YYYY 12 March 30, 1961 Month YYYY 13 March 1961 YYYY 5 1961 YYYYMM 4 196103 YYYYMMDD 3 19610330
Chapter 11: Miscellaneous Interfaces 263 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 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 Description A1^SQL0FC 1 argument required LENGTH(NAME) A12^SQL0FC 1-2 arguments RPAD(NAME) RPAD(NAME,'*') A13^SQL0FC 1-3 arguments EXTRACT(NAME) EXTRACT(NAME,3) EXTRACT(NAME,1,20) A2^SQL0FC 2 arguments required MINIMUM(X,Y) A23^SQL0FC 2-3 arguments FIND(NAME,'X') FIND(NAME,'X',10) A3^SQL0FC 3 arguments required AREA(LENGTH,WIDTH,HEIGHT) A34^SQL0FC 3-4 arguments DRG(DX,AGE,SEX) DRG(DX,AGE,SEX,OTHER) A4^SQL0FC 4 arguments required TIME(MILES,STOPS,MPH,STOPTIME) I2^SQL0FC 2 integer arguments required ANGLE(HEIGHT,SLOPE)
Chapter 11: Miscellaneous Interfaces 265 The SQL0GI Routine
This routine will restore a global that was saved in the KB_SQL global transfer format.
; Global save on
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 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
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 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 Code Example Hours HH HH Minutes MM HH:MM Seconds SS HH:MM.SS Military 24 HH:MM24 AM/PM 12 HH:MM12
Format Example Description HH 3 PM Hours in 12-hour format HH:MM.SS12 10:30.15 AM Hours, Minutes, and Seconds in 12-hour format HH:MM12 10:30 AM Hours and Minutes in 12-hour format HH:MM24 14:30 Hours and Minutes in 24-hour format HH24 15 Hours in 24-hour format HHMM.SS24 2230.15 Hours, Minutes, and Seconds in 24-hour format HHMM24 1430 Hours and Minutes in 24-hour format MM 584 Minutes since midnight SS 35075 Seconds since midnight
268 KB_SQL Database Administrator’s Guide 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 Description KME External moment value KMF Date and time separator, default is '@' KMFT If true, format with time first KMI Internal moment value in $H format
Chapter 11: Miscellaneous Interfaces 269 Entry Points
The following entry points are called to convert moment values.
Entry Point Description MC^SQL0TS Current moment value > D MC^SQL0TS > W "Today's external date is ",KME ME^SQL0TS Convert internal to external > S KMI=$H+1_",3600" > D ME^SQL0TS > W "Tomorrow at 6:00 AM is ",KME MI^SQL0TS 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 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 Date@Time Complete date and time > S KME="03/30/61@1:30 PM" > D MI^SQL0TS > W KMI Date Date only, default to current time > S KME="T" > D MI^SQL0TS > W KMI @Time Time only, default to current date > S KME="@1:30 PM" > D MI^SQL0TS > W KMI
Chapter 11: Miscellaneous Interfaces 271
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
Tag^Routine Description CHECK^SQLI Run integrity check interactively. AUTO^SQLI Run integrity check without user interaction. DEL^SQLI Delete status information from the most recent integrity check. FIX^SQLI Fix the errors reported by the most recent integrity check. VIEW^SQLI 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 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 Action Category Indexes for base table row Add index table row(s) ADD Base table row for index Drop index table row(s) DROP Base table foreign keys Set column to null FKEY Base table required Record as a follow-up REQD* columns issue Base table row locks Unlock base table row LOCK Data nodes = null Remove data node NDN Flag value or null Set column to null 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 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 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 Description SQLUSER 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. SQLDTYPE 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 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 Description SQLFILE=filename Store the error log information in a host system file. SQLT=# Check only this one table. SQLT(#) Check only the table #s included in this array. SQLX("ABORT_CHECK")= Execute M code to perform interrupt checking. The Integrity Check will abort if the variable SQLERR is defined. SQLX("JOB")= Process in background. SQLX("NO_AUTO_FIX")= Perform checking only. Do not fix any errors found by the check. SQLX("FILE_OVERWRITE")= Overwrites an existing file for output from the Integrity Check SQLX("NO_LOCK")= Allow other users in KB_SQL during the Integrity Check. SQLX("NO_RESET")= Do not run the RESET^SQL utility as a prerequisite for the check. SQLX("SILENT") Suppresses output normally displayed on your screen. SQLX("START_TABLE")=# Start checking with this table_id.
A-6 KB_SQL Database Administrator’s Guide 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 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 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 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 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 The ^SQLIC("CH ECK") 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")=
^SQLIC("CHECK","SUMMARY",
This section gives you a summary of errors by type. Types include index adds, drops, required columns, fkey columns, and others.
^SQLIC("CHECK","SUMMARY",
^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 B
The Handling of Null Values
According to AN SI 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 H andling of N ull Values B-1 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 AB A>=B
Two special predicates,
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 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 H andling of N ull Values B-3
B-4 KB_SQL Database Administrator’s Guide IN DEX
ADDRESS INFO option, 55 adding, 27 ^ Address line 1 prompt, 56 deleting, 28 Address line 2 prompt, 56 editing, 28 ^SQL entry point, 246, 248 Address line 3 prompt, 56 sample configuration, ^SQL global, 22 Address line 4 prompt, 56 29 ^SQLCHG global, 24 Allow connections prompt, 79 BC^SQL, 243, 244, 246, 248 ^SQLCK global, 22 Allow multiple jobs per user Bold ON/OFF windows, 106 ^SQLCUR global, 22 prompt, 71 Bottom margin prompt, 75 ^SQLEMP global, 24 Allow renewal after Box codes, 105 ^SQLEMPN global, 24 expiration prompt, 166 BOX CODES option, 104 ^SQLEX global, 22, 227 ANSI INFO option, 60 Box Drawing Codes window, ^SQLIC global, 22 API calls 105 ^SQLIN global, 22 trace, 79 Break at table prompt, 17 ^SQLIX global, 22, 227 ATTRIBUTES option, 106 Buffer size ^SQLJ global, 22 AUTO^SQLI, A-2 input, 81 ^SQLL global, 22 Auto select if one match output, 81 ^SQLP global, 22 prompt, 59 Build number prompt, 222 ^SQLPROJ global, 24 Avg distinct prompt, 210 ^SQLQ global, 22 C ^SQLRD global, 22 B ^SQLS global, 22 Cartesian products ^SQLT global, 22 Background colors handling of queries ^SQLXQ global, 22 setting, 118 with, 70 Background job Change job back to original A starting, 258 priority execute prompt, 67 Background queue manager Change job to low priority A1^SQL0FC entry point, 264 start date values for, 95, execute prompt, 67 A12^SQL0FC entry point, 96 Change User Password 264 BACKGROUND QUEUE window, 167 A13^SQL0FC entry point, option, 198 CHECK^SQLI, A-2 264 Background Task Information CHECK QUERY option, 91 A2^SQL0FC entry point, 264 window, 71 Class prompt A23^SQL0FC entry point, BACKGROUND TASKS in Device Type window, 264 option, 71 104 A3^SQL0FC entry point, 264 BASE ROUTINE EDIT in Subtype of window, A34^SQL0FC entry point, option, 4, 27 113 264 Base Routine Information Clear Entire Screen (or A4^SQL0FC entry point, 264 window, 28 Pagefeed) window, 109 ACCESS PLAN INFO option, Base routine prefixes, 27 Clear Entire Screen from 68 BASE ROUTINE PRINT Cursor window, 110 Add Subtypes window, 112 option, 99 Clear Line from Cursor Add User Group window, 154 Base routines, 27 window, 110
Index I-1 IN DEX
Clear operations Compiling queries supplying logic for, 108 related messages, 182 D Clearing jobs, 197 selecting, 181 Clients and server stopping the process, Data dialog between, 79 181 exporting it, 33 CLOSE^SQL0H, 254, 255 Compiling statistics, 244 importing it, 46
CLOSE EXECUTE option, Configuration menu options, Data access plan 116 4 showing, 59 Colors CONFIGURATION option, Data dictionary setting, 118, 169 25 menu options, 5 Command Qualifications for DBA, 4 Data dictionary objects window, 170 for sysmgr, 16 transferring, 223 COMMIT PROMPT option, Confirm password prompt, DATA DICTIONARY option 92 167 for DBA, 5 COMP^SQL, 239, 246, 248 Connecting to the server, 79 for sysmgr, 16 COMPILE^SQL, 241, 246, Cost of query Database administrator 249 error/warning if see DBA Compile-time M Code exceeds, 66 DATE/TIME LIMITS option, window, 41 Current Privileges window, 65 COMPILE ALL QUERIES 159, 162 Date conversion routine, 259, option, 8, 178 Current prompt, 29 260 Compile all tables prompt, Cursor movements see also SQL0DT 205 supplying logic for, 108 routine Compile only tables in use by Custom device close execute Date conversion utility, 259 queries prompt, 205 prompt, 87 DATE data type Compile only tables without in Device Definition output formats for, 58 statistics prompt, 205 window, 121 Date domain conversions, 263 COMPILE QUERIES option, Custom device open execute Date input prompt, 58 198 prompt, 87 Date output prompt, 58 COMPILE QUERY LOG in Device Definition Dates option, 213 window, 121 output formats for, 262 COMPILE STATISTICS Custom device selection prompting for, 72 LOG option, 213 execute prompt, 86 setting the start date, COMPILE STATISTICS Custom header code execute 138 option, 202, 204 prompt, 76 specifying display Compile Statistics window, Custom Logic #1 window, 84 formats for, 58 204 Custom Logic #2 window, 84 specifying input formats Compile tables with statistics CUSTOM LOGIC option, 84, for, 58 older than prompt, 205 114 valid input formats, 270 Compiled query Customizing KB_SQL, 25 DBA menu, 3 executing a, 259 DBA password, 3 I-2 KB_SQL Database Administrator’s Guide DBA responsibilities, 2
Index I-3
IN DEX
DBA SIGNON option, 90 Description prompt Device Definition window, DC^SQL0DT entry point, 260 in Base Routine 120 DE^SQL0DT entry point, 260 Information window, Device Executes window, 114 Default average distinct 29 DEVICE INFO option, 85 prompt, 69 in Device Definition Device name prompt, 120, Default base routine prompt, window, 120 135 63 in Device Type window, Device open execute, 86 Default file format prompt, 57 104 Device selection Default for COMMIT prompt in Export Method using your own, 236 prompt, 59 window, 34 Device selection execute, 86 Default global name prompt, in Function Information Device type attributes, 106 63 window, 39 DEVICE TYPE EDIT option, Default index density prompt, in Fuzzy Density 6, 101, 102 68 Information window, Device type name prompt, DEFAULT INFO option, 57 207 185 Default schema prompt in Fuzzy Size Device Type Name window, in Group Information Information window, 185 window, 155 209 Device Type Options (for Default SearchPatternEscape in Import Method subtypes) window, 112 character prompt, 60 window, 47 Device Type Options window, Default spacing between in Pseudo Column 103 columns prompt, 75 Information window, DEVICE TYPE PRINT DEFAULT STATISTICS 52 option, 123 routine, 201 in Subtype of window, Device type prompt, 120 Default table density prompt, 113 Device type subtypes 68 in TCP Host defining, 135 Default transaction isolation Information window, Device Type window, 103 level prompt, 62 82 Device types DEL^SQLI, A-2, A-3 Determine Input Function and support of, 101 DELETE^SQL, 242, 246, 249 Translate window, 117 DI^SQL0DT entry point, 260 DELETE command DETERMINE INPUT DICTIONARY LOCK option, rejecting error rows, 60 FUNCTION option, 117 199 Delete Job window, 197 Determine interactive device Display dash line in header Delete prompt, 163 type execute prompt, 85 prompt, 75 Delete transaction logs Device_Type object, 226 Display error if estimated cost after: days prompt, 65 transferring, 224, 226 exceeds prompt, 66 Deleting jobs, 197 Device Attributes window, Display page numbers in Delimiter prompt, 58 106 header prompt, 76 Demonstration globals, 24 Device close execute, 86 Display warning if estimated Density prompt, 207 Device control cost exceeds prompt, 66 using your own, 236 DNAME^SQL, 246, 249 DOMAIN EDIT option, 5 I-4 KB_SQL Database Administrator’s Guide IN DEX
Domain prompt Error trap EZQ Editor in Pseudo Column setting, 258 the DBA’s role in Information window, Errors introducing it to 52 display of M, 219 users, 11 Downloading data, 4, 33 trapped by the system, EZQ EDITOR option, 3 DTYPE^SQL, 246, 249 91 EZQ Editor tutorial, 12 Examine system status EZQ only prompt, 168 E prompt, 218 EZQ password, 19 Example EZQ password menu, 20 Echo ON/OFF windows, 107 in Function Information EZQ queries Edit list of available schemas window, 40 importing, 195 prompt, 77 Exceptions Edit network configuration display of, 219 F prompt, 79 Export Edit queries prompt, 168 device types, 184 Fail prepares with Cartesian EM^SQL, 246 examples of, 228, 229 Products prompt, 70 Enable quickview feature functions, 184 Fail prepares without table prompt, 69 pseudo columns, 184 statistics prompt, 70 Encrypting passwords, 171 queries, 187 Filename prompt END^SQL, 246 query output, 33, 34 for exporting a device End of File Check Execute tables, 190 type, 186 window Export all device types for exporting a query, and the Export Method prompt, 184 189 Edit option, 36 Export and import functions for exporting a table, and the Import Method in a stand-alone 192 Edit option, 49 environment, 57 FIX^SQLI, A-2, A-8 Entry points, 248, 251 Export device types edited Foreground colors for SQL0DT routine, after prompt, 184 setting, 118 260 Export Device Types window, Foreground only prompt, 120 for SQL0FC routine, 184 Formatting character strings, 264 EXPORT METHOD EDIT 257 for SQL0H routine, 254 option, 4, 33 FROM_GLOBAL_MULTI for SQL0TS routine, EXPORT METHOD PRINT TRANSFER method, 226 269 option, 99 From name prompt see also SQL entry Export method prompt, 58 in Query Names points Export Method window, 34 window, 157 EP^SQL, 246 Export methods From table name prompt ER^SQL, 246, 249 defining them, 33 in Print Tables window, ERROR LOG PRINT option, EXPORT option, 8, 183 17 214 Export strategies, 223 in Table Name window, Error rows 160 rejecting, 60
Index I-5 IN DEX
FUNCTION EDIT option, 4, Graphics ON/OFF windows, Import strategies, 223 37 107 Import TABLE window, 195 Function Information GROUP EDIT option, 7, 153 IMPORT TRANSACTIONS window, 39 Group Information window, option, 214 Function Name window, 38 154 Include null values in group FUNCTION PRINT option, Group Name window, 154 and order by clauses 99 GROUP PRINT option, 175 prompt, 61 Functions Group prompt, 165 INI^SQL, 246 adding, 38 Initial execute code prompt, deleting, 38 H 72 editing, 38 Inline function prompt transferring, 224, 226 Halt check, 66, 93 in Function Information using, 43 HALT QUERY option, 8, 193 window, 40 FUZZY DENSITY EDIT Halt Query window, 193 Input buffer size prompt, 81 option, 206 Header, 75, 76 Input function codes, 126 Fuzzy Density Information Host device prompt, 120 Input function translation, window, 207 Host file end-of-row 117 FUZZY DENSITY PRINT terminator prompt, 63 Input functions, 125 option, 212 Host file I/O, 255 translating them, 126 FUZZY SIZE EDIT option, HOST FILE NAME option, INPUT translation checklist, 208 89 129 Fuzzy Size Information Host File Name window Input translation routine window, 209 for Import option, 196 examples of, 132, 133 FUZZY SIZE PRINT option, Host name prompt, 81 initialization, 131 212 Hosts single character read, defining, 81 131 G How many queues prompt, 71 string read, 130 supplying, 124 GENERATE ROUTINE I termination, 131 option, 94 INSERT command, 46 I2^SQL0FC entry point, 264 Globals rejecting error rows, 60 IL^SQL0H, 254, 256 demonstration, 24 Insert prompt, 162 Import essential to operation of Integrity Check, A-1 data to tables, 46 KB_SQL, 22 customizing it, A-6 examples of, 230 for transfer utility, 227 scheduling it, A-11 IMPORT METHOD EDIT printing, 17 starting it, A-4, A-5 option, 4, 46 restoring them, 265 suppressing messages, IMPORT METHOD PRINT transferring them, 226 A-6 option, 99 GRANT statement, 142, 144 INTEGRITY CHECK Import method prompt, 58 Granting privileges ERRORS option, 212 Import Method window, 47 examples of, 145, 146 Interactive device types, 124 IMPORT option, 8, 194 Internal routines, 245 I-6 KB_SQL Database Administrator’s Guide IN DEX
IP address prompt, 81 KME variable, 268 formatting in, 257 Isolation level, 62 KMF variable, 268 IUL^SQL0H, 254, 256 KMFT variable, 268 M KMI variable, 268 J KO(27) variable, 87 M Commands KO(4) variable, 87 Merge prompt, 64 JOB^SQL0H, 254, 258 KTIME variable, 236 Set $Extract prompt, 64 JOB COMMAND option, 94 M errors Job priority, 67 L display of, 219 JOB variable, 236 M Execute window, 96 JOB WATCH option, 8, 197 LC^SQL0H, 254, 257 M Expression prompt JOBD variable, 73 Left margin prompt, 74 in Pseudo Column JOBQ variable, 73 Length prompt Information window, JOBR variable, 73 in Function Information 53 JOBT variable, 73 window, 40 M Functions JOBV variable, 73 in Pseudo Column $FNumber prompt, 64 JOBX variable, 73 Information window, $Get prompt, 64 53 $Name prompt, 64 K Limit search prompt, 168 $Query prompt, 64 Limits M INFO option, 63 KB_SQL search, 168 M process restricting access to, select, 168 removing, 197 141 Local host prompt, 82 M routines using locks to restrict Local hosts restoring them, 266 access to, 199 defining, 81 M string KB_SQL user interface LOCK entry points, 256 max. length of, 80 calling a query directly, LOCK STATUS option, 8, MANUAL STATISTICS 236 198 option, 202, 210 KB_SQL Version Information Lock Status window, 200 Manual Table Statistics window, 10, 222 Locked prompt, 200 window, 210 KDATE variable, 236 Locks, 198, 199, 253 MAP EXISTING GLOBALS KDE variable, 259 display of, 219 option, 5 KDF variable, 259 Log-off users after: Margins, 74, 75 KDI variable, 259 seconds prompt, 65 Max global data length KEY FORMAT EDIT option, LOG ERROR option, 91 prompt, 64 5 LOGICAL DEVICE EDIT Maximum counter prompt, 28 KEY TOPS option, 111 option, 6, 101, 119 Maximum length for sort keys Key Tops window, 111 LOGICAL DEVICE PRINT prompt, 62 Keys option, 123 Maximum length for SQL max. number of, 66 Lower query priority after: identifiers prompt, 62 KFL variable, 88 seconds prompt, 66 Maximum length of M string KIF variable, 88 Lowercase prompt, 80
Index I-7 IN DEX
209 Maximum number of keys in Import Method P prompt, 66 window, 47 Maximum routine size in Pseudo Column PAGE LAYOUT option, 74 prompt, 63 Information window, Page Layout Parameters Maximum stored queries 52 window, 74 prompt, 78 in Start Date Parse check routine, 44 MC^SQL0TS entry point, 269 Information window, Parse check routine prompt ME^SQL0TS entry point, 269 96 in Function Information MEMBER PRINT option, 175 in Subtype of window, window, 39 MGR password, 14 113 Password, 143 MI^SQL0TS entry point, 269 Network configuration assigning to a user, 166 MOMENT data type editing, 79, 80 encrypting, 171 perform conversions New password prompt, 167 for DBA, 3 for, 268 NOTRAP^SQL, 246, 250 for EZQ users, 20 Moment separator prompt, 59 Null values, 61 for SysMgr, 14 Moment time first prompt, 59 handling of, Appendix for USERS user group, Moment values B 19 converting, 269 Password expire days prompt, Must run in foreground O 60, 166 prompt Password expires on prompt, in the Export Method Object Types window, 156, 166 window, 34 171 Password prompt, 166 in the Import Method OPEN^SQL0H, 254, 255 Password warning days window, 47 OPEN EXECUTE option, 115 prompt, 60 Order by reduction factor Perform halt check after: N prompt, 69 rows prompt, 66 Output buffer size prompt, 81 Perform halt check after Name prompt Output device rows prompt, 93 in Current Privileges assigning one, 98 Perform ROW commit window, 162 OUTPUT FORMAT EDIT prompt, 60 in Device Type window, option, 5 Plan Information window, 68 103 Output to File window Populating tables, 46 in Export Method for exporting a device Port number prompt, 83 window, 34 type, 186 POSITION & CLEAR option, in Function Information for exporting a query, 108 window, 39 189 Position & Clear window, 108 in Fuzzy Density for exporting a table, Position Cursor & Clear Line Information window, 192 window, 109 207 Position Cursor & Clear in Fuzzy Size Screen window, 109 Information window, Position Cursor window, 108
I-8 KB_SQL Database Administrator’s Guide IN DEX
Post Process Execute window, granting and revoking, PUBLIC QUERY 36, 49 144 PRIVILEGES option, 175 Pre Process Execute window, granting to all users, PUBLIC TABLE 35, 48 172 PRIVILEGES option, 176 Predicate reduction factor listing, 173 PUBLIC user, 171 prompt, 69 to queries, 146, 158 Prefix to tables, 145, 158 Q of routine, 27, 28 to views, 147, 158 Prefix for stored query viewing them, 160 Qualifications, 143 routines prompt, 78 Programmer Query Preserve Old Statistics designating a user as a, privileges, 146 window, 196 14, 168 running in background, Preserve table statistics Programmer prompt, 168 238 prompt, 196 Prompt for file prompt running on a terminal, Primary key definition in Export Method 237 for calculating window, 34 scheduling the statistics, 201 in Import Method processing of, 138 Print Base Routines window, window, 47 stopping the execution 98 Prompt for start date/time of, 193 Print Device Names window, prompt, 72 transferring, 224, 226 123 Protected variable list prompt, Query base routine prompt, Print Device Specifications 64 155 window, 123 Pseudo column Query Compile window, 179 Print globals prompt, 17 adding, 51 Query definition Print on Device window, 135 definition of, 50 compiling, 241 for Configuration deleting, 51 compiling a set of, 243 reports, 98 editing, 51 creating, 240 for Security reports, 174 transferring, 224, 226 deleting, 242 for Utility reports, 211 PSEUDO COLUMN EDIT QUERY DIRECTORY Print Query Directory option, 4, 50 option, 212 window, 211 Pseudo Column Information Query halt check, 93 Print spool, 138 window, 52 Query name prompt Print Tables window, 16 Pseudo Column Name in Current Privileges Print User Groups window, window, 51 window, 159 174 PSEUDO COLUMN PRINT in Recompile Query Printing strategies, 134 option, 100 window, 180 Priority Public privileges in Select Query changing, 67 modifying, 172 window, 188 lowering, 66 warning for, 171 Query Names window, 157 Privileges PUBLIC PRIVILEGES Query object changing them, 160 option, 7, 171 availability of, 91 QUERY PRINT option, 212
Index I-9 IN DEX
Query priority, 66 in DATA SQL0H, 254 Query privileges, 158 DICTIONARY menu, SQL0RI, 266 changing, 157 6 SQL0TM, 267 viewing, 157 in SECURITY menu, 7, SQL0TS, 268 QUERY PRIVILEGES 173 table of essential ones, option, 175 in 23 Query queue TERMINALS/PRINT Row commit display of, 219 ERS menu, 6, 122 setting at query level, Query routines in UTILITIES menu, 9, 60 assigning names, 30 211 setting at site level, 60 running compiled RESET^SQL, 246, 250, A-10 Row Execute window, 35, 48 routines, 232 Reset Device Parameters Row level locking running them, 233 when Closed window, 116 and the MANUAL Query transactions Result domain prompt STATISTICS option, display of, 219 in Function Information 202 QUERY TRANSACTIONS window, 40 when compiling option, 214 Return null for expressions queries, 178 Queue manager override code that contain null prompt, when compiling prompt, 73 61 statistics, 202 Quickview feature, 69 Reverse sorting, 257 when exporting, 183 REVOKE statement, 142, 144 when importing, 194 R Revoking privileges Row locking, 256 examples of, 145, 146 RQM^SQL, 247, 251 READ^SQL0H, 254, 255 Right margin prompt, 74 RS^SQL0H, 254, 257 Read One Character into ROLL_UP device type, 127 RUN^SQL, 233, 247, 251 Variable 'A' window, 117 input translation, 127 RUN CHECK option, 93 Reason prompt, 200 Routine alter/save execute RUN password, 19 Recompile only edited queries prompt, 64 RUN password menu, 20 prompt, 179 ROUTINE NAME option, 89 Run queries in background Recompile Query window, Routine names prompt, 71 180 assigning prefix for, 78 Running a KB_SQL query Rejecting rows with errors, 60 Routine prefix prompt, 28 routine, 233 Remote hosts Routine prompt on a printer in defining, 81 in Device Type window, background, 238 Replace if exists prompt, 186, 104 on a terminal, 237 189, 192 in Subtype of window, RUNQ^SQL, 234, 247, 251 Report parameters 113 Runtime routine prompt, 41 for CONFIGURATION Routines Runtime Routine window, 41 reports, 98 SQL0CHK, 259 REPORTS option SQL0DT, 259 S in CONFIGURATION SQL0FC, 264 menu, 5, 97 SQL0GI, 265 Sample size prompt, 204 I-10 KB_SQL Database Administrator’s Guide
IN DEX
SAVE^SQL, 240, 247, 251 173 Scale prompt Select, Insert, Delete Fuzzy for in Function Information Density window, 207 TERMINALS/PRINT window, 40 Select, Insert, Delete Fuzzy ERS option, 122 in Pseudo Column Size window, 208 for UTILITIES option, Information window, Select, Insert, Delete Ports 211 53 window, 82 Select SECURITY window, 7 Scheduling tasks, 139 Select, Insert, Delete SQL Select specific queries prompt SCHEMA EDIT option, 6 Custom Start Dates in Query Compile Schema name prompt window, 95 window, 179 in Compile Statistics Select, Insert, Delete TCP with export option, 183 window, 205 Hosts window, 81 Select SQL Query window, in Print Tables window, Select, Insert, Delete User 158 16 Group window, 155 Select SQL Table window, in Select Table window, Select/Open/Close example, 161 190 87, 88 Select STATISTICS window, in Table Names Select (run) prompt, 159 203 window, 160 Select all queries prompt, 187 Select System-Wide Lock Security, 141 Select all tables prompt, 190 window, 198 customizing it, 152 Select CONFIGURATION Select SYSTEM MANAGER eliminating it, 152 window, 4 OPTIONS window, 15 for the DBA, 151 Select DATA DICTIONARY Select Table window, 190, for the system manager, window, 5 191 151 Select DBA OPTIONS Select tables edited after for the users, 151 window, 3 prompt, 190 integrating it, 152 Select Device Type window, Select Task window, 193 Security levels, 143 135 Select SQL command Select EXPORT window, 183 TERMINALS/PRINTERS qualifications, 143 Select IMPORT window, 194 window, 6, 102 system and procedures, Select prompt Select TRANSACTION 143 in Current Privileges LOGS window, 213 table and query window, 162 Select UTILITIES window, 8, privileges, 144 in User Information 178 SECURITY option window, 168 Sequence prompt for DBA, 7 Select queries edited after in Device Type window, for sysmgr, 18 prompt, 187 104 Select, Delete SQL User Job Select Queries window, 187 in Subtype of window, window, 197 Select Query window, 20, 188 113 Select, Insert, Delete Device Select REPORTS window Server Type window, 102 for CONFIGURATION allowing connections Select, Insert, Delete Device option, 97 to, 79 window, 119 for SECURITY option, Server and clients Index I-11 IN DEX
dialog between, 79 window, 57 RESET^SQL, 250 SERVER INFO option, 77 SITE EDIT option, 4, 54 RQM^SQL, 251 Server Information window, Site M Information window, RUN^SQL, 251 77 63 RUNQ^SQL, 251 Server initial execute prompt, Site name prompt, 54 SAVE^SQL, 251 79 Site Name window, 54 SQLJOB^SQL, 252 Server user initial execute Site Options window, 55 START^SQL, 252 prompt, 80 SITE PRINT option, 100 STOP^SQL, 252 SET $EXTRACT(...)=value Size prompt, 209 SYSLOCK^SQL, 198, syntax, 64 Smart device types, 104 253 SET COLORS option, 118 attributes for, 106 XFER^SQL, 253 Set Device Parameters when Sort keys SQL routine, 23 Opened window, 115 max. length of, 62 see also SQL entry Set Foreground (KVCF) and Sort nulls as ASCII value points Background (KVCB) prompt, 61 SQL0* routine, 23 Colors window, 118 Sorting SQL0CHK routine, 259 SET PROCESS ID option, 92 reverse, 257 SQL0DT routine, 259 SHARK password, 3 Special options prompt, 204 creating date domains, Show 'End of Report' message Special Options window, 205 263 prompt, 75 SQL custom output formats, Show 'Nothing to Print' compiling SQL into M 263 message prompt, 76 routines, 239 entry points, 260 Show data access plan SQL_IDENTIFIER output formats, 262 prompt, 59 definition of, 39 valid input formats, 261 Show DBA status window at SQL command qualifications, SQL0FC routine, 44, 45, 264 startup prompt, 60 143, 170 entry points, 264 Show rows inserted prompt, SQL Editor SQL0GI routine, 265 34, 47 the DBA’s role in SQL0H entry points, 255 Show search/select statistics introducing it to CLOSE^SQL0H, 255 prompt, 59 users, 11 IL^SQL0H, 256 Single character read, 131 SQL EDITOR option, 3 IUL^SQL0H, 256 SINGLE CHARACTER SQL Editor tutorial, 12 JOB^SQL0H, 258 READ option, 117 SQL entry points LC^SQL0H, 257 Site-specific queue manager ^SQL, 248 OPEN^SQL0H, 255 setting up the, 73 BC^SQL, 248 READ^SQL0H, 255 Site Address Information COMP^SQL, 248 RS^SQL0H, 257 window, 56 COMPILE^SQL, 249 TRAP^SQL0H, 258 Site ANSI Information DELETE^SQL, 249 UC^SQL0H, 257 window, 61 DNAME^SQL, 249 SQL0H routine, 254 Site Date/Time Limits DTYPE^SQL, 249 SQL0RI routine, 266 window, 65 ER^SQL, 249 SQL0TM routine, 267 Site Default Information NOTRAP^SQL, 250 SQL0TS routine, 268 I-12 KB_SQL Database Administrator’s Guide IN DEX
entry points, 269 SQLUCI variable, 227 manual, 202, 210 valid input formats, 270 SQLUCIB variable, 227 preserving, 196 SQLA*,SQLB* routine, 23 SQLUCIC variable, 227 showing, 59 SQLBG variable, 86, 87 SQLUCIL(#) variable, 227 see also Table statistics SQLCODE variable, 232 SQLUCIL variable, 227 STATISTICS option, 9, 199, SQLD* routine, 23 SQLUNAME variable 203 SQLDTYPE variable, 227, validating it, 80 Statistics queue 233, A-5 SQLUSER variable, 227, 232, display of, 219 SQLERR variable, 227, 232 233, A-5 STATS HALT CHECK SQLF* routine, 23 SQLV* routine, 23 option, 93 SQLFILE variable, 227, 236, SQLW* routine, 23 Stats object A-6 SQLWIN variable, 86, 87 transferring, 224, 226 SQLFPORT variable, 255 SQLX variable, A-6 STOP^SQL, 247, 252 SQLG* routine, 23 SQLX* routine, 23 Stop Recompile window, 181 SQLI* routine, 2 SQLXTM variable, 227 Stored procedure SQLIC global, A-12 SQLXTO variable, 227 specifying maximum SQLJOB^SQL, 247, 252 Standard device drivers, 126 number, 78 SQLJOB variable, 227, 233 START_DATE parameter, String read, 130 setting a unique value 138 Subtype of ... window, 113 for, 92 START^SQL, 247, 252 Subtypes SQLK* routine, 23 START_TIME parameter, defining them, 112, 135 SQLML variable, 227 138 examples of, 136 SQLOC routine, 23 Start date SUBTYPES option, 112 SQLOD variable, 86, 87 prompting for, 72 Syntax prompt SQLOS routine, 23 START DATE EDIT option, in Function Information SQLOW variable, 227 5, 95 window, 39 SQLPAGE variable, 232 Start Date Information SYSLOCK^SQL, 8, 198, 247, SQLQNAME variable, 233 window, 96 253, A-10 SQLQUERY variable, 233 START DATE PRINT option, SysMgr password, 14 SQLR* routine, 23 100 System delimiter ASCII value SQLRC variable, 243 Start query at time prompt, 72 prompt, 61 SQLRE variable, 243 Start query on date prompt, System locks, 198, 253 SQLSA variable, 227 72 display of, 219 SQLSEA variable, 232 Start recompile prompt, 180 System manager SQLSEL variable, 232 Start time password, 14 SQLSS variable, 244 prompting for, 72 responsibilities of, 14 SQLT variable, A-6 Statistics System manager menu, 15 SQLTITLE variable, 227 alternate method for System name prompt, 77 SQLTO variable, 236 compiling, 244 SYSTEM option, 199 SQLU* routine, 23 calculating, 201 SYSTEM STATUS option, SQLUAUTH variable compile, 202, 204, 206 217 validating it, 80 default, 201 for DBA, 9 Index I-13 IN DEX
for sysmgr, 18 Terminal execute code Transferring objects, 223, 224 System Status Options prompt, 72 TRAP^SQL0H, 254, 258 window, 218 TERMINALS/PRINTERS Tutorial issues, 12 System Status window, option TYPE INFO option, 103 60,218 for DBA, 6 TYPE INFO option (for TERMINALS / PRINTERS subtypes), 113 T option for sysmgr, 17 U Table Terminate jobs, 197 populating, 46 Thru name prompt UC^SQL0H, 254, 257 privileges, 145 in Query Names UNDO^SQL entry point, 197, transferring, 224, 226 window, 157 247 Table density prompt, 210 Thru table name prompt UNLOCK entry points, 256 Table name prompt in Print Tables window, Update (edit) prompt, 159 in Select Table window, 17 UPDATE command 191 in Table Name window, rejecting error rows, 60 Table Names window, 160 160 Update prompt, 163 Table privileges Time Uploading data, 4 changing them, 160 prompt for starting, 72 Uppercase viewing them, 160 setting the start time, formatting in, 257 TABLE PRIVILEGES option, 138 Use colors prompt, 169 175 specifying display User Table statistics format for, 58 adding, 164 calculating, 201 valid input formats, 270 definition of, 142 choosing a method for Time conversion utility, 267 deleting, 165 calculating, 201 TIME data type editing, 165 handling of tables output formats for, 58 USER EDIT option, 7, 164 without, 70 Time output prompt, 58 User functions preserving, 196 Time stamp, 59 creating, 4 Table transactions Timeout for read commands User group display of, 219 prompt, 80 adding, 153, 154 TABLE TRANSACTIONS Timeout in SQL Editor after: DBAS, 1, 2 option, 215 seconds prompt, 65 definition, 142 TCP/IP defaults, 80 Top margin prompt, 74 deleting, 156 editing, 79, 80 Trace API calls prompt, 79 editing, 155 TCP/IP Defaults window, 79, TRANSACTION LOGS privileges, 156, 157 80 option, 213 security for, 142 TCP Host Information Transfer combinations, 226 SYS_MGRS, 1, 14 window, 81 Transfer methods, 224, 225 USERS, 1, 19 TCP Ports window, 83 Transfer utility, 227 User group prompt, 154 listing, 83 example of, 228 USER ID option, 85 Terminal emulators, 137 Transferring data, 33 User information I-14 KB_SQL Database Administrator’s Guide IN DEX
adding, 164 VT100 device type User Information window, input functions for, 128 165 User name prompt, 165 W USER option, 199 USER password, 19 W/ option prompt, 159 USER password menu, 20 in Current Privileges USER PRINT option, 176 window, 163 User profile checklist, 13 Warning Bell window, 107 USER SIGNON option, 90 Wild card selection method User table for selecting queries, and PUBLIC 181 permissions, 171 Window box codes, 105 Utilities menu options, 8 Window Colors window, 169 UTILITIES option for DBA, 8 X for sysmgr, 18 XFER^SQL, 227, 247, 253 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 Index I-15