Open M Relational Client/Server Troubleshooting Handbook

Purpose

To assist application developers and support staff in resolving common problems with setting up and running the Open M Relational Client/Server.

Introduction

This document is a collection of reference tables, tricks & tips which can be used to troubleshoot problems with the Open M Relational Client and Server. This guide brings together information that was previously published in separate manuals with new information gathered by InterSystems technical support.

Related Documentation

Table of Contents

SECTION I: Open M Server

The Server side is where your M Database resides. The Open M Server can run on top of ISM, DSM, MSM or DTM as long as it has the Open M w/ SQL product installed.
The Relational Client product will allow you to use third party software, such as MSQuery, to access your M database.

Versions

It is important to be running the proper version of M/SQL when setting up your client/server configuration.

Recommendation: Open M w/SQL version F or higher.

(as of Feb. 1, 1996, F.7 release available for most platforms).

How to find out what version of the Open M Server you are running:

>d ^%msql
from the System Management Menu:
select Version

The Open M version will be displayed on the screen.
i.e. This is Version F, Maintenance Release F.7, Freeze # 008

Network Connection Protocol

Once the proper version of Open M w/SQL is installed on your server, you will also need to be sure that you have a supported network protocol such as TCP or DECnet. See your M system manual for what is supported by the M application on your server.

NOTE: If you are not sure about your TCP application, test the TCP open commands described in the Server Master Troubleshooting section.

Server Setup - General

System Defaults

The following will appear after hitting <RETURN> on the field <Communication Information>:

The following window will appear after hitting <RETURN> on the field <Jobbed Process Parameters> if you are running on a DSM system:

<Jobbed Process Parameters> on an MSM system:

Server Setup - TCP/IP

TCP Port - Range Values

If you are using TCP you will need to specify range values for TCP servers.

These are the TCP ports that will be used by the "Server Master" when it jobs off server processes. Valid TCP Port Numbers are 1000 to 65287.

GBI Device - Range Values

For servers running on DTM systems, a GBI device range must also be defined.

NOTE: The GBI devices defined must exactly match the devices defined in the MUMPS.DEV file.

Server Master Management

Systems using TCP for communication require a "Server Master" process to be running. This is the process that handles the management of all of the server processes. Prior to connection, define and start the Server Master(s).

Add/Edit/Delete Server Master List

Start /Stop a single Server Master

Once the Server Master is defined, go to the Start/Stop Server Master menu and try to start it.

Hitting <RETURN> on the field <Start Server Master> will start the Server Master and update its status to "Active".

NOTE: The time it takes to start/stop a server master is based on your Server System Default settings.

Time to start S.M. (in seconds) =         2 x (Open Timeout For Status Check)
                                                                  +    1 x (Delay after closing TCP Port)

Troubleshooting - Server Master

1. Server Master won' t start

2. Server Master dies

If the server master receives an M error, it will cause this process to stop in most cases. If you find that the server master process is gone, check the Server Error Log for errors. Another possibility is that M was stopped and server master was not automatically started.

3. Server Master not automatically starting

When you define a server master you are prompted to start it automatically. In order for this to work, you may need a call to the server master startup routine in your system startup routine (ZSTU for ISM Systems) as follows;

>D autostrt^%omsmsc4(1,1)

DTM Specific Server Setup - TCP/IP

A server running on DTM requires TCP/IP as well as the use of GBI devices. The server setup varies slightly from a non-DTM server as described below.

GBI Device ­ Range Values

GBI device numbers must be in the range 601­699.

InterSystems recommends reserving GBI devices in the range 601-609 to be assigned to server masters. As with TCP port numbers, it is very important that you do not include the Server Master GBI devices in the range of GBI devices allocated to server processes.

Server Master Management

Add/Edit/Delete Server Master

Select a name for your TCP server master
Define Server master with Connection type of "TCP"
Enter the TCP port number in the format:


                GBI,TCPsocket
    Where:      GBI  =  GBI device # (as defined in MUMPS.DEV file),
                TCPsocket = TCP/IP port #
    i.e.        601,51243

Important: In MUMPS.DEV file, you must uncomment the appropriate 600 devices to match your server master and GBI range values. i.e. If your server master is 601 and your GBI device range is 610-620, your MUMPS.DEV file should look something like the following example.

Notice 600 device is defined ­ this is reserved. Also, notice 602­609 and 621­699 are commented out (or not defined). The values in MUMPS.DEV need to match exactly what is defined in server configuration (see steps 1&2 above).

If you have problems, you can try defining less GBI devices (and define less in your server range). Also, try decreasing bufsize for server processes to 8 or 4.

PIF File Requirements

For DTM servers, the PIF file should meet the following requirements (Use PIF Editor to change these):

     Memory Requirements:  KB Required: ­1       KB Desired: ­1
     EMS Memory:           KB Required: 2048          KB Limit:  8098  
     Under Advanced section of PIF Editor, set Background Priorities = 5000

^%umacro Routine

Be sure DTM Manager's namespace includes ^%umacro routine. This is a dummy routine which just contains a QUIT.

DTM.INI File Requirements

The DTM.INI (or VB.INI) file should include the following lines (minimum) 

     appmemory   = 160K
     fore        = 16K, 24K, 144K

Troubleshooting TCP/IP connections

1. Check that your Data Source Name (DSN) points to the TCP port where the Server Master has been defined.

2. Check that the Server Master is running on the Server.
    See Server Master troubleshooting section for more details.

3. Check for any errors in the Server Error log.

4. Check that the DSN specifies a valid directory (or UCI/VOL)

5. Modify timeouts in the Default Server Configuration menu as recommended in the General Server troubleshooting section.

6. Try using 5 digit TCP port numbers for your Server Master and Server Range.

7. Check that your TCP port range does not conflict with the Server Master TCP port number.

8. If your server is running DTM 6.2 try setting MSWITCH to ANS in your DTM .INI (may be in VISUALM.INI) file.

9. If your server is running DSM, be sure that expanded strings are enabled on the volume set(s) containing application, ISC, and Manager UCIs.

10. Is your TCP application supported by the M vendor?

11. If all else fails, restarting TCP server may help clear up port problems.

