A single guide covering OLE DB → ODBC conversion, driver configuration and driver-version upgrades

Contents

Click any entry to jump to that section.

1.  Background — why ODBC replaced OLE DB

2.  Do you need to convert?

3.  Which ODBC driver version you need

4.  Prerequisites

5.  Before you start

5.1  Set RPT_DISABLE_CONV_TO_ODBC to N

5.2  Set the Web.config key for existing reports

5.3  Make sure all reports are checked in

5.4  Back up (export) all Crystal Reports

6.  Converting existing reports

6.1  Convert a single report and test

6.2  Convert all reports

6.3  Which menu option applies to your version

6.4  Bulk conversion outside Designer

6.5  Roll out to the other environments

7.  Creating a new report on an ODBC connection

8.  Verify it worked

9.  Upload and printing errors on TP 11.7 and higher (MS SQL only)

9.1  The symptom

9.2  If you are NOT using TLS 1.2 — set the setting to Y

9.3  If you ARE using TLS 1.2 — install the driver and convert

9.4  Report Printing Service

10.  Troubleshooting

11.  Quick reference

A note on Designer access: Almost every procedure in this guide starts in the STARLIMS XFD Designer, which you reach through the IE browser, the Native App, or the Designer application in an HTML system (if configured). To avoid repeating that, the steps below simply say “go to STARLIMS XFD Designer”.

1.  Background — why ODBC replaced OLE DB

Prior to Technology Platform (TP) 11.6, STARLIMS Crystal Reports connected to the database using Microsoft OLE DB Providers (SQLOLEDB for SQL Server and OraOLEDB.Oracle for Oracle). From 11.6 onward STARLIMS uses ODBC connections — ODBC (RDO) — primarily to ensure compatibility with TLS 1.2 and above.

Why this matters: In March 2021 RFC 8996 formally deprecated TLS 1.0 and 1.1, and in August 2023 Microsoft announced it would disable them in Windows by default. Reports still using an OLE DB provider will eventually fail to connect.

This guide covers the three related tasks together: converting legacy OLE DB reports to ODBC, configuring the ODBC connection for newly created reports, and moving reports from one ODBC driver version to another (for example ODBC 13 to 17 to 18) as the platform advances. The procedure is essentially the same in all three cases, which is why they are presented as one workflow.

Good news: It is safe to convert reports to ODBC more than once. It is easier to convert everything and then test than to inspect every single report in every language.

2.  Do you need to convert?

The connection information lives inside the uploaded .rpt Crystal Reports file, so you have to download a report from STARLIMS and inspect it in Crystal Reports Designer. The Conditions report from Base Static Tables | Conditions is a good sample:

1.    Go to STARLIMS XFD Designer.

2.    Navigate to Reports > Crystal Reports > BaseStaticTables > Condition.

3.    Right-click the report, select Download, and choose ENG.

4.    Save the template locally and open it in Crystal Reports.

5.    Go to Database > Set Datasource Location > expand report > 'database server' > Properties.

6.    Read the Database Type.

Figure 1 — Set Datasource Location > Properties on an unconverted report — Database Type: OLE DB (ADO) and Provider: SQLOLEDB. A report in this state will not work with TLS 1.2.

3.  Which ODBC driver version you need

The correct ODBC driver version depends on your Technology Platform version. Confirm the pairing for your TP version before converting anything.

Recent STARLIMS installers and upgraders install the correct ODBC version automatically. ODBC v18 and v17 are available from Microsoft. ODBC v13 is no longer distributed by Microsoft; if it is required, obtain the msodbcsql.msi installer from STARLIMS Support. The Microsoft download link for the driver is:

https://go.microsoft.com/fwlink/?linkid=2121020

Driver version in connection strings: Wherever this guide shows ODBC Driver 13 for SQL Server, substitute the version that matches your TP version — for example ODBC Driver 17 for SQL Server or ODBC Driver 18 for SQL Server.

4.  Prerequisites

