
	Applies To

	Product(s):	gINT Logs, gINT Professional, gINT Professional Plus
	Version(s):	N/A
	Environment:	N/A
	Area:	Report-Log
	Subarea:
	Original Author:	Kathleen Holcomb, Bentley Technical Support Group

This wiki explains and demonstrates the main underlying concepts in how a log report is created and modified in REPORT DESIGN:

Entities
Report properties
Entity properties
Expressions and functions
The Data Tool

Note: To perform the exercises in this wiki requires the use of the communities.bentley.com/.../std-training-project-_2600_-library.zip.

Basic Concepts in Log Report Design:

Report Design Overview

A report form is a set of graphics and properties that tell the program which data to output, how it is to be manipulated, and what it will look like. It is a structure that when combined with database data, generates a full-featured report. Let’s look at a log report in OUTPUT, then see what the report form that was used looks like in REPORT DESIGN. Do the following:

IMPORTANT: Ensure that the current library is training.glb. If not, select File -> Change Library.
Go to OUTPUT and select the Logs tab, if not already selected.
Open the training.gpj project.
Select ‘ENVIRONMENTAL BH’ from the object selector.
Select borehole ‘B-1’ in the Borehole ID field.
Click the Preview button. When the report appears, zoom in to show the upper half of the report using the Zoom Window or other zoom tools. The report looks like this:
Close the preview and select REPORT DESIGN -> Logs.
Zoom in on the upper half of the report. Notice that the same fields and graphic entities appear, but in a schematic form.
Select Settings -> Iconize Data Fields to remove the checkmark from this menu item (if checked). This causes many of the data expressions to be revealed:
Select Settings -> Iconize Data Fields again to place the checkmark back on the menu item.

A report is designed using a combination of two methodologies:

Report properties
Report entities

Report properties are characteristics that (in most cases) define the physical layout of the report: the dimensions and location of the data frame, the spacing of major and minor tick marks, the setup of grids and scales, and so on. There are also advanced report properties that are not covered here.

Report entities (or entities, for short) are features you place in the report design. The main entity types in log reports are the following:

Static drawing entities and text entities that are independent of the data, like boundary lines and axis labels.

Text entities that are populated with data from the database.

Note: On your screen you only see asterisks rather than field name expressions such as ‘<<PROJECT.Client>>’. That is because you currently have the Settings -> Iconize Data Fields setting checked. If you were to uncheck it, you would see the expression for each text entity.

Column entities that generate a scale or use the data to create vertically arrayed text items or graphic fills regions.

Depth-related individual entities whose depth is dependent on the data, such as water-level indicator symbols.

gIDraw is the subsystem of gINT that creates the drawing environment in the REPORT DESIGN application: the drawing area, the toolbox, the menus, and the command, coordinate and button areas. gIDraw is an engineering drawing application that shares several features with CAD systems, but many of whose drawing objects—the report entities—are manipulated at output time by database data to create structures on the log (or other) report.

Report Properties

Report properties are the characteristics that define how the report looks and also contain options for referencing data on the report. These properties allow you to set up the structure of the report. All reports share the General tab. The remaining tabs on the report properties dialog box are specific to the report style selected (graphs, logs, fences, and so on).

Let’s take a look at the properties of the ENVIRONMENTAL BH report.

Click the properties icon to view the LOG REPORT PROPERTIESdialog box:
Notice that you are initially in the General tab, and that this is one of five tabs. Notice also that there are various property fields in the General tab, some of them fairly obvious in purpose (such as Name, Description, Leftand Bottom Margin, Page Size and Orientation) and others that don’t seem obvious yet.
Click on each of the four remaining tabs in turn. Notice that each provides an additional set of properties that can be specified.
Report property settings are initially set when you create a new report. You can later change them in the current report by clicking the Properties icon and making the desired edits.
Click Cancel to exit the LOG REPORT PROPERTIES window.

Entity Properties

Every entity in a report is defined by its entity type, which is determined by which menu option or icon was used to create it, and the entity properties. The properties for an entity are entered into a multi-tabbed properties window, similar to the report properties window. We will examine some of the entities in the ENVIRONMENTAL BH report.

Do the following:

Using the Quick Zoom tool, zoom in on the column entities on the left side of the report.
Double-click in the Depth (leftmost) column, in the area near the crossed diagonal lines. This opens the COLUMN - VERTICAL SCALE PROPERTIES dialog box.

