KBS Getting Started Guide

Transcription

KB SQL
Getting Started Guide
Release 4.4
Generated: 8/6/2005 2:58:00 PM
Table Of Contents
Introduction ...........................................................................................................1
Audience...............................................................................................................3
Software Components Overview...........................................................................7
KB_SQL Architecture ........................................................................................7
Documentation ..................................................................................................8
Documentation Download Instructions ........................................................11
KB_SQL Server...............................................................................................12
KB_SQL ODBC Driver ....................................................................................12
QRE Professional............................................................................................13
QRE Services..................................................................................................14
Installing and Upgrading KB_SQL Server...........................................................15
KB_SQL Requirements ...................................................................................15
M Type Specific Issues................................................................................16
Installing the Server Software .........................................................................20
Pre-Installation Steps for Previous Installs ..................................................20
Installation Procedures ................................................................................22
Post-Installation...............................................................................................26
Customizing the Site Definition ....................................................................26
Defining a Printer .........................................................................................27
Defining Base Routines and Schemas ........................................................27
Adding Security............................................................................................28
Building Your Data Dictionary ......................................................................28
Allowing Client Connections ........................................................................29
Upgrading the Server Software .......................................................................29
Upgrading the Server Software from Previous Versions..............................29
Upgrading from Versions Prior to 3.6...........................................................29
Upgrading from Version 3.6 or Higher .........................................................30
View and Updating Licence Information ..........................................................31
Viewing License Information ........................................................................31
Changing the License Key ...........................................................................31
Changing the M Type ..................................................................................32
Starting KB_SQL .............................................................................................32
Auto Start by Logging into KB_SQL.............................................................35
Manually Start Using a Command ...............................................................35
Manually Start Using Menu Option ..............................................................36
Starting the Server in a VMS Cluster ...........................................................36
Stopping the Server.........................................................................................38
Configuring the Server Information..................................................................39
Definition of each fields on the SITE EDIT screen .......................................39
Customizing the KB_SQL Server Install Process ...............................................45
SQLSCR.USR .................................................................................................45
Customization Types.......................................................................................46
1 – KBS Routine Import ...............................................................................47
2 – KBS Global Import .................................................................................47
3 – Routine Execute ....................................................................................47
iii
4 – Prompt ...................................................................................................48
5 – Import Table Definitions .........................................................................48
6 – Import Query Definitions ........................................................................49
7 – Import Device Type Definitions ..............................................................49
8 – Execute M Code ....................................................................................49
9 – Import Function Definitions ....................................................................50
10 – Import Pseudo Column Definitions ......................................................50
11 – Import Table Statistics .........................................................................51
12 – Global Import from XFER Export File...................................................51
13 – Import Routine Data.............................................................................52
Installing and Configuring the KB_SQL ODBC Driver.........................................53
Before You Begin ............................................................................................53
ODBC Driver Installation .................................................................................54
Creating KB_SQL ODBC Data Sources..........................................................59
Test ODBC Data Source .................................................................................63
Installing QRE Professional ................................................................................65
QRE Professional Requirements.....................................................................65
File Summary......................................................................................................67
KB_SQL Server Installer File Summary ..........................................................67
Getting Technical Support ..................................................................................69
The Online Knowledge Base ...........................................................................69
Logging Into the Online Knowledge Base ....................................................70
Searching the Online Knowledge Base .......................................................72
Submitting Questions to KBS Support .........................................................74
Reviewing and Updating Incidents Submitted to KBS Support ....................77
Education/Training ..........................................................................................82
Ordering Software...............................................................................................83
Index ...................................................................................................................86
iv
Introduction
The Getting Started Guide provides information about the KB_SQL product
components, installation and upgrade procedures, installation customization, and
configuration of the KB_SQL Server, KB_SQL ODBC Driver, and QRE
Professional.
In addition, the Getting Started Guide offers guidelines for distributing the
software, getting technical support from Knowledge Based Systems (KBS), and
ordering additional licenses.
Page 1 of 91
© Copyright Knowledge Based Systems, 2005
8/8/2005
All rights reserved.
Audience
This manual is intended for Knowledge Based Systems’ Solutions Providers.
The various sections are targeted at different individuals as noted below:
•
Software Components
This section is targeted at the database administrator (DBA) or users
interested in obtaining a description of the pieces of the software.
•
Installing/Upgrading KB_SQL Server, Installing the KB_SQL ODBC Driver,
Configuring the KB_SQL ODBC Server, Installing and Configuring QRE,
Customizing the Software Install Process, Distributing Software
These sections are intended for the DBA or others responsible for the
installation, configuration, or distribution of KB_SQL.
•
Getting Technical Support
This section is targeted towards KB_SQL DBAs, users, and programmers
responsible for the support of KB_SQL.
•
Ordering Software
This section is targeted at individuals responsible for purchasing KB_SQL.
Page 3 of 91
8/8/2005
Copyright 2005 by Knowledge Based Systems, Inc. All rights reserved.
Knowledge Based Systems, Inc., Ashburn, Virginia, USA.
Printed in the United States of America.
No part of this manual may be reproduced in any form or by any means
(including electronic storage and retrieval or translation into a foreign language)
without prior agreement and written consent from Knowledge Based Systems,
Inc., as governed by United States and international copyright laws.
The information contained in this document is subject to change without notice.
Knowledge Based 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
WWW http://www.knowledgebasedsys.com
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.
Page 5 of 91
8/8/2005
Software Components Overview
The KB_SQL Software consists of five separate components:
• Documentation
• KB_SQL Server
• KB_SQL ODBC Driver
• QRE Professional
KB_SQL Architecture
Page 7 of 91
8/8/2005
Documentation
KBS strongly recommends downloading and reviewing the documentation
before installing other KB_SQL components.
KB_SQL documentation is distributed through the online knowledge base at
support website of Knowledge Based Systems.
Document
Data Dictionary
Guide
Audience
Technical resource
responsible for the
overall management of
the KB_SQL system
and who is familiar with
M, the relational
database model, and
SQL.
DBA (Database
Administrator’s)
Guide
Database administrator
of KB_SQL who is
responsible for the
smooth, ongoing
operation of the
system. Experienced
users and programmers
will find the information
in this guide helpful in
the basic
implementation of the
system and for
integrating the system
with existing
applications. Familiarity
with M, the relational
database model, and
SQL is required.
All users of the EZQ
Editor interested in
EZQ Reference
Giude
Description
The KB_SQL Data Dictionary
Guide explains relational tables
and the process of mapping M
globals to a data dictionary.
KB_SQL requires the data
dictionary to retrieve data from
your M database. This guide
also provides information about
a technology used to update M
globals and about an
alternative mapping process for
these globals.
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.
The KB_SQL EZQ Reference
Guide provides a
Getting_Started_Guide.doc
Page 8 of 91
8/8/2005
Document
Audience
generating reports in a
customized format.
SQL Reference
Guide
All users of the SQL
Editor wanting to
control database
information.
Syntax Guide
All users familiar with
the basics of SQL and
who want to use SQL to
access data from the
database systems
defined in the KB_SQL
Data Dictionary.
KB_SQL ODBC
Driver Help
The KB_SQL ODBC
Driver Help file is
intended for the DBA
and others responsible
for the installation and
support of KB_SQL.
Description
comprehensive understanding
of the EZQ Editor’s report
design process. It also
provides a tutorial that
introduces you to the EZQ
Editor and guides you through
the creation of four reports.
Each report uses one or more
basic features of the editor.
The examples in this guide
provide a foundation that
enables you to create more
comprehensive reports with
your data. The reference
section contains detailed
information about the features
of the EZQ Editor.
The KB_SQL SQL Reference
Guide explains how to use the
SQL Editor to select and
control information in your
database. A tutorial is
provided to give you hands-on
experience. Refer to the
KB_SQL Syntax Guide for a
listing of KB_SQL syntax,
usage rules, and examples.
The KB_SQL Syntax Guide is
an alphabetical listing of
KB_SQL syntax, usage rules,
and examples as they apply to
the KB_SQL Editor and
KB_SQL API. To use KB_SQL
with the SQL Editor, refer to
the KB_SQL SQL Reference
Guide.
The KB_SQL ODBC Driver
Help file describes the ODBC
solution in the context of the
KB_SQL Server product
provided by Knowledge Based
Systems, Inc. It contains the
following sections: Features,
Understanding ODBC, Driver
Installation and Setup, Server
Page 9 of 91
8/8/2005
Document
Audience
KB_SQL
Release Notes
All users interested in
information about
product changes,
problem resolutions,
and known problems.
QRE
Professional
Usage Guide
The QRE Professional
Usage Guide is
targeted towards
KB_SQL Query
Developers and
Database
Administrators. An
intermediate knowledge
of KB_SQL is
assumed. For an
introduction to
KB_SQL, KBS
recommends the
KB_SQL SQL
Reference Guide.
The QRE Services
Programmer’s
Reference is targeted
towards experienced
Windows Client
programmers or Web
programmers.
QRE Services
Programmer’s
Reference
Description
and Network Configuration,
Simulating ODBC with
QUICK^SQL, Managing ODBC
Data Sources, Windows
Applications, and Programming
Considerations.
The Version 4.3 Release Notes
provides information about the
product's new features, fixes,
and known problems for KBS'
Solutions Providers and direct
end-users.
The QRE Professional Usage
Guide includes an overview of
QRE Professional (capabilities,
requirements, considerations,
elements of QRE Professional
User Interface), instructions for
installing and configuring the
software, details on running
queries, guidance on creating
and editing queries, and
information regarding the
offline options.
The QRE Services
Programmer’s References
assumes the familiarity with
KB_SQL, familiarity with a
COM-based programming
language and Visual Basic.
Note it will not cover Visual
Basic coding tutorials (although
examples are written in Visual
Basic) and SQL syntax. The
QRE Services Programmer’s
Reference includes:
• A description of each
method
• Details about the
arguments (data type,
length, purpose)
• Details about the return
Page 10 of 91
8/8/2005
Document
Audience
•
•
•
Description
value of the (data type,
contents)
Example code (in VB)
Usage Notes
Related methods
Documentation Download Instructions
To download the documentation:
1. Go to http://www.knowledgebasedsys.com/support.
2. Select the My Knowledge Base tab, which will prompt you for login
information.
3. Enter your user id and password. (If you do not have an account to the
online knowledge base, please contact KBS at
[email protected] to request an account.)
4. Once you are logged in, select the Answers tab.
5. Select Documentation from the Categories drop down list.
6. Click the Search button. The available documentation for download will
display.
Page 11 of 91
8/8/2005
KB_SQL Server
KB_SQL integrates SQL and M, two ANSI standard languages, to provide stateof-the-art access to the information that drives your organization. KB_SQL
enables you to retrieve information from your existing M globals while remaining
completely independent of the M implementation. The DBA procedures that
accompany KB_SQL let you map your information into the KB_SQL Data
Dictionary, apply security to tables and queries, and define terminals and printers
for use by the system.
KB_SQL ODBC Driver
ODBC (Open Database Connectivity) is a standard interface developed by
Microsoft for accessing data from different kinds of SQL database management
systems.
For more information about ODBC, please see the Microsoft documentation
available at www.microsoft.com/data.
The KB_SQL ODBC Driver allows you to connect your M database to a world of
applications, providing more choices for data access and reporting of your M
application data.
For more information about the KB_SQL ODBC Driver, please refer to the
KB_SQL ODBC Driver Help.
Page 12 of 91
8/8/2005
QRE Professional
KB_SQL from Knowledge Based Systems has been the de facto data access
and reporting solution for M databases since 1988. Since its introduction, it has
progressed from simple report writer to database management system to
application development platform. Thousands of users worldwide use KB_SQL,
via terminal screen or ODBC application, to retrieve valuable information from
their M databases and present it as a formatted report. In 1999, Knowledge
Based Systems introduced QRE (Query and Reporting Environment) to serve as
a Windows-based companion to the terminal-based SQL Editor. QRE for the first
time made it possible for customers to access the power of KB_SQL reporting
from a Windows environment.
With QRE Professional, users can:
• Run existing queries created with SQL Editor, EZQ Editor, or previous
versions of QRE
• Create and edit KB_SQL queries that can be executed in QRE
Professional or SQL Editor
• Open multiple queries simultaneously
Page 13 of 91
8/8/2005
•
Output reports to the screen, Windows printers, host devices, or Microsoft
Word
For more information on QRE Professional, please refer to the KBS QRE
Professional Usage Guide.
QRE Services
QRE Services provide a Windows-based programmatic interface to functionality
historically provided only by the host-based SQL Editor and EZQ. Examples of
some of the features of QRE Services are:
•
•
•
•
•
•
Running a Query
Creating a Query
Editing a Query
Deleting a Query
Sending a Query to the Background Queue
Running a Query with Prompts
The QRE Services API is provided in a COM/ActiveX DLL that allows it to be
used in Visual Basic, Active Server Pages, Visual C++, Delphi, and other
programming environments that support COM.
For more information on QRE Services, please refer to the QRE Services
Programmer’s Reference.
Page 14 of 91
8/8/2005
Installing and Upgrading KB_SQL
Server
KB_SQL Requirements
This section is included to help you measure the impact on the operating system
and MUMPS environment. Some of the issues raised here are not explained in
full detail because they represent a larger issue that is typically in the domain of
the system administrator.
•
MUMPS
MUMPS (M) is required to run KB_SQL. The product is written in M,
specifically for providing SQL access to M data structures. The vast
majority of the product routines are identical and portable across all M
types. Implementation-specific code is well isolated for those issues that
are not portable across implementations. These functions are typically
managed in the routines that are loaded in the first step of the installation
process.
•
Disk Space
KB_SQL requires disk space for routines, globals, and host files. It takes
a minimum of 10mb of disk space to store our product routines and
globals. There is a requirement for approximately 10mb of additional
space in the host file system space during the installation only. After the
installation is complete, the installation files can be removed and the
space can be made available.
•
User Partitions/Stack Size
KB_SQL requires sufficient memory for routine compilation and other CPU
intensive procedures. A typical partition used for query development and
compilation requires 40-60kb of memory, but might require additional
tuning for performance.
Depending on your implementation and the characteristics of queries written at
your site, you may need to increase the amount of memory allocated for both
string and stack operations. If you encounter errors that are related to insufficient
memory, you may have to increase the default values. These values can usually
be modified in a startup script or by a startup parameter.
Consult your M system manager guide for more information on memory
configuration.
Page 15 of 91
8/8/2005
M Type Specific Issues
This section outlines some special considerations that may need to be
addressed.
If your operating system platform and the type of M that you use are not listed,
you can ignore this section.
In general, Knowledge Based Systems’ technical support can help with the basic
configuration of the KB_SQL product on almost all configurations. To ensure the
best possible support when contacting Knowledge Based Systems, please have
your M implementation documentation available.
KB_SQL supports the following implementations of M
M Type
Caché
Description
Unless specifically noted, the issues in this section apply to Caché,
OpenM, NextGen, and ISM product implementations from InterSystems.
•
MaxArray Size
InterSystems limits the number of entries in a local array
structure. One of the local structures used by the Server API is
an array of message elements that can approach the limits
specified by InterSystems. The default maximum number of
elements used is 1024 for all InterSystems licenses. If
<MaxArray> errors occur when using the Server API, please
contact KBS technical support for instructions on how to lower this
number.
•
Read Recall
There is a feature in Caché/OpenM that allows for quick recall of
previous READ values. It can be quite handy, but can also
conflict with the function key oriented interface provided by
KB_SQL. Because of the potential conflict, this feature is
disabled during a KB_SQL session. This primarily affects the
CACHE_TERMINAL and ISM_PC_CONSOLE device types.
CacheLinux
As of the date this was written, the Linux implementation of Caché does
not support the concurrent TCP feature. If using Caché on Linux, load
and use the ISM.RTN routine set.
CacheWindows
The WindowsNT/9x implementations of Caché support the concurrent
TCP feature. If using Caché on WindowsNT/9x, load the CACHE.RTN
routine set. When configuring the server, only one port will need to be
defined.
Page 16 of 91
8/8/2005
Installing and Upgrading KB_SQL Server
M Type
DSM
Description
•
Symbol Table Save Uses Host File
There are circumstances when KB_SQL attempts to save the
current symbol table of a process. On DSM, this is accomplished
by opening a host file in the current working directory, writing the
symbol table to the file, then reading the contents back. If errors
occur, it could be due to file ownership permissions.
•
Disable Line Editing
If problems occur using the cursor keys on the keyboard, check
the status of LineEditing for the terminal. This feature can be
turned off at the VMS level as well as within DSM. Note that the
newer device drivers from Knowledge Based Systems attempt to
turn this feature off as part of the device type initial execute.
•
VMS Clustering
If your installation uses VMS clustering, you will need to be
careful to only start the Server from the node that is defined as
the local host in the ServerAPI network configuration. You will
also want to disable the autostart option found on the
Configuration/Site Edit/Server Info menu.
Page 17 of 91
8/8/2005
M Type
GT.M
Description
•
Process Settings
Each process running KB_SQL must have the following attribute
settings.
StackSize >= 40k
•
Database Settings
The database that contains the SQL global must have the
following attribute settings.
RecordSize >= 512
KeySize >= 128
•
TCP/IP
Greystone provides TCP/IP on all current releases of the GTM
product for VMS and Unix. If unsure about TCP/IP support,
please verify this information with the GTM provider.
•
VMS File Versioning
If the installation uses VMS file versioning, KBS recommends
disabling the feature on the directory that stores the generated M
routine source files. These files can change dramatically based on
the source SQL commands.
•
Lock Space
The lock space setting for the segment is crucial for systems
running a large number of concurrent connections. On GT.M
Linux, we found that with a lock space of 20 pages, we were able
to get 158 locks and 78 concurrent connections. Increasing the
lock space to 40 doubled both the number of locks and
connections that we were able to acquire (i.e. 316 locks, 156
connections). The ratio of lock space to connections on VMS is
different than Linux. Setting the lock space to 80 pages resulted
in approximately 150 concurrent connections. It may take some
testing to find the ideal configuration of lock space. If you have
any questions or problems, please contact KBS Technical
Support.
HBOM
Page 18 of 91
8/8/2005
M Type
Description
ISM
M21
MSE
MSM
•
MSM-NT and TCP/IP
KB_SQL uses an undocumented feature within MSM to
accomplish the TCP/IP listen and accept functions required by the
Server API. This capability requires MSM-NT v4.3 or greater.
•
MSM-Unix and TCP/IP
MSM-Unix requires a muserver process for each TCP/IP session.
If multiple connections cannot be made, verify that a sufficient
number of muserver processes have been allocated.
Page 19 of 91
8/8/2005
Installing the Server Software
If this is not a new installation, make sure that the Pre-Installation steps are
completed before starting the installation of a new version.
The entire installation takes about one hour to complete. The data dictionary
integrity check takes anywhere from 20 minutes to several hours depending on
the number of object definitions in the data dictionary.
Note: For information on running the installation as a background process,
please see the documentation on AUTO^SQL0LOAD in the Upgrading from
Versions Prior to 3.6 section of this guide.
Pre-Installation Steps for Previous Installs
Before beginning the server software installation ensure the following steps have
been completed.
The KB_SQL Data Dictionary Integrity Check procedure has been run.
For more information on Integrity Check and options, refer the to KB SQL
Database Administrator's Guide.
The KB_SQL routines and globals have been backed up. Export the SQL
routines and globals together with any other custom routines necessary
for your KB_SQL environment.
Avoid mixing SQL routines and globals from different environments.
When copying the SQL globals or routines into an "area", it should first be
purged of any existing SQL globals or routines.
All users are logged out of KB_SQL.
Check to make sure that there are no connections to KB_SQL by
using the DBA OPTIONS menu and select the UTILITIES option,
then the JOB WATCH option.
Page 20 of 91
8/8/2005
There should be a Server-Listener process and the current process
you are using to access the Job Watch. If there are any more
processes, they must be stopped before starting the upgrade.
To shut down any of the background agent processes, use the
STOP^SQL utility as follows:
>D STOP^SQL
For more information on this utility, refer the KB_SQL Database
Administrator's Guide.
To make sure that no new sessions are created, go to the DBA
OPTIONS menu and select the Utilities option.
The Select System-Wide Lock menu displays. Select the
SYSTEM option.
The Lock Status window displays. Enter Yes in the
Locked? field? to keep all users off the system while the
upgrade is being performed.
Page 21 of 91
8/8/2005
Installation Procedures
If KBS SQL Server has previously been installed on your server, go to the preinstallation instructions before starting the installation.
Download the KBS SQL Server zip install file
(KBSQL_ANSI_V<Version>_Build_<Build#>.zip) from KBS Knowledge
Base.
Where Version is the current version number such as 44Q1.
Where Build# is the current build number such as 4819.
Extract the Setup Files into a temporary working directory on your M
Server:
such as C:\temp for a windows based installation
or /usr1/temp for a UNIX based installation.
The server setup files are extracted from a zip extraction tool such as
WinZip or PKUnzip.
The setup files can be deleted after completing all steps of the
installation process.
Load the Setup Routines. This step loads the routines necessary to begin
the software installation process. We recommend that you use a separate
UCI (an area also referred to as namespace or simply area) for KB_SQL.
If the KB_SQL routines and globals are loaded into a UCI with other
applications, check to ensure that no conflicts will occur. All of the
KB_SQL product routine and global names begin with the uppercase
characters, SQL. There are no %routines or %globals, and there are no
special requirements for your manager’s directory.
If you use a separate location (directory), you must reference your
application globals indirectly. Application globals can be on the same
machine or in the same network. Global data can be referenced via M
Vendor networking (e.g. DDP). Call you M technical support representative
if you need more assistance.
The mtype.RTN file contains the KB_SQL install routines. This file is stored
in an M vendor-specific routine transfer format. Use the routine
import/restore utility provided by the M vendor to load the .RTN file. Refer
to the following list for the appropriate utility in your environment. If it is not
listed, please contact your KB_SQL technical support representative.
Page 22 of 91
8/8/2005
M Type
Caché
DSM
Utility
%RI
%RR
Filename
CACHE.RTN
DSM.RTN
GTM
%RI
GTM.RTN
HBOM
ISM
M21
MSE
MSM
%RR
%RI
%RR
%YRR
%RR
HBOM.RTN
ISM.RTN
M21.RTN
MSE.RTN
MSM.RTN
Description
InterSystems Caché
InterSystems DSM
Sanchez Computer
Associates GTM
McKesson UK HBOM
InterSystems ISM
M21
McKesson MSE
InterSystems MSM
The following example shows using the InterSystems Caché to load the
setup routines.
Cache>D ^%RI
Input routines from Sequential
Device: /usr/kbsql/cache/cache.rtn (Sample for
Unix)
c:\temp\cache.trn (Sample for Microsoft)
Parameters: "R"=>
File written by KB_SQL V4.4 using %RI on yyyy-mmdd@hh:mm:ss
with extension INT and with description:
KB_SQL V4.4 Routine Save
( All Select Enter List Quit )
Routine Input Option: All Routines
If a selected routine has the same name as one
already on file,
shall it replace the one on file? No => YES
Recompile? Yes => Yes
Display Syntax Errors? Yes => Yes
^ indicates routines which will replace those now
on file.
@ indicates routines which have been [re]compiled.
- indicates routines which have not been filed.
SQL0BQ.INT@
SQL0DATE.INT@
.
SQL0CHK.INT@
SQL0DT.INT@
. <-- Other routine names will be displayed
Page 23 of 91
8/8/2005
.
71 routines processed.
Cache>
Run the KB_SQL Load Procedure
This step loads the KB_SQL routines, globals, and system catalogs. To
run the KB_SQL load procedure, log in to the M System and run the
KB_SQL software install utility SQL0LOAD (see the following example).
If this is a new installation, the organization name, license number
and license key (as provided by Knowledge Based Systems) must be
entered. Please contact Knowledge Based Systems technical support if
there any questions regarding the license.
A sample script using InterSystems Caché follows:
Cache>D ^SQL0LOAD
Software Installation Utility
-----------------------------This utility loads software from data files in a
directory into this UCI. Please enter the path of
the directory that contains the install files
followed by the [Enter] key.
You must include all characters needed to specify the directory
name up to the point where the file name begins. Path examples:
DOS
C:\TEMP\
VMS
USER:[TMP]
Unix
/usr/temp/
Directory path: /usr/kbsql/load/cache/
Customer name:
Supplier name:
License number:
License key:
<<-- Sample
XYZ Company
0000
XXXX-XXXX-XXXX
===================== License Agreement===========
Use of this product is governed by a software
license agreement. By entering your name at the
Page 24 of 91
8/8/2005
next prompt, you acknowledge that you have read the
license agreement that is included with the
product, and fully understand and agree to all of
the terms and conditions contained in the
agreement.
==================================================
If you agree to the terms of the license, enter
your name.
Otherwise, press the [Enter] key to exit the
installation.
Enter your name to accept license terms
Your name: YourNameHere
KB_SQL V4.4, (c) 2004 by Knowledge Based Systems,
Inc.
Install KB_SQL V4.4.xxxx [mm/dd/yyyy] <-new
installs
Update KB_SQL Vx.y ==>> KB_SQL V4.4.xxxx
[mm/dd/yyyy] <-upgrades
------------------------------------License number
= 0000
Company name
Supplier name
System type
M type
Number of users
= XYZ Company
=
=
=
=
FULL
CACHE
8
OK to Install? <Yes>: Yes <--Shown for new
installs
Delete obsolete SQL* routines? <No>: Yes <-- For
upgrades
OK to Update? <Yes>: Yes <-- For upgrades
StepID
StartTime
-------------1004 mm/dd/yyyy@hh:mm.ss
SQLSITE.GBL
Description
----------Loading global file:
The above step occurs for new installs only.
1005 mm/dd/yyyy@hh:mm.ss
ZAPSQL^SQL0RI
Executing M code: D
Page 25 of 91
8/8/2005
=>Delete obsolete routines
The above step occurs for upgrades only.
1006 mm/dd/yyyy@hh:mm.ss Loading routine file:SQLRTN.1
1007 mm/dd/yyyy@hh:mm.ss Loading routine file:SQLRTN.2
.
. <-- Other step descriptions will be displayed
.
Integrity Check started
System lock will remain set until completed
Software installation complete!
Cache
The installation is now complete. Your installation script should look similar to
the one above used as an example. Make sure no errors occurred.
Post-Installation
For upgrades the following steps are required:
Remove the System Lock to allow user connections to KB SQL.
Log into KB_SQL.
To restore new sessions are created, go to the DBA OPTIONS
menu and select the Utilities option.
The Select System-Wide Lock menu displays. Select the
SYSTEM option.
The Lock Status window displays. Enter No in the Locked? field.
This following offers suggestions on steps to configure KB_SQL for your site.
Customizing the Site Definition
Use the ConfigurationÆSite Edit option to customize the site definition. Refer
to the KB_SQL Database Administrator’s Guide for more information about the
Site Edit options.
Page 26 of 91
8/8/2005
•
Name and Address - You will want to ensure that the site definition
includes your accurate site name and address.
Log into KB_SQL
Go to the DBA OPTIONS menu and select the Configuration
option.
Go to the Site Edit option.
The Site Name window displays. Put your site name here if you
have not already done so.
Hit the Enter key and select the ADDRESS INFO option from the
Site Options menu. Enter your address in the Site Address
Information window that displays. Hit Enter until the window closes
and you return to the Site Options menu.
Press the F4 key until the commit? field appears. Enter Yes and hit
the Enter key to save your changes.
•
Go through the Default Info, ANSI Info, and M Info options of the Site
Options menu. Determine how to customize KB_SQL to meet the special
requirements of your site. Specifically, you will want to tell the system
about special M functions that you want to use and if you want to run
queries as background jobs.
•
User Signon and Device Info options, of the CUSTOM LOGIC option
from the SITE EDIT procedure, is where you can tell the system how to
automatically set your user and device type information at sign on. Refer
to the KB_SQL Database Administrator’s Guide for more information
about security and device definitions.
Defining a Printer
Use the TERMINALS & PRINTERS/LOGICAL DEVICE EDIT procedure to define
a printer. For starters, create a printer device with any printer accessible to M and
our default device type, PRINTER. This will allow you and your users to print
hard copies of reports. Refer to the section on the LOGICAL DEVICE EDIT
option in the KB_SQL Database Administrator’s Guide.
Defining Base Routines and Schemas
Use the DBA options menu, CONFIGURATION option, BASE ROUTINE EDIT
option to add one or more routine prefixes for use by your site. This is handy if
you want your compiled queries to be in separate routine names for different
schemas or user groups. Refer to the section on the BASE ROUTINE EDIT
option in the KB_SQL Database Administrator’s Guide.
Page 27 of 91
8/8/2005
Use the DBA options menu, DATA DICTIONARY option SCHEMA EDIT option
to define schemas for your applications. See the section on the SCHEMA EDIT
option in the KB_SQL Data Dictionary Guide for more information.
Adding Security
Use the SECURITY option from the DBA options menu to create user groups
and users.
As tempting as it might be to use the SHARK password, you should create your
own user groups and user passwords.
Each user group can be linked to a schema, so that users will see only the
information that is applicable to them.
You can configure your user accounts so that certain people can edit queries
using SQL, others can edit queries using EZQ, and others can only run existing
queries. You might even want to create a tutorial user group for people who want
to try the KB_SQL tutorials.
Refer to the KB_SQL Database Administrator’s Guide for more information on
Security.
Building Your Data Dictionary
Until you tell KB_SQL about your data dictionary, you can use it only to report on
the demonstration tables. While this may be sufficient for evaluation of the user
interface, the goal is to access your information. We have documented the
fundamentals of the KB_SQL data dictionary, strategies for mapping globals,
creating your data dictionary, and creating table filers in the KB_SQL Data
Dictionary Guide.
Please read the appropriate sections before you begin mapping your globals.
The success of your efforts will be greatly improved if you have a good
understanding of schemas, domains, tables, primary keys, and indexes before
you begin the mapping process.
The KB_SQL Data Dictionary Guide explains how to use the mapping
procedures: the MAP EXISTING GLOBALS option, which has been the sole
method for mapping your globals prior to KB_SQL Version 3, and the Data
Dictionary Language (DDL) interface, which has become the preferred method
because of its ease of use. The DDL interface processes a script file that
contains SQL CREATE, ALTER, and DROP statements. The script file is easy to
update and reusable.
Page 28 of 91
8/8/2005
Allowing Client Connections
As soon as some parts of your data dictionary are defined to KB_SQL, you will
want to see what the data looks like in the SQL Editor, EZQ Editor and from
client applications. In order to access your M data through Windows applications,
you will need the KB_SQL ODBC Driver. Please refer to the Installing the
KB_SQL ODBC Driver section of this manual for more information on installing
the KB_SQL ODBC Driver and the Configuring the KB_SQL ODBC Server
section for more information on configuring the server to accept connections. For
more information about the ODBC Driver, please see the KB_SQL ODBC Driver
Help.
Upgrading the Server Software
Upgrading the Server Software from Previous Versions
Before upgrading KB_SQL, make sure that the Pre-Installation steps have been
taken.
Upgrading from Versions Prior to 3.6
Starting with KB_SQL Version 3.6, Knowledge Based Systems implemented a
single setup disk and license key technology to simplify the software distribution
process. If upgrading from a version prior to V3.6, please contact KBS Technical
Support for a license key.
In order to change the default license number, you will need to load the software
using the AUTO^SQL0LOAD technique. The AUTO^SQL0LOAD tag allows
you to install KB_SQL without interactive prompts. It is invoked using the syntax
shown below:
>DO AUTO^SQL0LOAD(PATH,AUTH,ECHO,SQLFILE,CUSTOMER,LICENSE,KEY,SUPPLIER, NOIC)
This routine requires the following arguments:
PATH
The path to the load directory
AUTH
The name of the person installing the software
ECHO
A flag indicating if information should be echoed
to the screen (“”=no, 1=yes)
SQLFILE
A file name to store the messages that would
normally be echoed to the screen
The customer’s name
CUSTOMER
Page 29 of 91
8/8/2005
LICENSE
The license number
KEY
The license key
SUPPLIER
The supplier’s name
NOIC
Flag indicating whether or not the integrity check
should be run at the end of the installation. If true,
it will suppress the running of the Integrity Check
unless otherwise forced.
Note: The Integrity Check can only be suppressed for upgrades within
the same major.minor version.
Upgrading from Version 3.6 or Higher
If you are upgrading from Version 3.6 or higher, and do not wish to change your
existing license information, you may follow the installation steps documented in
the Installing the Server Software section of this Guide.
If you have any questions, please contact KBS Technical Support.
Page 30 of 91
8/8/2005
View and Updating Licence Information
Viewing License Information
The SHOWKEY^SQL0LOAD tag will displays the license key, license number,
number of concurrent users, and system type.
Example:
>D SHOWKEY^SQL0LOAD
Current Software Key= XXXX-XXXX-XXXX
License number= 0000
Number of users= 8
System type= FULL
Changing the License Key
The NEWKEY^SQL0LOAD tag is used to change the number of concurrent users
or system type. In order to use this routine, contact Knowledge Based Systems
for a new license key that reflects the appropriate changes. In order to use this
routine, a valid KB_SQL DBA user account is needed. This routine displays the
current license information and allows a new license key to be entered.
Example:
>D NEWKEY^SQL0LOAD
Change License Key setting
==========================
Password:
<-- Enter DBA password
Current Software
License number=
Number of users=
System type=
Key= XXXX-XXXX-XXXX
0000
8
FULL
New Software Key: YYYY-YYYY-YYYY <--Enter key from
KBS
Current Software Key= YYYY-YYYY-YYYY
Page 31 of 91
8/8/2005
License number= 0000
Number of users= 16
System type= FULL
Software key changed
Changing the M Type
The MTYPE^SQL0LOAD tag is used to change the M implementation. To move a
license from one M implementation to another, for example from DSM to MSM:
1. Copy all SQL routines and globals
2. Load the appropriate .RTN file for the new M implementation
3. Run MTYPE^SQL0LOAD
Starting KB_SQL
1. After the install process completes, execute the sign-on routine from the M
prompt.
>DO ^SQL
2. When prompted for a device type, select a device type from the list. If the
device type is not shown, select the ROLL_UP device type to use the
system in a scrolling mode.
3. When prompted for a user password, enter the supplied DBA password,
SHARK. This password gives provides access to all tables, queries, and
the DBA procedures.
We strongly recommend that the supplied DBA password be changed
using the SecurityÆUser Edit option.
After logging into KB_SQL, the KB SQL Server main menu is displayed.
Page 32 of 91
8/8/2005
4. Enter YES into the Examine system status? field. The System Status
Options menu displays.
5. Select the SERVER OPTIONS option. The Select option menu displays.
Page 33 of 91
8/8/2005
6. Select the ENABLE SERVER option. The Server Started message will
appear.
For more information on starting and stopping the server, refer to the KB_SQL
Database Administrator’s Guide.
There are several options available for starting the KB_SQL Server. The
following options will start the server in the background.
Page 34 of 91
8/8/2005
Auto Start by Logging into KB_SQL
If the following conditions are both true, the KB_SQL Server can be started by
simply logging into KB_SQL as a DBA or System Manager:
•
•
The Allow Connection field under ConfigurationÆSite EditÆServer
Info is set to Yes
The Disable auto start option under ConfigurationÆSite EditÆServer
Info is set to No
Manually Start Using a Command
The KB_SQL Server can be started by running the following command at the M
prompt:
>D START^SQL0SVR
This command line option allows you to start KB_SQL Server during the startup
of your M system or other times without the requirement to log into KB_SQL. If,
for some reason, the Server fails to start, the variable SQLERR may be trapped
and used to determine the reason for failure.
Page 35 of 91
8/8/2005
Manually Start Using Menu Option
The KB_SQL Server can be started by a DBA or system administrator using the
Enable Server option under System StatusÆServer Options.
Starting the Server in a VMS Cluster
In a VMS cluster, one or more nodes can access the M database.
Page 36 of 91
8/8/2005
However, the KB_SQL Server is configured to a specific IP address. In this
example, the KB_SQL server is configured with the IP address of Node 1.
Because of this, it is imperative that the KB_SQL Server is started from the node
identified in the KB_SQL server configuration. Starting the server from a node
other than the one identified in the server configuration will result in a variety of
problems including unsuccessful client connections and inability to stop the
KB_SQL server.
When the D ^SQL command is issued, the KB_SQL server will begin listening for
connections using the IP address of the node from which the command was
issued. When this happens on a node other than where KB_SQL is installed, no
connections are allowed to the server although it appears to be running. Should
you experience this problem, it will be necessary to kill the SQL0TCP processes
at the M level and start the KB_SQL server from the correct node.
Typically, when the server is accidentally started on the wrong node it is because
the Disable auto start? field is set to No. To prevent this from occurring, we
strongly recommend that this feature be disabled by setting the Disable auto
start? field to Yes (ConfigurationÆSite EditÆServer Info).
Note: By setting the “Disable auto start” option to “Yes”, it will be necessary
to manually start the KB_SQL Server using one of the methods discussed above.
Page 37 of 91
8/8/2005
Stopping the Server
You may need to stop the KB_SQL Server for various reasons (shutting down M,
system maintenance, etc.). You may stop the KB_SQL Server with the following
command:
>D STOP^SQL0SVR
This command may be called from procedures such as Shutdown, etc.
The KB_SQL Server can also be stopped by a DBA or system administrator
using the Disable Server option under System Status Æ Server Options
menu.
Stopping the server using the above methods does not affect current
connections to the KB_SQL Server. It does, however, prevent any new
connections from being established. As some applications require multiple
database connections for operation, it is best to ensure that everyone is logged
off before stopping the KB_SQL Server. You may check current connection
status by choosing Connections from the Systems Status menu.
Page 38 of 91
8/8/2005
Configuring the Server Information
The Server Information can be accessed through the ConfigurationÆSite
EditÆServer Info menu option. The SITE EDIT window displays, with the
Server Information section.
Definition of each fields on the SITE EDIT screen
Prefix for Stored Query Routines
KB_SQL allocates an M routine for each Server API query in the query
cache. The value entered in this field will serve as the prefix for these
routines. For example, if the prefix is SQLY, the routines are named in the
format SQLY, followed by a number (for example, SQLY1).
Page 39 of 91
8/8/2005
Maximum Number of Stored Queries
The value entered in the Maximum Number of Stored Queries field
determines the number of queries stored in the query cache.
As the Server API receives a SQL command, it checks the query cache for
the command’s corresponding M routine. If it finds the M routine, the
Server API runs the routine. If an M routine is not found, the Server API
must use the SQL engine to translate the SQL 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 a large number is specified in the Maximum Number of Stored Queries
field, such as 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. The value
supplied 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.
Allow Connections
Answer Yes to allow the KB_SQL ODBC server to accept connections.
Answering Yes to this prompt does not automatically start the server.
Please see the Starting the Server section of this document for information.
Answer No to disallow connections to the KB_SQL ODBC server. If the
server is already running it must be modified to disallow connections, first
invoke the STOP^SQL0SVR function before setting this prompt to No.
Answering No to this prompt does not stop the server. Please see the
Stopping the Server section of this document for information on stopping
the server.
Disable Auto Start
If the Disable Auto Start field is set to Yes, the KB_SQL ODBC Server will
NOT be started upon a KB_SQL log in (D ^SQL). The server will need to
be manually started using one of the options in the Starting the Server
section of this document.
Page 40 of 91
8/8/2005
If the site is using VMS clustering, Knowledge Based Systems
strongly recommends that this field be set to Yes to ensure that the server
is not started from the wrong node.
If the Disable Auto Start field is set to No, the KB_SQL ODBC Server will
be automatically started the first time a user logs into KB_SQL.
Trace API Calls
Setting the Trace API Calls field to Yes will cause KB_SQL to track the
dialog between the KB_SQL server and clients. The logged can be viewed
either by:
•
•
Using the VIEW^SQL0SVR tag at the M prompt, or,
Selecting the System Status Æ Server Options Æ Trace Options
Æ View Trace option
Tracing is used mainly for troubleshooting purposes and is typically
turned off due to the impact it can have on query performance.
Edit Network Configuration
Enter Yes to edit the TCP/IP defaults or host information. In general, the
network information consists of the TCP/IP host and port information.
Depending on the M implementation, alternate ports may need to be
defined. The TCP/IP Defaults window appears.
Server Initial Execute
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
Enter the M code that will validate and/or establish the username
(SQLUNAME) and password (SQLUAUTH) variables referenced during the
connection to the server
Page 41 of 91
8/8/2005
Network Site Edit Windows
Field
Timeout for read
commands
TCP/IP Defaults Window Fields
Description
Enter the number of seconds after which a
READ command should timeout and check error
status (default = No timeout)
Maximum length of M
string
Enter the maximum size of an M string value in
this implementation (default = 511)
Output buffer size
Enter the output buffer size in bytes (default =
2048
Input buffer size
Enter the input buffer size in bytes (default =
2048)
The TCP/IP Host Information window displays.
Page 42 of 91
8/8/2005
Values provided above are for illustrative purposes only.
Field
Host name
TCP/IP Host Information Fields
Description
The TCP/IP hostname for the server
IP address
The internet protocol address for the server. If the
system uses dynamic IP address allocation, enter the
host name in this field.
Description
A brief description of the server
Local host
Enter YES if the system is the local host. Enter NO if the
system is a remote host.
The TCP/IP Ports Window appears.
Page 43 of 91
8/8/2005
Values provided are for illustrative purposes only.
Field
Port number
Port server
TCP Ports Fields
Description
The port number is expected to be in the range of 500165535
Enter YES if this is the published port for connecting to
this server. Enter NO if this is an alternate port to be
used internally
Page 44 of 91
8/8/2005
Customizing the KB_SQL Server Install
Process
The Software Install Process is designed to prepare a designated M environment
for SQL access using the KB_SQL product. The process can be customized to
allow packaging of customer object definitions together with the base product.
This section describes how to customize the install process using the userdefined script file SQLSCR.USR. This file is a part of the server installation files.
To enable this feature, you must copy your revised file to the load directory as
the file SQLSCR.2.
Installing and/or upgrading the product software is accomplished by the
Software Install program (SQL0LOAD). That program is described in detail in the
Getting Started Guide.
Customization is accomplished by adding script steps to the user-defined script
file, SQLSCR.USR. Each line of this file can contain a coded command and
associated arguments and message text. This file will be processed after all
product installation steps are complete.
SQLSCR.USR
The following text is taken from the on-line copy of SQLSCR.USR.
; Knowledge Based Systems, Inc.
; SQLSCR.USR.
; User-defined Script
;
; This file can be modified by the customer in order to extend the
; product installation process.
;
; Types
; =====
; OKVar~1~Filename~Import Routine source
; OKVar~2~Filename~Import Global data
; OKVar~3~RoutineToRun~Message
; OKVar~4~PromptText~PromptVar~PromptDefault
; OKVar~5~Filename~Import Table definitions
Page 45 of 91
8/8/2005
; OKVar~6~Filename~Import Query definitions
; OKVar~7~Filename~Import Device Type definitions
; OKVar~8~ExecuteMCode~Message
; OKVar~9~Filename~Import Function definitions
; OKVar~10~Filename~Import Pseudo Column definitions
; OKVar~11~Filename~Import Table Statistics
; OKVar~12~Filename~Import Global data
; OKVar~13~Filename~Import Routine data
;
; Variables
; =========
; Customers should use variables in the SQLA-, SQLB- namespaces.
; Context variables (inherited from product install)
; OK Always true
; OKI True for INSTALL only
; OKU True for UPDATE only
;
; Example
; =======
; This script imports customer defined tables, queries and functions
; for the fictitious LAB application.
;
; Note: Simply remove the leading semi-colon to enable a line of the
; script.
;
; OKU~1~FIXUP.RTN~Load FIXUP routines
; Note: This step is run only for updates (OKU).
; OKU~8~d FIXUP^SQLAA~Cleanup
; Note: This routine was loaded by the previous step.
; OK~5~LAB Table Definitions
; Note: This step is run for installs and updates (OK).
; OK~6~LAB.Q~LAB query Definitions
; OK~9~LAB.FN~LAB Function Definitions
; OKI~2~SITEDEF.GBL~Load global defaults for Site Definition
; Note: This step is run only for new installs (OKI).
Customization Types
For each of the customization types, it is necessary to specify the context in
which the command should be run:
OK
Perform for both new installations and upgrades
OKI Perform only for new installations
OKU Perform only for upgrades
Page 46 of 91
8/8/2005
Customizing the KB_SQL Server Install Process
1 – KBS Routine Import
Description
Imports the routine(s) file into the area where KB_SQL is
installed.
Please note this type should only be used with the
assistance of Knowledge Based Systems. This type is
intended for use only in situations when KBS must provide
custom routines.
Format
<Context>~1~<Filename>~<Comment>
Sample
Script Entry
OK~1~FIXUP.RTN~Load FIXUP routines
Sample
Output
1001 11/04/2002@02:00.58 PM Loading routine file:
FIXUP.RTN
=>Load FIXUP routines
2 – KBS Global Import
Description
Imports the global(s) contained in the specified file into the
area where KB_SQL is installed.
Please note this type should only be used with the
assistance of Knowledge Based Systems. This type is
intended for use only in situations when KBS must provide
custom globals.
Format
Sample
Script Entry
OK~2~FIXUP.G~Load FIXUP globals
Sample
Output
1001 11/04/2002@02:00.58 PM Loading routine file:
FIXUP.G
=>Load FIXUP globals
3 – Routine Execute
Description
Executes an M routine.
Page 47 of 91
8/8/2005
Format
<Context>~3~<Routine to run>~<Comment>
Sample
Script Entry
OK~3~MAKE^SQLAVIEW~Create views
Sample
Output
1001 11/06/2002@11:12.58 AM Running routine
SQLAVIEW
=>Create views
4 – Prompt
Description
Prompts the user for a value which is stored in a variable.
Format
<Context>~4~<Prompt text>~<Prompt variable>~<Prompt
default>
Sample Script OK~4~Set TEST global?~SETGBL~Yes
Entry
; Following the above with the next line would set the
global based
; on the user’s input
SETGBL~8~S ^TEST($H)=1~Set ^TEST global
Sample Output Set TEST global? <Yes>:
5 – Import Table Definitions
Description
Imports table definitions.
The file is expected to have been created using KB_SQL’s
table export utility found under UtilitiesÆExportÆTable, or
XFER for table.
Format
Sample
Script Entry
OK~5~STUDENTS.T~Import STUDENT table
Sample
Output
1001 11/06/2002@11:34.22 AM Loading table file:
STUDENTS.T
=>Import STUDENTS table
Page 48 of 91
8/8/2005
6 – Import Query Definitions
Description
Imports query definitions.
query export utility found under UtilitiesÆExportÆQuery,
or XFER for query.
Format
Sample
Script Entry
OK~6~QUERY.Q~Import query definitions
Sample
Output
1001 11/06/2002@11:34.22 AM Loading query file:
QUERY.Q
=>Import query definitions
7 – Import Device Type Definitions
Description
Imports device type definitions.
device type export utility found under
UtilitiesÆExportÆDevice Type, or XFER for device type.
Format
Sample
Script Entry
OK~7~PRINTERS.D~Import device definitions
Sample
Output
PRINTERS.D
=>Import device definitions
8 – Execute M Code
Description
Executes the specified M code.
Format
<Context>~8~<Execute M code>~<Comment>
Sample
Script Entry
OK~8~D C^SQLAVIEW~Call tag to create views
Page 49 of 91
8/8/2005
Sample Output 1001 11/08/2002@01:49.13 PM Executing M code: D
C^SQLAVIEW
=>Call tag to create views
9 – Import Function Definitions
Description
Imports function definitions.
function export utility found under
UtilitiesÆExportÆFunction, or XFER for function.
Format
Sample
Script Entry
OK~9~FUNCTION.F~Import function definitions
Sample
Output
FUNCTION.F
=>Import function definitions
10 – Import Pseudo Column Definitions
Description
Imports pseudo column definitions.
device type export utility found under
UtilitiesÆExportÆPseudo Column, or XFER for pseudo
column.
Format
Sample
Script Entry
OK~10~PSEUDO.P~Import pseudo columns
Sample
Output
PSEUDO.P
=>Import pseudo columns
Page 50 of 91
8/8/2005
11 – Import Table Statistics
Description
Imports device type definitions.
The file is expected to have been created using XFER for
statistics. For example,
>; Export table statistics:
>S SQLXTO="STATS"
>S SQLXTM="TO_FILE"
>S SQLFILE="C:\TEMP\STAT.T"
>; Replace K4 on the following line with the table id
>S ^SQLEX($J,"STATS",K4)=""
>D XFER^SQL
Format
Sample
Script Entry
OK~11~STAT.T~Import table statistics
Sample
Output
1001 11/08/2002@02:33.34 PM Loading Statistics file:
STAT.T
=>Import table statistics
12 – Global Import from XFER Export File
Description
Imports global data using KB_SQL’s XFER transfer utility.
The file is expected to have been created using XFER for
GLOBAL. For example,
>; export three globals named NAME, CITY,
and STATE
>S SQLXTO=”GLOBAL”
>S SQLXTM=”TO_FILE”
>S SQLFILE=”C:\TEMP\DATA.G”
>S SQLXNM(1)=”^NAME”
>S SQLXNM(2)=”^CITY”
>S SQLXNM(3)=”^STATE”
>D XFER^SQL
Note that when importing globals, the overwrite mode
(SQLOW) value can be used to replace (SQLOW=1) an
entire global tree, or merge (SQLOW=2) with an existing
global tree. If the overwrite mode is create (SQLOW=0), the
import will only be allowed if the global tree does not already
exist.
Page 51 of 91
8/8/2005
Format
Sample
Script Entry
OK~12~DATA.G~Data for name, city, state
Sample
Output
1001 11/06/2002@12:06.20 PM Loading Global xfer file:
DATA.G
=>Data for name, city, state
13 – Import Routine Data
Description
Imports a routine using KB_SQL’s XFER transfer utility for
routines.
An export file must have been created using XFER for
ROUTINE. For example,
>; export three routines named NAME, CITY,
and STATE
>S SQLXTO=”ROUTINE”
>S SQLXTM=”TO_FILE”
>S SQLFILE=”C:\TEMP\RTN.R”
>S SQLXNM(1)=”NAME”
>S SQLXNM(2)=”CITY”
>S SQLXNM(3)=”STATE”
>D XFER^SQL
Format
Sample
Script Entry
OK~13~RTN.R~Routines for name, city, state
Sample
Output
1001 11/06/2002@12:06.20 PM Loading Routine xfer
file: RTN.R
=>Routines for name, city,
state
Page 52 of 91
8/8/2005
Installing and Configuring the KB_SQL
ODBC Driver
This section contains information on installing the KB_SQL ODBC Driver. For
more information regarding the ODBC Driver, please see the KB_SQL ODBC
Driver Help.
Before You Begin
Before installing the KB_SQL ODBC Driver, there are a couple of items to note:
Is the KB_SQL Server installed and configured?
Do you know the Server configuration parameters for the Hostname (or IP
address) and listening port?
Hostname/IP Address: __________________________
Listening Port: _________________________
Can you ping the Server using the Hostname (or IP address)?
If running Windows 2000 or Windows XP, do you have Administrator
privileges?
Page 53 of 91
8/8/2005
ODBC Driver Installation
1. Launch the KB_SQL ODBC Driver Installer by double-clicking
KBSODBCDriver_<version>_Build_<Build#>.exe.
You may receive the following window if security is setup on the server to
verify execution of the file. Click Run to continue to installation. To
prevent this security warning, add Knowledge Based Systems to your
trusted list.
2. The setup window will prompt, “This will install KBS KB_SQL ODBC
Driver. Do you wish to continue?”. Click the Yes button to proceed with
the installation. Otherwise, click No.
Page 54 of 91
8/8/2005
Installing and Configuring the KB_SQL ODBC Driver
3. The “Welcome to the KBS KB_SQL ODBC Driver Setup Wizard” window
displays. Click the Next button to continue the installation.
4. Accept the terms of the license agreement to continue the installation by
clicking the I accept the agreement radio button.
Page 55 of 91
8/8/2005
5. Click the Next button to continue to installation.
6. The Select Destination Directory window displays. Select the
destination directory and click Next button. By default the driver will be
installed in the C:\Program Files\KBS\ODBC directory.
Note: If the directory does not exist, the installer will prompt you to create
the directory. Click the Yes button to create the directory.
Page 56 of 91
8/8/2005
7. The ODBC Ready to Install window displays. Click the Install button to
continue the installation.
8. Once the KB_SQL ODBC Driver is installed, the KB_SQL Data Source
Setup window displays. A default Data Source Name and Description
is populated for you. Change these as appropriate for your site, or use the
defaults provided. Click the Next button to continue.
Page 57 of 91
8/8/2005
9. The KB_SQL Network Connection Setup window displays. If the default
values provided are not correct, put the values in Host and TCP_PORT
that are appropriate for your site in these fields. Click the Finish button to
complete the installation.
10. The Completing the KBS KB_SQL ODBC Driver Setup Wizard window
displays. The KB_SQL ODBC Driver has been installed and a Data
Source has been created. Click the Finish button to exit the setup.
Page 58 of 91
8/8/2005
Once the installation is complete, the KBSODBCDriver.exe file is no longer
necessary.
Creating KB_SQL ODBC Data Sources
To create an additional KB_SQL Data Source or change the one created at
installation:
1. Open the ODBC Administrator.
o In Windows 2000 and Windows XP, the ODBC Administrator is
available from the Administrative Tools Æ Data Sources (ODBC)
option.
o In Windows Me, the ODBC Administrator is available on the
Windows Control Panel.
Page 59 of 91
8/8/2005
2. Click the Add button to create a new data source. The Create New Data
Source window displays.
3. Select KB_SQL ODBC 32-bit Driver, and click the Finish button.
4. The KB_SQL Data Source Setup window displays. Provide a Data
Source Name and Description for the new data source and click the
Next button.
Page 60 of 91
8/8/2005
Note that the values provided are for illustrative purposes
only.
5. The KB_SQL Network Connection Setup window displays. Provide the
Host and TCP_PORT. Host is either the KB_SQL Server HOSTNAME or
IP Adress. TCP_PORT is the listening port of the KB_SQL Server.
Contact the KB_SQL Database Administrator if these values are
unknown. Click the Finish button.
Note that the values provided are for illustrative purposes
only.
Page 61 of 91
8/8/2005
6. The DSN will now appear in the list and is ready for use.
In the illustration above, a User DSN was created, which is available to the
currently logged in user (Windows 2000 and Windows XP only). System DSNs
are available to all users and system services. File DSNs can be saved on
network drives for shared use.
Page 62 of 91
8/8/2005
Test ODBC Data Source
To test that the ODBC Data Source is valid, from a terminal session, use the
TEST^SQL0TCP utility:
> d TEST^SQL0TCP
Answer the prompts or take the defaults, that correspond to the DSN.
If your data source connects properly your DSN will be ready to go.
If your data source cannot connect, you will receive an error message. Contact
your DBA or System Administrator for assistance if you entered the correct
information for each prompt.
The expected result from the TEST^SQL0TCP is as follows:
V44Q1>D TEST^SQL0TCP
KB_SQL Server Connect Test
Server Name or Address: KBSVS6//
Port Number : 7001//
UserName : DBA
PassWord :
Connection limit : 4//
Connecting to KBSVS6 (7001)
Connected to #1:
|TCP|292~KBSVS6~7001~~~~|TRM|:|2600~~~2048~2048~32767
Connected to #2:
|TCP|293~KBSVS6~7001~~~~|TRM|:|2600~~~2048~2048~32767
Connected to #3:
|TCP|294~KBSVS6~7001~~~~|TRM|:|2600~~~2048~2048~32767
Connected to #4:
|TCP|295~KBSVS6~7001~~~~|TRM|:|2600~~~2048~2048~32767
Disconnecting #4:
|TCP|295~KBSVS6~7001~~~~|TRM|:|2600~~~2048~2048~32767
Disconnecting #3:
|TCP|294~KBSVS6~7001~~~~|TRM|:|2600~~~2048~2048~32767
Disconnecting #2:
|TCP|293~KBSVS6~7001~~~~|TRM|:|2600~~~2048~2048~32767
Disconnecting #1:
|TCP|292~KBSVS6~7001~~~~|TRM|:|2600~~~2048~2048~32767
V44Q1>
Page 63 of 91
8/8/2005
Installing QRE Professional
QRE Professional Requirements
The following are the minimum requirements for QRE Professional:
•
Pentium-class Processor, Pentium II 266 or higher recommended
•
64 MB RAM (or more) recommended
• 100 MB free disk space (or more) recommended
•
One of the following operating systems (* indicates the preferred OS)
•
Microsoft Windows 2000 SP3* (or the latest released service pack)
•
Microsoft Windows XP SP1* (or the latest released service pack)
•
Microsoft Windows Me
•
Microsoft Internet Explorer 5.x, IE 5.5 or 6.0+ recommended
•
KB_SQL Server and Reporting Tools Version 4.3
•
KB_SQL ODBC Driver Version 4.3
•
Microsoft Word 97 and up (Word XP Preferred) if report output to
Microsoft Word is desired Installing QRE Professional
For more information on installation and configuration, refer to the Getting
Started section of the KBS QRE Professional Usage Guide.
The QRE Professional Guide documentation on QRE Professional Installation
follows:
QRE Professional Installation
Page 65 of 91
8/8/2005
File Summary
This section lists the files that are installed during the installation process for
each facility.
KB_SQL Server Installer File Summary
By default, all KB_SQL Server setup files are extracted to the \Program
Files\KBS\Server directory.
File Name
CACHE.DEV
CACHE.RTN
DEMO.DAT
DEMO.DB
DSM.DEV
DSM.RTN
GTM.DEV
GTM.RTN
HBOM.DEV
HBOM.RTN
ISM.DEV
ISM.RTN
LICENSE.KEY
LICENSE.TXT
M21.DEV
M21.RTN
MSM.DEV
MSM.RTN
SQL.FN
SQL.PC
SQL.Q1
SQL.Q2
SQL.Q3
SQL.Q4
SQL.Q5
SQLDD.DB
SQLGBL.1
Description
Caché device definitions
Caché installation routines
Sample data for the SQL_TEST demo tables
Table definitions for the SQL_TEST demo tables
DSM device definitions
DSM installation routines
GT.M device definitions
GT.M installation routines
HBOM device definitions
HBOM installation routines
ISM device definitions
ISM installation routines
Optional file that can contain a license key for an
automatic installation
KB_SQL license agreement
M21 device definitions
M21 installation routines
MSM device definitions
MSM installation routines
SQL_FN_* product functions
SQL_* product pseudocolumns
SQL* queries not included in the other SQL.Q files
SQL_SP_* queries
SQL_SUMMARY_* queries
SQL_CHECKUP_* queries
SQL_DD_CHECK_* queries
KB_SQL table exports
KB_SQL global exports
Page 67 of 91
8/8/2005
File Name
SQLGBL.2
SQLGBL.3
SQLRTN.1
SQLRTN.2
SQLRTN.3
SQLRTN.4
SQLRTN.5
SQLSCR.1
SQLSCR.USR
SQLSITE.GBL
STATS.DD
TOUPPER
VERSION.1
Description
KB_SQL routine exports
KB_SQL installation script
User-defined installation script template
Global export of SITE global for new installations
Table statistics for the KB_SQL data dictionary
Unix shell script to convert lowercase filenames to
uppercase
Information regarding the KB_SQL product version
Page 68 of 91
8/8/2005
At Knowledge Based Systems, we are working hard to provide you with intuitive
technical products. Additionally, we try to provide superior documentation to
enable you to work independently. The introduction of our new on-line
knowledge base allows you to access technical information (including viewing the
status of your own issues) 24 hours a day, 7 days a week.
The Online Knowledge Base
You can access the online knowledge base in the following ways:
through the Knowledge Based Systems web site
(http://www.knowledgebasedsys.com) under the Tech Support option
o directly at the support web site at
http://www.knowledgebasedsys.com/support/
o
The available tab options in the Knowledge Base include:
Answers
Frequently asked questions, how to’s, downloads,
problem resolutions, and known problems are all
stored in our online knowledge base. You can search
by product, category, keywords, or phrases.
Ask a Question
Submit a question to KBS Technical Support who will
reply via email.
My Knowledge
Base
Login to check the status of your questions, modify
your answer update notifications, update your personal
profile, or access client-only information and features.
Page 69 of 91
8/8/2005
Logging Into the Online Knowledge Base
To access the privileged area of the online knowledge base, it will be necessary
to log in using an account provided by Knowledge Based Systems.
If you do not have an account for the online knowledge base, please send
e-mail to KBS at [email protected] to request an account.
To log into the online knowledge base:
1. Go to the KBS Knowledge Base My Knowledge Base from the support
home page (http://www.knowledgebasedsys.com/support). The login
window displays.
Page 70 of 91
8/8/2005
2. Enter your User ID and Password and click the Login button to gain
access to the KBS Knowledge Base and Support area. The initial support
tab, Answers displays.
Page 71 of 91
8/8/2005
Searching the Online Knowledge Base
The online knowledge base is a resource for accessing answers to frequently
asked questions, software and documentation downloads, known problems, and
a variety of other technical information about KBS products.
Because technical information about the product is accessible only by
privileged Knowledge Based Systems clients, it will be necessary to log into the
online knowledge base.
To search the online knowledge base:
1. Log into the online knowledge base.
2. Depending on the screen that is displayed select the Answers tab.
Page 72 of 91
8/8/2005
3. Enter your search criteria by using one or more of the search options
available.
4. Click the Search button. The results of the search will be displayed in the
lower portion of the Answers page.
Page 73 of 91
8/8/2005
Submitting Questions to KBS Support
In the event that the information needed is not in the online knowledge base,
questions can be submitted to the KBS Support team by doing the following:
2. Click the Ask A Question tab.
Page 74 of 91
8/8/2005
3. Provide the information requested in the form and click the Submit
Question button at the bottom of the form.
Page 75 of 91
8/8/2005
4. The reference number for the incident will be displayed.
A confirmation email will also be sent to the email address associated with the
user that is logged into the knowledge base when the question was submitted.
The confirmation email will include the information provided in the form as well as
the reference number.
Page 76 of 91
8/8/2005
Reviewing and Updating Incidents Submitted to KBS Support
The online knowledge base provides you with access to all incident that have
been submitted to KBS Support by your organization. These incidents can be
viewed, updated, closed, or reopened at any time. In order to view, update,
close, or reopen incidents submitted by your organization, you must be logged
into the online knowledge base.
To Displaying an Incident:
2. Select the My Stuff tab.
3. Click on My Questions area.
Page 77 of 91
8/8/2005
4. The incidents that the current user has submitted are listed. To view all
incidents submitted by the current user’s organization, check the Display
all questions for my company checkbox.
Page 78 of 91
8/8/2005
5. To view the details for an incident, click on the incident’s summary. This
will display all interactions regarding the incident.
6. If you would like to provide additional information or would like to close the
incident, click the Update Question button.
7. Additional information can be provided in the Results and/or Additional
Information field. If you do not need additional information and would like
to close the incident, click the I no longer need an answer to this
question checkbox.
Page 79 of 91
8/8/2005
8. Click the Submit Update to Question button to send the update to KBS
Support.
Page 80 of 91
8/8/2005
Download the KBS SQL Server
The KBS SQL Server self-extracting installation file can be downloaded by
logging into the KBS Online Knowledge Base. To download the file:
1. From the My Stuff tab of the online Knowledge Base, click on the Downloads
link.
Page 81 of 91
8/8/2005
Education/Training
Knowledge Based Systems offers education and training designed to help you
get the most benefit from KB_SQL and to help you attain a high level of
confidence with the product. The program is composed of several modular,
instructor-led classes that focus on the needs and requirements of specific users
ranging from the novice to the experienced Database Administrator.
Classes are available for delivery at your site or at Knowledge Based Systems’
office. Please contact KBS Technical Support if you interested in more
information regarding education/training.
Page 82 of 91
8/8/2005
Ordering Software
Knowledge Based Systems is working to develop an online ordering system.
Until this system is available, we ask that you continue to fax order forms
(included in this section) to (703) 832-0479.
If you have any questions, please contact KBS Technical Support.
Page 83 of 91
8/8/2005
PRODUCT ORDER FORM
Effective 01/01/2001
Product Name Number of Users ANSI Mumps
Type
KB_SQL v4.x 1-User
Caché
4-Users
System Type
Unit Cost *
Run time (available
for VARs only)
Full development
DSM
8-Users
GTM
16-Users
HBOM
24-Users
ISM
32-Users
M21
48-Users
MSM
64-Users
Other
⇒ * All prices are obtained from the current KBS price list (end users) or your
current VAR contract, based on the number of concurrent users and your current
discount level.
⇒ All payments must be in U.S. currency.
⇒ By default, you will receive a copy of the license number and key by email.
Please complete delivery information on the following page!
Page 84 of 91
8/8/2005
Ordering Software
To complete your order, please supply the following information and fax to 703832-0479.
If you have any questions or need assistance, please contact technical support toll free at
(800) 613-5967 x208.
Company Name:
______________________________________________________
Name of Technical Contact:
___________________________________________
Name of End-User Customer:
___________________________________________
Shipping Address with Name of Contact:
__________________________________
________________________________________
________________________________________
________________________________________
Billing Address with Name of Contact:
__________________________________
(if different from above)
________________________________________
________________________________________
________________________________________
E-mail notification (specify address):
______________________________________
Your Tax Exempt Number:
______________________________________________
Any Special Instructions:
________________________________________________
__________________________________________________
__________________________________________________
Your Purchase Order #:_______________ Purchase Order Date: ____ / ____
/ ____
Page 85 of 91
8/8/2005
Index
Architecture..................................... 7
Auto Start................................ 32, 35
Building
Your Data Dictionary ................. 26
Building ......................................... 22
Building ......................................... 26
Change License Key..................... 31
Client Connections........................ 26
COM/ActiveX DLL......................... 14
COM-based .................................... 8
Configuring
KB_SQL ODBC Server ......... 3, 26
Server Information..................... 39
Configuring ..................................... 3
Configuring ................................... 26
Configuring ................................... 39
Configuring QRE....................... 3, 65
Connections .................................. 38
Create New Data Source window . 59
Data Dictionary Guide..................... 8
Data Sources .......................... 54, 59
DATA.G ........................................ 46
Disable Auto Start ......................... 39
Disable Line Editing ...................... 16
Disable Server .............................. 38
Disk Space.................................... 15
Display Syntax Errors ................... 22
Documentation Download
Instructions ............................ 8, 11
Edit Network Configuration ........... 39
Education/Training .................. 69, 82
Enable Server ......................... 32, 36
EZQ ........................................ 14, 26
Globals.. 8, 12, 15, 20, 22, 26, 31, 46
Hostname/IP Address ................... 53
Importing....................................... 46
Installation Procedures ........... 20, 22
Integrity Check .................. 20, 22, 29
InterSystems ........................... 16, 22
Introduction ..................................... 1
IP Adress ...................................... 59
JOB WATCH................................. 20
KB SQL Server..............................32
KBS Global Import.........................46
KBS Knowledge Base .............22, 70
KBS Routine Import.......................46
KBS SQL Server .....................22, 81
KBS Support .....................69, 74, 77
KBSODBCDriver_<version>_Build_<
Build#>.exe................................54
KBSQL_ANSI_V<Version>_Build_<
Build#>.zip .................................22
License Agreement .......................22
License Key...................................31
Listening........................................53
Logging into KB_SQL....................35
Managing ODBC Data Sources ......8
Mapping ........................................26
My Knowledge Base..........11, 69, 77
My Questions ................................77
My Stuff .........................................81
Namespace ...................................22
Network Configuration.....................8
Network Site Edit Windows .....39, 42
ODBC Driver .. 1, 3, 8, 12, 26, 53, 54,
65, 67
Order Form..............................83, 84
Ping ...............................................63
PKUnzip ........................................22
Port................................................53
Post-Installation.......................15, 26
Pre-Installation ..................20, 22, 29
Program Files/KBS/ODBC ............54
Program Files/KBS/Server ............67
Programming Considerations..........8
QRE Professional
QRE Professional Install File
Summary................................67
QRE Professional........ 1, 7, 8, 13, 65
QRE Professional..........................67
QRE Services............................7, 14
QRE Services Programmer’s
Reference ..............................8, 14
Routine Execute ............................46
Page 86 of 91
8/8/2005
Index
Routine Input Option ..................... 22
Schemas....................................... 26
Security......................................... 26
Server ......................... 22, 32, 38, 39
Server API .............................. 16, 39
Server Initial Execute .................... 39
ServerAPI ..................................... 16
Shutdown...................................... 38
SITE EDIT............................... 26, 39
Site Name window ........................ 26
Software.............................. 3, 69, 83
Solutions Provider Guide ................ 1
SQL globals .................................. 20
SQL Reference Guide..................... 8
TCP/IP.....................................16, 39
Test ODBC Data Source .........53, 63
Trace Options................................39
Unix ...................................16, 22, 67
Updating Licence Information..15, 31
User DSN ......................................59
User-defined Script........................45
VMS Clusters ....................16, 32, 36
Website
Knowledge Based Systems .........8
Website ...........................................8
Windows..................................13, 26
WinZip ...........................................22
Page 87 of 91
8/8/2005

KBS Getting Started Guide

Transcription

Similar documents

How to Install SQL Server 2008

Product Release Bulletin AccountMate 8.1 for SQL and Express July

Tutorial: Database Communication in LabVIEW

Regions CD Check Viewer Installation Guide

Can I use the document camera as a webcam for Skype (and other

Mining For Evil

Marchbanks, Earl - USS Frank E Evans Association

Attack of Slammer worm - A practical case study - Pen Test

Expert Oracle Database 11g Administration

KBSODBCDriver - Support Home Page

MCDBA Exam 70

SQL Anywhere® Server - Programming