• Administrator access to the STARLIMS database, application and batch servers.
• The correct ODBC driver installed on the application server(s) and on every BATCH server (see Section 3).
• Access to the server(s) running Starlims.Server.WorkerProcess.exe, if you intend to convert outside Designer.
• The ability to recycle the STARLIMS application pool.
• Designer access, or direct access to the STARLIMS DICTIONARY database, to check RPT_DISABLE_CONV_TO_ODBC.

Do not forget the BATCH servers: Reports will not run correctly on a BATCH server that is still using a mismatched ODBC version, even if the conversion succeeded everywhere else.

Cloud customers: the Enterprise Setting in Section 5.1 is already correct, and the drivers are managed for you.

5.  Before you start

5.1  Set RPT_DISABLE_CONV_TO_ODBC to N

The Enterprise Setting RPT_DISABLE_CONV_TO_ODBC may be set to Y. That blocks conversion to ODBC on upload to STARLIMS and disables the option to (bulk) convert reports. It has to be set to N. Use either method below.

One exception: If you are an MS SQL customer who does not use TLS 1.2 between the application and database servers, and you are hitting the upload error described in Section 9, the correct value is Y — not N. Read Section 9 before changing this setting.

Option A — through STARLIMS Designer

1.    Go to STARLIMS XFD Designer.

2.    Navigate to Application > Enterprise_Support > Enterprise_Settings > XFD Forms and open the form Edit_Settings.

3.    Run the form.

4.    Locate RPT_DISABLE_CONV_TO_ODBC (under the System category) and set its value to N.

5.    Close the form, close the Designer, then close the Native App / IE browser.

Option B — through the STARLIMS DICTIONARY database

Run the following against the DICTIONARY database using SQL Server Management Studio or a similar tool:

select VALUE from LIMSENTERPRISESETTINGS

where SETTINGNAME = 'RPT_DISABLE_CONV_TO_ODBC'

update LIMSENTERPRISESETTINGS set VALUE = 'N'

where SETTINGNAME = 'RPT_DISABLE_CONV_TO_ODBC' and VALUE = 'Y'

Mandatory after any change to this setting: Recycle the STARLIMS Application Pool. The change does not take effect until you do, and recycling does not affect active sessions.

5.2  Set the Web.config key for existing reports

In the Web.config of the application server, make sure the following key is present:

<add key="Reporting_EnableSetLocation" value="true" />

5.3  Make sure all reports are checked in

A report that is checked out cannot be converted — the conversion option is greyed out. For a single report, check the status through Source Control:

Figure 2 — Right-click the report > Source Control. No usernames should appear behind the languages; here ENG is checked out by user JSI. Note that Convert to ODBC connection is greyed out while the report is checked out.

Before a bulk conversion, check every user at once:

1.    At the bottom of the Designer screen, go to Pending Checkins.

2.    Click All Users and hit Refresh.

3.    Confirm that no user has Crystal Reports checked out.

Figure 3 — Pending Checkins with All Users selected. Here the Conditions report under Reports > Crystal Reports > BaseStaticTables is still checked out by user JSI and must be checked in first.

5.4  Back up (export) all Crystal Reports

Take a personal backup before you convert anything. Do this once, not per report.

1.    Go to STARLIMS XFD Designer.

2.    Navigate to Tools > Enterprise > Export Package and click Next.

3.    Pick English and all other languages in active use on the system, then click Next.

4.    Click Reports, tick All Layers at the bottom, tick the checkbox before Crystal Reports, click OK, then click Next.

5.    Name the package — for example PROD_AllCrystalReports_Backup_20260709 — and click Start export.

6.    Click Next, tick Download on client, and click Next.

7.    Save locally, then click Next and Finish.

6.  Converting existing reports

The same procedure applies whether you are converting from an OLE DB provider to ODBC or moving already-converted reports to a newer ODBC driver version. Start with one report, then do the rest.

6.1  Convert a single report and test

1.    Go to STARLIMS XFD Designer.

2.    Navigate to Reports > Crystal Reports > BaseStaticTables > Condition.