Note: Double-clicking in the header of a column entity does not open it. You have to double-click in the area below the header.
Notice that the title bar identifies the entity type, using the following format:

entity_type PROPERTIES

In the present case, the entity type is ‘COLUMN - VERTICAL SCALE’. This is a vertical scale column entity, which generates a depth scale or elevation scale on each page of the report.
Click on two or three of the tabs in turn, and notice that each one has a different set of properties or fields (we use the terms interchangeably in a report properties or entity properties window).
Return to the Main tab. Notice that the Column Width Expression property has a value of ‘0.35’ and the X property has a value of ‘0’. This specifies that the column has its left edge at X=0 (the report frame’s left edge) and the column is .35" wide.
Click on the drop-down arrow to the right of the Type property. Note the options for this property setting, which determines which kind of vertical scale appears. Press Esc to close the drop-down.
Return to the Main tab. Notice that the Column Width Expression property has a value of ‘0.35’ and the X property has a value of ‘0’. This specifies that the column has its left edge at X=0 (the report frame’s left edge) and the column is .35" wide.

Click on the drop-down arrow to the right of the Type property. Note the options for this property setting, which determines which kind of vertical scale appears. Press Esc to close the drop-down.
Click Cancel to close the properties window.

Expressions and Functions

Many properties in entities can hold an expression, rather than just a simple value. These properties have the Expand

button to the right of their text box. An expression derives the property value by performing a calculation, looking up data, and/or performing other manipulations. Here’s a more complete definition:

A gINT expression is a combination of table-field data locations, user data items, system data items, functions, operators, and formatting codes that are interpreted, that is, evaluated, by the software, and which returns a result value from that evaluation. Expressions can range from simple text or numbers (in which the result is the same as the expression) to very complex, multi-line combinations.

We’ll explain these terms:

Table-field data locations: When you need to include a reference to a field located in the project database, you enter it into an expression in the form <<TABLE.Field>>, such as <<LITHOLOGY.Bottom>> or <<SAMPLE.Recovery Length>>.

User Data Items: A user data item is an expression, saved in the library, that you create in DATA DESIGN -> User System Data and give a name to. Then you can invoke this expression by calling its name from inside another expression. In an expression in a report property or entity property, a user system data item is written as <<User System Data.user_data_name>>, such as <<User System Data.Blows and N Value>>.

System Data Items: System data items are similar to user data items, except that they already exist in gINT, and you cannot create or modify them. Various data items provide useful information that you may need to include in your report, such as the number of pages of output, the top elevation on a log page, or the company name and address.

Functions: A function performs a manipulation on one or more arguments that you supply to it. It takes the form <<function_name(argument1, argument2,...)>>. For example, <<Avg(<<SAMPLE.Depth>>)>> returns the average of the sample depth values in the borehole.
Notice that the double angle-bracket symbols enclose a function statement, similarly to how these symbols enclose a table/field reference.
Operators: Operators are mostly found inside functions. These can include arithmetic operators such as ‘+’ and ‘-‘, and logical operators such as ‘And’ and ‘Or’.

Formatting Codes: A formatting code applies character formatting such as bold, italic or color to whatever follows it in the expression. For example, if you want the sample number to print in bold, you would enter ‘<<B>><<SAMPLE.Number>>’.

To see how expressions are used in properties, do the following:

Double-click in the column entity in the right two-thirds of the SAMPLE TYPE-NUMBER column. The COLUMN - TEXT VS DEPTH PROPERTIESwindow opens.
Notice that the Column Width Expression property contains a numeric value, the Text Expression property contains a complex expression, and the Depth Expression property contains a user data item reference.
Click on the Expand button to the right of the Text Expression property. The contents of the property are opened in an expression builder window.
Notice that the upper portion of the window consists of four drop-down lists and two Paste buttons. This area is called the Data Tool, and is discussed below.
Notice that the expression contains a function called ListBuildSepTrim, the ‘<<cr>>’ formatting code for inserting a blank line, and two table-field references (sample type and sample number).

The ListBuildSepTrim() function creates a combined character string by concatenating together each of the arguments (three arguments in this case, including the <<cr>> formatting code).
Notice that a continuation character—the underbar symbol—terminates every line except the final one. This is so that the ListBuildSepTrim() function can be broken into multiple lines. Unless you use continuation characters, you cannot break up a function onto separate lines, and doing so improves the readability and understandability of the function. Here is what the expression would look like without formatting it:
<<ListBuildSepTrim(<<cr>>,<<SAMPLE.Type>>,<<SAMPLE.Number>>)>>
Especially in complex expressions, formatting the expression for readability is a very good idea.
Click OK to close the expression window.

The Data Tool

The Data Tool is a feature that appears at the top of any text entity or column entity properties window (or for certain other data dependent entities). It also appears in the expression builder window that opens when you click the Expand button to the right of properties that can hold expressions.

The Data Tool provides quick lookup access to database fields and the ability to paste them into property settings, eliminating the need for manual lookup and entry. It performs a similar role for functions, system data items, formatting codes, and other elements of expressions. The ability to look up and paste data and function elements into an expression—instead of manual typing—saves time and reduces the likelihood of mistakes.

To illustrate how the Data Tool is used, you will create a simple text entity:

Click the Report Properties button.
In the LOG REPORT PROPERTIES window, click the Browse button to the right of the Data Template property.
Select data entry.gdt then click OK. Click OK to close the LOG REPORT PROPERTIES window.

You must specify a data template in the report properties so that the tables and fields listed in the Data Tool are appropriate for that report. You can specify different data templates for different reports.
Select Draw -> Text -> Text. The TEXT PROPERTIES window appears for the new text entity, as shown:

The Data Tool consists of everything in the dialog box above the top of the tab bar.
Click in the Text Expression field.
In the Data Tool, click the drop-down arrow to the right of the Table list. Select the POINT table.
Click the drop-down arrow to the right of the Field list. Notice that the list includes all of the fields in the POINT (Borehole) table. Select the ‘Date Started’ field.
Click the Paste button immediately above the Field drop-down list. Notice that the following expression is pasted into the Text Expression field:
<<POINT.Date Started>>

The left half of the Data Tool is not restricted to project data tables. It can also display library table fields, user system data fields, and graphic symbols (such as material fill symbols). Project data tables are listed first in the Table drop-down list, followed by the other items.

The right half of the Data Tool is for pasting functions, system data items, operators, constants, and so on into expressions.

To see these capabilities, perform the following steps:

Highlight the expression in the Text Expression field.
Click the drop-down arrow to the right of the System list. Select ‘Functions’.
Click the drop-down arrow to the right of the Items list. Select ‘Format()’.
Right-click on the Paste button immediately above the Items drop-down list. Notice that the text of your previous expression has been inserted into the Format() function to create the following:

<<Format(<<POINT.Date Started>>)>>

Also notice that the cursor is immediately to the right of ‘<<POINT.Date Started>>’. This is because another argument is required: the format string.
Enter a comma followed by the string "MMM D, YYYY" in quotes. This formatting string converts a date to a format like ‘Jun 3, 2006’. The complete expression appears like this:
<<Format(<<POINT.Date Started>>,"MMM D, YYYY")>>
With functions, right-clicking the Paste button wraps the selected function around the highlighted text. Left-clicking the Paste button causes the selected function (or other system data element) to replace the highlighted text or insert at the cursor position (if nothing is highlighted).
Click Cancel to discard the text entity you have created. Normally you would click OK, which creates the entity in the report, but we do not want to add this text entity to one of our standard reports.

Note: In any expression builder window or property with a Data Tool, you can right-click to bring up a context menu.

Changing the Data Template Property in Multiple Reports

If you assign a Data Template to the report, it will populate the Data Tool and enable you to paste table and field names from the data template into report properties. This can help ease the process of designing (or editing) reports by synchronizing the report with the data structure (the table and field structure) contained in your data template file.

The data template needs to match your database structure, and it is important to update your data template (if you make changes to your data structure) to keep your projects, data template and reports consistent.

You can change the data template for multiple reports using DATA DESIGN without opening each report and modifying it. To do this, do the following:

Go to DATA DESIGN and click on the Project Database tab.
Select the Tools -> Assign Data Template to Reports menu option. You see the Assign Data Template to Reportsdialog box:
Select ‘data entry.gdt’ in the Data Template field.
Click the Browse button on the Report List field. Notice that all the reports in your library are listed. You can select specific reports to assign the template to by Ctrl-clicking or Shift-clicking on groups of report names. Click Cancel. This leaves the Report List field blank, which means to update the template in all reports.
Click Check the Assign to Data Design:Library Tables and Assign to Data Design:User System Data checkboxes. This assigns the specified template to these applications in DATA DESIGN.

