CA-dBFast
A dBase-compatible application development system
Release Notes
CA-dBFast 1.0 - November, 1992
Contents
This document contains information on the following topics:
Performance Tips for dBase III+↗ Files
Using CA-RET with CA-Clipper↗ Files
Using CA-RET with Text Files
Outer Joins Using CA-RET
Exporting CA-RET Reports in Rich Text Format
Using CA-RET with DDE↗
Using CA-RET Sample Reports with DDE
Text Comparisons and Trailing Blanks
Performance Tips for dBase III Files
When two or more dBase III files are joined, performance will be greatly improved if an index file is used. Although the report query will work without the index, performance will be unacceptable for files with a non-trivial number of records. To specify an index, you must edit the report query SQL↗ statement. For more information, see the CA-RET Reference Guide, Appendix B, "Using Your Database with CA-RET."
NOTE for CA-dBFast users: The Visual Designer of CA-dBFast automatically creates the SQL statement to be sent to CA-RET by using the index information specified when the report was first defined in the Visual Designer. After clicking the Report icon for the first time in the Visual Designer, you are prompted to select the data file and index (or data view) on which the report query should be built. If you choose a data view, CA RET also makes use of the indexes, data file relations, field lists, and data filters defined to the data view.
Using CA-RET with CA-Clipper Files
CA-Clipper files are used the same way dBase III files are used. To use a CA-Clipper index, specify the index just as you would specify a dBase III index (see the index_spec description in the FROM clause section of the CA-RET Reference Guide, Appendix B, "Using Your Database with CA-RET"). Use an .NTX extension for the file specification of a CA-Clipper index. CA-RET assumes all index files with an .NTX extension are CA-Clipper indexes. For example, to use the DETAILS.NTX index:
SELECT *
FROM INVOICE, DETAILS(C:\CARET\DETAILS.NTX)
WHERE INVOICE.ID = DETAILS.ID
Using CA-RET with Text Files
NOTE for CA-dBFast users: The version of CA-RET shipped with CA-dBFast permits the use of .DBF files only, not text files.
CSV↗ Text Files
When CA-RET processes text files, it must guess the data types of all fields. By default,
CA-RET scans the first 25 rows of your text file. For CSV files, CA-RET rounds up the maximum width of the text fields in the first 25 rows to a multiple of 5. This will be the maximum width that CA-RET will process for that text field. If rows after 25 have wider values for that field, only that maximum number of characters will be returned. To avoid this, do one of the following;
Explicitly tell CA-RET to look past 25 rows. Edit the QEX.INI file in the Windows directory to specify the number of rows to scan. Modify (or add) the FieldSizing value to be the number of rows you would like scanned. Of course, a high number would result in poorer performance. These rows will be read each time the report is opened or run. A sample section for QEX.INI might look like this:
[QETXT]
FieldGuessing=1
FieldSizing=30
Specify the width in the SQL query. Use the data_type_spec described in the FROM clause section in Appendix B, "Using Your Database with CA-RET," in the CA-RET Reference Guide. For example:
SELECT text_field FROM c:\caret\text.csv(char(30))
Construct your data so that the maximum width field occurs in the first 25 rows.
Fixed Record Length Text Files
The simplest way to access data in a fixed record length text file is to completely parse the file in the PARSE= statement. Also, it is easiest to define the SELECT clause if the HEADERLINE field definitions are all upper case. The following two samples show how to access fixed record length text files using both upper case and lower case HEADERLINEs. Note that only the selected fields are bracketed in the PARSE statement and defined by the data_type_spec that follows the PARSE= statement.
SELECT DEPT,
LOCATION
FROM C:\CARET\SAMPLES\DEPT.TXT
(HEADERLINE=1,
CHARSET=IBMPC,
PARSE="[DEPT ]NAME [LOCATION ]",
NUMBER(5,0), CHAR(9))
DEPT NAME LOCATION
1 Staff Kingshead
5 Sales Northwood
6 Production Denton
15 Level 1/2 Support Westwood
If the HEADERLINE in your data file contains field names in lower case, then you must enclose the field names used in the select statement with the ` (accent grave or backward apostrophe) character.
SELECT `dept`,
`name`,
`location`
FROM C:\CARET\SAMPLES\DEPT.TXT
(HEADERLINE=1,
CHARSET=IBMPC,
PARSE="[dept ][name][location ]",
NUMBER(5,0),CHAR(21),CHAR(9))
dept name location
1 Staff Kingshead
5 Sales Northwood
6 Production Denton
15 Level 1/2 Support Westwood
Outer Joins Using CA-RET
CA-RET supports outer joins with use of the *= operator. The where clause DEPT.DIV *= DIV.DIV in the following example will return all the DEPT rows even though they are not assigned to a division (i.e., all unmatched rows).
SELECT *
FROM x:\path\DEPT.DBF,
x:\path\DIV.DBF
WHERE DEPT.DIV *= DIV.DIV
NOTE for CA-dBFast users: Outer joins are not supported for reports created from within the CA-dBFast Visual Designer.
Exporting CA-RET Reports in Rich Text Format
A CA-RET report can be exported to a DOS↗ file in one of two formats, ASCII↗ text (unformatted) or Microsoft's Rich Text Format (RTF). RTF preserves the fonts, paragraph formatting, and alignment characteristics used in the report and is supported by several Windows word processors including CA-Textor↗, Microsoft Word for Windows, and Lotus AmiPro. The following caveats apply to RTF exports from CA-RET:
CA-RET page footers are placed into RTF immediately after the previous section; they may not appear at the bottom of the page if the body section does not fill the page.
Word wrapping is not preserved in RTF; the report may wrap and paginate differently after importing.
In CA-RET, graphics (lines, rectangles, and bitmap images) float freely in the section in which they are placed. RTF assumes that graphics are tied to a particular paragraph. Reports which contain graphics may not import correctly. In particular, when CA-RET exports a graphic, it places the object as if the section it is in were at the top of the page. To avoid this, either move the graphic to the desired location after importing the RTF file or include graphics only in page headers or other sections that will always be at the top of the page.
Bitmaps, lines, or rectangles placed inside a CA-RET cell may cause Microsoft Word for Windows to generate incorrect results or even crash when the RTF file is opened. To avoid this, place graphics outside of tables (in a plain text area) for reports which are to be exported to RTF.
Paragraph borders in CA-RET may not be applied correctly after importing the RTF file.
The maximum RTF report size that can be requested via DDE is 61,440 bytes. To access large reports via DDE, first export to a file (via the DDE Export command), and then import the file into your application.
Using CA-RET with DDE
To begin a DDE conversation, you must first open a channel between your application and CA-RET using the INITIATE function:
channel = INITIATE( application, topic )
To communicate with CA-RET, the application parameter must be "CARET" for CARET.EXE and "CARETRUN" for type run-time executable, CARETRUN.EXE. Note that when using CARETRUN.EXE, you can use only features supported by the run-time. CARETRUN.EXE does not support File.Save, File.New, Database.Set.SQL, and Database.Set.Report.Query.
CA-RET supports the following topics:
Topic Result
SYSTEM Opens a channel with CA-RET for commands
Report definition file name Establishes a link with the specified report
SYSTEM is the preferred topic if you will be issuing any commands (other than data requests) on the channel. There are restrictions if you initiate the channel on the file name topic:
You may not request data from any other report on the channel.
No user interaction is permitted during the initiate command. This includes no dialog boxes (e.g., for changed file specifications of the database), no error message boxes, and no prompting for parameters.
Most DDE commands and all DDE requests are executed synchronously; that is, the work associated with the command is completed when the command is executed. Some DDE commands are asynchronous; that is, the work is requested to be done by the command, but may be completed at a later time. The following commands are asynchronous:
File.Close
File.Exit
Export
File.Preview
File.Print
To determine when asynchronous commands are completed, you may issue an advise transaction using the SYSTEM topic and the CARETEVENTS item to receive notification of the following events:
Notice Event
Report.Complete Completion of report for export, preview, or print
File.Save;<filename> Before saving a file with name <filename>
Report.Opened Completion of File.Open()
Report.Close Closing of editor window.
View.Close Closing of preview window.
Note that CA-RET sends Report.Opened, Report.Close, and View.Close notification only if your application opened the report using DDE.
In the following two DDE commands, the SQL statements should be single quoted :
Database.Set.SQL(db_type, "sql") on page 6-4 of the CA-RET Reference Guide should read Database.Set.SQL (db_type, 'sql')
File.New(db_type, dfttype, lblid, filename, "sql") on page 6-5 of the CA-RET Reference Guide should read File.New(db_type, dfttype, lblid, filename, 'sql')
Word for Windows users should note that the CARET.DOT template commands CA-RET Insert Report(text) and CA-RET Insert Report(RTF) cannot be used to insert a report that requires parameters. The user must write a DDE Macro in Word and set the parameters by using the command Set.Parameter(number, value).
NOTE for CA-dBFast users: The CA-dBFast commands and functions to access CA-RET via DDE are as follows:
CA-RET DDE Command CA-dBFast Equivalent
INITIATE TALK TO CARET ABOUT <topic>
ADVISE AUTODATA('CARETEVENTS')
You would then check the contents of CARETEVENTS to determine the event returned. See the CA-dBFast User Guide for more information about using DDE in CA-dBFast.
Using CA-RET Sample Reports with DDE
The sample reports contain relative path references to databases and images. That is, instead of specifying C:\CARET\SAMPLES\SALES.DBF, SAMPLES\SALES.DBF is used. This is done to permit installation of CA-RET into any directory. However, if CA-RET's working directory is other than the installation directory, the sample databases and images will not be found. This can happen if DDE is used to start CA-RET. To set full paths for the sample reports, exit windows and go to DOS, change your directory to the sample directory (e.g., CD \CARET\SAMPLES), type CHGRET, and press Enter. CHGRET will display the list of report definitions that are being updated.
Alternately, you could change the paths for all databases by editing each report:
Select Database Edit
Select Query Tables
Select each table referenced
Choose Edit File Name
Enter the full path
To change the image file specifications, select the image either by double clicking on the image or by clicking on the image and choosing Format Picture; then modify the Source file specifiation.
Also, the CA-RET directory should be added to the DOS path when you use DDE to start CA-RET.
Text Comparisons and Trailing Blanks
Trailing blanks are significant when comparing text fields; "ABC" is not the same as "ABC ". Keep this in mind when comparing values in queries and in If() functions. To avoid the problem, you may use the RTRIM function in queries (...WHERE RTRIM(FIELD) = "ABC"), and the Trim() function with expressions (If( Trim(FIELD) = "ABC", 1, 0 )).
Windows, Word for Windows, and Write are registered trademarks of Microsoft Corporation. dBase III is a registered trademark of Borland International, Inc. All product names referenced herein are trademarks of their respective companies.
The following commands are asynchronous:
File.Close
File.Exit
Export
File.Preview
File.Print