QLR Version 5.4 User`s Guide
Query
L ayout
R eport
Manager
Your report generation tool
and more!
QLR Version 6.1
User’s Guide
by Tatler Software
Copyright © 2003–2010
Minor Release 6.1.0
November 2010
QLR Manager User’s Guide
Table of Contents
About QLR Manager .................................................................................................................... 1
Common Controls ....................................................................................................................... 2
Header tab navigation................................................................................................................ 2
Select database/schema............................................................................................................. 2
Table columns/table info ............................................................................................................ 2
Retrieving an object................................................................................................................... 3
Current object name .................................................................................................................. 3
Selecting colors......................................................................................................................... 3
Saving an object ....................................................................................................................... 5
Connect Panel ............................................................................................................................ 7
User Menu .................................................................................................................................. 8
Wizard Panel .............................................................................................................................. 9
Overview ................................................................................................................................. 9
DB & table selection................................................................................................................... 9
Joining tables ........................................................................................................................... 9
Report column specs................................................................................................................ 10
Using an existing layout ........................................................................................................... 13
Query Panel.............................................................................................................................. 14
Executing queries .................................................................................................................... 14
Batch queries ......................................................................................................................... 14
Query variables....................................................................................................................... 16
User session query .................................................................................................................. 19
Using an existing layout ........................................................................................................... 19
Executing SQL Server stored procedures .................................................................................... 19
Input Controls .......................................................................................................................... 22
Overview ............................................................................................................................... 22
Naming controls ...................................................................................................................... 22
Prompt text ............................................................................................................................ 22
Default values......................................................................................................................... 23
Control types .......................................................................................................................... 23
List of values .......................................................................................................................... 31
Query for values ..................................................................................................................... 31
Layout Panel ............................................................................................................................ 33
Titles & footers ....................................................................................................................... 33
Report body ........................................................................................................................... 33
Report breaks ......................................................................................................................... 36
Referencing column data .......................................................................................................... 38
Embedding calculations ............................................................................................................ 39
Report charting ....................................................................................................................... 40
Custom layout ........................................................................................................................ 41
Distribution e-mail................................................................................................................... 44
Report columns....................................................................................................................... 46
Creating a table layout ............................................................................................................. 53
Creating a pivot layout ............................................................................................................. 54
Linked Reports ......................................................................................................................... 57
Overview ............................................................................................................................... 57
Link style ............................................................................................................................... 57
Link window ........................................................................................................................... 57
Query mapping ....................................................................................................................... 58
QLR Manager User’s Guide
Table of Contents
Report Charting........................................................................................................................ 60
Overview ............................................................................................................................... 60
Creating charts ....................................................................................................................... 60
General characteristics ............................................................................................................. 61
X axis attributes...................................................................................................................... 63
Y axis attributes ...................................................................................................................... 64
Legend .................................................................................................................................. 65
Pie chart controls .................................................................................................................... 65
Odometer controls................................................................................................................... 66
Advanced controls ................................................................................................................... 67
Selecting plot data .................................................................................................................. 68
Scatter charts ......................................................................................................................... 68
Report Panel ............................................................................................................................ 70
Paging between page sets ........................................................................................................ 70
Display whole report ................................................................................................................ 70
Report tools............................................................................................................................ 70
Find text in output................................................................................................................... 70
Printing output........................................................................................................................ 71
Download formatted ................................................................................................................ 71
Download data file................................................................................................................... 72
Download PDF file ................................................................................................................... 73
Download XML file ................................................................................................................... 74
E-mailing output ..................................................................................................................... 75
E-mail distribution ................................................................................................................... 75
Creating a QLR Widget ............................................................................................................. 76
Defining Macros ....................................................................................................................... 79
Overview ............................................................................................................................... 79
Macro Execution Steps ............................................................................................................. 79
Step builder assistant .............................................................................................................. 79
E-mailing the results................................................................................................................ 80
Previewing & running ............................................................................................................... 81
Referencing variables............................................................................................................... 82
Custom macro layout ............................................................................................................... 83
Accessing externally ................................................................................................................ 85
Creating Menus ........................................................................................................................ 86
Overview ............................................................................................................................... 86
Titles & attributes.................................................................................................................... 86
Menu item details .................................................................................................................... 86
Menu builder assistant ............................................................................................................. 86
Previewing ............................................................................................................................. 87
Active menus.......................................................................................................................... 87
Designing Forms ...................................................................................................................... 88
Overview ............................................................................................................................... 88
Creating a simple form............................................................................................................. 88
DB & table selection................................................................................................................. 89
General characteristics ............................................................................................................. 90
Basic formatting...................................................................................................................... 94
Other properties...................................................................................................................... 98
Searching for data..................................................................................................................102
Creating sections....................................................................................................................107
QLR Manager User’s Guide
Table of Contents
Report Objects ....................................................................................................................... 108
Overview ..............................................................................................................................108
Basic steps ............................................................................................................................109
Examples ..............................................................................................................................109
Class functions.......................................................................................................................116
Popup calendar ......................................................................................................................128
Demo web page .....................................................................................................................130
Demo page source..................................................................................................................131
Data Importer ........................................................................................................................ 134
Overview ..............................................................................................................................134
Source file & target table.........................................................................................................134
Data filtering & mapping .........................................................................................................134
Import data preview ...............................................................................................................135
Installation ............................................................................................................................ 137
General instructions................................................................................................................137
LDAP interface .......................................................................................................................143
SMTP support ........................................................................................................................143
Create pseudo IDs..................................................................................................................144
Chart support ........................................................................................................................145
Version migration ...................................................................................................................147
MySQL..................................................................................................................................148
Oracle ..................................................................................................................................151
PostgreSQL ...........................................................................................................................153
Systems Admin ...................................................................................................................... 154
Overview ..............................................................................................................................154
User ID administration ............................................................................................................154
Creating input controls ............................................................................................................155
Usage tracking.......................................................................................................................155
Exporting QLR data.................................................................................................................155
Add to website/product ...........................................................................................................156
Connect panel bypass .............................................................................................................157
Connect panel message...........................................................................................................158
QLR Manager User’s Guide
About QLR Manager
About QLR Manager
Query/Layout/Report (QLR) Manager (© 2003-2007 Tatler Software) is a web server application used to generate reports from
databases. The application is 100% server based and only requires a newer, Javascript enabled web browser to begin generating
professionally formatted reports. The formatting capabilities are extensive and include such advanced techniques as table and pivoted
layouts for tabular output. Many different styles of charts and graphs can also be created from report output. After saving queries and
their associated layouts, they can be easily combined into macros that provide for the generation of many reports and charts with a few
mouse clicks. Queries and macros can also be used in the creation of user menus that hide all the SQL complexities from novice users,
or restrict access to sensitive data.
In addition to merely viewing the output, report tools provide many options for e-mailing and downloading useful file formats. Report
output can be downloaded as formatted output (HTML, MS-DOC, and MS-EXCEL), data files (MS-EXCEL, CSV, and TXT), or XML.
Contextual help is provided throughout QLR Manager and is associated with bold text and field labels, identifiable by
these areas are moused over. The full User's Guide (this document) can be launched by clicking the
or
as
in the Header.
To learn more about QLR Manager, please visit www.qlrmanager.com.
How QLR Manager is used
This application was developed to provide a user interface that is intuitive and easy to use for Restricted Users, yet offer powerful
features for more Advanced Users. With the Enterprise Edition of QLR Manager, the Administrator can grant specific levels of authority
to each User ID that can range from restricted access that permits running queries and macros from a menu, to an Advanced User that
can author queries and layouts, define macros and create user menus.
Restricted User:
• Connect and select the Function for "Queries · Layouts · Reports".
• User Menu offers a selection of macros and queries the User ID has authority to run.
• Layout (optional) provides controls used to modify the appearance of report data generated by a query.
• Report displays output and provides tools to e-mail the results and download popular formats.
General User:
• Connect and select the Function for "Queries · Layouts · Reports".
• Menu offers a selection of menus containing queries and macros that can be retrieved and run. This includes the menu associated
with the logged on User (*My Menu*) containing all the User's saved queries and macros.
• Query for retrieving, authoring and saving queries.
• Wizard for creating and saving queries without any knowledge of SQL.
• Layout provides controls used to modify the appearance of report data generated by a query.
• Report displays output and provides tools to e-mail the results and download popular formats.
Advanced User:
All the capabilities of a General User, plus the ability to define macros and create user menus.
• Connect and select the Function for "Macros · Menus · Forms".
• Define Macro to select from previously saved queries and layouts to produce output that can be viewed, e-mailed, and included in
user menus.
• Create Menu to construct a highly customizable user menu that can be associated with specific User IDs.
• Design Form supports the creation of "Forms" that allow for the editing of data found in a database table.
• Preview for displaying the output for a macro or user menu. Also provides tools to e-mail macro output or download as HTML.
1
QLR Manager User’s Guide
Common Controls
Common Controls
Provided below is a description of common controls used throughout the QLR Manager panels. The controls a user may see will
depend on their User Class and authorities granted to the User ID by the Administrator.
Header tab navigation
All the QLR Manager panels have a Header for page navigation. The header tabs displayed after logging on from the Connect panel
will depend on the product function selected and the level of authority granted the User ID. In many cases, the header tabs can be used
instead of form buttons within the body of the panel, with some limitations. For example, if a query exists in the Query panel, the
Report tab can be used to execute the query as an alternative to the Run Query button in the panel. However, if the Report tab
is clicked from the Menu panel, QLR Manager does not know which query or macro to execute and will instead display the message You must run a menu item to view the output. Many such color coded messages exist to help guide the User. GREEN messages are
for information, AMBER indicates a user action is being performed, and RED is an error condition describing why QLR Manager cannot
continue. The following are some common elements and functions of the Header, regardless of the product function selected.
Accessing help:
Manager
can be clicked to launch the full User's Guide. Contextual help is also provided throughout QLR Manager and is
associated with bold text and field labels. The mouse cursor will change to
or
to identify links to help text.
Connection status:
After connecting, the User ID, Database and Server are displayed above the header tabs.
Logging off:
The Log off button can be used any time to disconnect the User ID, delete any output temporarily stored on the server, and terminate
the session.
Report tools:
The "Report tools" icon may be substituted with "Output tools" or "Preview tools" depending on the type of output being viewed. Clicking
this icon will launch a small popup window that provides options for finding text in the output, printing, e-mailing, and downloading many
useful formats of the output. After output has been generated and the User navigates to another panel, this icon will change to "Current
report", "Current output" or "Current preview". This provides any easy means of returning to the previously generated output without
having to rerun.
Select database/schema
For MySQL, the database is the specific set of tables within the overall database system to which the User is connecting. The User
must have the authority granted by the Database Administrator to connect to a particular database. If an SQL command is issued to
create a new database, the User must access the Connect panel to reconnect and then return to the Query panel to see an
updated list.
For Oracle and PostgreSQL, the "Select Database" control lists the schemas where the currently connected User ID has access to at
least one table within the listed schema. Selecting a different schema name will update the list of tables that can be selected to view the
column attributes. This does not change the currently connected User ID, which can only be changed from the Connect panel.
Table info:
The "Table info" selection list allows the User to view the columns, and their attributes, of the selected table. A separate browser
window will be opened to display the column information. The list of tables available to choose from is based on the currently selected
database/schema. If an SQL command is issued to create or delete a table, the User must select the database/schema again to refresh
the table list.
2
QLR Manager User’s Guide
Common Controls
Retrieving existing objects
To view the list of items that others have shared, their Owner (User ID) can be selected from the Existing (objects) control near the top
of each panel. This will update the list of available Name objects that can be selected.
• The currently displayed object name can be retrieved by clicking the Get (object) button.
• The currently displayed object name can be deleted by clicking the Delete button. Objects owned by the logged on User ID are
the only ones the ID has authority to delete.
Owner:
The Owner is the User ID under which the object was saved. It is the ID under which the database connection was established.
Name:
The Name of the object as provided by the Owner when the object was last saved.
Current object name
After an object has been retrieved for use, the current object name is displayed near the top of the panel for reference. The name will
be prefaced with "Current Query", "Current Layout", "Current Macro", or "Current Menu", depending on the panel being viewed. If a
description was given to the object when it was saved, an i-nfo icon will follow the object name. Mousing over this icon will display
additional information about the object.
Selecting colors
The Color Selector allows the User to choose from a pallet of 16,777,216 RGB colors for any elements that require a color selection.
The selector can be moved within the browser window by selecting the title bar and dragging the selector to reveal page content
underneath. It is important to note the element for which the color selector was launched. This is the element that will receive the color
changes. There are 4 variations of the color selector to apply colors to the following elements:
•
•
•
•
Font and background colors for cells in reports.
Font colors for titles and labels.
Border and background colors for tables and charts.
Plot color ranges for charts.
For each of the above applications, the color selector will look slightly different, but the general layout and function of the controls is the
same.
Color selector controls:
Note: Click the labels 1 - 6 or the link in the description for more information about the function.
1
2
3
4
5
6
Display of the current color(s) and any modifications.
Display of the custom colors provided as defaults or previously modified by the User.
Base set of 70 web-safe colors to select.
Controls to create colors or enter known hex values for specific colors.
Selection of color to change when both font and background colors are required.
Control buttons to modify custom colors and apply changes.
* The color selector to apply plot colors for charts is described separately below.
3
QLR Manager User’s Guide
Common Controls
Current and new colors (1):
When the color selector is launched, the current color(s) are displayed along with an area to display any modifications made. The
color(s) in the NEW area are those that will be applied when the Apply button is pressed. The text "NEW" is only displayed for color
selections that include a foreground color.
Custom colors (2):
A default set of coordinated colors is provided with the QLR Manager installation to allow for quick and easy color selection. Custom
colors for table borders, chart margins and backgrounds are predefined to match colors that may be selected for titles, column headers
and data cells in reports. The illustration above is the foreground/background selector. The A-B-C in the custom color cells have no
significance other than to display the foreground (Font Color) selection against the Background color. As a general rule, if a darker title
and column headings are preferred, A can be used for the title, B for the column headings, and C for the data cells or alternate row
coloring in the data cells.
A company may have specific color preferences that help convey its identity. The color selector allows for the replacement of all custom
colors with user defined colors. The modification of custom colors is described in the Control buttons topic below.
A custom color is selected by clicking the desired color cell in area 2. The selection will appear in the NEW area of the selector.
Clicking the Apply button will apply the selection and close the selector. A custom color can also be selected as a starting point to
make modifications using the controls in 4 and 5, or a web-safe color can be selected by clicking a grid color in area 3.
Web-safe colors (3):
Clicking one of the 70 web-safe colors will update the NEW area with the color based on the color attribute selected in area 5. In this
example, Font Color and Background are the two attributes that can be selected. Web-safe colors are a mix of hex values
00,33,66,99,CC, and FF for the RGB components. There are a total of 216 web-safe colors that are non-dithering on older PCs that
only support 256 colors. Most modern PCs support true color (16M colors) and adherence to the web-safe colors need not be a limiting
factor in color selections. The colors in the grid can be used as a starting point and the controls described in the next topic can be used
to fine tune the colors to the User's preference.
Creating colors (4):
The control buttons and text inputs located in area 4 allow colors to be mixed, or the RGB hex values entered directly to create the
desired colors. The buttons with small arrows adjust in increments of 1 and the larger arrows increment by 8, ranging from hex values
00 through FF. Like a selection from the color grid, adjustments are reflected in the NEW area based on the color attribute selected in
area 5.
Color to change (5):
There may be available selections in this area depending on the type of element being colored. The Font Color/Background and the
plot color range selector offer these selections. Other types of color selections such as Border Color or Background will not require a
selection. If different options exist in area 5, the desired option must be selected before making color adjustments.
Control buttons (6):
After making the desired color changes that appear as NEW in area 1 of the color selector, Apply is used to apply the changes and
close the selector. The Cancel button will close the selector and discard the current change, leaving the element for which the selector
was launched unchanged. The Cancel button also serves as one-step undo. For example, if a custom color was deleted by accident,
Cancel can be clicked and the custom color will be restored the next time the color selector is launched.
The Remove Custom and Update Custom buttons allow CUSTOM COLORS to be changed for future use. A custom color cell can
be selected and the desired changes made by adjusting the color(s) using the controls in area 5. While the custom color cell is still
selected, clicking Update Custom will update the cell. Custom colors can also be deleted by clicking the cell to delete, then clicking
Remove Custom. If Update Custom is clicked without a cell selected, the NEW custom color(s) will be applied to the first available
(white) cell in the custom colors area. These changes will be saved in a cookie on the PC where the changes were made. Clicking cells
in the custom area that have neither a foreground (font) color or background color will have no affect. They are empty custom color
cells available for use.
Related to the creation of custom colors, the Layout panel is very color intensive with selections for all the color elements in reports
and charts. If a user wishes to save all their color preferences, the save control near the bottom of the Layout panel provides a check
box for Set as defaults. Selecting this option when a layout is saved will establish all the color selections, along with other layout
characteristics, as the defaults for the User ID.
4
QLR Manager User’s Guide
Common Controls
Plot range colors:
The Color Selector for Plot colors functions slightly differently than the others.
Three predefined plot color sets are provided with QLR Manager. The defaults for Current is a set of darker colors which work well
when gradients are applied to bars in a bar chart. Set 1 is a set of contrasting colors using vivid colors from the web-safe pallet and Set
2 is a set of web-safe pastels. The default colors were carefully selected to provide contrast between adjacent colors. When the
selector is launched, the current set of range colors for the Plot colors element is displayed. If the colors have not been previously
modified, this will be the default set of darker, or Current colors. The Current set can be modified or one of the other color sets can be
selected and applied. All 3 sets are customizable by selecting the range color to change, picking a new color, and clicking the Change
Color button. The original QLR Manager default colors for a selected plot color set can also be restored by clicking the Default
Colors button. Care should be exercised when using this button. Any changes made to the selected plot color set are saved in a
cookie on the User's PC and will be lost when restoring the defaults.
Saving an object
QLR Manager provides the ability to save objects such as queries, layouts, macros, and menus. The "Save" or "Manage" control is
located near the bottom of each panel. While saving any of these objects, the object may be designated as shared and a description
can be applied. The "Manage Layouts" control also provides the ability to "Set as defaults" for the User ID most of the selected layout
characteristics when the layout is saved.
Name:
Objects can be saved simply by entering a Name into the "Save this Query" or "Manage (objects)" control and pressing the Save
button. The name of an object can be up to 64 characters in length and spaces within the name are allowed. If the name for the object
already exists under the User ID, the User will be asked to confirm replacement of the existing object. The number of objects that can
be saved by a User ID is dependent on the edition of QLR Manager being used. The Enterprise Edition also provides "User ID Admin"
selections which can regulate save limits by object type for individual User IDs.
Share:
If a user wishes to allow other users access to the object being saved, the object can be saved with the "Share" checkbox checked.
This object will then be displayed under the list of objects available under the Owner's User ID and can be retrieved. In the case of a
query, the User retrieving the object must still have the proper authority, such as SELECT authority, to select information from the
table(s) in a shared query.
Set as defaults:
Checking this option while saving a layout or form for the logged on User ID will save many of the options as defaults for the ID. This
would include settings such as font faces, font sizes, color selections, etc. These become the default values displayed the next time the
Layout or Design Form panels are accessed. For saved layout options, the next time a query is executed by the User ID without a
specific layout chosen on the Query panel, the default layout values will be applied to the resulting report.
The trash icon can be used to discard the saved selections for the User ID and restore the original QLR Manager defaults.
5
QLR Manager User’s Guide
Common Controls
Describe:
In most modern browsers, a detailed description can be added for the object when it is saved by clicking the icon to the right of
"Describe:", which will open the description text area. This description can be entered as plain text, or it may contain HTML tagging.
HTML entities can also be entered for special characters such as • for a "•", etc. The contents of the supplied description are
displayed by moving the mouse pointer over the i-nfo icon adjacent to the Current (object) name. These same info icons can optionally
be used for queries and macros that are items in a user menu.
Reset:
The "Manage (objects)" control provides the ability to reset the panel to its default state. On the Layout panel, a reset will restore all
the values to "Based on Query". Using Reset on other panels will remove all field entries and restore the original defaults.
Inserting a row or column
The "Insert before" feature allows a row of data to be added, or on the Layout panel, a new report column. After choosing a row or
column reference to insert a new one before, QLR Manager will automatically insert the new row or column.
Removing a row or column
Just as the Insert allows the User to add a data row or report column, the "Remove" feature will remove a row or column. The User will
be prompted to confirm the removal of the data row before the removal will occur.
6
QLR Manager User’s Guide
Connect Panel
Connect Panel
User ID
Enter a User ID that has already been established in the database to be accessed.
Password
This is the Password for the database User ID entered.
Database
Some database configurations require that a database name be provided at connect time. If the Database input field is present on the
Connect panel, then a valid entry is required.
The Systems Administrator can manually edit the qlr.ini file to change the value of "DBlogin", such as DBlogin = inventory, to preset
the database that is selected at log on.
DB server
The DB server is the server where the database resides in relation to QLR Manager. For MySQL, it is generally "localhost", meaning
that the database resides on the same server as QLR Manager.
In MySQL or PostgreSQL, it might be necessary to specify a port if the database's default port is not used. This is accomplished by
adding the port to the end of the server reference, such as localhost:3305.
For Oracle database connections, this is the TNS alias that is created in Oracle's TNSnames.ora file which is used to reference the
desired database and server.
A selection list of available servers can be added by the Systems Administrator. This is accomplished by logging into QLR Manager
using the master QLR Manager ID and creating an Input Control called "qlr_server_list". This feature is available in the Enterprise
Edition only. The set of server choices can be entered as a List of values, using the text :: value format, such as:
local::localhost,
china::9.9.14.201,
denmark::23.45.98.2
This will trigger a select list to appear below the DB server input field. The User can then choose an entry from the list, or type a
new entry into the DB server field.
Function
This selection determines what page set of functions the User wishes to access.
Queries · Layouts · Reports allows for the creation of queries and layouts, and viewing, e-mailing, or downloading the output. It also
provides a menu listing all the macros and queries previously saved by the User ID, and those that have been built into a menu and
shared by other users. The Start-up preference selection will direct the logon to the desired panel and save this preference as a
cookie on the local PC.
Macros · Menus · Forms allows for the creation of macros, menus and forms, and provides the capability of previewing the output.
User ID Admin and Tools provides a set of panels to create input controls, export QLR data for import into another QLR instance, load
data from various source file types into a database table, and set authorities for User IDs.
Note: What the User ID actually sees after logon to any of the above functions is determined by the authority granted the ID through
User ID Admin. For example, a Restricted User will not see the header tabs for Query and Layout after logon, only User Menu
and Report . If a Restricted User attempts to select the option for Macros · Menus · Forms, they will receive a message that their User
ID is not authorized. An Advanced User could have access to both page sets and all functions. These authorities are normally set by
the Administrator logging on with the master ID and password established when QLR Manager was initially installed, but can also be
delegated to other IDs through User ID Admin.
Log off
Clicking the Log off button takes the User back to the Connect panel and erases all reports from the User's current session. The
User must log on again in order the gain access to QLR Manager.
7
QLR Manager User’s Guide
User Menu
User Menu
Overview
A User Menu is a menu of queries and macros created by a user with authority to Create Menus. Extensive control is provided to the
Menu Creator in organizing the queries and macros into expandable/collapsible sections, and applying titles to the menus, sections and
individual menu items. i-nfo icons may be included for those queries and macros that were saved with a description. Menus can also be
nested within menus. A General or Advanced User may also see a selection for a special menu called *My Menu* which is created for
the logged on User ID and displays all of the queries and macros created and saved by the ID.
Default Menu
When using the Enterprise Edition of QLR Manager, it is possible to define the default menu that is displayed when a user first
accesses the User Menu panel. This is accomplished by defining the User's authority on the User ID Admin panel after logging on
to the "User ID Admin and Tools" function from the Connect panel. A User ID can be granted the authority to choose other menus
from the menu selection control that have been created and shared by other users, or they can be restricted to a single menu for
security purposes.
Running a Menu item
A menu item is executed by either clicking on the Run button or the Menu item title. When running a macro in MySQL, it is executed
under the same database that the macro was saved under when the macro was created.
*My Menu*
A special menu is created for the currently logged on User ID that contains all of the queries and macros created by that User. If the
object was saved as a "Shared" object, the text (shared) will appear after the object name. Running queries and macros from this
environment is a quick way to execute stored commands.
8
QLR Manager User’s Guide
Wizard Panel
Wizard Panel
Overview
The Wizard panel enables a user to create queries to generate reports without any knowledge of the Structured Query Language
(SQL). An SQL query is ultimately produced, but this is transparent to the User. When the Wizard is saved, the SQL query is also saved
using the same name. If the Wizard is updated and resaved, the query is also resaved.
Note: If a Query that was previously saved as a Wizard is edited and saved from the Query panel, it will be out of synch with the
Wizard. The Wizard produces queries, but the Query panel does not produce or update Wizards.
The Wizard panel is constructed to guide the User through a few basic steps that will create a report:
•
•
•
•
Select the table or tables that contain the desired data.
Specify how multiple tables are "joined" together if more than one table is selected.
Select the data columns from the tables that are to be produced in the report.
Specify the selection criteria to filter the data to generate the desired rows.
Once a table has been selected, the Wizard can be executed by clicking the Run Wizard button or the Report tab in the header. If
no columns are selected, all columns from the selected tables will be displayed.
Clicking the Show Query button at any time will display the SQL that the Wizard is generating. It is possible for the User to learn SQL
by selecting various wizard options and then viewing the SQL that is generated.
Database & Table Selections
The Database & Table Selections section allows the User to choose the tables containing the desired data to produce a report and, if
more than one table is selected, "join" the tables together.
Database/schema selection:
The first step in creating a wizard is to choose the tables that contain the desired data. In order to find these tables, it may be necessary
to look in different databases or schemas. The database or schema can be changed by selecting a different entry from the available
select lists. Once a new entry is chosen, QLR Manager will automatically update the list of available tables.
Table selection:
Tables are chosen by selecting a table name from the table list. After a table is selected, it will appear below the table selection control,
prefaced with a letter reference. The Report Column Specifications section of the Wizard will also be displayed.
Using the database/schema name when referencing a table:
After a table has been selected, a checkbox will appear that allows the User to determine whether the table name will be prefixed with
the current database/schema association. If checked, the table will be prefaced with the database/schema name such as nick.billings,
where nick is the database name and billings is the table name. When the wizard (or the query it produces) is prefaced with this
information, it will only examine the data in the specific database/schema.
When the checkbox is unchecked for a table, a dynamic reference is the result. If the billings table is unchecked in the above example
and the User is connected to the nick database, the billings table in the nick database will be examined. If the database or schema
being used is changed, for example to kadir, then the wizard/query will execute against Kadir's version of the billings table.
A mixture of checked and unchecked tables can be defined. When the checkbox is checked, the prefixing database/schema will be
visible. When the checkbox is unchecked, the prefix will disappear.
Joining tables together:
If more than one table is selected, the User must specify how the data in one table matches up (is joined) to the data in the other
table(s). This is accomplished by selecting the columns in the tables that map to one another. For example, one table may contain
purchase orders and another table may contain the line items for each purchase order. If both tables contain a data column with the
purchase order number, these two columns, one from each table, are the basis for joining them together.
QLR Manager displays the column selections for each combination of tables to allow the User to specify the join columns. The column
names must be selected from each of these lists to specify the join. If more than one column set is necessary to join the tables together,
such as purchase orders that also have version numbers, the Add Pair button can be used to add an additional pair of column select
lists.
When presenting table columns to be joined, colors are applied to indexed fields in the column select list. When multiple columns are
part of the same index, they will be given the same color. However, there is no relationship between the colors used in table "a" to the
colors used in table "b". This color coding highlights up to 10 levels of indexed field combinations in the table. Whenever possible, it is
recommended that tables be joined with indexed fields which will result in faster executing queries.
9
QLR Manager User’s Guide
Wizard Panel
The following is an example of the colors used and their association to the level of index:
There are three ways in which tables may be joined together:
1 Data rows in the left table match rows in the right table.
2 All rows in the left table and matches from the right table.
3 All rows in the right table and matches from the left table.
The second and third join types allow the User to see data where there may not be complete matches between the data in the tables.
An example may be viewing all customers by joining the customer table to the purchase order table, regardless of whether they all have
purchase orders. These are called left or right outer joins. The sequence of choosing tables for multiple table reports is important when
outer joins are used. Once a left or right outer join is specified, all of the following table joins are treated as a left or right outer joins,
depending on the type of first outer join that was found.
Report Column Specifications
The Report Column Specifications section of the Wizard allows the User to select the columns that will appear in the report output. Sort
order, grouping and selection criteria can also specified in this section.
Selecting columns:
The columns to be used in a report are selected from the Columns select list. If more than one table has been specified for use in the
Wizard, the Tables selection control is used to set the columns available for use in the Columns select list. To add a column to the
report, select the desired column, select "Add column" from the Action for Col # control, and click the Apply button. The Column
name will be added to the bottom of this section and will become the first column to be displayed in the report.
Column actions:
There are several actions that can be performed to manipulate column data in the Wizard. All the following actions require the Apply
button to be clicked after the desired selections:
Action for
What it does
Col #
Add column Adds the column selected from the Columns list to the end of the set of Column names.
Insert before Inserts the column selected from the Columns list before the column number specified by the Col # selection.
This action works with columns that have already been added to the set of Column names. Select the name of the
Move before column to be moved from the Columns select list, choose the "Move before" option along with the Col # to move the
selected column before within the set of column names.
Replace
Replaces a column in the set of Column names. Select the name of the column to be replaced from the Columns
select list, choose the "Replace" option along with the Col # of the column to be replaced.
Delete (Col #) Deletes a column from the set of Column names as specified by the Col # selection.
An Undo button is provided which will undo all the column actions in the reverse order they were applied.
Column number:
The Col # indicates the position of the column within the report.
10
QLR Manager User’s Guide
Wizard Panel
Column name:
The Column Name is the name of the column, prefaced by the table reference letter, eg. a.purchase_order. A special column is also
added to the bottom of the set of Columns selections for each table called "Custom column". A custom column can contain formulas,
such as "a.quantity * a.price" (without the quotes). Only one instance of a column name is permitted in a wizard. If an existing column
name is desired in the report output more than once, the column can be added using the "Custom column" selection and entering the
column name into the input field.
Hiding a column:
The Hide checkbox will suppress a column from appearing in the report. This is useful when a column is required as part of the data
selection criteria, but not intended to be displayed in the report output. It is also possible to hide a column using the Layout panel.
Sorting report data:
The Sorting order provides a means of sorting the report data. Up to five levels of sorting, in either ascending or descending order, can
be specified. Another quick way of sorting the report data is to check the Sort based on display order checkbox. This will sort the
report output based on the first five columns of data in ascending order.
Grouping report data:
The Grouping function provides a means of compressing the report output. The data in a column can be grouped together with the
"Group" selection or a grouping action can be applied to a column, such as a "Sum" or "count" of values. After a grouping selection is
applied to a column, all remaining columns without a Grouping function specified will be omitted from the report. To include other
desired columns, a Grouping function must be selected for those columns as well.
Selecting report data:
The selection of the desired rows of data from the database tables is accomplished by choosing a comparison operator and the data
values to filter the data based on the comparison operator. The Wizard provides two sets of filters. The data being selected must meet
all of the filter criteria in the first set or all of the criteria in the second set.
There are numerous comparison operators that can be used. Most are self evident, but some require further explanation to fully utilize
their power:
Operator
What it does
=
Not =
Equals and not equals can either have a single entry, or multiple entries, separated by commas in the filter set. When
multiple entries are provided, the value in the database table column need only match one of the filter set values to be
included in the report output.
Less than
These equate to the logical operator of <, <=, > or >=. Only a single filter set value can be supplied when these
Less or =
Greater than operators are used.
Greater or =
These operators allow for a range of data to be selected. A minimum and maximum value must be provided for the filter
Between
Not between set, separated by the keyword "and". For example, "40 and 60" could be entered as the filter set to select all rows of
data between these values. Conversely, "Not between" would select all values outside the minimum and maximum
values.
Like
Not like
Like and Not like provide a method to partially match the rows in the database table. They utilize the wildcard symbols of
"%" and "_". The % will select data rows with partial matches, regardless of the number of preceding or succeeding
characters that do not match. For example, "Like fred%" would select data rows with fredi, freddy, or frederica. The "_"
character is a single character wildcard. "Like fr_d" would select fred or frod, but not freddy or fried. Conversely, "Not
like" can be used to exclude data rows that partially match the value entered for the filter set.
Null
Not null
Null selects rows from the database table where no data exists in the column being examined. Specifying Null will select
all rows where no data is present. Not null will select all rows where data is present, regardless of its value.
SQL
For users familiar with SQL, this operator provides a method to write an SQL phrase to be inserted into the query that
the Wizard produces. For example, selection criteria of "a.quantity * b.price > 500" could be entered into filter set.
Note: Character or date values entered into the filter set fields do not need to be surrounded in quotes. QLR Manager determines
when data field types need quotes. For example, to select data where the first name is equal to fred or mary, it is entered as: fred,mary.
There is no need to surround the values in quotes, such as 'fred','mary'.
11
QLR Manager User’s Guide
Wizard Panel
Variables and input controls:
Variables and input controls provide a means of prompting for filter set input when a wizard is executed. The simplest method of
prompting for variable input is to enter something like [Year] into the filter set field, or if the server database is Microsoft SQL Server,
{Year}. QLR Manager will detect the presence of the bracketed text and create a text input to enter the year when the Wizard is
executed by clicking either the Run Wizard button or the Report tab in the header. For more information about using these
variables, please see Query variables.
With the Enterprise Edition, input controls can be created that function like query variables, but instead of being limited to a text input,
they can be created to use any of the HTML form elements such as select lists, radio buttons, check boxes, etc. Above the set of
column names is an Edit Input Controls link that will launch a new window with the available selections required to create an input
control, or retrieve and preview an existing control. The input control can be added to a filter set for a specific column in the same way
a query variable is added, eg. [name of control], or {name of control} for Microsoft SQL Server. If input controls have already been
defined for the logged on user, or other users that have shared their input controls, they can be quickly accessed for use in the wizard
by pressing the ctrl key. In supported browsers, a control selection list like the following will become visible:
Clicking Add Control with the cursor in a filter set field will insert the selected control. For more information about creating and using
these controls, please see Input controls.
If the User wishes to use an input control that was created under a different User ID, the input control name can be prefixed with the
owning User ID followed by a period. For example, [joe01.account month] will find the input control named "account month", that
belongs to User ID "joe01".
Note: Multiple query variables or input controls can be used in the same Wizard. QLR Manager will look for all instances of
[bracketed] or **variable names when the Wizard is executed and present all the specified input controls to collect the User
input required to execute the Query. Query variables used with Microsoft SQL Server must always be enclosed in curly brackets, eg.
{variable name}.
Ignore duplicate data rows:
This option provides a method to build a report that contains all unique entries. When checked, the data combinations of all the columns
used in the report will have unique entries. For example, if the Column names of first_name and last_name have been added to the
Wizard and there are two persons with the name "John Smith", only one row will appear with "John Smith" in the report output. If there
is a "Kadir Smith" and a "Kadir Horton" in the selected database tables, both rows will appear in the report. Even though the first names
are the same, the combination of the first and last name make each of them unique.
Sort based on display order:
When checked, the report output will be sorted in ascending order based on the data in the first five columns in the set of Columns
names. This is a quick way to view the report data in a sorted order without having to individually specify the Sorting order in the set of
column names.
Limit the number of report rows:
The value entered will specify the number of output rows that will be generated for the report output.
12
QLR Manager User’s Guide
Wizard Panel
Using an existing layout
The "Run with Layout" option allows the User to apply a layout to the data being selected in a wizard, formatting the report output prior
to it being displayed. The list of available layouts will be based on layouts saved under the current connection ID, or others that have
been shared by other users.
In addition to layouts created by users, there are two options that are listed under a special Owner named *QLR Manager*.
• The first is called "Based On Query", which is the default selection under most circumstances. When selected, no layout is applied
and the report format is based upon the attributes of the data selected in the wizard.
• The other option is called "Current layout". This uses the existing layout attributes as found in the Layout panel. If data in the
Layout panel does not yet exist, this choice will not be displayed.
Note: If a stored wizard is retrieved and a layout exists with the same Owner and Name, it will become the default layout used to format
the report. This provides an easy means to employ a wizard/layout naming convention that will automatically find the layout associated
with a wizard.
If the column counts between the query and layout do not agree, the report will be displayed with the default formatting and the report
title will inform the User that the column counts do not match.
13
QLR Manager User’s Guide
Query Panel
Query Panel
The Query panel is where the User creates and executes Structured Query Language (SQL) commands to manipulate information in
a database. Prior to issuing these commands, the User must Connect and select a database.
Executing queries
The Query text area supports the input of any standard Structured Query Language (SQL) command. In addition to supporting a single
command, numerous commands can be run in batch mode simply by ending each SQL command with a semi-colon (;).Queries are
executed by clicking the Run Query button or the Report tab in the header.
The Reset Query button will clear the text displayed in the Query Text area.
Comments can be added to a query as well, and are identified by either a double hyphen (--), or a pound sign (#). Comments can start
anywhere on a line, but once a comment is started on a line, the remainder of that line is treated as a comment.
Query examples:
A simple SELECT query:
select * from prices where price > 55
A single SELECT command will produce a report to which a Layout can then be applied.
A more complex batch query containing comments:
# This query updates prices
update prices set price = 27.25 where product_id='44970';
-- Notice that a semi colon ended the prior query
update prices set price = 12.44 where product_id='99123';
When non-SELECT queries are executed, the resulting report will show the query followed by its impact to the database. If a database
error is detected, it is highlighted in red, such as:
Database error # 1146. Table 'test.prices' doesn't exist
The size and number of queries that can be entered in a batch is dependent on how much information can be entered into the query
area, such as through copying and pasting. This is totally dependent on the computer's operating environment and browser being used.
The maximum amount of data that can be stored as a query is 16.77 million characters. Queries larger than this size will be truncated, if
entering this much data into the query text area is even possible. Although it is unlikely that a query would be 16 million characters in
length, entering something such as 2,000 INSERT commands as a single batch query is acceptable.
Note: The MySQL SET command can be used in batch queries. However, the life of the value assigned to the variable only applies to
the current queries present when the Run Query button is pressed. More persistent values can be set for all supported database
engines by using the user session query.
Text can be copied and pasted into the Query text area.
Batch queries:
Multiple queries, including more than one SELECT query, can be run at the same time. Although a layout cannot be applied to the
results, it is a quick way to see information from multiple tables at once. An example is:
select * from customer where custnum = 14;
select * from orders where custnum = 14;
The resulting output is shown below. The results of each select statement are separated by a horizontal rule. Directly under the rule, the
query text will appear followed by the results of the query, which can be either a report (for a SELECT query) or a database message
(for the results of an action query, such as INSERT, etc). These results cannot be formatted with a layout since multiple queries were
run at once. A layout can only be applied to the results of a single SELECT query.
14
QLR Manager User’s Guide
Query Panel
Suppressing batch query messaging:
It may be desirable at times to suppress the messages that batch queries generate. One such time is when batches contain hundreds
(or perhaps thousands) of insert queries. Another use is when preliminary processing, such as the creation of temporary tables, needs
to take place prior to a report being produced. By suppressing messaging, a report can be produced where a Layout can be created
and Report Tools can be accessed.
In order to suppress messages, and turn messaging back on, a pair of comments (-- suppress_on and -- suppress_off) can be used.
Here is an example of such an approach in a batch query:
-- here is our batch query.
-- the first step is to create a temporary table in memory to store data
-- this next line turns off message reporting
-- suppress_on
CREATE TEMPORARY TABLE paper_summary
(netid text, first_rdate date, last_rdate date,
total_count int, total_amt float, avg_cost float);
-- now insert the data into the table.
INSERT into paper_summary select netid, min(rdate), max(rdate), count(*),
sum(total_amt), sum(total_amt)/count(*)
FROM newspaper
GROUP BY netid;
-- now turn messaging back on to allow the report to be displayed.
-- suppress_off
-- here is the report query.
SELECT
a.campaign, a.newspaper, b.first_rdate, b.last_rdate, b.total_count,
Sum(a.count), max(b.avg_cost),max(b.total_amt)
FROM
calls a, paper_summary b
WHERE a.npid=b.netid AND a.campaign
GROUP BY a.campaign, a.newspaper
ORDER BY a.newspaper
=
'SQ'
The end result is that all the queries will be executed, but only the report will be displayed as though the SELECT query was run by
itself.
15
QLR Manager User’s Guide
Query Panel
Substitute message when no results:
The -- no_result keyword, followed by a message, can be used with a SELECT query prior to the select statement. When no rows or
results are produced by the query, the message will be substituted for the output in the Report panel. For example, the following will
substitute the message No results found:
-- no_result No results found
select first_name,last_name from customer where last_name = "asher"
The default message is blue, but HTML tagging can be used to customize the message as desired. The following would produce No
results found in bold red:
-- no_result <font color="#FF0000"><b>No results found</b></font>
select first_name,last_name from customer where last_name = "asher"
Using batch mode to create procedures:
The batch mode capability of the Query panel can also be used to create database engine procedures. For example, when using
MySQL version 5.0 or greater, the following procedure can be defined:
delimiter !
create procedure circle_area (in r double, out a double)
begin
set a = r * r * pi();
end
!>
delimiter ;
Since the procedure itself contains a semi-colon delimiter, a new temporary delimiter needed to be defined. When defining a new
delimiter, it must be limited to one character. A database error message associated to the delimiter definition may be generated, but the
procedure is still created.
To access the above MySQL procedure, the following could be entered into the query text area after the procedure:
call circle_area(22, @a);
select @a;
Query variables
It is possible to add prompts to queries that will accept user input variables. These are called "query variables". QLR Manager version 5
introduced a more robust method for declaring input variables in queries and wizards. The recommended method of defining a query
variable is to enclose the variable name in brackets, such as [part number].
Note: If the server database is Microsoft SQL Server, the alternate curly bracket must be used, such as {part number}.
The variable name is also used as the prompt text in the query variable input panel. To maintain backward compatibility, the older
method of defining a query variable by placing two asterisks ** in front of the variable name, such as **part_number, is still supported.
The older ** method relied on the presence of a blank space to determine the end of the query variable name. Therefore, blank spaces
could not be part of a variable name. The new [variable name] method overcomes this limitation.
The "@" character, followed by a number, is used to specify the maximum input length for the input variable. The @ should be included
as part of the variable name when a maximum length for the input value is desired and to provide additional security. See below for tips
on query security. When using the newer method of declaring a query variable enclosed in brackets, the @value should also be
included within the brackets.
When QLR Manager executes the query, it examines the query text for all unique occurrences of query variables. It then displays an
input panel for the User to enter the desired value for each variable found. For example, the following query has two query variables:
select *
from order_item
where partnum = '[part number@12]'
and qty >= [minimum_quantity@5]
16
QLR Manager User’s Guide
Query Panel
When this query is run, it will produce an input panel that looks like:
The default HTML form element for collecting user input for a query variable is a text input. QLR Manager also provides for the design
of custom input controls using the available HTML form elements which include check boxes, radio buttons, select lists and text areas.
For more information about creating these controls, please see Input Controls.
There is a special query variable named [qlr_userid] (all lower case), {qlr_userid} for MS SQL Server, or **qlr_userid if using the
older method, that substitutes the current logon ID as its value. A prompt is not produced for the User to input a value. This allows for
the creation of queries where the results are based on the User ID running the query. For example, if customers were given a logon ID
that was the same as their customer ID, the following query would limit them to seeing only their purchase order data:
select * from purchases_ord where cust_id='[qlr_userid]'
In those instances where the User ID does not map directly to the data (the User ID is not the Customer's ID), a database table can be
created that maps one value to the other. A query could be written that uses a tables join between the reference table and the table(s)
where the data resides. This would support the inclusion of the proper User ID information to achieve the desired results.
When queries of this nature are utilized in a menu, a robust reporting environment that produces customer specific information can be
created with just a few queries.
A few things to note about query variables:
• In those rare instances where the query may contain strings of text that look like a query variable, but should not be treated as a
query variable, check the Ignore query variables checkbox found under the Reset Query button. The query text will be
executed "as is".
If it is necessary to selectively ignore query variable tagging, it can be accomplished by using the --ignore_query_variables_on
and --ignore_query_variables_off comments. The following example will treat [Select_date] as a query variable and allow for the
proper interpretation of a regular expression in the query text:
SELECT *
FROM mydb.mytable
WHERE date = [Select_date]
--ignore_query_variables_on
AND name REGEXP 'sms-[0-9][0-9][0-9]'
--ignore_query_variables_off
• If the same query variable name is used more than once, only one input prompt will be generated for the User to enter data.
• The use of @5 on the end of the minimum_quantity variable specifies that the maximum input size for that variable is 5 characters.
A two digit number, such as @43 is also acceptable. When no "@" is used, the default input size is 20 characters, with no
maximum input length.
• The value of the query variable is remembered throughout the User's session. If the same query variable is encountered again, the
input field will be primed with the value that was last entered.
• There is an exact replacement of the query variable name with the input value. In the example above, the '[part_number@12]'
variable is surrounded by quotes in the query, since the partnum field is a character field. Had [part_number@12] not been
surrounded in quotes, the User would have been required to place the quotes in the input field when they provided the value for
this variable.
• When underscores ( _ ) are used in defining query variables, they will be replaced with a blank space when presented as the input
label in the query variable data entry panel.
• Clicking the Cancel button will return the User to the Query panel.
• The Reset button will reset the input value fields to blank, or if predefined input controls were used, their original defaults.
• Clicking the Continue button will run the query after performing the variable value substitution.
• Note: The User supplied value for query variables can be referenced in titles, footers and breaks in a report by simply including the
query variable name (without the @length value) in the appropriate section of the Layout panel. For example, to include the
17
QLR Manager User’s Guide
Query Panel
minimum quantity variable from above, place [minimum_quantity], or the older method of **minimum_quantity, in the
desired location within the title, footer or break. This technique can be used to reference all query variables for use in the report
layout.
When using the older method of **variable_name to declare query variables, the ** must have at least one other character
following it to be recognized as a query variable. ** entered by itself will not be treated as a query variable.
Read only queries, security, and the @ character:
Using the Enterprise Edition, it is possible to set a user's profile so they cannot edit a query (read only) prior to running it, or even limit
them to running queries from a menu without the ability to view the query being executed. If the query includes query variables, it is
advisable to use the @ feature to specify a maximum input length for added security. The following illustrates why. The query below
looks secure enough, as it prompts a customer for their customer ID and password. The password variable is even enclosed in quotes:
select * from invoices
where custid = [Customer_id]
and password = '[Password]'
Suppose the Customer's input into the Password prompt is " ' or custid > 0 or custid =' ". If this value is supplied for the query
variable, the password part of the query would end up looking like this:
and password = '' or custid > 0 or custid =''
This would have bypassed the use of the quotes around the password and would show every customer's invoice data. Assuming that
the @ entries below represent the size of the fields in the invoice table, this query would provide a higher level of security:
select * from invoices
where custid = [Customer_id@7]
and password = '[Password@8]'
This would have prevented the entry of the lengthy response of " ' or custid > 0 or custid =' ".
Obviously, for users that have edit access to a query, this would not restrict access to the data. They could merely edit the query. The
use of the @ length option can also help in improving data input by trusted users.
Query variables with input controls:
With the Enterprise Edition, input controls can be created that function like query variables, but instead of being limited to a text input,
they can be created to use any of the HTML form elements such as select lists, radio buttons, check boxes, etc. Above the query text
area is an Edit Input Controls link that will launch a new window with the available selections required to create an input control, or
retrieve and preview an existing control. The input control can be added to the query text in the same way a query variable is added,
eg. [name of control], or {name of control} for Microsoft SQL Server. If input controls have already been defined for the logged on user,
or other users have shared their input controls, they can be quickly accessed for use in the query by pressing the ctrl key. In supported
browsers, a control selection list like the following will become visible:
Clicking Add Control with the cursor in the query textarea at the desired location will insert the selected control. For more information
about creating and using these controls, please see Input controls.
If the User wishes to use an input control that was created under a different User ID, the input control name can be prefixed with the
owning User ID followed by a period. For example, [joe01.account month] will find the input control named "account month", that
belongs to User ID "joe01".
Note: Multiple query variables or input controls can be used in the same query. QLR Manager will look for all instances of
[bracketed] or **variable names when the query is executed and present all the specified input controls to collect the User input
required to execute the Query. Query variables used with Microsoft SQL Server must always be enclosed in curly brackets, eg.
{variable name}.
18
QLR Manager User’s Guide
Query Panel
The User Session query
There is a special query a user can create named "user session" (all lower case). If a query exists with the name of "user session", the
query's contents will be executed when the Run Query button is pressed prior to the query in the Query panel being executed. This
allows for the setting of database commands, such as "alter session" commands in Oracle. An example of the contents of the user
session query could be:
alter session set nls_date_format = 'DD-MON-YY HH24:MI:SS';
Since QLR Manager supports batch query processing, multiple commands can be placed into this query, separated by a semi-colon (;).
The user session query is loaded into memory when a user connects from the Connect panel. To create the user session query, it is
suggested the query be authored and run to ensure it executes properly, then saved as "user session". The User must reconnect from
the Connect panel to load the latest version of the user session query.
If errors are encountered when the user session query is executed, the error messages will be displayed at the top of the output in the
Report panel.
Using an existing layout
The "Run with Layout" option allows the User to apply a layout to the data being selected in a query, formatting the report output prior to
it being displayed. The list of available layouts will be based on layouts saved under the current connection ID, or others that have been
shared by other users.
In addition to layouts created by users, there are two options that are listed under a special Owner named *QLR Manager*.
• The first is called "Based On Query", which is the default selection under most circumstances. When selected, no layout is applied
and the report format is based upon the attributes of the data selected in the query.
• The other option is called "Current layout". This uses the existing layout attributes as found in the Layout panel. If data in the
Layout panel does not yet exist, this choice will not be displayed.
Note: If a stored query is retrieved and a layout exists with the same Owner and Name, it will become the default layout used to format
the report. This provides an easy means to employ a query/layout naming convention that will automatically find the layout associated
with a query.
If the column counts between the query and layout do not agree, the report will be displayed with the default formatting and the report
title will inform the User that the column counts do not match.
Executing SQL Server stored procedures
The Query panel can be used to execute SQL Server stored procedures. The execution is similar to a batch query. The procedure is
first initialized, values are then assigned to variables that are found within the procedure, and then finally, the procedure is executed.
The execution is accomplished by using several QLR Manager keywords:
• proc_init [procedure name]
• proc_bind [variable name] | [variable value] | [sql server variable type]
• proc_exec
For example, suppose a stored procedure called add_user was created with the following SQL Server code. In this first example, the
procedure does not contain any variables:
CREATE PROC add_user
AS
INSERT INTO myusers(first_name, last_name, age)
VALUES('jim', 'doyle', 25)
This could be executed from the Query panel by entering:
proc_init add_user;
proc_exec;
19
QLR Manager User’s Guide
Query Panel
Suppose the above procedure was changed to include variables to add different users. It would look like this:
CREATE PROC add_user
@first varchar(20),
@last varchar(20),
@age
tinyint
AS
INSERT INTO myusers(first_name, last_name, age)
VALUES(@first, @last, @age)
This could be executed from the Query panel as follows:
proc_init add_user;
proc_bind first | Nick | sqlvarchar;
proc_bind last | Zhang | sqlvarchar;
proc_bind age | 35 | sqlint2;
proc_exec;
In this second example, the procedure contains variables for the first name, last name, and the person's age. The proc_bind keyword
has been used to define the values to be assigned to each of these variables when the procedure is executed. The first argument is the
name of the variable found in the procedure. It is then followed by the pipe "|" character, which is used as a delimiter to separate each
argument. The second argument is the value to be assigned to the variable. It is then followed by the "|" delimiter as well. The final
argument is an indicator that tells SQL Server what sort of data is being passed into the procedure. Valid data type entries are:
•
•
•
•
•
•
•
SQLBIT for bit data
SQLCHAR for nchar data
SQLFLT8 for decimal, money, smallmoney, numeric or real data
SQLINT2 for int and tinyint data
SQLINT4 for datetime, smalldatetime or timestamp data
SQLVARCHAR for binary, image, nvarchar, sql_variant or varbinary data
SQLTEXT for ntext
The use of query variables is also permitted. The text in the Query panel can also be entered as follows. The person executing the
query would then be prompted to enter the values for each of the variables.
proc_init add_user;
proc_bind first | {first name} | sqlvarchar;
proc_bind last | {last name} | sqlvarchar;
proc_bind age | {age} | sqlint2;
proc_exec;
A proc may also contain a query to output information when it is finished executing. In the example below, the query select * from
myusers has been added to the end of the procedure.
CREATE
@first
@last
@age
PROC add_user
varchar(20),
varchar(20),
tinyint
AS
INSERT INTO myusers(first_name, last_name, age)
VALUES(@first, @last, @age)
select * from myusers
20
QLR Manager User’s Guide
Query Panel
When the above is executed, the contents of the query select * from myusers will be displayed in the Report panel. The output can
be formatted by applying a layout using the Run with Layout option in the Query panel. However, this is not the optimal way of
formatting the output since the Layout panel cannot be accessed to apply layout characteristics to a batch query.
The suggested method of generating a report after a procedure has been executed is to suppress the messages generated by the proc
commands and end the batch job with the query that will generate the desired report, such as:
-- suppress_on
proc_init add_user;
proc_bind first | {first name} | sqlvarchar;
proc_bind last | {last name} | sqlvarchar;
proc_bind age | {age} | sqlint2;
proc_exec;
-- suppress_off
select * from myusers;
Using this approach will execute the stored procedure and provide full control in creating a formatted report.
21
QLR Manager User’s Guide
Input Controls
Input Controls
Overview
Input Controls are designed to replace the simple text input boxes that are created when query variables are found in query text. The
available input controls are the HTML form elements such as select lists, radio buttons, check boxes, etc. Instead of a simple text input
box being displayed on the query variable input panel, a predefined input control can be used. Selection lists can also be created so
that the available values for selection are based on the selected value of another input control, such as displaying only the cities in a
selected state. These are parent/child input controls.
For those Users with authority, input controls can be created by selecting "User ID Admin and Tools" from the Connect panel when
logging on to QLR Manager. Input controls can also be created from the Query , Wizard , and Design Form panels by clicking the
Edit Input Controls link, which will launch a new window with the available selections required to create an input control, or retrieve
and preview an existing control. An input control created by a User ID will be stored under the ownership of that ID like other saved
objects in QLR Manager.
When queries, macros, or forms belonging to a particular User ID are executed and query variable(s) are referenced, QLR Manager will
attempt to locate the query variable in the following priority sequence:
1 The query variable that is prefixed by the owner such as [joe01.account month] will always be used first.
2 A query variable exists that was created and saved by the owner of the object being executed.
3 QLR Manager will then look for the referenced control under the Administrator's master ID (the ID that was established when QLR
Manager was installed).
If none of the above are found, a text input will be created for user input.
This approach allows the Administrator to create a common set of input controls that can be referenced as query variables by all their
users.
When building an input control, the Preview button can be clicked to display what the control will look like and list its available values.
This is very useful when a query is used to create the value list.
Input Controls can be used in conjunction with Report Objects for building custom web pages to collect user input.
Naming input controls
The name assigned to an input control when it is saved is important. It must be named exactly the same as the query variable that is
used in the Query, Wizard, or Form. Input control names should not contain the leading ** that identify query variables (older method),
nor the brackets [ ] or { } used with Microsoft SQL Server, that can be used to declare query variables in QLR Manager version 5. For
example, a query could be written with the text:
select * from invoices where invoice_year = [year]
If an input control with the name "year" exists, it will automatically be displayed on the query variable input panel that is presented when
the query or wizard is run.
The input control name does not have to contain the @length option that can be used in a query variable. The above query could be
written as:
select * from invoices where invoice_year = [year@4]
The @4 would limit user input to 4 characters, but would still map to an input control named "year", if it exists.
Here is an example of an input control designed to allow the User to choose a year. It has been defined as a horizontal radio button set:
Prompt text
When designing the control, the entered prompt text will be displayed to the left of the input control. HTML tagging can be used if
desired. If this field is left blank, the input control name will be omitted. In the above example, <b>Choose a year:</b> was entered as
the prompt text.
22
QLR Manager User’s Guide
Input Controls
Default values
Default values (optional) can be set by entering them in this field. In the example above, 2007 was entered as the default value. If more
than one default value is to be set, such as for check box sets or multiple select lists, the values are separated with commas. Do not
enclose the values in quotes. If different values are used for display versus what is actually used (more on this under List of values), the
default values should match the values actually used.
When the value of [all] is entered for multiple select lists or checkboxes, all of the values in the list will default to "selected".
Calendar dates:
Setting the default date for popup calendars is very flexible. The PHP function strtotime() is used for determining the value. When left
blank, the current date is the default. It is also possible to enter the following: "2002-05-25", "January 1, 2004", "-1 day", "-2 years", "+1
month", or even "-1 week -2 days". Please see the PHP documentation for more information about the strtotime() function.
When creating an input control that uses the Popup Calendar, the date separator can be selected from the Calendar date separator
list.
Control types
QLR Manager supports the creation of several different control types by choosing from the following selection list:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Calendar popup - mmddyyyy
Calendar popup - ddmmyyyy
Calendar popup - yyyymmdd
Calendar popup - mmddyy
Calendar popup - ddmmyy
Time - hh:mm 22:59
Time - hh:mm:ss 22:59:59
Check boxes - horizontal
Check boxes - vertical
Check boxes - grid
Radio buttons - horizontal
Radio buttons - vertical
Radio buttons - grid
Select list - single select
Select list - multiple select
Text area - free form input
Text area - pop up editor
Text input - all characters
Text input - numeric only
Text input - no quotes
Text input - Password
23
QLR Manager User’s Guide
Input Controls
Popup calendar:
A popup calendar is provided for use with input controls that require date selections. When creating the input control for date input, the
date format and delimiter are selected by the Author of the control.
A date format can be chosen by selecting the appropriate "Calendar popup" value from the Control type list. Regardless of the
displayed format, QLR Manager will convert the date entry to the SQL standard 'yyyy-mm-dd' format when the query is executed. The
'yyyy-mm-dd' format can be overridden in a particular QLR installation by adding an entry into the qlr_info table with the control date
keyword. This entry utilizes the PHP date() formatting function parameters. For example, for an Oracle installation a dd-Mon-yy format
may be desired, such as '10-May-08'. This is accomplised by inserting the following entry into the qlr_info table:
insert in qlr_info values ('control date','d-M-y')
The conversion to the standard SQL format can be prevented by checking the Use calendar date as is option when creating the
calendar input control. Since dates are treated as strings, the most common practice is to surround the query variable in quotes when
constructing the query, such as where trans_date = '[start date]'.
Time fields:
There are two time field formats provided by QLR Manager. The first is 22:59, which is hours and minutes. The second is 22:59:59,
which is for hours minutes and seconds. These two fields only control how the information is displayed in the Input Control text input.
Depending on the database engine being used, it may be necessary to manipulate how data is handled when using these control
types. For example, the MySQL Time field types do not support the storing of time increments smaller than a second. So if it is desired
to store tenths, or even microseconds, the time data must be stored in a decimal field, such as decimal(7,2). In order to convert the
data displayed in the Input Control to the decimal representation (1 hour, 2 minutes, and 7.43 seconds 1:02:07.43 is 3727.43
seconds), the Input Control's Evaluated formula option is used to convert the time format into the MySQL database decimal format:
$value = "time_to_sec('$value') + microsecond('$value')/1000000"; $isSQL=TRUE
The formula converts the Input Control time into the necessary MySQL query text. Notice how $isSQL=TRUE is added to the end of
the formula. This tells QLR Manager to treat the text literally as SQL. If not added, backslashes will be added to the single quotes.
24
QLR Manager User’s Guide
Input Controls
Checkboxes:
Check boxes are preferred when selecting multiple values is desired. Check box entries can be arranged to appear
vertically, horizontally or in a grid (square) pattern. When multiple entries are chosen, the values are returned as a single
string, with the chosen entries separated by commas.
When a large number of check boxes are used, a control type of "Check boxes - grid" can be selected and an input width
from 1 to 12 can be entered to specify the number of columns of check boxes (with labels). This can be useful to control the
grid matrix to accommodate short or long labels.
If more than 5 check boxes are used as an Input Control, the following controls are presented above the check boxes to aid
the User with selection from large check box groups:
[Select all] [Deselect all] [Reverse]
By default, this control set appears if there are more than 5 entries. This number can be altered by entering a parameter into
the selection limit field.
Radio buttons:
Radio buttons are used when only a single value can be selected. Radio buttons can be arranged to appear vertically,
horizontally or in a grid (square) pattern. Below is an example of a grid arrangement.
When a large number of radio buttons are used, a control type of "Radio buttons - grid" can be selected and an input width
from 1 to 12 can be entered to specify the number of columns of radio buttons (with labels). This can be useful to control the
grid matrix to accommodate short or long labels.
Single select list:
A Single select list provides a drop down list of values, allowing only one entry to be chosen. This is the most common form
of a select list. The selection of the control type when creating the input control is an example of a single select list.
Multiple select list:
A multiple select list provides a drop down list of values, allowing more than one entry to be chosen. Multiple entries can be
chosen by holding down the Control (Ctrl) key and clicking on each item. The example below allows for multiple entries to be
chosen, and the number of rows to be displayed in the select list has been set to 4. Notice how the text "[Ctrl+click to select
multiple entries] [Shift+click selects a range of entries]" is added to the bottom of the multiple select control. Lists with 6 or
more selections will automatically receive the [Select all] [Deselect all] [Reverse] controls.
25
QLR Manager User’s Guide
Input Controls
Text areas:
Text areas can be used for the entering of large amounts of text, perhaps used in an INSERT query. The size of the area is
controlled by the "Text input width" for the width, and the "Text area height or select list rows" determines the height. The
following is an example of "Text input size " = 40 and "Text area height or select list rows" = 4:
Text area pop-up editor:
Another text area control is the pop-up editor. When the icon to the right of the text area is clicked, a new window is opened allowing
the User to edit the text in a large text area. This permits the control itself to be defined as a small area. The following is an example of
Text input width value of 20 and Text area or select list height value of 2.
Text input - all characters:
The Text Input control is very similar to what is automatically created for a query variable. The advantage of creating an input control is
that Prompt text and default values can be defined. The length of the input can be limited by setting the "Text input width" value. This is
an example of a text input with a maximum length of 6:
Text input - numeric only:
This control is the same as the "Text input - all characters" except that it limits the User to entering numeric input. This can be tested in
the example below:
Text input – no quotes:
The purpose of this input control is to prevent "SQL injection" attacks that are accomplished by "short circuiting" the intended use of
quotes for character value input. Suppose the following query exists with an input control called password:
select * from user where userid = '[userid]'
If a user was to enter ' or '1'='1, the query would be rendered as
select * from user where userid = '' or '1'='1'
The beginning and ending quotes surrounding the password input variable have been effectively turned into part of an SQL statement,
as opposed to surrounding a legitimate password value with quotes. The resulting query would display all rows in the user table, as
opposed to only those where the User has entered their password. When quotes are blocked from being entering into an input control,
this type of attack cannot be used.
26
QLR Manager User’s Guide
Input Controls
Text input - password:
This control allows for passwords to be entered, without the characters being displayed. As with the "Text input - no quotes" control
(see above), single quotes are not allowed to be entered into this control type to prevent SQL injection attacks.
Display order
The order in which input controls appear in the query variable data entry page is based upon the size and type of input control.
However, the Display order allows the User to override this automatic calculation for a specific input control. If the User wishes to
move an input control to the top of the query variable page, this can be accomplished by entering 1 as the display order. A value
between 1 and 999 can be used to sort controls to the top of the page. To move a control to the end of the query variable page, a
Display order of greater than 1000, such as 1001 and 1002, can be entered. All controls that are not given a Display order value will
remain in their original position as calculated based on their size and type. Since the input controls that appear on the query variable
page depend upon which controls are used within a specific query or macro, the desired order for one page may not be what is desired
for another page. In this case, a new input control can be created and saved with the same characteristics, but using a different
Display order.
Control alignment
This selection provides the ability to specify the alignment of an input control. The default alignment is "Left", but there may be some
instances where it may be desirable to align the Input Control to the "Center" or "Right". These selections only affect the Input Control,
not its associated prompt text. Although there is no separate control to specify the alignment of the Prompt text, this is possible by
entering HTML tagging into the Prompt text field. For example:
<div style="text-align:center;width:100%">Prompt text</div>
<div style="text-align:right;width:100%">Prompt text</div>
Text area or select list height
This data element controls the height for select lists and text areas. Generally, a single value select list is set to 1. Multiple select lists
and text areas will generally have a value of greater than 1.
Text input width
The text input width defines the width of both text input boxes and text areas. In addition, it sets the maximum number of characters
that can be entered into a text input box.
In those instances where a large number of check boxes or radio buttons are used, a control type of "Check boxes - grid" or "Radio
buttons - grid" can be selected with an input width to specify the number of columns of controls (with labels) to be presented. A value of
1 to 12 can be entered to override the default grid matrix to accommodate short or long labels.
27
QLR Manager User’s Guide
Input Controls
Regular expression validation
Regular expressions used with QLR Manager input controls only apply to text inputs and text areas. The JavaScript regular expression
syntax used in QLR Manager is very similar to Perl-style regular expressions. The syntax consists of /pattern/flags[,replacement]. All
that is required is a /pattern/ to perform a match against text input. For example, if the User input must begin with a #, a simple pattern
match like /^#/ can be used to validate that the # exists in the first position. When specifying a pattern match without the optional
replacement value, a regular expression message must be provided to alert the User of the failed match so the input can be corrected.
By using a [,replacement] value, the User input can be corrected automatically.
A regular expression like the following can be used to insert the # in the first position, if it doesn't already exist:
/^([^#])(.*)$/, "#$1$2"
Note: When using the replacement value, the regular expression message is optional.
There are flags that can be used with the pattern match. The most common are i and g. The i will instruct the pattern match to ignore
case and the g will perform a global match and search the whole string rather than stopping on the first occurrence. These flags and
others can be used in combination.
JavaScript functions can also be entered as a [,replacement] value. The following regular expression will match all characters A-Z and
use the JavaScript toLowerCase() method to change all the upper case characters to lower case:
/[A-Z]/g, function ($1) { return $1.toLowerCase() }
Regular expressions can be very complex. This information is not intended to be a tutorial about the use of regular expressions, but
merely a brief overview describing what is possible. Regular expressions can be a useful feature when used in conjunction with QLR
Manager Input Controls to validate user input, or replace specific values in the input. An abundance of information can be found on the
Internet about Regular Expressions by searching for "javascript regular expressions". A good library of regular expressions can be
found at: http://tools.netshiftmedia.com/regexlibrary/feed.php.
Regular expression message
The regular expression message is a JavaScript alert that will be triggered under two conditions when leaving the field containing a
regular expression validation:
1 A simple regular expression match is used and the User input fails the validation. The regular expression message is required in
this instance. The User will not be able to leave the input field without correcting the validation failure and must be informed what
condition is causing the failure.
2 A [,replacement] value is used in the regular expression. In this case, the regular expression message is optional, but may be
useful to alert the User to what has been replaced.
Character or Selection limit
The character or selection limit field accepts 3 optional values, separated by commas. The following is an explanation of each of these
values and the function they perform.
The character limit applies to text inputs and text areas and can be entered as a single value, i.e. 100, 10, etc. When used with a text
area, the character limit will be displayed above as Character limit: 100. The selection limit can be set for multi-select lists and
checkbox groups. For these types of controls, Selection limit: 10 is displayed above the control. As characters are typed into the text
area or selections clicked for a multi-select list or checkbox group, the value is decremented to display the remaining available
characters or selections.
The minimum character count or selection value can also be set by entering a second parameter. An entry of 10,2 indicates that a
maximum of 10 selections are permitted and a minimum of 2 selections are required.
A third parameter can be entered which determines when the selection controls are presented, which will override the default of 5:
[Select all] [Deselect all] [Reverse]
An entry of 10,2,1 indicates that these controls should be displayed when there is more than 1 entry.
28
QLR Manager User’s Guide
Input Controls
Surround selection with quotes
This selection determines whether the returned value will be surrounded by single quotes, such that Spain will be returned as 'Spain'.
It is necessary to use this feature for controls that can return multiple values that each need to be surrounded in quotes. An example
of this is for use in a query that uses an IN clause:
select * from customer where last_name in ([lastName])
If the lastName control is a checkbox set that allows for multiple last names to be selected, each of these last names must be
surrounded in quotes for the query to execute as expected, such that Smith,Jones is returned as 'Smith','Jones'.
Adding empty selections
There may be times when it is desired that a control, such as a radio button set or a select list, provides the capability to not select
any items. The nature of these types of controls prevents that from happening. By adding an empty selection value to the list, the
User can select the empty value. Here is an example of a radio button set, in a grid configuration, with an empty value added. Notice
that the empty value is labeled as "None" for radio buttons. For a select list, it will be a blank entry at the top of the list.
Always refresh list values
When this is checked, the list of values available to the User is updated every time the query variable input page is displayed. This is
most useful when lists are comprised of actively changing data, such as customer lists or invoices and the list source is the query
text. When not checked, the list is updated the first time the User accesses that particular input control during their browser session.
Evaluated formula
The Evaluated formula field allows PHP code to be entered that will manipulate the value selected by the input control. This provides
greater flexibility when using input controls. An example might be the use of a field to enter a date value, but if no date is entered, then
the query does not even contain selection criteria for a date:
if($value!='') $value = "start_date = '".$value."'"; else $value = '';
The input control used in the query might look like this:
SELECT custnum, first_name, order_date
FROM orders
WHERE [getStartDate]
If a date value of 2007-11-19 is provided, the input control returns start_date='2007-11-19'. If no date is provided, the input control
returns a blank. Notice that the value that is manipulated in PHP is $value. Also remember that if Surround selection with quotes is
checked, the value will have single quotes around it.
29
QLR Manager User’s Guide
Input Controls
Parent/Child select lists
Sometimes it may be desirable to have the choices available in one select list (child) based on the selected value of another select list
(parent). An example could be when selecting a customer from the customer select list, only the purchase orders for that customer are
displayed in the purchase order list. This is accomplished by selecting the parent control name from the Parent control list while
creating the child control. For this example, the customer input control name would be selected from the Parent control list while
creating the purchase order select list control. The general rules are:
•
•
•
•
•
The parent control must be a single select list.
The child control can be either a single select list or a multiple select list.
A parent control cannot have its own parent control defined.
Multiple child controls can reference the same parent control.
The parent control does not have to be referenced in the query as a query variable. It will automatically be added due to the
presence of the child control.
In addition, the data in the child input control must be mapped to the insert value of the data in the parent input control. This is
accomplished by specifying three data elements for each desired child entry: the display value, insert value, and the parent's insert
value. When a List of values is used, the entries might look like the following if the months of the year are mapped to each of the four
quarters:
Jan::1::1,Feb::2::1,Mar::3::1,Apr::4::2,May::5::2,Jun::6::2,
Jul::7::3,Aug::8::3,Sep::9::3,Oct::10::4,Nov::11::4,Dec::12::4
For the month of April, "Apr" is the displayed value and if selected, the value of 4 (month number) would be inserted as the query
variable value. The parent's insert value of 2 (quarter number) is used to associate months 4 through 6 with the parent list selection.
Only the entries for Apr, May and Jun are displayed when the "2nd Quarter" is selected from the "Choose the quarter" list.
If a query is used as the source, the query must select 3 fields. The sequence being the display value, insert value, and the related
parent's insert value:
select purch_ord_num,purch_ord_num,cust_num from purchase_orders order by 3,1
In this example, the purchase order number is both the displayed and insert value. The customer number maps to the customer number
found in the customer input control, which has been specified as the Parent control. If an input control with a parent control is used in a
query, the parent control does not need to be specified in the query. QLR Manager will automatically add it to the query variable input
panel immediately above its associated child control.
Searching for multiple entries within the same field
There may be instances where the User may need to search for multiple entries within the same field. An example of this, is the MySQL
"SET" field type is used to store information. A SET field contains multiple values separated by commas. An example of this would be a
field in a table, related to pizza orders, called "toppings". It might be that this field contains the possible toppings for a pizza order. Valid
data elements for this field might be any combination of "onions, sausage, pepperoni, olives or mushrooms".
Suppose the User wishes to find all pizzas that have meat on them. You would need to find entries that contained either sausage or
pepperoni. An input control can be defined to do this by specifying a Multiple entries, same field value of Contains and defining the
Multiple entry field name as toppings.
When the input control generates it's output, it will be (toppings LIKE '%sausage%' OR toppings LIKE '%pepperoni%'). Notice how
the field reference is part of the generated value. Since this is the case, there is no need to specify the table column of toppings in the
query text. Assuming that the Input control is named "getToppings", the query might look like this:
select * from pizza_orders where [getToppings]
When the query variable is replaced, the query text will be:
select * from pizza_orders where (toppings LIKE '%sausage%' OR toppings LIKE '%pepperoni%')
If the User wishes to find the "Meat Lovers" pizzas that contained both sausage and pepperoni, then the Contains all comparison
option can be used. The resulting query would be
select * from pizza_orders where (toppings LIKE '%sausage%' AND toppings LIKE '%pepperoni%')
If there is a chance that no toppings would be selected, this would cause a problem because the resulting query text would be:
30
QLR Manager User’s Guide
Input Controls
select * from pizza_orders where
The Input Control's Evaluated formula field can be utilized to solve this problem by entering a formula of:
if ($value!='') $value = 'where '.$value
and omitting the "where" keyword from the query text:
select * from pizza_orders [getToppings]
This will then conditionally add the where clause to the query only when at least one topping is selected. It is most likely that the use
of the Multiple entry option is used when the input control type is a checkbox set or a multiple selection list. In order for this option to
work, values for both Multiple entries, same field and Multiple entry field name must be specified.
List source
There are two ways to populate check box, radio button and select list input controls. The values can be provided from a static List of
values or by executing a query to build a dynamic list of values. The "List source" indicates which source to utilize. Entries for both a
List of values and a query can be present at the same time. It is the List source selection that determines which one will be used.
List of values
There are two ways of creating a list of values that will comprise the User's selection options. One is to enter the values into the "List
of values" text area. The other is by authoring a query to select the values.
Values are entered into the List of values text area, separated by a comma. To create a selection list of valid years, the data can be
entered as:
2004,2005,2006,2007
or as:
2004,
2005,
2006,
2007
It is also possible to enter a text/value pair for each entry, such that the text is displayed in the input control and the value is the actual
value submitted for the selection. The displayed text and the value are separated with a double colon :: to make the delineation. For
example, to build a list that shows the names of the month and uses a month number as the selected value, enter a List of values like
the following:
January::1,
February::2,
March::3,
April::4
This can be used to produce a horizontal radio button set:
Query for list of values
There are two ways of creating a list of values that will comprise the User's selection options. One is to enter the values into the List of
values area and the other is by creating a query to select the values. To create a list of values using a query, a query must be
authored that will select a list of values intended to be offered as selections. It is advisable to test the query by clicking the provided
Preview button and to fully qualify table name(s) by preceding it with a database/schema reference where applicable.
Note: The following examples use standard brackets [ ] to identify query variables. If the server database is Microsoft SQL server,
curly brackets { } must be used instead.
A query may look like:
select custNum from mydb.customer where region = 'southwest' order by 1
This produces a list of customer numbers that could be used to create a single select list control.
As is the case with the "List of values", text/value pairs can be defined. The first column selected is used as the displayed text and the
second column selected is treated as the value to be submitted for the selection.
select concat(last_name,', ',first_name),custNum from mydb.customer
31
QLR Manager User’s Guide
Input Controls
order by 1
This example creates a list that displays the last and first names concatenated together (MySQL concatenation syntax shown here),
with the substituted value being the actual customer number.
It is also possible to use the special QLR Manager query variable called [qlr_userid] to build lists specific to the logged on User ID:
select invoiceNum from mydb.invoice where custNum = '[qlr_userid]' order by 1
The database/schema name can also be referenced by using [qlr_userdb]. This will substitute the value of the current database or
schema connection:
select invoiceNum from [qlr_userdb].invoice where custNum = 198563 order by 1
It is important consider the implications of having select authority on the table(s) that are being referenced when building a dynamic
list of values. When an input control is owned by the QLR master ID, the master ID connects to the database to execute the query.
Therefore, the master ID has to have select authority on the applicable table(s).
If the input control is owned by an individual user, obviously the User needs select authority on the applicable table(s) in order to build
the list of values. What may not be obvious is that when sharing a query for execution and it has an input control owned by the author
of the query, the person executing the shared query also needs select access to the table(s) that are part of the input control. If an
input control is to be widely used, it is probably easiest to create it under the QLR master ID and then grant the appropriate select
authority to the master ID.
Parent/Child queries
It is possible to reference input controls within the query text of an input control. Doing so allows for the creation of parent / child
controls. For example, suppose there is a you have a control to select a given part number. The query text would be:
select partnum from inventory order by 1
Suppose this produces a list of thousands of part numbers. You may not find it to be a very usable control listing so many part
numbers. Assuming that your inventory data has a "category" related to each part number, you could modify the query to:
select partnum from inventory where category='[category]' order by 1
You would then create an input control called "category" that had query text of
select distinct category from inventory order by 1
When QLR Manager executes the query to display the query variable input panel, it will first prompt the User to select a category.
Then a second query variable page will appear and ask the user to select a partnum that falls within that category. This is similar to
the parent / child controls that are described above. However, there are several differences. The first is that parent / child controls that
appear on the same input page work well with small number of children, perhaps a hundred or so. When there are thousands of
entries, it is probably best to use the approach described here. Secondly, the parent / child controls that appear on the same page are
limited to a single parent / child relationship. Using this method allows for an unlimited number of drill down tiers, so you can have
child / parent / grandparent, etc. relationships to narrow down the data being presented to the User. Lastly, using this approach does
not limit you to a "select list" input control type.
32
QLR Manager User’s Guide
Layout Panel
Layout Panel
The Layout panel is used to modify the appearance of the report data generated by a query. It provides extensive control over the
output format and allows for the creation of charts and graphs. HTML tagging can be imbedded into many of the text inputs and text
areas, such as the title, footers, break text, etc., to further enhance the report's appearance. The following expandable/collapsible
sections correspond to the sections found in the Layout panel and describe their function and use.
Titles & Footers
Report title
The Report title is text that appears on the top of each page of the report. If the report title text is left blank, then no report title cell will
appear on the report. The report title characteristics can be manipulated with the various formatting options that appear in the Report
title section. The report title can contain either plain text or HTML tagging. If text such as <b>My <u>Report</u> Title</b> is entered, it
will produce a title of My Report Title.
In addition to text and HTML, there are special replacement character references that allow the User to specify page numbering, data
from within the report body, and numerous options for formatting the current date and time. More information can be found in the topic:
referencing column information.
It is also possible to split the title text to appear in 3 segments as Left, Center, and Right justified. This is accomplished by using "||" to
split the text. If Fred||Summary Report||Sales Dept is entered, then Fred will appear as left justified, Summary Report will appear in
the center, and Sales Dept will be right justified in the title cell. This technique works for footer text as well.
Bold, Underline and Italic text formatting can be applied to the title cell by checking the appropriate checkboxes. Bold is checked as
the default for the Report title.
Column headings
General formatting, such as the font type, size, color, and background color can be applied to all of the Column headings as a single
group. This area also contains a text input with a default value of "Pivoted<br />Columns" to allow for the input of a column heading
when a "Pivot" column is selected in the Report Columns section of the Layout panel. If the User wishes to change the appearance of
individual column headings, this can also be accomplished by embedding HTML tags into the specific columns as found in the Report
Columns section.
Bold, Underline and Italic text formatting can be applied to all the column headings by checking the appropriate checkboxes.
Report footer
The Report footer is text that appears on the bottom of each page of the report. If the report footer text is left blank, then no report footer
cell will appear at the bottom of the report pages. The report footer characteristics can be manipulated with the various formatting
options that appear in the Report footer section.
The same formatting options and characteristics available for the title can also be applied to the footer. Please see the Report title
section above for more information. A common use for footer text is the entry of "Page &PN" to reference the page number.
Bold, Underline and Italic text formatting can be applied to the footer cell by checking the appropriate checkboxes.
Report Body
Font faces, colors and other attributes can be set for all the data cells in a report using the controls in the Report Body section.
Changing the alignment of text in specific columns can be accomplished using the alignment controls in the Report Columns section.
The report body controls also provide many other options for controlling the appearance of the data cells in the report.
Outer border size:
The Outer border setting allows the thickness of the borders to be specified that will be displayed around the report pages. The
selections range from 0 to 10 pixels. Please note that Netscape Navigator 4.x is unable to center the report pages when a border size
of 0 is set. The color of the border can be set using the "Outer border color" control.
Inner border size:
The Inner border setting determines how thick the lines should be between data cells in a report. The selections range from 0 to 10
pixels. The color of these lines can be set using the "Inner border color" control.
33
QLR Manager User’s Guide
Layout Panel
Section border size:
The Section border size determines the line thickness that will delineate the report title and column headings from the report data. For
table and pivot layouts, the column groupings will also be separated from the data with the selected section border size. The color of
these lines is determined by the "Inner border color" setting.
Inner border use:
The Inner border use controls whether the vertical, horizontal or both vertical and horizontal lines are displayed. To eliminate the display
of all inner border lines, the Inner border size can be set to 0.
Max displayed rows:
This value determines how many rows will be produced per "page set". A page set is the total number of rows of data to be displayed
when a query is executed. For example, if a value of 500 is used in conjunction with a Rows per page value of 50, 10 pages of report
output will be displayed at one time. When the number of rows produced by the query exceeds the Max displayed rows value, the User
must click the appropriate navigation buttons (First, Back, More, Last) found above the report to move between page sets. A larger
number will show more data, but it takes longer to display results, especially if a user is connected with a modem.
The number of rows displayed will not always be exactly equal to this setting, as subtotaling data will add additional rows to reports.
QLR Manager will always complete the current page with data. If you have a report row setting of 500 and the 500th row appears in the
middle of the page, QLR Manager will fill up the final page with rows of data, if there is more data available.
Hint: To print a large report, or generate a PDF using a PDF writer such as Adobe Acrobat or CutePDF, this value can be set to a
number of rows greater than the total rows expected to be produced by the query. If the layout is saved as the same name as the query
or wizard, it will be automatically be applied when the query, wizard or menu item is executed.
Rows per page:
This determines how many rows will be produced per page. If 0 is entered, no pagination is applied and will result in one continuous
report page with one set of column headings, and one title or footer if applied. There are two other limiting factors that determine how
large of a continuous report page can be created. These are the Max displayed rows above and Maximum output file size settings
applied when QLR Manager was installed. These values default to 500 rows and 5 MB.
Currency symbol:
This option sets the currency symbol that will be used when the $1,234.56 or $1.234,56 formatting options are chosen in the report
column Format option. The $, £ or ¥ symbols can be used, or up to 4 text characters can be entered. If the User's keyboard cannot
produce the £ or ¥ symbols, the characters can be copied and pasted from this help text.
Currency symbol location:
The Currency symbol location determines whether the currency symbol should appear "Before" or "After" the values when a currency
formatting option is selected.
Cell padding:
Cell padding refers to the amount of space between the data in a report cell and the border of the cell. The selections range from 0 to
10 pixels. This setting is applied to all cells in the report, including the title, column headings and the footer.
Date separator:
The Date separator allows the User to specify which character will be used when displaying dates. This will work with all date formatting
options that contain a "/", and the "Date Time" option. Dates such as 2001/31/12 can be displayed as 2001.31.12 if "." is chosen as the
separator. It also controls the appearance of the &DT date reference options that can be used in titles, footers and break text.
Pages across:
This selection provides a means to layout multiple report tables horizontally. This can be useful if each report has only a few columns of
data resulting in a narrow table. The selected number of reports can be generated from left to right and make more efficient use of the
browser window.
Print black & white:
With this option checked, a printed report will be produced with black text and table borders, and with the cell background colors
removed. This allows for the creation of report output that is optimized for viewing and will save colored ink when printing. It does not
affect the printing of charts which are images and will print as they are displayed.
34
QLR Manager User’s Guide
Layout Panel
Ignore wrapped line count:
There may be instances where Word wrap may be selected for a specific data column under Format or use in the Report Columns
section. This will cause long lines of data to wrap within the confines of the specified column width. If the number of Rows per page
have been defined to provide page breaks for printing, the additional rows created for wrapped data are not included in the row count
and will likely cause printed page overruns. Selecting Adjust for wrapped data will attempt to estimate the additional rows created by the
Word wrapped data to produce uniform sized pages for printing.
Note: This adjustment is only an approximation. There are many variables such as font metrics and other factors that determine how
the data will wrap in a report column within the client’s browser.
Alternate row coloring:
Alternate row coloring produces a "striped" report appearance. When checked, every other row is colored with the Report Body "Data
row colors". The alternate rows are colored white.
Negative numbers in red:
When checked, all negative numbers in the body of the report will be displayed in red.
Show HTML tags:
Reports that contain HTML tags within the data will display with the tagging rendered by the browser as the default. For example, if a
field contains <u>My Information</u>, it will be displayed in the report as My Information. If "Show HTML tags" is checked, it will instead
be displayed as <u>My Information</u>.
Auto arrange columns:
When checked, the columns in a Standard report format are automatically arranged so that the Break columns appear on the left,
followed by the Group columns. All columns that contain other actions, such as Sum, appear on the right side of the report. This has no
impact on Table or Pivot Layouts.
Ignore Table/Pivot sort:
When Table and Pivot Layouts are created, the entries that are spread across the page for these two report formats are sorted
alphabetically. If the ignore option is checked, and the Format type of the chosen Table or Pivot column is "General", then the order of
the data being spread across the page will be the order of the data as found in the report rows.
Fill balance of page with empty rows:
When Fill page with rows is set to "Yes", QLR Manager will fill the balance of each page with as many rows necessary to meet the
number of rows set in the Rows per page option. This will create uniform sized pages throughout a report. If Alternate row coloring is
checked, the filler rows will alternate between white and the specified "Data row colors". The color of the filler rows can be modified
using the "Color" or "White" selections.
35
QLR Manager User’s Guide
Layout Panel
Report Breaks
Report Breaks allow the User to define groupings within the report to either visually separate data, or for subtotaling, counting, and
other Actions. Breaks are triggered when the data value in the break column changes from one row to the next. Proper use of breaks is
dependent upon how the query sorted the report data.
Up to 5 levels of breaks can be defined and they are nested to provide a "break within a break". More than one column of data can also
be used to define a single break. An example might be report columns for both "State" and "City" set as "Break1".
Bold, Underline and Italic text formatting can be applied to break text by checking the appropriate checkboxes. Bold is checked as the
default for report breaks. Font and background colors can also be applied by launching the appropriate color selector. The break text
can contain either plain text or HTML tagging.
Break text
Text before break:
The leading break text is the text that will appear prior to the start of a new break section. The space allotted to this text spans the width
of the report. When referencing report data, be sure to use the &amp;n reference (next row of data) instead of the &c reference. For
leading break text it is usually the next row of data that is most relevant.
Text at the break:
The trailing break text is the text that will appear on the corresponding break line that is added into the report. The amount of column
space that is allocated to the break text is dependent upon the first column of data that is encountered that has an activity that the break
needs to display. For example, if the User is using the Sum action in the 4th column, the break text will span the first 3 columns of the
report. The 4th column will be used to display the sum amount.
If there are no actions for a break to act upon, such as "Sum", etc., the break text will still appear in the report. If the break text is blank,
the break row will not be displayed. This allows for data outlining without empty report rows being added to the report.
If it is desired to exclude the text at the break from displaying, but still include the spacing at the break, enter the tag of <omit> as the
break text.
Custom Text at the break:
Custom break text can be entered, allowing for great flexibility in report creation. A classic example is to "stack" several break level
items on top of each other, such as adding taxes to the bottom of an invoice.
The following is an example of how to modify a typical report, with data in separate columns, into a report that has stacked data at the
break. Suppose the original report looks as follows:
A simple example of adding plain text to the break on a separate line that spans across the entire report by changing the break text:
From: Total for &c4
Total for &c4||<center>End of invoice</center>
To:
Notice the use of "||" as the indicator that custom text follows the normal break text input. An additional row in the report is created that
36
QLR Manager User’s Guide
Layout Panel
spans the width of the report:
The steps involved to "stack" the tax information directly below the purchase price information:
1 Hide the tax column by setting the the Column width to 0 in the Report Columns section of the Layout.
2 The "Break #1:" Text at the Break is entered as: Total before Tax
||<td class="break" colspan="2">Plus Sales Tax</td>
<td class="bdata6">$eval(number_format(&b8~,2))</td></tr>
<tr><td class="break" colspan="2">Total with Tax</td>
<td class="bdata6">$eval(number_format(&b7~+&b8~,2))</td>
Some important notes regarding this example:
• Total before Tax
This is typical break text that starts the break section.
• ||<td class="break" colspan="2">Plus Sales Tax</td>
The "||" signifies the start of the custom text. The class of "break" is always used for the leading text, and the colspan of 2 equals
the number of columns that the data needs to span in this instance. QLR automatically adds an HTML tag to start of the custom text
if the <tr> tag is not provided.
<td
class="bdata6">
•
The class entry of "bdata6" refers to break data for the 7th column in the report (the first column of the report is column number 0).
The reason that it does appear as the 7th column is because several columns have been hidden.
• $eval(number_format(&b8~,2)) </td></tr>
The text that is displayed is a dollar sign ($) followed by an embedded evaluated formula, which takes the break data for column 8
(the column that contains the sales tax data) and formats it to have 2 decimal places. The "~" that follows the &b8 indicates to use
the raw unformatted data from column 8 in the evaluated formula. Finally, there is the HTML </tr> tag to close this table row.
<tr><td
class="break" colspan="2">Total with Tax</td>
•
As with the previous table cell that contained text, the class of "break" is used for the text that appears to the left of the break level
formulas. The colspan of 2 represents the number of columns that the data must span in this instance.
• <td class="bdata6">$eval(number_format(&b7~+&b8~,2)) </td>
The text that is displayed is a dollar sign ($) followed by an embedded evaluated formula, which sums the break data for columns 7
and 8, and formats the data to have 2 decimal places. The "~" that follows &b7 and &b8 indicates to use the raw unformatted data
from those columns in the evaluated formula. QLR Manager will automatically add a closing table row tag </tr> if none is
provided.
37
QLR Manager User’s Guide
Layout Panel
Referencing column data and other information in a Layout:
The Layout panel provides the User with the capability of including column data in a report's Break text fields, as well as the Report
title and Report footer. For example, suppose the report is a list of employees that is sorted by the state in which they are employed. A
break is desired to sum the "Total for state XX", with XX being the state on which the break is based. This can be accomplished by
entering the following into the Break #1 "Text at the break":
Total for state &C1
This triggers QLR manager to replace &C1 with the data in the CURRENT record at the time of the break, with report column number
1's data. If column number 1 in the report is the state, and the value is "NY" at the time of the break, this would result in:
Total for state NY
If it is desired to reference the data in the NEXT record coming up in the report, &N1 would reference the data from the first column in
the next record. This is useful when it is desired to reference information in the Report title.
Multiple references can be used in the text, such as "State &C1", "City &C4 employee count" is acceptable.
Either upper case or lower case C's and N's can be used as a reference.
The current break level data can also be referenced using &BXX or &bxx. It assumes that an "Action", such as Sum, Count, etc., has
been performed on the referenced column to produce break level information. An example of such usage might be to count the number
of items (for example in column 4) in a break section and then the "Text at the break" for "Break #1" might be:
Number of entries &b4
This approach also works if column 4 had been hidden by setting the display width to zero. By setting the display width = 0, the column
"Action" can be set = Count. An alternate way of hiding a column is with the Hide Action. But using this approach would not allow for the
Count action to have been applied to the column.
Note: The use of reference values in Break text can be used in conjunction with the BreakxH (hidden break action) or the Hide Action
to display information in a report break, but not take up space as a column in the report. More information about Actions is available in
the Report Columns section.
In addition to referencing column data, query variables can also be referenced. Suppose a query contains a query variable called
{customer_number} used with MS SQL Server only, [customer_number] for other supported databases, or the older method of
**customer_number. The User supplied value for this variable can be referenced in the report title by adding the text
{customer_number} for MS SQL Server or [customer_number] into the title at the desired location. The value provided for this
variable will be substituted for the variable name. Note that the variable name must be enclosed in brackets or start with ** (older
method) as found in the query text or wizard filter set. If the @ length parameter is used in the query variable, it is not used when
referencing the query variable name in the Layout.
38
QLR Manager User’s Guide
Layout Panel
Embedding calculations in headers, footers and breaks:
When the string eval([formula]) is added to header, footer or break text, its content is evaluated as a formula. The column referencing
technique described above can be used in the formula. PHP code can also be used in the formula in the same manner that the
Evaluated formulas work. Some examples:
Calculations with Replacement Reference Values
Formula
Description
eval(10/4)
Returns 2.5.
EVAL(&b7/&b9)
Returns column 7 divided by column 9. Notice how EVAL can be in upper (or even
mixed) case.
This makes a conditional assignment to $value ($value must be used as the
eval(if(&b4>10) $value='Good'; else $value='Bad') variable name) and displays either Good or Bad, depending on the value of column
4's break data.
eval(number_format(&b6 * 3.1415,2))
Returns the result formatted to 2 decimal places.
If the parenthesis () do not pair up properly in the formula, a message "!_paren_error" will be displayed in the replacement text.
Page numbering in titles, footers and breaks:
Page numbering can be added (usually in the footer), by including &pn or &PN in the appropriate layout input field.
Dates in titles, footers and breaks:
The current server date or time can be added by using &DTx or &dtx, where the "x" represents a specific type of date formatting. These
format options can be found in the Date formatting section.
Summary of Replacement Reference Values
Value
Example
Description
&Cx or &cx
&C1
Replace with data value from column 1 from the current data row.
&Nx or &nx
&N1
Replace with data value from column 1 from the next data row.
&Bx or &bx
&B1
Replace with data value from column 1 with the break level data row.
&PN or &pn
&PN
Replace with current page number.
&DTx or &dtx
&DT3
Replace with a Date or Time format as found in the Date formatting section.
[query variable]
[year]
References the value given to the "year" input variable when the query was executed.
{query variable}
{year}
Same as above, but curly brackets are required for use with Microsoft SQL Server.
Final text:
The Final text is text printed at the end of the report. It is only printed when an Action is present to create a final row of data, such as a
Count or Sum. The replacement value referencing described above can be used for final text. In addition, final calculated values can be
accessed by the use of &fx or &Fx. These references can also be used prior to the final break section (such as in break level text), and
will render the calculated value at the time it is called, such as cumulative summing..
Break text alignment:
The alignment of all levels of break text is controlled by this Alignment setting. Valid choices are Left, Center or Right. There are two
different settings: One that controls the text that appears before a break, and one to control the text that appears at the break
39
QLR Manager User’s Guide
Layout Panel
Outlining:
The Outlining checkboxes specify whether the values within a break column are blank in the following row of data, or if the same data is
repeated. All new break sections and the beginning of pages will display the column value even if outlining is set to "Yes". Outlining can
be controlled for each break level.
Show final text:
The "Show final checkbox" determines whether the final text/grand total information is displayed. If subtotals exist for breaks and the
grand total is not desired at the bottom of the report, this value can be unchecked.
Spacing after break:
This determines how many blank lines will appear after the associated Break level is triggered. It is also possible to specify that a new
page be printed. The new page feature is not supported in Netscape Navigator 4.x.
Wrapping break text:
When checked, the break text will be permitted to word wrap within the cell.
Use break text colors:
When checked, the break text colors as specified in the color controls are used. When not checked, the overall row coloring scheme is
used.
Show break data for a single data row:
When checked, break information will be displayed even if there is only a single row of data in the current break. When unchecked,
breaks with only one row of data will not produce break text, producing much "tighter" report output.
Report Charting
Please reference the separate topic about Report Charting.
40
QLR Manager User’s Guide
Layout Panel
Custom Layout
A Custom Layout is created by entering text into the "Custom Layout" section of the Layout panel. This text may contain HTML
tagging. QLR Manager allows the User to reference individual data fields, break level data, an entire report, and charts for inclusion in
the custom output that is generated.
Custom Layout controls
The Custom Layout section is intended to provide the User with "freeform" control over the formatting of output using HTML tagging.
This is particularly useful to generate e-mails to multiple recipients, each with specific information related to the addressee. More
information about this capability is provided in the Distribution e-mail topic below. Following is a description of the controls in this
section:
Number of e-mails to display:
If e-mail fields have been identified in the Report Columns section, this option determines the number of e-mails to display at one time.
Use Custom Layout Text and HTML:
When checked, QLR Manager applies the text that has been entered to create a custom report. If not checked, the custom text is
ignored. This allows for easy toggling between viewing the custom report based on the custom text and viewing a normal tabular style
report.
Use font settings:
There are three font settings that can be applied to the custom text on a global basis. These are the font face, color and size. If the User
wants complete control over the appearance of their custom report, they can uncheck this option and include their own HTML tagging.
Custom Layout Text and HTML:
This is the text area where the actual Custom Layout text is entered. HTML tagging can be entered to produce a freeform layout with
<report> and <chart> objects nested as desired. Replacement value references can also be used.
41
QLR Manager User’s Guide
Layout Panel
Basic Custom Layout:
The following report and chart will be used to demonstrate the features of Custom Layouts. Assume that the font color has been set to
blue to help identify custom text output.
Entering simple text:
If the text "This is custom text" is entered into the Custom Layout Text and HTML text area and the checkbox is selected to
Use Custom Layout Text and HTML, the following output will be produced:
This is custom text
This is custom text
This is custom text
This is custom text
This is actually useless output, but it demonstrates how the entered text is generated for each row in the report. The blank spacing
between rows is controlled by the Spacing after break setting.
42
QLR Manager User’s Guide
Layout Panel
Referencing column data:
If the text "This is custom text for &c3 &c2" is entered into the custom text area, it will produce the output:
This is custom text for Daryl Johnson
This is custom text for Daryl Johnson
This is custom text for Fred Jones
This is custom text for Ferb Shimpimple
The data for columns 2 and 3 in the report have been added using the column referencing technique.
Including the report or chart:
If the following text and HTML is entered into the custom text area:
This is custom text before the report
<table border=”0” cellspacing=”0” cellpadding=”2”><tr>
<td align="center"> <report> </td>
<tr></tr>
<td align="center"> <chart> </td>
</tr></table>
This text comes after
The resulting output will look like this:
This is custom text before the report
This text comes after
43
QLR Manager User’s Guide
Layout Panel
A few things to note:
• The tags <report> and <chart> are used to embed the report and chart into the output.
• A tabular report is the default output produced by QLR Manager. If a <chart> is desired, the appropriate selections must be made in
the Report Charting section of the Layout panel.
• HTML tagging is used to enhance the Layout by centering the report and chart in their own table cells.
• Leading and trailing text was added before and after the embedded report and chart.
• The custom text no longer repeats for each data row. If the <report> or <chart> tags are found in the custom text area, the custom
text is only used once per instance of the embedded report or chart.
Distribution e-mail
Distribution e-mail output is created when one or more fields are selected for use as an e-mail address in the Report Columns section
of the Layout panel. This designation is applied by choosing either "Email to:", "Email cc:" or "Email bcc:" as the Format or use
selection. These e-mail choices only appear when the report column is a data type of text. In order for a distribution e-mail to occur, at
least one field must be designated with an "Email to:" selection. Multiple entries for Email to, Email cc and Email bcc can be chosen.
Any change in the e-mail addresses associated with chosen fields will trigger a new e-mail to be produced.
The actual sending of distribution e-mails is initiated by either choosing the E-mail distribution option in the Report Tools window or by
specifying an Output type of "Distributed email" in the E-mail Specifications section of the Define Macro panel. Both options require
that the hosting server is running Simple Mail Transfer Protocol (SMTP).
Distribution e-mails go hand in hand with custom report layouts. It would be very rare to define a distribution e-mail and not use a
Custom Layout. Additionally, distribution e-mails impact the way in which data is presented in a Custom Layout. When a new set of email addresses is encountered, QLR Manager forces the page to end. For example, if the following text is entered into the Custom
Layout Text and HTML text area:
&c3, here is your invoice information totaling $&b6:
<report>
The output resulting from a format of "Email to:" selected for column 1 would look like this:
Daryl, here is your invoice information totaling $368.75:
Fred, here is your invoice information totaling $284.40:
44
QLR Manager User’s Guide
Layout Panel
Ferb, here is your invoice information totaling $43.40:
A few things to note:
•
•
•
•
A new page with a page header and footer is produced for each e-mail. An e-mail can contain reports that have multiple pages.
The custom text is rendered for each e-mail and &c3 is used to reference the first name value in column 3.
The break level amount (the total amount in column 6) was referenced using &b6. &b is used to retrieve break level data.
The report page will have a white background, providing a visual indicator that this is a distribution e-mail. Also, be aware that
distribution e-mails will be sent with a white background since many e-mail clients do not support page background colors.
Other helpful hints:
• If the custom text includes a <chart> reference and a chart was defined in the Layout, a new chart will be generated for each e-mail.
• If output is desired with multiple reports or charts, advantage can be taken of the way distribution e-mails trigger the creation of
individual output for each unique set of e-mail addresses. This works even if the field referenced as an e-mail address field, such as
the Break1 entry, is not really an e-mail address. This also requires that the report or chart be formatted with a Custom Layout,
which can be accomplished by entering as little as <center><chart><report></center> into the custom text area.
• Printer page breaks are inserted between each e-mail. This allows the User to print e-mails as though they were form letters. If there
are many e-mails to print, it may be helpful to increase the number of e-mails to a large number.
45
QLR Manager User’s Guide
Layout Panel
Report Columns
The Report Columns section of the Layout panel contains the most important selections for formatting a report. The options
presented provide the User with extensive control over the appearance of the report and format of the data.
Heading text:
The Heading text is the text to be displayed at the top of each column. The default value is the column name selected in the query. A
multiple line heading can be created by using the HTML break tag, <br />, or by using the underscore ( _ ) character. The "_" will be
interpreted as the HTML break. Database column names that include "_" will therefore automatically appear on multiple lines. Both
"First_Name" and "First<br />Name" will result in a column heading of:
First
Name
Each column as selected in the query is listed as a row of information in the Report Columns section.
HTML tagging can be used in the Heading text field as well, such as <u> to underline the text.
General formatting, such as the font type, size, color, and background color can be applied to all of the columns as a single group.
These settings are found in the Column headings area of the Titles & Footers section.
Display order:
The order that columns of data appear in a report is based upon the order that they appear in the query that produced the report. This
order can be changed by entering a value for Display order. If the User wishes to move two columns from the middle of the report to
the left edge of the report, this can be accomplished by entering 1 and 2 into the two columns to be moved. To move columns to the
end (right side) of a report, use a display order of greater than 1000 to move them to the right, such as 1001 and 1002. All columns that
are not given a display order value will remain in their original position.
Multiple row report:
Multiple row reporting allows for the "wrapping" of column data so that a single row of data will appear over multiple lines. This is
accomplished by entering key information into the Display order field. The format for the data entered into the Display order field is:
display order, +, column span
Entering a "+" in the second position indicates a start of a new line at that column. Some examples of key information entered into the
Display order field:
Display
What it does
order
3
Sets the display order to 3.
,+
Display order is the default order. Start a new row at this column.
,+,4
Display order is the default order. Start a new row at this column. It's column span is 4, which means that it spans four data
columns in the report.
,,3
Display order is the default order. A new row is not started. It's column span is 3, which means that it spans three data
columns in the report.
3,,3
The Display Order is set to 3. A new row is not started. It's column span is 3, which means that it spans three data columns
in the report.
46
QLR Manager User’s Guide
Layout Panel
Below is an example of a multiple line report. The Display order entry for the FORM ACTION column is ",+". The entry for the
ORIGINAL DATA and NEW DATA columns is ",+,6":
Note: It may be necessary to adjust the Rows per page setting when multiple row reports are produced.
Alignment:
This attribute controls how data will be displayed in a report column, either Left, Right, or Centered. The Auto (default) selection will
automatically display character data to the Left and numeric data to the Right.
Vertical alignment:
This attribute controls the vertical alignment of data in a report column. Data can be vertically aligned to the Top, Middle or Bottom of its
table cell.
47
QLR Manager User’s Guide
Layout Panel
Action:
There are numerous actions that can be performed to manipulate column data in a report layout:
Action
name
None
Break 1-5
What it does
No Action performed. This is the default value.
A Break is performed when the value in the column changes from the previous row's value. Breaks should only be used
on columns that have been properly sorted by the query. It allows for the calculation of subtotals, etc. The data in the
Break column will be displayed in an "Outline" format, meaning only the value of the first row of the break column will be
displayed. Showing the value for all rows of data is controlled by the "Outline" feature in Report Breaks.
Hidden breaks work the same as regular breaks, except that the column is hidden from view in the report. The
information can still be referenced using the &column number technique. This permits a break column to be hidden in
Hidden
the report, but still allows the data to be referenced in the Report Break's "Text before the break". An example might be
Break 1H-5H
to choose a hidden break for column 1, such as Break1H, and then reference the data in the Break #1 "Text before the
break" by entering "Data for &n1". This will display the next value found in column 1.
Group
The Group action allows for the compressing of data into a single row. For example, if another column in the report is
being "Summed", then the summed value for the column will be displayed as a single value for the Group. As with the
Break action, it should only be used on data that has been sorted properly by the query. Columns that have an Action
type of "None" or "Hide" will not be displayed in the report when grouping is present. It is possible to Group more than
one column in a layout.
Note: The grouping of large amounts of data may actually exceed the PHP processing time limit set on the hosting
server. It is recommended that the grouping of large amounts of data be performed with the SQL query, not the Layout.
Table
The Table action allows for the creation of a "Table" report. When the Table action is used, the values found in the
column where "Table" is specified are spread horizontally across the report as their own columns. The "Group" action
must also be used at least once, and at least one column action, such as "Sum" or "Count", must be specified for the
data in another column. The "Break" action can be used in conjunction with the "Table" action. Please refer to Table
layout for more information.
Table-
The Table- action works the same as that Table action, except the output is minus the Total columns that appear on the
right side of a Table layout.
Pivot
This selection will transpose column data into rows of data in a report.
Hide
The Hide action will hide columns from being displayed on a report.
Sum
Sum will add up numbers. It only works for columns that have been defined as a numeric column in the database. If
applied to non-numeric column, it will be ignored.
Cum sum
Cumulatively adds up numbers. At each break, the accumulation is reset back to zero. It only works for columns that
have been defined as a numeric column in the database. If applied to a non-numeric column, it will be ignored.
Average
Average calculates the average value of numbers. It only works for columns that have been defined as a numeric
column in the database. If applied to a non-numeric column, it will be ignored.
Count
Minimum
Median
Mode
The Count action counts the number of rows in the query results.
Minimum displays the minimal value for a column.
Median displays the middle value for a column, as if the values are sorted numerically or alphabetically, and this is the
value in the middle of that list.
Mode displays the most frequently occurring value in that column.
Mode(cnt)
Mode displays the most frequently occurring value in that column, along with the count of the number of occurrences.
Maximum
Maximum displays the maximum value for a column.
First
Formula
Last
% of total
First displays the first value found in a column.
Allows for a report column that utilizes an “Evaluated Formula” to be included in a report that uses the Layout's
Grouping Action. This may be necessary when report output is Grouped, because columns without a Layout Action
(such as Sum, Maximum, etc.) will not appear in the report. This forces the column to display when an Evaluated
Formula is present. The Evaluated Formula will be applied to both the individual rows and the Break summary level
data. The Formula Action is ignored for Table and Pivot reports.
Last displays the last value found in a column.
Calculates and displays the % of total for each row in the column.
48
QLR Manager User’s Guide
Layout Panel
Format or use:
Formatting provides control over how the data in a report field appears. The available formatting options depend on the type of data
selected in the query. There are 3 basic types of data for formatting. These types are character, numeric and date/time data.
Character data can be formatted as follows:
Format
option
What it does
General
Displays content as it appears in the database.
Truncate
Truncate will limit the number of characters that will display in a cell. The Column width setting will determine the number
of characters that will be displayed.
Unserialize This option will take data that is stored as a PHP "serialized" array, unserialize it and display it in a readable format.
This allows for the wrapping of larger amounts of textual data within a report column. Text will wrap within the boundaries
as set by the Column width. The default value is to prevent wrapping in a report cell, which is equivalent to and uses, the
Word wrap
HTML "NOWRAP" attribute. If data is allowed to wrap in a report cell, it can greatly affect the page length for printing
purposes.
Image
Email to:
For fields that have been defined as binary data (BLOB) fields, the Image option will appear and when chosen, will display
the data in the field as an image. The size of the image, its height and width, can be controlled by entering pixel values in
the "Column width" field. For example, if the User wishes to display the images as 200 pixels high by 300 pixels wide,
200x300 should be entered into the "Column width" field. The "x" or "X" must be used as the separator value between the
height and the width. Since images are data intensive, only a certain number (dependent upon the number of bytes in the
images) can be displayed. Once the limit is reached, the message "Image limit exceeded" will be displayed, instead of an
image. The amount of memory allocated for Image cache size is a setup option defined during the QLR Manager install
process.
This selection designates the field as an e-mail address. This would normally be used for Distribution e-mails, but could
also be used to produce output with multiple reports or charts by taking advantage of the way distribution e-mails trigger
the creation of new output for each unique set of e-mail addresses. This works even if the field referenced as an e-mail
address field, such as the Break1 entry, is not really an e-mail address. This also requires that the report be formatted
with a Custom Layout.
Email cc: This selection designates the field as an e-mail address to be used as a carbon copy.
Email bcc: This selection designates the field as an e-mail address to be used as a blind carbon copy.
Numeric data can be formatted as follows:
Format
option
What it does
General
Displays content as it appears in the database. The number of decimal places is dependent upon the raw data. Negative
numbers will be shown as -123.45.
1234.56 This allows for a fixed number of decimal places. A period is used as the decimal point. Negatives are shown as -1234.56.
This format displays numbers with a fixed number of decimal places and a comma in the thousands position. 12345.6789
1,234.56 is displayed as 12,345.67 when this formatting is chosen along with the Decimals set to 2. Negative numbers are show as
(12,345.67).
This represents currency formatting. Currency formatting displays numbers with a fixed number of decimal places, commas
$1,234.56 as the thousands separators and a period as the decimal point. The Currency symbol and its placement before or after the
number, is set by the User in the Report Body section. Negative values are displayed as ($12,345.56).
1234,56 This allows for a fixed number of decimal places. A comma is used as the decimal point. Negatives are shown as -1234,56.
This option displays numbers with a fixed number of decimal places and a period in the thousands position. 12345.6789 is
1.234,56 displayed as 12.345,67 when this formatting is chosen along with the Decimals set to 2. Negative numbers are shown as
(12,345.67).
This currency formatting option displays numbers with a fixed number of decimal places, a period as the thousands
$1.234,56 separators and a comma as the decimal point. The Currency symbol and its placement before or after the number, is set
by the User in the Report Body section. Negative values are displayed as (£12,345.56).
%
This displays the values as percentages. 1.0845 would be displayed as 108.45%.
49
QLR Manager User’s Guide
Layout Panel
Date and Time data can be formatted as follows:
In addition to formatting data in the column of a report, these options can be used to include the server's current date or time in the
Report's Title, Footer or Breaks by using the replacement strings as listed with each option. See referencing column information for
more information about replacement reference values.
Note: The Date separator option found in the Report Body section determines the character displayed as the separator for the selected
format.
Format
option
What it does
General
Displays content as it appears in the database.
Date time displays data in DD/MM/YYYY HH:MM:SS format. May 6th, 2002 2:29 pm 48 seconds is displayed as
d/m/y h:m:s
06/05/2002 14:29:48. This format can be accessed using the &DT1 replacement string.
12/31/2001
This will display May 6th, 2002 2:29 pm 48 seconds as 05/06/2002. This format can be accessed using the &DT2
replacement string.
2001/12/31
This will display May 6th, 2002 2:29 pm 48 seconds as 2002/05/06. This format can be accessed using the &DT3
replacement string.
Dec/31/2001
12/31
10:59:59 PM
This will display May 6th, 2002 2:29 pm 48 seconds as May 06, 2002. This format can be accessed using the &DT4
replacement string.
This will display May 6th, 2002 2:29 pm 48 seconds as 05/06. This format can be accessed using the &DT5
replacement string.
This will display May 6th, 2002 2:29 pm 48 seconds as 2:29:48 PM. This format can be accessed using the &DT6
replacement string.
10:59 PM
This will display May 6th, 2002 2:29 pm 48 seconds as 2:29 PM. This format can be accessed using the &DT7
replacement string.
22:59:59
This will display May 6th, 2002 2:29 pm 48 seconds as 14:29:48. This format can be accessed using the &DT8
replacement string.
22:59
31/12/2001
31/Dec/2001
2001/31/12
This will display May 6th, 2002 2:29 pm 48 seconds as 14:29. This format can be accessed using the &DT9
replacement string.
This will display May 6th, 2002 2:29 pm 48 seconds as 06/05/2002. This format can be accessed using the &DT10
replacement string.
This will display May 6th, 2002 2:29 pm 48 seconds as 06 May, 2002. This format can be accessed using the &DT11
replacement string.
This will display May 6th, 2002 2:29 pm 48 seconds as 2002/06/05. This format can be accessed using the &DT12
replacement string.
31/12/01
This will display May 6th, 2002 2:29 pm 48 seconds as 06/05/02. This format can be accessed using the &DT13
replacement string.
2001/Q4
This will display May 6th, 2002 2:29 pm 48 seconds as 2002/Q2.
2001/52
This will display May 6th, 2002 2:29 pm 48 seconds as 2002/19.
12/31/01
This will display May 6th, 2002 2:29 pm 48 seconds as 05/06/02. This format can be accessed using the &DT14
replacement string.
31/12
This will display May 6th, 2002 2:29 pm 48 seconds as 06/05. This format can be accessed using the &DT15
replacement string.
y/m/d h:m:s
Date time displays data in YYYY/MM/DD HH:MM:SS format. May 6th, 2002 2:29 pm 48 seconds is displayed as
2002/05/06 14:29:48. This format can be accessed using the &DT16 replacement string.
Monday
This will display May 6th, 2002 2:29 pm 48 seconds as Monday. This format can be accessed using the &DT17
replacement string.
Dec/01
This will display May 6th, 2002 2:29 pm 48 seconds as May/02. This format can be accessed using the &DT18
replacement string.
01/Dec
This will display May 6th, 2002 2:29 pm 48 seconds as 02/May. This format can be accessed using the &DT19
replacement string.
December
This will display May 6th, 2002 2:29 pm 48 seconds as May. This format can be accessed using the &DT20
replacement string.
50
QLR Manager User’s Guide
Layout Panel
Decimals:
The number of decimal places to be displayed for numeric data. 0 to 9 decimal places can be set. The "Auto" setting will automatically
float the number to however many decimal places the number produces.
Column width:
The Column width sets the approximate number of characters to display in the column. If set to blank or zero (0), the column will not be
displayed in the report. Text will only be wrapped within the cell if Word wrap is selected for the "Format or use". The values for the
column widths are calculated based on the largest value found in the column, either its data or the column title. The calculation is an
approximation based on the font size, font type and character count. It is not an exact number. Using a monospace font such as Courier
10pt will map the character count close to the calculated size.
Chart use:
The Chart use selections specify which columns to use as Labels or data Plots for a graph. Please reference the separate topic about
Report Charting for more information.
Report links:
Report links allow for the launching of a new report, based on an existing query and layout, by clicking a link within a report. The link
text is passed as a query variable to the query associated with the link. Links can be defined by clicking on the Create/Edit Report
Links icon found in this Report Columns section of the Layout panel.
Links are applied by assigning an existing link to a layout column. Both the Link owner and Link name must be entered. When
mapping a link, the column number in the layout to which that link applies must be selected. This is accomplished by using the Col #
selections found to the left of the Link owner field. If report links have been previously defined, they can be accessed by clicking the
button.
See Linked Reports for more information about how links are defined.
Evaluated formula:
QLR Manager is written in a language called PHP. The evaluated formula area allows the User to define a valid PHP command to be
executed using the PHP eval() function. The variable name that represents the data to be displayed in that field is named $value.
Note: Formula evaluation takes place prior to data formatting options being applied to the data. Although this provides greater user
control, it may result in some formatting issues that can be overcome by formatting the data in the formula itself. Here are some
examples of how to manipulate data in the field. The evaluated formula only changes the way the data is displayed, not its
underlying value.
When defining an evaluated formula, the column number in the layout to which that formula applies must be selected. This is
accomplished by using the Col # selections found to the left of the Link owner field.
Desired result
Evaluated formula
To change the text from upper to lower case
$value=strtolower($value)
To select a sub string of the first 15 characters in a field
$value=substr($value,0,15)
To format numbers with a European style, with 2 decimal places $value=number_format($value,2,',','.')
To format a date field to a particular format
$value=date('d M, Y',strtotime($value))
To conditionally change the text from one value to another
if ($value=='CO') $value='Colorado'
To replace text line breaks with HTML line breaks
$value=str_replace(chr(10),'<br />',$value)
51
QLR Manager User’s Guide
Layout Panel
It is also possible to reference the values in other columns with a formula. Other columns are referenced by using $val[column
number]. For example, if a report contains a last name in column 3 and it is desired to highlight the data in column 5 in red where the
last name is "doyle", the following evaluated formula could be entered for column 5:
if ($val[3]=='doyle') $value='<font color=”red”>'.$value.'</font>'
Although data in other columns can be referenced, only the data in the column where the evaluated formula is entered can be changed
by referencing that data using the $value variable name. Some of the basics for writing a formula are as follows:
• The language is case sensitive, using lower case for commands.
• The "if" statement conditions are enclosed in parenthesis, such as if ($value > 100).
• "&&" represents logical AND conditions. "||" is used for logical OR. For example, if ($value > 100 && ($val[2]=='CO' ||
$val[2]=='NY')) is read as: if the value in the column where the formula is written is greater than 100, and the value in column 2 is
either "CO" or "NY".
• The equals operator is "==" and not equal is "!=". A single equal sign assigns a value to a variable.
• A period is used to concatenate strings together, such as '<b>'.$value.'</b>' This would result in displaying the value as bold.
The prior row's data can also be accessed. $pvalue is the reference for the current column's prior row data and $pval[] is the array
reference for all of the fields. For example, a formula can be written as:
if ($val[2] != $pval[2]) $value='This is a new customer number'
Evaluated formulas will also calculate at the break and final levels as long as certain conditions are met. There cannot be any Action
assigned to the column that contains the Evaluated Formula and all columns that are referenced in the formula must have an Action
which produces data at the break level to perform the calculation.
Please reference the PHP manual for a full list of available functions.
52
QLR Manager User’s Guide
Layout Panel
Creating a table layout
A Table layout is a powerful layout action. It allows the User to create two dimensional reports by taking the data values found in the
column specified with the Table or Table- action and create new report columns for each of these values, spreading them horizontally
across the page. For example, if a column exists that contains a category code for each of the items in an order, a Table style layout
could be created with a column to "Sum" both the inventory value and the quantity of items for each category, and tabulate the totals for
each. The Table action will also produce Total columns on the right hand side of the report. A Table- layout will be minus these Total
columns.
A sample report of data prior to Table formatting could look as follows:
When the Action selections are changed in the Report Columns section of the Layout as depicted below, a Table layout report is
produced:
The resulting report is a Table layout:
53
QLR Manager User’s Guide
Layout Panel
A few important things to be aware of when using the Table layout action:
• The Table action can be used on only 1 column. The first column found with the Table action will be used. Other instances will be
treated as a "None" action.
• At least one Group action must be used on another data column. If a Group is not specified, an error message will be displayed on
the Layout panel when attempting to apply the Layout.
• Breaks can be used in a Table layout.
• At least 1 data column must have an action on which the column can calculate a value, such as "Sum". Multiple calculation actions
can be used with the Table action.
• If more than one action is specified, the data for each Table value listed horizontally across the page will be separated with a heavy
vertical line in the report.
• Columns that do not have an action are excluded from the report.
• It is acceptable to use a "Format" option on the column where the "Table" action is being used. This can be extremely useful for
tables created using date data. For example, using the 'December' format (which indicates to QLR Manager to extract the month
name from a date field), will create a Table layout, sorting the months from January - December. It works similarly when using
'Monday' as a date format. This will sort the days of the week as Monday - Sunday, as the table headings.
• If headings are included when producing a CSV output file, all 3 heading lines from the Table layout will be included in the CSV file.
• When an XML file is produced, all 3 title levels, separated by a ".", will be used to produce a unique field name. In the example
above, the amount for "Crank Baits" on order number 1003 is $25.75 and will have an XML field name of
category.Crank_Baits.amount. The User can change the name by altering the Heading text for the Report Columns in the Layout.
Creating a pivot layout
A Pivoted layout is similar to a Table layout in that it spreads the "Pivot" column values horizontally across the page. But unlike the
Table layout which creates a column for each of the fields that contain a form Action such as Sum, a Pivoted layout creates a row of
data for each of the fields that are assigned a layout action.
In the following example, a simple set of data has been selected and formatted with a Break #1 on the Region, and Sum for the Plan
and Actual columns:
54
QLR Manager User’s Guide
Layout Panel
To illustrate the difference between the Table layout and the Pivot layout, the above report was formatted using a Table layout. Only the
first 3 months are shown to limit the width of the example. An Action of Table was selected for the Month column and Group was
selected for the Qtr, resulting in the following report:
If the Layout is adjusted to set the Action of the Month column to "Pivot", along with the following changes:
• The Action of the Qtr column set to "None".
• The Text at the break for Break #1 set to &C1 to reference the Region name.
• The use of break coloring is unchecked.
The following report is produced:
Notice how both the Plan and action columns' data are rotated and displayed horizontally. Also notice how columns without an action
(in this case, the Qtr column) are not part of the report. To include a column, the Group action can be used. Also, the text above the
pivoted columns is displayed as "Pivoted Columns". This can be changed to the desired value ("Data" in the following example) by
updating the appropriate field in the Column headings area of the Titles and Footers section:
55
QLR Manager User’s Guide
Layout Panel
To add a finishing touch, a title was added and the "Use break coloring" check box was checked, with the title colors applied to the
Break text:
56
QLR Manager User’s Guide
Linked Reports
Linked Reports
Overview
Linked Reports support the spawning of a new (child) report when the User clicks on a link in an existing (parent) report. To create a
link, an existing Query and Layout is selected to be executed when a link is clicked. Creating a link in a report is accomplished in the
Report Columns section of the Layout panel.
Data values in the parent report can be mapped to query variables that exist in the child query. Child reports can also spawn their own
linked reports. A report can contain multiple links. A linked report does not have to be a "report". It might actually be a query that
executes a command, such as INSERT or UPDATE. Any valid existing query can be executed as a linked report.
Links are "portable", meaning that they can be sent in e-mails, downloaded to HTML files, or be present in a Report Object. QLR
Manager encodes into the link the database connection values of the User ID creating the link. The link connects to the database as
though it is the creator User ID connecting. A unique encryption key is created for each installation of QLR Manager, so links created in
one installed instance of QLR Manager cannot be altered to access another installed instance of QLR Manager. Although this method
is very secure, it is recommended that links intended for external access be created using a User ID with limited access authority. This
eliminates the risk of exposing the "root" or other Power User's ID and password. Given enough time and effort, anything that can be
encoded, can be decoded.
The link encryption key resides in QLR Manager's qlr_info table. If there is a need to change the encryption key, simply delete the "link
key" entry from the qlr_info table. QLR Manager will automatically recreate a new link key the next time a link is created. Links created
with the old key will be invalid and no longer work.
Defining a link:
Report links are defined by clicking on the Create/Edit Report Links icon in the Report Columns section of the Layout panel. In
general, a link defines what the link looks like, the browser window behavior for the child report, as well as which query is executed
when the link is pressed.
Selecting a link style
There are two different types of links that can be created. If QLR Manager output containing report links is intended to be e-mailed or
downloaded in a format other than HTML, the Text link is recommended for wider compatibility.
Produces a standard hypertext link. The font face and size is inherited from the Report Body section of the Layout
panel. The Link color can be selected along with Bold, Underline and Italic text attributes. A Hover style can also be
defined which is applied when the cursor is placed over the link.
Button link Selects a standard form button. The font face and size is inherited from the Report Body section of the Layout panel.
The button's foreground and background color can be specified, along with Bold, Underline and Italic text attributes.
Rather than assigning colors to the button, it may be desirable to use the browser's default button style. This is
accomplished by checking the "Use default button style" checkbox.
Text link
Link window characteristics
When a link is clicked, a query is executed in either the existing QLR Report panel, or in a new browser Window. There are several
options for selecting a target for the linked report output:
New window for every link
This will open a new window when any link is clicked. If five links are clicked, then five new
windows will be opened.
New window for each link column This will create a new window when a report contains more than one linked report. If two
columns in a report are links, then a maximum of two new windows will be opened. All links from
within the same column will target the same window.
Same window for all links
All links that are clicked will open in a single window. In order for this to hold true for reports with
multiple linked columns, all the links must use this selection.
Existing window or frame
The output will be sent to the QLR window or frame that launched the report. A "Return to
Previous" link is provided under the Header to return to the parent report after spawning the
child report. If used with a Report Object, this selection will open the report in the same window
or frame that links to the report.
The height and width (in pixels) of a newly opened link window can be specified. If either value is left blank, the blank dimension will
default to the size of the parent window, also called opener window. The Window features allow for further customization of the new
window. The window's "chrome" features can be selectively added or omitted, along with control over whether the window should have
scrollbars and can be resized.
57
QLR Manager User’s Guide
Linked Reports
Defining the query and mapping query variables
Begin by creating and saving a query that will produce the desired parent report. It is recommended that the tables used in the query be
fully qualified by prefixing the table names with the appropriate database/schema. The reason for this is that the database/schema that
is in use at the time the link is created may be different than the database/schema being used when the query which will be used as the
basis for the link was created. Next, determine which column(s) will be linked to child report(s). Author and save the child queries. It
may be desirable to include query variables in the child queries that can be mapped to data in the parent report. It is possible, but not
required, to map the data from a column in the parent report to the query variables. This allows for the linked reports to present dynamic
data.
Execute the parent query and access the Layout panel. Click the Create/Edit Report Links icon in the Report Columns section of the
Layout panel. This will open the Report Links window where link characteristics are defined. It is necessary to select an existing
query to be executed when a link is clicked. Specifying a layout is optional. After a query has been selected, the Examine button can
be clicked to display the query variables associated with the query. If query variables exist and are displayed, it is possible to map the
data from a column in the report to the query variables. In order to perform the mapping, the Layout's report column number must be
entered into the space provided. If the linked query contains additional query variables, the query variable data collection panel will be
presented to collect values for the additional variables when the link is executed.
Note: Any changes made to a report layout or a report link must be applied to the report. This requires the report to be rerun by clicking
either the Apply Layout button in the Layout panel or the Report tab in the Header.
Assigning the link to a report column:
A column in a report becomes a link when a valid Link owner and Link name is assigned to the corresponding Col # in the report. If an
invalid Link owner or Link name is assigned, or the Col # is omitted, the creation of a link is ignored. An error message will appear in the
report title and the data in the report remains as is (without links). If report links have been previously defined, they can be accessed by
clicking the
button. To remove a link, both the Link Owner and Link Name fields should be blanked out.
Conditionally creating a link:
Conditional links can be created with the use of an evaluated formula. This is accomplished by writing a formula that assigns the
keyword qlr_omit_link to the value in the link column. Using the linked report example below, if the following evaluated formula was
written for report column 1, links would be omitted for the Billings brothers.
if ($val[3]=='Billings') $value='qlr_omit_link'
Example of a Linked Report:
The following is an example of defining and using two Linked Reports. The example makes use of both available linking styles... A form
button and a hypertext link with font attributes applied. The hypertext link also has custom link and hover colors defined.
This scenario involves an initial report that lists a subset of customers that have product orders. The objective is to be able to display a
list of orders for a particular customer and also offer a link to the Customer profile. The fully functional example can be experienced at
our Online Demo by logging onto the Query Editor with ID and password of guest, then retrieving the query baitshop customer list
and clicking the Run Query button.
The initial report is created by executing the following query:
select c.custnum, c.first_name, c.last_name, 'customer profile'
from qlrmanager_baitshop.customer c, qlrmanager_baitshop.orders o
where c.custnum=o.custnum
group by c.custnum, c.first_name, c.last_name
limit 10
58
QLR Manager User’s Guide
Linked Reports
The following report is produced:
The first column's Linked Report allows a user to click on the customer number and load a new report, configured to open in the QLR
Manager window and display all of the selected customer's orders. A query to generate the desired report already exists for frank as
the owner and is called baitshop customer orders. It uses a query variable called [custnum] that is passed to the query when the
button is clicked.
The query associated with the form buttons in column #1:
select o.ordnum, o.ord_date, c.custnum, c.first_name, c.last_name
from qlrmanager_baitshop.orders o, qlrmanager_baitshop.customer c
where o.custnum = [custnum] and o.custnum=c.custnum
order by o.ordnum
The second Linked Report in column #4 allows a user to click the hyperlink and view the Customer's profile. The query for this link is
also owned by frank and is called customer profile. Instead of loading into the QLR Manager window, this link is configured to open in
a new window.
The query associated with the hypertext links in column #4:
select *
from qlrmanager_baitshop.customer
where custnum = [custnum]
Notice how [custnum] is also used as the query variable for the customer profile query. Even though the link is in column #4, the
Report Link is mapped to column #1 so the custnum value is passed when clicked.
Multiple levels of "drill down" can be achieved by employing the same techniques described above to child reports. When viewing the
child reports, either Report tools or Output tools will be presented in the Header to allow for downloading various formats or e-mailing
the output. Since linked reports only work within the QLR environment, all linked columns within the report are converted back to plain
text for downloads and e-mails.
59
QLR Manager User’s Guide
Report Charting
Report Charting
Overview
The Enterprise Edition provides the capability to graph data with a few simple selections from the Report Charting and Report Columns
sections of the Layout panel. 5 chart styles (Vertical bar, Horizontal bar, Line, Pie and Scatter-XY) are available with over 25
variations of these styles. There are over 40 chart characteristics that can be controlled. The following instructions describe the
available controls and their use, along with examples of the resulting charts.
Creating charts
Creating charts is very simple. There are only two required actions to create a basic chart:
• Select a "Position" for the chart in the Reporting Charting section of the Layout panel.
• Choose at least one column of numeric data to plot in the Report Columns section of the Layout panel by setting the Chart use =
"Plot", or "Plot+" to display the values above the plot.
The following will describe the steps of creating and modifying a chart. It will use the data from the following report when creating chart
examples:
Creating a basic chart:
In most of these examples, the charts are produced with a chart size of 300 x 225 pixels using a landscape orientation.
• Specify a General style of "Vert Bar" using the General characteristics controls in the Report Charting section.
• Select "Plot" from the Chart use controls in the Report Columns section for the Plan and Actual columns.
60
QLR Manager User’s Guide
Report Charting
Adding data labels:
A title and axis labels can be added to the chart.
• A Chart Title was added using the General characteristics controls.
• X and Y axis Titles were added using the controls in the X axis and Y axis control groups.
• The labeling of X axis tick marks is accomplished by setting a Report Column's Chart use to "Label". In this example, the "month"
column was chosen. In addition, "Dec" was used as the Report Column Format so the month's short name would be displayed.
Additional formatting:
• The "2005 plan" column was added with the Chart use of "Plot+", which specifies to display the data values above the
corresponding plot.
• The 2005 plan column number (5) was also specified to be plotted as a "lines in a bar chart" in the Advanced control group.
• The Maximum value of the Y axis was set to "40".
• The Legend location was set to "Center Bottom" of the chart in the Legend control group.
General characteristics
Position:
The Position determines where the chart will appear in relation to the report data.
Title:
A title can be entered to appear at the top of the chart. It is acceptable to use replacement strings within the title.
61
QLR Manager User’s Guide
Report Charting
Title font size:
The default selection for Title font size is "auto". When auto is selected, QLR Manager will automatically calculate the font size for the
title based on the size of the chart that is selected.
Orientation:
The Orientation determines how the chart will be displayed. Portrait is taller than it is wide, and Landscape is wider than it is tall.
General style:
The General style is used to define what type of chart will be produced. The styles consist of vertical bar, horizontal bar, line, pie and
scatter (X/Y plot) charts.
Size:
The size value controls the size (pixels) of the chart produced. When Landscape orientation is used, the first value is the width. When
Portrait orientation is used, the first value becomes the height. The smaller chart sizes are intended for use as charts that can be
generated using QLR Manager's Report Object feature.
Specific type:
The Specific type provides a selection of additional options for the chosen chart style:
• Vertical and Horizontal Bar
- Basic: Bars are grouped together next to each other.
- Stacked: Bars are stacked on top of each other, with the data being cumulative.
- Stacked %: Bars are stacked on top of each other, with values equaling 100% in total.
• Line
- Basic: Typical line chart. No markers for data points.
- Markers: Typical line chart with markers for data points.
- Stacked: Lines are stacked on top of each, with the data being cumulative.
- Stacked %: Lines are stacked on top of each other, equaling 100% in total.
- Filled: Lines are stacked on top of each, with the data being cumulative. The area below the lines are color filled.
- Filled %: Lines are stacked on top of each, equaling 100% in total. The area below the lines are color filled.
• Pie
- Basic: Flat pie charts.
- 3D: Three dimensional pie charts. With 3D pie charts, the data labels will always appear outside the pie slices.
• Scatter
- Basic: Typical plotting of X/Y values.
- Impulse: A line is added to connect the plot point to the zero value of X axis.
Data source level:
The data source level provides the User control over what data is used to produce the plots in a chart. There are three levels:
• Row uses each individual data row for plotting. This is typical.
• Break1 uses the data found at the Break #1 level of the report. In order to use this level of plotting, some sort of Action, such as
Sum, must be applied against the columns to be plotted.
• Final uses the data from the Final summary of the report. In order to use this level of plotting, some sort of Action, such as Sum,
must be applied against the columns to be plotted.
Plot data orientation:
The data orientation setting determines how the data should be interpreted for plotting. It is best explained with two examples:
The query to produce the rows of data used in the chart examples above, looked something like this:
select region, month, plan, actual, actual*1.08 from sales
where region='southeast'
The data to be plotted was Column oriented
Had the data been stored differently, needing to be selected as follows, it would have been Row oriented:
select category, jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec from sales
where region='southeast'
62
QLR Manager User’s Guide
Report Charting
Chart border type:
This option provides selections for an outer border around the chart. The selections include None, Line and 3D Shadow.
Page break for printing:
If checked and supported by the browser, this will force a page break between the chart and report table when printed.
Margin color:
The Margin is the border area around the chart. This sets the color for that area.
Background color:
The Background refers to the back of the plot area. This sets the color for that area.
Plot colors:
The Plot colors allow for the selection of colors to be used for each plot. 20 colors can be selected and the colors will be used in
sequential order. If there are more plots than colors, the colors will be repeated starting with the first color.
The following chart has a 3D effect with modified margin and background colors.
X axis attributes
Title:
A title can be entered for the X axis. It is acceptable to use replacement strings within the title.
Font size:
The default setting for the X axis font size is "auto". When auto is selected, QLR Manager will automatically calculate the font size
based on the size of the chart that is selected.
X axis label angle:
If True Type fonts are installed, the angle of the X axis labels can be set to be 0,30,45,60 or 90 degrees. Without True Type fonts
installed, only 0 and 90 degree labels are supported. If angles other than 90 degrees are chosen, they will be treated as 0 degrees.
Label truncation:
If there are X axis labels whose length makes them too long for reasonable display, the number of characters can be limited by
truncating the values. The length can be limited between 1 to 12 characters.
Label spacing method:
There are two ways to define the spacing for X axis labels. The "Frequency" method determines how often a label value is displayed on
the X axis. The "Number of labels" method controls how many labels that will appear on the X axis. The first label value is always
displayed.
Spacing value:
How the Spacing value is applied is dependent on the Label spacing method. If a value of 5 is entered and "Frequency" is selected,
every 5th entry will receive an X axis label. If "Number of labels" is specified, then 5 labels will be displayed regardless of the number of
X axis values. Both methods require that the number of X axis plots be evenly divisible by the Spacing value or QLR Manager will
adjust the number of labels accordingly.
63
QLR Manager User’s Guide
Report Charting
Show grid lines:
If checked, the X axis grid lines will be displayed. The Y axis grid lines are always displayed.
In this chart, the X axis frequency has been set to 3, grid lines are checked, and the label angle has been set to 60 degrees.
Y axis attributes
Title:
A title can be entered for the Y axis. It is acceptable to use replacement strings within the title.
Font size:
The default setting for the Y axis font size is "auto". When auto is selected, QLR Manager will automatically calculate the font size
based on the size of the chart that is selected.
Y scale type:
The Y axis scale can be set to be either Linear, Logarithmic, or Percent.
Decimals:
This option allows for the selection of the number of decimal places to be displayed for Y axis values.
Minimum value:
The Y axis values are automatically created when a chart is generated. However, the minimum value can be manually set in this field.
Please note that depending on the relative size of the numbers needed in the Y axis, the value entered may be modified when the chart
is created with a minimum value.
Maximum value:
The Y axis values are automatically created when a chart is generated. However, the maximum value can be manually set in this field.
Please note that depending on the relative size of the numbers needed in the Y axis, the value entered may be modified when the chart
is created with a maximum value.
64
QLR Manager User’s Guide
Report Charting
This is an example of a Horizontal Bar
chart with Portrait orientation. Notice
how the X and Y axis have been
rotated. The Y axis information now
appears on the top. The Maximum Y
value has been set to 40 and the
Legend is at the "Center Bottom". The
title was created with the string of "&c1
region", which used the data from
report column number 1 to determine
the region for the chart.
Legend
Legend location:
This specifies the Location of where the legend will appear on the chart. The legend is comprised of a description of each of the sets of
plot data. Depending on the size of the chart, and the number of items to appear in the legend, there may not be enough room to
properly display the legend. It is up to the User to find a suitable placement for a legend.
Legend truncation:
If there are items in the legend whose length makes the legend too long for reasonable display, the number of characters can be limited
by truncating the values. The length can be limited between 1 to 12 characters.
Pie chart controls
Pie slice label:
Pie slices can be labeled in a variety of ways. The selections include no label (None), Percent, the actual Value, or the Legend label.
Label location:
The Label can be set to appear inside or outside of the slice on Basic Pie Charts. For 3D pies, the label can only appear on the outside
of the slices.
Max pies per row:
If the plot data results in more than one pie created, this setting specifies the maximum number of pies to chart horizontally across the
chart. Selections range from 1 to 4. QLR Manager will support up to 5 rows of charts with 4 charts each, resulting in a maximum of 20
pies in a chart.
65
QLR Manager User’s Guide
Report Charting
Slices to explode:
This field allows the User to specify which slices to explode in a pie chart. If multiple exploded slices are desired, each plot number is
entered separated by a comma. For example, to explode slices 2 and 5, they would be entered as "2,5".
The following is an example of a pie chart with slices 2 and 5 exploded:
Odometer chart controls
Odometers look like an old fashioned speedometer gauge in an automobile. These charts allow you to plot a single data point per
gauge. Up to 25 gauges can be plotted in a chart.
Needle type and color:
This control allows you to set the gauge indicator (the needle) style. The color of the needle can also be set using the Needle color
control.
Gauge numbering color:
The color of the numbers that appear on the gauge are set with this control.
Gauge numbering interval:
The gauge numbering interval provides control over how often tick marks appear on a gauge and how often that numbers appear next
to the tick marks. A setting of "50,2" would set tick marks to appear at 50, with numbers appearing every 2nd tick, such as for 100, 200,
etc.
Plot color range indicators:
This control allows the User to select the points at which the color pattern should change. The colors themselves are defined in the Plot
Color control found in the General Characteristics section of Report Charting. If an entry of "300,600,800" is entered, 0 - 300 would get
the first color of the Plot Colors, 300 - 600 would be given the second color and 600 - 800 would get the third color. Any area past the
end of the range of these colors will be white.
Max gauges per row:
This determines the numbers of gauges to plot horizontally. Up to 5 rows of gauges can be plotted.
66
QLR Manager User’s Guide
Report Charting
Gauge starting and ending values:
These controls allow the starting and ending point for the gauge to be specified. If no values are given, the default of 0 and 100 are
applied.
The following is an example of an Odometer:
Advanced controls
Scatter chart Y column:
When scatter charts are created, the first two selected plot columns are used as the X and Y plot values. This field specifies if the Y
value is the first or second column found.
Column numbers as lines in a bar chart:
It may sometimes be desirable to create a chart that is a mixture of bars and lines. This can be accomplished by using a vertical or
horizontal chart type, and then using this field to specify that certain plots (as referenced by their report column numbers) are to be
treated as lines. If more that one plot is to be treated as a line, then the entries are separated by a comma. For example, to specify that
the plots for columns 2 and 5 are to be line plots, they would be entered as "2,5".
Line thickness:
The Line thickness selection controls the pixel size of lines used in line charts or bar charts with plotted lines. When a line thickness of 1
is applied, anti-aliasing (line smoothing) will be used. Anti-aliasing can only be used with a thickness of 1. This is a limitation of the chart
generation software (JPGraph).
Bar chart color gradients:
The gradient selection allows the User to give their bars a "fading" effect. There are several settings: Vertical, Horizontal, Fade to top,
and Fade to bottom. The following is an example of a vertical gradient setting. It also employs a Y axis scale type of "Percent" and a
Chart use of "Plot+" to display the percentages above the bars.
67
QLR Manager User’s Guide
Report Charting
Selecting plot data
The Chart use column, found in the Report Columns section of the Layout panel, is used to specify how the columns data will be
used in creating a chart. There are four selections for this value:
•
•
•
•
None
Label
Plot
Plot+
Column not used as part of the chart creation.
The data in this column will be used as X axis labels, except for pie charts where it will be used as the slice labels.
The data in this field will be used as plot data. Plot is only available when the column contains numeric data.
The data in this field will be used as plot data. In addition, the data value will appear above the plot in Bar and Line charts.
Plot+ is only available when the column contains numeric data.
The Plot and Plot+ options only appear for numeric columns. This may present a problem if the User wishes to plot the results of
applying the "Count" action to a column of non-numeric data. The work around for this situation is to add an addition column to the
query select list, such as 1 as count. An Action of Count or Sum can be applied to the data in this new column. The data will be treated
as numeric in nature, allowing the Plot and Plot+ Chart use options to appear.
Scatter charts
Scatter charts are intended to plot two related sets of column information. One of the plot sets will determine the X axis values. The
other will determine the Y Axis values that are plotted. If only one column is specified, it becomes the Y axis data. The X axis will be set
as a sequential frequency. If more than two plot columns are specified, the extra columns are ignored.
The example below demonstrates a scatter chart's features.
• The first column of plot data (depth) has been identified as the Y axis column. See advanced controls for more information about
selecting the 1st or 2nd column as the Y axis column.
• When a Break1 is specified in the Layout, each set of data becomes a "Plot Set".
• Each plot set is assigned a different symbol.
• When more than one plot set is found, Legend data is available for use. There is no Legend information for a single plot set (i.e. no
Break1 in the Layout was found).
68
QLR Manager User’s Guide
Report Charting
69
QLR Manager User’s Guide
Report Panel
Report Panel
The Report panel allows the User to view the report that is generated by running a SELECT query. The appearance of the report is
controlled by changing attributes in the Layout panel. Output generated from UPDATEs, INSERTs, or batch queries can is also
viewed in the Report panel, but Layout control is not available for this type of output.
Paging between page sets
When a report is produced, only a certain number of rows of data are displayed at one time. In order to move between "page sets", the
User must click the appropriate navigation buttons (First, Back, More, Last) found above the report. Unavailable options are grayed
out.
There are two limiting factors that determine how large of a continuous report page can be created. These are the Report rows and
Maximum output file size settings applied when QLR Manager was installed. These values default to 500 rows and 5 MB.
Display whole report:
The capability exists to override the number of report rows displayed for each "page set" in the Report Body section of the Layout
panel. This can be useful for printing a large continuous report using the Print displayed output option in the Report tools pop-up. The
value entered for Max displayed rows can be used to increase the page set size and be saved for use with a particular report. If the
Layout is saved as the same name as the query or wizard producing the report, it will become the default layout applied when the
query, wizard or menu item is executed.
Output can also be printed to a PDF file using a PDF writer such as Adobe Acrobat or CutePDF (available free from www.cutepdf.com).
Increasing the max displayed rows also provides a means of creating a large, continuous PDF of the report output.
Note: When printing to a PDF writer, it is usually desirable to print in full color. The default browser printing behavior is to avoid printing
background colors to save ink. Instructions are provided in Printing output that describes how to change these settings in common
browsers.
Logging off
Once the User has connected with an ID and password, a Log off button will appear in the upper right corner of the QLR Manager
Header. Although it appears on all panels, it is most relevant to report generation.
When QLR Manager generates the web pages it displays, including report pages, it creates the information in temporary storage.
Clicking the Log off button will erase these files and take the User back to the Connect panel. Although it would be very difficult
(never say impossible) for someone to access these report pages, this provides a means to delete from the server all pages created
during the User's session.
Report Tools
When viewing a report or other type of output, a "Report tools", "Output tools", or "Preview tools" icon will appear in the header adjacent
to the Report or Preview tab. Clicking on this icon allows the User to Find information in the current page set, or create various
output formats, such as downloads of formatted output, data files, XML output, and e-mails. The options available are dependent on the
type of output generated. Individual reports provide the greatest flexibility in terms of the download and e-mail options. Macro output
and the output from UPDATEs, INSERTs, or batch queries is not conducive to formatting some types of downloads and most options
will not be available.
Find text in output
The Find function, available in Internet Explorer, Netscape and Mozilla, allows the report to be searched for a string. It only searches
the pages that are currently displayed. For other types of output, such as Macro output organized into expandable/collapsible sections,
a checkbox is available for "Visible text only". This will limit the Find to only those sections that are expanded.
70
QLR Manager User’s Guide
Report Panel
Printing output
If the User wishes to print output in full color, the Print black & white checkbox in the Report Body section of the Layout panel must
be deselected. In addition, the browser's print settings may have to be changed. The default installation for most browsers prevents
printing page and table cell backgrounds in color to conserve ink. Below are some tips for changing these preferences in some common
browsers:
Internet Explorer:
1 Click Tools | Internet Options.
2 Click the Advanced tab.
3 Scroll to the Printing section. Check Print background colors and images.
4 Click OK.
Mozilla Firefox:
1 Click File | Page Setup.
3 Check Print Background (colors & images).
4 Click OK.
Netscape Navigator 6.x & 7.x and Mozilla:
1 Click Edit | Preferences.
2 Expand Appearance and select Colors.
3 Check Always use the colors and background specified by the web page.
4 Click OK.
Netscape Navigator 4.x:
1 Click File | Page Setup.
2 Check Print backgrounds.
3 Click OK.
Opera:
1 Click File | Print options.
2 Check Print page background.
3 Click OK.
Download file formats
For some types of output, the only download option is HTML. Individual reports can be downloaded as HTML, or Microsoft Word and
Excel files. The User can choose to create the file based on the currently Displayed page set, or if there are more rows than can be
displayed in the current page set, a file of all pages (Whole report).
If the DOC or XLS radio button is selected, the HTML will be modified to allow the file to be loaded into the chosen application and
maintain the report formatting, including colors, font sizes, etc. The only noticeable difference between this format and the normal
HTML output is that some types of numeric formatting may not line up precisely.
71
QLR Manager User’s Guide
Report Panel
Download as DATA file
QLR Manager allows the User to create several different types of data files for report output. Microsoft Excel (XLS), comma separated
values (CSV) and semi-colon separated values (TXT) files can be created. These files can then be imported into other applications
such as Microsoft Excel. The file is created on a "What You See, Is What You Get" basis, giving the User maximum control over the
format of their output. The layout capabilities found in the Layout panel can be used to format, break and group the data, prior to
creating the data file. All HTML formatting is stripped out of the data when the file is created. A report that looks like this:
Will produce a CSV file that contains:
"partnum","name","boh","price"
"dubcr","Uncle Billy's Crappie Rod",0,14.00
"dwscr","Shakespear Casting Rod",18,14.00
"dlwg25","Super G Caster",43,29.95
"dml47","Light weight glass rod",0,28.95
An XLS file can be created with the same data to be loaded directly into Microsoft Excel. Text formatting, such as colors and fonts, will
not be preserved.
Report pages:
This option specifies the scope of the amount of data that will be output. If the "Displayed" option is selected, then the output content
will only contain what is in the currently viewed page set. If "Whole report" is selected, then all the data associated with the report will be
output. There is a third option available when downloading a XML or Data file. The selection of "Whole report (Raw data - fast)" creates
a data file, bypassing any changes made in the Layout panel. The benefit of using this option is that it is much faster when working
with large amounts of data.
Include column headers:
When selected, this option will add one additional row of data to the top of the data file, which are the column headings as they appear
in the report.
File type:
This option allows the User to specify the type of file to be created. Microsoft Excel (XLS), comma separated values (CSV) and semicolon separated values (TXT) files can be produced.
72
QLR Manager User’s Guide
Report Panel
Download as PDF file
Transforming the HTML output from QLR Manager into a PDF file is computation intensive. It is possible that large report output may
timeout on the server before the output is created. For this reason, PDF downloads should be limited to smaller reports. The number of
cells in the tabular output is the critical factor. Five pages or less can usually be converted without any difficulty, but more pages with a
large number of report columns may timeout. Smaller chunks of PDF output can be created and merged together with Adobe Acrobat if
desired.
Note: An alternate method of producing large PDFs from QLR Manager output can be achieved by displaying the whole report and
using a PDF writer such as Adobe Acrobat or CutePDF (available free from www.cutepdf.com). This method is recommended for large
reports and is usually much faster than converting HTML to PDF on the server.
Page margins:
These are the page margins that will be applied to the PDF output. The default values are 15mm, which are slightly less than 5/8 inch.
Orientation:
This selection sets the page orientation of the output. Portrait is narrower than it is tall and landscape wider than it is tall.
Paper size:
This option provides a selection of paper sizes for the PDF output.
Page width:
The Page width selection can be equated to screen resolution. For example, if the workstation resolution is 1024x768 and the web
browser is expanded full screen, the 1024 selection would approximate the width of the content visible in the browser window. The
higher the selected page width value, the smaller the font. A smaller value may be more suitable for narrower reports with a few
columns and a larger value for wider reports.
Watermark:
Text entered into this field will be rendered diagonally on the first page of the PDF in a large outline font. This may be useful to add text
such as DRAFT across the front of the PDF.
73
QLR Manager User’s Guide
Report Panel
Download as XML file
This option allows the User to create an XML file of the report data, which contains an internal DTD. The User is allowed to define their
own root tag, and a tag for the record level data. The tags for each field will be the column titles that are entered in the Layout panel.
QLR manager will try to interpret column titles to create tags, replacing spaces and HTML breaks with "_" characters.
Note: It is up to the User to provide column titles using the Layout panel. These values will be used as element tags in the XML
output.
As with the CSV file creation, it is a WYSIWYG approach to creating the data, with the exception that break information and blank lines
will not be included in the output. All HTML tagging is stripped out of the output, and the characters, <, >, &, ' and " are replaced with
their XML equivalents. Be careful with "Breaks" in the report output where data outlining is checked. This will cause blank data entries
to be created for the outlined fields. Remember, What You See, Is What You Get.
A report that looks like this:
Will produce an XML file that contains:
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE data [
<!ELEMENT data (record+)>
<!ELEMENT record (partnum,name,boh,price)>
<!ELEMENT partnum (#PCDATA)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT boh (#PCDATA)>
<!ELEMENT price (#PCDATA)>
]>
<data>
<record>
<partnum>dubcr</partnum>
<name>Uncle Billy's Crappie Rod</name>
<boh>0</boh>
<price>14.00</price>
</record>
<record>
<partnum>dwscr</partnum>
<name>Shakespear Casting Rod</name>
<boh>18</boh>
<price>14.00</price>
</record>
<record>
<partnum>dlwg25</partnum>
<name>Super G Caster</name>
<boh>43</boh>
<price>29.95</price>
</record>
<record>
<partnum>dml47</partnum>
<name>Light weight glass rod</name>
<boh>0</boh>
<price>28.95</price>
</record>
</data>
74
QLR Manager User’s Guide
Report Panel
E-mailing output
This option allows output to be e-mailed to one or more recipients. Multiple recipients can be specified by separating each address with
a comma. The output is sent as HTML formatted data, just as it appears on the screen. A message can be added to the top of the note
using the "Message before report" text box. HTML tagging can be included in the message.
Report pages:
This option specifies the scope of the amount of data that will be output. If the "Displayed" option is selected, then the output content
will only contain what is in the currently viewed page set. If "Whole report" is selected, then all the data associated with the report will be
output.
Sending charts:
If charts or graphs are included in the output, they can be sent as attachments or in-line images. In-line images require that the charts
be stored on the originating server so they can be referenced with the HTML <HREF> tag that will be created by QLR Manager when
the e-mail is generated. The length of time these charts are retained on the server is a configuration setting applied during installation.
Some e-mail clients may not be able to display images in-line within the e-mail, but should automatically include them as an
attachment.
The safest approach to sending charts or graphs is to send them "As attachment". This is not as convenient for the recipient, but it does
eliminate the possibility that the image may have been deleted from the originating server and provides the widest compatibility with the
myriad of e-mail clients in use today.
E-mail distribution
This distribution option is only available if the report data contains at least one e-mail address field that has been designated as a
Format or use of "Email to:" in the Report Columns section of the Layout panel. Selections for "Email cc:" and "Email bcc:" are also
available when multiple e-mail address fields are present in the report data.
Distribution e-mails are typically used with Custom Layouts that allow tabular report data and charts to be embedded within "free form"
text and HTML. This is an efficient means of executing a large e-mail distribution with the same output sent to all recipients, or output
specifically tailored to each recipient, using e-mail addresses stored in the database.
When distributing e-mail, QLR Manager will attempt to use a direct connection to the SMTP mail server as defined in your
environment's php.ini file. This is usually a server of localhost and port 25. In some situations, the direct socket connect method may
not work correctly. The socket connection method can be bypassed by adding the phrase "useSocket = No" to the bottom of your qlr.ini
file. QLR Manager will then use a standard method for distributing e-mail. The only drawback is the speed at which the e-mail will be
sent. This should not be an issue if you are sending less than several hundred e-mails at a time.
Sending charts:
If charts or graphs are included in the output, they can be sent as attachments or in-line images. In-line images require that the charts
be stored on the originating server so they can be referenced with the HTML <HREF> tag that will be created by QLR Manager when
the e-mail is generated. The length of time these charts are retained on the server is a configuration setting applied during installation.
Some e-mail clients may not be able to display images in-line within the e-mail, but should automatically include them as an
attachment.
The safest approach to sending charts or graphs is to send them "As attachment". This is not as convenient for the recipient, but it does
eliminate the possibility that the image may have been deleted from the originating server and provides the widest compatibility with the
myriad of e-mail clients in use today.
75
QLR Manager User’s Guide
Report Panel
Creating a QLR Widget
A QLR Widget is an HTML link that can be used to allow users to gain direct access to a Query, Macro, User Menu, or Form. QLR
Manager produces the HTML that can be copied and pasted into an existing web page. The HTML is formatted as an HTML anchor tag
with href, title and target attributes:
<a href="WidgetURL" title="QLR Linked Report" target="qlrwidget">click here</a>
When the link is executed, it takes the User directly into QLR Manager, either displaying the results of the Query, Macro, User Menu, or
Form. The QLR connection is established using the logon ID, logon password, database reference, and database server reference that
is active at the time the widget is created. The connection information is passed to QLR Manager as the encrypted part of the widget
link. Although the connection ID and password are encrypted in the link, it is still prudent to use an ID with limited QLR Manager
authorities and does not have update authority to the database when creating the QLR Widget, unless it is a Form Widget which will
require DELETE, INSERT or UPDATE authority depending on the type of form.
If a widget is created for a query or macro that has query variables, the values of those variables are displayed when the widget is
being created. The author of the widget can choose to change the values that will be used when the widget is executed, or leave the
values as blank. When left blank, QLR Manager will prompt the User of the widget for input values when the widget is executed. This
allows for the creation of very flexible widgets.
Widgets for queries are created using either Report Tools or Output Tools. The only place that widgets can be created for Macros,
Menus and Forms is after logging on to the Macros · Menus · Forms suite from the Connect panel. Widget creation is available from
Preview tools when previewing the object. In order to create a widget of any type, the object being created must be saved in order for
QLR Manager to know the logged on Owner and the query, macro, menu, or form Name to associate with the widget.
Depending on which type of widget is created, the resulting output will have access to either the Report or Output Tools. However, for
security reasons, a widget cannot be created from within a widget.
Window open target:
A widget can be defined to open in either the existing browser window when the link is executed or open in a new browser window.
When defined to open in a new window, the target name for the new window is set as target="qlrwidget". A new window contains a
frameset comprised of a header frame, a message frame, and the main content frame. The header frame includes either the Report
Tools or Output Tools option, depending on the type of output.
If it is desired to have various widget links open in separate browser windows, the widget target attribute can be manually edited to
change the name of the target="value" to something different for each link. Javascript can also be used to create a pop-up window with
specific features and is described below.
HTML tag type:
Widgets can be created as either an HTML <a href> tag or an <iframe> tag. When created as an href tag, a text link is displayed that
must be clicked in order to execute the widget. An iframe is an in-line frame and that may be more suitable for some applications, such
as presenting report output in-line within a web page. The content of the iframe is loaded at the same time the web page is loaded.
Output header text:
When a new window is opened, the "Output header text" which appears at the top of the window in the blue header bar can be
specified when the widget is created. The default text that will appear in this area is "QLR Linked Report". This can be changed or
omitted entirely be clearing the value in this input field.
Text for widget link:
The link text that will appear within the HTML href tag is defined in the "Text for widget link" input field. An HTML image tag can also be
entered to allow the link to be associated with an image.
Optional password:
If a value is provided in the optional password field, the User is prompted to supply the password when they execute the widget. QLR
Manager prompts the User by presenting the Query Variables panel. If there are other query variables for which the User needs to
provide input, the password field will appear at the top of the Query Variable panel.
76
QLR Manager User’s Guide
Report Panel
Editing a widget link to add query variable values:
When developing customized applications, it may be desirable to create a widget link and add specific values for query variables to be
used when that link is executed. This can be accomplished by adding the query variable name prefixed with r000 (zeros), such as
r000custnum. Please note that the query variable names should be "URL encoded" to work properly. For example, a query variable
name that contains a space, such as "sales region", becomes "sales%20region". For security reasons, variables that are already
defined in the encoded link cannot be overridden by adding a variable as described below. Some examples are as follows. Note that
there should be no line breaks when real links are created.
http://www.mysite.com/qlr/reportwin.html?r000sales%20region=northwest&Action=qlr_new&isW=yes& formname=query
&qlr_linkid=V1RKb2JGa3ljMmRpUnpscVdWZDRiMkl6VGpCWVVYZ1SlIzUm9aRTZVZwRFFuaGlTRXAwV1ZjMW
http://www.mysite.com/qlr/reportwin.html?Action=qlr_new&isW=yes& formname=query
&qlr_linkid=V1RKb2JGa3ljMmRpUnpscVdWZDRiMkl6VWVVYZ1SlIzUm9aRWhTZVZwRFFuaGlTRXAwV1ZjMW
&r000start_date=2007-10-09
Another way of passing a variable to pages that can process php requests (such as when using Drupal, and the "Input format" is set to
allow PHP code), is to embed php code to processes either an HTML POST or GET argument. The following is an example of placing a
widget within a page called showme.php, where the start date is being passed as a GET variable. The requesting URL is
showme.php?r000start_date=2007-10-09. The widget code within showme.php would be as follows to process the incoming GET
variable. Notice that the php code even checks to make sure that the URL string contains the variable "r000start_date".
http://www.mysite.com/qlr/reportwin.html?Action=qlr_new&isW=yes& formname=query
&qlr_linkid=V1RKb2JGa3ljMmRpUnpscVdWZDRiMkl6VWVwRFFuaGlTRXAwV1ZjMW <?php if
(isset($_REQUEST['r000start_date'])) echo '&r000start_date='.$_REQUEST['r000start_date']; ?>
77
QLR Manager User’s Guide
Report Panel
Javascript pop-up window:
Javascript can be used to create a pop-up window to load the QLR Widget. This will require some manual editing of the widget link to
add an onclick event to call the Javascript window open method:
onclick="window.open(URL,windowName[,windowFeatures]);return false"
Since Javascript must be enabled in the User's browser for the onclick event to be recognized, the addition of the onclick event without
altering the standard href and target attributes will allow the link to be accessed without Javascript. With Javascript enabled, the use of
the return false at the end of the onclick event will cancel the normal href action and load the link into the window opened by Javascript
with the specified features. The following is an example of the modification to the QLR Widget link to use this Javascript method. The
manual addition is in (blue). The entire <a href=...>click here</a> tag must be kept on one line in the HTML page:
<a href="WidgetURL" title="QLR Linked Report" target="qlrwidget" onclick="window.open(this.href,
'qlrwidget','top=100,left=100,width=300,height=200,resizable=1,
scrollbars=1');return false">click here</a>
Note: The "WidgetURL" is the long encoded string that follows the <a href= attribute in the widget link and must be substituted above.
To specify a window feature, add the desired value to the windowFeatures arguments as feature=1(true) or feature=0(false), as
illustrated by the use of resizable=1,scrollbars=1 in the above example. Below are some descriptions of the more common
Javascript window.open features.
Feature
Description
top
The top placement of the window in pixels.
left
The left placement of the window in pixels.
width
The width of the window in pixels.
height
The height of the window in pixels.
status
The status bar at the bottom of the window.
toolbar
The browser toolbar with buttons such as Back and Forward.
location
The location entry field where the URL is displayed or entered.
menubar
The menu bar of the window with options for File, Edit, View, etc.
directories
The browser directory buttons, such as What's New and What's Cool.
resizable
Allows the User to resize the window (recommended).
scrollbars
Enables scrollbars if the output is larger than the window (recommended).
78
QLR Manager User’s Guide
Defining Macros
Defining Macros
Overview
A macro allows the User to execute multiple queries, each with its own layout, in a set of sequential steps. The results of a step or steps
can be e-mailed to one or more recipients.
When a macro is defined, it can be given a general description by clicking the "Describe" icon in the Manage Macros control near the
bottom of the panel. This description will be displayed as an i-nfo icon and provide a hovering description if the macro is used in a User
Menu. If the macro is shared, this can be a useful method to provide a description of the macro's purpose.
Macro Execution Steps
A macro is made up of query execution steps. Each step must contain a query owner and name. If both the Query Owner and Query
Name are left blank, the step will be ignored. Optionally, a Layout Owner and Layout Name can be applied. If a layout is defined, it
will be applied to the results of the query. Any type of query can be used in a step. It is not limited to queries that produce reports. A
macro can have up to 999 steps. Steps can be added and removed by using the "Insert" and "Remove" step controls found in the
bottom of both the Execution Steps and E-mail Specifications sections.
Note: When a SELECT query is used in a macro, paging between page sets is not available. Instead, the entire set of output is
displayed. The limits that determine how large a report can be displayed are the Max displayed rows value in the Report Body section
of the Layout panel and the Maximum output file size setting applied when QLR Manager was installed. These values default to 500
rows and 5 MB. These size limits prevent cases where a query may produce reports of tens of thousands of report rows that the
browser can't handle. If there is a desire to produce reports that exceed the limit, an alternative is to Create a Menu, which contains the
query as a menu item. Of course, executing the query from the query or wizard panels will work as well. These options will provide the
ability to page between page sets in the report panel.
Step Builder Assistant
The Step Builder allows the User to easily find existing queries and layouts to be used in a step. Simply locate the desired entries,
choose the step number to apply the values to, and use the Apply button to copy the query and layout selections into the appropriate
step. If a specific layout does not exist for a query, or if a layout is not desired, the "Based on query" list option can be selected from the
Layout Name selection list. When chosen, the Layout Owner and Name will be left blank.
It is also acceptable to just type the Query and Layout Owner/Name values into the desired step. The Step Builder is merely offered to
make the process of building a macro easier.
Step Title text
The Title text is the text that will be displayed for the macro step when executed. This also serves as the label that can be clicked to
open the expandable/collapsible section containing the macro output. If the title text is left blank for a step, a default title is created
using the Query Owner.Name and, if a layout was specified and it is being previewed, the Layout Owner.Name. The title text can also
include dynamically referenced information. The following are examples of how the title is displayed for different uses.
Default title applied in preview mode:
Step #1 - Query: frank.overstock Layout: frank.overstock
Title displayed in a User Menu:
Query: frank.overstock
Title text applied to the step:
Excess Inventory
79
QLR Manager User’s Guide
Defining Macros
E-mailing the results
E-mail information is entered into the E-mail Specifications section. If an e-mail address is present for a step, the output of that step will
be sent to the recipients listed. In addition, content produced in prior macro steps where the recipients = "add" (all lower case, without
the quotes), will be added to the current step and sent as a single e-mail. This allows for the creation of a single e-mail with multiple
reports. Once an e-mail is sent, the content to be sent is reset. Multiple recipients can be specified by separating their addresses with a
comma.
For example, if the recipients for steps 1 and 2 are entered as "add", and step 3 has real e-mail addresses, the results of all 3 steps will
be sent to the recipient(s) in step 3 in a single e-mail. If step 4 has an e-mail address, the results of step 4 only will be sent to the
recipients specified in step 4.
E-mailing only takes place when using the Run Macro button. When the Preview button is pressed, no e-mail is sent. The preview
only displays the results of the macro in the Preview panel. If a particular step of a macro does not have an e-mail recipient, the results
for that step are only displayed if Preview, Run Macro, or a Menu item is executed.
The e-mail "Subject" can contain dynamically referenced information, such as report column data or query variables.
A single E-mail from address can be specified for all steps in a macro by entering the "E-mail from" information into the General
Specifications section of the Macro panel. A Confirmation e-mail can also be specified resulting in an e-mail sent to this address
containing information about the macro that was executed. This is especially useful to track when other users are executing the macro
as a Menu item.
The manner in which charts are sent in an e-mail is determined by the E-mail charts as setting in the General Specifications section.
Depending on the radio button chosen, charts can be sent as attachments or as in-line images which are really HTML <IMG> tags that
reference files that are stored on the hosting server.
Sending output to a file:
In addition to e-mailing, output can be directed to a file. This is accomplished by specifying file in the Recipient(s) textarea within the
E-mail Specifications section of the Macro panel. For example:
file ../monthlydata/sales
The format is the keyword of file, followed by a space, then the path and the file name. Please note that the file extension is not
included. It is automatically appended to the file name based on the selected Output type. If an output type of Report or Distributed
email is selected, an HTML file will be produced.
The use of the /reports or /graphs directories to store the files should be avoided. These directories are purged on an on-going basis.
Both relative or absolute path references can be used.
Preventing empty reports from being e-mailed:
It is possible to prevent the e-mailing of empty reports. This is accomplished by starting the recipient list with ">0" (greater than zero),
such as >0 fred@yahoo.net. This indicates to QLR Manager to only send a report when at least one row of data is found. This is
designed to work with queries intended to produce a single formatted report. If prior steps utilized the "add" function in the recipient
field, and the step to do the e-mailing uses the ">0" option with no rows found in that step, none of the reports are e-mailed.
File name:
The File name field provides a means to specify a file name for the report attached to the e-mail. A value entered into this field will
override QLR Manager's default naming convention of report_1, report_2, report_3, etc.
80
QLR Manager User’s Guide
Defining Macros
Output types:
Various types of output can be specified for e-mails by setting the Output type. Each macro step can have a different output type
specified. The Output type is found in the E-mail Specifications section.
• Report:
This is the standard report embedded into the body of an e-mail. This output type along with Distributed email are
the only options that will send charts. If charts are present, they are handled in accordance with the "E-mail
charts as" selection in the General Specifications section.
• CSV file:
A Comma Separated Value file is created and sent as an attachment.
• CSV +headings: A Comma Separated Value file, containing the column headings from the report, is sent as a file attachment.
• Excel file:
A Microsoft Excel file is sent as an attachment.
• Excel +headings: A Microsoft Excel file, containing the column heading from the report, is sent as an attachment.
• HTML file:
An HTML file of the report sent as an attachment.
• HTML for Excel: An HTML file of the report, modified to be loaded into Microsoft Excel, is sent as an attachment. When loaded
into Excel, the color and border attributes are maintained.
• Formatted Excel: An XLS file of the report, modified to be loaded directly into Microsoft Excel, is sent as an attachment. When
loaded into Excel, the color and border attributes are preserved. Note that this file format only works in MS Excel
2002 or newer.
• MS Word Doc:
A DOC file of the report, modified to be loaded into Microsoft Word, is sent as an attachment. When loaded into
Word, the color and border attributes are preserved.
• Distributed email: This will send e-mails to recipients based on the email addresses specified in the layout's "Format or Use" field in
the Report Columns section. In order for e-mails to be sent, at least one field has to be identified as an "Email to"
address. See distribution e-mail for information about creating distribution e-mails.
Previewing and running
There are two ways to execute a macro from the Define Macro panel. The first is to "Preview" it. This is accomplished by clicking on the
Preview button or Header tab at the top of the screen. When previewing, all actions are the same as Running the macro except that
no e-mails are sent. This allows the User to see what the macro will produce prior to actually sending e-mails. Each step of the macro
will be displayed in an expandable/collapsible section. Using the Preview button is a good way to confirm that a macro is executing
as desired, prior to actually running it.
The second way to execute a macro is to click on the Run Macro button. When clicked, a confirmation dialogue box will first appear
asking the User to confirm they want to run the macro. E-mails will be sent if recipients are defined in the macro. The content will also
appear in the Preview panel.
The Preview tools icon will appear in the header adjacent to the Preview tab. This allows the User to print, create an HTML file, or email the content of the Preview panel.
81
QLR Manager User’s Guide
Defining Macros
Macro and Query variables
It is possible that the queries used in execution steps contain query variables. If this is the case, values for these variables can be
provided at the macro level and the query level. In both cases, the format for providing values is the same, which is the query variable
name = value. Multiple variables are separated by a comma. It is not necessary to prefix the variable names with the ** or enclosing
brackets [ ] as they appear in the queries themselves, nor is it necessary to include the @length size limit that may be found at the end
of the variable name. For example, if queries in the macro have the variables of {month_number} and {customer_id@7} used with
MS SQL Server, [month_number] and [customer_id@7] for other supported databases, or **month_number and
**customer_id@7 if using the older method, they would be entered as:
month_number=7, customer_id='FRED987'
Note: Variable or input control names may also be prefixed with the User ID that owns the control:
joe01.month_number=7, joe01.customer_id='FRED987'
If these values are entered into the Macro variable values field in the General Specifications section, the provided values will be
applied to all occurrences of these variables in all steps.
When entering query variables that have multiple values, the vertical bar is used to separate each value:
states='NY'|'CO'|'NJ' or month_number=3|6|9
Notice how quotes are used for string values, but not for numeric values.
Creating entries in the Query variable values found in the Execution Steps section will only apply the given value to that step. This
allows the User to override the macro level values for a given query or step. Using the above example, if month_number=7 was input as
a macro variable, it could be overridden in a specific execution step by entering month_number=6 in that step.
If there are still variables that have no value assigned, either by the macro or the query level variable assignments, the User will be
presented with the variable input panel showing the remaining variables that require a value. If the Confirm query variables option
found in the General Specifications section is checked (which is the default value), then even if all variables have been assigned
values, the User will still be presented with the variable input panel. Macro level variables can be changed at that point. However, if a
query level variable assignment is present, the query level values will be used for that particular execution step.
82
QLR Manager User’s Guide
Defining Macros
Custom Macro Layout
The Custom Macro Layout allows the User to position the reports generated by each step of the macro. The report output is
referenced by <reportx>, where x is the step number as defined in the Macro Execution Steps. To reference the output in step 1,
<report1> is embedded in the macro custom text area.
The following is an example of using the Custom Macro Layout text area to create customized output. The intent is to display three
reports side by side of statistics related to youth basketball players. By using query variables, the User to chooses the grade level (4th
grade, 5th grade, etc.) and to set the number of rows that will be displayed in the reports. All 3 queries have the same two query
variables, shown in bold text below:
select ord,concat(first_name,' ', last_name), games, ppg
from player_stat_summary
where grade = '[grade]'
order by 4 desc
limit [limit]
In the Custom Macro Layout text area, the report designer has defined that the output shoud be arranged in an HTML table, with all
three reports appearing side by side:
<table border="0" cellpadding="0" cellspacing="0"><tr>
<td><report1></td><td width="10">&nbsp;</td>
<td><report2></td><td width="10">&nbsp;</td>
<td><report3></td>
</tr><</table>
The only special formatting is the use of the tagging width="10" in an extra table cell between the reports to produce a 10 pixel space
between the reports. Similar results can be achieved by changing the cellpadding or cellspacing values. Assuming that the User
chooses a limit value of 3, the macro produces output of:
In order to provide the User the ability to see more than just the top three players in each report, a link to a QLR Manager Widget will be
added to the bottom of each report. The Widget links are created using the Report Tools "Create a query widget" option. After
executing each query, access the Report Tools link in the QLR header and choose the "Create a query widget" option. Simply copy and
paste the created links into the Custom Macro Layout text area into the appropriate positions to be launched by the href tags. The
widget links appear in red text in the example below.
In addition, values for the two query values that are present in the underlying queries have been integrated into the links by manually
editing the Widget text. The [limit] variable has been manually set to show the top 100 players by including &r000limit=100. Notice how
when query variables are manually added to a widget link, they are prefixed with "r000" (3 zeros) to indicate that these are values that
QLR Manager should recognize as query variables. The grade that is to be used when the widget link is executed has been set to use
the same grade that was selected by the User when the Macro was executed. This was accomplished by using a query variable to
reference the value: &r000grade=[grade]. Query variables that are referenced in the custom text will be replaced with the values
provided by the User when the Macro is executed.
When the widget link is produced, the background color of the resulting page is set to the default background color of QLR Manager.
This setting is part of the link in the format of &QLRbgc=(color). This can be manually edited to display page backgrounds in a different
color. In this case, the background color has been set to &QLRbgc=%23F4F7E7. "%23" is the url encoded value for a "#" character,
which preceeds hex color values used in HTML. The "more" links are configured to open the QLR widget in a new window. The default
arguments for the "window.open" function 'top=100,left=100,width=600,height=400,resizable=1,scrollbars=1' can be modified to
size and position the window as desired.
83
QLR Manager User’s Guide
Defining Macros
The modified Custom Macro Layout text with the above referenced features added:
<table border="0" cellpadding="0" cellspacing="0"><tr>
<td align="center" colspan="5"><p><b>Top performers for the [grade]</b></p></td>
</tr><tr>
<td><report1></td><td width="10"> </td>
<td><report2></td><td width="10"> </td>
<td><report3></td><td width="10"> </td>
</tr><tr>
<td align="right"><div style="width:50px;background-color:#6F6F6F;border:1px solid #000000;
text-align:center"><a href="Javascript:void(0)" title="Top 10 PPG" target="qlrwidget"
onclick="window.open('http://www.mysite.com/qlr/reportwin.html?Action=qlr_new&isW=yes&formname=query
&qlr_linkid=(encoded link removed from widget)&qlr_hdr=Top%20[limit]%20PPG&QLRbgc=%23F4F7E7
&r000limit=100&r000grade=[grade]','qlrwidget','top=100,left=100,width=600,height=400,resizable=1,
scrollbars=1');return false" style="font:bold 11px Verdana,Arial,Helvetica,
sans-serif;color:#FFFFFF;text-decoration:none">more</a></div></td>
<td></td>
<td align="right"><div style="width:50px;background-color:#6F6F6F;border:1px solid #000000;
text-align:center"><a href="Javascript:void(0)" title="Top 10 FG%" target="qlrwidget"
onclick="window.open('http://www.mysite.com/qlr/reportwin.html?Action=qlr_new&isW=yes&formname=query
&qlr_linkid=(encoded link removed from widget)&qlr_hdr=Top%20[limit]%20FG%25&QLRbgc=%23F4F7E7
&r000limit=100&r000grade=[grade]','qlrwidget','top=100,left=100,width=600,height=400,resizable=1,
scrollbars=1');return false" style="font:bold 11px Verdana,Arial,Helvetica,
sans-serif;color:#FFFFFF;text-decoration:none">more</a></div></td>
<td></td>
<td align="right"><div style="width:50px;background-color:#6F6F6F;border:1px solid #000000;
text-align:center"><a href="Javascript:void(0)" title="Top 10 3P%" target="qlrwidget"
onclick="window.open('http://www.mysite.com/qlr/reportwin.html?Action=qlr_new&isW=yes&formname=query
&qlr_linkid=(encoded link removed from widget)&qlr_hdr=Top%20[limit]%203P%25&QLRbgc=%23F4F7E7
&r000limit=100&r000grade=[grade]','qlrwidget','top=100,left=100,width=600,height=400,resizable=1,
scrollbars=1');return false" style="font:bold 11px Verdana,Arial,Helvetica,
sans-serif;color:#FFFFFF;text-decoration:none">more</a></div></td>
</tr></table>
The modified Custom Layout will display as follows (more links intentionally disabled):
84
QLR Manager User’s Guide
Defining Macros
External access
Macros can be executed from outside of QLR Manager. An example of such access could be a desire to run a batch of daily reports
from a cron job. This capability must be enabled by checking Allow external access in the General Specification section. Access can
also be limited to a specific IP address, or IP addresses starting with a particular value, by entering a value into the IP access mask
field. For example, to limit external access to IP addresses starting with 68.122, this value could be entered into the IP access mask
field.
External access is accomplished by entering the following URL pattern, that contains HTTP Get variables:
For URL execution:
Pattern: mydomain/mydir/runmacro.php?macroowner=(the macro owner)&macroname=(the macro name)
Example: www.baitshop.com/qlr/runmacro.php?macroowner=frank&macroname=reorder
For cron jobs that do not support URL execution, the values can be provided as command line arguments separated by spaces. As
many query variable name/value pairs can be added as needed. If arguments contain spaces, the url encoding value of %20 should be
used for those spaces.
Pattern: runmacro.php [macroowner] [macroname] [query variable name] [query variable value]
Example: runmacro.php frank reorder month 12 year 2005
In some instances, a cron job may need to reference the directory where QLR Manager is located. In this case, a small script can be
written and executed from the cron job that changes the directory and executes runmacro:
cd /var/www/html/reporting
/usr/bin/php -q ./runmacro.php rob daily_ticket_counts
The runmacro.php execution file is found in the main QLR Manager directory.
There are two variables that must be submitted, macroowner and macroname, and must be lowercase. These identify the Macro Owner
and the Macro Name. If a name contains a space, the URL escape code of "%20" must be used to represent the space. If a macro
contains query variables, these values can be supplied as additional Get variables. For example, if in the macro example above there
was a query variable called "month_number", it could be added to the end of the URL string as: &month_number=7. Notice how the **
that is used to identify a query variable in the query is not included. Variables that are entered in the URL will override macro level
variables that are defined in the macro. They do not override the variable values that are defined as Query variable values for each
execution step.
When runmacro.php completes successfully, it prints a response that says "runmacro.php successfully completed". This can be
controlled by adding an additional HTTP GET argument of &response=your_text. The response text will be returned, replacing
underbars with blank spaces. For example, &response=Invoice_report_created would print "Invoice report created" to the screen.
Messages can also be suppressed from being sent by using &response=silent.
These HTTP Get variables can also be submitted as HTTP Post variables from an HTML form. The form action would reference
mydomain/mydir/runmacro.php and the values would be submitted with the form.
When the macro is run externally, the results of the steps are e-mailed to the recipients as specified in the macro. The output for
execution steps without e-mail recipients defined will be ignored. Therefore, if a macro does not contain any e-mail recipients, no output
will be seen. It could be that some steps in the macro are action queries, such as INSERTs or UPDATEs. These commands will be
executed, but without any tracing of what actions occurred. This differs from running a macro from within QLR Manager, where this type
of output would be displayed in the Preview panel.
For security reasons, the User is not asked to expose their User ID and password when executing runmacro.php. Instead,
runmacro.php is executed with the same User ID, password, database/schema and server as when the macro was saved in QLR
Manager. The password is saved as encoded data to prevent exposing the password here as well.
Note: If a user changes their database password, they must retrieve and re-save just one of their macros. This will update the database
password associated with all their macros.
85
QLR Manager User’s Guide
Creating Menus
Creating Menus
Overview
Menus can be created to allow users to select and run both queries and macros. In addition, other existing menus can be added as a
menu item. Menu items are part of a "section". A menu can have up to 10 expandable/collapsible sections. Menu items are executed by
clicking the Run button or the menu item title.
Titles & Attributes
The Titles & Attributes section of the Create Menu panel allows the User to define a Page Title for their menu. HTML tagging can be
used if desired. The Menu Creator can control the text characteristics by using the font control options that are present under the Page
Title input area.
Section Titles can also be defined in the Titles & Attributes input area. A menu can have up to 10 expandable/collapsible sections. Like
the Page Title, HTML tagging can be used when defining section titles. At the bottom of the section titles, are controls for selecting the
text attributes. If menu items are defined for a particular section number and a section title is not present, a default title of "Section
(number)" will be created.
Sections in a menu can be expanded and collapsed by clicking the Section Title. Whether a section is open, allowing visibility to the
items within the section when the menu page is first loaded, is controlled by the Visible onload checkbox.
The text characteristics for the menu items can be selected with the Item Title Attributes controls at the bottom of the Titles &
Attributes area. This will change the settings for all the items in the menu.
When queries, macros and menus are saved, a description can be entered. These descriptions can be presented to the User in the
form of a hovering description in the menu itself. The Description icon location determines the placement of these i-nfo icons relative
to the menu items, or they can be omitted. If no description is available for the item, no icon will be presented.
Menu Item Details
A menu item is either a query, with an optional layout, a macro or a menu. Each item is assigned to a particular section number. When
the menu is saved and retrieved from the database, the items are sorted and presented in Section Number order. A menu can contain
up to 999 items.
Each item is assigned to a section number by choosing the section number from the selection list. The type of object must be specified
for the item, along with the Object Owner and Object Name. If the menu object is a query, a Layout Owner and Layout Name can also
be specified, but not required. If a layout is provided for a macro or a menu, it is ignored.
The default Image that precedes the menu item title is a Run button. The Image is specified with the path to the file immediately
followed by its (WIDTHxHEIGHT):
qlr_manager/images/run.gif(36x17)
The path to the image is relative to the directory where QLR manager is installed and it is recommended a separate folder be created
outside the QLR directory structure to hold custom image(s). This allows QLR Manager to be upgraded and preserve the reference to
the directory with the custom image(s). It is also suggested that the pixel dimensions be included with custom images to allow the
browser to allocate the proper amount of space for the image as the page is being rendered. The Image text input can be left blank if
no leading image is desired for a particular menu item. This will align the menu item title directly beneath the Section Title. A
transparent spacer gif is provided that can be defined with variable (WIDTHxHEIGHT) to achieve any desired indentation and vertical
spacing:
qlr_manager/images/spc.gif(20x20)
The title for each menu item is entered into the Title text input. Item titles can contain HTML tagging when necessary, but it is probably
easiest to control the overall appearance of item titles by using the controls in the Item Title Attributes group. If a title is not provided, a
default title is created using the object type, owner and name, such as "Macro Frank.daily reports". If the Object Name provided cannot
be found, an error message will be displayed for that item when the page is previewed or displayed as a working menu.
Menu Builder Assistant
The Menu Builder allows the User to find existing queries and layouts, macros, or menus to be used as a menu item. Simply locate the
desired entries, choose the item number to apply the values to, and use the appropriate Apply button to copy the selections into the
targeted item number within Menu Item Details. The Menu Builder will also set whether the chosen menu item is a query, macro or
menu. If a specific layout is not desired for a query, "Based on query" should be selected from the Layout Name option list. When this
value is chosen, the Layout Owner and Name will be left blank.
It is also acceptable to type the Object Owner and Object Name values directly into the desired step. When typing these entries, care
should be taken to ensure the correct Object Type is selected. Using the Menu Builder simplifies this process.
86
QLR Manager User’s Guide
Creating Menus
Previewing
When a menu page is being constructed, its appearance can be validated by pressing the Preview button or Preview Header tab.
This will build and display the menu that is currently being created. Menu items cannot be run from the Preview panel. If a Run button
is clicked, an alert is presented reminding the User that menu items cannot be executed in Preview mode.
Active Menus
After creating and saving menus, a user can log on to the "Queries · Layouts · Reports" function and access the User Menu or Menu tab.
Clicking this tab in the header will display active menus. If the ID has sufficient authority, the User can choose from the Existing Menus
list to select and load a menu. Clicking a Run button or the menu item title will run the menu item.
If using the Enterprise Edition of QLR Manager, the User's profile can be set to load a default menu when the Menu or User Menu tab
is clicked. Additionally, the User's profile can be set to omit the Existing Menus selection control. This provides the capability to limit a
User ID's access to a single, predefined menu. The configuration tool used to define these User Profiles is User ID administration. This
can be extremely useful to restrict a user's access to specific data. An example could be a menu created for a customer which limits
them to running queries and macros against their data and does not provide access to any other queries, macros, or menus.
If a user has any saved queries or macros, a menu of these objects, called *My_Menu* will automatically be created for the logged in
user ID containing these items. This provides two expandable/collapsible sections, one containing the queries and the other containing
the macros.
87
QLR Manager User’s Guide
Designing Forms
Designing Forms
Overview
The Design Form panel supports the creation of "Forms" that allow for the editing of data found in a database table. Forms can be
defined that:
•
•
•
•
Add records
Edit existing data
Edit existing data, with delete capability
Delete records
Once a form is created and saved, in order to use it, it must be executed from a Menu or as a QLR Widget. Form widgets are created
using Preview tools which is available when designing a form and viewing it in Preview mode. The Design Form panel supports
the creation and previewing of a form and its associated search panel to define its layout and behaviors. Although previewing the Form
displays live data, no data can be added, edited or deleted in Preview mode.
When a form is designed to Edit or Delete data, the Form Designer is used to design the Form and also the characteristics of the
Search Portal, which is used to find the records to be edited or deleted.
Using the Form Designer, forms can be created that range from allowing a power user to select all records and edit all fields, to tightly
limiting access to specific data that can be selected for deleting or editing. When a Delete Form is created, data fields are displayed as
read only text. No data editing is permitted.
The Designer's User ID and password are associated with a form, so when the Form is accessed from a menu or a widget, it is
accessed using the Designer's connection credentials. This allows for other users to use the Form to edit data in tables for which they
don't have Insert, Update or Delete privileges. If the Designer's password changes, the Designer must login to QLR Manager, retrieve
and save a single form. This will update the password associated with all forms belonging to the Designer's User ID.
Note: Edit and Delete forms can only be created for tables that contain at least one unique index, or where a set of columns can be
selected to Define a unique identifier for each row of data in a table.
Creating a Simple Form
A form to edit data in a table can be created with just a few mouse clicks.
After clicking on the Design Form tab:
1
2
3
4
5
Choose a database / schema where the table resides.
Select a table and click the Get Table button.
Click either the Preview tab or Preview button. The default search panel will appear.
Click the Search button. A 10 row Tabular form will appear in Preview mode.
This Form can be saved on the Design Form panel. It can be accessed and run from the Menu panel by retrieving "My menu",
the Form can be built into a custom menu using the Create Menu panel, or a QLR Widget can be created using Preview tools.
Example of a Simple Edit Form:
88
QLR Manager User’s Guide
Designing Forms
Designing a Form
Forms are associated with a database table. This requires that the Form Designer first select the database and/or schema where the
desired table resides, and then choose the table from the table list. After selecting a table, click the Get Table button.
Tables must have at least one unique index to be used with a form. QLR Manager will perform this check when the table is retrieved. If
no unique index is found, an error message will be presented and no form will be created.
The default behavior is to add all of the columns (up to the first 50) from the table into the Form Designer. If the intent is to create a form
to edit a limited number of columns of data, it may be preferable to select the "None" radio button for the "Initially populate Form
elements for selected Source table with" and manually add only those columns to be included in the Form. The Form Elements - Basic
Formatting section supports the addition, deletion and rearranging of the data columns that are part of a form.
Forms can contain the following types of elements:
• Label and input field pairs associated with a column of data in the table being edited. The default Form layout of "Tabular"
selected in the General Form Characteristics section will display the labels as column headings. When a "Free Style" layout is
selected, the label positioning in relation to the input field can be defined by the Form Designer.
• Label text only provides a means to add a custom label without an associated input element. It may be used as a heading or
explanation preceding a group of related form elements or for whatever purpose the Form Designer deems appropriate. This
selection is only available when "Free Style" is used as the Form layout.
• Horizontal rule is provided to add some separation between groups of form elements. This selection is only available when "Free
Style" is used as the Form layout.
Database & Table Selections
Source database and schema:
In order to locate the table to create a form, the Form Designer must first navigate to the desired database and/or schema. Changing
the current selection will automatically update the table list.
Source table:
Once the desired database/schema has been selected, the table upon which the Form is based must be selected. The table is retrieved
by clicking the Get Table button. In order to create an Edit or Delete form for a table, the table must have at least one unique index
defined, or the Form Designer must select a set of table columns that will uniquely identify each row of data in the table.
Defining a unique identifier:
When a unique index for a table cannot be found, the Design Form panel will display a multiple select list that contains a listing of all
the columns in the table. The Form Designer must select one or more columns whose values will uniquely identify each row of data in
the table. Once these columns have been selected, clicking the Define button will cause QLR Manager to check the data in the table
to determine if the selected columns uniquely identify all the existing rows of data. Unique identification is necessary to find the correct
rows for updating and deleting information. When uniqueness cannot be determined, only an "Add" form can be created for the table.
Initial form field population:
When a table is first selected and before clicking the Get Table button, a decision should be made whether to start with the default of
all columns in the table (up to 50) or no columns. Importing 50 columns from a large table will slow the web browser's performance. If
the Form Designer intends to create a form with a limited number of columns of data, it would be more efficient to select "None" for the
"Initially populate Form elements for selected Source table with" control. Regardless of the choice, table columns can be added,
removed, and rearranged by using the controls found in the Form Elements - Basic Formatting section of the Form Designer.
Detail form selection for a Master/Detail form:
A Master/Detail form combines two forms with related information. The Master Form will be displayed as a Free Style form and the
Detail Form will be displayed as a Tabular form. An example may be a Purchase Order, where the main body of the Form contains
general information about the Purchase Order, and the bottom of the Form contains details about each item being ordered.
In order to create such a form, the Detail Form is created first. Even if the Detail Form is defined as a Free Style form, it will be treated
as a Tabular form when used in a Master/Detail Form. The Detail Form name selection list will be populated with all forms belonging to
the User who is designing the Form. This option is for selecting the desired Form for use as the Detail Form.
Once the Detail Form has been selected, the Design panel will be repopulated with 5 pairs of selection lists that contain all of the fields
in both the Master and the Detail tables. The Form Designer then selects the fields that define how the data in the two tables is related.
Up to 5 field pairs can be defined for this relationship. An example could be that the Master table contains a field called PO_NUM and it
is related to the PO_NUMBER field found in the Detail table.
89
QLR Manager User’s Guide
Designing Forms
General Form Characteristics
The General Form Characteristics section allows the Form Designer to change common attributes that apply to the entire Form.
Form layout:
There are three basic form layouts that can be created. These are Tabular, Free Style and Master/Detail Forms.
• Tabular Form is one that shows multiple records at one time in a table layout, similar to a spreadsheet. Each row is a different
record from the table, and each column is a different field within the table. A 10 row Tabular form is the default format.
• Free Style Form works with one record of data at a time. When this layout style is selected, the Form defaults to display all data
fields aligned vertically, preceded by the table column name.
• Master/Detail Form is one that combines the two previously mentioned form layouts. The top of the Form is the Master data and is
presented as a Free Style layout. The bottom part of the Form is a Tabular layout of the Detail information. The data is linked
together by specify how the two sets of data are related. A typical example of a Master/Detail Form is a Purchase Order. The Master
information is general information about the Purchase Order. Each line item of purchase data is the Detail information. This type of
form has two sets of buttons for moving between records. One set moves between different occurrences of the Master records, the
other moves between the Detail records that are associated with the current Master record.
Form use:
Forms can be designed for various types of updates.
• Add Form is intended to insert new records into a table. Data is entered into a form and then the "Add" button at the bottom of the
screen is clicked to actually add the information. If the data being entered is repetitive in nature, including the Add - Provide a copy
data option in the Form may be beneficial. If within the database definition itself, a table column has been defined with default
values, QLR Manager will populate the Form with the default values.
• Edit Form is used to edit existing information. When designing a form for editing, the characteristics of the Search Portal, which is
used to locate existing data, should also be defined.
• Delete Form is used to delete records from a table. When designing a form to perform deletes, the characteristics of the Search
Portal, which is used to locate existing data, should also be defined. Prior to deleting data, the User is asked to confirm the delete
request.
When designing a form, it is only necessary to have database authority to SELECT data from the table for which the Form is being
designed. However, when a form is used, the connection ID to the database is that of the Form Designer - the User ID that saved the
Form. Therefore, a form with Add capability requires that the Form Designer has INSERT authority for the form table, forms with Edit
capability requires UPDATE authority, and forms that can Delete records requires that the Form Designer has DELETE authority for the
table.
Form use options:
Add and Edit Forms can be enhanced by applying additional options:
• Add - Provide a copy data option: After a record is added using a form, the User is presented with a blank form to add another
record. When this option is selected, a checkbox is added to the bottom of the Form. If checked by the User, The Form presented
after adding a record is repopulated with the data that was just added. This is useful when entering repetitive information where only
a few data elements have changed.
• Edit - Include Add capability: This allows the User to add a record when in Edit mode. A control is added to the bottom of the Form
to either create a new record from scratch, or to copy existing data as the basis for the new record.
• Edit - Allow for Delete: This option adds a delete checkbox to a form in edit mode. This allows the User to either edit or delete data
from the same Form.
Optional password:
A password can be assigned to a form which will prompt the User to supply the password prior to being granted access to the Form.
90
QLR Manager User’s Guide
Designing Forms
General attributes:
The General attributes allow the Form Designer to set the Form background and border colors, form width, inner border display, and
how the Form will align in the browser window.
The "Specify form width" option is useful when a form contains multiple sections. The default size of each section depends upon the
form elements included in the section, their width and positioning. This setting allows the Form Designer to set all sections to a uniform
width. The width will be honored as long as a section's content is not wider than the provided width in pixels.
If inner borders are desired, checking "Display inner borders" will display a one pixel border around each cell in the Form. This is
generally better suited for a Tabular form, but it can also be used for a Free Style form. This option is also useful when designing a Free
Style form to see where form elements are being placed within the multiple columns in the Form.
Form buttons:
The Form buttons controls allow the Form Designer to define the appearance of the buttons used in the Form. When the "Use default
button style" checkbox is checked, the Browser's default button style is used.
Tabular form:
These options are specific to a Tabular form layout. In addition to setting alternate row coloring, the number of rows of data to be
displayed at any one time can be defined ranging from 1 to 100 rows. In general, the more columns of data that the Form is used to
edit, the smaller the row setting should be to minimize page load time. In order to move between "page sets", the User can click the
appropriate navigation buttons (First, Back, More, Last) found above the Form. Unavailable options are grayed out.
Title text:
The Title text options allow the Form Designer to control the appearance of the Form title. The Form title appears above the Form and
also above the Search Portal that is produced when an Edit or Delete Form is defined. The default value populated for the "Form title" is
the name of the table selected for editing. The title can be edited or omitted by over-typing or clearing the value in the "Form title" field.
Label text:
The Label text options control the appearance of the text labels that are associated with each of the data fields that are part of the
Form. In addition to controlling the appearance, there are a few additional settings worthy of note.
The Required prefix will appear at the beginning of each label that is associated with a data element that has been defined as Input
req'd. HTML tagging can be used in this field. For example, <font color="#FF0000"><b>*</b></font> can be used to create a bold red
asterisk prefix, such as *. Spacing can also be added by using the HTML entity of &nbsp;. When input is required for certain fields in the
Search Portal, this same prefix will be used with those fields as well.
The Free Style suffix is added to end of all the field labels when a Free Style form layout is selected. HTML tagging can be used when
defining the suffix. The suffix is not applied to the Labels when a Tabular layout is specified.
The default alignment of all the Labels is set by adjusting the Align and Vertical align settings. The alignment setting can be
overridden at the individual form element level.
Input fields:
These options control the overall appearance of the input fields found in the Form, including the text color, size, font face and text
decoration attributes. The Border style and Border widths that surround input elements can also be set. Note that how border settings
are rendered can vary among different browsers.
The default alignment of all the input fields is set by adjusting the Align and Vertical align settings. The alignment setting can be
overridden at the individual form element level.
Help links:
Each element label in a form can have help text associated with it. There are two types of help. Tooltip help, which is visible when the
User places the mouse pointer over the label text, and URL based help opened in a pop-up window when the label text is clicked. This
set of options controls the color and text decoration (Bold, Underline, Italic) of the label text defined as links, and also the
foreground/background colors of the tooltip help. More information about defining URL based links and tooltip help text is described in
the Form Elements - Other Properties section.
91
QLR Manager User’s Guide
Designing Forms
Optional text:
Additional text can be added to the top of the Search Portal, and to the top and bottom of the Form. This optional text provides
additional flexibility for the Form Designer to add instructions or convey any additional information. This text can contain HTML tagging.
The font-size and font-family applied to this optional text is the same as defined for the Label text. These attributes can be easily
overridden by applying different styles to a nested DIV. For example:
<div style="font-size:12px;font-family:Verdana,Tahoma,Arial,Helvetica,sans-serif"> optional text <div>
The Search Portal with optional text added:
Customer
This is an example of "Optional text to include above the Search Portal". It can be formatted with HTML tagging and will stretch across the entire page.
The Form Designer can control the width by adding HTML <br> tags or enclose the text inside a <div tag with style="width:400px">. In this case, the
text color has been set to dark blue with some bold emphasis.
The Form with optional text added above and below:
Customer
This is an example of "Text or instructions to include above the Form". It can be formatted with HTML tagging and will stretch across the entire page.
The Form Designer can control the width by adding HTML <br> tags or enclose the text inside a <div tag with style="width:400px">. In this case, the
text color has been set to dark blue with some bold emphasis.
This is an example of "Text or instructions to include below the Form". It can be formatted with HTML tagging and will stretch across
the entire page. The Form Designer can control the width by adding HTML <br> tags or enclose the text inside a <div tag with
style="width:400px">. In this case, the text color has been set to dark blue with some bold emphasis.
92
QLR Manager User’s Guide
Designing Forms
Widget behavior:
This set of options allows the Form Designer to control how an "Add" form behaves when it is used in a QLR Widget. An example of a
form used to collect user input could be a Send Feedback or Contact Us form.
When "Display message text" is selected, the defined message text, which can contain HTML tagging, is displayed after the Add form is
successfully submitted and processed. This form can also contain replacement references to the columns found in the form, such as:
[first_name],<br />
Thank you for submitting your comments. We will contact you shortly.
The font-size and font-family applied to this message text is the same as defined for the Label text. These attributes can be easily
overridden by applying different styles to a nested DIV. For example:
<div style="font-size:12px;font-family:Verdana,Tahoma,Arial,Helvetica,sans-serif">
[first_name],<br />
Thank you for submitting your comments. We will contact you shortly.
<div>
When the "Execute listed URL" is selected, QLR Manager will direct the User to the URL entered. Replacement references can also be
used here and will be URL encoded, such as:
www.mysite.com/php/thankyou.php?last=[last_name]&first=[first_name]
Or simply direct the User to a static thankyou.html page:
www.mysite.com/php/thankyou.html
These behavior options only apply to a QLR Widget. When the same Add form is run from the Menu panel within QLR Manager, it will
present another copy of the Add form after the Update button is clicked. When the form is a Tabular layout, data from the first record
in the form is used as the replacement values. When a Master/Detail layout is used, only values from the Master record will be
replaced. The reference to form field names is case sensitive and is dependent upon how the fields have been defined when the
database table was created. Generally, these will be lower case.
In order to test these behaviors, the Form Designer must first save the Form, then create the Widget from the Preview panel by
launching Preview tools.
93
QLR Manager User’s Guide
Designing Forms
Form Elements – Basic Formatting
The Basic Formatting section is used to define which table columns (Available elements) will appear in a form, their order, and basic
characteristics.
Available elements:
The list of available elements is composed of the columns found in the Form table. In addition, for a Free Style form, "Label text only"
and "Horizontal rules" can be added to the Form. If these are added to a Free Style layout which is then changed to a Tabular layout,
they are ignored when the Tabular layout is rendered.
Column actions:
The Column actions are used to manipulate the Available elements. Actions can be rolled back one at a time by clicking the Undo
button.
• Add column works by first selecting an element from the Available elements list. Select the "Add column" Action, and then click
the Apply button. The selected element will be added to the bottom of the existing form elements. A table column can only be
added to a form once.
• Insert before works similar to the "Add column" Action. First select an element from the Available elements list. Choose the
"Insert before" Action, then select the Col # of an existing element and click the Apply button. The selected element will be added
before the selected Col # element. A table column cannot be inserted if it is already used in the Form.
• Move before works with elements that are already part of the Form. Choose the name of the element to be moved from the
Available elements list. Select the "Move before" Action, then choose the Col # the element should be moved in front of and click
the Apply button. If moving a "Label text only" or "Horizontal rule" and more than one of those types is present in the Form, QLR
Manager will prompt you to click on the specific element you wish to move after you have clicked on the Apply button.
• Replace works similar to the "Insert before" Action. First select an element from the Available elements list. Choose the "Replace"
Action, then select the Col # of the existing element to be replaced. Clicking the Apply button will replace the selected Col #
element with the selection from the Available elements.
• Delete (Col #) will remove a form element. Select the "Delete" Action, choose the Col # to be deleted, then click the Apply
button. This Action does not reference the Available elements list and explicitly deletes the selected Col #.
Column number:
The Col # refers the column number of an element in a form. It is used as a reference to apply many of the Column actions described
above.
Form element:
The Form element column is a list of elements that have been defined to be part of the Form. These are followed by an icon that
indicates the type of data related to that form element. Mousing over the icon will provide additional information about the element.
Section:
Form elements can be grouped into separate expandable/collapsible "Sections". An example of the use of sections is the
Design Form panel itself. It is divided into multiple sections, such as Database & Table Selections, General Form Characteristics,
etc. Using multiple sections may be desirable when a form contains many form elements. It is also helpful when complicated Free Style
form layouts are designed. A form is comprised of elements organized into HTML table columns. Each section is comprised of a
separate HTML table. Grouping form elements into separate sections may help solve some layout issues.
The default section number for a form element is zero, which is the equivalent of no section. QLR Manager allows for elements to be
placed into sections 0 to 5. Sections 1 to 5 can be given a title, and their behavior can be defined in the Section Title & Opening
Behavior section of the Form Designer.
Label alignment:
The Label alignment can be used to override the global Form level label alignment setting, which is set in the General Form
Characteristics section. The default value is the global "Form" level setting.
Label text:
The Label text is the text that is associated with an input field. The default value is the table column name.
94
QLR Manager User’s Guide
Designing Forms
Input required:
When the Input required checkbox is checked, the field label in the Form will be prefixed with the Required prefix as defined in the
General Form Characteristics section of the Form Designer. QLR Manager examines the table being edited for data fields where nulls
are not allowed. These fields are automatically checked, and cannot be unchecked. If any fields in the Form require input, then the
designated prefix, followed by the phrase "Input required", will appear at the bottom of the Form.
Upon submission of the Form to the server, QLR Manager will check to make sure that data is present in that field. If required data is
missing, an error page is displayed stating which fields are missing input. Clicking the Return button on the error page will take the
User back to the Form.
Input alignment:
The Input alignment can be used to override the global Form level input alignment setting, which is set in the General Form
Characteristics section. The default value is to use the "Form" level setting.
Optional input control:
When QLR Manager creates an Add or Edit Form, the default data entry area is a simple text input field. This can be changed to use an
Input Control. If the Form Designer wishes to use an input control that they authored and saved, it is only required to enter the Input
Control name. If the use of an input control owned by another User ID is desired, the referenced control must be prefixed using the
owner ID.control name format, such as jeff01.customer list. When the cursor is in one of the Optional input control fields, pressing
the "Ctrl" key will present a small window that contains a list of input controls. This can be used to quickly reference and apply available
controls:
There is also a set of special QLR internal input field types that can be entered as an Optional input control. These are listed in the
Input Control pop-up as the first selections for the current logged on Owner:
• qlr_read_only will create "Read Only" data, which means the data will be displayed in the Form as text, without the ability to alter it.
When a Delete Form is created, all input fields will be displayed as "Read Only".
When qlr_read_only or qlr_read_only_wrap are used, PHP formulas can be added to manipulate the appearance of the displayed
data. The formula is entered after the qlr_read_only (or wrap) keyword, preceded by a blank space. The value of the form element is
referenced by $value. Some examples:
Display the first 50 characters only: qlr_read_only_wrap $value=substr($value,0,50)
Format to a specific date format: qlr_read_only $value=date('Y-m-d',strtotime($value))
• qlr_read_only_wrap also presents "Read Only" data. The difference is that the text will be word wrapped within the boundaries set
by the Input width setting for the field.
See the help for qlr_read_only above for information about using formulas to manipulate how data is displayed.
• qlr_numeric creates a text field that accepts numeric characters only, which are "-.0123456789". This can also be accomplished by
creating a numeric only Input Control.
• qlr_image_from_db allows an image for which the content is stored in the database to be added to a form. Image size arguments
(height followed by width) can be provided after qlr_image_from_db as additional arguments. Entering qlr_image_from_db 100 120
will display the image as 100 pixels high and 120 pixels wide. If qlr_image_from_db 100 is specified, the 100 will be used for both
dimensions and the image will be displayed as 100 pixels high by 100 pixels wide. If no size arguments are added, the image will be
rendered as its native size.
• qlr_image_from_file allows an image for which the content is a file to be added to a form. Image size arguments (height followed
by width) can be provided after qlr_image_from_file as additional arguments. Entering qlr_image_from_file 100 120 will display the
image as 100 pixels high and 120 pixels wide. If qlr_image_from_file 100 is specified, the 100 will be used for both dimensions and
the image will be displayed as 100 pixels high by 100 pixels wide. Without the size arguments, the image will be rendered as its
native size. If the field data does not contain the required path to locate the image, it can be added as a third argument surrounded
by single quotes, such as qlr_image_from_file 100 120 '../../images/'. Note how the ending slash or backslash (depending on the
server operating system) is part of the path reference.
• qlr_upload_to_db creates a file upload control. This will upload file content from the User's workstation to the field it is mapped to.
The field must be defined to be large enough to accept the anticipated data, or data truncation will occur.
95
QLR Manager User’s Guide
Designing Forms
Important: The number of bytes of data that can be uploaded are limited by two php.ini settings, those being "upload_max_filesize"
and "post_max_size". upload_max_filesize limits the size of each individual file. post_max_size limits the entire amount of data
uploaded from any given page. This means that Tabular form layouts which may contain multiple upload controls are more likely to
truncate data uploads unless the php.ini file is updated accordingly.
When this control is used in a form type of Edit, the existing image will be displayed above the upload control. File uploads have
been tested with Mysql Blob data types, the Oracle Blob data type using Oracle 10g, Postgres Bytea data type, and the MS SQL
Server data type of Image.
• qlr_upload_to_file creates a file upload control. This will upload file content from the User's workstation to a file of the same name
on the server. A path argument can be added to specify the path where the file should land, such as qlr_upload_to_file
../../images/. It is not necessary to surround the path with quotes. The name of the uploaded file, without the optional path, will be
added to the field it is mapped to. When this is used in a form type of Edit, the existing image will be displayed above the upload
control.
Important: The number of bytes of data that can be uploaded are limited by two php.ini settings, those being "upload_max_filesize"
and "post_max_size". upload_max_filesize limits the size of each individual file. post_max_size limits the entire amount of data
uploaded from any given page. This means that Tabular form layouts which may contain multiple upload controls are more likely to
truncate data uploads unless the php.ini file is updated accordingly.
• qlr_hide_date allows for a date field to be part of a form, but not visible in the Form. When the data record is added or updated, the
current systems date, such as 2009-06-22, is entered into this field.
• qlr_hide_datetime allows for a date-time field to be part of a form, but not visible in the Form. When the data record is added or
updated, the current systems date plus time, such as 2009-06-22 09:34:11, is entered into this field.
• qlr_hide_timestamp allows for a field that is used for a Unix timestamp to be part of a form, but not visible in the Form. When the
data record is added or updated, the current timestamp, such as 1248459518, is entered into this field.
• qlr_hide_ip allows for a field that is used for an ip address, such as varchar(15), to be part of a form, but not visible in the Form.
When the data record is added or updated, the ip address of the connected User, such as 69.105.56.234, is entered into this field.
• qlr_hide_userid allows for a field that is used for tracking a User ID, such as varchar(64), to be part of a form, but not visible in the
Form. When the data record is added or updated, the User ID of the connected User, such as jeff01, is entered into this field.
Notice how the above hidden fields can be added to tables to help track who was the last person to create or alter data.
If the name of the Input Control, or a special keyword cannot be found, the default value will be a simple text input field.
Input width:
When QLR Manager creates a form, the default data entry area is a simple text input. The default size of that text box is determined by
the field data type. A text field is the lesser of 16 or the field size as defined in the database. A numeric field type is 8 characters wide,
and a Date/Time field type is 10 characters wide. This Input width control provides a means to override the default widths. The width
value is an approximation of the number of characters that will be visible, and is used by QLR Manager to calculate the pixel width of
the input fields. What is actually visible in the input field is dependent on the selected font face, font size and the characters themselves
for variable width fonts (WWW takes up more pixel width than iii).
96
QLR Manager User’s Guide
Designing Forms
Audit trail:
A table may contain important information where it is necessary to track changes to certain data fields within the table. QLR Manager
supports this by allowing individual fields to be tracked in an audit table called qlr_form_audit_trail. When the Audit trail checkbox is
checked for a given data element, the original value and the new data value are added to this table. The following data is recorded as
part of the audit trail:
table_name
table_col
form_name
form_owner
host
dbspace
form_action
userid
ip_address
change_date
trans_num
original_data
new_data
varchar(64)
varchar(64)
varchar(64)
varchar(24)
varchar(60)
varchar(64)
varchar(24)
varchar(64)
varchar(15)
datetime
smallint
text
text
not null,
not null,
not null,
not null,
not null,
not null,
not null,
not null,
not null,
not null,
not null,
null,
null
--------------
name of the associated table
name of the table column
form name
form owner
database host
dbspace where associated table resides
action performed on data(insert,update,delete)
userid performing the changes
user ip address
date and time of change
transaction number for that batch update
original data in the field
new data that replace original data
Any change to a data element from an Add, Edit or Delete Form are entered into this table. The data will reside in this table until
manually removed by someone who has the authority to do so.
Multiple audit trail entries, all occurring from a single form, will have the same change_date tracked to the second. Oracle may require
an update to the way dates are displayed in order to query the data in this table. An Example of adjusting for Oracle is: alter session set
nls_date_format='DD/MON/YYYY HH24:MI:SS';
97
QLR Manager User’s Guide
Designing Forms
Form Elements – Other Properties
The Other Properties options are intended to enhance the appearance and layout of Free Style forms. Tooltip or URL based pop-up
help can also be defined for both Free Style and Tabular layouts.
Free Style column set:
Free Style forms are based upon an HTML table layout. Tables are comprised of columns and rows of table cells. The elements within
a form are placed into these table cells. When the Label associated with an input field is positioned to the left of the Input field (default),
the two elements take up two columns in the table. Since QLR Manager considers the Label and the Input field as a pair that comprise
a form element, the two columns are considered a single (1) column set, or colset. In the example below, the form elements are all in
colset 1, which actually occupy two columns in the table as illustrated with "Display inner borders" checked in the General Form
Characteristics.
If the Free Style colset value for the First name field is set to 2, this field will be placed in the same row as the Last name field and
occupy column positions 3 and 4. Every time that the colset value is greater than the preceding form element's colset value, the form
element will be placed into a pair of adjacent columns on the same row as the previous form element. QLR Manager fills out a form by
placing items into the table starting in the top left corner and adding adjacent elements to the right for each incremented Free Style
colset value. When a new colset of less than or equal to the previous elements value is applied, a new row is started.
Label colspan:
The Label colspan provides a means to define how many columns across the Form a label will span. If the Label colspan for the State
is set to 3, then the label will span across 3 columns in the Form as illustrated below.
There are some special elements available for Free Style layouts to help label and delineate groups of elements. These are the "Label
text only" and "Horizontal rule" elements. In most cases where these are used, it will generally be beneficial to use the Label colspan to
span all columns across the Form.
98
QLR Manager User’s Guide
Designing Forms
Label vertical alignment:
The vertical alignment of labels is useful when a multiple row input field is associated with it. This could be an input control assigned to
an input field that is a textarea, a set of vertical checkboxes, etc. In the example below, the Comments label has been set as a vertical
alignment of "Top". The type of Input Control used here is a "Text area pop-up editor" that can be useful to minimize the footprint of the
textarea in the Form, yet still offer a much larger textarea to collect input.
Label help link or tooltip text:
This field is used to define help that is associated with the label for a particular element. There are two types which offer different
behaviors:
• Tooltip help is visible when the User mouses over a label. This type of help is useful for a brief tip that does not require a lot of
content. The text is entered into this field and can contain HTML tagging.
• Pop-up help which is a URL loaded into a pop-up window. This type of help is more useful to link to a more extensive set of
instructions or to another URL.
Whether the element label displays a tooltip or acts as a link to open a pop-up window is determined by what is entered into this field.
An entry beginning with http://, https://, ./, or ../ will denote either an absolute or relative URL for which QLR manager will open a popup window and load the URL. Any other text entered into this field will be treated as a tooltip. This allows a form to contain a mixture of
tooltip and URL based help.
The attributes for the label link and tooltip properties are defined in the General Form Characteristics section.
Free Style Label location:
The Label location determines where the label should be positioned in relation to the input field. QLR Manager creates two columns in
an HTML table for form elements. The first column contains the label and the second column holds the input field. This is important to
understand when selecting from the 5 options below to reposition these elements:
• Left of input places the label to the left of the input field in its own table column. By using two columns, QLR Manager is able to
vertically align both the labels and input fields. This is the default setting.
99
QLR Manager User’s Guide
Designing Forms
• Input below groups the label and input field into the same cell and the pair is stacked so that both fall within the same column as
other input cells where the labels are positioned to the left of input cell. In the example below, Last name, First name (placed into
Free Style col set 2), and Street are set as "Left of input". City, State (Free Style col set 2) and Zip (Free Style col set 3) are all set
as "Input below".
• Label above groups the label and input field into the same cell and stacks both into the label column. If multiple occurrences of
"Label above" are used in the same form row, accomplished by incrementing the Free Style col set, they are compressed together.
This is a good technique to use when multiple columns must be spread across the page, such as working with 12 months of data.
• Same cell will group both the label and the input field into the same table cell and place both into the label column. In the example
below, the Street element is placed into the same cell, and the Label colspan is set as 2.
• Omit Label omits the entire cell that would hold the element Label. This allows the input cell to slide to the left. In the example
below, the First name label is omitted, and the Last name label is altered to identify both the Last and First name input fields.
Input vertical alignment:
This control allows the Form Designer to set the vertical position of the input field. The default value is "Middle". In this example the Last
and First name input fields have been set to "Bottom":
100
QLR Manager User’s Guide
Designing Forms
Input colspan:
The Input colspan determines the number of columns that an input field will span. In this example, the Street field has a colspan of 2 in
order to accommodate a much wider text input field:
Both rowspan (Label & Input cell):
The Both rowspan setting impacts both the Input Field and its associated Label. In this example, the Comments element is set to the
right of three other input fields. In order to produce the proper alignment, it has been assigned a Both rowspan of 3.
The Data Search Portal
The Search Portal is created along with the Form and is utilized by the User to locate records in the database for Edit and Delete
Forms.
Comparison:
Search comparisons define how the Search Portal should treat the provided search criteria. A detailed explanation of Comparison
operators is provided with the Search comparison topic below.
Criteria:
Search criteria may be entered into the Search Portal to aid in locating specific data. The provided Criteria will be evaluated against the
Field name based on the selected Comparison.
Sort order:
The Sort order selection allows the User to determine the order in which they want to see the records found in the search.
101
QLR Manager User’s Guide
Designing Forms
Data Search Portal Attributes
Whenever an Edit or a Delete Form is created, there is usually a need to first locate the data that these forms are intended to
manipulate. This is the job of the Data Search Portal. Along with creating the Form, the Form Designer should create the Search Portal.
Search Portals can select data from the database table by allowing the User:
•
•
•
•
Full access to search on all fields.
Limited searches on specific fields.
Hidden searches where the search criteria is not displayed.
No search which would select all records in the table.
The Search Portal will select data from tables that may contain millions of records. However, it limits the number of records in the
search results to a maximum of 10,000.
Searchable fields:
The Searchable fields is a list of fields in the table selected for the basis of the Form. If the Form is initially populated with the "First 50
table columns" option, the Search Portal is also populated with those table columns. If "None" is selected for the initial population of the
Form, it is up to the Form Designer to choose the fields they wish to include. Just as with the Form itself, the order in which the fields
appear is controlled by the order in which they were added into this section.
As an example, the Form Designer may want to create a Search Portal to locate certain customers in the Customer table. If the Form
Designer added the City, State and Zip fields to the Searchable fields list, the resulting Search Portal would look like this:
Records in the table must match all of the selection criteria provided. If 'Billings' is entered for City and 'MT' is provided for the State,
the selection criteria would translate to: where city='Billings' AND state='MT'.
Field actions:
The Field actions are used to manipulate the searchable fields. Actions can be rolled back one at a time by clicking the Undo button.
• Add column works by first selecting an element from the Searchable fields list. Select the "Add column" Action, and then click the
Apply button. The selected element will be added to the bottom of the existing search elements. A field can only be added once.
• Insert before works similar to the "Add column" Action. First select an element from the Searchable fields list. Choose the "Insert
before" Action, then select the Fld # of an existing element and click the Apply button. The selected element will be added before
the selected Fld # element. A field cannot be inserted if it is already used in the Search Portal.
• Move before works with elements that are already part of the Search Portal. Choose the name of the element to be moved from the
Searchable fields list. Select the "Move before" Action, then choose the Fld # the element should be moved in front of and click
the Apply button.
• Replace works similar to the "Insert before" Action. First select an element from the Searchable fields list. Choose the "Replace"
Action, then select the Fld # of the existing element to be replaced. Clicking the Apply button will replace the selected Fld #
element with the selection from the Searchable fields.
• Delete (Fld #) will remove a search element. Select the "Delete" Action, choose the Fld # to be deleted, then click the Apply
button. This Action does not reference the Searchable fields list and explicitly deletes the selected Fld #.
102
QLR Manager User’s Guide
Designing Forms
Field reference:
The Fld # refers to the column number of an element in the Search Portal. It is used for referencing the column associated with many of
the above "Field actions".
Field name:
The Field name column is a list of fields that have been defined to be part of the Search Portal. Removing all the Field names will
eliminate the Search Portal and immediately present the Form. If more than one record is found in the table, a set of navigation buttons
will be available at the top of the Form (First, Back, More, Last). This allows the User to move between the selected records.
Hide field:
When the Hide field checkbox is checked, the selected field will not be displayed. This allows for selection criteria to be defined as part
of the Search Portal, but not displayed to the User. In the example below, the Hide field for Zip was checked and will not be displayed
even though a specific Zip code was entered as the Default search criteria. Other values can be populated in this manner and hidden
from the User.
If all search fields are hidden, then the data selection is based upon the hidden selection criteria and the Search Portal will not be
displayed to the User. The Edit or Delete form will be immediately presented.
Search comparison:
Search comparisons define how the Search Portal should treat the provided search criteria. In most cases, it is the combination of what
is selected as a Comparison, working with the provided Criteria.
• Equals is the most basic of search comparisons, selecting data where the information in the table field matches the provided
criteria. If the criteria provided for the state field is NY, then the search is state='NY'. When multiple values are provided in the
criteria field separated by commas (such as NY,CO,GA), then each value will be part of the search: state='NY' OR state='CO' OR
state='GA'.
• Not equals is the opposite of equals, selecting data where the information in the table field does not match the provided criteria. If
the criteria provided for the state field is NY, then the search is state!='NY'. When multiple values are provided in the criteria field
separated by commas (such as NY,CO,GA), then each value will be part of the search: state!='NY' AND state!='CO' AND
state!='GA'.
• Less than returns values that are less than the criteria value provided.
• Less or = returns values that are less than or equal to the criteria value provided.
• Greater than returns values that are greater than the criteria value provided.
• Greater or = returns values that are greater than or equal to the criteria value provided.
• Between will return values that fall between the two provided values, or are equal to either of the provided values. The format for the
criteria is lower_value and higher_value, such as AL and GA. The and keyword is used between the values.
• Not between will return values that do not fall between the two provided values, or are equal to either of the provided values. The
format for the criteria is lower_value and higher_value, such as AL and GA. The and keyword is used between the values.
• Begins with will find records that begin with the provided characters in the criteria field. Multiple entries can be provided when
separated by commas. For example, the criteria of n,g for the state field would find states beginning with either an "n" or "g".
• Not begins will find records that do not begin with the provided characters in the criteria field. Multiple entries can be provided when
separated by commas. For example, the criteria of n,g for the state field would find states that do not begin with either an "n" or "g".
• Contains will search for a provided string of characters within the associated data field. If the state field were comprised of the full
state name, then an entry of ne would return both new york and maine. Multiple entries can be provided, separated by commas.
103
QLR Manager User’s Guide
Designing Forms
• Contains all is intended to be used with multiple criteria entries which are separated by commas. It will return records only when all
of the Contain all values are found. An example of this would be a data field that tracks the toppings for pizzas. An entry of
onions,peppers would find all pizzas that had both onions and peppers. Be as specific as possible, as this search would also return
records that contained "red peppers and onions". This search is best suited to find records that may have been populated by
checkbox sets or multiple select lists.
• Not contains will search for a provided string of characters within the associated data field and return those records where that
string is not present. If the state field was comprised of the full state name, then an entry of ne would omit both new york and maine.
Multiple entries can be provided, separated by commas.
• Ends with will search for a provided string of characters at the end of the associated data field. If the state field was comprised of
the full state name, then an entry of ma would return both alabama and oklahoma. Multiple entries can be provided, separated by
commas.
• Not ends will return records when a provided string of characters is not at the end of the associated data field. If the state field were
comprised of the full state name, then an entry of ma would return new york and virginia, but not alabama or oklahoma. Multiple
entries can be provided, separated by commas.
• Like utilizes the SQL LIKE command. It uses wild card characters to find string segments. The two wild card characters are "%" and
"_". "%on" would find any string ending with "on". "james%" would find any string starting with "james". The "_" is a wildcard for a
specific position in a string. "b_nk" would find "bank" and "bunk". "%L__" (two underscores) would find records where the third to the
last letter is an "L" Multiple entries can be provided, separated by commas.
• Not like utilizes the SQL LIKE command. It works the same way as the "Like" above, except it returns items that do not match.
Multiple entries can be provided, separated by commas.
• Null will select all records where there is a null value for that field. This ignores any criteria that may have been provided. Please
note that a null value in a database is different than an empty string. To locate empty strings, use Equals with a comparison of '' (two
single quotes with no spaces between them).
• Not null will select all records where there is a value for that field. This ignores any criteria that may have been provided.
• Custom SQL allows the User to define Structured Query Language (SQL) text to be inserted into the search. For example, the User
could enter the following into the criteria field where the comparison has been set to Custom SQL: city in (select big_city from
high_population). Notice how the "city" field is referenced in the Custom SQL text. It is up to the User to create a complete
comparison, including the fields to which the comparison is mapped.
• Ignore crit allows the User to ignore the currently entered criteria for that field. This is useful when a large criteria entry has been
provided, and the User wants to ignore it for an individual search without having to remove the criteria.
Default comparison:
When defining a form, the default value for the Comparison operator is "Equals". This option allows the Form Designer to set the
default value to something else, such as "Contains". When the Search Portal is presented to the User, the selected default value will be
displayed
Lock comparison:
There may be times where the User should not be given the option of changing the search comparison, such as creating a search
panel to allow a customer to access only their information. When this checkbox is checked, the default comparison operator will be
visible, but no select list of values will be presented:
104
QLR Manager User’s Guide
Designing Forms
Default search criteria:
The Default search criteria is the initial value that will be displayed to the User when they access the Search Portal. If an input control is
used for presenting the criteria choices, such as a checkbox set, then these values will set the initial values of the Input Control:
Lock criteria:
Checking the Lock crit checkbox will make the criteria visible, but the User will not be able to change it. If an input control has been
mapped to this field, it will be ignored.
Sort order of found data:
The Sort order field allows the User to determine the order in which they want to see the records found in the search. The default Sort
order can be set here by the Form Designer.
Lock sort:
Checking the Lock sort checkbox will make the sort order visible to the User, but they will not be presented with a select list to change
the value. The Form Designer could lock all of the sort controls to prevent the User from overriding the sort order:
105
QLR Manager User’s Guide
Designing Forms
Optional input control:
The Criteria text input box can be replaced with an Input Control. If the Form Designer wishes to use an input control that they
authored, then it is only required to enter the Input Control name. If the use of an input control owned by another owner is desired, the
referenced control must be prefixed using the owner ID.control name format, such as jeff01.customer list. When the cursor is in one
of the Optional input control fields, pressing the "Ctrl" key will pop up a small window that contains a list of input controls. This can be
used to quickly reference and apply available controls:
In this example, the zip field has been assigned an input control that is comprised of vertical checkboxes. The Lock crit checkbox is
ignored when referencing an input control:
Input required:
If the Input req'd checkbox is checked, QLR Manager will validate that search Criteria has been entered. If not found, a message
panel will be displayed and the User will be returned to the Search Portal:
106
QLR Manager User’s Guide
Designing Forms
Section Titles & Opening Behavior
Forms can be divided into expandable/collapsible sections by selecting a section number in the Basic Formatting section. The behavior
of each of these sections is controlled by these settings. The behavior cannot be changed for section 0 (zero). It is always open, and
does not have a title. Section 0 is the default section number.
Section title properties:
These controls are used to change the appearance of the section title text.
Title:
The title is the text that will appear at the top of the section.
Behavior:
The Behavior setting controls if a section can be opened or closed. In addition, if the section can be opened, should it be open when the
Form loads for the first time.
Twistie:
Sections are easily identifiable by the "twistie" that precedes the section title. These are dark blue GIF images. If the Form Designer
wishes to uses different color twisties, perhaps to match the color of the section title, the following GIFs can be replaced.
qlr_manager/images/sec_rt.gif:
qlr_manager/images/sec_dn.gif:
Moving between records and updating data
When working with an Edit or a Delete Form, records will be selected that meet the criteria entered into the Search Portal. If more than
one record is found, a set of navigation buttons will be available at the top of the Form (First, Back, More, Last). Unavailable options
are grayed out. This allows the User to move between the selected records.
In order to update data in a record, or delete a record, the User must click the Update or Delete button, which is located at the
bottom of the Form. Moving between records will not update or delete data.
107
QLR Manager User’s Guide
Report Objects
Report Objects
Overview
Report Objects give the PHP programmer the ability to embed QLR Manager reports into the body of their web pages. These report
objects can be tabular report data, a chart, or both depending upon the layout that was applied. ReportObject.php is a PHP Class file
that is used to generate a report object. It provides a number of PHP functions that can be used to build and manipulate a report.
Ultimately, a report body and set of Cascading Style Sheet (CSS) entries are returned.
By default QLR Manager Report Objects can create PDF output and Charts. This requires that certain support files be loaded. The
loading of these files can be suppressed for improved performance and to help relieve memory limitations. This can be accomplished
by setting either or both of these session variables:
$_SESSION['qlr_no_pdf']
$_SESSION['qlr_no_chart']
= 'yes';
= 'yes';
The default is for a single report of all records found to be returned in the Report Object. "Report Blocks" can be specified by using the
setStartRow() and setBlockSize() functions.
Additional functions in this class such as runQuery(), getDataRow(), and others, also provide the Programmer with basic database
interface capabilities.
Input Controls can be used in conjunction with report objects to collect user input for query variables. These input controls can be
created by logging onto the "User ID Admin and Tools" function from the QLR Manager Connect panel and selecting Input Controls .
They can also be created on-the-fly by clicking the Edit Input Controls link in the Query or Wizard panels.
The functions getControl() and setControl() are provided to implement the controls in a PHP generated web page. Some controls are
returned in a table to preserve formatting. This is the most expedient way of providing an input control to collect user input. However,
this may not provide a control that fits well with the web page design. An alternative is for the Author to create their own control and
pass the selected value(s) to the report object using the setQueryVar() function. This method provides unlimited flexibility in the design
of the input control.
Whether using input controls that have been created in QLR Manager or a control designed by the Author of the web page, the method
of implementation is the same.
• Create a web page that will display the input controls to collect the desired values. This is accomplished be creating an HTML form,
which uses <form> </form> tagging. The key element of this form is the ACTION to process when the "Submit" button is clicked. It
is the name of the PHP file that will be called to create the report object. A simple example:
<form name="varform" action="./custinv.php" method="post">
<table border="0" cellspacing="2" cellpadding="0"><tr>
<td align="center"><select name="customer" size="1">
<option value="17">Asher, Artimus</option>
<option value="15">Bagadonuts, Nessa</option>
<option value="11">Benton, Edward</option>
<option value="6">Billings, Billy Bob</option>
</select></td>
</tr><tr>
<td align="center"><input type="submit" value=" Submit "></td>
</tr></table></form>
This will create a simple input form:
Example #5 contains the code for creating an input control web page.
• When the "Submit" button is clicked, it will execute a file called custinv.php. custinv.php should contain the PHP code (see
examples below) to create a report object. custinv.php can use the customer number that is being passed to it via the HTML
<form>. It's value can be accessed via PHP using the $_POST array entry of $_POST['customer']. The customer number can be
supplied to a stored QLR Manager query using the setQueryVar() function. See Example #2 for an example of how to set query
variables.
Report Objects are only available in the Enterprise Edition of QLR Manager.
108
QLR Manager User’s Guide
Report Objects
Basic steps
There are several basic steps used to create a report object. It is assumed that these are performed within a PHP environment.
1 A PHP session is started.
2 A session variable called 'inc_path' (or optionally, qlr_inc_path) is defined. This variable identifies where the QLR Manager files are
located in relation to the file that is requesting to create a report object.
3 Include the file ReportObject.php in the code.
4 A report object is created using database connection values that have authority to run the query to produce the report.
5 The query and layout used to produce the report are defined.
6 Optionally, values for query variables and changes to the layout can be made.
7 The report is created.
8 The report and CSS values are requested.
Steps 4 through 7 are repeated for each report to be embedded into a page.
Examples
An example of a PHP generated page with embedded report objects is provided as a Sample web page. The Sample page source is
also provided to illustrate how the report objects are defined. The following examples provide more information about how report
objects can be customized to meet different needs.
Depending on how calls to report objects are nested inside functions, it may be necessary to include a reference to a global variable
called $mconn (for the QLR master connection) in that function. If an error is encountered stating that the function dbquery() cannot be
found in MasterBlock.php, the function may need to be modified as follows:
function myreportcreator() {
global $mconn;
(your code starts here)
}
109
QLR Manager User’s Guide
Report Objects
Example #1: This first example uses the basic steps to create a report from a stored query, owned by 'frank', named 'customer
invoice'. The necessary statements are highlighted in blue.
<?php
// First create a PHP session
session_start();
// Define the relative path to the QLR Manager file directory
$_SESSION['inc_path'] ='../qlr/';
// Include the Report Object file
include ('../qlr/ReportObject.php');
// Create a new report object
// Provide the host, database associated to the query to be run, userid and password
// The user id needs authority to execute the query
$rptObj = new ReportObject('localhost', 'qlrmanager', 'jake', 'myd0g22');
// Define the query owner and query name, followed by the layout owner and name
$okay = $rptObj->defineReport('frank','customer invoice','frank','invoice details');
// Create the report table
$rptObj->createReport();
// HTML for the web page
echo '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">'."\n";
echo '<html><head>'."\n";
echo '<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">'."\n";
echo '<meta http-equiv="Content-Script-Type" content="text/javascript">'."\n";
echo '<meta http-equiv="Content-Style-Type" content="text/css">'."\n";
echo '</head><body>'."\n";
// Get both the CSS entries and the report table
echo $rptObj->getOutput();
echo '</body></html>'."\n";
?>
110
QLR Manager User’s Guide
Report Objects
Example #2: This second example uses a few additional functions. It shows how to set the values for query variables that may be
present in the query, and retrieves the CSS entries separately from the report table data. Also, the row count is requested to determine
what to display when the query does not produce any records.
<?php
// First create a PHP session
session_start();
// Define the relative path to the QLR Manager file directory
$_SESSION['inc_path'] ='../qlr/';
// Include the Report Object file
include ('../qlr/ReportObject.php');
// Create a new report object
// Provide the host, database associated to the query to be run, userid and password
// The user id needs authority to execute the query
$rptObj = new ReportObject('localhost', 'qlrmanager', 'jake', 'myd0g22');
// Define the query owner and query name, followed by the layout owner and name
$okay = $rptObj->defineReport('frank','customer invoice','frank','invoice details');
// Set query variable values
// Notice how this is done AFTER defineReport() and BEFORE createReport()
$rptObj->setQueryVar('customer_id', $custID);
$rptObj->setQueryVar('invoice_year', $year);
// Create the report table
$rptObj->createReport();
// HTML for the web page
echo '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">'."\n";
echo '<html><head>'."\n";
echo '<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">'."\n";
echo '<meta http-equiv="Content-Script-Type" content="text/javascript">'."\n";
echo '<meta http-equiv="Content-Style-Type" content="text/css">'."\n";
echo '<style type="text/css"><!--'."\n";
// Get the CSS values and place them in the HTML <head>
echo $rptObj->getCSSvalues();
echo '//--></style>'."\n";
echo '</head><body>'."\n";
if ($rptObj->getRecordCount() > 0) {
echo $rptObj->getReport();
}
else {
echo 'No invoice records found for this customer number';
}
echo '</body></html>'."\n";
?>
111
QLR Manager User’s Guide
Report Objects
Example #3: This is an example of a page containing more than one report object. For each report, a separate report object is
created. Notice how the Cascading Style Sheet (CSS) entries are retrieved separately from the report and included in the HTML Head
section. When creating multiple reports that require multiple sets of CSS entries, this method is safer for supporting older browsers,
such as Netscape 4.x.
<?php
// First create a PHP session
session_start();
// Define the relative path to the QLR Manager file directory
$_SESSION['inc_path'] ='../qlr/';
// Include the Report Object file
include ('../qlr/ReportObject.php');
// Create a new report object
// Provide the host, database associated to the query to be run, userid and password
// The user id needs authority to execute the query
$rptObj1 = new ReportObject('localhost', 'inventory', 'jake', 'myd0g22');
$rptObj2 = new ReportObject('localhost', 'customer', 'jake', 'myd0g22');
// Define the query owner and query name, followed by the layout owner and name
$okay = $rptObj1->defineReport('jake','low stock','jake','low stock details');
$okay = $rptObj2->defineReport('frank','customer invoice','frank','invoice details');
// Create the report tables
$rptObj1->createReport();
$rptObj2->createReport();
// HTML for the web page
echo '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">'."\n";
echo '<html><head>'."\n";
echo '<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">'."\n";
echo '<meta http-equiv="Content-Script-Type" content="text/javascript">'."\n";
echo '<meta http-equiv="Content-Style-Type" content="text/css">'."\n";
// Get the CSS values to be placed in the <head> section
echo '<style type="text/css"><!--'."\n";
echo $rptObj1->getCSSvalues();
echo $rptObj2->getCSSvalues();
echo '//--></style>'."\n";
echo '</head><body>'."\n";
// Get the report table data
echo 'Here are the low stock items:';
echo $rptObj1->getReport();
echo 'And here is the customer invoice information:';
echo $rptObj2->getReport();
echo '</body></html>'."\n";
?>
112
QLR Manager User’s Guide
Report Objects
Example #4: This is an example of creating a Microsoft Excel file for download from a report. When creating a download file, no
characters can be sent to the browser prior to executing getOutputFile().
<?php
// First create a PHP session
session_start();
// Define the relative path to the QLR Manager file directory
$_SESSION['inc_path'] ='../qlr/';
// Include the Report Object file
include ('../qlr/ReportObject.php');
// Create a new report object
// Provide the host, database associated to the query to be run, userid and password
// The user id needs authority to execute the query
$rptObj = new ReportObject('localhost', 'qlrmanager', 'jake', 'myd0g22');
// Define the query owner and query name, followed by the layout owner and name
$okay = $rptObj->defineReport('frank','customer invoice','frank','invoice details');
// Create the report table
$rptObj->createReport();
// Create an xls output file called invoice that contains the report column headings
// See getOutputFile() for valid output types
$rptObj->getOutputFile('xls', 'invoice');
?>
Example #5: This is an example of creating a page to collect input variables to be passed to a page that will create a report object.
<?php
// First create a PHP session
session_start();
// Define the relative path to the QLR Manager file directory
$_SESSION['inc_path'] ='../qlr/';
// Include the Report Object file
include ('../qlr/ReportObject.php');
// Create a new report object
// Provide the host, database associated to the query to be run, userid and password
// The user id needs authority to execute the query
$rptObj = new ReportObject('localhost', 'qlrmanager', 'jake', 'myd0g22');
// Define the input controls that will be called within the HTML page down below
$controls = array('customer','end_date','start_date');
$rptObj->setControl($controls);
// Set the default value of the customer input control
$rptObj->setControlValue('customer','default_val','12337');
?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
<title>Customer Invoice Selection</title>
<style type="text/css"><!-body,td,input,select { font-size:13px; font-family:Arial,Helvetica,sans-serif;
color:#000000; font-weight:normal }
.hdr { font-size:16px; font-family:Arial,Helvetica,sans-serif;
color:#000000; font-weight:bold }
.sub { font-size:11px; font-family:Arial,Helvetica,sans-serif;
color:#333333 }
.btn { font-size:12px; font-family:Verdana,Tahoma,sans-serif; color:#F0F0F0;
font-weight:bold; background-color:#4B7396; border-color:#8CBED7 }
//--></style>
113
QLR Manager User’s Guide
Report Objects
// This next section is in support of popup calendar controls
<script language="javascript" src="./calendar/calendar.js" type="text/javascript"></script>
<style type="text/css"><!-#calWin {
position:absolute;
visibility:hidden;
left:-500px;
top:-500px;
z-index:10;
}
.calBtn {
width:26px;
height:20px;
background:#4B7396 url(./calendar/calbtn.gif) no-repeat center; border-color:#8CBED7;
}
.datein {
width:100px;
}
//--></style>
</head><body bgcolor="#f6f6f6">
<form name="varsForm" action="./invoice.php" method="post">
<center>
<br />
<br />
<table border="0" cellpadding="4" cellspacing="0"><tr>
<td colspan="3" align="center" class="hdr">Please select customer and date range for invoices</td>
</tr><tr>
<td>&nbsp;</td>
</tr><tr>
<td>Select a customer:</td>
<td><?php echo $rptObj->getControl('customer'); ?></td>
</tr><tr>
<td>Select starting date:</td>
<td><?php echo $rptObj->getControl('start_date'); ?></td>
<td class="sub">(a date early in 2002 should be used)</td>
</tr><tr>
<td>Select ending date:</td>
<td><?php echo $rptObj->getControl('end_date'); ?></td>
<td class="sub">(a date late in 2004 should be used)</td>
</tr></table>
<br />
<input type="submit" value=" Submit " class="btn">
</center>
</form>
// This next line is to support popup calendar controls (keep on one line)
<iframe id="calWin" name="calWin" src="./calendar/calendar.html" width="192" height="187"
marginwidth="0" marginheight="0" hspace="0" vspace="0" frameborder="0" scrolling="no"></iframe>
</body></html>
114
QLR Manager User’s Guide
Report Objects
Example #6: This is an example of using a Report Object to create the contents for a report file. A report is generated and then,
using PHP, a file is written.
<?php
// First create a PHP session
session_start();
// Define the relative path to the QLR Manager file directory
$_SESSION['inc_path'] ='../qlr/';
// Include the Report Object file
include ('../qlr/ReportObject.php');
// Create a new report object
// Provide the host, database associated to the query to be run, userid and password
// The user id needs authority to execute the query
$rptObj = new ReportObject('localhost', 'qlrmanager', 'serge', 'i8mylunch');
// Define the query owner and query name, followed by the layout owner and name
$okay = $rptObj->defineReport('frank','sales history','frank','history layout');
// Create the report table
$rptObj->createReport();
$content = $rptObj->getOutput();
// add windows line breaks for making source prettier if on a windows server
$content = str_replace("\n","\r\n",$content);
// note: do not use the QLR /reports directory, as files get purged automatically
//
after 12 hours once another user logs in
$filename = '../userReports/myreport.html';
if (!$handle = fopen($filename, 'w')) {
echo "Cannot open file ($filename)";
exit;
}
// Write content to the opened file.
if (fwrite($handle, $content) === FALSE) {
echo "Cannot write to file ($filename)";
exit;
}
echo "Success, wrote content to file ($filename)";
fclose($handle);
?>
115
QLR Manager User’s Guide
Report Objects
Class functions
addAttachment:
null addAttachment(file_content, file_name)
This function allows for a content to be added as file attachment to an e-mail. The e-mail is sent using the sendMail() function. Multiple
files can be attached by calling this function more than once.
Example:
// Create the report table
$rptObj->createReport();
// get ready to send an e-mail
$to
= 'jake@gmail.com';
$cc
= '';
$bcc
= '';
$from
= 'greg@iris.com';
$subject = 'Inventory report';
$body
= 'Please find attached the latest inventory report.';
// This command gets the report data formatted for Excel
$content = $rptObj->getFileData('xlsf');
// Now add the attachment
$rptObj->addAttachment($content,'inventory.xls');
// Note: Once sendMail is executed, it resets the current attachments to empty.
$rptObj->sendMail($to, $cc, $bcc, $from, $subject, $body);
See sendMail() for information about sending an e-mail. In addition, getFileData() is used to retrieve the current report in a particular
file format.
cleanUpFiles:
void cleanUpFiles()
This calls the QLR Manager clean up routine. It will delete QLR Manager pages that are over 12 hours old. This is intended for
installations that primarily run Report Objects and rarely use the traditional QLR Manager interface. The traditional interface invokes
this routine once a day with the first log on through the Connect panel.
Example:
$rptObj->cleanUpFiles();
createReport:
string createReport()
Creates the report based on the query and layout parameters provided in defineReport(). Returns either "report" when a report table is
successfully created or "info" when an informational message is generated instead of a report.
Example:
$outputType = $rptObj->createReport();
116
QLR Manager User’s Guide
Report Objects
defineReport:
bool defineReport( string query_owner, string query_name,
string layout_owner, string layout_name)
Defines the query and layout to be used as the basis for the report. Alternately, if the query_owner is defined as '*query_text*', a query
string can be entered as the query_name as illustrated in Example #2. If no layout is desired, the layout_owner and layout_name can
be entered as '' (empty single quotes). The queries used in this function should be a single SELECT query, to which a layout can be
applied.
Note: The query and layout specified in defineReport() must either be owned by the ID that was provided when the new
ReportObject() was created, or the query and layout must have been saved to be SHARED with other users.
Example #1:
$okay = $rptObj->defineReport('frank', 'invoice report',
'frank', 'invoice summary');
Example #2:
$query = 'select custID, first_name, last_name from customer';
$okay = $rptObj->defineReport('*query_text*', $query, '', '');
getControl:
string getControl(string control_name)
Returns an HTML formatted string for the specified Input Control. If the Input Control is not found, a "not found" message is returned.
The HTML “name” is the Input Control name. Some controls are returned in a table to preserve formatting. If the Input Control is a date
input with the popup calendar, there are some CSS Classes, a JS file import and an <iframe> element that must be included in the
web page. Please see Popup calendar for more information.
Note: This function should be called after setControl() has initialized the input control(s) for use.
Example:
echo $rptObj->getControl('custlist');
Would return:
<select name="custlist" size="1">
<option value="17">Asher</option>
<option value="15">Bagadonuts</option>
<option value="11">Benton</option>
<option value="8">Billings</option>
</select>
Input Controls designed in QLR Manager offer some advanced features that can be deployed when used as Report Objects:
•
•
•
•
[Select all] [Deselect all] [Reverse]for checkbox groups and multi-select lists.
Character limit for text areas.
Selection limit for checkbox groups and multi-select lists.
Regular Expression validations and string replacement for text inputs and text areas.
If any of the above features are used with an input control, the following js file must be imported into the <head> of the HTML page to
support these functions. The path for the "src=" attribute may have to be adjusted to correctly locate inptctl.js relative to the PHP file
producing the HTML page:
<script language="javaScript" src="./qlr_manager/jslib/inptctl.js" type="text/javascript"></script>
For features such as Character/Selection limit and Regular Expression validations, it is also wise to validate the submitted data on the
server. These functions on the client side rely on JavaScript and it is possible to disable JavaScript in the browser which would disable
these limits and validations.
117
QLR Manager User’s Guide
Report Objects
getCSSvalues:
string getCSSvalues()
Returns the Cascading Style Sheet (CSS) values needed to format the report table.
Note: It does not return the opening and closing <style> tags.
Example:
$css = $rptObj->getCSSvalues();
getDataRow:
array getDataRow()
Returns an associative array of the values in the current result set and then points to the next record in the result set.
Example:
$okay = $rptObj->runQuery('select partnum,boh from inventory where boh>10000');
if ($okay) {
echo 'Record count: '.$rptObj->getRecordCount()."<br />\n";
for ($i=0; $i < $rptObj->getRecordCount(); $i++) {
$row = $rptObj->getDataRow();
while (list($key,$value) = each ($row)) {
$key = strtolower($key);
echo " $key = $value";
}
echo "<br />";
}
}
else echo 'Error: '.$rptObj->getErrorNum().' '.$rptObj->getErrorMsg();
getErrorMsg:
string getErrorMsg()
Returns the database engine error message when runQuery() returns false.
Example:
$okay = $rptObj->runQuery('select * from inventory where boh>10000');
if (!$okay) {
echo 'Error: '.$rptObj->getErrorNum().' '.$rptObj->getErrorMsg();
}
getErrorNum:
integer getErrorNum()
Returns the database engine error number when runQuery() returns false.
Example:
$okay = $rptObj->runQuery('select * from inventory where boh>10000');
if (!$okay) {
echo 'Error: '.$rptObj->getErrorNum().' '.$rptObj->getErrorMsg();
}
getFieldName:
string getFieldName(integer field_number)
Returns the field name from a result set associated to a column number. The first column in a result set is equal to zero.
Example:
$okay = $rptObj->runQuery('select * from inventory where boh>10000');
if ($okay) {
echo 'The second column is called: '.$rptObj->getFieldName(1)."<br />\n";
}
else echo 'Error: '.$rptObj->getErrorNum().' '.$rptObj->getErrorMsg();
118
QLR Manager User’s Guide
Report Objects
getFileData:
string getFileData(output_type)
This returns the current report data formatted in a particular file format.
Valid output types are as follows:
Output
Type
csv
csv+
csvr
csvr+
doc
html
html+
txt
txt+
txtr
txtr+
xls
xls+
xlsr
xlsr+
xlsf
xml
xmlr
Description
Comma separated value file.
Comma separated value file with report column headers.
Comma separated value file produced from the raw query results. This is much faster, but bypasses applying any Layout
data modifications.
Comma separated value file with report column headers produced from the raw query results. This is much faster, but
bypasses applying any Layout data modifications.
Microsoft Word Doc file.
HTML formatted file.
HTML formatted file that can be imported into MS Excel or Word.
Semi-colon separated value file.
Semi-colon separated value file with report column headers.
Semi-colon separated value file produced from the raw query results. This is much faster, but bypasses applying any
Layout data modifications.
Semi-colon separated value file with report column headers produced from the raw query results. This is much faster, but
bypasses applying any Layout data modifications.
Microsoft Excel file (data only).
Microsoft Excel file (data only) with report column headers.
Microsoft Excel file (data only) produced from the raw query results. This is much faster, but bypasses applying any Layout
data modifications.
Microsoft Excel file (data only) with report column headers produced from the raw query results. This is much faster, but
bypasses applying any Layout data modifications.
Microsoft Excel file formatted with coloring, etc.
XML formatted file.
XML formatted file produced from the raw query results. This is much faster, but bypasses applying any Layout data
modifications.
Example:
// Create the report table
$rptObj->createReport();
// This command gets the report data formatted for Excel
$content = $rptObj->getFileData('xlsf');
// Now add the attachment
$rptObj->addAttachment($content,'inventory.xls');
See addAttachment() for information about adding an attached file to an e-mail.
getInfo:
string getInfo()
Returns the informational message text generated when createReport() returns "info".
Example:
$msg = $rptObj->getInfo();
119
QLR Manager User’s Guide
Report Objects
getOutput:
string getOutput()
Returns both the Cascading Style Sheet values (enclosed in <style> tags) and the report table when createReport() returns "report".
Example:
$output = $rptObj->getOutput();
getOutputFile:
(browser download interface) getOutputFile(string output_type, string file_name)
Creates an output file for user download as defined by the output type. The file extension is automatically appended to the file name
based on the output type. This function is called after createReport().
Valid output types are as follows:
Output
Type
csv
csv+
csvr
csvr+
doc
html
html+
txt
txt+
txtr
txtr+
xls
xls+
xlsr
xlsr+
xlsf
xml
xmlr
Description
Comma separated value file.
Comma separated value file with report column headers.
Comma separated value file produced from the raw query results. This is much faster, but bypasses applying any Layout
data modifications.
Comma separated value file with report column headers produced from the raw query results. This is much faster, but
bypasses applying any Layout data modifications.
Microsoft Word Doc file.
HTML formatted file.
HTML formatted file that can be imported into MS Excel or Word.
Semi-colon separated value file.
Semi-colon separated value file with report column headers.
Semi-colon separated value file produced from the raw query results. This is much faster, but bypasses applying any
Layout data modifications.
Semi-colon separated value file with report column headers produced from the raw query results. This is much faster, but
bypasses applying any Layout data modifications.
Microsoft Excel file (data only).
Microsoft Excel file (data only) with report column headers.
Microsoft Excel file (data only) produced from the raw query results. This is much faster, but bypasses applying any Layout
data modifications.
Microsoft Excel file (data only) with report column headers produced from the raw query results. This is much faster, but
bypasses applying any Layout data modifications.
Microsoft Excel file formatted with coloring, etc.
XML formatted file.
XML formatted file produced from the raw query results. This is much faster, but bypasses applying any Layout data
modifications.
Example:
$rptObj->getOutputFile('csv', 'invoices');
Note: It is very important that no information is sent to the browser, not even blank characters, prior to calling this function.
120
QLR Manager User’s Guide
Report Objects
getPDFfile:
PDF data stream getPDFfile(integer left_margin,
integer right_margin,
integer top_margin,
string page_orientation, ('p' for portrait, 'l' for landscape)
string paper size, ('A3','A4','A5','Letter' or 'Legal')
integer page_width, (600, 800 or 1024)
string page_content) (an empty string '', or custom content)
This function supports the creation of a PDF file stream sent to the browser. Since it does send data back to the browser, no output
should be sent from the server prior to this function returning data. The "page_orientation" is determined by examining the first letter of
the value provided and is case insensitive. The "paper_size" arguments are also case insensitive. As the "page_width" value is
increased, more information can be fit onto a page, similar to how the screen resolution setting works on a computer display.
There are two basic ways to provide content to this function. The first is by executing the createReport() function prior to calling
getPDFfile and entering '' (empty quotes) as the "page_content" value. The second way is to provide customized content for the entire
PDF output stream via the "page_content" value. Following are examples of the two methods.
Report created by QLR Manager:
$rptObj = new ReportObject('localhost', 'baitshop', 'frank', 'my02dog');
// Define the query owner and query name, followed by the layout owner and name
$okay = $rptObj->defineReport('frank','sales','frank','sales summary');
// Create the report
$rptObj->createReport();
// The following will create a PDF stream based on the report created in
// createReport(). Notice how the last argument for page_content is ''.
$rptObj->getPDFfile(10,10,5,5,'p','letter',800,'');
Customized output:
$rptObj = new ReportObject('localhost', 'baitshop', 'frank', 'my02dog');
// Define the query owner and query name, followed by the layout owner and name
$okay = $rptObj->defineReport('frank','invoice','frank','invoice_layout');
// Create a report body
$rptObj->createReport();
// Start some custom content
$content = 'Dear Mary,<br /><br />Here is your invoice<br />';
// Optionally embed a report into the custom content
$content .= '<center>';
$content .= $rptObj->getStyledReport();
$content .= '</center>';
// Finish the custom content
$content .= '<br /><Sincerely,<br /><<br />Frank';
// The following will create a PDF stream based on the custom content.
$rptObj->getPDFfile(15,15,20,20,'portrait','a4',1024,$content);
getQuery:
string getQuery()
Returns the query string that was executed by createReport(). This is helpful for debugging, especially when a query includes query
variable replacement.
Example:
$okay = $rptObj->runQuery('select * from inventory where boh>10000');
if (!$okay) {
echo 'Query text: '.$rptObj->getQuery();
}
121
QLR Manager User’s Guide
Report Objects
getRecordCount:
integer getRecordCount()
Returns the number of rows in the report that is generated after createReport() is executed.
Example:
$count = $rptObj->getRecordCount();
getReport:
string getReport()
Returns the report HTML table generated when createReport() returns "report".
Example:
$reportBody = $rptObj->getReport();
getSQLdate:
string getSQLdate(string raw_date_value, string input_control_name)
Returns a date string in the database yyyy-mm-dd format by converting dates that are in a different format for a given Input Control.
Example:
$sql_date = $rptObj->getSQLdate('12-31-2005', 'first_date');
getStyledReport:
string getStyledReport()
Returns the report HTML table generated when createReport() returns "report". The CSS entries are created as in-line style="(values)"
entries as part of each report table cell. This provides formatted output without having to accommodate CSS entries. The drawback is
that it returns more data.
Example:
$reportBody = $rptObj->getStyledReport();
ReportObject:
object ReportObject( string host, string database_name,
string userid, string password)
Creates an object of type ReportObject and establishes database connection parameters. When using QLR Manager with Oracle, the
database name is be entered as '' (empty single quotes).
Example:
$rptObj = new ReportObject('localhost', 'custdata', 'jake', 'myd0g22');
replaceNameChars:
string replaceNameChars(string input_control_name)
Returns a string that converts special characters back to their original form in an input control name.
When input controls are created as report objects, the name of the input control is used as the HTML form element NAME. The name
applied to the input control when saved in QLR Manager may contain invalid characters that cannot be used as in the HTML form
element NAME attribute. Certain characters must be converted to produce valid HTML. For example, an input control with the name of
"first.date(yyyy-mm-dd)" is converted by QLR Manager to "first_pe_date_lp_yyyy_ds_mm_ds_dd_rp". replaceNameChars will convert
the QLR use of the form element NAME attribute back to the original input control name.
Examples:
$name = $rptObj->replaceNameChars('first_pe_date_lp_yyyy_ds_mm_ds_dd_rp');
122
QLR Manager User’s Guide
Report Objects
runQuery:
bool runQuery(string query_text)
Executes an SQL query string using the connect values as provided when the ReportObject() was created.
Examples:
$rptObj->runQuery('select * from customer');
$rptObj->runQuery('update inventory set boh=495 where partnum=65099');
saveOutputFile:
bool saveOutputFile(string output_type, string path/file_name)
Saves a file to disk as defined by the output type. The path can be either relative or absolute. The file extension is automatically
appended to the file name based on the output type. This function is called after createReport(). Returns TRUE if the file is
successfully written.
Valid output types are as follows:
Output
Type
csv
csv+
doc
xls
xls+
xlsf
html
html+
Description
Comma separated value file.
Comma separated value file with report column headers.
Microsoft Word Doc file.
Microsoft Excel file (data only).
Microsoft Excel file (data only) with report column headers.
Microsoft Excel file formatted with coloring, etc.
HTML formatted file.
HTML formatted file that can be imported into MS Excel or Word.
Example:
$okay = $rptObj->saveOutputFile('doc', '../myfiles/invoices');
sendMail:
boolean sendMail(string to_addresses, (multiple address separated by commas)
string carbon_copy_addresses, (multiple address separated by commas)
string blind_copy_addresses, (multiple address separated by commas)
string from_address,
string email_subject,
string email_content)
This function supports HTML formatted email distribution. It requires that you have a Simple Mail Transfer Protocol (SMTP) server
running. This returns true if the email content is successfully sent to the SMTP server, but it does not know if the STMP server has
successfully sent the message.
Example:
// Create the email body
$Body = '<p>Fred, here is your account activity:</p>';
$Body .= $rptObj->getStyledReport();
$Body .= '<p>Sincerely,<br />Frank</p>';
$To
= 'fred@yahoo.com';
$Cc
= '';
$Bcc = 'jake@comcast.net, tom@hotmail.com';
$From = 'john@tekoutsight.com';
$Subject = 'Account activity';
// Returns true or false based on getting mail to SMTP server.
$sent = $rptObj->sendMail($To,$Cc,$Bcc,$From,$Subject,$Body);
See addAttachment() for information about adding an attached file to an e-mail.
123
QLR Manager User’s Guide
Report Objects
setBlockSize:
void setBlockSize(integer number_of_rows_to_display)
Allows the User to specify the number of rows of data to return in a Report Object. It is used in conjunction with setStartRow() to create
Report Objects that contain ranges of report row output.
This function should be used after defineReport() is called and before createReport() is called.
Examples:
$rptObj->setStartRow(1001);
$rptObj->setBlockSize(500);
setColumnAttribute:
void setColumnAttribute(integer column_number, string field_name, string value)
Allows the User to set the attributes associated with given column within a report. The first column is equal to 1. These are the same
fields as found in the Report Columns section of the Layout panel. Generally this function does not need to be used. It is much simpler
to create and save a Layout and then reference the Layout in defineReport().
The allowable field_names are column_title, column_align, column_action, format, decimal_places, display width and evaluate. Please
view the allowable choices for these fields in the Report Columns section of the Layout panel.
This function should be used after defineReport() is called and before createReport() is called.
Examples:
$rptObj->setColumnAttribute(1, 'column_title','customer<br />number');
$rptObj->setColumnAttribute(1, 'column_align','Left');
setControl:
void setControl(string or array of
control_names)
This function initializes the Input Controls to be used in a page. A single control can be specified by providing a string argument. If
more than one control is to be used in a page, an array of string arguments should be provided.
Examples:
$rptObj->setControl('custlist');
$controls = array('custlist','startDate','endDate','region');
$rptObj->setControl($controls);
124
QLR Manager User’s Guide
Report Objects
setControlQueryVar:
void setControlQueryVar(string query_var_name, string value)
This function allows for the values of query variables that are present in the input control query text to be set with a value. Note: This
must be set prior to calling the setControl() function.
The control_name references a control that was defined in SetControl().
Here is an example, assuming that the query text in the following Input Control named "customer number" has a query that contains
the text of "select acnt_num from customer where region='[region code]' ".
$rptObj->setControlQueryVar('region code','southwest');
$rptObj->setControl('customer number');
If need be, an entire query can be dynamically set if the query text in the Input Control is nothing more, for example, than [my query
text].
$rptObj->setControlQueryVar('my query text',$query);
$rptObj->setControl('custom list');
setControlValue:
void setControlValue(string control_name, string field_name, mixed value)
This function allows for certain input control characteristics to be overriden and set at the time of use.
The control_name references a control that was defined in SetControl().
The field_name can be one of the following. Different fields can be set by issuing this function more than once.
Field
default_val:
error_msg:
list_text:
max_size:
reg_exp:
select_limit:
text_rows:
Description
This allows for the default value of a field to be set. If the control is a checkbox set or multiple select list, an array of
values can be used to set multiple values.
The error message to display when a regular expression check fails.
This allows for the replacement of query variables within an Input Control's list text as the data source.
the character width of a text input field or text area, or the number of columns of checkboxes or radio buttons when a
grid arrangement is specified.
A regular expression string to perform data validation.
The number of characters that can be entered into a text field or textarea, or the number of selections that can be
chosen from a checkbox set or multiple select list.
The number of rows to display in a textarea or the height of a select list.
Examples:
$rptObj->setControlValue('customer number','default_val', 230099);
$rptObj->setControlValue('customer number','select_limit', 5);
$names = array('Fred','Nick','Kadir','Anitha');
$rptObj->setControlValue('first names','default_val',$names);
$rptObj->setControlValue('organizer event list','list_text', 'option1,option2,option3');
125
QLR Manager User’s Guide
Report Objects
setPageAttribute:
void setPageAttribute(string field_name, string value)
Allows the User to set the attributes associated to the overall page appearance of a report. These are the same fields as found in all
the sections of the Layout panel, except for the setColumnAttribute() which corresponds to the Report Columns section of the Layout.
Generally this function does not need to be used. It is much simpler to create and save a Layout and then reference the Layout in
defineReport().
The allowable field_names for this function can be found by looking at the Table info (from the Query panel) for the table
qlr_layout_master.
This function should be used after defineReport() is called and before createReport() is called.
Examples:
$rptObj->setPageAttribute('title_text','Customer Invoice report');
$rptObj->setPageAttribute('title_font_face','Arial,Helvetica,sans-serif');
setPDFdestination:
void setPDFdestination(integer 1 (default browser) 2 file)
Allows the User to specify that PDF output should be sent to a file.
This function should be used before getPDFfile() is called. The file will be created in the QLR Manager /reports directory. Please note
that when saving to a file, the process will cause the user's browser window to go blank, so some sort of HTML should be sent after the
creation of the file.
Examples:
$rptObj->setPDFdestination(2);
$rptObj->setPDFfilename('juneSales');
setPDFfiledir:
void setPDFfiledir(String file_directory)
Allows the User to specify the directory of where the PDF file will be created. This can be used when creating a file for downloading or
when saving the PDF output to a file. The directory is relative to where the executing report object is located. If not specified, the QLR
Manager reports directory is used.
Examples:
$rptObj->setPDFfiledir('../../june_reports/');
$rptObj->setPDFfilename('sales');
setPDFfilename:
void setPDFfilename(String file_name)
Allows the User to specify the name of the PDF file that is being created. This can be used when creating a file for downloading or
when saving the PDF output to a file. QLR Manager will automatically add the .pdf file extension.
Examples:
$rptObj->setPDFfilename('juneSales');
$rptObj->setPDFfilename('invoice224');
setQueryVar:
void setQueryVar(string variable_name, string value)
Allows the User to set the value of a query variable when present. It is not necessary to use the ** prefix, or the [brackets] used in QLR
Manager version 5, with the variable_name.
This function should be used after defineReport() is called and before createReport() is called.
Examples:
$rptObj->setQueryVar('customer_id','73490');
$rptObj->setQueryVar('year','2004');
126
QLR Manager User’s Guide
Report Objects
setStartRow:
void setStartRow(integer first_row_to_display)
Allows the User to specify the first row number of data to return in a Report Object. It is used in conjunction with setBlockSize() to
create Report Objects that contain ranges of report row output. The first report row is 1.
This function should be used after defineReport() is called and before createReport() is called.
Examples:
$rptObj->setStartRow(1001);
$rptObj->setBlockSize(500);
setWatermark:
void setWatermark(text)
Allows the User to specify text that will be displayed as transparent text rendered diagonally across the first page of the generated PDF
file.
Example:
$rptObj->setWatermark('Draft');
setXMLRecordTag:
void setXMLRecordTag(text)
Allows the User to set the record level tag for xml output. The default value is "record".
Example:
$rptObj->setXMLRecordTag('customer');
setXMLRootTag:
void setXMLRootTag(text)
Allows the User to set the root level tag for XML output. The default value is "data".
Example:
$rptObj->setXMLRootTag('allcustomers');
suppressSelectAll:
void suppressSelectAll(void)
This function will suppress the addition of the [Select all] [Deselect all] [Reverse] controls that appear on the top of checkbox sets and
multiple select list input controls.
$rptObj->suppressSelectAll();
127
QLR Manager User’s Guide
Report Objects
Popup calendar
A popup calendar is provided for use with input controls that require date selections. The calendar is automatically included within QLR
Manager if an input control is defined using one of the "Calendar popup" selections available under Control type. These input controls
can be created by clicking the Edit Input Controls link from either the Wizard or Query panels. An example of the Popup calendar
can be viewed in the Input Controls topic. This popup calendar can also be used when input controls are used in conjunction with
Report Objects. Since this use requires the calendar be available in the web page using the getControl() and setControl() functions,
there are some additional steps required for the calendar to be accessible and function correctly.
Note: All the path references below must be adjusted to reference the calendar files relative to web page PHP directory. All the files
required to support the calendar input control are located in the /qlr_manager/calendar directory. It may be more convenient to copy
this directory and its contents to a location under the PHP directory to more easily reference the path. The instructions below assume
this path configuration. Be sure to read the comments in the top of calendar.html for available configuration options.
CSS classes:
There are a few CSS classes that should included in the <head> of the web page:
#calWin: This class is required to define the <iframe> that will hold the calendar.
.calBtn: This defines the size, color and background image for the button used to launch the calendar.
.datein: Since the rendering width of text inputs varies greatly among different browsers, this class is included within the <input
type="text" class="datein" size="12" produced with the input control. Using the width value along with the size attribute
produces a consistent width across most browsers.
<style type="text/css"><!-#calWin {
position:absolute;
visibility:hidden;
left:-500px;
top:-500px;
z-index:10;
}
.calBtn {
width:26px;
height:20px;
background:ButtonFace url(./calendar/calbtn.gif) no-repeat center;
}
.datein {
width:100px;
}
//--></style>
JS file import:
A JS file must be imported that will launch the calendar and position it immediately below the text input it is associated with. The
following should be placed in the <head> of the web page following the <style> declarations:
<script language="javascript" src="./calendar/calendar.js" type="text/javascript"></script>
Calendar html file:
The main component of the calendar is the HTML file. For most modern browsers, this HTML is loaded into an <iframe> that must be
defined in the web page. For older browsers that do not support the <iframe>, such as Netscape 4.x, the calendar is launched in a
popup window. Include the following <iframe> element in the bottom of the web page before the closing <body> tag:
<iframe id="calWin" name="calWin" src="./calendar/calendar.html" width="192" height="187"
marginwidth="0" marginheight="0" hspace="0" vspace="0" frameborder="0" scrolling="no"></iframe>
Keep the <iframe> tagging on one line.
128
QLR Manager User’s Guide
Report Objects
Button to launch calendar:
When using a "Calendar popup" input control defined within QLR Manager, the text input and button using the "calbtn.gif" is returned in
a table:
<table border="0" cellspacing="0" cellpadding="0"><tr>
<td><input type="text" size="12" maxlength="10" name="begin_date" value="" class="datein"></td>
<td><input type="button" value="" alt="Calendar" class="calBtn"
onClick="openCalendar(event,0,'varsForm','Begin_date','mmddyyyy','/','Begin date',1);return
false"></td>
</tr></table>
Since some older browsers do not support the CSS to include an image on a form button (i.e. Netscape 4.x), a slightly different
approach is used and automatically generated by QLR Manager when a calendar input control is used with report objects. Instead of a
button adjacent to the text input, the "calBtn.gif" is enclosed in a <href> with the following HTML returned:
<table border="0" cellspacing="0" cellpadding="0"><tr>
<TD><input type="text" size="12" maxlength="10" name="begin_date" value="" class="datein"></td>
<td><a href="./calendar/calendar.html"
onClick="openCalendar(event,0,'varsForm','r000Begin_date','mmddyyyy','/','',1);return false"
title="Calendar">
<img src="calendar/calbtn.gif" alt="Calendar" align="top" border="0" /></a></td>
</tr></table>
This is the most expedient way of creating a date selection input control. However, this may not provide a control that fits well with the
web page design. An alternative is for the Author to create their own control and pass the date value to the report object using the
setQueryVar() function. This method provides more flexibility in the design of the control, but it does require that the arguments passed
to the openCalendar() function be carefully constructed with the selected value passed to the setQueryVar() function as described in
the Overview.
Color schemes:
When used as a date input control associated with report objects, all the colors that make up the popup calendar can be easily changed
to allow the Author to coordinate the look of the calendar with their web site. There are commented instructions in the top of
calendar.html that describe how to change the colors. Following are examples of 3 predefined color sets that can be selected:
GRN
BRN
XP
129
QLR Manager User’s Guide
Report Objects
Demo web page
Customer Order Information
Frank's Bait and Tackle
** Items Discounted 20% **
Welcome back, Sam
Please check our
Weekly Specials...
Since your account is in good standing, we have an exclusive offer for you. We are
overstocked on the listed items and are aiming to reduce or inventory by 75% with this
weeks Inventory Reduction Sale. We're offering these popular items at a 20%
Discount. The table at right is generated from our database. It shows how much
inventory we wish to sell of each item and is refreshed each time you log on. They're
moving fast! Be sure to visit each week to check our specials.
As always, we offer Free shipping on orders over $30.00.
Sorry, no rain checks if an item sells out.
Avail Sale
Qty Price
Category
Name
Crank Baits
Crank Baits
Crawdads
Crawdads
Reels
Reels
Reels
Soft Baits
Soft Baits
Soft Baits
Soft Baits
Minnow lure
Polly wog
Crawdad green
Crawdad red
Ab Gacio D3
Ab Gacio D4
Little Momma
Andy's Auger
Monster worm
Squirmin worm
Super crawler
177
2322
1836
354
205
172
205
407
3501
259
599
7.16
7.16
3.16
3.16
47.99
55.99
47.99
2.36
2.36
2.36
2.36
Your order history:
YTD Order Summary for Customer #: 15
Order #
Item
# Part #
Item name
Item description
1022
Andy's Auger
Lou's Laser
Good for pan fishin
The reel deal!
1026
Little fish lure
Squirmin worm
Crawdad red
Crawdad brown
Good for Bass
Feels so squirmy, I don't even like to touch this one
Crawdad bait number 1
Crawdad bait number 3
1030
Monster worm
Crawdad green
Big Daddy
Like fishin with a big old worm
Daddy and baby crawdad
Big Daddy Bait Caster
1
spopp18
2
rll300
Total for order # 1022
1
c470
2
squ65
3
craw1
4
craw3
Total for order # 1026
1
smonst42
2
craw2
3
rbd01
Total for order # 1030
Grand Total
Unit
price Qty
Total
price
$2.95
$29.95
2
2
4
$5.90
$59.90
$65.80
$3.95
$2.95
$3.95
$3.95
1
1
1
2
5
$3.95
$2.95
$3.95
$7.90
$18.75
$2.95
$3.95
$62.50
1
3
1
5
$2.95
$11.85
$62.50
$77.30
14
$161.85
1
130
QLR Manager User’s Guide
Report Objects
Demo page source
Following is the source for the sample web page with two embedded report objects. Some JavaScript and HTML has been removed for
simplicity.
<?php
// Create a php session. This must be the first line executed in your php file.
session_start();
// Define the relative path to the QLR Manager file directory
$_SESSION['inc_path'] ='../demo/';
// Include the Report Object file
include ('../demo/ReportObject.php');
// Create a new report object
// Provide the host, database associated to the query to be run, userid and password
// The user id needs authority to execute the query
$rptObj = new ReportObject( 'localhost', 'qlrmanager_baitshop', 'guest', 'guest');
$rptObj2 = new ReportObject( 'localhost', 'qlrmanager_baitshop', 'guest', 'guest');
// Define the query owner and query name, followed by the layout owner and name
$okay = $rptObj->defineReport('frank','overstock','frank','overstock');
$okay = $rptObj2->defineReport('frank','order info','frank','order info');
// Notice how this is done AFTER defineReport() and BEFORE createReport()
$rptObj2->setQueryVar('customer_number', 15);
// Now create the report table
$rptObj->createReport();
$rptObj2->createReport();
// Start your HTML page
echo '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">'."\n";
echo '<html><head>'."\n";
echo '<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">'."\n";
echo '<meta http-equiv="Content-Script-Type" content="text/javascript">'."\n";
echo '<meta http-equiv="Content-Style-Type" content="text/css">'."\n";
echo '<title>Frank\'s Baitshop: Customer Info</title>'."\n";
echo '<style type="text/css"><!--'."\n";
// Styles used in page
echo 'BODY,TD { font-family:Arial,Helvetica,sans-serif; font-size:10pt; color:#000000 }'."\n";
echo 'P { font-family:Arial,Helvetica,sans-serif; font-size:10pt; color:#000000; margin-top:0px;
margin-bottom:6px }'."\n";
echo 'A:HOVER
{ color:#177CB0; text-decoration:underline }'."\n";
echo '.fntLogo { font-family:Arial,Helvetica,sans-serif; font-size:14pt; color:#033E66; fontweight:bold }'."\n";
echo '.hdrFont { font-family:Tahoma,Arial,Helvetica,sans-serif; font-size:14pt; color:#000000;
font-weight:bold }'."\n";
echo '.rainbow { font-family:"Comic Sans MS",Georgia,Tahoma,sans-serif; font-size:14pt;
color:#FF0000; font-weight:bold }'."\n";
echo '.welcome { font-family:Arial,Helvetica,sans-serif; font-size:12pt; color:#000000; fontweight:bold }'."\n";
echo '.celFade {
filter:alpha(opacity=100,finishOpacity=10,style=1,startX=1,startY=1,finishX=100,finishY=100)
}'."\n";
131
QLR Manager User’s Guide
Report Objects
// Get the report CSS values and place them in the HEAD
echo $rptObj->getCSSvalues();
echo $rptObj2->getCSSvalues();
echo '//--></style>'."\n";
echo '</head><body bgcolor="#ffffff" link="#033E66" vlink="#033E66" alink="#033E66">'."\n";
echo '<table border="0" cellspacing="0" cellpadding="0" width="100%"><tr>'."\n";
echo '<td width="1%" rowspan="5"><img src="../html/images/frank_s.gif" alt="Frank" width="50"
height="60" /></td>'."\n";
echo '</tr><tr>'."\n";
echo '<td width="1%" height="49" valign="bottom" nowrap><font face="Arial,Helvetica,sans-serif"
color="#033E66"'."\n";
echo 'size="+1"><b class="fntLogo">Frank\'s Bait and Tackle</b></font></td>'."\n";
echo '<td width="1%" valign="bottom"><img src="../html/images/fish_s.gif" alt="" width="40"
height="33" /></td>'."\n";
echo '<td width="97%" valign="bottom" align="center" nowrap><font
face="Tahoma,Arial,Helvetica,sans-serif"'."\n";
echo 'color="#000000" size="+1"><b class="hdrFont">Customer Order
Information</b></font></td>'."\n";
echo '</tr><tr>'."\n";
echo '<td colspan="3" height="2"><spacer type="block" width="2" height="2"></td>'."\n";
echo '</tr><tr>'."\n";
echo '<td colspan="3" bgcolor="#033E66" class="celFade" height="2"><spacer type="block" width="2"
height="2"></td>'."\n";
echo '</tr><tr>'."\n";
echo '<td colspan="3" height="7"><spacer type="block" width="7" height="7"></td>'."\n";
echo '</tr></table>'."\n";
echo '<table border="0" cellspacing="4" cellpadding="0" width="100%"><tr>'."\n";
echo '<td valign="top"><p><b class="welcome">Welcome back, Sam</b></p>'."\n";
echo '<p>Please check our <font face="Comic Sans MS,Georgia,Tahoma,sans-serif" color="#FF0000"
size="+2"><b'."\n";
echo 'class="rainbow">Weekly Specials...</b></font></p>'."\n";
echo '<p>Since your account is in good standing, we have an exclusive offer for you.'."\n";
echo 'We are overstocked on the listed items and are aiming to reduce or inventory by 75%'."\n";
echo 'with this weeks <b>Inventory Reduction Sale</b>. We\'re offering these popular items
at'."\n";
echo 'a <font color="#FF0000"><b>20% Discount</b></font>. The table at right is generated'."\n";
echo 'from our database. It shows how much inventory we wish to sell of each item and'."\n";
echo 'is refreshed each time you log on. They\'re moving fast! Be sure to visit each week'."\n";
echo 'to check our specials.</p>'."\n";
echo '<p>As always, we offer <font color="#FF0000"><b>Free shipping</b></font> on orders'."\n";
echo 'over $30.00.</p>'."\n";
echo '<p>Sorry, no rain checks if an item sells out.</p></td>'."\n";
echo '<td rowspan="2" valign="top">'."\n";
// Following HTML can be used to float a DIV in a paragraph of text
// echo '<div style="position:relative;float:right;border:2px solid #033E66">'."\n";
// Get the first report
if ($rptObj->getRecordCount() > 0) {
echo $rptObj->getReport();
}
else {
echo '<br><nobr><b> No sales this week. </b></nobr></br><br>';
}
132
QLR Manager User’s Guide
Report Objects
echo '<table border="0" cellspacing="2" cellpadding="0"><tr><td></td></tr></table></td>'."\n";
echo '</tr><tr>'."\n";
echo '<td valign="bottom"><b class="welcome">Your order history:</b></td>'."\n";
echo '<td></td>'."\n";
echo '</tr><tr>'."\n";
echo '<td colspan="2" bgcolor="#033E66" class="celFade" height="1"><spacer type="block" width="1"
height="1"></td>'."\n";
echo '</tr></table>'."\n";
echo '<table border="0" cellspacing="4" cellpadding="0" align="center"><tr>'."\n";
echo '<td align="center">'."\n";
// Get the second report
if ($rptObj2->getRecordCount() > 0) {
echo $rptObj2->getReport();
}
else {
echo '<br><b class="welcome">No order history.</b>';
}
echo '</td></tr></table>'."\n";
echo '</body></html>'."\n";
?>
133
QLR Manager User’s Guide
Data Importer
Data Importer
Overview
The Data Import utility allows a user to load data from various source file types into a database table. QLR Manager's importing
process supports the filtering of the source data, so only the desired data from the source file is loaded to the table. For more advanced
users, the data itself can be manipulated during the import process with QLR Manager's "evaluated formula" technique when
adjustments to the raw data are desired.
For Users with authority, this utility is accessible by selecting "User ID Admin and Tools" from the Connect panel, then clicking the
Data Import header tab. Importing data is a two set process. Step one is to define the Source File and the Target Table associated
with the data. Step two is to "map" the data found in the Source File to the columns found in the Target Table. Optionally, a third step
can be used, which is the definition of load filters and formulas to alter the raw data.
Once the data has been acquired and mapped to a table, clicking the Load Data button found in the top left corner of the data
preview will execute the import.
Source File & Target Table
The source file:
The source file is selected by using the browser's HTML file upload control to navigate to the desired file using the Browse… button.
After a file is selected, clicking the Get File button will load the contents of the file to the server, allowing QLR Manager to work with
the data. The Get File button need only be used once to initially load the data, but the process can be repeated to load a different
source file. There is no harm in acquiring the same data again, but with large source files, the upload process may be time consuming.
Data delimiter:
The data delimiter determines which character QLR Manager will use to parse the source data. The types of delimited data that can be
imported into QLR Manager are "Comma", "Semi-colon", "Space", "Tab" and "Fixed width". The delimiter can be chosen prior to
acquiring the source file data. However, if the delimiter must be changed after selecting and loading a source file, the data does not
need to be acquired again. Simply change the delimiter setting. QLR Manager will automatically parse the data using the newly
selected delimiter.
Fixed width data does not use a character for parsing. Instead, the data is separated by defining the starting points of each column or
field of data. The ending point for that field is one character (space) less than the next starting point value. When Fixed width is the
delimiter, and the Source File and Target File have been defined, the User will be able to specify the starting points in the preview data
table that will be displayed. The starting points are entered into the Col start positions text box, with each starting point separated by a
space. QLR Manager will pre-populate this field with its "best guess" for the field starting points. As the starting points are entered, use
the Refresh button to see how the new values impact the parsing of the data.
Target table:
The Target table is chosen using the controls provided for selecting a database/schema and then the desired table. Once the source
file data has been acquired, and target table has been selected, the "Data Filtering & Mapping" section will appear.
Data Filtering & Mapping
Preview Type:
The preview type provides a means to analyze the data before importing. When the table containing the sample (50 rows maximum) of
the data to be imported is initially displayed, all the rows will be displayed. This includes the rows that will be loaded along with the rows
that will be filtered displayed with a red background. To see a sample of just the rows that will be filtered, choose the "Rows to be
filtered" selection and click the Refresh button. Conversely, choosing the "Rows to be loaded" selection will show a sample of only
those rows that will be loaded during the import.
Header rows:
The header rows refer to leading rows that may be present at the start of the source file, such as column headings or descriptions. This
option provides a means to bypass the loading of these header rows by choosing the number of rows in the beginning of the source file
to be ignored when the data is loaded. These rows will be displayed in a dark red background after clicking the Refresh button.
134
QLR Manager User’s Guide
Data Importer
Data Filtering:
The data filtering controls allow the User to specify the records to load when the data in a column meets the given criteria. Data rows
that do not meet the filter criteria will be shaded with a light red background after clicking the Refresh button. Rows that meet the
import criteria will have a white background. There are two sets of filters that can be used in conjunction with one another, in either an
"And" or "Or" relationship. The column number found in the select list in the first field of the filter represents the column number as
found in the data preview area. In order for a filter to be applied, a column number must be selected. If the column number selection is
left blank, the filter is ignored.
The second field of the data filter allows the User to choose a comparison operator. The comparison operator will be applied to the
column selected in the first field. The third field of the filter is used to enter the comparison values. An example of a basic filter is Col #
7 equals Montana. There is no need to surround the comparison values with quotes.
When the "evaluated formula" is chosen as the comparison operator, the User can create their own PHP based formula in the
comparison field. An example might be the 3rd column of data contains the last name and only imported data desired is where the last
name is Jay, but the data it is a mixture of entries such as Jay, JAY and jay, along with other last names. The User could set the
column reference to Col # 3, the compare operator to "evaluated formula" and the comparison text field could contain the evaluated
formula of strtoupper($value)=='JAY'. This combination will find all occurrences of Jay, regardless of the case of the letters. The
evaluated formulas used in the data filters do not change the data being loaded. The evaluated formula found in the data preview area
can be used to manipulate the data during load.
As with other places where evaluated formulas are supported in QLR Manager, data found in other columns can be referenced by using
the $val[ ] array format. For example, if the customer number is found in column 1, and the state is found in column 6, an evaluated
formula can be written to import all customers, whose customer number is greater than 2000 and are in NY: $val[1] > 2000 &&
$val[6]=='NY'. Please note that when using the $val[ ] technique to reference column data, the column reference field (such as Col # 1)
is not used. However, a column number must be selected to apply the filter (any Col #). QLR Manager will only apply a filter if the
column reference selection is not blank.
Import Data Preview
Once a source file and target table have been selected, the Import Data Preview will appear showing the first 50 rows of source data. It
is in this preview where the source data is mapped to the columns in the chosen table.
When the data is displayed in the preview, the number of characters for any given column of source file information is limited. When
delimiters other than "Fixed width" are used, the data is limited to displaying the first 25 characters, followed by "...", which indicates
that the data has been limited for display purposes. When the data is fixed width, the middle section of the data is removed and
replaced with "...". The first 25 and last 25 characters are displayed.
Source file column:
The source file column number is used as a reference for each of the data columns that are the result of the data parsing. These
column references are used with the data filtering option.
Map table columns:
This is the most important of the import preview options. The column mapping is where the columns in the source file are mapped to
the table columns when loaded. At least one column in the source data must be mapped to a table column. A source data column can
only be mapped to one table column. QLR Manager will check for both of these conditions when the Load Data button is clicked. If
either condition is found, the User is returned to the Data Preview to correct the situation.
Column data types:
As the mapped columns are selected, the column data type is updated to display the "type" of data that is associated to that table
column. Typical entries are varchar, int, datetime, etc. This can help in determining if the source data is being mapped to the correct
table column.
Evaluated formulas:
The evaluated formula provides the User the ability to manipulate their data to be loaded using PHP. This gives the User unlimited
flexibility in performing clean-up when importing their data. The data in the column is referenced by $value. Data in other columns is
referenced using the $val[ ] array format. Some evaluated formula examples are:
•
•
•
•
$value = strtolower($value)
$value = substr($value,1,4)
$value = $val[2].substr($val[7],2,8)
$value = date('Y-m-d')
The impact of an evaluated formula can be seen by clicking the Refresh button.
135
QLR Manager User’s Guide
Data Importer
Column start positions:
This option is only displayed when "Fixed width" data is being imported. It allows the User to specify the break points to parse the
source data into separate columns of information. The numeric values entered into this field are separated by spaces, such as 1 15 32
56. When a source file is first loaded, and the Data delimiter is "Fixed width", QLR Manager will try and determine what the starting
points might be by looking for repeating patterns in the source data. It also does this when the starting point input field is blank, and a
Refresh button is clicked. The User can edit the values in this field and click the Refresh button to view the impact of new values.
Column position gauge:
This option is only displayed when "Fixed width" data is being imported. The gauge allows the User to determine the proper starting
points to be defined when working with fixed width data.
136
QLR Manager User’s Guide
Installation
Installation
General installation instructions
QLR Manager is a Query, Layout and Report (QLR) Manager that allows you to write SQL queries, run them, save them, and share
them with other users. Once a SELECT query has been run, the resulting report can be formatted by creating a layout and applying the
Layout to the Report data. Output from non-SELECT queries can also be viewed, but a layout cannot be applied to this type of output.
QLR Manager also provides the ability to Define Macros and Create User Menus. Through the use of User Profiles defined with User ID
Administration, the Administrator is provided extensive control over the capabilities of a User ID. These capabilities range from a
Restricted User that can only connect and run queries and macros from a menu, through an Advanced User that can create and save
queries, wizard, layouts, macros and menus.
QLR Manager uses a series of database tables to manage this information. These tables must be created and populated with control
data in your database. It is suggested that you create a separate database space (schema) within your overall database to manage
these tables.
Establishing the QLR Manager operating environment:
The basic requirements are:
• PHP 4.1 or greater.
• A database engine supported by QLR Manager.
Installing the QLR Manager application:
The Install & Migration Manager is intended to guide you through the installation process. There are only a few steps in the process,
each requiring minimal information. Once the necessary information is gathered, the actual execution time of the installer only takes a
few seconds, depending on your server. These are the steps:
1 Download the desired archive type of the Full Version package from our Downloads page.
2 Create a directory, e.g. /qlr, /qlrmgr, etc. in your server's execution path for QLR Manager.
3 Unzip or untar the contents of the full install package into the new directory and be careful to preserve the original
directories/folders as they exist in the install package. If you download and extract the contents on a client, you can FTP the files
to your new server directory.
4 Obtain a FREE 30 day trial license for the Enterprise Edition from our Purchase page. Place the QLRlicense.inc file into the
new server directory. If you first request a trial license and later wish to buy QLR Manager, you simply upgrade the trial license.
5 It is optional to temporarily grant Read, Write and Execute (Unix 777) permissions to the main directory you created in step #2.
This will allow the install program to write the qlr.ini file into this directory. If you don't grant this authority, the install program
displays its output to the browser, which allows you to copy and paste the contents necessary to manually create the qlr.ini file.
The qlr.ini file must be present in the new server directory to run QLR Manager. If write authority is granted, don't forget to remove
it after the installation is completed.
6 From your browser, start the install program by referencing install.html in the newly created directory, e.g.
http://127.0.0.1/qlrmgr/install.html. Select the New Installation option and click the Begin button.
7 Carefully follow the instructions on the install panels, paying attention to any messages generated during the install. The bold
labels are linked to help in the Installation topic of the QLR User's Guide. Use the buttons on the bottom of the panel to proceed
through the install process.
8 After completing all the install panels, the qlr.ini file will be created with all the configuration parameters for your QLR Manager
installation. If you granted the authority suggested in step #5, the qlr.ini file will be written into the new server directory.
9 Grant Read, Write and Execute (Unix 777) permissions to the following directories in the QLR Manager directory structure:
• /reports to allow for temporary output file storage and support the creation of PDFs.
• /graphs in the Enterprise Edition to support the creation of charts and graphs.
• /html2pdf/fpdf/font to allow PHP to create font files used during PDF creation. The iso-8859-1 Western European and US
charset fonts are pre-built and shipped as part of the install package. If a different HTML character set is selected during
installation, write permissions must be granted to this directory.
10 From your browser, start QLR Manager by referencing qlrmanager.html in the newly created directory, e.g.
http://127.0.0.1/qlrmgr/qlrmanager.html
137
QLR Manager User’s Guide
Installation
The Install & Migration Manager is not only intended to initially install QLR Manager, it can also be used to update the QLR Manager
parameters. On installation step Step 2 of 3, there is a button at the bottom of the page to Update Settings Only . This will bypass
dropping and re-creating of the tables used by QLR Manager, and only update the parameters in the qlr.ini file.
The install process can be started by entering install.html, with the proper path information, into your browser. Install.html resides in
the top level directory you created to store the QLR Manager files on your server.
Items to consider before installing
Before running the install program, there are several items that should be considered:
•
•
•
•
•
•
•
On what server will the QLR Manager application be located?
How will I be storing the temporary HTML content that is produced by QLR Manager? In files on my server, or in a database?
What Database ID will be used to perform the install?
What database/schema (new or existing) will the QLR Manager tables be installed in?
On what server is this database located?
What Database ID (new or existing) will run QLR Manager?
Do I want to use or change any of the Advanced Settings?
Prior to running the install program, you should browse through this documentation to answer the preceding questions.
Where to store your report pages
When QLR Manager runs, it produces HTML output to be displayed by the client's browser. Some of this HTML, particularly report
output, must be stored somewhere in order for the application to provide some of its functions such as downloads of various formats
and emailing output. It can be stored in either your server's file structure or inside the database you will be working with.
The default install setting for pageSource is to store the pages as files in the /reports directory. There may be times when you are not
able to choose the file option for storing pages. An example would be when you are using a UNIX based hosting service that runs its
web server ID as "nobody". In this situation, you would have to grant read, write and execute permissions to all users (UNIX
permissions of 777) in order for the web server ID "nobody" to write the pages to the /reports directory. The 777 setting leaves you wide
open for other persons on your server to access your /reports directory, and from there, the rest of your server directories. In these
instances, you may choose to use the database storage option, as opposed to a 777 directory setting.
As with all the settings in the qlr.ini file, you can experiment with both options by updating the settings only.
If you do choose the file option, you can password protect (.htaccess) the /reports directory. This will force the User to enter a User ID
and password prior to being able to use the application.
138
QLR Manager User’s Guide
Installation
Granting access to the /reports directory:
UNIX
• The CHMOD command can be used to grant read/write access to a file or directory. A setting of 755 can be used. See above for
when it might not be possible to establish 755 permissions.
Windows 2000
•
•
•
•
IIS runs with an anonymous user called IUSR_ followed by your computer name (i.e. IUSR_MYCOMPUTER).
You will need to go to the folder or file you are trying to write to, right-click and choose Properties.
Click the Security Tab, then click the Add button.
In the drop-down list, select your computer if it isn't already selected, and look for the IUSR_ account. Click on this item and click
the Add button. It may take a few seconds to process.
• You will then return to the panel with file permissions. Check the read and read and write permissions, then click OK .
Windows XP
• Go to the /reports folder, right-click it and choose Sharing and Security.
Note: This only works for the /reports folder and not the qlr.ini file. You will need to update the qlr.ini file manually at the end of the
install process.
• Click the Sharing Tab.
• Under Network sharing and security, check both the "Share this folder on the network" and the "Allow network users to change my
files". Keep the Share name as "reports".
Recommended php.ini settings
The PHP Core configuration settings can be changed by editing the servers php.ini file. Adjusting the following 3 settings will help
ensure QLR Manager functions properly on your server. If you're running on a shared hosting environment, check with your Hosting
Service (ISP) about modifying these settings. Some ISPs provide solutions where the php.ini file can be read from the hosted domain to
override the server's default php.ini settings.
max_execution_time Should be set from a minimum of 60 seconds to as long as 90 seconds to support large, sophisticated queries.
Beyond 90 seconds, the browser may timeout waiting for a response from the server.
memory_limit
The Enterprise Edition with chart support enabled should be set to a minimum 32M.
The Enterprise Edition without chart support, or other editions, should be set to a minimum 16M.
safe_mode
With this mode set to OFF, QLR Manager will adjust memory allocation and execution time as needed to
execute large queries or longer running macros.
PHP GD support
If you intend to create charts and download PDFs, GD support must be enabled in PHP. More information is
provide below about Chart support and Graphics manipulation with PHP.
QLR License file
In order to run QLR Manager, you must have a product license file. Prior to buying QLR Manager, we urge everyone to take advantage
of our FREE 30 day trial of the Enterprise Edition. This will ensure it runs correctly in your environment and the product meets your
expectations. If you first request a trial license, and then wish to buy QLR Manager, you will simply upgrade the trial license. To receive
a license, you must first create a user account so we can e-mail your license file. A trial or purchased license can be obtained from the
Purchase page of our web site.
To install the QLRlicense.inc license file, copy the file into the same directory where QLR Manager is installed, which is the same
directory where the file qlrmanager.html is located.
A license will entitle you to free upgrades and fixes within the same version. We don't release a new version until we incorporate
significant new function and features. Upgrades to new versions are steeply discounted for existing license holders.
139
QLR Manager User’s Guide
Installation
The qlr.ini file
In order for QLR Manager to run, it must create a file called qlr.ini in which it stores the parameters that were provided during the install
process.
When the install program completes, it attempts to write the contents of this file into the main QLR Manager directory (where
qlrmanager.html resides) by either creating or replacing the qlr.ini file. If the application has authority to write this file, it will do so. If not,
it sends the content to your browser window. You can simply create a file called qlr.ini (all lower case) in the main QLR Manager file
directory and copy and paste this information into the file.
If you wish to have this file automatically created, see the section on Where to store your report pages for information on how to set up
proper read/write authority to the main directory.
The qlr.ini content will look as follows. As you can see from the amount of content created below, copying and pasting the information
may be easier than setting up the necessary read/write access.
// *********************************************************************
// Created by QLR Install Manager on 06-12-2006 19:16:47
// Contains QLR Manager configuration variables for product version 5.0
// This file can be manually edited, except for the userid and password.
// You must use the install program to update these two values.
// *********************************************************************
db
= baitshop
host
= localhost
useSchema
= Yes
userid
= VmxaV05GVXhaM2hWVkDFOStY
password
= Z28yFmKtMCtN
dbType
= mysql
appServer
= localhost
adminEmail
=
sysEmail
=
cacheSize
= 5000
reportRows
= 500
maxTime
= 300
imageCache
= 20
DBfilter
=
startFile
= qlrmanager.html
logoffFile
= http://www.mysite.com
maxSizeMB
= 3
pageSource
= database
isGraphing
= Yes
archiveDays
= 60
charset
= iso-8859-1
ldap
= Yes
DBlogin
= No
primerDB
=
showErrors
= No
140
QLR Manager User’s Guide
Installation
General install options
The following selections and values can be entered during installation to customize many features of QLR Manager. The values will be
populated in the qlr.ini file.
HTML character set for generated output:
QLR Manager allows you to specify the character set that is used in the HTML page encoding. This allows your browser to interpret
various character sets. QLR Manager provides a drop down list of the most common character sets, but this entry in the qlr.ini file can
be specifically edited if necessary.
The MySQL version of QLR Manager, when using MySQL version 4.1 or later, allows for you to install the product as UTF-8 database
tables. This option is found in the Advanced Settings section of Step #2 of the installation process. The selection is stored in the qlr.ini
file as the charset value.
Database:
The Database specifies the type of database engine with which QLR Manager will interact. This selection is stored in the qlr.ini file as
the dbType.
Login ID and Password:
Once you have run the install process and created a qlr.ini file, the master userid and password that were created in the qlr.ini must
be entered to update the file when running the install program for a second time. You will be given 4 attempts to enter the correct ID
and Password. After that, it is necessary to close your browser session and try again.
Click on these links for install information specific to MySQL or Oracle configurations.
QLR Manager ID:
An ID must exist or be established that will have the ability to update the QLR Manager tables. Its purpose is to be able to save, update
and delete the queries, wizards, layouts and other data that will be created by QLR Manager. It is best to create a separate ID to run
QLR Manager, as the installer will grant SELECT, UPDATE, INSERT and DELETE privileges to this ID for each of the tables created to
support QLR Manager.
MS SQL Server requires that the QLR Manager master ID is an existing SQL Server ID and password that has been set up in SQL
Server to use "SQL Authentication".
Password for the QLR Manager ID:
In order to connect to the database where the QLR tables reside, the QLR Manager ID requires a password. It is suggested that a
password be 6 to 16 characters in length, and contain both alpha and numeric characters.
When the ID and password are saved in the qlr.ini file, they are encrypted by the install program. All values, except for the QLR ID and
password can be edited with a text editor in the qlr.ini file.
Note: Do not attempt to manually edit the QLR userid or password values in the qlr.ini file. Use the install program to update the
userid or password by launching your web browser and accessing the file install.html. Select the Upgrade existing installation option
and proceed through the panels to Step 2 of 3 and click Update Settings Only .This will update the userid and password in your
qlr.ini file. Close your browser and open a new browser session to test the change.
Create a schema:
When using PostgreSQL, you have the option of creating a separate schema for the QLR Manager tables. If you do choose to create a
schema, it will be given the same name as the QLR Manager ID you create. If you do not choose this option, the QLR Manager tables
will be created in the "public" schema. This option will only appear for a PosgreSQL install.
The file path where the MS SQL Server database will be located:
If you are creating a new Microsoft SQL Server database for storing your QLR Manager tables, you must reference the absolute path
where SQL Server should store the database on your file system. Do not include the database file name in this reference. QLR
Manager will default this value to where the SQL Server master.mdf file is stored on your system.
An example of a path name is C:\Program Files\Microsoft SQL Server\MSSQL$LOCALHOST\data\
User ID and Password request:
The email address for User ID and Password request is used on the QLR Manager Connect panel. It is presented as an
expandable/collapsible section entitled Request ID and Password. It contains fields for the User to enter their email address, subject,
and description. This option is not available with the Basic edition of QLR Manager and will only be visible if a value is provided for this
field. The value is recorded in the qlr.ini file as sysEmail.
141
QLR Manager User’s Guide
Installation
Report database problem:
The email address for reporting database problems is used on the QLR Manager Connect panel. It is presented as an
expandable/collapsible section entitled Report Database Problem. It contains fields for the User to enter their email address, subject,
and description. This option is not available with the Basic edition of QLR Manager and will only be visible if a value is provided for this
field. The value is recorded in the qlr.ini file as adminEmail.
Archive days for charts:
The sending of e-mails that contain charts can be done in one of two ways. The first is that the charts are sent as attached files. The
second is to reference the charts as an in-line image, using an HTML <img> tag. When sent as an in-line image reference, QLR
Manager has to maintain a copy of the chart on the server. This setting specifies the number of days for the files to be retained before
being erased. The value is recorder in the qlr.ini file as archiveDays.
Advanced settings
There are several advanced settings that control how QLR Manager behaves.
Report array cache size:
The cacheSize value controls how much data from a query is stored in memory after the query has run. The larger this number, the
quicker the response will be when formatting your data with Layout information. The drawback is the amount of server memory that will
be used, which if too much, will actually slow performance. A typical setting is 5000.
Report rows:
The reportRows value sets a default which controls the total number of rows of data that are displayed when a query result is shown. A
larger number will show more data, but it takes longer to display results, especially if a user is connected via a modem. This value can
be overridden with the Max displayed rows control in the Report Body section of the Layout panel for specific reports. If the Layout is
saved as the same name as the query or wizard producing the report, it will become the default layout applied when the query, wizard
or menu item is executed. When the number of rows produced by the query exceeds this reportRows value, navigation links (First,
Back, More, Last) are presented above the report to move between page sets.
The number of rows displayed will not always be exactly equal to this setting, as subtotaling data will add additional rows to reports.
QLR Manager will always complete the current page with data. If you have a reportRows setting of 500 and the 500th row appears in
the middle of the page, QLR Manager will fill up the final page with rows of data, if there is more data available.
Maximum execution time:
This maxTime setting determines the maximum amount of time that is allowed for an action to complete, such as running a query. A
typical setting is 300 seconds.
Image cache size:
QLR Manager is able to display binary data (BLOB fields) as images. In order to do this, it must temporarily store the images outside of
the database on the server. The imageCache setting determines the amount of memory in megabytes to allocate for image
management. A typical setting is 30. Once this limit is exceeded, no more images of this type will be displayed in the report.
QLR Manager startup file:
This option allows you to change the name of the start up file for QLR Manager. The default value is qlrmanager.html. If you wish, you
can rename qlrmanager.html so that the Users can start QLR Manager by referencing a different file name. If the file is renamed, the
name of the new file should be entered and will be recorded in the qlr.ini file as startFile.
Note: A file named js_bver.html located in the /qlr_manager directory contains a line of Javascript near the top of the file:
if (self == top) location.replace("../qlrmanager.html")
The reference to qlrmanager.html should be replaced with the new start file name.
QLR Manager logoff file:
This option allows you to specify a URL that the User will be directed to when clicking the Log off button in the header. The default
behavior is to direct the User to the Connect panel when logging off QLR Manager.
142
QLR Manager User’s Guide
Installation
Maximum output file size:
This maxSizeMB value allows you to specify the maximum size of files to be created to send to the User's browser session. This value
is entered as a number between .5 and 16, representing page sizes from .5 to 16 megabytes. The default value is 5 megabyte.
If a query produces a report with numerous columns of data, then the number of rows returned will be limited to stay under the size
limit. Where this setting is most relevant, is in the production of reports in Macros. As there is no row limitation to the number of rows of
data the will be returned in a SELECT query when used in a Macro, the output will be restricted to fall under the set limit.
Note: For MySQL users, the mysql database engine has a parameter called max_allowed_packet, which determines the amount of
data that can be sent to the server in the form of a query. More information on this can be found here. When using MySQL and
choosing to store your report pages in the database, the default value is 1 megabyte, which is the default setting for the
max_allowed_packet setting in MySQL.
Database selection filter:
The DBfilter value allows QLR Manager to filter out the database selection list that is presented to the User. If you're accessing a
database with hundreds of schemas, it allows you to narrow down the display list. This may very well be the case if you are on a
hosting service that shares a database engine. It uses the SQL LIKE command format and is case sensitive. A setting of fin% would
select all databases beginning with "fin". You do not need to enclose this filter text in quotes.
If a DBfilter of **omit** is specified, then the database/schema selection control will be suppressed from appearing altogether. This may
be helpful in large Oracle installations with thousands of schemas.
LDAP interface support:
LDAP (Lightweight Directory Access Protocol) support allows for the interfacing with an external directory to authenticate a user when
they attempt to connect to QLR Manager. The qlr.ini keyword is ldap. If enabled, when the Connect button is clicked at logon time,
QLR Manager looks for a file called ldap.php and executes it. It is up to the installer of QLR Manager to place the PHP code they wish
to execute into the ldap.php file. The PHP code can be designed to execute LDAP functions, or any other functions that are desired.
At the bottom of the file, there are several variables that are passed back to the login process. These are:
• $ldap_authentic This is set to either TRUE or FALSE, and tells QLR Manager whether the login ID has been authenticated by the
external process
• $ldap_message This is an optional message that can be displayed when $ldap_authentic = FALSE
• $ldap_user is an optional value that can be set to replace the login ID that the users provided. This value might be part of a user's
directory data.
• $ldap_password is an optional value that can be set to replace the login password that the users provided. This value might be
part of a user's directory data.
Simple Mail Transfer Protocol (SMTP) support:
QLR Manager's default behavior examines your system's php.ini file to determine the SMTP server (php.ini setting for "smtp") and port
(php.ini value of "smtp_port"). It is possible to override these values, as well as providing a User ID and Password, by adding entries to
the data table called qlr_info (notice this is not the qlr.ini file, but a database table).
This is accomplished by connecting to your master QLR Manager database/schema and issuing the following SQL commands in the
Query panel:
insert into qlr_info values ('smtp_server','mysmtpsite.com');
-- optional port, default value is 25 if not specified
insert into qlr_info values ('smtp_port', '22');
-- optional userid, provide if necessary
insert into qlr_info values ('smtp_userid','fred');
-- optional password, but must be used if userid is provided
insert into qlr_info values ('smtp_password','mydog8it');
When distribution e-mails are sent, QLR Manager attempts to connect directly to the SMTP mail server's socket. However, in some
environments, QLR returns a false positive that the socket connection method is working properly. If this is the case in your situation, an
optional entry of useSocket = No can be added to your qlr.ini file. This will instruct QLR Manager to not directly use the SMTP socket.
The drawback of employing this setting is that distribution e-mails will be sent at a slower rate.
143
QLR Manager User’s Guide
Installation
Creating pseudo log on IDs and passwords:
The base function of QLR Manager is to validate the User IDs and passwords that have been established in the database engine. It is
also possible to create "pseudo" QLR Manager IDs and passwords that will allow persons to connect to the database. The actual ID
and password that these pseudo IDs will connect through is the QLR master ID and password.
Pseudo IDs may be useful in instances such as establishing IDs for a set of customers, a class of students or other groups of users.
Each ID can manage its own set of Queries, Layouts, etc. and authority levels can be controlled using QLR Manager's User ID Admin
and Tools function accessed from the Connect panel.
In order to utilize this function, the qlr.ini file must be edited to set ldap = qlrid. The second step is to edit a php file (found in the main
QLR directory) called qlrid.php. This file will contain the pseudo IDs and their passwords, so take care to limit access to this file. The
content of the editable portion of qlrid.php is included below. The two user IDs that are present in the file are for example purposes only.
You should edit this file to add your desired IDs and their passwords.
<?php
// don't edit above this line
//
//
//
//
//
//
//
**********************************************************************
This file is designed to allow you to create 'pseudo' users
that will connect to QLR Manager using the QLR master ID and password
but will appear as individual users with their own queries, layouts, etc.
NOTE: the qlr.ini file must be updated so that the ldap entry is
ldap = qlrid
**********************************************************************
// initial state of authentication
$qlrid_authentic = FALSE;
// build up an array of all the pseudo users you want to manage.
// the format is an associative array where
// the $user[userid] is assigned it's password
$user = array();
// userid
password
$user['tom']
= 'misty';
$user['charlie'] = 'i82much';
// validate that the password is correct for
if (isset($user[$_POST['userid']])) {
// good password for the userid.
if ($user[$_POST['userid']] == $_POST['password']) {
$qlrid_authentic = TRUE;
}
// password did not match. This is the failure message
else {
$qlrid_message = 'Could not authenticate login ID '.$_POST['userid'];
}
}
// this allows all existing other normal database id's to be used
// remove the following line if you want to block their access
else $qlrid_authentic = 'bypass';
// don't edit below this line
?>
Bypassing direct socket e-mail distribution (optional):
When distribution e-mails are sent, QLR Manager attempts to connect directly to the SMTP mail server's socket. However, in some
environments, QLR Manager returns a false positive that the socket connection method is working properly. If this is the case in your
situation, an optional entry of useSocket = No can be added to your qlr.ini file. This will instruct QLR Manager to not directly use the
SMTP socket. The drawback of employing this setting is that distribution e-mails will be sent at a slower rate.
144
QLR Manager User’s Guide
Installation
Presetting the connection server:
In a single database server environment, it may be desirable to preset the server value so that the DB server input field on the
Connect panel is not displayed to the User and the server value is automatically assigned. This is accomplished by manually adding
a line item to the qlr.ini file to set the "presetServer" value. An example of such an entry is:
presetServer = localhost
Chart support
The Enterprise Edition of QLR Manager supports chart creation. In order to produce charts, PHP must be running with GD support,
either basic GD or GD2. GD support is enabled by uncommenting the proper PHP extension in your php.ini file, which is either
extension=php_gd.dll or extension=php_gd2.dll. You can easily tell if GD support is enabled for your installation by clicking on the
Click here to test for GD support link, which is found in Step 1 of the installation routine. If it is installed, the message PHP GD
support is installed will appear.
From an article located at http://www.macromedia.com/devnet/mx/dreamweaver/articles/php_graphics_03.html, below is a brief
explanation on how to install GD support:
Graphics manipulation with PHP
GD is an ANSI C library for the dynamic creation of images. Much like PHP, GD is an open source library that is maintained by
Boutell.com; the official home page of GD is http://www.boutell.com/gd. As of this writing the current version of GD is 2.0.3 for the
stable version. GD was once able to output both the GIF format and the JPG formats, however because of the Unisys patent, version
1.6 was the last with GIF support. The GD developers moved in favor of PNG, which we'll be using here.
Installing GD from Source:
Installing GD is pretty straightforward on both Windows and Linux. On the Macintosh I'd recommend a precompiled binary. An excellent
source for Mac users is from Marc Liyanage at http://www.entropy.ch. GD is going to be standard in the next upcoming release of PHP
4.3. Once this version becomes available, GD will be there by default. Many precompiled versions of PHP come with GD support.
Windows:
Getting GD enabled on the Windows platform is very easy. The GD module is included in the PHP distribution, but is not enabled by
default. You will need to modify your php.ini file and uncomment the line:
;extension=php_gd2.dll
Then make sure the php_gd2.dll library is in the correct directory. You will have to restart your web server if PHP is running as a
module. No restart is needed if PHP is running as a CGI.
If your ISP does not have the GD library compiled in to PHP, you can use the dl() function. Although it's slower, you can also choose to
load the GD module on demand.
<?php
dl('php_gd2.dll');
?>
Linux:
Binding GD to PHP under Linux is more challenging, but only required if running a PHP version earlier than 4.3. You'll need to
download GD as well as FreeType if you plan to do TrueType font manipulation You can get GD from the Boutell homepage at
http://www.boutell.com/gd/. You can get FreeType at http://www.freetype.org/.
Unpack the GD and FreeType distributions, and run the following commands in each.
make
make install
Once GD is built you need to bind it to PHP. In the directory that contains the PHP source, type:
./configure --with-gd --with-freetype-dir
make
make install
If you have any additional parameters to configure PHP, you'll need to add them to the configure statement.
For RedHat and other RPM users, binary installs for the i386 platform are available at: http://rpms.arvin.dk/php/.
A simple call to phpinfo() reports whether the GD library is bound to your install of PHP.
145
QLR Manager User’s Guide
Installation
This version of PHP is correctly bound to GD as the output of phpinfo() has an entry for the GD extension. This version has JPG and
PNG support.
Once you have confirmed that GD support is installed, the true test for creating charts is done by clicking on the Click here to test
chart creation link. It should create the following chart:
You must be able to create this chart in order to have QLR Manager produce charts. If you can't, then you should return to the start
and uncheck the Install with charting support checkbox on the initial install panel.
146
QLR Manager User’s Guide
Installation
Version migration
A migration is necessary when the underlying QLR Manager database tables, or data in those tables, must be updated. A migration is
always necessary when upgrading from one major version to another, e.g. version 4.1.5 to version 5.0. In addition to updating the QLR
database tables, the migration will copy your existing queries, layouts, etc. to the new version.
The same QLRlicense.inc file will work with all levels of the same major version number. In other words, a version 4 license will work
with versions 4.0, 4.1.5, etc. but not version 5.0. Existing customers upgrading to the latest version will receive a 60% discount for a
one version upgrade and a 20% discount for a two version upgrade. Before purchasing an upgrade license, we urge you to take
advantage of a FREE 30 day trial license for the Enterprise Edition of the new version. Trial licenses can be obtained from our
Purchase page. If you first request a trial license and later wish to buy QLR Manager, you simply upgrade the trial license.
1 Download the desired archive type of the Full Version package from our Downloads page.
2 Create a new directory, e.g. /qlr_v53, for the new version of QLR Manager.
3 Unzip or untar the contents of the full install package into the new directory and be careful to preserve the original directories/folders
as they exist in the install package. If you download and extract the contents on a client, you can FTP the files to your new server
directory.
4 Copy the qlr.ini file from your existing QLR directory into the new directory.
5 If you are utilizing the conmsg_xxx.html file (Connect panel message where xxx represents the language code), copy your existing
conmsg_xxx.html file into the new directory.
6 Place the trial or purchased license file (QLRlicense.inc) for the new version into your new directory.
7 Below are the steps to follow depending on your currently installed version. The version appears in the header of the Connect
panel when first accessing QLR Manager.
Version 5.0 or newer:
• Launch your web browser and access the file qlrmanager.html in the newly created directory, e.g. /qlr_v53. QLR Manager will
automatically detect that it needs to update its data tables. An Update button will be presented. Click this button to update your
version of QLR Manager.
Versions prior to 5.0:
• Launch your web browser and access the file install.html in the newly created directory, e.g. /qlr_v53. Select the Upgrade
existing installation radio button near the top of the panel and click the Begin button.
• You will be prompted to enter the master QLR Manager User ID and Password that you created and stored in your qlr.ini file with
the initial installation of the earlier version. Click Continue
• Verify the license information on the next panel and review any other notes and messages. Click Proceed to Step 1
• The next few panels will collect all the information necessary to perform the migration. Complete all the applicable fields and
selections, while paying attention to any messages. The bold labels are linked to help in the Installation topic of the QLR User's
Guide. Use the buttons on the bottom of the panel to proceed through the upgrade process.
• The install program will display the results of the upgrade activity as it migrates your QLR data (queries, layouts, etc.) from the
prior version to the new level of QLR Manager tables. Please check the results for any errors that may have been encountered.
• Test your new version of QLR Manager. Once you are satisfied that it is working correctly, you can rename or delete the old
version directory and rename the new directory to the old directory name.
If you wish to erase your existing queries and layouts, or this is a new installation, simply access install.html with your browser and
choose the New Installation option to install the product.
147
QLR Manager User’s Guide
Installation
MySQL
Server configuration
QLR Manager can be set up in different ways, depending on your server configuration. The most important item to note is the
referencing conventions used to configure QLR Manager and to grant your users access to their data.
Single server configuration:
The single server setup is rather straight forward. Both the database that the users will access, and the QLR Manager application, are
on the same server. When this is the case, the server is referred to as "localhost". This means the following:
• Your master QLR Manager ID that you create must have access to the QLR Manager tables, with the requesting server being
"localhost"
• Your users' database ID's must have access to their data on "localhost".
• When your users log into QLR manager, they can reference "localhost" as the server.
One Server Setup
Database & QLR Manager on the same server
Multiple server configuration:
If the QLR Manager and the database servers are different, the referencing is not difficult, but it is a little trickier than calling all server
references "localhost". The important thing to remember is that when you establish database access (within your database application),
it is based on which server a request is coming from, not based on where the data is located.
• The master QLR Manager ID that you create must have access to the QLR Manager tables, with the requesting access coming
from the server where the QLR Manager application resides.
• Your users' database ID's must have access granted to their data, with the requesting access coming from the server where the
QLR Manager application resides.
• When your users log into QLR manager, they reference the server where their data is located, which enables QLR Manager to find
it. Note: Be sure to grant your users access to execute their commands as coming from the server where QLR Manager resides.
148
QLR Manager User’s Guide
Installation
Two Server Setup
Database & QLR Manager on different servers
Running the install program
Once the proper access has been established, the install program can be run by invoking a URL that references install.html. This is
found in the main directory of the directories you established when you loaded QLR Manager to your web server.
• If you have not established the proper file access to the /reports directory, and you have chosen to store your pages as files, the
install program will issue a warning message.
• A warning message will also be generated if you have not established proper access to the qlr.ini file.
Even if you don't grant access to create/update the qlr.ini file, the information needed to populate this file will be displayed on the install
status page (see below) and you can manually copy and paste this data into the qlr.ini file.
There are only few steps to the install process:
1 If this is the first time you are using the installer, you will be asked to accept the terms of the license agreement. If it is not the first
time using the installer (there is an option to Update Settings Only on the second page of the install program), you will be prompted
to enter the master QLR Manager User ID and password. Even though the install manager is password protected, it is
recommended that you rename install.html once you have finished the installation.
2 Next you will be asked to define the database engine with which QLR Manager will be working.
3 The first installer page gathers information about your operating system and an existing database ID to perform the install. When
the first page is displayed, it also verifies that the proper access exists for the qlr.ini file and /reports directory. If it does not, a
warning message will appear at the bottom of the first page.
4 The second installer page gathers information about the database that will house the tables that drive QLR Manager. This page
also contains some advanced settings options.
5 The final installer page is a status page that will give you the results of your install or Settings Update, along with information to
manually update your qlr.ini file.
Database server
QLR Manager uses a small set of tables to manage its information. The database server identifies the server that will contain the
database for these tables. This can be either a computer name or an IP address. If the QLR Manager database and the QLR Manager
application reside on the same server, "localhost" can be used to describe the database location.
149
QLR Manager User’s Guide
Installation
Application server
The Application Server identifies the server on which the QLR Manager Web application will reside. This can be either a computer
name or an IP address. If the QLR Manager database and the QLR Manager application reside on the same server, "localhost" can be
used to describe the application location. There are really only two choices for the server name:
• "localhost" if you plan on running QLR Manager and the QLR database on the same server.
• The name or IP address of the server that is running this install program.
Existing ID to perform the install
In order to perform the installation, you must specify an ID that exists in your database, which has sufficient authority to execute the
install. This ID needs the authority to be able to:
• Create new databases.
• Create a new user ID.
• Grant SELECT, UPDATE, INSERT and DELETE authority to the QLR Manager ID that will be created in the install process.
In order to connect to the database to perform the installation, you must also provide the password for the installation ID. This ID must
be able to receive requests from the QLR Manager application server.
For example, if the ID to perform the install is called "Fred", and the QLR Manager application server is called "webapps", then fred
should have been created with a database command similar to:
GRANT SELECT, UPDATE, INSERT and DELETE on *.* to fred@'webapps' with GRANT OPTION;
New or existing database
You must decide which database that the QLR Manager files will reside. It is recommended that a separate database be established for
the QLR Manager tables, but it is not mandatory to do so.
Installing QLR Manager with UTF-8 tables
A Unicode transformation format (UTF) is an algorithmic mapping from every Unicode code point (except surrogate code points) to a
unique byte sequence. The ISO/IEC 10646 standard uses the term "UCS transformation format" for UTF; the two terms are merely
synonyms for the same concept. UTF-8 is the byte-oriented encoding form of Unicode.
If you are using MySQL 4.1 or later, QLR Manager can be installed specifying that it's data tables be set up as UTF-8 compatible. This
will allow you to store queries, layouts, etc. that contain character data from numerous languages.
This option can be set in the Advanced Options setting in Step #2 of the installation.
150
QLR Manager User’s Guide
Installation
Oracle
Server configuration
In order to install QLR Manager, you will need to know the Oracle database reference name found in the TNSNAMES.ORA file that you
will define to contain the schema which will run QLR Manager. It may also be necessary that your PHP application server be running an
Oracle client (such as an instance of SQL Plus) in order for QLR Manager to resolve the reference name into it's network address.
Running the install program
Prior to running the install program, we recommend you read the General Installation help information.
Once the QLR Manger files have been copied onto your application server, the install program can be run by invoking a URL that
references install.html. Install.html is found in the main directory of the directories you established when you loaded QLR Manager to
your application server.
• If you have not established the proper file access to the /reports directory, and you have chosen to store your pages as files, the
install program will issue a warning message.
• A warning message will also be generated if you have not established proper access to the qlr.ini file.
Even if you don't grant access to create/update the qlr.ini file, the information needed to populate this file will be displayed on the install
status page (see below) and you can manually copy and paste this data into the qlr.ini file.
There are only a few steps to the install process:
1 If this is the first time you are using the installer, you will be asked to accept the terms of the license agreement. If it is not the first
time using the installer (there is an option to Update Settings Only on the second page of the install program), you will be prompted
to enter the master QLR Manager User ID and password. Even though the install manager is password protected, it is
recommended that you rename install.html once you have finished the installation.
2 Next you will be asked to define the database engine with which QLR Manager will be working.
3 The first installer page gathers information about your operating system and an existing database ID to perform the install. When
the first page is displayed, it also verifies that the proper access exists for the qlr.ini file and /reports directory. If it does not, a
warning message will appear at the bottom of the first page.
4 The second installer page gathers information about the schema that will house the tables that drive QLR Manager. This page also
contains some advanced settings options.
5 The final installer page is a status page that will give you the results of your install or Settings Update, along with information to
manually update your qlr.ini file.
Existing ID to perform the install
In order to perform the installation, you must specify an ID that exists in your database which has sufficient authority to execute the
install. This ID needs the authority to be able to:
• Create a new schema.
• Grant create session, create table, create trigger, and create sequence to the QLR Manager ID that will be created during the install
process.
In order to connect to the database to perform the installation, you must also provide the password for the installation ID.
New or existing schema
You must decide on the schema where QLR Manager tables will reside. It is recommended that a separate schema be established for
the QLR Manager tables, but it is not mandatory to do so.
151
QLR Manager User’s Guide
Installation
Defining tablespaces for a new schema
When creating a new schema, the tablespaces for permanent and temporary data storage must be defined. You can either create new
tablespaces, or use existing tablespace.
Note: It is highly recommended you create a new Permanent tablespace for the schema that will house the QLR Manager tables.
This is especially true if you have decided to use the database to store the page content created by the QLR Manager, as peak load
usage may exceed tablespace limits for existing permanent tablespace configurations. This should not be a problem for your temporary
tablespace, so using an existing temporary tablespace should not present a problem.
The datapath displayed for where the tablespaces will reside on disk is determined by examining the datapath for your SYSTEM
tablespace. The filename created for newly created tablespaces is the datapath + the new schema name + '01.dbf'.
152
QLR Manager User’s Guide
Installation
PostgreSQL
PostgreSQL schema
When installing in the PostgreSQL environment, the installation is very similar to a MySQL installation. One difference is the availability
of schemas in PostgreSQL. The installation gives you the option of creating a schema (recommended) for the QLR Manager control
tables. If "No" is chosen, then the QLR Manager tables will be created in the "public" schema.
153
QLR Manager User’s Guide
Systems Admin
Systems Admin
QLR Systems Administration
The Systems Administration functions are only available in the Enterprise Edition of QLR Manager. They are accessible from the
Connect panel by selecting "User ID Admin and Tools" when logging on. The available functions include the creation of Input
Controls, Data Export of QLR data for transfer to another installed instance, Data Import from various file types such as CSV, and User
ID Administration. Access is initially limited to the User ID established during the install process, but using the User ID Admin panel,
other IDs can be granted the same authority. This topic also includes some information about re-branding or integrating QLR Manager
with your website and updating the Connect panel message.
User ID Administration
The Enterprise Edition of QLR Manager allows you to manage access for each of your users. Access can range from permitting full
authority to limiting a user to running reports from a single menu.
Controlling user authority to perform certain actions is accomplished in two ways. The default authority for all users is established by
retrieving the *default* User ID from the User ID Admin panel and making the appropriate selections. These values will become the
defaults for every user. The second level of control is to establish an entry for individual users by creating a User ID that is the same as
their database log on ID and make the desired selections. When QLR Manager finds a saved User ID, the selected authority values
saved for the ID will take precedence over the values set for the *default* User ID.
ID Status:
If you wish to prevent a specific ID from using QLR manager, you can "Lock" them out of the system. This is accomplished by setting
their ID Status to "Locked". Setting the *default* ID Status to Locked will prevent all users from using QLR Manager, except those that
have their User ID established and saved with a Status of "Active".
Access control:
The Access control setting determines which functions a user has authority to use. When checked, the User will have authority to view
the corresponding panel (Query, Layout, Define Macro, and Create Menu, etc.). If access is granted to the Query panel, the User will
automatically be given access to the Layout panel as well. The Select Menu selection will allow a user to select existing menus from
the Menu panel. If the Select Menu option is unchecked, a "Default menu owner" and "Default menu name" must be defined in order
for the User to have menu items to run.
If you wish to limit a user's capabilities, uncheck all the boxes and create a default menu. When this approach is used, QLR Manager is
transformed into a reporting interface for that user. All the User will be able to do is to run queries and macros that have already been
defined in their Default menu. See [qlr_userid] query variables for information about building dynamic queries based on the User's ID.
This may be useful for building a single menu that can be used as the default menu for multiple users.
Query execution restrictions:
The Query execution selections provide a means to restrict the type of queries a particular User ID can execute. This applies to queries
executed from the Query, Wizard, Macro and Menu panels. If "None" is selected by itself or with other options, there are no restrictions
on the type of queries the User ID can execute. Deselecting all options, including "None", will be treated as if "None" (no restrictions)
was selected. The most common restriction would be "Select", which would limit the User ID to executing only SELECT queries.
Save limits:
The Save limit defines how many of each object type can be saved. The values initially displayed are derived from the *default* User
ID settings, but can be overridden for a specific ID.
Note: If the "Query save limit" is set to 0, the User ID will not be able to create Input Controls. Any value greater than 0 for the Query
save limit will enable the User ID to create and save an unlimited number of Input Controls.
Query edit access:
The "Allow query edit" setting for the User ID determines whether the User can edit, execute and save retrieved queries. If unchecked,
the Query panel is effectively a read-only environment for that User ID.
Viewing shared objects:
The "View shared objects" setting allows you to hide shared objects from the User. If unchecked, the User will only be able to see
queries, layouts, macros and menus that are saved under their ID. Other user's shared objects will not be displayed.
Saving shared objects:
This setting allows the Administrator to control whether a user is allowed to share objects when they save them. If this is unchecked,
then the "Share" label and checkbox is omitted from the Save control.
154
QLR Manager User’s Guide
Systems Admin
Default menu owner and name:
The "Default menu owner" and "Default menu name" fields allow for the association of a specific menu with a User ID. This is the menu
that will be displayed when the User accesses the "Menu" (General User) or the "User Menu" (Restricted User) panels. If the User has
"Select Menu" authority, they will be able to choose a different menu from a list of menus shared by other users. If the User ID is being
established without Select Menu authority, the Default menu owner and name must be entered.
Defining a QLR Manager ID:
QLR Manager supports the creation of "QLR Manager IDs". You can create IDs that are known to QLR Manager (pseudo ID), but
actually connect to the underlying database using an ID that is defined in the database engine. For example, you can create pseudo
ID's for each of your customers, but the connection to the database is accomplished using a single common database ID. This can also
be useful in a shared hosting server environment where the hosting service provides a single connection ID, but you have more than
one person using QLR Manager. These IDs can be established by selecting "User ID Admin and Tools from the Connect panel,
clicking the User ID Admin header tab and expanding the Define QLR Manager ID section. Saving entries from this panel replaces
the function previously available using the qlrid.php file.
In order to have the User ID act as a QLR Manager ID, three values must be provided:
• The password for the new QLR Manager pseudo ID being created and saved.
• The existing database connection User ID with authority to your database(s).
• The password for the existing User ID through which the new ID will connect.
Note: If you change the password for the existing database connection ID in the database engine, all User IDs that use this connection
ID will be updated to use the new password. This will allow the QLR Manager pseudo IDs to maintain their access.
Creating input controls
Users with the authority to access the Edit Input Controls panel and the ability to save queries as established in their User ID profile,
will be able to create an unlimited number of input controls. For more information about all the available HTML form elements that can
be created to collect user input, please reference the separate topic about Input Controls.
Tracking query and macro usage
The use of queries and macros can be tracked by issuing the following query which will add an entry into the qlr_info table:
insert into qlr_info values ('track usage','yes')
This will instruct QLR Manager to add information into the table qlr_usage_log every time a user executes a stored query or macro,
including execution from a menu. Running a select query against the qlr_usage_log will provide information about the objects executed,
the connected User ID and the date/time of execution.
To turn off usage tracking, the following query can be executed:
delete from qlr_info where ref='track usage'
Exporting QLR data for use in another QLR Manager instance
The Data Export function allows QLR Queries, Layouts, Macros, Menus and User ID profiles to be selectively extracted for importing
into another installed instance of QLR Manager. A common use for this capability would be to create new queries and layouts in a test
environment and later export them for transfer into a production environment.
The Data Export facility provides a means to specify which type of objects to export (queries, layouts, etc.) and produce a file containing
a set of SQL statements. The contents of this file can be copied and pasted into the Query panel of another QLR Manager instance
and executed as a batch query simply by clicking the Run Query button. The "Ignore query variables" checkbox should be checked
so that any existing query variables are ignored when the batch query is executed.
SQL delete statements can be created to replace objects that may exist with the same owner and name by checking the "Create SQL
delete transactions" checkbox found in the Data Export panel.
Objects can be selectively extracted (except for User ID profiles) by using the SQL selection criteria area that is provided for both the
Owner like and Name like fields. For example, entering "nickd%" into the Owner like field would select all the selected object types
belonging to "nickd". To create a file containing all the saved queries and layouts beginning with "prod", Queries and Layouts could be
selected as the object types to export and "prod%" could be entered into the Name like field. The Data Export feature uses the SQL
LIKE syntax for data selection.
155
QLR Manager User’s Guide
Systems Admin
Integrating QLR Manager into a website or product
The recommended method of integrating QLR Manager into your website is to launch the application in a separate window. It is also
possible to nest the QLR Manager frameset (3 frames) into its own frame on your site. When using a frameset, it is important to name
the frame loading qlrmanager.html as QLR. This is necessary for the Javascript code to execute correctly. A typical frameset
configuration with QLR Manager nested in a frame may look like:
<frameset border="0" frameborder="0" framespacing="0" rows="50,*">
<frame src="top_frame.html" scrolling="no" />
<frameset border="0" frameborder="0" framespacing="0" cols="100,*">
<frame src="left_frame.html" scrolling="no" />
<frame src="./qlrmanager.html" name="QLR" scrolling="no" />
</frameset>
</frameset>
You may have an application where you wish to integrate QLR Manager into your website or bundle it with a product and provide a
more seamless look and feel. This can be accomplished by changing the colors and replacing images used in the QLR header files.
After purchasing a license or entering into an OEM marketing agreement with Tatler Software, we do permit this re-branding.
Depending on your application, you may have five header files to modify. These are all located in the qlr_manager directory. We do not
recommend that you modify the Javascript code in these files:
•
•
•
•
•
qlr_logon.html
qlr_admin.html
qlr_basic.html
qlr_classic.html
qlr_macro.html
Several other aspects of the QLR Manager color scheme can be changed by adding entries to the qlr_info table. Three different
settings can be modified. Here are examples of the commands that can be executed from the Query panel to update the color
scheme, assuming you are connected to the database where the QLR Manager tables reside:
• insert into qlr_info values ( 'background color','#0000FF');
• insert into qlr_info values ( 'section color','#CCCCFF');
• insert into qlr_info values ( 'section border','#DDDDFF');
Other associated images and colors can be identified by inspecting the HTML source.
156
QLR Manager User’s Guide
Systems Admin
Bypassing the Connect panel
QLR Manager provides a means of bypassing the Connect panel to log on. This can be very useful if you set up a common User ID
for your user community to execute items from a menu environment. In the top level QLR directory, there is a file called qlrgo.html that
can be launched instead of qlrmanager.html to create such access. The bottom frame of qlrgo.html references a file called
autolog.html, also found in the top level QLR directory. This file must be edited to include the following logon variables for your
particular application (highlighted in blue):
var User_ID = "guest2";
var Password = "guest2";
var DB_Server = "localhost";
The variables above are each required. In addition, if your logon requires a connection to a specific database, you can update the
following variable:
var Database = "my_database";
Note: When using this feature, you are exposing the User ID and Password in the source of the web page, so please consider the
security aspects of this approach.
If the specified User ID only has User Menu access as configured using User ID Admin, executing this html file will take the User
directly to the User Menu panel. If the User ID has Query panel access as well, then they will be taken to the Query panel. If you wish to
direct a user with both Menu and Query panel access to the Menu panel instead of the Query panel, a value of &umenu=umenu
should be declared for the User_Menu variable in autolog.html:
var User_Menu = "&umenu=umenu";
The files that facilitate this Connect panel bypass (qlrgo.html and autolog.html) can be copied and renamed to create as many
instances of this type access as needed. Be certain to synchronize the two files to achieve the expected result. For example, if you
create a second copy of autolog.html, such as autolog2.html, make sure you update the second copy of qlrgo.html to reference the
correct autolog file:
<frameset onunload="closeWin()" rows="68,26,*" border="0" frameborder="0" framespacing="0">
<frame src="./qlr_manager/qlr_logon.html" name="header" scrolling="no" />
<frame src="./qlr_manager/messages.html" NAME="message" scrolling="no" />
<frame src="./autolog2.html" name="QLRmanager" scrolling="auto" />
</frameset>
157
QLR Manager User’s Guide
Systems Admin
The Connect panel message
QLR Manager provides a means of displaying a message to your user community on the Connect panel. This is accomplished by
editing the file conmsg_xxx.html (where xxx represents the language code) that exists in the directory where QLR Manager was
installed, the same directory where qlrmanager.html is located. This file can be used to convey a simple message to your users, such
as "The Inventory database is down", or a more complex HTML formatted file with graphics. An example can be viewed at our Online
Demo page.
Following are two examples of different box style formats for conmsg_xxx.html:
Fieldset box style:
HTML source:
<!-- STARTS BOX BORDER AROUND HTML MESSAGE -->
<center><fieldset style="border:2px solid #033E66;padding:1px;width:100%">
<legend><font color="#033E66" style="font-size:10pt;
color:#033E66;font-family:Verdana,Arial,Helvetica,sans-serif"><b>
&nbsp;Welcome to QLR Manager&nbsp;</b></font></legend>
<!-- END START OF BOX -->
<table width="100%" border="0" cellpadding="4" cellspacing="0" bgcolor="#FFFFFF">
<tr><td>This is an optional <b>Connect</b> panel message that can be
edited to convey information to your users or customize this
installation of QLR Manager for any purpose. The contents of this message
exists in the file <u>conmsg_xxx.html</u>, which is located in the directory
where QLR Manager was installed. If you want to omit this message box,
you can delete or rename (recommended) conmsg_xxx.html.</td></tr></table>
<!-- CLOSES BOX BORDER AROUND HTML MESSAGE -->
</fieldset></center>
<!-- END CLOSE OF BOX -->
Plain box style:
HTML source:
<!-- STARTS BOX BORDER AROUND HTML MESSAGE -->
<center><table width="90%" border="0" cellpadding="2" cellspacing="0" bgcolor="#033E66">
<tr><td>
<!-- END START OF BOX -->
<table width="100%" border="0" cellpadding="4" cellspacing="0" bgcolor="#FFFFFF">
<tr><td>This is an optional <b>Connect</b> panel message that can be
edited to convey information to your users or customize this
installation of QLR Manager for any purpose. The contents of this message
exists in the file <u>conmsg_xxx.html</u>, which is located in the directory
where QLR Manager was installed. If you want to omit this message box,
you can delete or rename (recommended) conmsg_xxx.html.
</td></tr></table>
<!-- CLOSES BOX BORDER AROUND HTML MESSAGE -->
</td></tr></table></center>
<!-- END CLOSE OF BOX -->
158
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising