KB SQL Database Administrator Guide

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


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


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


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.


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.


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.


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.


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


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.


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.



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.


of the TERMINALS / PRINTERS options.


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.


of the SECURITY options.


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.


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.


VERSION IN FORMATION Option

VERSION INFORMATION displays information about the customer

and the KB_SQL product.

KB_SQL Version Information


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.


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.


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


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.


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.


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.


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.


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.


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


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.


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


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.


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.


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.


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.


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


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.


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


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].


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.


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.


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.)


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.)


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].


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.


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.


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.


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.


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.


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


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


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.


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


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.


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.


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.


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.



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.)


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.


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.


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.


Each pseudo column must have a name to identify it within the SQL

syntax. The name must be a valid SQL_IDENTIFIER.


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.


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.


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.


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.


Site Address Information

Address line 1: character (40)

The first line of the site address (e.g., 10000 South Michigan Ave).


The second line of the site address (e.g., Suite 500).


The third line of the site address (e.g., Lansing, MI 48917).


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.


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.


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.


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.


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


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.


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.


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.


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


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].


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.


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.


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]


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.


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.


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.


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.


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.


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)


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


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}"


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.


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.


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.


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)


(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.



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


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.


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


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.


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.


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


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


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'.


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.


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.


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.


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.


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.


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


Start D ate Information


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.


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.


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


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


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.


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.


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.


D evice Type Options

TYPE IN FO Option

Device Type


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)


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.


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.


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


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.


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.


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).



Position & Clear

Position Cursor


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.


Clear Entire Screen from Cursor

Clear Line from Cursor


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


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)


TYPE IN FO Option (for Subtypes)

Subtype of ...


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.


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


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.



Device Executes

OPEN EXECUTE Option


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


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


option will override this code. Reset D evice Parameters when Closed


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


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


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


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.


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.


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



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




REPORTS Option

When you select the REPORTS option, the Select Reports window

appears.

Select REPORTS


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


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.


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


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.


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.


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.


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))


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.


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.


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


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


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.


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


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


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.


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.


The KB_SQL print spool handles regularly scheduled tasks as well as one-

time tasks.

Examples:

To run a task every day, include the following statement in your query:

SET START_DATE='ALL'

To run a task on Fridays, include the following statement in your query:

SET START_DATE='FRIDAY'


Chapter 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.


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.


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


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.


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


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


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.


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


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


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


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.


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.


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.


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.


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


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.


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.


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.


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].


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.


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


Current Privileges

Note: Tables and views can have select, insert, update, delete, and

with_option privileges.


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].


Update? YES/NO

If you want this user group to be able to update rows in the table, type


Delete? YES/NO

If you want this user group to be able to delete rows in the table, type


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].


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.


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.


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.


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.


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.


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


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


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


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.


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


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


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.


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.


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.


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.


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.


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


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.


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.


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.


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.


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.


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.


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.


Ouput to File




conventions.


Answer YES if you wish to overwrite an existing file. Otherwise,

answer NO.


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.


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.


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.


Output to File




conventions.


Answer YES if you wish to overwrite an existing file. Otherwise,

answer NO.


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.


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


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.


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.


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.


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.


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.


Lock Status

Locked? YES/NO

To lock, type YES; to unlock, type NO.

Reason: character (60)

Enter a reason for setting the lock.


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.


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




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





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


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.



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


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].


Select, Insert, D elete Fuzzy D ensity

Fuzzy Density Information


Supply a name for logical reference to the fuzzy density value.


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.


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


Fuzzy Size Information


Supply a name for logical reference to the fuzzy size value.


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.


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.


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.


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.


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).


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


TABLE TRAN SACTION S Option

This report produces a listing of all table transactions for a


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


P date, time, user

P view name

P type (CREATE, ALTER, DROP)



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.


System Status

If you answer YES to the Examine system status prompt, the System

Status Options menu appears.

System Status Options


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.



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.



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.


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


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


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.


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


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


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


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


D END^SQL

Q


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