Server Setup - MTM (Memory to Memory)
MTM connections use TCP/IP ports and their setup is very similar the TCP/IP setup for DTM servers. MTM uses a Server Master, and jobbed Server processes in the same way that TCP/IP connections use them. The only difference is that the Server and the Client are both the same machine. MTM can only run with a DTM server running DTM 6.0 or higher.

Memory­to­Memory GBI Device ­ Range Values
GBI device numbers must be in the range 806­899.
Recommendation: Start with a small range (i.e. 806­808) and build from there.

Add/Edit/Delete Server Master
Select a name for your MTM server master.
Define Server master with Connection type of "Memory to Memory"
Memory­to­Memory Device Number must be in the range 801 through 805

MUMPS.DEV File Requirements
Uncomment the appropriate 800 devices to match your server master and GBI range values.

i.e. If your server master is 801 and your GBI device range is 806­808, your MUMPS.DEV file should look something like the following example.


Notice 800 device is defined ­ this is reserved. Also, notice 802­805 and 809­899 are commented out (not defined). The values in MUMPS.DEV need to match exactly what is defined in server configuration (see steps 1&2 above).

PIF File Requirements
The DTM PIF file should include (Use PIF Editor to change these): 

     Memory Requirements:  KB Required: ­1       KB Desired: ­1
     EMS Memory:           KB Required: 2048     KB Limit:  8098
     Under Advanced section of PIF Editor, set Background Priorities = 5000

^%umacro Routine
Be sure DTM Manager's namespace includes ^%umacro routine.


DTM.INI File Requirements
The DTM.INI file should include the following lines (minimum values) 

     appmemory  = 160K
     fore       = 16K, 24K, 144K

Troubleshooting MTM connections

1. Try defining less GBI devices in your server range (must also be edited in MUMPS.DEV file). Along the same lines, you can try decreasing bufsize for GBI server devices to 8 or 4.

2. Be sure ^%umacro routine is defined in the DTM manager's namespace.If it's not there define the routine containing just a "QUIT".

3. MTM problems are generally due to memory limitations on the machine you are using. Try the connection on another machine whenever possible to compare behavior.

4. Be sure your TCP application supports Windows Sockets version 1.1 and is also supported by your DTM version.

5. Remember to match your GBI device range with the MUMPS.DEV file.

Server Setup - DECnet

DECnet does not require you to manually define and start a Server Master. Instead, we define and use a DECnet object to start up the server process.

Setting up DECnet Connections (ISM Server)

1. Using the VMS editor, create a DCL command procedure file in the systemmanager's directory. You can name this file anything you'd like, (i.e. DECNET. COM). This file calls the M program that runs the server master. The text of this file should be as follows:

     DECNET.COM

     $ SET DEFAULT SYS$M
     $ M "%omsdnet"
     $ EXIT

2. Define your DECnet object.

a. To enter NCP, issue the following command:
        $ RUN SYS$SYSTEM:NCP

b. At the NCP prompt, issue a command with the following syntax:
        NCP> SET OBJECT object_name NUMBER 0 FILE mgr_directory:filename USER username PASSWORD password

Where filename is the name of the file from step 1.
Username and password are VMS level identifiers with sufficient privileges to run Open M.

i.e. NCP> SET OBJECT MSQL NUMBER 0 FILE SYS$M:DECNET.COM USER CLIENT PASSWORD PASS

Setting up DECnet Connections (DSM Server)

1. In DSM, create a routine in your system manager's directory called %OMSDNET (routine name must be in uppercase). The routine should contain the following two lines: 

     D ^%omsdnet
     QUIT

2. Using the VMS editor, create a DCL command procedure file in the system manager's directory. You can name this file anything you'd like, (i.e. DECNET.COM). This file calls the M program that runs the server master. The text of this file should be as follows:

To have multiple environments, create a command procedure file for each environment and change the second line of the text as follows: 

     $ DSM/ENV=xxx ^%OMSDNET

3. Declare your DECnet object to the VMS system.

a. To enter NCP, issue the following command:
        $ RUN SYS$SYSTEM:NCP

b. At the NCP prompt, issue a command with the following syntax:
        NCP> SET OBJECT object_name NUMBER 0 FILE

NOTE: For multiple environments, you must call them from different object names which call the appropriate DCL command procedure.

Troubleshooting DECnet connections

1. Check that the DECnet object is set up correctly, i.e. valid username, password, file # 0, object name matches the object name specified in the Data Source Name (DSN) on the client machine.

2. Check that the DSN is pointing to a valid directory (or UCI/VOL)..

3. Try increasing timeouts in Default Server Configuration menu as recommended in General Server Troubleshooting section.

4. If your server is running DSM, be sure that expanded strings are enabled on the volume set(s) containing application, ISC, and Manager UCIs.

5. Check that your DECnet command file runs without errors.
        i.e. $@DECNET.COM

M/SQL Server - General Troubleshooting

Forced Error Log
When you are experiencing any problems with client server communication, it is a good idea to force errors in the server error log. This is done in the Server System Defaults Screen by setting Force Error logging to "Yes".

NOTE: To delete all errors from the log, kill the global ^%oms("errors")

Server Error log - sample entry

The following error is "Forced" and is expected. Normally this error is not displayed in the log. If Force Error flag is set to "Yes", then it will appear in the log.

Generally, when debugging a problem look for any M errors such as UNDEFINED, SYNTAX, and/or SQL error codes. If the problem is not immediately apparent, call Technical Support.

Stored Procedures

Stored procedure management is an important part of the client server's success. Whenever client and/or server versions are upgraded, all stored procedures should be deleted. Also, if an error is encountered and then corrected, we could also delete stored procedures to avoid propagating the old error.

Yes! there is a trick to deleting all stored procedures. On the Delete Stored Procedure screen only fill in "AND Usage Count (GREATER) Than: 0" as follows:

Default Server Configuration

When connection problems persist, increasing Server System timeouts may help.Key items are the timeout for READS and the TCP timeout for close. Experiment with different values to find the optimum times for your system. (For details on all fields, see appendix)

Global Protections

Generally, these are set up properly during installation, but in some DSM Server installations there may be problems. Seeing an error code 52 on the client or PROTECT errors in the Server error log are good indications of a protection problem. Check that the following globals on the server have RWD privileges (RWP for DSM):

     ^mroutine, ^mtemp, ^mtemp1             in application directory/UCI
     ^%oms, ^mtemp, ^mtemp1                 in managers directory/UCI
     ^m* globals                            in ISC common directory/UCI

