Upload
others
View
32
Download
0
Embed Size (px)
Citation preview
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.
KB_SQL Database Administrator’s Guide iii
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vii
vii
vii
Conventions Used in this Manual ...................................................................... viii
The Organization of this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
x
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
4 KB_SQL Database Administrator’s Guide
PSEUDO COLUMN EDIT Option .............................................................. 50
KB_SQL Database Administrator’s Guide iii
SITE EDIT Option ........................................................................................ 54
START DATE EDIT Option ........................................................................ 95
REPORTS Option ......................................................................................... 97
Chapter 4: Managing Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEVICE TYPE EDIT Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOGICAL DEVICE EDIT Option . . . . . . . . . . . . . . . . . . . . . . . . . . .
REPORTS Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supplying Input Translation Routines . . . . . . . . . . . . . . . . . . . . . . . . .
Printing Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
101
102
119
122
124
134
Chapter 5: Applying Security Measures . . . . . . . . . . . . . . . . . . . . . . . .
Security for Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Security for User Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Security Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Views and Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Default Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customizing Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Eliminating Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Integrating Security Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GROUP EDIT Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
USER EDIT Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PUBLIC PRIVILEGES Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REPORTS Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
141
142
142
143
147
151
152
152
152
153
164
171
173
Chapter 6: Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C
6 KB_SQL Database Administrator’s Guide
OMPILE ALL QUERIES Option . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
178
KB_SQL Database Administrator’s Guide 5
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
6 KB_SQL Database Administrator’s Guide
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Appendix B: The Handling of Null Values . . . . . . . . . . . . . . . . . . . .
. .
. .
A-1
B-1
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I-1
KB_SQL Database Administrator’s Guide 7
Preface
Purpose
The KB_SQL Database Administrator’s Guide contains information
about maintenance procedures for KB_SQL. This document is
designed to help the database administrator (DBA) use the KB_SQL
procedures effectively to ensure good performance and consistent
operation of the system.
Audience
The manual is written for the database administrator of the KB_SQL
system. The material is directed to those persons responsible for the
smooth ongoing operation of the system. Experienced users and
programmers will find this information helpful in the basic
implementation of the system and for integrating the system with
existing applications.
We expect you to be familiar with M, the relational database model,
and SQL. For those who want to increase their understanding of these
topics, we have provided a list of publications in the “ Additional
Documentation” section of this preface.
We also suggest that you review Lesson 1: The Basics in the KB_SQL
SQL Reference Guide to become familiar with the functions of the
interface.
viii KB_SQL Database Administrator’s Guide
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.
KB_SQL Database Administrator’s Guide 9
Prompt: data type (length) [key]
The manual includes information about all of the system prompts. Each
prompt will include the data type, length, and any special keys allowed.
If the prompt is followed by a colon (Prompt:), you may enter a value
for the prompt.
If a prompt is followed by an equal sign (Prompt= ), it is for display
purposes only.
If the prompt is followed by a question mark (Prompt?), you can enter
a value of YES or NO.
^GLOBAL
All M global names will be prefixed by the '^' character.
Tag^Routine
All M routine references will appear as tag^routine.
Menu Option/Menu Option/Menu Option
A string of options shows you the sequence in which you must select
the options in order to arrive at a certain function. Each menu’s option
is separated by a slash (/).
Example:
DATA DICTIONARY/REPORTS/SCHEMA PRINT
x KB_SQL Database Administrator’s Guide
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.
KB_SQL Database Administrator’s Guide 11
Chapter 10: External Interfaces shows how to compile and run queries
outside of the standard KB_SQL interface.
Chapter 11: Miscellaneous Interfaces provides information on some of
the internal functions used by KB_SQL.
Appendix A: Integrity Check explains the Integrity Check procedure
which you can use to evaluate the integrity of the KB_SQL tables.
Appendix B: The Handling of Null Values describes how KB_SQL
handles null values.
Error Messages
**********
Earlier versions of this manual listed error messages in a separate
appendix. Error messages are now available by running the
SQL_ERROR_LIST query.
xii KB_SQL Database Administrator’s Guide
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.
13 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
DBAS
The database administrator has a comprehensive
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.
USERS
The user has a specialized understanding of a
particular information area within the
Information System.
Chapter 1: An Overview of the KB_SQL User Groups and Menus 3
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.
4 KB_SQL Database Administrator’s Guide
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
Chapter 1: An Overview of the KB_SQL User Groups and Menus 5
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.
6 KB_SQL Database Administrator’s Guide
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.
Chapter 1: An Overview of the KB_SQL User Groups and Menus 7
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.
8 KB_SQL Database Administrator’s Guide
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.
Chapter 1: An Overview of the KB_SQL User Groups and Menus 9
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.
10 KB_SQL Database Administrator’s Guide
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.
Chapter 1: An Overview of the KB_SQL User Groups and Menus 11
VERSION IN FORMATION Option
VERSION INFORMATION displays information about the customer
and the KB_SQL product.
KB_SQL Version Information
12 KB_SQL Database Administrator’s Guide
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.
Chapter 1: An Overview of the KB_SQL User Groups and Menus 13
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.
14 KB_SQL Database Administrator’s Guide
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
Chapter 1: An Overview of the KB_SQL User Groups and Menus 15
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.
16 KB_SQL Database Administrator’s Guide
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.
Chapter 1: An Overview of the KB_SQL User Groups and Menus 17
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.
18 KB_SQL Database Administrator’s Guide
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.
Chapter 1: An Overview of the KB_SQL User Groups and Menus 19
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.
20 KB_SQL Database Administrator’s Guide
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
Chapter 1: An Overview of the KB_SQL User Groups and Menus 21
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.
22 KB_SQL Database Administrator’s Guide
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.
Chapter 2: Essential Globals and Routines 23
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
^SQL The KB_SQL data dictionary P
^SQLCUR Temporary data for cursor-saved ESQL
queries
^SQLEX Temporary global used by the export utility
^SQLIC Info from last Integrity Check P
^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
^SQLT Default location for user tables P
^SQLXQ Temporary global used by queries for sorting
24 KB_SQL Database Administrator’s Guide
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.
Chapter 2: Essential Globals and Routines 25
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.
26 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 27
Note:
All M code executes and device type executes
in this chapter are for illustrative purposes only.
28 KB_SQL Database Administrator’s Guide
BASE ROUTIN E EDIT Option
Add
KB_SQL uses base routines to assign names to the M routines that it
generates to perform your queries. Typical base routine prefixes will
be 1-4 alpha characters in length and allow between 9 and 999 base
routines. The combination of prefix and maximum number can not
exceed seven characters. Creating multiple base routines will allow
different user groups to produce queries with different routine prefixes.
Note: To control which routine suffixes are allocated, refer to the
CONFIGURATION/SITE EDIT/CUSTOM LOGIC/GENERATE
ROUTINE option.
After you select the BASE ROUTINE EDIT option, the Select, Insert,
Delete selection window will appear. You can press [insert] to add a
base routine, or select the base routine you wish to edit. If you want to
delete a base routine, highlight it and press [delete].
Adding a new base routine is as easy as deciding on a prefix and how
many different routines to allow. You can use the generic SQLX prefix
or a prefix specific to a site or group. Some research should be done to
ensure that there are no routines in conflict with the new prefix. It is
usually best to keep base routines distinct and uniform in length. For
example, use two character prefixes such as AA, AB, AC, etc.
Chapter 3: Configuring KB_SQL for Your Site 29
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.
30 KB_SQL Database Administrator’s Guide
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
Chapter 3: Configuring KB_SQL for Your Site 31
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.
32 KB_SQL Database Administrator’s Guide
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
Chapter 3: Configuring KB_SQL for Your Site 33
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].
34 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 35
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.)
36 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 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.)
Chapter 3: Configuring KB_SQL for Your Site 37
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].
38 KB_SQL Database Administrator’s Guide
Function N ame
Add
Edit
You need to follow some simple steps to define and use a function.
First, once a need is established, determine the number and type of
input variables. Then determine the type and format of the return
variable. After you specify these parameters, using this procedure, any
query can reference the function.
Be sure to determine the potential effect of any change to a function
definition. If the function has been widely used, you may decide that a
new function is required. If not yet implemented or if the definition is
incorrect, simply change the definition and compile the affected queries.
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.
Chapter 3: Configuring KB_SQL for Your Site 39
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.
40 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 41
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.
42 KB_SQL Database Administrator’s Guide
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
Chapter 3: Configuring KB_SQL for Your Site 43
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
44 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 45
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
required
TEST(N,M)
where N, M are both integers
46 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 47
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.
48 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 49
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.)
50 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 51
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.
52 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 53
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.
54 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 55
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.
56 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 57
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.
58 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 59
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.
60 KB_SQL Database Administrator’s Guide
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
Chapter 3: Configuring KB_SQL for Your Site 61
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.
62 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 63
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.
64 KB_SQL Database Administrator’s Guide
Max global data length: integer (10)
Enter an integer value that represents the maximum number of
characters that may be stored as a data value in a global.
M Functions? YES/NO
If compiled query routines can take advantage of the $FNumber, $Get,
$Query, and $Name M functions, answer YES. If you answer NO, the
compiled routines will simulate the function.
M Commands? YES/NO
Answer YES if your M implementation supports the Merge command
and the Set $Extract(...)=value syntax. Otherwise, answer NO.
Protected variable list: character (65)
Enter a list of variable names separated by commas. These variables
will be preserved in all kill and exclusive kill commands. We will not
kill these variables on entry or exit of KB_SQL. However, we cannot
ensure that these variables will not be used internally by KB_SQL.
Therefore, we recommend that your list of variables be in the user-
defined range of SQLA* variable names.
Routine alter/save execute: character (65)
Use this prompt to call a program. The program will affect the M code
that KB_SQL generates from your queries. The program will be
executed after KB_SQL resolves all soft tag references and other
compile time variables. You will receive a local array to which you can
add code and then save. If you take responsibility for saving the
routine, you must kill the local array before returning to the caller. If
you encounter an error, you should return the SQLERR variable. If
you don’t save the routine, KB_SQL will save it using the logic in
SAVE^SQL0RI. You are responsible for the format of any lines that
you insert in the local array. All routine lines are of the form:
[tag]<space><Mcode>.
The routine array is in the format:
RTN=Name of routine
RTN(0)=Number of routine lines
RTN(n)=Routine line #n
Chapter 3: Configuring KB_SQL for Your Site 65
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].
66 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 67
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.
68 KB_SQL Database Administrator’s Guide
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]
Chapter 3: Configuring KB_SQL for Your Site 69
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.
70 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 71
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.
72 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 73
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.
74 KB_SQL Database Administrator’s Guide
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)
Chapter 3: Configuring KB_SQL for Your Site 75
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
76 KB_SQL Database Administrator’s Guide
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}"
Chapter 3: Configuring KB_SQL for Your Site 77
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.
78 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 79
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.
80 KB_SQL Database Administrator’s Guide
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)
Chapter 3: Configuring KB_SQL for Your Site 81
(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.
82 KB_SQL Database Administrator’s Guide
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
Chapter 3: Configuring KB_SQL for Your Site 83
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.
84 KB_SQL Database Administrator’s Guide
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
Chapter 3: Configuring KB_SQL for Your Site 85
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.
86 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 87
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
88 KB_SQL Database Administrator’s Guide
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
Chapter 3: Configuring KB_SQL for Your Site 89
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'.
90 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 91
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.
92 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 93
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.
94 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 95
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
96 KB_SQL Database Administrator’s Guide
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.
Chapter 3: Configuring KB_SQL for Your Site 97
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
98 KB_SQL Database Administrator’s Guide
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
Chapter 3: Configuring KB_SQL for Your Site 99
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 4: Managing Devices 100
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.
100 KB_SQL Database Administrator’s Guide
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.
102 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.
Chapter 4: Managing Devices 103
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)
104 KB_SQL Database Administrator’s Guide
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.
Chapter 4: Managing Devices 105
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
106 KB_SQL Database Administrator’s Guide
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.
Chapter 4: Managing Devices 107
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.
108 KB_SQL Database Administrator’s Guide
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
Chapter 4: Managing Devices 109
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.
110 KB_SQL Database Administrator’s Guide
Clear Entire Screen from Cursor
Clear Line from Cursor
Chapter 4: Managing Devices 111
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
112 KB_SQL Database Administrator’s Guide
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)
Chapter 4: Managing Devices 113
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
114 KB_SQL Database Administrator’s Guide
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
Chapter 4: Managing Devices 115
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
116 KB_SQL Database Administrator’s Guide
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
Chapter 4: Managing Devices 117
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
118 KB_SQL Database Administrator’s Guide
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
Chapter 4: Managing Devices 119
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
120 KB_SQL Database Administrator’s Guide
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.
Chapter 4: Managing Devices 121
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.
122 KB_SQL Database Administrator’s Guide
REPORTS Option
When you select the REPORTS option, the Select Reports window
appears.
Select REPORTS
Chapter 4: Managing Devices 123
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
124 KB_SQL Database Administrator’s Guide
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.
Chapter 4: Managing Devices 125
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
126 KB_SQL Database Administrator’s Guide
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.
Chapter 4: Managing Devices 127
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.
128 KB_SQL Database Administrator’s Guide
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.
Chapter 4: Managing Devices 129
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))
130 KB_SQL Database Administrator’s Guide
The Translation Routine
The typical input translation routine has sections for the functions
outlined below.
String Read
The string read is typically used in value windows. The determine
input function execute determines if any special input has been entered
and invokes the input translator. This sample code is typical of the
determine input function execute: IF <special terminator> THEN DO
<string read translation>.
P User input is in the variable N.
P Input terminators are available in vendor-specific variables.
P The routine should return the input function in the variable KIF.
Invalid function keys should be reported as follows:
P Set input function (KIF) = 0 and quit.
Chapter 4: Managing Devices 131
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.
132 KB_SQL Database Administrator’s Guide
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
Chapter 4: Managing Devices 133
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
134 KB_SQL Database Administrator’s Guide
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.
Chapter 4: Managing Devices 135
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
136 KB_SQL Database Administrator’s Guide
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_
Compressed
W *27,"(8U",*27,"(s0p16.66H8.5v0s0b0T"
,*27,"&l88p8D",*27,"&a10L"
S KFL=80,KFW=120
Landscape_Letter W *27,"&l10",*27,"(s0p10H"
S KFL=44,KFW=105
Landscape_
Compressed
W *27,"&l1o5.45C",*27,"(s0p16.66H"
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
Chapter 4: Managing Devices 137
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.
138 KB_SQL Database Administrator’s Guide
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.
Chapter 4: Managing Devices 139
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'
140 KB_SQL Database Administrator’s Guide
Chapter 5: Applying Security Measures 141
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.
142 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 143
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
144 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 145
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
146 KB_SQL Database Administrator’s Guide
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
Chapter 5: Applying Security Measures 147
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.
148 KB_SQL Database Administrator’s Guide
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
Chapter 5: Applying Security Measures 149
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
150 KB_SQL Database Administrator’s Guide
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
Chapter 5: Applying Security Measures 151
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.
152 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 153
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.
154 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 155
Edit
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.
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
156 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 157
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.
158 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 159
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].
160 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 161
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
162 KB_SQL Database Administrator’s Guide
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].
Chapter 5: Applying Security Measures 163
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].
164 KB_SQL Database Administrator’s Guide
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.
Add
If you have not defined any users, the Add User window will appear.
Select YES to add a user. Otherwise, if users exist, the Select, Insert,
Delete selection window will appear. You can press [insert] to add a
new user, or select the user you wish to edit. If you want to delete a
user, highlight it and press [delete].
Add a user record for each individual that is going to use KB_SQL.
This provides a method of tracking activity in the system. The DBA
should control the assignment of user names and passwords and keep a
list of all active users.
Chapter 5: Applying Security Measures 165
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.
166 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 167
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.
168 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 169
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
170 KB_SQL Database Administrator’s Guide
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
Chapter 5: Applying Security Measures 171
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
172 KB_SQL Database Administrator’s Guide
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.
Chapter 5: Applying Security Measures 173
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
174 KB_SQL Database Administrator’s Guide
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
Chapter 5: Applying Security Measures 175
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.
176 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 177
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.
178 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 179
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.
180 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 181
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 <query_name> to select a single query.
P Enter <partial match>* to select all queries that match the letters
supplied.
P Enter <from_query_name>:<thru_query_name> to select all queries
that fall within the range.
In the example below, 32 queries that begin with the letters DEMO
have been selected to be recompiled.
Stopping the Process
During each query compile, KB_SQL will display a series of messages.
If you need to halt the compilation process, you may press any key.
You will be given the chance to resume or end the process.
Stop Recompile
182 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 183
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.
184 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 185
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 <device_type_name> to select a single device type.
P Enter <partial match>* to select all device types that match the letters
supplied.
P Enter <from_device_type_name>:<thru_device_type_name> to select
all device types that fall within the range.
After you are finished selecting your device types, press [enter] at the
Device type name prompt and the cursor will fall to the Filename
prompt in the Output to File window.
186 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 187
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.
188 KB_SQL Database Administrator’s Guide
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 <query_name> to select a single query.
P Enter <partial match>* to select all queries that match the letters
supplied.
P Enter <from_query_name>:<thru_query_name> to select all queries
that fall within the range.
After you are finished selecting your queries, press [enter] at the Query
name prompt and the Output to File window will appear.
Chapter 6: Utilities 189
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.
190 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 191
Select Table
Table name: character (30) [list]
Supply a valid table name, or press [list] to select from a list of tables,
or you can use the following wild card selection method:
P Enter <table_name> to select a single table.
P Enter <partial match>* to select all tables that match the letters
supplied.
P Enter <from_table_name>:<thru_table_name> to select all tables that
fall within the range.
After you are finished selecting your tables for that schema, press
[enter]. The cursor will move to the Schema name prompt. You may
select another schema (and then tables to export) or you can press
[enter] and the Output to File window will appear.
192 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 193
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.
194 KB_SQL Database Administrator’s Guide
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
Chapter 6: Utilities 195
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.
196 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 197
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.
198 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 199
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 201
Lock Status
Locked? YES/NO
To lock, type YES; to unlock, type NO.
Reason: character (60)
Enter a reason for setting the lock.
200 KB_SQL Database Administrator’s Guide
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.
202 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.
Chapter 6: Utilities 203
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
204 KB_SQL Database Administrator’s Guide
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]
Chapter 6: Utilities 205
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
206 KB_SQL Database Administrator’s Guide
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].
Chapter 6: Utilities 207
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.
208 KB_SQL Database Administrator’s Guide
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
Chapter 6: Utilities 209
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.
210 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 211
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.
212 KB_SQL Database Administrator’s Guide
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.
Chapter 6: Utilities 213
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).
214 KB_SQL Database Administrator’s Guide
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 <object> imported
P <object> imported and overwritten
P <object> not imported (reason)
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
Chapter 6: Utilities 215
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)
216 KB_SQL Database Administrator’s Guide
217 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.
218 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
219 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.
220 KB_SQL Database Administrator’s Guide
221 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.
222 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.
Chapter 9: Transferring Data Dictionary Objects 223
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.
224 KB_SQL Database Administrator’s Guide
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
Chapter 9: Transferring Data Dictionary Objects 225
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
_MULTI
6 Import object definitions from global using
multiple steps
226 KB_SQL Database Administrator’s Guide
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.
Chapter 9: Transferring Data Dictionary Objects 227
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
228 KB_SQL Database Administrator’s Guide
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
Chapter 9: Transferring Data Dictionary Objects 229
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
230 KB_SQL Database Administrator’s Guide
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
Chapter 10: External Interfaces 231
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.
232 KB_SQL Database Administrator’s Guide
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
Chapter 10: External Interfaces 233
The DDLI interface requires that you supply the following variables:
234 KB_SQL Database Administrator’s Guide
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.
Chapter 10: External Interfaces 235
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
236 KB_SQL Database Administrator’s Guide
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
Chapter 10: External Interfaces 237
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 241
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.
242 KB_SQL Database Administrator’s Guide
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
Chapter 10: External Interfaces 243
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
244 KB_SQL Database Administrator’s Guide
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
Chapter 10: External Interfaces 245
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
246 KB_SQL Database Administrator’s Guide
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.
Chapter 11: Miscellaneous Interfaces 247
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
248 KB_SQL Database Administrator’s Guide
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.)
Chapter 11: Miscellaneous Interfaces 249
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
250 KB_SQL Database Administrator’s Guide
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
Chapter 11: Miscellaneous Interfaces 251
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
252 KB_SQL Database Administrator’s Guide
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.
Chapter 11: Miscellaneous Interfaces 253
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
254 KB_SQL Database Administrator’s Guide
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.
Chapter 11: Miscellaneous Interfaces 255
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
256 KB_SQL Database Administrator’s Guide
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
Chapter 11: Miscellaneous Interfaces 257
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
258 KB_SQL Database Administrator’s Guide
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
Chapter 11: Miscellaneous Interfaces 259
System Tools
The remaining tools are used throughout KB_SQL.
JOB^SQL0H
This entry point will start a background job using the variable RTN. In
the following example, a background job will be started at tag GO of
the XYZ routine.
> S RTN="GO^XYZ"
> D JOB^SQL0H
> I FAIL S SQLERR="Unable to start job "_RTN W $C(7),!,SQLERR
> Q
TRAP^SQL0H
This entry point can be called to set an error trap. For example,
KB_SQL can set and clear error traps, while users branch between
menu options. The following example specifies GO^ROUTINE as the
starting point and ERR^ROUTINE as the error trap point. Any errors
encountered will be trapped to the ERR tag.
> S SQLTRAP(0)="ERR^ROUTINE"
> S SQLTRAP(1)="GO^ROUTINE"
> G TRAP^SQL0H
> ;
> GO<TAB>; entry point
> ;
> ERR<TAB>; error processing point
> Q
260 KB_SQL Database Administrator’s Guide
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
Chapter 11: Miscellaneous Interfaces 261
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
262 KB_SQL Database Administrator’s Guide
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
MM/DD (2) 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.
Chapter 11: Miscellaneous Interfaces 263
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
264 KB_SQL Database Administrator’s Guide
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)
Chapter 11: Miscellaneous Interfaces 265
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)
266 KB_SQL Database Administrator’s Guide
The SQL0GI Routine
This routine will restore a global that was saved in the KB_SQL global
transfer format.
; Global save on <date> at <time>
; KB_SQL <version>
name-1st
value-1st
name-2nd
value-2nd
.
.
.
name-last
value-last
<NULL>
<EOF>
This routine can be used to restore a global that was saved in the
KB_SQL global transfer format as described above.
> D ^SQL0GI
Filename: A:SQLGBL.2
Or, for automatic loading:
> S SQLFILE="A:SQLGBL.2"
> D AUTO^SQL0GI
Chapter 11: Miscellaneous Interfaces 267
The SQL0RI Routine
This routine will restore a set of M routines that was saved in the
KB_SQL routine transfer format. To build your own routine export
file, follow the format below.
; Routine save on <date> at <time>
; KB_SQL <version>
routine name
line #1
line #2
.
.
line #N
<NULL>
routine name
line #1
line #2
.
.
line #N
<NULL>
<NULL>
<EOF>
To run SQL0RI:
> D ^SQL0RI
Filename: A:SQLRTN.2
Or, for automatic loading: > S SQLFILE="A:SQLRTN.2"
> D AUTO^SQL0RI
268 KB_SQL Database Administrator’s Guide
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
Chapter 11: Miscellaneous Interfaces 269
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
270 KB_SQL Database Administrator’s Guide
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
Chapter 11: Miscellaneous Interfaces 271
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
Appendix A: The Integrity Check A-1
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.
A-2 KB_SQL Database Administrator’s Guide
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.
Appendix A: The Integrity Check A-3
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
columns
Record as a follow-up
issue
REQD*
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.
A-4 KB_SQL Database Administrator’s Guide
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].
Appendix A: The Integrity Check A-5
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.
A-6 KB_SQL Database Administrator’s Guide
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.
Appendix A: The Integrity Check A-7
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
A-8 KB_SQL Database Administrator’s Guide
ADD SCHEMA index -1 2
TABLE index -1 1
TABLE index -8 1
DROP TABLE index -1 1
TABLE index -8 1
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
-----------------------------------------------------------------------------
End>
*** NOTE: REQD errors can not be automatically fixed ***
Page 1>
Appendix A: The Integrity Check A-9
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
A-10 KB_SQL Database Administrator’s Guide
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.
Appendix A: The Integrity Check A-11
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.
A-12 KB_SQL Database Administrator’s Guide
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")=<error_coun t>
^SQLIC("CHECK","ERROR_LOG",<error_#>)=< text>
This section gives you the total number of errors and then lists each
error number and its corresponding text. This section includes
executable M code to add/drop indexes and make other database
corrections. It is referenced by the FIX logic.
^SQLIC("CHECK","SUMMARY",<type>)=<count>
This section gives you a summary of errors by type. Types include
index adds, drops, required columns, fkey columns, and others.
^SQLIC("CHECK","SUMMARY",<type>,<gblref>)=<count>
This section provides more detail for the summary. The global
reference indicates which particular index table structure was added or
dropped.
^SQLIC("CHECK","WORKING")=#;TableName
This level stores the number and name of the table that is currently
being checked.
Appendix B: The H andling of N ull Values B-1
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
B-2 KB_SQL Database Administrator’s Guide
Let A and B be comparable database objects.
If A is null or B is null or both A and B are null, then (in the context of
a WHERE or HAVING clause) each of the following expressions
evaluates to the unknown truth-value (i.e., not true and not false). If a
predicate includes a null value, the associated row will not be included
in the query result.
A=B
A<>B
A<B
A<=B
A>B
A>=B
Two special predicates, <value> IS NULL and <value> IS NOT
NULL, are provided for testing to see whether a given value is defined.
According to KB_SQL
KB_SQL allows you to control how null values are handled. By
default, KB_SQL is configured to be consistent with the ANSI SQL
definition.
Expressions that include a null value will return a null result.
You can choose to treat the value as the empty string. This would treat
null values in a manner consistent with M logic rules. This makes
KB_SQL more like M, but may frustrate seasoned SQL users.
Appendix B: The H andling of N ull Values B-3
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.
B-4 KB_SQL Database Administrator’s Guide
Index I-1
IN DEX
^
^SQL entry point, 246, 248
^SQL global, 22
^SQLCHG global, 24
^SQLCK global, 22
^SQLCUR global, 22
^SQLEMP global, 24
^SQLEMPN global, 24
^SQLEX global, 22, 227
^SQLIC global, 22
^SQLIN global, 22
^SQLIX global, 22, 227
^SQLJ global, 22
^SQLL global, 22
^SQLP global, 22
^SQLPROJ global, 24
^SQLQ global, 22
^SQLRD global, 22
^SQLS global, 22
^SQLT global, 22
^SQLXQ global, 22
A
A1^SQL0FC entry point, 264
A12^SQL0FC entry point,
264
A13^SQL0FC entry point,
264
A2^SQL0FC entry point, 264
A23^SQL0FC entry point,
264
A3^SQL0FC entry point, 264
A34^SQL0FC entry point,
264
A4^SQL0FC entry point, 264
ACCESS PLAN INFO option,
68
Add Subtypes window, 112
Add User Group window, 154
ADDRESS INFO option, 55
Address line 1 prompt, 56
Address line 2 prompt, 56
Address line 3 prompt, 56
Address line 4 prompt, 56
Allow connections prompt, 79
Allow multiple jobs per user
prompt, 71
Allow renewal after
expiration prompt, 166
ANSI INFO option, 60
API calls
trace, 79
ATTRIBUTES option, 106
AUTO^SQLI, A-2
Auto select if one match
prompt, 59
Avg distinct prompt, 210
B
Background colors
setting, 118
Background job
starting, 258
Background queue manager
start date values for, 95,
96
BACKGROUND QUEUE
option, 198
Background Task Information
window, 71
BACKGROUND TASKS
option, 71
BASE ROUTINE EDIT
option, 4, 27
Base Routine Information
window, 28
Base routine prefixes, 27
BASE ROUTINE PRINT
option, 99
Base routines, 27
adding, 27
deleting, 28
editing, 28
sample configuration,
29
BC^SQL, 243, 244, 246, 248
Bold ON/OFF windows, 106
Bottom margin prompt, 75
Box codes, 105
BOX CODES option, 104
Box Drawing Codes window,
105
Break at table prompt, 17
Buffer size
input, 81
output, 81
Build number prompt, 222
C
Cartesian products
handling of queries
with, 70
Change job back to original
priority execute prompt, 67
Change job to low priority
execute prompt, 67
Change User Password
window, 167
CHECK^SQLI, A-2
CHECK QUERY option, 91
Class prompt
in Device Type window,
104
in Subtype of window,
113
Clear Entire Screen (or
Pagefeed) window, 109
Clear Entire Screen from
Cursor window, 110
Clear Line from Cursor
window, 110
I-2 KB_SQL Database Administrator’s Guide
IN DEX
Clear operations
supplying logic for, 108
Clearing jobs, 197
Clients and server
dialog between, 79 CLOSE^SQL0H, 254, 255
Compiling queries
related messages, 182
selecting, 181
stopping the process,
181 Compiling statistics, 244
D
Data
exporting it, 33
importing it, 46
CLOSE EXECUTE option,
116
Colors
setting, 118, 169
Command Qualifications
window, 170
COMMIT PROMPT option,
92
COMP^SQL, 239, 246, 248
COMPILE^SQL, 241, 246,
249
Compile-time M Code
window, 41
COMPILE ALL QUERIES
option, 8, 178
Compile all tables prompt,
205
Compile only tables in use by
queries prompt, 205
Compile only tables without
statistics prompt, 205
COMPILE QUERIES option,
198
COMPILE QUERY LOG
option, 213
COMPILE STATISTICS
LOG option, 213
COMPILE STATISTICS
option, 202, 204
Compile Statistics window,
204
Compile tables with statistics
older than prompt, 205
Compiled query
executing a, 259
Configuration menu options,
4
CONFIGURATION option,
25
for DBA, 4
for sysmgr, 16
Confirm password prompt,
167
Connecting to the server, 79
Cost of query
error/warning if
exceeds, 66
Current Privileges window,
159, 162
Current prompt, 29
Cursor movements
supplying logic for, 108
Custom device close execute
prompt, 87
in Device Definition
window, 121
Custom device open execute
prompt, 87
in Device Definition
window, 121
Custom device selection
execute prompt, 86
Custom header code execute
prompt, 76
Custom Logic #1 window, 84
Custom Logic #2 window, 84
CUSTOM LOGIC option, 84,
114
Customizing KB_SQL, 25
Data access plan
showing, 59
Data dictionary
menu options, 5
Data dictionary objects
transferring, 223
DATA DICTIONARY option
for DBA, 5
for sysmgr, 16
Database administrator
see DBA
DATE/TIME LIMITS option,
65
Date conversion routine, 259,
260
see also SQL0DT
routine
Date conversion utility, 259
DATE data type
output formats for, 58
Date domain conversions, 263
Date input prompt, 58
Date output prompt, 58
Dates
output formats for, 262
prompting for, 72
setting the start date,
138
specifying display
formats for, 58
specifying input formats
for, 58
valid input formats, 270
DBA menu, 3
DBA password, 3
Index I-3
DBA responsibilities, 2
I-4 KB_SQL Database Administrator’s Guide
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
Index I-5
IN DEX
Domain prompt
in Pseudo Column
Information window,
52
Downloading data, 4, 33
DTYPE^SQL, 246, 249
E
Echo ON/OFF windows, 107
Edit list of available schemas
prompt, 77
Edit network configuration
prompt, 79
Edit queries prompt, 168
EM^SQL, 246
Enable quickview feature
prompt, 69
Encrypting passwords, 171
END^SQL, 246
End of File Check Execute
window
and the Export Method
Edit option, 36
and the Import Method
Edit option, 49
Entry points, 248, 251
for SQL0DT routine,
260
for SQL0FC routine,
264
for SQL0H routine, 254
for SQL0TS routine,
269
see also SQL entry
points
EP^SQL, 246
ER^SQL, 246, 249
ERROR LOG PRINT option,
214
Error rows
rejecting, 60
Error trap
setting, 258
Errors
display of M, 219
trapped by the system,
91
Examine system status
prompt, 218
Example
in Function Information
window, 40
Exceptions
display of, 219
Export
device types, 184
examples of, 228, 229
functions, 184
pseudo columns, 184
queries, 187
query output, 33, 34
tables, 190
Export all device types
prompt, 184
Export and import functions
in a stand-alone
environment, 57
Export device types edited
after prompt, 184
Export Device Types window,
184
EXPORT METHOD EDIT
option, 4, 33
EXPORT METHOD PRINT
option, 99
Export method prompt, 58
Export Method window, 34
Export methods
defining them, 33
EXPORT option, 8, 183
Export strategies, 223
EZQ Editor
the DBA’s role in
introducing it to
users, 11
EZQ EDITOR option, 3
EZQ Editor tutorial, 12
EZQ only prompt, 168
EZQ password, 19
EZQ password menu, 20
EZQ queries
importing, 195
F
Fail prepares with Cartesian
Products prompt, 70
Fail prepares without table
statistics prompt, 70
Filename prompt
for exporting a device
type, 186
for exporting a query,
189
for exporting a table,
192
FIX^SQLI, A-2, A-8
Foreground colors
setting, 118
Foreground only prompt, 120
Formatting character strings,
257
FROM_GLOBAL_MULTI
TRANSFER method, 226
From name prompt
in Query Names
window, 157
From table name prompt
in Print Tables window,
17
in Table Name window,
160
I-6 KB_SQL Database Administrator’s Guide
IN DEX
FUNCTION EDIT option, 4,
37
Function Information
window, 39
Function Name window, 38
FUNCTION PRINT option,
99
Functions
adding, 38
deleting, 38
editing, 38
transferring, 224, 226
using, 43
FUZZY DENSITY EDIT
option, 206
Fuzzy Density Information
window, 207
FUZZY DENSITY PRINT
option, 212
FUZZY SIZE EDIT option,
208
Fuzzy Size Information
window, 209
FUZZY SIZE PRINT option,
212
G
GENERATE ROUTINE
option, 94
Globals
demonstration, 24
essential to operation of
KB_SQL, 22
for transfer utility, 227
printing, 17
restoring them, 265
transferring them, 226
GRANT statement, 142, 144
Granting privileges
examples of, 145, 146
Graphics ON/OFF windows,
107
GROUP EDIT option, 7, 153
Group Information window,
154
Group Name window, 154
GROUP PRINT option, 175
Group prompt, 165
H
Halt check, 66, 93
HALT QUERY option, 8, 193
Halt Query window, 193
Header, 75, 76
Host device prompt, 120
Host file end-of-row
terminator prompt, 63
Host file I/O, 255
HOST FILE NAME option,
89
Host File Name window
for Import option, 196
Host name prompt, 81
Hosts
defining, 81
How many queues prompt, 71
I
I2^SQL0FC entry point, 264
IL^SQL0H, 254, 256
Import
data to tables, 46
examples of, 230
IMPORT METHOD EDIT
option, 4, 46
IMPORT METHOD PRINT
option, 99
Import method prompt, 58
Import Method window, 47
IMPORT option, 8, 194
Import strategies, 223
Import TABLE window, 195
IMPORT TRANSACTIONS
option, 214
Include null values in group
and order by clauses
prompt, 61
INI^SQL, 246
Initial execute code prompt,
72
Inline function prompt
in Function Information
window, 40
Input buffer size prompt, 81
Input function codes, 126
Input function translation,
117
Input functions, 125
translating them, 126
INPUT translation checklist,
129
Input translation routine
examples of, 132, 133
initialization, 131
single character read,
131
string read, 130
supplying, 124
termination, 131
INSERT command, 46
rejecting error rows, 60
Insert prompt, 162
Integrity Check, A-1
customizing it, A-6
scheduling it, A-11
starting it, A-4, A-5
suppressing messages,
A-6
INTEGRITY CHECK
ERRORS option, 212
Interactive device types, 124
Internal routines, 245
Index I-7
IN DEX
IP address prompt, 81
Isolation level, 62
IUL^SQL0H, 254, 256
J
JOB^SQL0H, 254, 258
JOB COMMAND option, 94
Job priority, 67
JOB variable, 236
JOB WATCH option, 8, 197
JOBD variable, 73
JOBQ variable, 73
JOBR variable, 73
JOBT variable, 73
JOBV variable, 73
JOBX variable, 73
K
KB_SQL
restricting access to,
141
using locks to restrict
access to, 199
KB_SQL user interface
calling a query directly,
236
KB_SQL Version Information
window, 10, 222
KDATE variable, 236
KDE variable, 259
KDF variable, 259
KDI variable, 259
KEY FORMAT EDIT option,
5
KEY TOPS option, 111
Key Tops window, 111
Keys
max. number of, 66
KFL variable, 88
KIF variable, 88
KME variable, 268
KMF variable, 268
KMFT variable, 268
KMI variable, 268
KO(27) variable, 87
KO(4) variable, 87
KTIME variable, 236
L
LC^SQL0H, 254, 257
Left margin prompt, 74
Length prompt
in Function Information
window, 40
in Pseudo Column
Information window,
53
Limit search prompt, 168
Limits
search, 168
select, 168
Local host prompt, 82
Local hosts
defining, 81
LOCK entry points, 256
LOCK STATUS option, 8,
198
Lock Status window, 200
Locked prompt, 200
Locks, 198, 199, 253
display of, 219
Log-off users after:
seconds prompt, 65
LOG ERROR option, 91
LOGICAL DEVICE EDIT
option, 6, 101, 119
LOGICAL DEVICE PRINT
option, 123
Lower query priority after:
seconds prompt, 66
Lowercase
formatting in, 257
M
M Commands
Merge prompt, 64
Set $Extract prompt, 64
M errors
display of, 219
M Execute window, 96
M Expression prompt
in Pseudo Column
Information window,
53
M Functions
$FNumber prompt, 64
$Get prompt, 64
$Name prompt, 64
$Query prompt, 64
M INFO option, 63
M process
removing, 197
M routines
restoring them, 266
M string
max. length of, 80
MANUAL STATISTICS
option, 202, 210
Manual Table Statistics
window, 210
MAP EXISTING GLOBALS
option, 5
Margins, 74, 75
Max global data length
prompt, 64
Maximum counter prompt, 28
Maximum length for sort keys
prompt, 62
Maximum length for SQL
identifiers prompt, 62
Maximum length of M string
prompt, 80
I-8 KB_SQL Database Administrator’s Guide
IN DEX
Maximum number of keys
prompt, 66
Maximum routine size
prompt, 63
Maximum stored queries
prompt, 78
MC^SQL0TS entry point, 269
ME^SQL0TS entry point, 269
MEMBER PRINT option, 175
MGR password, 14
MI^SQL0TS entry point, 269
MOMENT data type
perform conversions
for, 268
Moment separator prompt, 59
Moment time first prompt, 59
Moment values
converting, 269
Must run in foreground
prompt
in the Export Method
window, 34
in the Import Method
window, 47
N
Name prompt
in Current Privileges
window, 162
in Device Type window,
103
in Export Method
window, 34
in Function Information
window, 39
in Fuzzy Density
Information window,
207
in Fuzzy Size
Information window,
209
in Import Method
window, 47
in Pseudo Column
Information window,
52
in Start Date
Information window,
96
in Subtype of window,
113
Network configuration
editing, 79, 80
New password prompt, 167
NOTRAP^SQL, 246, 250
Null values, 61
handling of, Appendix
B
O
Object Types window, 156,
171
OPEN^SQL0H, 254, 255
OPEN EXECUTE option, 115
Order by reduction factor
prompt, 69
Output buffer size prompt, 81
Output device
assigning one, 98
OUTPUT FORMAT EDIT
option, 5
Output to File window
for exporting a device
type, 186
for exporting a query,
189
for exporting a table,
192
P
PAGE LAYOUT option, 74
Page Layout Parameters
window, 74
Parse check routine, 44
Parse check routine prompt
in Function Information
window, 39
Password, 143
assigning to a user, 166
encrypting, 171
for DBA, 3
for EZQ users, 20
for SysMgr, 14
for USERS user group,
19
Password expire days prompt,
60, 166
Password expires on prompt,
166
Password prompt, 166
Password warning days
prompt, 60
Perform halt check after:
rows prompt, 66
Perform halt check after
rows prompt, 93
Perform ROW commit
prompt, 60
Plan Information window, 68
Populating tables, 46
Port number prompt, 83
POSITION & CLEAR option,
108
Position & Clear window, 108
Position Cursor & Clear Line
window, 109
Position Cursor & Clear
Screen window, 109
Position Cursor window, 108
Index I-9
IN DEX
Post Process Execute window,
36, 49
Pre Process Execute window,
35, 48
Predicate reduction factor
prompt, 69
Prefix
of routine, 27, 28
Prefix for stored query
routines prompt, 78
Preserve Old Statistics
window, 196
Preserve table statistics
prompt, 196
Primary key definition
for calculating
statistics, 201
Print Base Routines window,
98
Print Device Names window,
123
Print Device Specifications
window, 123
Print globals prompt, 17
Print on Device window, 135
for Configuration
reports, 98
for Security reports, 174
for Utility reports, 211
Print Query Directory
window, 211
Print spool, 138
Print Tables window, 16
Print User Groups window,
174
Printing strategies, 134
Priority
changing, 67
lowering, 66
Privileges
changing them, 160
granting and revoking,
144
granting to all users,
172
listing, 173
to queries, 146, 158
to tables, 145, 158
to views, 147, 158
viewing them, 160
Programmer
designating a user as a,
14, 168
Programmer prompt, 168
Prompt for file prompt
in Export Method
window, 34
in Import Method
window, 47
Prompt for start date/time
prompt, 72
Protected variable list prompt,
64
Pseudo column
adding, 51
definition of, 50
deleting, 51
editing, 51
transferring, 224, 226
PSEUDO COLUMN EDIT
option, 4, 50
Pseudo Column Information
window, 52
Pseudo Column Name
window, 51
PSEUDO COLUMN PRINT
option, 100
Public privileges
modifying, 172
warning for, 171
PUBLIC PRIVILEGES
option, 7, 171
PUBLIC QUERY
PRIVILEGES option, 175
PUBLIC TABLE
PRIVILEGES option, 176
PUBLIC user, 171
Q
Qualifications, 143
Query
privileges, 146
running in background,
238
running on a terminal,
237
scheduling the
processing of, 138
stopping the execution
of, 193
transferring, 224, 226
Query base routine prompt,
155
Query Compile window, 179
Query definition
compiling, 241
compiling a set of, 243
creating, 240
deleting, 242
QUERY DIRECTORY
option, 212
Query halt check, 93
Query name prompt
in Current Privileges
window, 159
in Recompile Query
window, 180
in Select Query
window, 188
Query Names window, 157
Query object
availability of, 91
QUERY PRINT option, 212
I-10 KB_SQL Database Administrator’s Guide
IN DEX
Query priority, 66
Query privileges, 158
changing, 157
viewing, 157
QUERY PRIVILEGES
option, 175
Query queue
display of, 219
Query routines
assigning names, 30
running compiled
routines, 232
running them, 233
Query transactions
display of, 219
QUERY TRANSACTIONS
option, 214
Queue manager override code
prompt, 73
Quickview feature, 69
R
READ^SQL0H, 254, 255
Read One Character into
Variable 'A' window, 117
Reason prompt, 200
Recompile only edited queries
prompt, 179
Recompile Query window,
180
Rejecting rows with errors, 60
Remote hosts
defining, 81
Replace if exists prompt, 186,
189, 192
Report parameters
for CONFIGURATION
reports, 98
REPORTS option
in CONFIGURATION
menu, 5, 97
in DATA
DICTIONARY menu,
6
in SECURITY menu, 7,
173
in
TERMINALS/PRINT
ERS menu, 6, 122
in UTILITIES menu, 9,
211
RESET^SQL, 246, 250, A-10
Reset Device Parameters
when Closed window, 116
Result domain prompt
in Function Information
window, 40
Return null for expressions
that contain null prompt,
61
Reverse sorting, 257
REVOKE statement, 142, 144
Revoking privileges
examples of, 145, 146
Right margin prompt, 74
ROLL_UP device type, 127
input translation, 127
Routine alter/save execute
prompt, 64
ROUTINE NAME option, 89
Routine names
assigning prefix for, 78
Routine prefix prompt, 28
Routine prompt
in Device Type window,
104
in Subtype of window,
113
Routines
SQL0CHK, 259
SQL0DT, 259
SQL0FC, 264
SQL0GI, 265
SQL0H, 254
SQL0RI, 266
SQL0TM, 267
SQL0TS, 268
table of essential ones,
23
Row commit
setting at query level,
60
setting at site level, 60
Row Execute window, 35, 48
Row level locking
and the MANUAL
STATISTICS option,
202
when compiling
queries, 178
when compiling
statistics, 202
when exporting, 183
when importing, 194
Row locking, 256
RQM^SQL, 247, 251
RS^SQL0H, 254, 257
RUN^SQL, 233, 247, 251
RUN CHECK option, 93
RUN password, 19
RUN password menu, 20
Run queries in background
prompt, 71
Running a KB_SQL query
routine, 233
on a printer in
background, 238
on a terminal, 237
RUNQ^SQL, 234, 247, 251
Runtime routine prompt, 41
Runtime Routine window, 41
S
Sample size prompt, 204
Index I-11
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
I-12 KB_SQL Database Administrator’s Guide
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
Index I-13
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
I-14 KB_SQL Database Administrator’s Guide
IN DEX
for sysmgr, 18
System Status Options
window, 218
System Status window,
60,218
T
Table
populating, 46
privileges, 145
transferring, 224, 226
Table density prompt, 210
Table name prompt
in Select Table window,
191
Table Names window, 160
Table privileges
changing them, 160
viewing them, 160
TABLE PRIVILEGES option,
175
Table statistics
calculating, 201
choosing a method for
calculating, 201
handling of tables
without, 70
preserving, 196
Table transactions
display of, 219
TABLE TRANSACTIONS
option, 215
TCP/IP defaults, 80
editing, 79, 80
TCP/IP Defaults window, 79,
80
TCP Host Information
window, 81
TCP Ports window, 83
listing, 83
Terminal emulators, 137
Terminal execute code
prompt, 72
TERMINALS/PRINTERS
option
for DBA, 6
TERMINALS / PRINTERS
option
for sysmgr, 17
Terminate jobs, 197
Thru name prompt
in Query Names
window, 157
Thru table name prompt
in Print Tables window,
17
in Table Name window,
160
Time
prompt for starting, 72
setting the start time,
138
specifying display
format for, 58
valid input formats, 270
Time conversion utility, 267
TIME data type
output formats for, 58
Time output prompt, 58
Time stamp, 59
Timeout for read commands
prompt, 80
Timeout in SQL Editor after:
seconds prompt, 65
Top margin prompt, 74
Trace API calls prompt, 79
TRANSACTION LOGS
option, 213
Transfer combinations, 226
Transfer methods, 224, 225
Transfer utility, 227
example of, 228
Transferring data, 33
Transferring objects, 223, 224
TRAP^SQL0H, 254, 258
Tutorial issues, 12
TYPE INFO option, 103
TYPE INFO option (for
subtypes), 113
U
UC^SQL0H, 254, 257
UNDO^SQL entry point, 197,
247
UNLOCK entry points, 256
Update (edit) prompt, 159
UPDATE command
rejecting error rows, 60
Update prompt, 163
Uploading data, 4
Uppercase
formatting in, 257
Use colors prompt, 169
User
adding, 164
definition of, 142
deleting, 165
editing, 165
USER EDIT option, 7, 164
User functions
creating, 4
User group
adding, 153, 154
DBAS, 1, 2
definition, 142
deleting, 156
editing, 155
privileges, 156, 157
security for, 142
SYS_MGRS, 1, 14
USERS, 1, 19
User group prompt, 154
USER ID option, 85
User information
Index I-15
IN DEX
adding, 164
User Information window,
165
User name prompt, 165
USER option, 199
USER password, 19
USER password menu, 20
USER PRINT option, 176
User profile checklist, 13
USER SIGNON option, 90
User table
and PUBLIC
permissions, 171
Utilities menu options, 8
UTILITIES option
for DBA, 8
for sysmgr, 18
VT100 device type
input functions for, 128
W
W/ option prompt, 159
in Current Privileges
window, 163
Warning Bell window, 107
Wild card selection method
for selecting queries,
181
Window box codes, 105
Window Colors window, 169
X
XFER^SQL, 227, 247, 253
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