This document outlines the process used to configure the PRO/5 TCP/IP client or the BASIS ODBC Driver to access files through the PRO/5 Data Server.

1. Install the products according to their instructions.

2. Modify the services file to include an entry for the Data Server. This entry is the service name, and the following defaults are recommended:

     pro5srv   1100/tcp   # PRO/5 Data Server
   

   The services file will need to be modified for the machine on which the Data Server is running as well as every workstation on which the client or ODBC Driver is running. If the Data Server is installed on a UNIX machine, the services file can be found in the /etc/ directory. The following shows typical locations for the services file.

   Operating System	Services File Location
   UNIX	/etc/services
   Windows 95	\windows\services
   Windows NT	%SystemRoot%\system32\drivers\etc\services

   Note: %SystemRoot% is the drive and root directory where NT was loaded.

3. Start the Data Server with logging enabled. This example will invoke the Data Server, force it to use port 1100, and log all activity to the file named ds.log in the Data Server's directory. Note that it is not necessary to specify the port, but it can be helpful for testing purposes to rule out problems with the services file mentioned in Step 2.
   

   • UNIX Data Server

       ./pro5.server -r -l./ds.log -p1100
     

   • NT Data Server Revision 2.03 and lower:

       c:\BASIS\NTDS\pro5srv.exe -r -l./ds.log -p1100
     

   • NT Data Server Revision 2.04 and higher:

     The PRO/5 Data Server for Windows NT Revision 2.04 and higher doesn't log events into a specific log file you create. Instead, when logging is enabled, the Administrative Tool Event Viewer logs all events for the Data Server. Any event that causes an error contains complete text about the error along with a time/date stamp in the Application Event Viewer.

     The PRO/5 Data Server for Windows NT Revision 2.04 and higher is designed as a Windows NT Service. To accommodate the differences, the required steps to set up and start the Data Server with logging enabled are:
     

     1. From the Windows Start menu, open the Control Panel.
     2. Execute the PRO/5 Data Server applet. (This applet sets the parameters contained on the command line in previous releases.)
     3. Select the checkbox next to Enable Event Logging.
     4. Click on the Apply button to accept changes.
     5. Close the window and return to the Control Panel.
     6. Open the Services window, highlight the PRO/5 Data Server in the list and click Start. Note that the Startup Parameters line in the Services window does not have any effect on the PRO/5 Data Server.

4. From the Windows workstation, ensure that the TCP/IP stack is installed and configured correctly. Over 75 percent of all problems accessing the Data Server are due to problems in this area. The steps outlined below are necessary to ensure that the system is configured properly. Also, the Data Server has more stringent TCP/IP configuration requirements than simpler programs such as Telnet. Therefore, if a Telnet via TCP/IP is working correctly, it does not necessarily indicate that the TCP/IP is configured correctly. To verify that everything is set up correctly, check the following:
   
   
   1. Can you ping the host on which the Data Server is running? You should be able to ping the host, specifying only the server's name (this can be obtained executing the hostname command on the UNIX machine). In other words, to ping a machine named 'server', you should be able to run

        ping server
      

      from a DOS prompt. If this is successful, the ping will indicate that the data is being transferred. Also, it is very important that the ping results resolve the server's IP address and domain (if applicable).

        pinging server.mycompany.com [255.255.255.255] with 32 bytes of data...
      

      If the server's IP address is not resolved properly, check either:

      
      
      1. The DNS setup, if you are using a Domain Name Server to provide IP lookups. Note that the DNS should be configured to do lookups and reverse lookups. This means that it will be able to resolve a machine's IP address if given its hostname, and it should also be able to resolve a machine's hostname if given its IP address.

      2. The local hosts file, usually called hosts and residing in your Windows directory. The TCP/IP stack that comes with Windows 95 includes a sample hosts file named hosts.sam located in the windows directory. To use this file, add the remote server's name and IP address to the file with a text editor. It already has some sample definitions to use as a template. Once you've added your server, rename the file to hosts.

   2. Can you ping the workstation from the UNIX host? If not, check the /etc/hosts file or DNS server configuration to verify that the workstation is listed with a valid IP address. Note that the ping indicates both the workstation's IP address and hostname.

   3. You should also be able to do an nslookup on the workstation from the UNIX machine if you are using DNS:

            
        nslookup my_workstation
      

      Sample result:

        Name: my_workstation.basis.com Address: 255.255.255.255
      

      This should resolve the workstation's domain (if applicable) and IP address.