Understanding Log Report Layout

The dimensions of a log report form, its placement on the printed page, and the heights of the vertical regions dedicated to particular kinds of data, are all specified in the report properties. Let’s see how this works for an existing report. Do the following:

Go to REPORT DESIGN->Logs.
Ensure that Settings -> Paper Outlines is checked; if not, select the option to add the checkmark.
In the object selector, choose ‘FINAL SIMPLE LOG WITH LEGEND’. Click the Zoom Extents tool, then the Zoom Out tool to view the entire report (including the page edges).

Note: We chose this report because it utilizes both a report header and footer.

Notice the following features of the report layout (starting at lower right in the diagram):

Page Edge: The outermost dashed-line rectangle designates the edge of the paper. In the current case, this rectangle is 8.5" x 11", since the Page Size is ‘Letter’.
Edge of Printable Area: This dashed-line rectangle is specific to your printer, and is only drawn so that you can see whether any of your report elements will be cut off by the printer. No calculations are based on the edge of the printable area.
Report Border: This is a box that defines the outside of the report, and typically encloses all of the report’s elements. The border’s dimensions are defined by the Border Height and Border Width properties, and its lower left corner position (relative to the page edge) is defined by the Bottom Margin and Left Margin properties.
Bottom Margin: Specifies the vertical distance from the bottom of the page edge to the bottom of the border box.
Left Margin (not shown): Specifies the horizontal distance from the left page edge to the left edge of the border box.
Report Footer: The report footer, like the report header, is a vertical region of the report where information at the project, company, or entire-borehole level resides. Depth-specific data, that is, data from individual records in child tables of POINT, is not displayed in the report footer or header. However, such depth data may be summarized, as with a Hole Depth or Average Water Depth field. The height of the report footer region is specified in the Page 1 Footer Height and Page 2 Footer Height properties. In many reports, the footer is omitted (by setting these properties to zero).
Report Body: The report body is the vertical region of the report where depth-based entities are used to display depth-specific child data for the borehole. For example, in the current report, data from LITHOLOGY table records is presented graphically in the Graphic Log column and the material descriptions from the same records appear in the Material Description column. Similarly, SAMPLE table data is presented in the Type (graphic) and Number (text) columns. All entities that plot or print against depth are restricted to the report body. The height of the report body is specified in the Page 1 Body Height and Page 2 Body Height properties.
Column Header: The column header is the vertical region where the heading label is displayed for each column entity. The height of this region is specified in the Column Header Height property.
Report Header: The report header is comparable to the report footer, in that this is an area for display of entire-borehole, project, and/or company information. The height of the report header is not directly specified. Instead, it is calculated as the height of the border, less the heights of the footer, body and column header. If you have a specific report header height in mind, you must adjust these other parameters accordingly.

The following table summarizes this information by property:

Property Name	Tab	Purpose
Bottom Margin	General	Vertical distance from the bottom paper edge to the bottom of the border box.
Left Margin	General	Horizontal distance from the left paper edge to the left edge of the border box.
Page Size	General	Specifies the dimensions of the paper to be printed on.
Border Height	Columns and Lines	Height of the report bounding box.
Border Width	Columns and Lines	Width of the report bounding box.
Column Header Height	Columns and Lines	Height of the region where the column entity labels are printed.
Page 1 (or 2) Body Height	Report Structure	Height of the body, which is the region where depth-specific entities appear.
Page 1 (or 2) Footer Height	Report Structure	Height of the footer, which is one of two regions (the other is the report header) where borehole-level, project-level and summary data appears.

Let’s see how these values interact in the FINAL SIMPLE LOG WITH LEGEND report.

Click the Properties

icon. View the contents of the General, Report Structure and Columns and Linestabs. The following values have been set:

Property Name	Tab	Value
Bottom Margin	General	1
Left Margin	General	1.25
Page Size	General	Letter
Border Height	Columns and Lines	9
Border Width	Columns and Lines	6
Column Header Height	Columns and Lines	0.5
Page 1 Body Height	Report Structure	7.5
Page 1 Footer Height	Report Structure	0.5

These settings can be diagrammed as follows: