BUSINESS SOFTWARE, INC. (BSI) CONFIDENTIAL AND PROPRIETARY INFORMATION

Step 3. -- Connect to the Database/Dataset

Call the following APIs from your payroll system. They should be called only once per session.

C Instructions:

/*
** Connecting to the database
*/

BSI_CHAR str[256] = "";

if (!ConnectToDataSource(str, NULL))
fprintf(stderr, "Connect to data source error: %s.\n", str);

When you run the system for the first time, the above API displays a dialog box with a list of configured data sources. Select the data source you have configured for use with TaxFactory in the above step. Once you have successfully connected to the database, TaxFactory stores the login information in the system. This API uses this information for logging onto the data source. To change or connect to a different data source from the interface, use the Connect to Data Source option from the main interface. The CONNECTTODATASOURCE function will automatically connect to the data set defined the registry entry.

Note 1: For Windows ODBC, users can specify the database connection string in several ways. The following list details the ways users can specify the database connection string, in order of importance:

On the ConnectToDataSource API call, specify the connect string. This string is found by first connecting from the GUI to the database of interest, then looking in the registry (under key Software\BSI\TF90\Connection) and copying the DSN string found there. This DSN string needs to be edited. The registry entry contains an encrypted UID (Login) and PWD (Password). Substitute the unencrypted values into the DSN string. If the DSN string is unresolvable by the API, the Select Data Source window will prompt the user. For example:
ConnectToDataSource("DSN=MyDataSource;UID=MyLogin;PWD=MyPassword;OtherStuff;", NULL);
The first non-blank environment variable from the list below. Use the same DSN syntax (the registry value, with unencrypted UID and PWD) as explained above. If the first non-blank variable contains PROMPT (or any unresolvable DSN string), the Select Data Source window will prompt the user.

TF90_CONNECT_STRING
TF90_DATABASE
TF_CONNECT_STRING
TF_DATABASE
DATABASE

Example: setTF90_CONNECT_STRING=DSN=MyDataSource;UID=MyLogin;PWD=MyPassword;OtherStuff;
The DSN system registry entry indicating the last successful connection string. This entry will be used when a blank string is used in the ConnectToDataSource API call and no environment variables are defined.

Example: ConnectToDataSource(ErrorMessage, NULL);
If there is no DSN system registry entry, the Select Data Source window will prompt the user to choose a data source.

If the connection string is specified from the API call or taken from an environment variable, it will NOT be used to update the system registry.

Note 2: If you use multiple sets of TaxFactory server exes (residing in different folders but on the same Windows machine), you can connect each set to a different database by using a different startup script (DOS batch file) for each set. In this script, first set one of the following environment variables to identify the connect string:

TF90_CONNECT_STRING
TF90_DATABASE
TF_CONNECT_STRING
TF_DATABASE
DATABASE

The value that you set this variable to will be taken from the TF90 Connection registry entry, using the text from the DSN variable. The script will launch the TF.exe.

/*
** Connecting to the dataset
*/

BSI_CHAR str[256] = "";
TF9_SESSION Session;

strcpy(str, "MyDataSet");
if (!ConnectToDataSet(str, "TF90", "bsi", &Session, NULL))
fprintf(stderr, "Connect to data set error: %s.\n", str);

Note 3: For Windows ODBC, users can specify the dataset connection string in several ways. The following list details the ways users can specify the database connection string, in order of importance:

On the ConnectToDataSet API call, specify the dataset string.

Example:
ConnectToDataSet("DEFAULT", "MyLogin", "MyPassword", &MySession, NULL);
The first non-blank environment variable from the list below. If the first non-blank variable contains an unresolvable dataset string, the ConnectToDataSet API call will fail.

TF90_DATASET
DATASET
The Data Set system registry entry indicating the last successful dataset string (under key Software\BSI\TF90\Data Set Section). This entry will be used when a blank string is used in the ConnectToDataSet API call and no environment variables are defined.

Example:
ConnectToDataSet(ErrorMessage, "MyLogin", "MyPassword", &MySession, NULL);

If the dataset string is specified from the API call or taken from an environment variable, it will NOT be used to update the system registry.

COBOL Instructions:

COPY TF9API.
.
.
.
MOVE "<DB2 CONNECTION STRING>" TO ERROR-MESSAGE.
CALL "CONNECTTODATASOURCE" USING
    BY REFERENCE ERROR-MESSAGE
    BY REFERENCE RTN-CODE
    BY REFERENCE RTN-STATUS.

IF RTN-STATUS NOT = 1
    DISPLAY "ERROR ON CONNECT TO A DATABASE:" ERROR-MESSAGE.
STOP RUN.

COPY TF9API.
.
.
.
MOVE "MYDATASET" TO ERROR-MESSAGE.
CALL "CONNECTTODATASET" USING
    BY REFERENCE ERROR-MESSAGE
    BY REFERENCE TF90-LOGIN-USERID
    BY REFERENCE TF90-LOGIN-PASSWD
    BY REFERENCE TF10-SESSION-ID
    BY REFERENCE RTN-CODE
    BY REFERENCE RTN-STATUS.

IF RTN-STATUS NOT = 1
    DISPLAY "ERROR ON CONNECT TO A DATASET:" ERROR-MESSAGE.
STOP RUN.

C# Instructions:

/* Connecting to the database*/
TF90API api = new TF90API();
String err = String.Empty;

err = null;
if (api.connectToDataSource(ref err) <= 0)
{
System.Console.WriteLine(String.Format("Unable to connect to database {0}\n", err));
return;
}

/* Connecting to the data set */
TF90API api = new TF90API();
String err = String.Empty;

err = "DEFAULT"
if (api.connectToDataSet(err, "TF90", "bsi") <= 0)
{
System.Console.WriteLine(String.Format("Unable to connect to data set {0}\n", err));
}

At this point you can call any other BSI-APIs.