Server Debugging

When you are not able to resolve a problem through troubleshooting methods, InterSystems provides error tracing capabilities to help further debug problems.

Caution: The server debug stream is a disk intensive debug log and should only be used at the request of your technical support contact.

If you decide to use this, proceed as follows:

1. Make sure you have room in your database (as well as disk space!)

2. Kill ^%oms("debug")

3. S ^%oms("sys","debug")=1

4. Run the query/connection that is causing your problem

5. K ^%oms("sys","debug")

It is very important that you remember the last step which turns off the debug stream once you have captured the error. If you neglect to do this, your disk will fill up very very quickly!

Setting the above global location will populate the following global when any operations involving communications with TCP/IP are performed:


tcp operation         Operation Description
        "o"                Opens a TCP/IP communication port
        "r"                 Read from a TCP/IP communication port
        "w"               Write to a TCP/IP communication port
        "d"                Disconnect from a TCP/IP communication port
        "c"                Close a TCP/IP communication port

NOTE: You should delete ^%oms("debug") when finished to regain disk space.

SECTION II: Open M Relational Client

Versions 

Client Version string:    M.mm.bbbb
                               M = Major Release number
                               mm = Minor Release number
                               bbbb = Build Number

Installation
Run Windows Setup from diskette, be sure to highlight the InterSystems Open M driver during installation.

How to find out what version of the Open M Relational Client you are running:
From Windows, select
Main Icon
Control Panel Icon
ODBC Icon
Click on the Drivers... Button
Highlight the InterSystems Open M Driver
Click on the About... Button
Next to Version you will see your Relational Client version
i.e. 1.95.0018

Requirements

Network Connection Protocol
TCP/IP - must support Winsockets version 1.1
DECnet Pathworks for DOS - v4.1A, v5

Windows
MicroSoft Windows version 3.1
MicroSoft Windows for Workgroups
MicroSoft Windows 95 (requires Client 1.95 build 18 or higher)
MicroSoft Windows NT (16 bit)

Client Applications
ODBC enabled application
OCI
Detailed list of client support in Appendix A

Additional Client Applications
The following applications have been used by customers in the field, but have only had limited testing by InterSystems (not listed in table in Appendix A):
Cognos Impromptu v3.02 (requires Client 1.95.0018 or higher)
GUPTA SQL Windows (requires all GUPTA patches and client 1.95.0018 or up)
The Reporter

Miscellaneous

Transaction Processing
Currently, we do not support Transaction Processing, in client/server operations.This means that other users can modify data on the Server side while a Client is accessing the data. This feature is in progress currently.

ODBC level 2 compliance.
Client 2.0

32 Bit ODBC driver
Beta testing phase

Client Setup

Defining Data Source Names

The Data Source Name (DSN) is what tells the client how to get to the M server. The DSN consists of the following components:

And, if we don't want to be prompted at connection time we can specify:

It is important to use your Open M w/SQL username/password here (i.e. SYSTEM/SYS), NOT the operating system username/password!

Important: If you choose to enter a username/password here, be sure that the user has the proper privileges to access your M database tables.

Troubleshooting - Relational Client

Common Errors:

1. S1000 Error - General ODBC error code

Usually reflects a problem creating or compiling a stored procedure. This should be accompanied by an SQL error code or a server error message.

Possible reasons:

2. 20603 - Server Fatal Error

A fatal error has occurred on the Server side. You will need to turn on server forced error log and check Server Error log for an SQL or M Error code.

Some reasons that this error may occur:


3. 28007 Error - Device Support not loaded

4. ODBC Conformance errors

Always run =>d all^%dainteg on server after getting a conformance error. Also, be sure to delete all stored procedures after correcting any problems. If you get a -7730 conformance error, it usually means that a field within a view's query is not found, duplicate, or doesn't have a field name within the view. Check the server error log when you see these errors. See the table of ODBC compliance messages in Appendix B for further information on error codes.

5. Microsoft Jet Engine

If you are using a Microsoft client application (i.e. Access, Query, etc.) or a client application that uses the Microsoft Jet-Engine, you will not be able to do inserts, updates and deletes to your M database. You may see errors trying to connect to tables as well. To avoid problems, be sure to edit the file called MSACC20.INI (VB.INI for Visual Basic) as follows:

Also, If you are using Microsoft Access, you may see 'invalid username' errors trying to attach to tables, but then your process continues. This is due to Microsoft Access expecting tables to be owned by its Admin user. To avoid this error, add the following line to MSACC20.INI:

