(#203) Installation and Configuration Troubleshooting

To as great a degree as possible, the SOS system was designed to be self-correcting. In addition, the database in which your data are stored was specifically chosen for its proven track record for both reliability and performance. Nevertheless, electrical anomalies, hardware failures, and accidents of one kind or another can potentially create difficulties. Here are some situations that might arise and steps you can take to recover.

Database Corruption

If you are unable to start the database and determine that the problem is corruption of the database files, the usual course of action is to:

Before doing anything else, make a copy of all files in the DATA folder under SOS (or other folder, if your data is not located in the default folder). Ideally, burn a copy of the files onto a CD or DVD.

Identify and correct hardware problems (such as insufficient disk space, faulty hard drive, defective hard drive controller, or failing computer power supply) that might have caused the problem.

Restore from your most recent backup. If you backup only the DB files and not the matching LOG file, then be sure to rename or move the current log file before trying to restart the database after restoring your backup.

If the backup starts normally, it may be possible to apply the current log in order to bring it up to date. A technician at SOS can talk you through this process.

If you do not have a good, current, backup, you now know how important it is to make backups and verify them. It may still be possible to recover some or all of your data. Contact SOS to discuss possibilities and costs.

Authentication Error

The program seems to start normally, but as soon as it tries to add or update any data the system stops with an “Authentication error (8001)”.

Your copy of SA is a special “authenticated” edition that limits full usage to programs provided by SOS. These programs contain a special key that must be provided to the database before it will permit the program to modify any information. The details of the key must therefore be present in both the database and the program you are running. If you have just upgraded from a pre-2001 release of the software, there is some chance that the database has not been properly authenticated. You can try to run the SETAUTHN.EXE program (located in your SOS folder) to reinstall the authentication key in the database. Be sure to stop the database and restart it after running this program.

Unable to Connect to Database

On startup, the first thing that an SOS program does is to establish a connection to the database. The normal log-in window appears after the connection has been established. If the ODBC configuration window appears instead, this is a sure sign that the database is not accessible. Listed below are a variety of reasons why this might happen and how the problem can be corrected.

· The ODBC Configuration window will appear if the database cannot be located on a server (network) or started (standalone).

· Improperly Configured Firewall

If you are running firewall software such as Norton Internet Security or ZoneAlarm on your database server system and/or your workstation, temporarily disable it to see if the workstation will connect. If it connects when the firewall is down, but not when it is active, then you must configure your firewall software to permit UDP and TCP/IP traffic among the addresses used by your local network and open port 2638, which is the port used by the database for communication with the workstations.

· Missing or Invalid PRM File

When you run SOS on a standalone (non-networked) computer, it checks a file called STDALONE.PRM (through SOS 2009) in the main SOS directory for additional startup parameters. On a network server (and standalone for SOS 2010 and later) the file name is SERVER.PRM. As shipped from SOS, this file contains some standard parameters that set default packet size and cache size. If the STDALONE.PRM file (or on a server or SOS 2010 + standalone, SERVER.PRM) is not present, you will see an ODBC window similar to the one pictured above because the database engine could not start and the program could therefore not connect to it.

Check to be sure the appropriate PRM file, is present in the \SOS folder. If it is not, then create it with Notepad or another text editor and include the parameter:
-c 50m
or even just a space. Note that the parameter “-c” must be lower case. If you were to type “-C 50M” instead of “-c 50m”, on starting the program you would see a help screen listing all the valid startup parameters and the database would not start. There is no such parameter as uppercase “-C”, hence the failure.

If the file is present, but contains information that the database does not understand, (such as an uppercase parameter) the database engine will not start and the program, not finding the database, will behave as described.

Correct the information in the PRM file and try again.

· Network Workstation (Client) Displays ODBC Window

First you must determine whether the problem is in network communication or in the ODBC setup.

Assuming that the computers on the network communicate with one another using the standard TCP/IP protocol, you should be able to “ping” the server computer successfully. For example, if the IP address of the database server computer is, open a command window (Start > Run, then type CMD <enter>) and type the following command:

ping <enter>

In the above text, <enter> means press the Enter key on the keyboard.

If communication with the server is intact, you will see something like this:

8-20-2010 5-33-11 PM

If there is a problem with network communication, the ping will not be successful and after a substantial delay, you will see an error message. Contact whoever is responsible for the network and report the situation to him or her.

If the ping is successful, double-check the status of the database server program. It must be running and have successfully loaded the sosdata database. If it has not started successfully, you must troubleshoot that problem first. If you have other workstations, can any of them connect successfully? If not, the problem is probably on the server side.

Very carefully examine the startup messages on the server to be sure that the database actually loaded and started successfully. It is possible for the server software to start but the database to fail. This can happen, for example, if the database has become corrupt or if the database and transaction log do not match. The DB files and the LOG files are a matching set. Having newer DB files or a mismatched LOG file in the directory along with the database files will cause the database to fail. If you think this might be the problem, rename the LOG file and let the database create a new one when it starts.

The server must be using the same network protocol as the workstations. If the server is set to start on the TCP/IP protocol and the the workstations are looking for it on a different protocol, you will never get a connection. Protocols are specified in the command line parameters (usually set in the SERVER.PRM file) on the server, and in the ODBC data source settings on the workstation. The next section of this document contains detailed information about startup settings for both the server and client components.

By default, when you first install SOS on a network workstation, the installation program will configure the “sosdata” ODBC data source to attempt connections on the TCP/IP protocol. If that protocol is not installed on the client, or is installed, but restricted by firewall software installed on the workstation or server, connection will fail. If you have a local firewall such as Norton Internet Security or ZoneAlarm installed, try temporarily disabling it to see if that makes a difference. If it does, then configure it to allow packets to go to and from the SOS programs, the IP addresses involved, and through the ASA port, 2638.

It is essential that the syntax be correct for any entries in the SERVER.PRM file. For example, almost all of these parameters should be specified in lower case (“-X” is not the same as “-x”). An invalid parameter will prevent the database server software from loading.

If you suspect that the parameters may be faulty, open a command prompt window on the server, change to the SOS directory, and type (all on one line):

c:\sos\sa\bin32\dbsrv11 @server.prm c:\sos\data\sosdata.db <enter>

(Substitute the correct directories if those in the example do not match your installation.) If a help window comes up rather than the server starting, there is almost surely a syntax error in your SERVER.PRM file.

To check for an incorrect protocol on the workstation:

1. Click Start > Settings > Control Panel > Administrative Tools > Data Sources (ODBC).

2. Click the System DSN tab.

3. Highlight “sosdata” and click Configure.

4. Click the Network tab.

5. Inspect the protocol options. If the wrong protocol is checked, uncheck the inappropriate options and check the desired protocol. (Note that this protocol must be configured and running on your workstation. You can check that by looking at the Network settings in Control Panel.) Make sure that the TCP/IP protocol is installed and that it is bound to your network adapter.

On some systems, it may be necessary to specify the IP address of the system running the database server as the “host” address in the ODBC configuration next to the protocol, as shown in the figure below. In this case, the database is running on the computer configured with the TCP/IP address

Of course, this is just an example. You must determine and substitute the actual address of the system running the database server software.


Testing the Workstation to Server Connection

Before going any farther, find and delete the file named ASASRV.INI in the workstation’s \SOS\SA\BIN32 folder, if it is present. This file contains information about the most recent successful connection and attempts to use it on subsequent connections. If you have changed the protocol you are using on the network, or the TCP/IP address or port on which the database server is running, the information in this file will be incorrect and can prevent a successful connection. During troubleshooting, it is strongly recommended that this file be deleted after every successful connection so that the information contained therein does not “muddy the waters” while you fine-tune your connection parameters.

To test the ODBC connection, use the Test Connection button on the first tab of the sosdata ODBC configuration. You must input an ID and password on the Login tab first. You can use any ID and password that you have set with the “Grant access from third party programs” option. You cannot use the “SUPER” account for this purpose! If you have not yet configured additional accounts, launch the SOS Log-in directly on the server’s console and use the SUPER account (ID = SUPER and initial password = SUPER) to launch the Admin module and create another user account, configured with the “Grant access from third party programs” option.

Network Server

When you start the database server (Start > Programs > SOS Applications > Start SOSData Server) on a Windows-based server, it checks a file called SERVER.PRM in the main SOS directory for additional startup parameters. As shipped from SOS, this file contains a parameter, -p 1460, which sets the network packet size to 1,460 bytes, the appropriate size for most networks, and another (-c 10m) that sets the starting size for the database’s cache. Check to be sure a file with this name is present. If it is not, then create it with Notepad or another text editor. Include these parameters as well as any others you want (see http://www.sosoft.com/fod/doc204-networkguide.pdf).

If running the database over the TCP/IP, it may be necessary to specify the system’s address in the server.prm file, as in this example:

-x tcpip{MYIP=}

Of course, this is just an example. You must determine and substitute the actual address of the system running the database server software. Specifying the server’s address in this fashion will also eliminate the possibility of the server software trying to start on more than one IP address, which is remotely possible if you have assigned a static IP address to the server but also have a DHCP server running on your network.

Invalid Transaction Log

A corrupt transaction log file (sosdata.log), or a transaction log file that does not match the database, will prevent the database engine (standalone personal server) or server (network) from starting. When an SOS application starts, the first thing it does it attempt to connect to the database. If it cannot access the database, the ODBC configuration window will appear.

Assuming that you have a good backup of the main database files, rename the SOSDATA.LOG file. (SOS recommends that you include the date in the file name, for example: SOS042305.LOG.) You will the log file in the \SOS\DATA directory. It will be set to read-only, so you may have to change the file’s properties using Windows Explorer in order to rename it.

When you restart the database, it should create a new transaction log and load normally.

Do not delete the old transaction log (SOSDATA.LOG) file! Instead, copy it to a CD, label it “Transaction Log” with the date, and store it with your archival backups in a secure, preferably off-site, location. The LOG file serves as a detailed audit trail of database activity and may be required for data recovery or legal purposes.

Standalone Computer

Use of SOS on a standalone computer requires that the ASA personal server (standalone engine) be installed on the same computer as the SOS program and data files. The typical “Standalone” installation from the SOS CD should automatically copy all the required files and properly configure the Windows ODBC Administrator. If the ODBC data source is not configured correctly, SOS will not be able to connect to the database and the program will not run.

Configuring ODBC for Standalone Use

To check the ODBC configuration:

Select Start > Settings > Control Panel > Administrative Tools, then double click the Data Sources (ODBC) icon. When the ODBC Administrator window appears, select the System DSN tab. A window showing currently configured System Data Sources should appear, including a data source with the description “SOSDATA SQL Anywhere 11”.

Make sure the SOSDATA entry is highlighted and select Configure. The fields on each tab should be setup as described below, except that the drive and path references should match the drive and path in which it has been installed on your system. Prompts that do not appear below should be left blank.

Tab Prompt Value
ODBC Data source name SOSDATA
Description SOS Standalone
Isolation level (blank)
Microsoft applications (unchecked)
Delphi applications (unchecked)
Suppress fetch… (unchecked)
Prevent driver… (unchecked)
Delay AutoCommit… (unchecked)
Describe cursor behavior If required
Translator <No Translator>
Login Supply user ID and password (selected)
User ID Optional. After adding users to SOS, may specify an ID that is has option set to “Grant access from third party programs”. Will eliminate need to type ID when using Crystal Reports and other products, but defeats security and therefore could be considered a HIPAA violation.
Password Optional, as above.
Database Server name SOSDATA
Start line (all on one line) c:\SOS\SA\BIN32\dbeng11.exe @c:\sos\stdalone.prm c:\sos\data\sosdata.db
Database name SOSDATA
Database file (blank)
Encryption key (blank)
Start database automatically option checked
Stop database after last disconnect option checked
Network TCP/IP (unchecked)
Shared memory checked
Liveness timeout (dimmed/disabled)
Idle timeout (dimmed/disabled)
Buffer size 7300
Compress network packets Default is unchecked
…method for encryption… None
Advanced Connection name (blank)
Character set (blank)
Allow multiple record fetching checked
Display debugging… (unchecked)
Additional connection parameters (blank)

In this example, additional startup options, such as specifying the initial size of the database cache, are read from the stdalone.prm file located in the c:\sos directory. This is a plain text file that you can edit with Notepad or another text editor. It is strongly recommended that you specify any command line options in this file rather than entering them directly in the ODBC field. If your command line or stdalone.prm file contains any startup options, you might want to remove them to see if the simpler configuration is successful. If it is, then carefully check your options and syntax before putting them back in.

To review options and syntax for the dbeng11 startup command line, go to a system prompt in your \sos\sa\bin32 directory and type dbeng11 /? <enter>

Network Systems

If you are working on a network, program connection problems are often the result of the fact that the database server program has not been started on the server computer or that the workstation has lost its connection to the network.

Are any other stations able to run the program? If everyone has the same problem, then it is surely a problem with the server, its network cable, or the switch or hub to which it is connected.

If the problem is restricted to one workstation, then it is likely to be a workstation issue such as improper network software configuration, a bad cable or interface card, or something of the sort.

Check the server console to be sure that the server is up and that the SOSData database engine is running. You will see a lightning bolt icon in the system tray at the right end of the task bar, unless you are running the database as a background service.

If you are running the database as a background service, bring up Task Manager and check the Processes tab. Make sure the option to display all user processes is checked and look for the dbsrv11 process in the list.

If the database is not running, then start it on Windows servers by selecting the appropriate item on the Start > Programs > SOS Applications menu.

If the SA server is running, then open its status window by double-clicking the icon in the system tray. Scroll up in the window to check for error messages and to be sure that the server is running and the database loaded successfully.

If the SOSData server seems to be loaded, check to be sure that the server computer is running properly. Enter some commands at the server console or return to a workstation and run some other programs that access the server computer’s hard disk to be sure that it responds. If it is hung, follow appropriate shutdown and restart procedures if possible. You should never just shut off or reset a server computer unless there is absolutely no other alternative!

If the SOSData server software appears to be running but none of the workstations can access it, try to verify that all network connections are intact. Can you run other programs from a workstation that access the server’s hard disk?

If the server computer, software, and network are intact, the problem could be an ODBC data source configuration error. Each workstation must have a correctly configured ODBC data source. Correct data source setup is detailed below.

If some stations are able to access the database server, but others are not, or you are just setting up the system for the first time, it could be an ODBC configuration error. In order for the application to establish a connection with the database server, the information in the ODBC configuration must be correct. During installation the setup program attempts to add a correctly configured ODBC entry, but if it failed or was modified after installation, that could be the problem.

You should always start the database from one of the following:

– Start > Programs > Start SOSData Server

– Desktop shortcut that executes the same command as the menu item above

– From a previously configured Windows Service that runs the above command.

Do NOT start the database server by starting an SOS application on the server computer. If you do so, you may find that the database is unloaded when you exit the application on that computer or log off that computer, preventing other workstations from accessing it.

Configuring ODBC for Network Clients

To check the ODBC configuration:

Select Start > Settings > Control Panel > Administrative Tools, then double click “Data Sources (ODBC)”. A window showing currently configured Data Sources should appear. The first tab is User DSN. If you see “sosdata” on this tab, it should be removed. (There are some rare exceptions to this rule, but in no cases should “sosdata” appear on both the User DSN tab and the System DSN tab of the ODBC Administrator.) Select the System DSN tab. You should see a data source with the description “SOSDATA SQL Anywhere 11”.

Highlight the SOSData entry select Configure.

Check each tab and set as described below. Prompts not detailed should be left blank.

Tab Prompt Value
ODBC Data source name SOSDATA
Description SOS Client
Isolation level (blank)
Microsoft applications (unchecked)
Delphi applications (unchecked)
Suppress fetch… (unchecked)
Prevent driver… (unchecked)
Delay AutoCommit… (unchecked)
Describe cursor behavior If required
Translator <No Translator>
Login Supply user ID and password (selected)
User ID Optional. After adding users to SOS, may specify an ID that is has option set to “Grant access from third party programs”. Will eliminate need to type ID when using Crystal Reports and other products, but defeats security and therefore could be considered a HIPAA violation.
Password Optional, as above.
Database Server name SOSDATA
Start line (blank)
Database name SOSDATA
Database file (blank)
Encryption key (blank)
Start database automatically (disabled)
Stop database after last disconnect (unchecked)
Network TCP/IP Checked
Shared memory (unchecked)
Liveness timeout 120
Idle timeout 240
Buffer size 7300
Compress network packets Default is unchecked
…method for encryption… Default is None
Advanced Connection name (blank)
Character set (blank)
Allow multiple record fetching Checked
Display debugging… (unchecked)
Additional connection parameters (blank)

Workstation Loses Connection to Database Server

By default, the server is configured to disconnect any workstation client that has had no activity for four hours. This default client idle timeout period may be modified with the -ti server startup parameter, but client-side idle timeout settings will override the server default (see previous section).

Another process, called liveness timeout can result in disconnects on some systems. Normally, the connection between the client and server is tested every 30 seconds to check to see if the connection is still there. If the test fails four times in a row, the connection will be terminated. The interval can be changed from the default of 120 seconds on the Network tab of the ODBC system data source for SOSDATA on the workstation client. To disable this check altogether, set the liveness timeout to zero.

If the pattern of disconnects is clearly not related to timeouts, you probably have a hardware issue of some sort. In one case a user found a defective CPU fan that apparently was the source of the problem. In another case, there were some environmental, cable, or subtle hardware factors that prevented the network from running reliably with a 100 megabit switch. Replacing the fast switch with a 10 megabit hub solved the problem in that case.

Database Corruption

Using a Security Administrator ID, start the Administration Module, then select Database Tools > DBA Utilities.

Validate Database

When that program comes up, select Tools > Check Database to run the SA DBVALID utilty. DBVALID does a test read of all the data and indices that comprise the database. If any errors are reported, we would suggest that you contact SOS before attempting any correction. It may be necessary to do a database rebuild or we may recommend that you restore your most recent backup and apply the current transaction log. In the event of serious corruption, it may be necessary to send your data to SOS for diagnosis and repair, if possible.

Some of the following utilities are destructive (in the sense that rows in the database may be changed or deleted) so SOS strongly recommends that you do a backup of the database prior to proceeding with any of these steps!

Check Database Integrity

Also on the tools menu in DBAUtils is the selection Check DB Integrity. This utility works through the database, checking for a variety of possible issues. As each step is completed, a check mark will appear next to it. When the last step is done, click the Finish button in the lower right corner of the window.

If any issues were detected, a window will appear listing the issues detected.

Your next step should be to print the summary and detailed reports by clicking the appropriate icons in the toolbar (the printers). If you are sure that you have both a good backup and the reports, click the Repair All icon to attempt automatic fixes of the listed problems. Depending on the problem, this step can take a while.

When the repair is complete, click the scan (magnifying glass) button to repeat the first step to see if any problems remain.

Other Data Repair Utilities

There are several other, more specific, utilities on the Tools menu. It is best to use these with the guidance of an SOS support technician.

Hangs and Lockups

When a program seems to be “locked up” you may see a message that the application is “not responding”, or something to that effect. It is a very common mistake to assume that this message means that the program has stopped functioning. In fact, what this message really means is that the program is not interacting with the user interface (screen, keyboard, and mouse). Sometimes, in fact, this message will appear when a healthy application is just busy working and not locked up at all. The best way to check is to examine the Performance tab of Task Manager. That will show CPU activity. If the CPU is clearly working, you should think long and hard before doing something drastic, such as rebooting the system! The issue is further complicated by the fact that software like SOS sometimes issues a command to the database engine on the server computer and has to wait until that computer has issued a response before it can proceed. That situation will result in the “not responding” condition, but there won’t be any CPU activity in task manager to reassure you that something is happening. You would have to examine CPU activity on the database server to know for sure. There is yet another condition, that should be rare, in which your operation must wait for another user to release a lock on a row or table that you are waiting to update. If everything is working as it should be, this type of user lock scenario should be extremely rare.

That said, there are times when an application can hang. Hangs and lockups can come from a variety of sources. It is essential that you determine whether the problems are seemingly random or reproducible every time you attempt a particular operation in the system.

Reproducible problems

If the system hangs, locks, or crashes every time you try a particular operation, try reinstalling the software, especially if you are on a network system and the problem seems to be unique to your workstation. Make sure that the version you install is the same as that running on the other stations. If that does not seem to make a difference, there may be a programming, configuration, or installation issue that needs to be addressed. Document the problem carefully, including any error messages that appear, and contact SOS tech support.

Random lockups

Seemingly random lockups are often the result of conflicts among the programs that you are running. Check the programs that you are automatically loading when your system starts and eliminate any that are not really essential. Contact your consultant or another computer-savvy individual for assistance with this task.

It is essential that you have ample free space on your hard disk, especially the system drive, if you have more than one disk in your computer. Many programs, including SOS applications, create temporary files that can be quite large. If there is not enough space to store these files, frequent system crashes are inevitable. Check your disk space on your system drive.

Random hangs are sometimes the result of faulty RAM modules. Swap or replace the RAM modules in your system to see if that makes any difference.

A common cause of computer malfunction is heat. If your system acts up after it has been on for a while, the fan or fans in the system may not be turning, or you may have a good deal of dust in the system. If your system has a metal case, do a quick check by just touching the case. It should be cool to the touch. If it is warm or hot, you will have to open it up, blow out the dust with a can of compressed air (best done outside!), and switch it back on with the case off to see if all the fans are turning, including the one on the CPU chip/heat sink.

Even if the case is cool, the CPU fan may not be functioning, so you should check it to be sure it is ok if your system is exhibiting strange behavior.

Other Issues

Check the SOS web site Document Library at http://www.sosoft.com/html/document_library.php to see if there is a document that addresses your issue.

Another good resource is the SOS User Group at Google Groups: http://groups.google.com/group/sosoft. You can search all the messages to see if there has been any discussion of the problem you have encountered.

Those who have a current support contract with SOS are welcome to contact us directly by phone (352-242-9100), fax (352-242-9104, or email (support@sosoft.com) with any questions.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

This site uses Akismet to reduce spam. Learn how your comment data is processed.