This describes how to use the Merant Text Driver on Solaris and Linux through the example below. When creating a text data source, a file named "QETXT.INI" must be created in the same directory as your text file. "QETXT.INI" describes the structure of the text datasource file.
Follow the steps below to configure text drivers on UNIX platforms.
Here the files used are beans.txt, QETXT.INI, and textDriverTest.cfm.




A) Create three files:


1) Save or create "beans.txt" in a directory. This text data file contains your record set data.
Bean_ID, Type, Distributor
01, Columbian, Valdez Inc.
02, French, Tres Chaud Inc.
03, American, Maxwell House Inc.


2) Save or create "QETXT.INI" in the same directory as beans.txt. The "QETXT.INI" filename must be in all caps, and must always be located in the text data file. This file contains:
[Defined Tables]
beans.txt=BEAN
[BEAN]
FILE=beans.txt
FLN=1
TT=Comma
Charset=ANSI
FIELD1=Bean_ID,NUMERIC,2,0,8,0,
FIELD2=Type,VARCHAR,20,0,20,0,
FIELD3=Distributor,VARCHAR,20,0,20,0,
The file fields are:
∑ The name of the file, "beans.txt" is equal to the tablename, "BEAN"
∑ FILE is the file name, "beans.txt"
∑ FLN specifies whether the first line of the file contains column names, using 1 for yes and 0 for no.
∑ TT is the table type, which and describes the delimiter.
∑ FIELD1 (and so on): Define the fields in the table, beginning with FIELD1. For each field, specify the field name, field type, precision, scale, length, offset (for fixed tables), and date/time mask.



3) Save or create textDriverTest.cfm and save it in your web root. If you choose to create the file, use the code below. Make sure to save it in your web root.
[CFQUERY NAME="getBean" Datasource="myBeans">
Select * from BEAN
[/CFQUERY>


Output from query to Beans.txt via the Merant Text Driver:
[CFOUTPUT Query="getBean">
#Bean_ID#, #Type#, #Distributor#
[/CFOUTPUT>





B) Create a data source for the text file in ColdFusion Administrator.


1) For this example, create a directory called "text" at: /opt/coldfusion/database/text, or your ColdFusion install root.
2) Open the ColdFusion Administrator, and click on "ODBC" in the main menu.
3) Enter 'myBeans' as the datasource name, and select the Merant Text Driver from the dropdown list. Click "Add."
3) Fill in the data source "Description."
4) Use "Browse" to enter the "Database Directory" or type the directory path. In this case, the entry is: /opt/coldfusion/database/text/
Important note: the database directory path should point to the directory, and not the text data file itself.
5) Click "Create."



C) Call "textDriverTest.cfm" from a web browser to test the text data source. The URL should be: http://yourwebserver/textDriverTest.cfm, depending on where textDriverTest.cfm is saved. It is recommended turning on debugging in your ColdFusion Administrator. To do this, click on "Debugging" in the main menu. Check the debugging opions desired, and enter the browsing machine's IP or leave it blank (if you wish everybody to see debugging information), click "Add" and "Apply."
With debugging turned on, the following output occurs:
Output from query to Beans.txt via the Merant Text Driver:
1, Columbian, Valdez Inc.
2, French, Tres Chaud Inc.
3, American, Maxwell House Inc.
Queries
getBean (Records=3, Time=9ms)
SQL =
Select * from BEAN
Execution Time
14 milliseconds
12ms VAR/WWW/HTML/TEST/TEXT_DRIVER_QUERY.CFM
2ms STARTUP, PARSING, & SHUTDOWN



D) Possible Errors


∑ Error:
ODBC Error Code = S0002 (Base table not found)
[MERANT][ODBC Text driver]File not found '/opt/coldfusion/database/text/BEAN'.
SQL = "Select * from BEAN"
Data Source = "MYBEANS"
The error occurred while processing an element with a general identifier of (CFQUERY),
occupying document position (6:2) to (6:46) in the template file /var/www/html/test/text_driver_query.cfm.
Possible Cause: QETXT.INI is not in the same directory as beans.txt.
Solution: Move QETXT.INI to the same directory as beans.txt.


∑ Error:
ODBC Error Code = S1C00 (Driver not capable)
[MERANT][ODBC Text driver]Optional feature not implemented.
SQL = "SELECT * FROM db.txt"
Data Source = "TEXTDB"
Possible Cause: The ColdFusion user account does not have write permissions on the odbc.ini file under ColdFusion home.
Solution: chmod or chown the odbc.ini to give the cfuser write permission.


∑ Error:
ODBC Error Code = S1000 (General error)
[MERANT][ODBC Text driver]Error on input or output to a file.No such file or directory
Additional Information /opt/coldfusion/database/text/beans.txt/QETXT.INI.
SQL = "Select * from BEAN"
Data Source = "MYBEANS"
The error occurred while processing an element with a general identifier of (CFQUERY),
occupying document position (6:2) to (6:46) in the template file /var/www/html/test/text_driver_query.cfm.
Possible Cause: The CF Administrator data source settings are incorrect.
Solution: Change the setting for "Database Directory" so that it points to the directory that contains beans.txt instead of pointing to the actual beans.txt file.


∑ Error:
The browser hangs and ColdFusion restarts itself. Server.log shows the error:
Caught a fatal signal (11) - Aborting
Possible Cause: One of the three files created in Step A are owned by root instead of the user that ColdFusion is running as.
Solution: Change the owner of the files, or change the account that ColdFusion is running as.