3.    Confirm the report is checked in (Section 5.3).

4.    Right-click the report and select Convert to ODBC connection.

5.    Right-click again and choose Preview > ENG to verify the report.

Figure 4 — Right-click menu on a single report (Conditions) with Convert to ODBC connection selected.

Reading the result: The report may open with only headers and no rows, because no Condition data is registered in your system. If it opens at all, the conversion succeeded. You can equally test a different report.

Missing parameters: Some reports require parameters to run, and STARLIMS cannot infer this. Add the parameters manually and review the converted report through the application.

If you hit an error: Stop here. Create a support ticket and share the error message and the problem found, rather than converting the rest.

6.2  Convert all reports

1.    Go to STARLIMS XFD Designer.

2.    Confirm no user has Crystal Reports checked out (Section 5.3).

3.    Navigate to Reports > Crystal Reports.

4.    Right-click and select Convert to ODBC connection. You can also do this on a single category instead of the root.

5.    Watch the log at the bottom of the Designer for progress.

6.    Test several reports from the Main Menu, and verify that all custom daily reports still work.

Figure 5 — Right-click the Crystal Reports root node to convert every report at once.

6.3  Which menu option applies to your version

The name of the right-click option differs between platform versions. On TP 11.6 it is Add Multi-Subnet Failover Support; from TP 11.7 onward it is Convert to ODBC connection.

Figure 6 — TP 11.6 — right-click the report in Reports Manager and choose Add Multi-Subnet Failover Support.

Figure 7 — TP 11.7 and higher — the same menu offers Convert to ODBC connection, shown greyed out here.

If the option is greyed out: It is sometimes said that this means the report has already been converted. That is under investigation and is most likely not true. The option is disabled when RPT_DISABLE_CONV_TO_ODBC is set to true and STARLIMS has no knowledge of the database connection used in the Crystal Reports template — or when the report is checked out. Check Section 5.1 and Section 5.3 first.

6.4  Bulk conversion outside Designer

Reports can also be converted to the target ODBC version without opening Designer, by invoking Starlims.Server.WorkerProcess.exe from the command line with the appropriate arguments. This allows bulk or scripted conversion. Underneath, both routes call the same server-side provider.

Figure 8 — The mechanism behind the conversion — server script Enterprise_Data_Providers.ReportCategProvider, whose Convert procedure submits ConvertAll to batch when categoryID is “All”, and _ConvertCategory for a single category.

6.5  Roll out to the other environments

Once the conversion has completed successfully on DEV (or TEST), move on to the other environments. There are two ways to do it:

• Repeat Sections 6.1 and 6.2 on each environment in turn.
• Or, if all PRODUCTION reports also exist in DEV: convert everything in DEV, export the converted reports, then import them into TEST and PRODUCTION. This avoids running the conversion separately in each environment.

If you export and import: Take the export after the conversion has finished in DEV — otherwise the imported reports still reference the old connection or driver version.

7.  Creating a new report on an ODBC connection

New reports must be built on an ODBC (RDO) connection rather than an OLE DB one.

1.    Create a new report. In the Standard Report Creation Wizard, expand ODBC (RDO) under Available Data Sources.

Figure 9 — Standard Report Creation Wizard — select ODBC (RDO), not OLE DB (ADO).

2.    On the next screen, pick Enter Connection String.

Figure 10 — ODBC (RDO) Data Source Selection — choose Enter Connection String rather than Select Data Source or Find File DSN.

3.    Enter the connection string, substituting your own server name and database name:

Driver={ODBC Driver 13 for SQL Server};

Server=<DB server name>;

Database=<STARLIMS Data database name>;

A fuller variant adds the multi-subnet and trusted-connection options (server and database names shown are examples):

Driver={ODBC Driver 13 for SQL Server};

Server=STLUHWL6YPNZM;

Database=STARLIMS_DATA_QM11_1;

MultiSubnetFailover=No;

Trusted_Connection=yes

If you convert on the server instead: You do not need the full connection string. Converting a report server-side only requires the server name, database name, user name and password.