5. For the ODBC Driver, you must set up a data source in the Windows ODBC Administrator tool, located in the Control Panel. When configuring the data source, include a Data Source Name and the location of the config.tpm file. The Data Source Name is an alias that will be used to refer to your data source. The name should be short and descriptive, and an optional Description field is available for extended comments. The most import aspect of the configuration is the 'Database Configuration' field. This points to the config.tpm file that is used to point to the Data and Data Dictionary. The config.tpm file may either be local, such as:

     c:\basis\project\config.tpm
   

   or remote. A remote config.tpm is located on the Server and is accessed through the Data Server, such as:

     /<server_name,port=1100>/usr/bbx/project/config.tpm
   

   This config.tpm file must have a DATA and DICTIONARY entry that points to the appropriate directory and specifies the Data Server. A sample config.tpm file is:

     DICTIONARY=/<server_name,port=1100>/usr/bbx/project/BBDICT/
     DATA=/<server_name,port=1100>/usr/bbx/project/data/
   

   Note that the server's hostname must be used instead of its IP address. If the IP address is specified instead as in:

     DICTIONARY=/<200.100.10.5,port=1100>/usr/bbx/project/BBDICT/
     DATA=/<200.100.10.5,port=1100>/usr/bbx/project/data/
   

   the ODBC driver will not be able to read the Data and Data Dictionary. If the config.tpm file resides on the server, it will not have references to the Data Server. An example is:

     DICTIONARY=/usr/bbx/project/BBDICT/
     DATA=/usr/bbx/project/data/
   

   Note that there are no spaces allowed on a line, DATA and DICTIONARY are in uppercase, and the port has been specified for testing purposes.

6. If the Data Server is running on UNIX, set the user id for the client or ODBC Driver. The specified login is used to by the client or ODBC driver to attach to the server so that it can communicate with the Data Server that is running on that machine. Note that the login should never be 'root' because anyone logged in as root cannot access the Data Server.

   If the Data Server is running on Windows NT, skip to Step 7.

   
   
   1. For the TCP/IP client, set the user id with either an environment variable called USERID or by using the -u command line parameter.

   2. For the ODBC driver, set the user id with the following steps:
      1. Bring up the Windows ODBC Administrator located in the Control Panel.
      2. Select your data source from the list, and click on the Configure or Setup button.
      3. Click the Advanced button.
      4. Fill in the Network User ID box with the appropriate login name.

7. Ensure that the user id will have adequate permissions when logging in from the workstation. This is done with one of the following methods:
   
   
   1. On UNIX, a .rhosts file must be modified to include the workstation. The .rhosts file is located in the user's home directory. An entry should be added that will include the name of the remote workstation, signifying that the user has permission to login to the UNIX machine from the remote workstation. The name of the machine can be acquired by printing out the current host name ( >print info(3,4) ) from the TCP/IP client, or it can be retrieved with the Network portion of Control Panel. Also, adding a + after this entry can also help with error 70s if the Data Server was started by a user other than root. Finally, the permissions on the .rhosts file should be 644.

      The following is a sample .rhosts file:

        workstation1.yourdomain.com
        workstation2.yourdomain.com
        my_workstation.yourdomain.com +
      

   2. Under UNIX you can also create an entry in the hosts.equiv to signify that the user has permission to login to the UNIX machine from the workstation. Also, adding a + after this entry can sometimes help solve error 70s.

