Understanding and Extending Report Structure
In Visual FoxPro 9.0, both design-time and run-time Report System extensions are more feasible and varied than ever before. To ensure you create extensions successfully, you must understand the report (.frx) and label (.lbx) table structures.
Note
Report and label file structures are identical in Visual FoxPro. For more information about the contents of the FILESPEC directory, see Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx).
This topic discusses how you explore and extend the tables' use of various columns to describe different aspects of report layout and behavior. It also provides you with specified limitations for extensions to these tables.
This information allows you to:
Manipulate existing report and label table data successfully.
Describe new types of report elements and behavior in the tables.
Understanding the Changes to Report and Label Tables
Visual FoxPro 9 adds no required fields to the native report table structure. Because no new fields are added to migrate report and label forms, you can use Visual FoxPro 9's enhanced design facilities to edit existing reports. These reports will still run when distributed to end-users of your existing applications.
To support various design-time and run-time enhancements, Visual FoxPro 9 overloads some fields in report and label tables, using them in new ways for report elements that did not use these fields in earlier versions. Some of the new values are not used directly by the product, instead providing information to ReportBuilder applications or other user-code.
Visual FoxPro 9's new content, supporting design and processing enhancements, can also be added into existing reports without disturbing backward- compatibility. The additional content in report and label fields will be ignored at runtime by Visual FoxPro 8 and earlier versions.
Visual FoxPro provides information about the system tables for various elements, including reports, in the FILESPEC directory. Visual FoxPro 9.0 supplies an updated copy of 60FRX.DBF, the table that specifies usage of the various fields in the report and label tables.
Changes to 60FRX.DBF
The 60FRX.Descriptio column has been updated in almost every record, to better explain usage of fields by reports and labels. The updated information you see in this field applies to all versions of Visual FoxPro, and adds a separate section indicating any new usage in Visual FoxPro 9.0.
The following example is the 60FRX.Descriptio entry for the 60FRX.Fields value RULERLINES.
RULERLINES is used only in the header record.
0 = Show Ruler Lines: No
1 = Show Ruler Lines: Yes
==============================
Visual FoxPro 9-only Information Below
==============================
RULERLINES is reserved in VFP9 for OBJTYPE=8 (Field) for StringTrimming.
Default is StringTrimmingEllipsisWord.
0 or not entered = Default
1 = StringTrimmingCharacter
2 = StringTrimmingWord
3 = StringTrimmingEllipsisCharacter
4 = StringTrimmingEllipsisWord
5 = StringTrimmingEllipsisPath (for filenames).
To help you find how each type of report and label field is used for different types of layout elements, the Visual FoxPro 9.0 version of 60FRX.DBF contains a new field, 60FRX.Usedby_obj. The 60FRX.Usedby_obj field contains a list of keywords for all report elements that uses a given field.
For example, if you wanted to find out all fields used in the header record of a report or label file, and a description for how these fields are used, you could issue this command:
SELECT Fields, Descriptio FROM 60FRX WHERE ATC("Header",Usedby_obj) > 0
The Fields column in the resulting cursor gives you the name of each field in an FRX or LBX table used in the Header record. The Descriptio column tells you how each field is used.
Tip
If a report field has new uses in Visual FoxPro 9.0, the keywords for elements newly using the field follow a symbol, "|", in the 60FRX.Usedby_obj list. For example, for the 60FRX.Fields value RULERLINES, the 60FRX.Usedby_obj value reads HEADER | EXPR. As indicated in the 60FRX.Descriptio entry for RULERLINES above, previous versions of Visual FoxPro used this field in the header record only. Visual FoxPro 9.0 also uses this field for Field (or Expression) layout elements. As a result, the two keywords appear separated by the "|" symbol in the 60FRX.Usedby_obj column.
The following table gives you the 60FRX.Usedby_obj keywords for each type of report object.
Report table Objtype field value |
Report object description |
60FRX.Usedby_obj value |
|---|---|---|
0 |
Comment |
N/A |
1 |
Report Header |
HEADER |
2 |
Workarea (FoxPro 2.x reports) |
20TABLE |
3 |
Index (FoxPro 2.x reports) |
20INDEX |
4 |
Relation (FoxPro 2.x reports) |
20RELATION |
5 |
Label |
TEXT |
6 |
Line |
LINE |
7 |
Rectangle / Shape |
SHAPE |
8 |
Field |
EXPR |
9 |
Bandinfo |
BAND |
10 |
Group |
GROUP |
17 |
Picture / OLE Bound |
PICT |
18 |
Variable |
VAR |
21 |
Printer Driver Setup (FoxPro 2.x reports) |
20PDRIVER |
23 |
Font resource |
FONTRES |
25 |
Data Environment |
DATAENV |
26 |
Cursor, Relation, or CursorAdapter (See Name field to determine which) |
CURSOR-RELATION |
Creating Valid Report and Label Content
Visual FoxPro 9 supplies reference code to show you how to locate and size the various objects used in reports and labels in Foundation Classes. For more information, see FRX Cursor Foundation Class and FRX Device Helper Foundation Class. These classes are part of the default ReportBuilder Application. They give you the ReportBuilder Application's tools to use, when you want to determine appropriate placement and metrics for new report and label elements.
Formatting and Reviewing 60FRX.DBF Information
A new report in the FILESPEC directory, 90FRX.FRX, provides consolidated information on full report and label table usage in all versions, while highlighting new-to-Visual FoxPro 9 usage. The earlier reports available for 60FRX.DBF, 60FRX1.FRX and 60FRX2.FRX, are still included in FILESPEC.
Extending Report and Label Tables Safely
Visual FoxPro 9 provides reliable persistence of user-defined content in reports and labels. You can add your own content to these tables in the following ways:
Add new columns to report and label tables.
Add new report and label object types as rows to the tables.
Add records with new Platform values (records that with platform values other than "Windows").
Add private data into columns, such as the User column, not used natively by reports or labels.
Add private attributes into the Reporting memberdata XML data schema. Reporting memberdata is stored in the Style column. For more information, see How to: Assign Structured Metadata to Report Controls.
Visual FoxPro 9 preserves all these types of user-defined content, whether they occur in records used natively, or in additional records. It makes this content available to user code in Report Designer sessions, through Report Builder hooks. When you process reports and labels, it makes the full content of the report or label table available to ReportListener events and methods.
Warning
Earlier versions of Visual FoxPro did not preserve user content in design sessions and did not allow user-defined records or columns in report and label tables. As a result, you should not add new types of content into reports and tables using Visual FoxPro 9 if you expect to edit these files in earlier versions later, because the new content can be lost. You can add new content into existing records of reports and labels and distribute them successfully to users of earlier versions. However, do not add new columns into these tables, to ensure that the earlier versions can recognize the tables as reports and labels.
The following limitations must be observed when you extend reports and labels with new types of content.
Differentiating Between Native and User-defined Record Types
There are 100 total possible Objtype values (0 through 99). Visual FoxPro 9 explicitly reserves Objtype values 49 and below for internal or native Report Designer use. Only records with recognized and documented Objtype values, and only records containing Objcode field values natively associated with these Objtype values, are manipulated in the native Report Designer.
Users and add-ons such as ReportBuilder Applications can alter the contents of records with natively-recognized values in the Objtype field of the report or label. They can also add new records with native Objtypes, taking care to follow standard usage of columns for all native types.
Users and add-ons should not add unknown or undocumented Objcode values to records with native Objtype values (49 and below). They may be removed by the native Report Designer without warning.
You can add records with user-defined Objtype values of 50 and above. These records can have any Objcode values. The native Report Designer preserves and ignores all content of such records, but ReportBuilder Applications and other add-ons can be used to add and modify them.
Note
Although user-added records with Objtype values of 50 and above are preserved, the position of such records within the report or label table is not guaranteed. A Report Designer session may change the order of records in the report table. User-defined records will usually appear at the end of the table after the report is saved by the Report Designer. If record order is significant to your application, store information relevant to record order in an additional column.
Ensuring Unique ID Values for Records With User-defined Content
Extra content in any records without UniqueID values,including content in native fields such as the User field, will not be preserved. The restriction holds for records with native Objtype values as well as user-defined Objtype values.
Tip
Use the SYS(2015) function to create values for the UniqueID field of new records. Use the FRXCursor Foundation Class's getFrxTimeStamp method to create appropriate Timestamp values.
Reports and labels have a few native Objtype values without UniqueIDs, notably font (objtype 23) and data environment-related resources (objtypes 25 and 26), used in specific ways by the Report Engine at runtime. It is also possible to have a “comment” record (objtype 0 or blank). The Report Designer and ReportBuilder Application are not guaranteed to preserve user-defined content in these records. You can add new records of the appropriate objtypes for these resources, giving them standard contents. You can also extend these resources by associating user-defined object types with them. For example, a record of objtype 53 could represent an "extended font resource record.
Locating User-added Content in Report and Label Table Structures
User-added columns must be at the end of the Report or Label table structure. If native columns are re-ordered, deleted, edited for size, type or name, etc., Visual FoxPro will consider the report or label to be invalid.
The header record of the table, describing global report or label attributes, must remain in its standard position (first record in the table).
The Expr, Tag, and Tag2 columns in the header record (used for printer setup attributes) are reserved for internal use.
In some limited cases, users may edit the values in the Expr column and, if these values are reasonable for the associated attributes, they will be recognized by the Designer, remain stable and be available during design sessions, and used by the Report Engine at run time. However, this behavior is not supported and not extensible. In particular, user-defined value-pairs in the Expr field will not be saved back to the report table after design sessions, even if no explicit changes to Page Setup are made during these sessions. You can use the Picture field of the header record to store user-override information for printer instructions, instead. For more information, see SYS(1037) - Page Setup Dialog Box.
See Also
Concepts
Report XML MemberData Extensions
Reference
SYS(2015) - Unique Procedure Name