4.    Click Next. On the Connection Information screen, provide the server name again together with the User ID and Password used to connect to the database server.

Figure 11 — ODBC (RDO) Connection Information — Server, User ID and Password.

5.    Pick the tables you will use in your report.

Figure 12 — Standard Report Creation Wizard — expand the database, dbo and Tables, then move the required tables into Selected Tables.

8.  Verify it worked

• Reports run successfully against the new ODBC driver in every environment.
• The application pool has been recycled after any change to RPT_DISABLE_CONV_TO_ODBC.
• BATCH servers run scheduled and triggered reports without ODBC-related errors.
• Custom daily reports and any reports that take parameters have been opened and checked through the application.

9.  Upload and printing errors on TP 11.7 and higher (MS SQL only)

Scope: This section applies only to customers using Microsoft SQL Server. It covers the specific failure seen when an OLE DB report is uploaded to, or printed from, a system running TP 11.7 or higher.

9.1  The symptom

Uploading the report to a system running 11.7 or higher (which uses the Microsoft OLE DB Provider for SQL Server driver) produces a server error:

---------------Server Error---------------

Exception of type: StarlimsServerException

Description: Error Converting Report(s): Unable to convert report.

Failed to open the connection.

Failed to open the connection.

7b845b2f-9e91-4c35-9d04-891d86be2248.tmp

{08D56BA1-D0A4-43AD-80B5-89786FE8D8DC}.rpt

Execution Stack:

  ServerScript.Enterprise_Data_Providers.ReportProvider.add() : line: 162

----------End Server Error----------

Other users may not see an error at all — the report simply does not work and shows a blank page.

What the error actually means: The system is trying to convert the report to ODBC, but the ODBC driver is missing. The fix therefore depends on whether you need ODBC at all, which comes down to whether you use TLS 1.2 between the application server and the database server.

9.2  If you are NOT using TLS 1.2 — set the setting to Y

Note the reversal: Everywhere else in this guide, RPT_DISABLE_CONV_TO_ODBC is set to N so that conversion can run. This is the one case where Y is the correct answer: if there is no reason to convert to ODBC, setting it to Y stops STARLIMS from attempting the conversion, and the upload error goes away.

Check the setting from the Designer app (Application > Enterprise_Support > Enterprise_Settings > XFD Forms > Edit_Settings, as in Section 5.1) and set RPT_DISABLE_CONV_TO_ODBC to Y.

Figure 13 — Enterprise Settings in the Designer, filtered to RPT_DISABLE_CONV_TO_ODBC under the System category, with the value set to Y.

Still recycle the application pool: As with any change to this setting, the STARLIMS Application Pool must be recycled before the change takes effect.

9.3  If you ARE using TLS 1.2 — install the driver and convert

1.    Make sure the ODBC driver is installed on the server machine (see Section 3 for the version that matches your TP version).

2.    Open Enterprise Settings and enable the conversion option: set RPT_DISABLE_CONV_TO_ODBC to N (Section 5.1).

3.    Convert the reports using the right-click option for your version — Add Multi-Subnet Failover Support on 11.6, or Convert to ODBC connection on 11.7 and higher (Section 6.3). You can convert one report or a whole category.

An OLE DB report will never work with TLS 1.2: If the report still uses an OLE DB driver, it cannot work over TLS 1.2 — converting it is the only fix. Download the report and check its provider, as described in Section 2.

9.4  Report Printing Service

The same failure can occur in the Report Printing Service. If it does, check both of the following on the printing service machine:

1.    If this is a runtime upgrade, verify the version of the files in the Printing Service folder — ReportPrintingService.exe and Starlims.Server.Reporting.dll should be version 11.7 or higher.

2.    Verify that the ODBC driver is installed on the printing service machine.

Figure 14 — ODBC Data Source Administrator (64-bit) > Drivers tab — confirm the required driver is listed. This is also how to verify driver installation on the application and BATCH servers.

10.  Troubleshooting

11.  Quick reference