8. At this point, you should be able to test the TCP/IP client or ODBC Driver.
   
   
   1. For the TCP/IP client, verify that you have enabled Network Access with the options vector. Here's how:

        >LET A$=OPTS
        >IF AND(A$(4,1),$20$)=$20$ THEN PRINT "enabled" ELSE PRINT "disabled"
      

      This bit must be set to access the Data Server. Here's how:

        >LET A$=OPTS
        >LET A$(4,1)=IOR(A$(4,1),$20$)
        >SETOPTS A$
      

      If the bit does not remain set, you are not running the TCP/IP client version of BBx or PRO/5.

   2. Next, try to open a file through the Data Server by running the following:

        >OPEN(1) "/<server_name,port=1100>/etc/services"
      

      This is a good example for two reasons:

      1. The services file should be there and be readable.
      2. The port=1100 forces the port selection.

      If problems occur, see Diagnosing Problems. If it does work, try the same thing but do not specify the port:

        >OPEN(1) "/<server>/etc/services"
      

      If this works, you're in business! If it does not, but it worked when you specified the port, there is a problem with the Data Server entry in the services file (Step 2). Check for typos!

   3. For the ODBC Driver, attempt to access the data through the Data Server with a third-party tool such as Microsoft Query or Access.

Problems Opening A File From The TCP/IP Client

• An !ERROR=12 indicates that the client was not able to contact the Data Server. This usually means that the network setup is not correct on the workstation. Possible causes:
  
  • Not having the Network Access setopts bit set for the client.
  • Not having a valid method of resolving IP addresses for hosts.
  • Not specifying a domain.
  • The Data Server is not running. On UNIX, this can be verified by executing a 'ps' command such as:

    ps -ef | grep pro5.server
  

  • Network problems such as a bad cable or lost connection.

  • The current working directory is being dsksyn'd in the config.bbx file being used by the VPRO5 client. If this statement returns an error 17. check the config.bbx file. Verify that the drive being referenced in Start In for the VPRO5 shortcut does not have a dsksyn in the config.bbx file:

     print dir("")
    

• An !ERROR=70, 71, or 72 means that there was a network problem when the workstation attempted to communicate with the Data Server. Check the Data Server's log file, which will indicate the exact failure. Some common problems are:
  • ruserok failure: This means that the workstation did not have adequate permissions to talk to the Data Server. To fix this, check the .rhosts file or hosts.equiv as mentioned in Step 7.
  • The server was accessed by its IP address instead of its hostname. The proper syntax for the Data Server references its hostname as in the following example:

      >open(1)"/<server>."
    

  • The following example is incorrect and will result in a !ERROR=72:

      >open(1)"/<200.100.10.05>."
    

  • get hostname by addr failed: This means that there is a problem with the DNS, the workstation's local hosts file, or the UNIX hosts file. Ensure that these are correct, and that a ping will correctly resolve a machine's IP address. If this occurs, the Data Server's log file will have an entry similar to:

      Jul 11 16:15:06: connect error, gethostbyaddr failed errno: 0, _errno: 2
    

• An !ERROR=8 usually indicates that the Data Server and client revision levels do not match.

• An !ERROR=18 usually indicates a permissions problem. This is accompanied by an error message in the Data Server's log file similar to:

    ruserok failure, host: hostname user: localuser: username
  

• A TCB(10) = -10061 from the Visual PRO/5 client indicates a Winsock 'Connection Refused Error'. If the Data Server is running on a UNIX machine, this error is most likely due to a ruserok failure. If so, the Data Server's log file will register the ruserok failure. To fix this, check the .rhosts file or hosts.equiv as mentioned in Step 7.

  This error can also occur if you attempt to open a file with the Data Server and specify the wrong port. For example,

     
    >open(1)"/<kazoo,port=8888>."
  

  will result in this error if the Data Server is not running on port 8888.

• If an error such as:

    Unable to open dictionary 'datasource name'
    Dictionary element does not exist.
    Cannot open base dictionary file 
    /<server_name,port=1100>/user/bbx/BBDICT/FILE1.1
    busy/timeout.
  

  is reported, this usually means that the Data Server is not running or is not using the specified port.

• fserr=5, fserrs=-21. Possible Causes:
  
  
  • This error can occur when there are spaces in the config.tpm file before the =. For example:

      DICTIONARY=/<server_name,port=1100>/usr/bbx/BBDICT/
      DATA=/<server_name,port=1100>/usr/bbx/data/
    

  • This error can occur when the Data Dictionary definition in _ddedit.utl has the path to the Data files hard coded instead of using the (DATA) global.
  • This error can occur when DICTIONARY and DATA are not all uppercase; for example, Dictionary=, and/or Data= even if there are no spaces in the definition lines.
  • This error can occur when the Network User ID field (in the advanced section of the Data Source Setup in the ODBC Administrator) is blank, and the ODBC Drive attempts to contact the Data Server.