NOTE: The above instructions are for MicroSoft Jet Engine 2.0 applications only, i.e. Visual Basic 3.0, Access 2.0. For Jet Engine 3.0 ('95 Versions) these parameters can be set via the Registry.

6. TCP Errors

TCP errors may mean there is a low level TCP problem, usually TCP is not working between the 2 machines or you are not using a TCP that supports Winsockets 1.1. Try telnet-ing to the server to see if the connection works. Also check that the client's ip address is listed in the servers host file.

7. Data Source Name

Always check each item in your data source name (DSN) carefully. If changes are made, exit your application and try reconnecting.

Client Debugging

In cases where you are unable to resolve a client connection/operation issue, the Open M Relational Client has its own debugging capabilities. This is usually requested when calling Technical Support with a client problem.

Steps to invoke client debugger (for Relational Client 1.5 and up):

1. Insert Client diskette into drive

2. From DOS prompt in the WINDOWS\SYSTEM directory type: A:\DEBUG\DEBUGDLL
Respond (A)ll at the prompt to overwrite messages

3. From Windows, select Run from the Program Manager File menu.
Type A:\DEBUG\CLIDEBUG at command line.

4. This should bring up the Profiler window
Choose Debug Flags from File Menu

5. Select the following flags:
        Dump Stream         All Errors         Device QIO         Device APIs
        API Utility         API Sub­Functions         API Entry Point         Library Loaded

6. Click on UPDATE and then close the Profiler Window

7. Restart Windows to activate Debugger

  1. The log file will be called OPENM.LOG in the WINDOWS directory.

NOTE: To include the ODBC trace file in the client log file, redirect ODBC trace to the OPEN.LOG file in the WINDOWS directory.


NOTE: To find an error in OPENM.LOG file, search for "ERROR:" If you find an error, check the tables in Appendix B for error description.

Client/Server Troubleshooting Quick Checklist

On the Server:

1. Check the Server Configuration Defaults. Key items here are the timeout for READS and the TCP timeout for close. Increasing these values often will help. READ timeout can be set to -1 to disable. TCP timeout for close should be at least 5 seconds.

2. If you are using a DTM server, check that the routine %umacro exists in the system namespace. This routine should exist but just contains a QUIT.

3. Check that your server master is running (for TCP and MTM).
Check that your DECnet object exists - default name is MSQL
Check that your DECnet command procedure runs without any errors.

4. If the are no errors in the Server Error Log, enable forced error logging from Default Server Configuration menu and re-check for errors in the log.
If you see SQL errors in the log, look them up in the tables in Appendix B.

5. Delete the stored procedures & try again.

On the Client:

1. Double-check your Data Source Name. It should have:

2. Be sure your network protocol is correct. For Relational client 1.95, you must have TCP that supports Windows Sockets 1.1.

3. Be sure your TCP (or DECnet) directory is in the path.

4. Do you have enough memory? Can you test with another PC?

  1. Try getting a client LOG file and look for any errors. Check Appendix B for error codes, as well as the section on Common Errors (page 28).


InterSystems Technical Support

(    (617)621-0700 phone
        (617)494-1631 fax
        support@intersys.com

Ü     In order to expedite your problem resolution, please provide the following information when you contact InterSystems support:

1. Version of Open M w/SQL       i.e. 6.1-F.7, etc.
2. Version of Relational Client       i.e. 1.95.0013
3. Client application version          i.e. MSAccess 2.0
4. Networking protocol                 i.e. DECnet V5
5. Any Client/Server Errors you are experiencing
6. Brief problem description
    i.e. When I try to attach from MSAccess, I get a 20603 error on the client and a <FILEFULL> error in the server error log.
7. OPENM.LOG file if possible

APPENDIX A

TABLES and USEFUL INFORMATION

Application Tools Supported by the Relational Server

You need this API
With these application tools
In this tier

ODBC
Microsoft Access 2.0

Microsoft Excel 5.0 or higher

Power Builder 4.0

Visual Basic 3.0

Visual C++ 1.5 or higher

Microsoft Office 4.2 or higher

Microsoft Word 6.0


Tier 1

Tier 1

Tier 1

Tier 2

Tier 2

Tier 1

Tier 1


OCI
Focus

JAM

Microsoft Excel 3.0 or 4.0

Pilot Lightship 3.01 or higher

Q+E 5.0

WordPerfect for Windows


Tier 1

Tier 2

Tier 2

Tier 2

Tier 1

Tier 2

Tier 1 - Extensively tested
Tier 2 - Minimal testing

NOTE: The versions listed are very important to the success of the Relational Client

Open M Server System Requirements

Platform
M Version
Open M Version
Networking Supported

UNIX
ISM V5.1

ISM V5.7 or higher


E.5

F.1 or higher


TCP

TCP / DECNet


VAX-VMS
ISM v6.4

ISM v6.9 or higher

DEC Standard v6.0a-v6.2

DEC Standard v.6.3


E.5

F.1 or higher

E.5

F.1 or higher


TCP

TCP / DECNet

TCP

TCP / DECNet


PC
DTM v4.8

DTM v6.0 or higher


F.4 or higher

F.4 or higher
TCP

TCP / MTM

E.5 only supports the OCI API interface.
TCP vendor must be supported by the M system running on the server.
MTM is only supported in Open M v F.6 or higher - may be discontinued in future releases.

Client System Requirements

Application Tool & Version
Hardware
Operating System
Network Software

JYACC JAM/dbi 5.03 or higher
VAX
VMS
TCP

FOCUS 6.5 or higher
IBM RS/6000

Hewlett-Packard

DEC Risc

VAX


AIX

HP-UX

Ultrix

VMS


TCP

Any of these:
Microsoft Access 2.0
PowerBuilder 4.0
Visual Basic 3.0
Crystal Reports 2.0 for Visual Basic 3 Q+E MultiLink for Visual Basic
Visual C++ 1.5 or higher with
Microsoft Foundation Classes
WordPerfect for Windows 6.0
Pioneer Software Q+E 5.0
Pilot Lightship 3.01 or higher
LightShip Lens 3.0 or higher
MS Excel 3.0 or higher; v 3.0 and 4.0 must use Q+E 5.0 for Q+E Add-in Macro
All of these:

IBM PC or compatible with a 386 processor, 4MB of memory, and a hard disk. We recommend a 486 processor or higher and 8MB of memory.

VGA, 8514/A, or Hercules Graphics Adapter

Microsoft mouse or compatible pointing device


Both of these:

Microsoft Windows 3.1

MS-DOS 3.1 or higher


One of these:

TCP

DECNet

Pathworks for DOS 4.1

and 5

DTM



NOTE: The versions listed are very important to the success of the Relational Client

Application Tool & Version
Hardware
Operating System
Network Software

 C compiler/C application for Windows
All of these:

IBM PC or compatible with a 386 processor, 4MB of memory, and a hard disk. We recommend a 486 processor or higher and 8MB of memory.

VGA, 8514/A, or Hercules Graphics Adapter

Microsoft mouse or compatible pointing device


One of these:

Microsoft Windows 3.1

with MS-DOS 3.1 or higher

OS/2 Version 2

Windows NT

Version 3.1


One of these:

TCP

DECNet

Pathworks for DOS 4.1

DTM


C compiler/C application for UNIX
DG AviiON

IBM RS/6000

Hewlett-Packard

DEC Risc

SCO

VAX


DG/UX

AIX

HP-UX

Ultrix

UNIX

VMS


TCP

TCP applications must support Windows Sockets 1.1

Components of the Data Source Name

Parameter
Definition
Required/

Optional


Data Source Name
A user-defined name
Always required

Description
A description of this Data Source Name
Optional

Network Type
TCP, DNET, or MTM
Always required

M/SQL Server Parameters for TCP

TCP Host
System name or ip address of the server. If no system name is defined , you must use the full internet address, in the form nnn.nnn.nnn.nnn
Required

for TCP


TCP Port
The TCP network port to which you want to connect. You must use the port # that is defined for your server master. Obtain this # from your server system manager. If your server uses InterSystems' default port ranges, port #s for server masters must be from 5000 through 9999, or 11001 through 20000. To avoid possible conflicts with other uses, it is best to use only 5000 through 9999.
Required

for TCP


Location
Database path of the Open M/SQL database that contains the data you want to access.
Required

for TCP


M/SQL Server Parameters for DECNet

System
Host name of the server machine. Note that you must use this name, not the actual DECNet address, in the connection string.
Required

for DECNet


Object
The name of the object you use to connect to server. default = MSQL.
Required

for DECNet


Database
Directory path of the Open M database that contains the data you want to access. For a server running ISM, use the form physical drive:[directory]. For a server running DSM, use the form UCI,volume
Required

for DECNet


M/SQL Server Parameters for MTM

GBI Port
Generic Buffered Interface port as defined in the DTM.INI file. The device I/O for MTM connections, normally a # in the range 800-899.
Required

for MTM


NameSpace
The DT-MAX namespace name for Open M database as defined in the Namespace Name parameter of the DT-MAX DTM.MAP file.
Required

for MTM


Open M/SQL User Identification Parameters

DBSM User ID
Open M RDBMS Username that can log on through this DSN. If you specify the User ID and Password when you define the DSN, the user does not specify them when connecting to the server.
Optional

DBMS Password
Open M RDBMS Password for username (if specified)
Optional

High Speed Fetch
READ only connection that allows you to pre-fetch as many rows as possible asynchronously. Overrides default ODBC setting "READ-WRITE" connection.
Optional

Server System Defaults

Field
Meaning
Default Value

Job Server Timeout
Number of seconds a Server Master attempts to job off a server process to handle a client request. If the connections does not succeed within this time (for example, because the maximum user license limit is reached), the client receives a "failed login" message.
5 seconds

Open Timeout
Number of seconds a jobbed Server process attempts to open a TCP port. If the open does not succeed within this time (for example, because all ports are busy), the Server

process will terminate with an error message sent back to the client by the Server Master.


5 seconds

Read Timeout
Not supported for Open M RDBMS version E.6
360 sec.

Open Timeout for Status Check
Number of seconds the system attempts to open a TCP port for the purpose of checking the status of the Server Master.
UNIX -> 3

DTM -> 5

DSM -> 2


Delay after Closing TCP port
Number of seconds the system hangs after closing a TCP port in order to allow for synchronization of system resources.
UNIX -> 2

DTM ->5

DSM ->3

Save Stored Procedures
Here, you may select one of the following choices to determine whether or not the Server saves SQL requests as stored procedures after it has processed them:

Save -The Server automatically saves SQL requests as compiled routines and files them as stored procedures. It always stores SQL requests from third party software. It stores SQL requests submitted by C programs when the OMS_REQ_SAVE flag is set to 1, which is the default.

Don't Save - The Server does not store client SQL requests.


Save

Force Error Logging
Here, you may answer Yes or No to indicate whether or not the Server should maintain an error log for all server related errors or for fatal errors only.

No - The Server maintains an error log only for fatal errors that cannot be returned by an error message to the client. This error log should be adequate for your debugging purposes.

Yes - The Server forces all Server related errors system-wide into the error log. This includes many non-serious errors that are returned by error message to the client. InterSystems does not recommend forced error login for customer use.


No

Check Object Differences
This field sets up a system-wide default used to determine whether or not to check object differences when the Server uses a stored procedure to process an SQL request.

When the Server receives an SQL request, it first checks to find a stored procedure that matches the text of the request. If it finds a matching stored procedure, it then checks the object differences switch. If it is ON, the Server checks to make sure that all tables and views listed in the FROM clause of the SQL request have not been edited since the last time the stored procedure was executed. If it detects that changes have been made to these objects, the server knows to recompile/regenerate the request in order to incorporate those changes. If it finds that no changes have been made to the source objects, the Server does not recompile.


Yes

Syntax Checking
Here, you may select On or Off to indicate whether or not you want the Server to perform syntax checking on a client SQL request when compiling it into a stored procedure. Turning syntax checking Off can improve performance by making the SQL request compile faster.
Off

Additional Error Logging
Here, you may insert a line of M code up to 80 characters in length to be executed whenever the Server receives an error. Typically, this is used to invoke an error logging routine into which the Server will log all pertinent information whenever it receives an error.

To invoke your own logging routine, you might enter code such as the following:

do ^%errlog


None

Communication Information
Press <RETURN> on this action field to access the Communication Information window. This Window requests the system-wide TCP/IP address, which the system needs in order to shut off its own processes in case the Server Master goes down..
N/A

Jobbed Process Parameters
This field applies only to Servers running in the VAX/DSM environment. Press <RETURN> to access the Jobbed Process Parameters window, where you can define additional DSM-specific job parameters required by the Server.
N/A

MsysConf Table Information

MSysConf is a table that may optionally be defined in a given database (ie: on your M system). The table definition is by Microsoft. The contents of the table tune the performance of the MS­Jet Engine.

TABLE DEFINITION:: MSysConf

Column Name                 Datatype                 Description
­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­--------------------------­
Config                            Number(5,0)           The number of the configuration option
chValue                          Text(255)               The text value of the configuration option
nValue                            Number(10,0)         The integer value of the configuration option
Comment                       Text(255)                Description of the option
FetchDelay                     Number(10,0)          indicates how often to fetch another chunk of query results
FetchRows                     Number(10,0)          indicates how many rows to fetch
­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­--------------------------­­­­­­­­­­­­­­­­­­­­­­­­­­­

Descriptions from Microsoft::

Article, Jet Database Engine ODBC Connectivity (c.1993)

"Currently, only one option is defined: Config = 101. If the corresponding nValue is non­zero, it is ignored. But if nValue = 0, Jet will never store user ID and password information in tables attached from this server. The Attach Table check box "Save login ID and password locally" will be ignored. Users will be forced to type a user ID and password upon first using the attached table. This option was created to permit database administrators concerned about security to eliminate the possibility of unauthorized users gaining access to data through using another person's computer."

....

In a another document, ODBC: Architecture, Performance, and Tuning (March 24,1994), the following addition was made:

"More MSysConf settings: two new settings in the server­based MSysConf configuration table control how fast Microsoft Access does background population of query results:

* FetchDelay :indicates how often to fetch another chunk of query results

* FetchRows : indicates how many rows to fetch

These two setting have defaults, incase MSysConf doesn't exist: 100 rows are fetched every 10 seconds of idle time. These settings allow a system administrator to trade server locking against network traffic, and not allow ordinary users to override these settings.

APPENDIX B

ERROR CODES

Client Error Codes

Errors that may occur on the client /client log file:10000+

1         Not owner
2         No such file or directory
3         No such process
4         Interrupted system call
5         I/O error
6         No such device or address
7         Arg list too long
8         Exec format error
9         Bad file number
10         No children
11         No more processes
12         Not enough core
13         Permission denied
14         Bad address
15         Block device required
16         Mount device busy
17         File exists
18         Cross-device link
19         No such device
20         Not a directory
21         Is a directory
22         Invalid argument
23         File table overflow
24         Too many open files
25         Not a typewriter
26         Text file busy
27         File too large
28         No space left on device
29         Illegal seek
30         Read-only file system
31         Too many links
32         Broken pipe
33         Argument too large
34         Result too large
35         Operation would block
36         Operation now in progress
37         Operation already in progress
38         Socket operation on non-socket
39         Destination address required
40         Message too long
41         Protocol wrong type for socket
42         Protocol not available
43         Protocol not supported
44         Socket type not supported
45         Operation not supported in socket
46         Protocol family not supported
47         Address family not supported by protocol family
48         Address already in use
49         Can't assign requested address
50         Network is down
51         Network is unreachable
52         Network dropped connection on reset
53         Software caused connection abort
54         Connection reset by peer
55         No buffer space available
56         Socket already connected
57         Socket is not connected
58         Can't send after socket shutdown
59         Too many references - can't splice
60         Connection timed out
61         Connection refused
62         Too many levels of symbolic links
63         File name too long
64         Host is down
65         No route to host
66         Directory not empty
67         Too many processes
68         Too many users
69         Disc quota exceeded

Open M Relational Client Error Messages

Message Code
Description

Errors from Open M Client (ORACLE connections)

00942
Table not found. Make sure you are in the right directory and that you have entered a valid table name.

00904
Field not found in table. Make sure you have entered a valid column name. You can query ACCESSIBLE_COLUMNS to learn the fields in any table.

01001
Invalid Cursor. This error indicates a problem in the Open M Relational Data Dictionary. Notify your server system manager.

01002
Fetch out of sequence. This error indicates a problem in your application.

01017
Invalid username/password. Log on to the server again, using a valid username /password.

01031
Insufficient privileges. You may have issued an improper GRANT statement.

01405
Fetched column value is NULL. This is a warning; however, LightShip treats it as an error, and does not retrieve any data after the null value.

01406
Fetched column value was truncated. This is a warning.

03114
Connection not available. You receive this error when you are not logged on correctly, or if your Server port has been shut down for any reason: licensing problems, Server system shutdown, long inactivity on a port, etc. Issue a ping command to the Server to check your connection, or check that the port you requested is currently available. You may need to use a different Server port.

00603 or 20603
Fatal Error occurred on the Server in your SQL statement. Check the SQL Server error log for more information on the error.

25021
SELECT request processed cannot contain an INTO clause

Errors from Open M Client (ODBC Connections)

00000
Successful completion

01002
Disconnected Error
01004
Data truncated

01S00
Invalid connection string error

08001
Unable to connect to data source

08004
Data source rejected establishment of connection

08S01
Communication Link failure

21S01
Insert value list does not match column list

22003
Numeric value out of range

22005
Error in assignment

22008
Datetime field overflow

24000
Invalid cursor state - function calls out of order

28000
Invalid authorization specification

34000
Invalid cursor name

37000
Syntax error or access violation

42000
Syntax error or access violation

IM001
Driver does not support this function

S0002
Base table not found

S0022
Column not found

S1000
General Error - see M return code for for more information

S1001
Memory allocation failure

S1002
Invalid column number

S1009
Invalid argument value

S1010
Function sequence error

S1090
Invalid string or buffer length

S1097
Column type out of range

S1102
Table type out of range

S1110
Invalid driver completion

S1C00
Driver not capable

Open M Relational Server Error Codes

Error Code
ORACLE Error Code
Message

00000
00000
Successful completion

00001
00900
Invalid SQL statement

00002
00002
Exponent digits missing after "E"

00003
00003
Closing quote ("") missing

00004
25304
A term expected, beginning with one of the following: identifier, constant, aggregate, %ALPHAUP, %UPPER, %EXACT, $$,:,+,-,(,NOT,EXISTS,or FOR)

00005
01785
Column # specified in ORDER does not match SELECT list

00006
25306
ORDER must specify column #, not names, when after UNION

00007
25307
ORDER column is not in SELECT list

00009
25309
Incompatible SELECT list used in UNION

00010
25310
The SELECT list of the subquery must have exactly one item

00011
25311
A scalar expression expected, not a condition

00012
25312
A term expected, beginning with one of the following: identifier, constant, aggregate,$$,:,(,+,-, %ALPHAUP, %UPPER, %EXACT

00013
25313
An expression other than the subquery expected here

00014
00920
A comparison operator is required here

00015
25315
A condition expected after NOT

00016
25316
A qualifier SOME or ALL expected after the FOR in the for-

expression


00017
25317
A for-condition expected after the (in the for-expression)

00018
25318
IS (or IS NOT) NULL predicate can be applied only to a field

00019
00934
An aggregate function cannot be used in a WHERE clause

00020
25320
Name conflict in the FROM list over label

00022
25322
ORDER must specify column names, not numbers, after 'SELECT *'

00023
00964
Label not listed in FROM

00024
00942
Table or View not found

00025
25325
Input Error encountered after end of query

00026
00923
Missing FROM clause

00027
00918
Ambiguous labels for field

00028
25328
Host variable name must begin with either % or a letter

00029
25329
Field ambiguous/not found

00030
00942
Table or View not found

00031
00904
Field not (found/unique) in table

00032
25332
Outer-join symbol (=*) must be between two fields

00033
25333
No field(s) found for table

00034
25334
Contradictory conditions: 'f IS NULL' vs. 'f=constant''

00035
25335
Contradictory conditions: 'f IS NULL' vs. 'f in range'

00036
25336
Contradictory conditions: 'f IS NULL' vs. 'f=expression'

00037
25337
Contradictory conditions: constants should satisfy condition

00038
25338
No master map for table

00039
25339
No RowID field for table

00041
25341
An extrinsic function call must have the form '$$tag^rou(...)'

00042
01756
Closing quote ("""") missing following pattern match

00051
25351
SQL Statement expected

00052
25352
Cursor (Already/Was Not) DECLAREd

00053
25353
Constant or variable expected as new value

00054
25354
Array designator (last subscript omitted) expected after values

00055
25355
Invalid GRANT <role> TO or REVOKE <role> FROM

00056
25356
Action not applicable to an object of this type

00058
25358
Object type not found

00059
25359
Cannot have more than one field

00060
25360
An action (%ALTER, SELECT, UPDATE, etc.) expected

00061
25361
Cursor not updatable

00062
25362
Additional new values expected for INSERT/UPDATE

00063
25363
Data Exception - invalid escape character

00099
25399
Privilege violation

00100
01403
No (more) data found

00101
101
Attempt to open a cursor that is already open

00102
102
Operation (FETCH/CLOSE/UPDATE/DELETE...) attempted on unopened cursor

00103
25403
Positioned UPDATE or DELETE attempted but the cursor is not positioned on any row

00104
25404
Field validation failed in INSERT

00105
25405
Field validation failed in UPDATE

00106
25406
Row to DELETE not found

00107
25407
Table validation failed

00108
0400
Required field missing; INSERT or UPDATE not allowed

00109
25409
Cannot find the row designated for UPDATE

00110
25410
Locking conflict in filing

00111
25411
Operation not licensed on this system

00112
25412
Access violation

00201
25501
Table or View name not unique

01000
01000
Maximum open cursors exceeded

Note: up to 255 cursors are permitted for a given connection


01001
01001
Invalid cursor

01002
01002
Fetch out of sequence

01003
01003
No statement parsed

01006
01006
Bind variable does not exist

01007
01007
Variable not in select list

01008
01008
Not all variables bound

01012
01012
Not logged on

01013
01013
User requested cancellation of current operation

01017
01017
Invalid Username/Password

01024
01024
Invalid data type in 'obndrv','obndrm', or 'odefin' call

01031
01031
Insufficient privileges

01403
01403
No data found

01405
01405
Warning: Fetched column values is NULL

01406
01406
Warning: Fetched column value was truncated

01454
01454
Cannot convert select item value to numeric data type

01455
01455
Value overflows specified integer data type

01459
01459
Invalid length specified for variable character string

01483
01483
Invalid length for DATE or NUMBER bind variable

03114
03114
Not connected to server

20019
00019
Maximum sessions per process exceeded

20020
00020
Maximum number of processes exceeded

20603
00603
Fatal error occurred

25001
25001
Invalid flag specified in 'oms_flag_set' or 'oms_flag_get'

25002
25002
Invalid flag specified in 'oms_flag_set'

25003
25003
Invalid interface value specified in 'oms_set-interface'

25011
25011
Stored procedure (Named Request) does not exist

25012
25012
Routine (Named Request) already exists

25021
25021
SELECT request processed via 'osql3' cannot contain an INTO clause

25022
25022
The 'oexn' function can be used with INSERT, UPDATE, and DELETE requests only

25031
25031
Invalid directory

25032
25032
Unable to start server

25033
25033
Client and server versions are not compatible

25037
25037
Invalid suer ID string

25039
25039
Failure in connecting to server

25050
25050
Invalid server function

25177
25177
Read terminated on 'Timeout'

25180
25180
Unable to read from communication device

25181
25181
Unable to write to communication device

25188
25188
Unable to write to server

25189
15189
Unable to write to Server Master

25197
25197
Unable to assign a server communications port

25198
25198
Unable to open Server communications

25199
25199
Unable to open Server Master Communications

25603
25603
Termination due to interrupt

25604
25604
Licensing security violation

26000
26000
Server Master successfully started

26001
26001
Server Master not started

26002
26002
Server Master successfully stopped

26003
26003
Server Master not stopped

26004
26004
Server Master not running

26005
26005
Server Master already running

26006
26006
Server not stopped

26007
26007
Server not running

26008
26008
Server successfully stopped

26020
26020
Invalid routine (stored procedure) name

27016
27016
Warning: UPDATE or DELETE statement does not contain a WHERE clause

28001

Client - Bad active cursor index

28002

Client - Bad message format

28003

Client - Unknown network transport

28004

Client - Could not allocate memory

28005

Client - Maximum number of logins reached

28006

Client - No low level devices found

28007

Client - Communications to server failed

28008

Client - Wrong version of server protocol

28009

Client - Wrong function type returned from server
28010

Client - Wrong type of function returned from the server

28011

Client - Wrong active cursor number returned from server

28012

Client - Invalid buffer length

28013

Client - Invalid server identification

28014

Client - Not a valid hostname during lookup

28015

Client - Bad server identification string

28999

Client - UNKNOWN ERROR

MicroSoft Jet Engine ODBC Spec-Compliance Errors

Error
ODBC Call
Condition causing the error

-7701
SQLGetInfo(ODBC_API_CONFORMANCE)
*pcbInfoValue !=2

-7702
SQLGetInfo(ODBC_API_CONFORMANCE)
wValue <1

-7703
SQLGetData(fCType=SQL_C_CHAR)
Call return "driver could not convert"

-7704
SQLGetTypeInfo(SQL_ALL_TYPES)
neither SQL_CHAR nor SQL_VARCHAR was returned; type support is insufficient

-7705
SQLGetTypeInfo=>SQLNumResultsCols
*pccol <6

-7706
SQLGetTypeInfo=>SQLGetData(TYPE_NAME)
*pcbValue <=0

-7707
SQLGetTypeInfo=>SQLGetData(DATA_TYPE)
*pcbValue !=2

-7708
SQLGetTypeInfo=>SQLGetData(PRECISION)
*pcbValue !=0 or *pcbValue!=4

-7709

odbc.dll missing oAPI function

(possibly bad odbc.dll)


-7710
SQLSetParam(fSQLType=SQL_VARCHAR)
driver could not convert

-7711
SQL Error
An error was returned by an ODBC call, but no error string

-7712

primary key > 255 bytes

-7713

SQL_INVALID_HANDLE returned by ODBC API. ie:

driver claims hen/dhbc/hstmt is invalid


-7714
SQLGetTypeInfo=>SQLNumResultCols
*pccol<9

-7715
SQLTables=>

SQLGetData(TABLE_OWNER/TABLE_NAME)


length(ownername.tablename) > 255 bytes

-7716
SQLTables=>SQLGetData(TABLE_NAME)
*pcbValue<=0

-7717
SQLTables=>SQLGetData(TABLE_TYPE)
*pcbValue<=0

-7718
SQLTables=>SQLGetData(TABLE_TYPE)
*pcbValue>128

-7719
SQLStatistics=>SQLGetData(COLUMN_NAME)
total length of columns for index >255 bytes

-7720
SQLGetInfo(SQL_CURSOR_COMMIT_BEHAVIOR)
*pcbInfoValue!=2

-7721
SQLGetInfo(SQL_CURSOR_ROLLBACK_BEHAVIOR)
*pcbInfoValue!=2

-7722
SQLTables=>SQLNumResultsCols
*pccol<4

-7723
SQLSpecialColumns=>SQLNumResultsCols
*pccol<2

-7724
SQLSpecialColumns=>SQLGetData(COLUMN_NAME)
*pcbValue<=0

-7725
SQLGetTypeInfo=>SQLGetData(SEARCHABLE)
*pcbValue!=2

-7726
SQLGetTypeInfo=>SQLGetData(SEARCHABLE)
value out of range

-7727
SQLColumns=>SQLNumResultCols
*pccol<11

-7728
SQLColumns=>SQLGetData(TABLE_OWNER)
*pcbValue<0

-7729
SQLColumns=>SQLGetData(TABLE_NAME)
*pcbValue<=0

-7730
SQLColumns=>SQLGetData(COLUMN_NAME)
*pcbValue<=0

-7731
SQLColumns=>SQLGetData(DATA_TYPE)
*pcbValue!=2

-7732
SQLColumns=>SQLGetData(PRECISION)
*pcbValue!=0 or 4

-7733
SQLColumns=>SQLGetData(SCALE)
*pcbValue!=0 or 2

-7734
SQLColumns=>SQLGetData(NULLABLE)
*pcbValue!=0 or 2

-7735
SQLColumns=>SQLGetData(NULLABLE)
value out of range

-7736
SQLStatistics=>SQLNumResultCols
*pccol<12

-7737
SQLStatistics=>SQLGetData(TABLE_OWNER)
*pcbValue<0

-7738
SQLStatistics=>SQLGetData(TABLE_NAME)
*pcbValue<=0

-7739
SQLStatistics=>SQLGetData(NON_UNIQUE)
*pcbValue!=2

-7740
SQLStatistics=>SQLGetData(INDEX_QUALIFIER)
*pcbValue<0

-7741
SQLStatistics=>

SQLGetData(INDEX_QUALIFIER/INDEX_NAME)


length(qualifier.indexname)

>255 bytes


-7742
SQLStatistics=>SQLGetData(INDEX_NAME)
*pcbValue<0

-7743
SQLStatistics=>SQLGetData(TYPE)
*pcbValue!=2

-7744
SQLStatistics=>SQLGetData(TYPE)
value out of range

-7745
SQLStatistics=>

SQLGetData(TYPE/NON_UNIQUE/INDEX_NAME)


TYPE==SQL_TABLE_STAT, but either NON_UNIQUE or INDEX_NAME is non-NULL

-7746
SQLStatistics=>

SQLGetData(TYPE/NON_UNIQUE/INDEX_NAME)


TYPE!=SQL_TABLE_STAT, but either NON_UNIQUE or INDEX_NAME is non-NULL

-7747
SQLStatistics=>SQLGetData(COLUMN_NAME)
*pcbValue<=0

-7748
SQLStatistics=>SQLGetData(COLLATION)
*pcbValue!=0 or 1

-7749
SQLStatistics=>SQLGetData(COLLATION)
value not 'A' or 'D'

-7750
SQLGetInfo(SQL_TXN_CAPABLE)
*pcbInfoValue!=2

-7751
SQLGetInfo(SQL_TXN_CAPABLE)
value <0 or >2

-7752
SQLGetInfo(SQL_DATA_SOURCE_READ_ONLY)
*pcbInfoValue!=1

-7753
SQLGetInfo(SQL_DATA_SOURCE_READ_ONLY)
value not 'Y' or 'N'

-7754
SQLGetInfo(SQL_IDENTIFIER_QUOTE_CHAR)
*pcbInfoValue!=1

-7755
SQLGetInfo(SQL_IDENTIFIER_QUOTE_CHAR)
value '.' or alphanum

-7756
SQLGetInfo(SQL_STRING_FUNCTIONS)
*pcbInfoValue!=4

-7757
SQLGetInfo(SQL_NUMERIC_FUNCTIONS)
*pcbInfoValue!=4

-7758
SQLGetInfo(SQL_TIMEDATE_FUNCTIONS)
*pcbInfoValue!=4

-7759
SQLGetInfo(SQL_SYSTEM_FUNCTIONS)
*pcbInfoValue!=4

-7760
SQLGetInfo(SQL_OUTER_JOINS)
*pcbInfoValue!=1

-7761
SQLGetInfo(SQL_OUTER_JOINS)
value not 'Y' or 'N'

-7762
SQLGetInfo(SQL_EXPRESSIONS_IN_ORDERBY)
*pcbInfoValue!=1

-7763
SQLGetInfo(SQL_EXPRESSIONS_IN_ORDERBY)
value not 'Y' or 'N'

-7764
SQLGet Info(SQL_CONCAT_NULL_BEHAVIOR)
*pcbInfoValue!=2

-7765
SQLGet Info(SQL_CONCAT_NULL_BEHAVIOR)
value not 0 or 1

-7766
SQLGetData(SQL_C_BIT)
pcbvalue!=1

-7767
SQLGetData(SQL_C_SHORT)
pcbValue!=2

-7768
SQLGetData(SQL_C_TIMESTAMP)
pcbValue!=

sizeof(TIMESTAMP_STRUCT)

Home | M Technologies | Support | Company | Contact

MOVE TO CACHÉ

© Copyright 1996-2000 InterSystems Corporation. All Rights Reserved.
email: wwwadmin@intersys.com

Copyright 1996 © InterSystems Corporation. All Rights Reserved.
wwwadmin@intersys.com