S SQLOW=""

S SQLXTO="TABLE"

S SQLXTM="FROM_FILE"

S SQLFILE="C:\TEMP\TEST.DD"

D XFER^SQL


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


S SQLOW=""

S SQLXTO="QUERY"

S SQLXTM="FROM_FILE"

S SQLFILE="C:\TEMP\TEST.Q"

D XFER^SQL


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.


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:


SQLERR Error message (if defined)

SQLSEA Number of rows searched

SQLSEL Number of rows selected

SQLPAGE Number of pages output


SQLUSER User password

SQLCODE Returns status information


The DDLI interface requires that you supply the following variables:


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


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.


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 SQLDEV="PRINTER_HPIIP"

S SQLDTYP2="PORTRAIT_COMPRESSED"

D RUNQ^SQL

I $D(SQLERR) W !,*7,SQLERR


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 SQLDEV="0"

S SQLDTYPE="VT220"

S SQLDTYP2="132_COLUMN"

D RUNQ^SQL

I $D(SQLERR) W !,*7,SQLERR


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.


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).


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


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.


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


D COMPILE^SQL


D END^SQL

Q


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


D DELETE^SQL


D END^SQL

Q


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


D END^SQL

Q

Special options can be controlled by setting the following control

variables.


SQLRE Compile only edited queries S SQLRE=1

SQLRC Compile ALL queries S SQLRC=1


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


D END^SQL

Q

Special options can be controlled by setting the following control

variable.


SQLSS Sample Size S SQLSS=1000


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


DELETE^SQL Deletes an existing KB_SQL query


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



RUN^SQL Runs a query from outside the KB_SQL environment


RUNQ^SQL Provides a non-interactive interface for running

compiled queries


SAVE^SQL Saves an array of SQL text into a KB_SQL query


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.)


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


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


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


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


> D RQM^SQL


> 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.


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


SYSLOCK^SQL

****** IMPORTANT EXTERNAL ROUTINE ******

This entry point can be used to view and edit the status of the system

locks.

> K


> D SYSLOCK^SQL


> 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.


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


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


> Q

READ^SQL0H

> S SQLFILE="A:DEMO.Q"

> D READ^SQL0H


> Q


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


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


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


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


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


Entry Points

The following entry points are called to convert dates.


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


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.


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


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)


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.


A1^SQL0FC 1 argument required

LENGTH(NAME)

A12^SQL0FC 1-2 arguments

RPAD(NAME)

RPAD(NAME,'*')


EXTRACT(NAME)

EXTRACT(NAME,3)

EXTRACT(NAME,1,20)

A2^SQL0FC 2 arguments required

MINIMUM(X,Y)


FIND(NAME,'X')

FIND(NAME,'X',10)


AREA(LENGTH,WIDTH,HEIGHT)


DRG(DX,AGE,SEX)

DRG(DX,AGE,SEX,OTHER)


TIME(MILES,STOPS,MPH,STOPTIME)

I2^SQL0FC 2 integer arguments required

ANGLE(HEIGHT,SLOPE)


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


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


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


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


Entry Points

The following entry points are called to convert moment values.


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


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.


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.


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].


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.


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.


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.


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


> Q


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>


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


> Q


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.


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.


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


264



264



264


ACCESS PLAN INFO option,

68

Add Subtypes window, 112

Add User Group window, 154

ADDRESS INFO option, 55

Address line 1 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


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


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


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


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


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


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


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


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


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


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


103

in Export Method

window, 34


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


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


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


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


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


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


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


window, 40

Return null for expressions

that contain null prompt,

61

Reverse sorting, 257

REVOKE statement, 142, 144

Revoking privileges


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


104


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


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


IN DEX

for sysmgr, 18

System Status Options

window, 218

System Status window,

60,218

T

Table

populating, 46

privileges, 145


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


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


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

Date post:	05-Jan-2022
Category:	Documents
Upload:	others
View:	15 times
Download:	0 times

KB SQL Database Administrator Guide

Documents