• fserr=61 fserrs=-161. This error can occur when there are spaces in the config.tpm file after the =. For example:

    DICTIONARY=/<server_name,port=1100>/usr/bbx/BBDICT/
    DATA=/<server_name,port=1100>/usr/bbx/data/
  

  It can also occur if the Network User ID field in the data source configuration section of the Windows ODBC Administrator is blank or incorrect.

• fserr=3, fserrs=3 or fserr=17, fserrs=17. These can occur when multiple applications or sessions are trying to connect to the same data source from the same workstation.

• If a "Duplicate or missing file" is reported from the Windows application, and the data server log file reports an "error getting packet size," then it is likely that a data dictionary file is corrupt. If the data server log does not report any problems, ensure that all dictionary files in the BBDICT (or equivalent) directory are in uppercase, with the exception of the .dat extension, which is in lower case for the DD_* files.

• If using the BASIS ODBC Driver 1.x, the following error may occur. If an error such as

    [BASIS] [BASIS ODBC Driver] No such table in catalogSQLGetTypeInfo,
    Critical Signal: No such table in catalog
  

  is reported, it usually means that the data dictionary is damaged or incorrect. To test, use _ddedit.utl. But first, force the ODBC driver to recreate the shadow data dictionary by turning off the appropriate checkbox in the advanced section of the setup from the ODBC administrator, and then physically removing the old shadow data dictionary by removing the *.dat files in the BBDICT directory.

• If an fserr=13, fserrs=13 is experienced when attempting to open a table (after successfully connecting), ensure that the case of the data files in the DATA (or equivalent) directory matches what is defined in the data dictionary. Usually, along with the fserr=13, the Windows application will report through the ODBC Driver which file it was unable to open, and it will show the case of the expected file. For example, when trying to open a table named CUSTOMER when the actual data file is named customer, MS Query reports:

    [BASIS ODBC Driver]
    Unable to open /<server_name,port=1100>/usr/bbx/project/data/CUSTOMER,
     err=duplicate or missing file, fserr=13, fserrs=13
  

  Note that the file expected is uppercase. Ensure case sensitivity is observed with UNIX.

• If an "fserr=70" is issued, there may be a license conflict. Check the Data Server log to confirm it.

• An "fserr=71" usually indicates that the user's hostname is not defined in the .rhosts file on the Data Server side.

• An entry in the Data Server log file such as:

    Jul 11 16:15:06: connect error, gethostbyaddr failed errno: 0, h_errno: 2
  

  indicates that the UNIX or NT server cannot resolve the PC's hostname from its IP address.

• If you kill and then immediately restart the Data Server under UNIX, it is possible to get an error message saying 'error binding stream socket'. This is because the operating system has not cleaned up after the original Data Server process killed with the 9 option. The stream socket in question is the one with which the original Data Server process was invoked, usually port 1100. This parameter is either supplied at startup (through the -p command line parameter), or the default is taken from the services file from the PRO/5 data server entry.

  There are two methods to resolve this. The first involves waiting for the operating system to clean up and recycle the socket. This can range from a few seconds to several minutes. We are not aware of a way to force this. The second method involves starting the Data Server on a new socket. Do this by using the -p parameter with an unused socket. For example, if the original Data Server was running on port 1100, try 1101 instead, if it is not already used. Remember to change the configuration files to reference the new port.

• Ensure that any reference to a remote system (including the OPEN or config.tpm) references a host name and NOT an IP address.

• ODBC log files. There are two log file types that can be generated to assist in diagnosing ODBC related problems. They are:
  • BASIS ODBC log file: This file is not useful for diagnosing/tracking specific SQL commands. It can, however, be used for diagnosing data dictionary problems or SQL optimization strategy issues. This can be specified in the Advanced Setup options for a [BASIS ODBC Driver] data source in the ODBC Administrator.

  • SQL log file: This will monitor all SQL function calls that occur and is specified in the ODBC Administrator under Options.