Introduction & Key Benefits

Visual CUT lets you schedule periodic and exception reports (Crystal, Excel, or SQL statements) for exporting, bursting, e‑mailing, and printing. E-mail messages, export file names and folders, number of copies, and many other options can incorporate dynamic content from fields/formulas in the report via a drag & drop user interface. The main benefits of Visual CUT include:

1. E-mail a dynamic-content message from reports/Excel/SQL data as a whole or for each Group. Include auto‑generated HTML tables of report/group data in the email message. A variety of options are supported including queued, archived, secured (NTLM, CRAM-MD5, SSL, STARTTLS), encrypted, and signed messages. Message bodies and options (subject, From, To, cc, bcc, priority, attachments) can incorporate dynamic content from fields/formulas in the report (via a drag & drop user interface) and can be formatted as HTML.

2. Export the report as a whole or Burst each Group Level-1 to a variety of file formats, save the results to dynamically named disk files/folders and include them as attachments to email messages.

3. Schedule exporting, bursting, emailing, and printing of reports based on parameters and options you specify (and save) during an interactive session.

4. Generate Auto-Refreshing Web Dashboards, Grids, and Pivot Tables from Crystal or Excel data.

5. Control and Invoke processing of Crystal reports, Excel workbooks, or SQL statements using command line arguments. A full command line interface allows calls from batch files, schedulers (including the free Windows Task Scheduler), desktop shortcuts, or any other program.

6. E-mail Alert Messages and Exception Reports by scheduling exception reports with an option that aborts processing when the report has zero selected records.

7. Special Capabilities include:

§ HTML exports (including charts & logos) can be embedded in email message bodies.

§ PDF exports can include Color-Coded Bookmarks & Table of Contents for easy online & hardcopy navigation.

§ PDF exports can be password protected (128-bit or 256-bit AES encryption) and/or restricted (for example, prevent editing).

§ PDF files can be split and emailed based on bookmarks or embedded text tags.

§ PDF files can be Merged (and bookmarks added) to create mixed page layouts, combine & staple output.

§ PDF files can be merged to create multiple Layers inside a single pdf file.
Within Acrobat reader, users can then turn the visibility of each layer on or off.
This is particularly useful for map layers. You can control the naming and initial visibility of each layer.

§ PDF files can be linearized (web-enabled) for faster opening from a web url.

§ Export/Burst to BMP, JPEG, WMF, EMF, EPS, PNG, TIF or GIF Image Files
(via an option to convert PDF files to image files).

§ Add web, email, or file links (hotspots) with optional text to PDF files.

§ Add an image with an optional hotspot to PDF files.

§ PDF Forms can be Filled (and optionally flattened) using Crystal formula values.

§ PDF Exports cangenerate Form Fields based on report formulas. This means that you can use Crystal Reports to design pdf forms, and Visual CUT to generate and distribute these forms.

§ PDF files with embedded files and drill-down links can be created.

§ Bursting to Excel can generate either a separate excel workbook file for each Group or multiple sheets (tabs) within a single workbook.

§ Excel exports can be inserted as tabs in a specified excel file to create briefing books.

§ Excel exports can display auto filter interface.

§ Excel exports can be password protected.

§ Excel pivot tables can be generated automatically.

§ Multi-tab excel exports (due to 65,536 row limitation) can be merged and converted into single-tab .xlsx files.

§ MS Word template documents can be mail-merged with Crystal/Excel data & tables and saved/emailed to dynamic destinations.

§ Text exports can be embedded in email message bodies.

§ Text exports or files can be merged into new or existing files.

§ Export to multiple file formats in a single pass.

§ Print to multiple printers in a single pass.

§ Print Burst so each Group Level-1 becomes a separate print job.

§ Split the printout of a pdf file to different printer trays.

§ FTP files to dynamically named web server folders using simple or secure connection.

§ Report Inspector allows mass-update of formulas, expressions, fonts, subreports, and Data Sources.

§ Zip and password protect files for secure single-file emailing of report exports.

§ ODBC Exports can replace or append to existing tables, This provides ETL (Extract, Transform, Load) and scheduled data snapshot functionality.

§ Capture incoming emails into a database and use them to trigger reports and database updates.

§ Inspect and Mass-Update reports.

Install / Remove

Selecting a Version: 8.5, 9, or 11 (XI R2)

In most cases, you should install Visual CUT 11. It can run all .rpt file versions, including 7, 8, 8.5, 9, 10, XI, 2008, 2011, 2013, 2016, and 2020.

Running a Crystal 2008-2020 report in Visual CUT 11 like running it in Crystal XI R2. New features degrade gracefully. You can support new features by delegating exporting/bursting to DataLink Viewer 2011.
A free DataLink Viewer license is available for that purpose.

Installation:
Make sure you install while being logged in as an Administrator on that PC.
1. Extract the .zip file to the local hard drive using the provided password.
It results in an msi file and a batch (VC11_Uninstall_Install_RClick_Run_As_Admin.cmd) file.
Don't run the msi file from within the zip file. Make sure the .msi file is placed on the LOCAL hard drive (not a CD or a mapped drive). Installation (.msi) files have self-repair and on-demand installation (for other users) functionality. Do not delete/move the msi file unless you removed the software.
2. Right-click the .cmd file and select Run as Administrator. It will take care of various aspects such as checking for and stopping/uninstalling previous versions.

urlmon.dll message
You can ignore and click OK to continue if the installer shows a message about not being able to update urlmon.dll.

Important steps After Installation
In post-XP Windows versions, the application folder (e.g., c:\Program Files (x86)\...) is write-protected by default. When Visual CUT gets loaded for the 1st time, it redirects the key files (Visual CUT.mdb, DataLink_Viewer.ini, ReportList.txt, ReportList.grd) to a MilletSoftware folder under \ProgramData or \AppData. The best way to navigate to this location is to click the Version Information button, and double-click the path information at the bottom of that window. Be sure to give other users modify permissions to that folder. Otherwise, Windows will automatically manage a dedicated version of these files for each user under a virtual store folder: users\user name\appdata\local\VirtualStore\Program Files... (this can lead to odd behaviors whereby saved settings are not available to other users or scheduled processing).
You can see an explanation of this at: http://www.west-wind.com/WebLog/posts/5584.aspx.

To allow administration of the smtpQ service, you may need to Right-click the Visual CUT.exe and set it (Properties, Compatibility tab) to Run as Administrator (set the option to apply to all users).

PDF Processing Errors
If you get one of these errors: Error 429: ActiveX component can't create object , iSED.exe registration error , 'error accessing ole registry' , 'Automation error The system cannot find the file specified' or 'Out of Memory'
Some pdf processing options require the use iSED.exe as a component, which must be registered while you are logged in as an Administrator.
Use Notepad to place the following command line in a batch (.bat) or command (.cmd) file:
"c:\Program Files\Visual CUT 11\ised.exe" -regserver
or, on a 64-bit machine:
"c:\Program Files (x86)\Visual CUT 11\ised.exe" -regserver
Right-click the batch file and select 'Run as administrator'

Avoid Installation on a Machine acting as a Crystal Reports Server (Crystal Reports Server, BOE, SBS, MAS90, SAGE 100):
Due to the risk of runtime component conflicts, you should avoid installing the software on a machine acting as a Crystal Reports Server.

Changing a Version (between 8.5, 9, or XI):
If you installed one version and then you decide to REMOVE it and install another version, be sure to first rename the old Visual CUT.mdb file, since it is not identical across all versions. To transfer settings from an old Visual CUT.mdb to the new one, follow these steps:

Open both Visual CUT.mdb files (old and new) in MS Access and copy all tables except for Export_Opt from the old to the new.
If you installed to a new folder, copy ReportList.txt, ReportList.grd and DataLink_Viewer.ini from the old folder to the new one.

Step 1: Select Report Tab

After starting Visual CUT, you would see the following screen:

Main Buttons

Use to browse for and open a report for the first time. Previously selected reports are listed in a grid and can be launched by double-clicking or by Right-Clicking and selecting ‘Preview Report’ from the popup menu.

Use to reload a report (if changed and saved in Crystal).

Use to set various options, which are maintained in DataLink_Viewer.ini

Use to open this User Manual form my web site. Shift-click attempts to open the local pdf version.

Use to access a dialog with Version (and system) information. That dialog also displays the paths to the folder where settings are maintained. Double-click that text area to open the folder in File Explorer.

Use to manage and monitor scheduled tasks.

Use to view the failure log. Color changes to red if new failures were logged since last used.

Use to exit Visual CUT.

The Report List Grid

Visual CUT can open and schedule processing for Crystal Reports, Excel workbooks, or SQL statements. The grid provides easy access and information about previously opened .rpt, .xlsx, or .sql files.

The grid information in maintained in a plain text file (ReportList.txt).
Copies of that file are periodically saved to the Recycle Bin in case you need to restore a previous version.

When opening a report for the first time, it gets added to the grid and Visual CUT populates the title and subject columns automatically if it finds that information in the summary information for the report.
You can set that information for the .rpt file in Crystal (under the file menu). Or you can manually enter that information into the grid.

To sort the grid, click the column headers.
To group the grid, drag column headers to the group area above.
To order the columns, drag the column headers to a different position.
To resize the grid columns, drag the borders between the column headers.

Right-Click Menu for Column Headers

As shown in an earlier image, right-clicking column headers provides a menu with options to change font size, hide/show the grouping area, and hide/show certain columns.

Right-Click Menu for Report Rows

When you right-click a report row in the grid, the popup menu shown above is displayed.

The Delete Row option deletes the report only from the grid but not from the hard drive (and not from the saved settings for the report in the Visual CUT.mdb file).

Copy .rpt and Settings allows you to clone the rpt and its saved settings to a new report or to an existing report.

Export .rpt and Settings à ZIP allows you to package an rpt and its saved processing options to a ZIP file that you can copy to another machine and place in a folder where you wish to extract the rpt file.
Using Visual CUT on that other machine you can then use Import.rpt and Settings à ZIP to import the rpt and its settings. This is useful when you need to replicate processing options for a report across multiple machines.

Generate HTML Tables instructs Visual CUT to auto-generate {@HTML_Table_All_Rows} and {@HTML_Table_Group} tokens for Inserting HTML Tables with Report/Group Data into Email Messages.

Launching a Report

You can launch a report using one of these methods:

1) Selecting that row and clicking the Preview Tab, or

2) Right-Clicking that row and selecting Preview, or

3) Double-clicking the row.

Note: the sample reports expect to find the Xtreme sample database and an ODBC DSN for connecting to that database on your PC. If you don’t have that database, simply elect to NOT refresh the data. That would load the report with saved data stored in the .rpt file.

Step 2: Preview

The Preview Tab is an integrated viewer that would prompt you for any report parameters and logon information required by the report.

Remember Parameter Values from a previous Session

Visual CUT remembers the parameter values used for the same report (and same path). Those values are automatically used during scheduled/unattended processing. For interactive processing, when you preview the same report again, this dialog allows you to reuse some or all of these values. You simply mark those parameters that you wish to change:

Save Date Parameter Values as Date Tokens

If you frequently run reports with data parameters that should typically be set to Today or Yesterday, add the following entry to the [Options] section of DataLink_Viewer.ini:
Save_Date_Parameters_As_Tokens=||Today||Yesterday||

Such date parameter values would then be saved and reused in scheduled/unattended processing as well as in interactive use, as Today or Yesterday date constants.

For example, here is a selective parameter refersh dialog with saved dates matched to Today and Yesterday:

Speeding Up Report Previews

If you are opening a report in Visual CUT, you may wish to cut the time it takes to preview the report so you can get to the business of changing some settings. This can be achieved by saving the report with data in Crystal. When you open a report with saved data in Visual CUT, you get the option to preview the report without refreshing the data.

Changing Processing Options without Previewing

All processing options are stored in Visual CUT.mdb. You can use MS Access to open that database and edit processing options in the Report_Opt and Report_Export_Options tables.

Changing Login, Report Paths & Other Settings without Previewing

Visual CUT stores login information (strongly encrypted) for each report in the Login_Opt table within Visual CUT database. Imagine your password to a data source used by 20 reports has changed. Instead of previewing each of these reports just so that the new logging information is captured, use the Options dialog, Process tab, to ‘Change Stored Login Information’ for all reports. Similarly, use the 'Find & Replace Report Paths and other Saved Settings' button to
update Report Paths (in the database as well as in the grid) or other saved settings.

Find & Replace Report Paths and other Saved Settings

This dialog allows you to search specific types of saved setting for string replacements.
For example, as shown below, if you turn on the 'Parameters' checkbox, only saved parameter values would be targeted for Search & Replace:

Disabling Find & Replace Categories

In some scenarios you may wish to block the user from some or all of the Find & Replace categories. To do so, you can set the following entry in the [Options] section of a Master_DataLink_Viewer.ini file in the application folder:

[Options]

// Use ALL some combination of: Report_Paths, Email_Addresses, Email_Information,
// Export_and_Email_Attach_Files, Saved_Arguments, and Parameters delimited by '||'.

// For example, the following entry would disable only 2 categories:

Disable_Find_and_Replace_Categories= Email_Addresses||Email_Information

Save and Reuse Named Parameter Sets

If you click the refresh button for a report that has at least 8 parameters (Options dialog allows you to change that number), a Save button becomes visible in the following dialog:

If you click Save, the following dialog allows you to save the current parameters value set to DataLink_Viewer.ini under a unique name for this report.

The next time you load this report, you would get a dialog that allows you select and reuse any of the saved named parameter sets for this report:

Double-clicking any of the entries (or selecting an entry and clicking the OK button) would launch a dialog allowing you to reuse that set of saved parameter values or selectively change some of these saved parameter values.

This functionality was designed to address scenarios where reports with many parameters are used in one of several parameter patterns. By saving and naming these patterns, the user can reuse them.

Note: if you are a report developer, you can deliver these saved parameter patterns to a user machine by copying the [Named_Parameter_Sets] section in your DataLink_Viewer.ini file to the user’s DataLink_Viewer.ini file.

Step 3: Export/Burst/Email…

The 3^rd tab of the application is where the real magic occurs. Let’s review how ea ch area on this screen is used.

Group Values Area

Visual CUT automatically detects Group Level 1 in the selected report and, if grouped on a Text or Numeric field/formula, populates this area with all group values. The name of the Group Level-1 field or formula is presented at the top of exporting options area, where the exporting burst option can be activated.

Note: the Group Values area is visible when 2 bursting conditions are met:

1) The report must be grouped at level 1 on a Text or Numeric field/formula and
2) That field/formula must be placed (can be suppressed) in the Group Header/Footer (can be suppressed).

Fields & Formulas Area

Visual CUT automatically detects & lists in this area all fields & formulas in Report or Group Level-1 Headers and Footers (even if the objects/sections are suppressed).
Hovering your mouse over a field provides a tooltip reflecting the dynamic value associated with that field for:
a) the whole report (if in a report-level section), or
b) the selected group in the Group Values area (if in a Group1 section)
For example, hovering over the {@Subject} formula produced the tooltip shown in the image above.

You can double-click to insert (or drag & drop) these fields & formulas into the processing options area to specify options that change values based on report/group data.

Also listed in that area are main report parameters that are in use. For example, {?01?Year} is the {?Year} parameter. The 01 indicates the position of the parameter in the list of parameters. That position is important in constructing parameter arguments such as "Parm1:2015". The dynamic string values provided for parameter fields are converted to text from the data type of the parameter (Boolean, date, datetime, time, number, currency, or string). Multi-value parameters are returned as comma separated values. Range parameters are returned as [from-to] strings. If you need more control over the values returned from parameters, create a formula that returns the parameter value in the desired format (typically using the ToText() function), and place the formula (suppressed) in the report header or footer.

Since adding current day, month, and year values to options such as export file names and email subject are common needs, Visual CUT includes in the Fields & Formulas area a list of current date values (day, month, year) with various variations (number, name, length). This allows you to avoid creating formulas in your report just to pass current date values to Visual CUT. Similarly, this area also lists the following tokens:

{%UserName%} – provides the Windows User ID
{[ODBC_DSN:]} – provides the ODBC DSN used to override the default DSN for the report.
{[User_ID:]} – provides the user id used for login (blank otherwise).

Notes:

· Text objects containing fields/formulas are not included in this process.

· Even if the field/formula or its report section is suppressed the field/formula is recognized.

· Report Header/Footer subsections a,b,c,d,and e participate in field/formula detection.

· Group Header/Footer Level-1 subsections a & b (GH1a, GH1b, GF1a, GF1b) participate.

Exporting/Bursting Options

This area allows you to specify the Exporting format (all file export formats are available) and whether you wish to export the whole report or burst each Group Level-1 into its own file.

When bursting, you should typically specify a dynamic Export File Name option by dragging fields/formulas from the report into the export file name. If you hover your cursor over any option, a tooltip displays the dynamic value corresponding to the group currently selected in the Group Values area.
The button provides export options for some export formats.
The button provides a grid preview of the export files to be generated by bursting.

Note: when exporting, if the target file exists, it is first deleted and moved to the Recycle Bin.
To avoid invalidating hyperlinks to cloud drives (e.g. OneDrive) you can turn off this behavior by going to the Options dialog, Process tab, and turn off the ‘Save Overwritten Exported Files in Recycle Bin’ option.

Exporting to Multiple Files/Formats in a Single Pass

Imagine that you need to export and email a report in two or more file formats. Visual CUT allows you to do this in a single pass. You can specify multiple export file names (separated by a semi-colon) and Visual CUT will export to all of them without retrieving the report multiple times. For example: c:\temp\test.xlsx;c:\temp\test.pdf

The multiple export file names can either be entered into the export file name option or specified in the "Export_File" command line argument.

Visual CUT automatically uses the appropriate export format for files with different extensions (.pdf, .xls, .doc, .htm, .txt, .csv, or .rpt) than the extension of the first file name.

The first export file extension should match the export format selected for the report. Since some export formats, such as .xls and .txt, have extra options, it makes sense to select that export format as the first file to be exported (allowing saved settings to control the extra options). Export formats that have no variations (such as .pdf and .rpt) should be specified as the extra export files.

Note: this applies even to bursting, so each bursting cycle can generate multiple exports.

Skipping Exporting (VC_Skip_Export)

You may wish to skip exporting of the report in some cases such as using a dummy report as an excuse to apply special processing for an existing file. Or perhaps you have a scheduled process where even with zero records
(-E vs –e) you still want to email but avoid exporting.

For the first case, where you always want to skip exporting, you can simply set the export file to VC_Skip_Export (note there's no path).

For the 2^nd case, you can use a Crystal formula to control exporting. For example
IF IsNull({Order.Order_ID}) THEN "VC_Skip_Export" ELSE "C:\Temp\" & {Order.Order_ID} & ".pdf"

Place that formula in the Report Header (so Visual CUT can recognize it) and suppress it.
In Visual CUT, you can then place that formula as the dynamic value of the Export File.

If the report sees zero records, the formula would return VC_Skip_Export, and the export would be skipped.

Note: to skip emailing, there's a similar constant (VC_Skip_Email). That can be used as the static or dynamic value of the Email_To option.

Replacing Illegal Characters in Dynamic File Names

Starting November 2011, you no longer need to worry about illegal and non-printing characters in file names unless:

a) your export file names contain the illegal characters ‘*’ or ‘?’ (those characters are not replaced because they may be used in wild card selection of email attachments)

b) you wish to apply your own logic for character substitution

Visual CUT takes care of replacing illegal characters in export file names, email file attachments, and .eml files (.eml files are used in email queuing). Visual CUT also removes non-printing characters from these options. The logic of illegal character substitutions is shown in the sample formula below. When hovering your mouse over the export file name or email attachment option, the tooltip shows the corrected dynamic value.

If you need to override the automated handling and control what legal characters substitute for what illegal characters, you can use a Crystal formula like the one shown below. Remember to place that formula in the RH/RF or GH1/GF1 section of the report so that it becomes available for drag & drop within Visual CUT.

// illegal Characters for windows file names include: ?/\|<>:"*

// Note: change InputFileName to your file name field or formula

Local StringVar InputFileName := "Test?/\|<>:""*" ;

Local StringVar OutputFileName ;

OutputFileName := Replace(InputFileName, "?", "_");

OutputFileName := Replace(OutputFileName, "/", "_");

OutputFileName := Replace(OutputFileName, "\", "_");

OutputFileName := Replace(OutputFileName, "|", "_");

OutputFileName := Replace(OutputFileName, "<", "{");

OutputFileName := Replace(OutputFileName, ">", "}");

OutputFileName := Replace(OutputFileName, ":", "_");

OutputFileName := Replace(OutputFileName, """", "'");

OutputFileName := Replace(OutputFileName, "*", "x");

// If destination is web server, replace spaces with "_"

//OutputFileName := Replace(OutputFileName, " ", "_");

Incrementing Export File Name Counter

Dragging the {[v]} token from the list of Fields/Formulas into the Export File Name adds a file version counter to the file name, ensuring the export file is new and doesn't overwrite previous versions. Note that in most cases this should not be needed because you can make the file name dynamic using Crystal fields/formulas or using date/time-stamp tokens.

Default Behavior

If the file doesn't exist, the {[v]} token is replaced with a blank text ("").
If the file exists, the {[v]} token is replaced by the first entry in the sequence of _1, _2, _3 …
that results in a new file. For example, if C:\Export.pdf and C:\Export_1.pdf already exist, then
an Export File set to C:\Export{[v]}.pdf would result in C:\Export_2.pdf being exported.

Customized Behavior

If you add an entry such as this:
{[v]}_Format=N(8)
to the [Options] section of DataLink_Viewer.ini, the {[v]} token always gets replaced with the first counter value that doesn't exists in a zero padded sequence starting with 00000001 where the number of digits is controlled by the number inside the parentheses.
In the example above 8 causes the number to have 8 digits.

Printing Options

Bursting to Printer

You may want to burst a report directly to a printer. For example, you may want each group to become a separate print job so it gets stapled.

There are 3 options for achieving this.

Method 1

Use Printer_Burst or Printer_Burst_Only command line arguments. For detail, see:
Using Command Line Arguments to Specify Printer Bursting Destination

Method 2

Burst to PDF files and use PDF_Print command line arguments to print them. For detail, see:
Printing PDF Files

Method 3

Export to Printer (Default) or Printer (Specified) as the export format.
This allows print bursting to be initiated/stopped interactively. If the Rename_Printer_Jobs option in the DataLink_Viewer.ini file is set to True, the printer queue shows the group value for each burst cycle print job.

When using Printer (Specified) as the export format, the export file name option controls the name of the printer. Since this option can be dynamic (contain field/formula reference), this means that each group can be printed to a different printer.

Users who don’t see these export format options in the drop-down should add two new rows to the Export_Opt table in the Visual CUT.mdb Access database:

Export Constant	Export Name
Printer_Default	Printer (Default)
Printer_Specified	Printer (Specified)

Setting Custom Text for each Print Copy

When printing directly to a printer (not via PDF_Print), each print copy can have custom text. Simply place a formula called {@Print_Copy_Template} on the report canvas. For each printed copy, Visual CUT updates the text in that formula by replacing [[N]] with the copy number and [[M]] with the total number of copies.
For example, "Copy [[N]] of [[M]]" would become 'Copy 1 of 2', 'Copy 2 of 2’ like this:

Visual CUT would also:
a) Replace references to fields/formulas with their dynamic values. Example: "Copy [[N]] of {@G1_Count}"
b) Replace [[{StartCount}+N]] with the dynamic value of a {@StartCount} formula + copy number.
Note: the token does not include the @ symbol in the formula name.

To dynamically control number of copies use "Print_Copies" argument like "Print_Copies:{@ Quantity}" or place field/formula in the Copies option as shown below:

Interweaving Burst Printouts From Multiple Reports

Imagine that you need to burst a report such that each group results in a check printed on special paper using Landscape orientation followed by supporting documentation using Portrait orientation on another type of paper. Or perhaps you need to burst 3 different reports (sales, commissions, and product returns) to sales representatives and you want the output to be sorted by report output within Sales Rep (rather than by Sales Rep within report output).

The After_Burst_Batch command line argument allows you to insert batch file operations after each successful export burst step (and waiting for that batch file to complete processing).

You can embed within the command lines inside the batch file field/formula names just as you can within the Visual CUT 3^rd tab options. Visual CUT substitutes the appropriate values (those associated with the current processing cycle) for these field/formula names before launching the batch file processing. This allows synchronized interweaving of group bursting printouts from multiple reports without the limitations of subreports (subreports don’t support different paper trays, different paper orientations, and nested subreports).

For example, using the following scheduling string (or batch file):
------------------------------------------------------------------------------------------------------------

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Printer_Burst_Only:\\PS\Laser1"
"After_Burst_Batch:C:\VC_Prod_Type.bat>>Show>>Wait"

------------------------------------------------------------------------------------------------------------

would cause Visual CUT to:

1. Start processing the Visual CUT.rpt and burst the first group value ("Competition")

2. Before bursting the next group value ("Mountain"), Visual CUT looks into the VC_Prod_Type.bat file to see if recognized fields/formula names should be temporarily replaced with dynamic values.
Parm1:{Product_Type.Product Type Name} is then replaced with Parm1:Competition

3. The dynamic/temporary copy of the batch file is then triggered for processing, causing a secondary instance of Visual CUT to process the After-Bursting request.

4. Visual CUT then resumes the cycle with the next group value ("Mountain")

NOTE: in cases where paper tray choices within the reports don't seem to be honored during the processing, I recommend you add the same Printer to your Windows setup a 2^nd time with a different name and a different paper tray as the default. Then set each report to use the printer "clone" that has the desired tray as the default.

Note that in the example above 2 optional arguments are specified: (>>Show>>Wait).
You can hide the batch file window by setting the 1^st optional argument to Hide instead of Show. You can tell Visual CUT to not wait for the batch file to finish by setting the
2^nd optional argument to NoWait instead of Wait.

Printer Job Name Functionality

When printing reports, Visual CUT names the print job according to the export file name option (even when only printing, and no exporting, takes place). Since the export file name can be a mixture of static text and field/formula values, this allows you to have a very fine control over the printer job names showing up in the printer job queue. For example, during print bursting, you can have each group printed under a different job name, allowing you to abort printouts for certain groups.

In cases where you don't have permissions to rename jobs in the printer queue, you should disable this functionality by setting the following option in the DataLink Viewer.ini to False:
[Options]
Rename_Printer_Jobs=FALSE

Email Options

If you wish to generate a single Email from the selected report, turn on the "Single Email" option. To generate an Email message for each Group Level-1, either in conjunction with export bursting or as simple email bursting, turn on the "Email for Each Group Level 1" option.
The button provides a grid preview of email bursting.

Combining Static & Dynamic Content

In all options, you can combine static text and dynamic values you drag from the fields/formulas area on the right. Moving the cursor over any of these options results in a tooltip display combining the static text with the dynamic content of the fields/formulas (based on the selected Group Value).

For example, in the example shown above, the email subject line resolved the text:
{@Year_Parameter} Sales for {Product_Type.Product Type Name}

into the dynamic content of:
2004 Sales for Competition
This allows you to see what dynamic content you are building into your processing options.

Specifying SMTP Server

While you may specify the SMTP Server in the Export/Email tab settings for an individual report, you should do so ONLY when you need to override the default smtp server setting.

The defaults SMTP Server is specified in the global Options dialog:

Sending Emails via Office365

You can use simple SMTP AUTH (user id and password) or OAUTH (Client Credentials Flow) when emailing via Office365.

SMTP AUTH Option (simple)

1. Open the Microsoft 365 admin center and go to Users > Active users.

2. Select the user, and in the dialog that appears, click Mail.

3. In the Email apps section, click Manage email apps.

4. Set Authenticated SMTP as checked.

5. Save changes.

In the Visual CUT Options dialog (Email tab), simply set the Email User ID and Password.

OAuth Option (complex)

Please contact Millet Software for detailed instructions.

Sending Emails via Gmail

To email via Gmail when 2-factor authentication is enabled, the simplest option is to
create a Gmail Application-Specific Password:

1. In https://myaccount.google.com/ select Security.

2. Click App password

3. Select Mail as app and Windows Computer as device.

4. Generate and copy the password.
5. Set it as the email password (Visual CUT Options dialog, Email tab).

If email from Visual CUT still fails, visit the Display Unlock Captcha page and
click 'Continue' to remove the security block.

Embedding Special Content

Embedding Report as Image in Email (old approach)

Imagine you need to embed an image of the report's 1^st page inside the email message body. The email recipient would see the report without needing to open an attachment. First, export the report to pdf and use PDF_Save_As to convert to an image. For example, bursting to: c:\temp\Sales for {Product_Type.Product Type Name} in {@Year_Parameter}.pdf
the argument would be:
"PDF_Save_As:c:\temp\Sales for {Product_Type.Product Type Name} in {@Year_Parameter}.pdf> c:\temp\Sales for {Product_Type.Product Type Name} in {@Year_Parameter}.png>PNG>96"
Each page is saved with page number added at the end, so the 1^st page from Sales for Competition in 2004.pdf would create a png file called: Sales for Competition in 20041.png

Then, embed a reference to the png image file inside the HTML message body. For example:
…<BODY>

Hi Ido, <br><br>

Here is your Sales Report for {Product_Type.Product Type Name} in {@Year_Parameter}: <br>

</BODY></HTML>

Embedding Report as Image(s) in Email (new approach)

An Image export format converts report pages to images. You place an {[HTML_IMG_Src]} token in the HTML email message, and Visual CUT replaces it with the HTML img source directives for all the image files generated (one image per page). See video demo.

For example, for a report resulting in 3 pages, this HTML email message raw text:

…<BODY>Here is your Sales Report for {@Year_Parameter}: <br>

{[HTML_IMG_Src]}

</BODY></HTML>

may result in dynamic value substitutions that look like this:

…<BODY>Here is your Sales Report for 2020: <br>

</BODY></HTML>

And the email will show all pages of the report as images within the email message (sample):

Depending on Border, Crop, Pad, and Separator options you set in the Image_Export_Options ini entry or a command line argument, Visual CUT crops, pads, borders, and separates the image source directives to improve the layout. The options dialog for the Image export format makes it easy to adjust these options and insert the resulting directive into the Argument area.

The sample image above shows an email with page images that were cropped, padded (3 pixels), and bordered. The <br><br> provided vertical separation between the images.

Notes:

2. Supported image file extensions are png, bmp, jpg, and jpeg.

3. To add the Image export format to existing Visual CUT installation, you need to add Image to the list of export formats in the Export_Opt table in the Visual CUT database:

Export Constant	Export Name
Image	Image

- Click Version Info button, and double-click text area at bottom to open the folder where the Visual CUT database is located.

- Close Visual CUT and open the Visual CUT database in MS Access

- Open Export_Opt table and add the row shown above.

Embedding Pivot Tables in Email Message Body

To embed a Pivot Table inside the email message body, follow these steps:

a) Use XLS_Save_As to target the pivot table for conversion to HTML. For example, using the sample Pivot_Data.rpt, the following XLS_Pivot_Table and XLS_Save_As arguments would generate the After_Pivot.xlsx workbook with a tab called Revenue Pivot Table and a pivot table with the same name. The XLS_Save_As argument would then save the pivot table into an html file (c:\temp\Revenue_PivotTable.htm).

b) Embed a reference to the html file inside the HTML message body. For example:
<BODY>The attached Excel Workbook contains the <STRONG>Revenue</STRONG> and <STRONG>% Late</STRONG> <STRONG><FONT color=#ff0000>pivot table</FONT></STRONG>.

Or, here is the Pivot Table as HTML: [[Insert_File:c:\temp\Revenue_PivotTable.htm]] </BODY></HTML>

Embedding HTML Export in Email Message Body

Imagine you need to export a report to HTML but you wish to embed the resulting content (including charts and images) inside the email message body. To do this you need to observe the following simple rules:

b) The email message body must be left completely blank.

c) The first attached file name must be the html file to embed as the HTML email message (typically, it’s the report export to HTML). That file name must end with .htm or .html

d) Use HTML 40 as the export format

Limitations:

· email clients typically corrupt the formatting of complex HTML messages when users attempt to Reply to or Forward the email message.

· Outlook 2007 is very limited in rendering HTML content. Use an older version of Outlook if you need HTML embedding in email messages or instruct Outlook 2007 users to open HTML emails in a full window (double click), and then click the "Other actions" toolbar button and choose "View in browser."

To avoid these limitations, a different method of sending report content as HTML is described in the following sections:
Sending Message Text as HTML
Embedding Images inside the HTML email body
Dynamic Tables inside HTML Email Messages
Using Cascading Style Sheets (CSS) in HTML messages

Embedding TEXT Export in Email Message Body

Imagine you need to export a report to Text but you wish to embed the resulting content inside the email message body. To do this you need to observe the following simple rules:

The email message body must be left completely blank.
The text file (probably the file exported by Visual CUT, but it can be any other file as well) to embed in the message body must be either the only specified attachment or the first file in the attachment list (reminder: multiple file attachments are separated by a ";" without spaces).
The text file name must end with .txt, .prn, or .text

Embedding File(s) Content in Email Message Body

Imagine you need to insert a standard header and footer into the email message body, or you wish to give the user an easy way to modify the content of a specific paragraph by editing a text file, or you are specifying the email body via a command line and wish to refer to the body content via a file rather than by including the full content in the command line itself. To do any of the above, you can embed within the message a references to a file using the following structure: <<Insert_File:File_Path_and_Name>>
For example, <<Insert_File:c:\temp\MyFile.htm>>

For HTML email messages, you should use [[Insert_File: … ]]
When Visual CUT encounters such a "file token" it replaces it with the content of the specified file (if such a file exists).
References to report fields/formulas are replaced with their dynamic content.
You can use as many file tokens as you wish within a single message body.
You can use a Crystal formula that results in such a token and embed the reference to that formula in the message body. Visual CUT would first resolve the formula reference into the token and then replace the token with the file content. A typical use for this would be to embed a different paragraph in an email message depending on the number of days an account is overdue.
If an inserted file has embedded file tokens, they would be replaced as well
(the process is recursive).

Embedding Images inside the HTML email body (old email engine – no longer available)

In order to include an image as an embedded file, the HTML syntax of your message would include something like:
<p><font color="#000080"><img border="0" src="file:///C:/Program%20Files/Visual%20CUT/logo.gif"
width="211" height="69"></font></p>

You would need to attach that file to the email message.
The attachment would be specified as something like
C:\Program Files\Visual CUT\logo.gif
(separated from other attachment by ";")

You don't need to attach the image if it is a reference to an image available on the web.

Embedding Images inside the HTML email body (new email engine)

If you are using the GUI HTML editor for the email message body, just insert an image and Visual CUT would take care of embedding it in the email message.

If you are manually creating the reference to the image, use the following structure:
<IMG src="file:///image_file_path_and_name">

For example, <IMG src="file:///C:/Pictures/My_Logo.jpg">

The path and name of the image file must point to an existing file. Of course, it may include a dynamic reference to a Crystal field or formula. For example:
<IMG src="file:///C:/Pictures/{Product_Type.Picture_Path}.jpg">

You should not specify the image file as an attachment.

Custom Email Headers

See details in Argument to Specify Email Headers.

Email Priority

See details in Argument to Specify Email Priority.

Including Emoji in Email Subject

Including an emoji (e.g. ✔) in the email subject line can improve response rates and recognition of your emails.
You can dynamically set the subject emoji using a formula that returns one of several paths to a text file containing the emoji of choice. See video demo. For detail, see Argument to Specify Email Subject Emoji.

Sending Message Text as HTML

Visual CUT ensures that e-mail messages that starts with <HTML> and ends with </HTML> are sent as HTML messages.

You can use the integrated HTML editor to create the message and drag and drop dynamic content into appropriate locations within the resulting HTML text.

<html>

<br>

Here's your <big><font color="#990000"><b>annual sales report</b></font></big>

for <big><b><i><font color="#3333ff">{Product_Type.Product Type Name}</font></i></b></big>

products.<br>

<br>

Please Contact Ido Millet (814 898-6262) if you have any questions.<br>

<br>

Regards,<br>

- TCW (The Crystal Wizard)

</html>

The message body above resulted in the following e-mail message body:

Using Cascading Style Sheets (CSS) in HTML messages

Just like any other HTML document, you can use CSS directives by embedding them in the header section of the HTML document.

For example, assume you are embedding dynamic HTML tables inside the email message (see previous section for a detailed description of that technique. You may wish to control the font type and font size of table element (identified as td in HTML).

Here is an example of using CSS to achieve this:

<html>

<head>

<title>Reseller Balance Report for (@Product_Param}</title>

<style type='text/css'>

td{font-family:Verdana; font-size:8pt;}

</style>

</head>

<body>

<font face="Verdana, Arial, Helvetica, sans-serif" size="2">
Hi {Reseller.First_Name},<br><br>

This message shows your <b>{@Product_Param} </b>purchases, transfers,

and balance as of {@Nice_Date}. <br> <br>

<hr width="100%" size="2">
<b><big>Your Purchases:</big></b><br><br>

{@HTML_Table_Sub}<br><br>

<hr width="100%" size="2">
<b><big>License Transfers and Balance:</big></b><br><br>

{@HTML_Table_3_GF1}<br><br>

</font>

</body>

</html>

Integrated HTML Editor

Just to the left of the email message body, you can click on button to start an integrated HTML editor. If the message is not already in HTML syntax, clicking the button will add the necessary HTML syntax including a few useful cascading style sheet options (defaulting the message body text as well as any Table text to Verdana).

The editor allows you to change formatting, insert tables, images and links, check spelling, and edit the text, all from an intuitive word processing interface. It also allows you to preview the resulting email messages with dynamic values substituted for Crystal field/formula references.

Email Merge using Report Fields/Formulas

You can double-click or drag & drop dynamic fields to embed them in the email message:

Integrated Spell Checker

Starting in 2021 a new html editor provides inline spell-checking, similar to the experience you get when editing documents in MS Word.

Copy & Paste from Other Software

In most cases, you can copy and paste content into the HTML editor, while preserving formatting, from other software such as Microsoft Word or Excel.

CSS considerations

When Visual CUT starts a new html message in the html editor, it injects default css directives into a <Style> subsection within the <HEAD> area of the html. You can delete, modify or add directives to the default css.

<HEAD>

<title>Your Order has Shipped</title>

body{font-family: Verdana, Geneva, sans-serif; font-size:10pt;}

th, td{font-family: Verdana, Geneva, sans-serif;font-size:10pt; border:#585858 1px solid; min-height: 1em}}

table{border-collapse: collapse; border:#585858 1px solid;}

p{margin-top: 10px; margin-bottom: 10px;}

ol,ul{margin-top: -10px; margin-bottom: -10px;}

</style>

</HEAD>

Note: some email clients do not fully support css declarations in the <Head> area.
For example, Gmail styles tables properly only if you use Inline CSS rather than Header CSS.
To get around this limitation, you can use the inline-styled HTML tables auto-generated by Visual CUT (see video demo) or use Crystal formulas to generate an inline-styled HTML tables (see video demo).

Here is an image demonstrating this approach, which reduces the effort involved in setting colors, borders, and styling options:

Enter Key Behavior

Starting 2022, the editor handles Enter as a new line (<br>) and Shift-Enter as a new paragraph (<p>).

If you wish to reverse those assignments, please locate the Email_Enter_Key_as_Paragraph ini option and set it to True instead of False.

The title of the editor window shows the behavior assigned to Enter and Shift-Enter.

Auto-Generated HTML Tables for Report/Group Data

See Video demonstration

Visual CUT can auto-generate HTML tables for the report data and for each group level 1 data.

Right-Click the report row in the grid and turn on the option to Generate HTML Tables.

This causes the tokens highlighted in the image below to be generated and populated with Report/Group data:

Switching to Preview mode confirm the token is indeed replaced by the HTML table for the current group:

Excluding Columns

The column names in the HTML table are generated based on the column headers in the report's Page Header section. You can exclude columns from the HTML table by starting their column header name with a space. For example, in the sample report the Country and Web Site columns were excluded by setting the column headers to ' Country' and ' Web Site':

Parsing Requirements

The HTML tables are populated by Visual CUT by automatically generating an Excel (Data Only) export and "cleaning" it to remove blank columns, Blank Rows, and Non-Detail Rows. For a Grouped report, this requires that you avoid placing data directly above or below (GH1/GF1) the grouped-on column.
However, to support typical subtotal scenarios, you may place numeric content (e.g. group totals) above/below a string grouped-on column as demonstrated in the image below:

If you want to generate HTML tables for each group at level 1, the Group field/formula cannot have spaces within its name. Use underscores instead.

Column headers cannot repeat. If your report spans multiple pages, place column headers in the
Report Header rather than the Page Header.

Notes:

· The {@HTML_Table_Group} token is generated only if
a) the report is grouped, and
b) the column the report is grouped on is in the report details section and its column header matches the name of the column (if you need a better looking name, use a formula instead of the raw column)

· If you need more control over the content of the HTML table (e.g. conditional formatting, HTML table from a subreport, or hierarchical HTML tables) you can use the technique described in the following section.

· If you need column data to act as a hyperlink, use a formula that returns the full syntax of an anchor tag. For example:
"<a href=""" + {@URL} + """>" + {@Label} + "</a>"

Dynamic Tables inside HTML Email Messages

See Video demonstration.

HTML tables are very useful, particularly when sending email messages to mobile devices. Because the width of an HTML table and its columns can be specified as percentages of the available screen width, the information would adapt itself to the device displaying the message.

It is very easy to create static HTML tables (use the integrated HTML editor). However, this section describes a powerful technique for using Crystal formulas to create dynamic HTML tables (with information from your Crystal report). You can then embed the formula containing the full table syntax in the email message body.

The general idea is to use:
1) one formula (in a Report or Group header section) to set the value of a string variable to the
table header syntax (<Table>….
2) P another formula (in a Detail or Group section) would repeatedly append table rows

3) a final formula (in a Report or Group Footer section) would provide the table footer and close
the table syntax (using …</Table>)

The Visual CUT 11.rpt sample report demonstrates this technique (and email bursting) using:
HTML_Table_1_GH1 (formula placed in GH1):

// In order to capture multi-section detail into an HTML table string

// (called HTML_Table), this report uses 3 Formulas:

// HTML_Table_1_GH1 sets the variable to the Table Header info

// HTML_Table_2_GF2 appends a row of data (for each Group Footer level 2)

// HTML_Table_3_GF1 Closes the Table

// Place this formula in GH1 to set formatting, column names, widths, etc.

WhilePrintingRecords;

Stringvar HTML_Table;
// Reset the string variable only if this is not a repeated group header

IF NOT InRepeatedGroupHeader THEN

HTML_Table := "<table width=""100%"" border=""1"" cellpadding=""5"" cellspacing=""0"" bordercolor=""#0033CC"">" +

"<tr bgcolor=""#66CCFF"">" +

"<td width=""60%"" align=""left""><strong><big>Product</big></strong></td>" +

"<td width=""20%"" align=""right""><strong><big>Revenue</big></strong></td>" +

"<td width=""20%"" align=""center""><strong><big>Days<br>To Ship</big></strong></td>" +

"</tr>"

HTML_Table_2_GF2 (placed in GF2):

// Place this formula in GF2 to append Table Row Information

WhilePrintingRecords;

Stringvar HTML_Table;

HTML_Table := HTML_Table +

"<tr>" +

// Here we add the Product Name column

// (note that where we need to have " we must specify "")

"<td><div align=""left"">" +

{Product.Product Name} +

"</div></td>" +

// Here we add the total Revenue column:

"<td><div align=""right"">" +

"<b>$" + ToText(Sum ({@value}, {Product.Product Name}),0) + "</b>" +

"</div></td>" +

// Here we add the Average Days to Ship:

"<td><div align=""center"">" +

(

IF Average ({@Days_To_Ship}, {Product.Product Name}) > 5 THEN

// Slow shipping, so format as Red

"<b style=""color: rgb(255, 0, 0);"">" +

ToText(Average ({@Days_To_Ship}, {Product.Product Name}),1) +

"</b>"

ELSE IF Average ({@Days_To_Ship}, {Product.Product Name}) < 3 THEN

// Fast shipping, so format as Green

"<b style=""color: rgb(4, 180, 4);"">" +

ToText(Average ({@Days_To_Ship}, {Product.Product Name}),1) +

"</b>"

ELSE

// Intermediate level of performance. Format as Blue

"<b style=""color: rgb(0, 0, 255);"">" +

ToText(Average ({@Days_To_Ship}, {Product.Product Name}),1) +

"</b>"

) +

"</div></td>" +

"</tr>"

HTML_Table_3_GF1 (used in Visual CUT to embed the HTML Table in email body):

// Place this formula in GF1 to "close" the HTML Table

WhilePrintingRecords;

Stringvar HTML_Table;

HTML_Table := HTML_Table + "</table>"

In Visual CUT, the report is set to burst and the {@HTML_Table_3_GF1} formula (because it was placed in a GF1 section) is available for drag & drop into an email message body:

<HTML>

Here is {@Year_Parameter} sales data for {Product_Type.Product Type Name}:<br><br>

{@HTML_Table_3_GF1}<br><br>

Cheers,<br>

- Ido
</HTML>

The resulting email message provides the dynamic content with an embedded HTML table:

Applying Alternating Row Color

To create an alternating background color effect to the HTML table rows, use the bgcolor attribute of the tr (table row) html tag. [Note: see Default CSS with Table Formatting for an easier approach!]

For example, the following HTML email message used the same approach described in the previous section, except that instead of a static "<tr>" to start each data row (GH2 formula), a string variable called ls_alternating_color_TR is used to alternate between "<tr>" (no color) and "<tr bgcolor=""#E0FFFF"">" (a light blue background color):

WhilePrintingRecords;

Stringvar HTML_Table;

// instaed of using "<tr>" to start each row, alternate row colors between "<tr>" and "<tr bgcolor=""#E0FFFF"">"

Stringvar ls_alternating_color_TR;

IF ls_alternating_color_TR = "<tr>" THEN

ls_alternating_color_TR := "<tr bgcolor=""#E0FFFF"">"

ELSE

ls_alternating_color_TR := "<tr>" ;

HTML_Table := HTML_Table +

Chr(10) + ls_alternating_color_TR + …

Embedding Hyperlinks to Reports/Files inside HTML Email Messages

Instead of attaching reports to email messages, you can use the email message to provide hyperlinks to the report files located on shared or web folders.

Visual CUT would export the reports directly to shared folders or upload them to web folders using FTP_Upload or SFTP_Upload arguments. Then, instead of attaching the files to the outgoing email message, you can use Visual CUT’s HTML email message editor to embed a hyperlink to the report file. The hyperlink can be simple text or an icon of your choice.

Here is an email example of combining this approach with the HTML table technique described in the previous section. The pdf and excel icons act as hyperlinks for opening report files
.

If you’d like me to send you a sample report demonstrating how Crystal formulas can dynamically construct the hyperlinks and the references to the icons, please send me an email request. I can also send you the pdf and excel icons used in this example.

File Attachments

Attaching Multiple Files

To attach multiple files to a single email message, simply specify multiple files and separate them with a semi-colon (;) Without any spaces.

If all files are under the same folder, it's enough to specify the full path only for the 1^st file.
For example: c:\temp\Sales.pdf;Returns.pdf

You can also specify file names using wild cards.
For example, in a bursting scenario, to send all pdf files in the current month folder under the current customer:

C:\VC_Exports\{customer.customer_id}\{@Month}\*.pdf

and to send all files that start with the current Customer ID:

C:\VC_Exports\{customer.customer_id}*.*

Attaching Optional Files

You can indicate that an email attachment is optional by prefixing <Opt> to the file path & name. For example, if you need to email Sales.pdf (always) and Returns.pdf (if it exists), use: c:\temp\Sales.pdf;<Opt>c:\temp\Returns.pdf
- or -
c:\temp\Sales.pdf;<Opt>Returns.pdf

Email Addresses

Specifying Multiple (Simple/Composite) Email Addresses

You specify multiple email address destinations in the To, CC, or BCC emailing options, by separating them with a semi-colon (;) Without any spaces.
You can also specify composite (display name as well as address) email destinations.
For example: "Ido Millet" <ido@MilletSoftware.com>;"Jane Doe" <Jane@aol.com>

Specifying Email Distribution Lists in Text Files

To facilitate emailing to a long list of recipients, you can specify in the
To, CC, and BCC emailing options a file name containing a distribution list.
For example, using Notepad you can create a file such as:

You then specify that Visual CUT should use that file as a distribution list by entering
File:c:\temp\test_email_list.txt
in the To, CC, or BCC emailing options.

Notes:

· you use the word "File:" followed by the path & name of the text file containing the email addresses. Each address should be on a separate line and it can be specified as an email address only or as a composite (display name and address) as shown in the example above.

· As always, you can include references to dynamic fields and formulas. For example,
File:c:\distribution_lists\Department_{@DeptID}.txt
would allow you to burst a report by department and use a different distribution list for each department.

Specifying Email Distribution Lists in SQL Queries

In cases where you wish to dynamically retrieve the list of email addresses using an SQL query against an ODBC data source, you can specify in the To, CC, and/or BCC emailing options an expression such as:

MS Access Example:
ODBC:Customers::User_ID::Password::SELECT [email] FROM [Contacts] WHERE [Customer_ID] = '{Customer_ID}'

SQL Server Example:

ODBC:CONTACTS::sa::xxxxx::SELECT DISTINCT AHD.ctct.c_email_addr FROM

AHD.ctct where AHD.ctct.c_email_addr IS NOT NULL

The expression starts with ODBC: followed by 4 elements separated by ::

1. ODBC DSN (Note: could be different from the DSN used for the Crystal report)

2. User ID (use a single space if not needed)

3. Password (use a single space if not needed)

4. SQL Statement

Notes:

§ If the SQL statement returns multiple rows, Visual CUT takes care of concatenating the email addresses from all the rows to a single string with semi-colon as the delimiter.

§ The SQL statement syntax depends on your database. For example, as shown in the samples above, MS Access uses [ ] around field/table names but SQL Server doesn't.

§ You can embed dynamic fields/formula values anywhere inside the expression.
In the MS Access example, the list of contacts for the Customer in the current bursting cycle would be retrieved. This offers powerful email distribution management options...

Specifying Bursting email Addresses in a Formula

In bursting scenarios, if the database doesn’t contain an email address for each Group Level 1, you can use a suppressed Crystal formula (in GH1 or GF1 sections) to return a different email destination for each Group. For example:

Select {Branch_Manager.ID}

Case 101:

"Jim@Acme.com"

Case 103:

"Amy@Acme.com;Don@Acme.com"

Case 204:

"Veronique@Acme.com"

Default:

"serge@Acme.com";

Force Email_From to Match Email_User_ID

To block impersonation, many email servers accept messages only when the Email_User_Id (used to authenticate) matches the Email_From address. To avoid failures, you can set the following entry in the [Options] section of the ini file:
[Options]
Email_User_ID_Override_Email_From = True

During processing, this would automatically set the Email_From to the Email_User_ID even if a user sets the Email_From option to something else. Note that the user would be free to set the email from name to whatever they want (e.g. "My Preferred Name" <from email address>).

New Email Engine

Starting 2011, extra options are available via the ‘Email 2’ tab in the Options dialog:

Settings & Arguments for Advanced Email Features

When sending messages to multiple recipients, if the SMTP server rejects one of the recipients as a bad email address the process still continues emailing to the other recipients.

You can also use secure connections to the SMTP server (NTLM, CRAM-MD5, SSL, STARTTLS).

The StartTLS option allows you to communicate securely with SMTP servers that require that option. Note: use the Email_StartTLS command line argument ("True", "False", or dynamic reference) to override the default specified in the Options dialog.

The Encrypt Email Messages option allows you to encrypt the message so that only the recipient can open it. Visual CUT automatically searches for and uses the public key found in the first non-expired certificate matching the recipient's email address (the recipient will be using their private key). The search for matching key includes the Current User’s personal certificate store and then the Local Machine's personal certificate store. Use the Email_Send_Encrypted command line argument ("True", "False", or dynamic reference) to override the default specified in the Options dialog.

The Sign Email Messages option allows you to sign (using your private key) the message so that the recipient can verify (using your public key) that a) you are the true sender of the message, and b) the message content hasn’t been altered. Note: use the Email_Send_Signed command line argument ("True", "False", or dynamic reference) to override the default specified in the Options dialog.

The SMTP Domain option allow you to specify a domain in cases where the SMTP server used integrated authentication. Note: use the Email_SMTP_Domain command line argument (static or dynamic reference) to override the default specified in the Options dialog.

Queuing Emails & The smtpQ Service

With the new email engine, you can queue outgoing email messages in an ‘Outgoing’ folder monitored by a new smtpQ service. If you enter any path in the Outgoing Folder option in the ‘Email 2’ tab, Visual CUT would use that approach. You can also activate this behavior by using the command line argument of "Email_Outgoing_Folder:Path_to_Some_Folder".

A special smtpQ Service (a separate process that always runs in the background) is responsible for handling the email messages queued in the ‘Outgoing’ folder. You can install, start/stop, and administer the smtpQ Service by clicking on the ‘Administer smtpQ Service’ button or by double-clicking the status labels on the right:

If the smtpQ Service Fails to Start

You need to have Administrator rights to manage the smtpQ service. You may also need to Right-click the Visual CUT.exe and set it (Properties, Compatibility tab) to Run as Administrator (set the option to apply to all users).You may also need to lower the Windows ‘User Access Control’ security settings before the machine allows Visual CUT to manage the smtpQ service without causing a popup window each time Visual CUT starts.

If the service still doesn't start, download and install the VC++ 2015 runtime from Microsoft.

Monitoring Email Queuing

If an Outgoing Folder is specified, Visual CUT shows the number of email messages in the Outgoing and Undeliverable folders in the first 2 panels of the status bar.
The panel showing the number of messages in the Outgoing Folder, also indicates if the smtpQ service is Not Installed, Stopped, or Running. The information is refreshed every 5 seconds:

If the Visual CUT & smtpQ Folder don’t match, the status bar indicates there is a problem:

As an added convenience, you can open the Outgoing folder or the Undeliverable folder in
File Explorer by double-clicking their panel.

Operating Logic

As soon as a new .eml file appears in the Outgoing Folder, the smtpQ Service will attempt to send it. If it succeeds, it will either move the file to a Sent folder or you can elect to have successful messages deleted. If after several minutes of repeated retries, the service fails to send the message, it will move it to an Undeliverable folder.

These email messages are deposited as .eml files that can be opened in Windows Mail or Outlook Express. You can also manually move these files between folders. For example, if you copy .eml files from the ‘Sent’ folder to the ‘Outgoing’ folder, they will be emailed again. This can be useful in cases where the receiver junked your original message by mistake.

Among other benefits, this allows you to archive outgoing emails and easily recover from email service disruptions. For example, your email server may be down or your email service provider may not allow more than 100 messages per hour.

After making changes to the options in the smtpQ Service Manager dialog, you should click the Apply button, and then stop and restart the service to have these changes take effect.

smtpQ Administration

Clicking on the Administer smtpQ Service button brings up the following window:

The Install Service button installs the service so that each time your computer starts the service will start automatically. Once the service is installed, you can Start or Stop the service using the appropriate buttons. You can also stop and start the service from the Windows Control Panel, Administrative Tools, Services.. (it will show up as Chilkat SMTPQ):

Important: while the Outgoing Folder option in Visual CUT controls where Visual CUT deposits outgoing email messages (as .eml files), the Outgoing Folder option in the smtpQ Service controls what folder is monitored by the service. Obviously, these two options should point at the same folder if you wish to actually send emails automatically.

Keep the Max Threads option low unless you are sure the SMTP server would allow you to send a high volume of emails through many concurrent sessions.

The Max Retries option allows you to specify how many attempts would be made to send a failing email message (for example, if connectivity to your SMTP Server was lost). The delays before each retry keep increasing from 1 to 10^th {5 sec, 10 sec, 15 sec, 1 min, 1.5, 2, 5, 10, 15,
20 minutes}.

Slowing Down Outgoing Emails

If your SMTP service provider imposes a limit on how many emails you are allowed to send within a given time period, you may need to slow down the email queuing process. The Sleep After Send option (see image above) allows you to do that. If set to a value greater than 0, the service “sleeps” for a specified number of milliseconds.

For example, A value of 10000 milliseconds would cause 10 seconds of sleep after each successful email.

To disable sleep mode, leave that value as zero.

Naming Scheme of .eml Files

To facilitate the process of locating specific messages, the .eml files are named using three parts:
a) the name and address of the first email recipient

b) [the Subject of the email message]

c) {the date and time the message was generated}
d) [The group number being processed]

Remember that these .eml files can be opened using software such as Windows Live Mail, Outlook Express, etc..

Here’s an example:

smtpQ Service Failure Action Properties

Each time the smtpQ service is installed or reinstalled, it is a good idea to set Recovery properties in case it fails. Locate Chilkat SMTPQ in the Component Services panel in Windows:

Right-click the service, select ‘Properties’ and go to the Recovery tab. Change the failure options from ‘Take No Action’ to ‘Restart the Service’:

Generating Twitter or SMS Messages via Email

You can send SMS messages from Visual CUT using email. If you know the number & carrier, you simply email to the phone number and a domain associated with the carrier.
For example, 1234567890@txt.att.net see list of domains here.
If you don't know the carrier associated with the phone number, you can use an email-to-SMS gateway service such as: https://www.textlocal.com/integrations/email-to-sms/ or my CUT Light UFL (see example here).

Or direct emails to a Zapier account with a business rule that triggers an SMS via Twilio.

SMS via Visual CUT -_ Zapier -_ Twilio.png (1484×679)

Sample Zapier rule to send SMS via Twilio upon receiving the email from Visual CUT:

In order to send tweets via Visual CUT, you can send email messages via a service that acts as a bridge to Twitter. The text below was provided by a Systems Analyst at a Fire Department that asked to remain nameless:

Other Options

Specifying an Email Reconnect Option for Email Bursting

During Email bursting, the default behavior is to disconnect from the email server after each message. This avoids scenarios where the SMTP server imposes a limit on how many messages can be sent within a single connection. If you know your server doesn’t impose such a limitation, or if the number of emails you are sending during a burst operation is always below that limit, you can set an Email_SMTP_Disconnect_After_Send option (in DataLink_Viewer.ini) to FALSE.

Specifying a Different Character Set

In order to override the default character set (iso-8859-1) you should add an entry to the [Options] section of DataLink_Viewer.ini. For example, in order to support Chinese characters, you should add the following entry:
Email_Char_Set=big5

Skipping Emails (VC_Skip_Email)

If you wish to skip the sending of an email message, you can include the text VC_Skip_Email anywhere inside the Email_To option. For example, you can create a formula that, depending on customer or order status skips the email messages to certain customers. In those cases, instead of returning the customer’s email address, the formula would return "VC_Skip_Email". You can drag that formula into the Email_To option and Visual CUT would then skip the emails for those cases.
The advantage of this approach, compared to filtering the report, is that you may want the skip just the emailing while keeping exporting or printing functionality.

‘Start Process’ button and Progress Window

This button simply starts the process of Bursting, Exporting, and Emailing as specified by the options above. During the process, a window traces the progress of the operation:

While in progress, instead of a Close button, you will see a STOP button allowing you to abort the operation.

Tip: at the end of a process, if you double-click the export file name field
(in the export/email tab) , Visual CUT will open that folder in file explorer for you.

Scheduling

Version 6.9002 has an integrated task scheduling GUI (Windows Scheduler used as engine).

See 9-minute video demo.
Note: to disable this functionality, see Restricting User Actions.

Scheduling Area

Scheduling String

The scheduling string text provides the necessary command line to trigger Visual CUT processing for this report. The button to the right allows you to select or create a batch file to hold this command line.

Scheduled Printing

This area also shows what printer is currently associated with the report. Visual CUT sends reports scheduled for printing to that printer. Within Crystal, you can associate each report with a different printer using the File, Printer Setup… dialog. As explained later, you can override the printer destination when scheduling or invoking Visual CUT via command lines.

The number of copies option can be dynamic (drag & drop a formula into that option) or static (enter a value). You can also specify the collation option.

Note that these printing options apply only for scheduled (command line) invocations of Visual CUT. if you want the report to be printed during an interactive session, you should simply print it from the Preview tab).

Arguments

The argument field allows you to specify and save extra processing directives. The list of available directives is provided in the table of command line arguments at the end of this user manual.

These arguments allow you to tackle many use scenarios that are impossible to address with other tools. By specifying the arguments in this field, you remove the need to specify them in the command line. You can then test and benefit from these options even during interactive processing.

A double-click on the arguments area, or a click on the button to its right, launches an 'Edit Arguments' window that makes it easier to review/edit the arguments:

You can drag & drop or double-click the report fields/formulas to insert them into the arguments. As demonstrated by the tooltip, the dynamic values of these fields/formulas are used during processing.

The Rich Text Format allows you to switch to plain text formatting. In Rich Text Format mode, arguments that are acceptable in the GUI are highlighted in blue. For example, Parm arguments are not recognized at this stage because we reach the Preview phase only after the report data is retrieved.

The paper scroll button launches a browser to the table of command line arguments in the online user manual.

Control Processing Options When Encountering Zero Records

The command line is constructed as the name and path of the executable (surrounded by quotes),
followed by –e or -E and the path and file name of the report (surrounded by quotes):

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt"

Specifying –e or –E in the string above causes automatic "Execution" based on encrypted and stored logon information, stored parameter values, and the various processing options specified & saved during an interactive session in Visual CUT.

–e aborts processing of empty reports while –E doesn’t.

Specifying –s in the string above causes automatic "Show" (Preview Tab) based on logon and parameters specified & saved during a previous session in Visual CUT.
You can also use this to create a simple shortcut for quick viewing of a report.

If no processing option (-e, -E, or –s) is specified in the Scheduling string, the application’s Preview Tab would open for the specified report prompting for Parameters and Logon information if required.

Adding Scheduled Tasks

In the Export/Email tab, a button to the right of the scheduling string launches a dialog that allows:

a) Viewing and modifications of the command line

b) Inserting the command line into a new/existing batch file

c) Creating a scheduled task for the command line or the batch file

Inserting multiple command lines into a single batch file allows a single scheduled task to trigger multiple processes. Consider naming the batch file to reflect the schedule logic (for example, "Morning Reports.cmd" or "Every Hour.bat"). If you are scheduling a new batch file, turn on the '& Schedule' checkbox. You would be prompted to set the task trigger options
(see image). Then, the task is automatically created with all other options set to recommended defaults. You may then use the task management & monitoring window to review/edit those options.

Place the command line in a batch file

The "Scheduling String" in Area 5 provides you with the command line needed to run a report via Visual CUT in unattended mode. You may copy and paste that command line into a batch file but a better approach is to click the button to the right of the scheduling string.
This prompts you to enter a new batch file (.cmd / .bat) name or select an existing batch file.

The command line is then inserted into the new/existing batch file and you can elect to immediately view/edit the batch file inside Notepad.

You can test the process by double-clicking the batch file. This should trigger processing of the report in Visual CUT.

Command Line Wizard (Parameters & Skip Zero Records)

If the report has parameters, the button to the right of the scheduling string starts a dialog with options to include parameters in the initial command line. If the report has Date or DateTime parameters, the dialog defaults to including them. You can then edit the static values in Notepad, and replace them with Date Constants such as Yesterday, Start_Month_Minus_1, etc. (see Date Constants section in the user manual).

If you select ‘ALL parameters’ from the drop-down, all active parameters are included.
Note: you should include parameter arguments only if you need to override the parameter values saved when you previewed the report in Visual CUT.
(Parm1 is not included in the case below because it is an unused parameter):

If you uncheck the ‘Skip 0 Records’ option, the execute flag in the command line changes from ‑e to -E. With the default of ‑e Visual CUT skips processing if the main report has zero records (allowing easy implementation of exception reports and email alerts).

Management & Monitoring of Scheduled Tasks

A button on the first tab launces a window for managing & monitoring scheduled tasks.
The targeted tasks are those that call batch files, Visual CUT or DataLink Viewer.

Compared to the Windows Task Scheduler dialog, this window has several key advantages:

· Task status is updated automatically without needing to click Refresh (and is color-coded)

· Mass update of login information for all tasks that belong to a specified user.

· Suspend/Resume all enabled tasks (leaving Disabled Tasks untouched)

· Easily update batch file tasks to avoid failure (insert missing Start-in folder) or
to run in an invisible window.

· Rename, Clone, Edit, Export & Import tasks.

· Arrange the grid: sorting, grouping, filtering, visible columns…

Fixing Issues

Failure to Add a Scheduled Task

If you get an error message indicating 'Failed to register with given user id…Access is denied…',

right-click the Visual CUT.exe and set it (Properties, Compatibility tab) to Run as Administrator (use the option to apply to all users). Do the same for Visual_CUT_Helper.exe. You may also need to use Windows 'Change User Account Control Settings' and lower UAC to 'Never Notify'.

You can see background information about this here: https://www.devopsonwindows.com/create-scheduled-task/

Note, in particular, the following text:

--------------------------------------

However, if you try to run the task manually, it will fail with an “access is denied” exception (assuming you have User Account Control enabled). To address this, either disable UAC (always a valid option in my book), or you can configure the task to effectively “run as administrator”:

…
Note that you will need to run the application that creates the task as an administrator as well if you use this approach.

--------------------------------------

Failure to Refresh Status in Monitoring Grid

If the monitoring grid doesn't update status and doesn't show newly added tasks:

1. Make sure the tasks were saved under the ‘Task Scheduler Library’ root folder of the Windows Task Scheduler. Not under a subfolder.

2. Make sure Task History is not disabled in Windows Task Scheduler options. Start Windows Task Scheduler and change the settings to match what is shown in this image.

Mapped à UNC File Paths

The task scheduler, given that it runs under the local SYSTEM account, may not recognize mapped network drives. Visual CUT automatically convert mapped paths to UNC paths when you open an rpt from a mapped folder, or when you set up export file locations.
For example: \\server123\ixm7\{@Year}\Sales for {Product_Type.Name}.pdf
Instead of: P:\{@Year}\Sales for {Product_Type.Name}.pdf
But if the report uses a mapped drive in the data source setup, you should change the data source definition to use a UNC path instead.

Processing of Multiple Reports in a Single Batch (.BAT) File

You can use several command lines inside a single batch (.bat or .cmd) file to trigger processing (manually or via scheduling) of multiple reports. For example, double-clicking (or scheduling) the following Ido.bat file would trigger processing, one after the other, of Report1.rpt and then Report2.rpt:

Execute Multiple Reports in a Single Process

You can execute multiple Visual CUT command lines found inside a batch file (or any text file) in a single process. This avoids multiple starts and improves performance.
You specify the target batch/text file using the following command line:

"C:\Program Files (x86)\Visual CUT 11\Visual CUT.exe" "Batch:C:\Test\My.cmd>>0>>"
or

"C:\Program Files (x86)\Visual CUT 11\Visual CUT.exe" "Batch:C:\Test\My.txt>>0>>"

Visual CUT then executes all the relevant command lines (those that call Visual CUT) found inside the specified file.

Notes:

· The '>>0>>' portion of the command line argument is reserved for future use.

· While the single process is running, the tooltip for the Visual CUT status bar icon shows the progress (e.g. Visual CUT [1/4]: Invoices.rpt...).

· In cases where you need the process to redirect to a non-default Main Files folder, add the Main_Files_Folder command line argument to the command line above, not for each command line, because this directive gets processed once upon initial load. This avoids the need to specify this directive for each command line.

Execute all Command Files in Queue Folder

To execute all Visual CUT command lines in all batch/text files found inside a folder (acting as a queue folder for processing requests) and move those files to another folder (to avoid repeat executions) use a command line such as this:

“C:\Program Files (x86)\Visual CUT 11\Visual CUT.exe" “Batch:QFolder_P1>>0>>"

Instead of specifying a file name, as in the section above, QFolder_P1 specifies a DataLink_Viewer.ini section that should look like this:
[QFolder_P1]

QFolder= C:\Users\jxd7\OneDrive - MS\Requests\

XFolder=C:\temp\Xecuted\

The section name must start with QFolder_
QFolder specified the folder to scan for (and execute) all .cmd/.bat/.txt files
XFolder specifies the folder where the files should be moved to (to avoid duplicate processing)
XTimeStamp (True or False) specifies whether a date & time stamp should be added to the file.
for example, Test.cmd è Test_20210123_111242.cmd

You can use my ActionQ software to trigger processing when a file appears in a folder.

Scheduling (old approach)

By clicking on the Save button, all report processing options, parameters, and logon information (encrypted) are saved for later use by Visual CUT. This allows the application to process any report in unattended mode by simply invoking the executable (Visual CUT.exe) with a proper command line (using a *.Bat file, a RUN command, a desktop shortcut, or a call from any other application).

The typical approach, if you are not using the New method described in the previous section,
is to
1) place the command line in a batch (.bat) file, and
2) call the batch file from the Windows Task Scheduler

Call the Batch file from Windows Task Scheduler

While there are many commercial schedulers, the free Windows Task Scheduler (already installed as part of your Windows operating system) is capable of handling most scheduling requirements. Here’s how you can go about scheduling a batch file:

In Windows, click on Start, Settings, Control Panel, Scheduled Tasks
Double-Click Add Scheduled Task
In the Scheduled Task Wizard, click the Browse button,
and select the Batch file containing the Visual CUT command line(s).
Specify Name and Frequency for the scheduled task:
Specify Schedule options. These options vary depending on the frequency you selected above.
Specify your password:

Select the option to Open advanced properties and click Finish.

The Schedule tab in the advanced properties dialog provides an Advanced button:

Clicking on that button, provides various advanced scheduling options:

9. Using the Settings Tab, you can specify other advanced options such as minimum idle time requirement before the scheduled task is allowed to begin.

Be sure to turn on the option of "Wake the computer to run this task."
For a description of why this setting is important (in the context of the Vista operating system), see: http://support.microsoft.com/kb/930133.

10. After the task is scheduled, it is listed and tracked under the Scheduled Tasks folder.
By double- or right-clicking-clicking any task in the Scheduled Tasks folder, you can bring up the scheduling dialog, change settings, rename, run, or disable a task.

Scheduling Issues

Windows 7+ Task Scheduler

Turn on the "Run with highest privileges" task property (‘General’ tab).
The user account that is setting up the task should be a local administrator.

On the actions tab, set action to Start a program

You can simply browse and select the batch file (*.bat or *.cmd).
Or set the Program/script as cmd.exe and
the arguments as: /C C:\Some_Folder\Your_Bat_File.bat

Hide Batch (Command) Windows

To avoid being distracted by the batch file window each time it gets triggered, save the following line as invisible.vbs (use Notepad Save As... All Files):

CreateObject("Wscript.Shell").Run """" & WScript.Arguments(0) & """", 0, False

In task scheduler, follow this example (use actual paths to invisible.vbs and to your batch file).

The application in this case is wscript, and the arguments to it are the invisible.vbs followed by the batch file. Here is a link to an explanation and other options.

Another option to hide the task process is to set it to 'Run whether user is logged on or not'.

E-mailing Alert Messages and Exception Reports

Imagine managers at your company wish to receive daily reports showing exceptions such as orders with very low profit margins, products with very low inventory levels, late shipments, or production runs with very high scrap rates. In most days these exception reports should be empty and should not reach the managers.

Using Visual CUT you can schedule these reports to run as frequently as you wish, but with
–e rather than –E in the command line. This would ensure that during each scheduled processing cycle, the e-mail message, and (optionally) the attached report would be sent only if exceptions were indeed found. If no records pass the record selection criteria, exporting, e‑mailing, and printing of the report are simply aborted.

This logic applies to the main report. A case of no records in the main report but some records in a subreport is still considered as no records.

Note: to avoid repeating the same exception email, see Avoiding Duplicate Processing.

Management By Exceptions and Business Activity Monitoring (BAM) are powerful approaches to management, and Visual CUT makes them easy… J

Using Command Line Arguments

Arguments to Specify Parameter Values

When you open a report in Visual CUT, the values you specify in response to parameter prompts are saved in the internal database (Visual CUT.mdb). In some cases, you may want to invoke Visual CUT processing via command line calls while overriding some or all of these stored parameter values. You can do this by specifying additional command line arguments.

So far, the string used to schedule or launch processing of reports was described as:

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt"

"C:\Program Files\Visual CUT\Visual CUT.exe" -E "C:\Program Files\Visual CUT\Visual_CUT.rpt"

You can add optional arguments to the command lines, which identify the parameter (by its number) and specify its value. For example, using the following string would override the first parameter value saved by Visual CUT with the value of 1988 (in the sample Visual_Cut.rpt report, the first parameter is the YEAR).

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Parm1:1998"

The value of a date parameter would be specified as:

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Parm1:3/10/2003"

Note that the syntax is constructed as the word "Parm", followed by the number of the parameter (according to the order of parameters shown in Crystal), followed by a colon and the value.

Here’s how you would specify the 1^st and 3^rd parameter values:

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Parm1:1998" "Parm3:Ido Millet"

Notes:

· Visual CUT handles the necessary data type conversion to match the parameter data type.

· All command line arguments must be enclosed in double quotes and separated by a single space.

Range and Multi-Value Parameters

Visual CUT supports all parameter types including multi-value, range, and mixed parameters. To learn how such parameter values can be specified via command line arguments, save the report settings in Visual CUT, open Visual CUT.mdb in MS Access and observe the parameter values saved in the Report_Opt table.

A multi-value discrete parameter value is specified as follows:

---------------------------------------------------
... "Parm1:Competition:::Gloves:::Helmets"
---------------------------------------------------

A range parameter (in this case a date range) is specified as follows:
---------------------------------------------------
... "Parm1:7/15/1996>>>7/15/2003>>>3"
---------------------------------------------------
The 3 at the end indicates the start and end points are included.
A 0 at the end would indicate the start and end points are NOT included.
A 2 at the end would indicate the start point is included and the end point is not.
A 1 at the end would indicate the start point is not included and the end point is.

Add 4 to these values if there is no Upper Bound.

Add 8 to these values if there is no Lower Bound.

For example, this would indicate all dates up to, and including 7/15/2003:
---------------------------------------------------
... "Parm1:12:00:00 AM>>>7/15/2003>>>9"
---------------------------------------------------
The 12:00:00 AM value is just a place-holder. Any date value would work (will be ignored).

Request User Input for Certain Parameters

You can use "ParmN:[?]" command line arguments to indicate that Visual CUT should prompt the user for certain parameter values. For example,
---------------------------------------------------
... "Parm1:Today" "Parm3:[?]"
---------------------------------------------------
Would set the first parameter to today's date, prompt the user for the 3^rd-parameter, and use saved parameter values for all other parameters. This is useful when Visual CUT is called from a command line and the user needs to interactively override saved parameter values.

Null Values

Null parameter values (for Stored Procedures) are specified in command lines by using the constant [VC_NULL]. For example, to specify that the first parameter value is null, use:
"Parm1:[VC_NULL]"

Date Constants

When scheduling reports that have Date or DateTime parameters, you can set the parameter to dates relative to the current date. Visual CUT can do this for discrete or range date parameters.

The supported constants are:

TODAY -or- YESTERDAY
TODAY_PLUS_N -or- TODAY_MINUS_N -or-
TODAY_PLUS_N_PLUS_M -or- TODAY_MINUS_N_MINUS_M -or-
TODAY_PLUS_N_PLUS_M_EOM –or- TODAY_MINUS_N_MINUS_M_EOM -or-
TODAY_PLUS_N_PLUS_M_SOM –or- TODAY_MINUS_N_MINUS_M_SOM
START_MONTH_PLUS_M -or- START_MONTH_MINUS_M
END_MONTH_PLUS_M -or- END_MONTH_MINUS_M
START_YEAR_PLUS_Y -or- START_YEAR_MINUS_Y
END_YEAR_PLUS_Y -or- END_YEAR_MINUS_Y
Nth_N_PLUS_M –or- Nth_N_MINUS_M
LAST_MM_DD –or- NEXT_MM_DD
Now_Plus_S -or- Now_Minus_S -or- Now_GMT_Plus_S -or- Now_GMT_Minus_S
YMD=+Y/Month/Day_of_Month or YMD=-Y/Month/EOM

Where N=days, M=Months, Y=Years, and S=seconds to be added or subtracted.

For example, if the current date is March 6, 2004 then:

Today = 3/6/04

Nth_16_MINUS_1 = 2/16/04 (the 16^th of the previous month)

Today_Minus_3 = 3/3/04

Last_04_01 = April 1, 2003

End_Month_Minus_1 = 2/29/04

Start_Year_Plus_0 = 1/1/04

Start_Year_Minus_1>>>Today>>>3 = Inclusive range of [1/1/03 to 3/6/04]
YMD=-1/6/15 = 6/15/2003 (-1 indicates 1 year prior).
YMD=+0/6/EOM = 6/30/2004 (must use + or – after the = sign). EOM = End of Month.

In the case of Today_Minus_N_Minus_M, N is the Days and M is the Months, so:

Today_Minus_1_Minus_2 = 1/5/2004 (one day and two months earlier)

Adding _EOM or _SOM to the end of a Today_Minus_N_Minus_M constant returns the
End-of-Month or Start-of-Month, so:
Today_Minus_1_Minus_2_SOM = 1/1/2004 (Start of Month for 1/5/2004)
Today_Minus_1_Minus_2_EOM = 1/31/2004 (End of Month for 1/5/2004)

For DateTime parameters, Now_Plus_S or Now_Minus_S, returns the current datetime adjusted by the number of specified seconds. For Time parameters, this argument returns just the current time adjusted by the number of specified seconds. For example, if the current datetime is
June 17, 2008, 5:22:38 PM then Now_Minus_3600 returns
June 17, 2008, 4:22:38 PM for a DateTime parameter and 4:22:38 PM for a Time parameter.

One way to use a date constant is to specify it as the parameter value in a command line invocation of Visual CUT. For example:
   "C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Test\Report.rpt"
   "Parm1:Today"

Another option is to open Visual CUT.mdb and entering it directly in the appropriate parameter column within the Report_Opt table.   Note that such a manual entry in the Report_Opt table would be overwritten if you interactively open the report in Visual CUT and click SAVE.

Benefits: these date constants allow you to use the same report interactively (specifying any date as the parameter value) as well as in scheduled mode. This can also lead to faster report execution since using date functions in the record selection formula within the report can force record selection to be performed by Crystal instead of by the DBMS.

Note: for DateTime parameter, the Time portion of the parameter value is set by these constants to 12:00:00 AM (start of the day). To set a DateTime parameter to the end of the day (11:59:59 PM), you must include the parameter name in a DataLink_Viewer.ini entry
under the [Options] section like this (the parameter names are separated by ||):
--------------

[Options]
Date_Constants_EndofDay_Parameters={?To_Date}||{?EndDate}

-------------

Custom Calendars

If you need to set Date or DateTime parameters to the start or end date of custom periods (for example, Fiscal Weeks or Quarters) relative to a current or shifted date, you specify just the start dates of the periods in the DataLink_Viewer.ini as follows:

[Custom_Calendars]

FiscalQ =1/1/2013>>4/1/2013>>7/1/2013>>10/1/2013>>1/1/2014

For this FiscalQ custom calendar example, you can specify parameter values like this: "Parm1:FiscalQ_Start_RelativeTo_Yesterday"
FiscalQ is the name of the custom calendar, Start requests the start date of the period within which the relative date falls. If you specify End, the parameter is set to 1 day before the next start period (at 11:59:59 if DateTime parameter).
RelativeTo is a fixed word. The date constant can be any date constants as described in the Date Constants section above. Assuming today is 6/7/2013:
"Parm1:FiscalQ_Start_RelativeTo_Today" would return 4/1/2013
"Parm1:FiscalQ_End_RelativeTo_Today_Minus_5" would return 6/30/2013
"Parm1:FiscalQ_End_RelativeTo_Start_Year_Minus_1" would return 3/31/2012

If the relative date falls outside the boundaries of the calendar, the custom calendar years are shifted until the relative date is within the calendar. This allows you to set the custom calendar and not worry about updating it again (if the dates remain the same across years).

Adjusting Date Constants for Day of Week

Visual CUT allows you to set a date parameter to the first day of week (DOW) before or after a specified date constant. For example, the first Monday in the previous month.

The syntax options are as follows:

DayOfWeek[>]Date_Constant for first target DOW after the date constant.

DayOfWeek[<]Date_Constant for first target DOW before the date constant.

Or, same as above except that date returned from date constant is used if it falls on target DOW:

DayOfWeek[>=]Date_Constant
DayOfWeek[<=]Date_Constant

Examples, assuming today is Tuesday, March 10, 2015

"Parm1:Wednesday[>]Today" => March 11, 2015
"Parm1:Wednesday[<]Today" => March 04, 2015

"Parm1:Tuesday[>]Yesterday" => March 10, 2015
"Parm1:Tuesday[>=]Today" => March 10, 2015

Number Constants

When scheduling reports that have a Number (not currency) or String parameter, you may want to set the parameter to a constant reflecting a year or a month relative to the current year or the current month.
Visual CUT can do this for discrete or range number parameters.

The supported constants are:

MONTH_PLUS_N -or- MONTH_MINUS_N
YEAR_PLUS_N -or- YEAR_MINUS_N
YEAR_AT_PLUS_MONTHS_N -or- YEAR_AT_MINUS_MONTHS_N
YearMonth_AT_PLUS_MONTHS_N –or- YearMonth_AT_MINUS_MONTHS_N

Where N is the number of months/years to be added/subtracted from the current month/year.

For example, if the current date is January 6, 2005 then:

Month_Plus_0 = 1

Month_Minus_1 = 12

Year_Plus_0 = 2005
Year_Minus_2 = 2003
Year_AT_Minus_Months_1 = 2004
YearMonth_AT_MINUS_MONTHS_3 = 200410 (year=2004 and month = 10)

One way to use a Number constant is to specify it as the parameter value in a command line invocation of Visual CUT. For example:
   "C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Test\Report.rpt"
   "Parm1:Year_Plus_0"
Note: For a string parameter, you must enclose the constant with square brackets like this: "Parm1:[Year_Plus_0]"

Another way of doing this is by opening Visual CUT.mdb and entering it directly in the appropriate parameter column within the Report_Opt table.   Note that such a manual entry in the Report_Opt table would be overwritten if you interactively open the report in Visual CUT and click SAVE.

Benefits: these constants allow you to use the same report interactively as well as in scheduled mode. This can also lead to faster report execution since using formulas within the report can force record selection to be performed by Crystal instead of by the DBMS.

Reports with More Than 8 Parameters (restriction removed, 6.2002)

This restriction is removed starting March 19, 2010. Any parameters beyond the first 7, including unlinked subreport parameters, are now saved inside the Parm8 column (in the Report_Opt table) for later handling by Visual CUT. You may still specify main report parameters via command line arguments such as
…."Parm9:Some Values" "Parm10:Some Values"

Using Parm8 to Specify all Extra Parameter Values

Let’s refer to all independent (unlinked) subreport parameters as well as all parameters beyond the first 7 main report parameters as "Extra" parameters. As mentioned above, starting with version 6.2002, all extra parameter values are saved inside the Parm8 column inside the Report_Opt table in Visual CUT.mdb. The syntax for holding these values looks like this:

[Parm_8]:Suppress
-----
[Parm_9]:2010
-----
[Parm_10]:4/1/2010>>>4/30/2010>>>3
-----

[Parm_11]:Competition:::Gloves:::Helmets
-----
[Parm_1_{Subreport1Name.rpt}]:2010
-----
[Parm_2_{SomeSubreport1Name.rpt}]:101

As you can see, main report parameters are identified by their number and independent (unlinked) subreport parameters are also specified by the subreport name. The parameters are separated by "-----" delimiters.

If you wish to use command line arguments to override the stored Parm8 values, you can use the Parm8 command line argument using the same syntax. For example (all in 1 line of course):

"Parm8:[Parm_8]:Suppress-----[Parm_9]:2010-----[Parm_10]:START_MONTH_MINUS_1>>>END_MONTH_MINUS_1>>>3-----[Parm_11]:Competition:::Gloves-----[Parm_1_{Subreport1Name.rpt}]:2010-----[Parm_2_{SomeSubreport2Name.rpt}]:101"

Alternatively, if you need to specify only main report parameters (no subreport parameters), you can simply use their position in the main report parameter list like this:
…."Parm9:Some Value(s)" "Parm10:Some Value(s)"

Using PowerShell to Set Relative Date Parameters and Call Visual CUT

The following PowerShell code sample was contributed by Roger Dearnaley, IT Manager at Sataria. It demonstrates how PowerShell calls Visual CUT (using the & symbol to trigger the command line) after applying relative date logic to set parameter values.

Similar logic can be achieved using regular batch files, but this sample may help other users who are interested in moving from batch files to PowerShell files.

emp perf reports.ps1 Roger Dearnaley, Sataria, November 2013

this script will call two Crystal Reports using Visual CUT

It will pass the previous weekday (i.e. Saturday=Friday, Sunday=Friday, Monday=Friday, Tuesday=Monday.....Friday=Thursday)

the daily report will run on Monday-Friday and weekly will only run on Monday

[DateTime]$now = ([DateTime]::Now)

[DateTime]$prevWorkDay = $now

switch (($now.DayOfWeek))

{

"Sunday"

{ $prevWorkDay = $now.AddDays(-2) }

"Monday"

{ $prevWorkDay = $now.AddDays(-3) }

default

{ $prevWorkDay = $now.AddDays(-1) }

}

$exe = "C:\Program Files (x86)\Visual CUT 11\Visual CUT.exe"

#run daily report

[Array]$params = '-e', '"\\Mufasa\Publicdocs\WMS Reports\Operations\daily emp perf.rpt"', [string]::Format('"Parm1:{0:MM/dd/yyyy}"',$prevWorkDay)

& $exe $params;

#run weekly report on Monday only

if ($now.DayOfWeek -eq "Monday")

{

[Array]$params = '-e', '"\\Mufasa\Publicdocs\WMS Reports\Operations\weekly emp perf.rpt"', [string]::Format('"Parm1:{0:MM/dd/yyyy}"',$prevWorkDay)

& $exe $params;

}

Argument to Set Formula Expressions

You can set formula expressions via a command line argument provided that:

· The formula name(s) must begin with a ^ character.

· Any double-quotes are specified as [dblq]

· Only main report formulas are targeted

The command line argument starts with Set_Formulas1: followed by pairs of Formula Names and Formula Expressions. The name is separated from the expression by >>>. Each pair is separated from the following one by ||| like this:

… "Set_Formulas1:Name1>>>Expression1|||Name2>>>Expression2"

For example, the following command line argument would set the first specified formula expression to the string "Ido" and the second formula to the numeric expression of 2 + 2:

… "Set_Formulas1:{@^MyName}>>>[dblq]Ido[dblq]|||{@^TwoAndTwo}>>>2+2"

Note: this functionality is not available in Visual CUT 8.5

Argument to Set Extra Record Selection Logic

You can use the Xtra_Record_Selection command line argument to append an extra expression to the main report record selection formula via a command line argument. This provides flexibility in filtering the report beyond parameter logic. The change applies only to the process triggered by the command line.

If the report already has a record selection formula the logic becomes:
(old expression) AND (extra expression).
Otherwise, the extra expression simply becomes the temporary record selection formula.

Here is an example:
…"Xtra_Record_Selection:{Product.Product Name} <> [dblq]Triumph Vertigo Helmet[dblq]"

Notes:

· any double-quotes in the expression must be specified as [dblq]

· this functionality is currently available only for Visual CUT 11

Arguments to Specify Printer Destination

If you turn on the "Print (if scheduled)" option, Visual CUT sends the report to the printer associated with the report. You can override the printer destination by specifying a different printer name using a command line argument:

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Parm1:1998" "Printer:HPLaser1"

Note that the syntax is constructed as the word "Printer:" followed by the printer name.

If you use "Default" as the printer name, the report gets printed to its default destination.

If instead of "Printer:…" you use "Printer_Only:….", Visual CUT limits the processing to printing only. Exporting, bursting, and e-mailing options saved for the report in Visual CUT are ignored. This allows you to invoke Visual CUT processing for printing only via one command line and invoke full processing via another command line.

When a Command Line includes "Printer:" or "Printer_Only:" argument, Visual CUT always sends the report to the printer even if the "Print (if scheduled)" option is turned off for this report.

Printing to Multiple Printers

If you need to schedule or invoke printing of the same report to multiple printers on your network, you can specify an unlimited number of "Printer_Only:" command line arguments and Visual CUT would send the report to all these printers. This improves performance compared to specifying each printer destination in a different command line because the report gets retrieved and processed only once.

Using a Text File to Specify Multiple Printers

If you have a text file containing a list of printer destinations, such as shown below, you can instruct Visual CUT to print the report to all these printers using the key word "List_File:" followed by the path & name of the text file.
"Printer:List_File:c:\temp\Supervisor_Printers.txt"

As usual, you can dynamically control the list of printers to be used by referencing field or formula names from the Crystal report. For example:
"Printer_Only:List_File:{@Printers_File}"

Arguments to Specify Printer Bursting Destination

If you need each group level 1 of your report to be printed separately (e.g., to a fax printer driver or for automatic stapling), you must have the Export and Burst options turned on in the Visual CUT saved settings for that report. Then, use the following command line argument structure:

"C:\Program Files (x86)\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Parm1:1998" "Printer_Burst:\\pc10\hp04"

Note that the syntax is constructed as the word "Printer_Burst:" followed by the printer name.

If instead of "Printer_Burst:…" you use "Printer_Burst_Only:….", Visual CUT will skip the export bursting processing and would just burst the report to the printer.

If you use "Default" as the printer name, the report gets printed to its default destination.

The printer name argument is dynamic (field/formula names are replaced with values from the report). This means you can create a formula that returns a different printer name for different group values, place that formula (suppressed) in GH1 or GF1, embed that formula as the printer name argument, and sent the printouts for different groups to different printers. For example:
"C:\Program Files (x86)\Visual CUT 11\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Parm1:1998" "Printer_Burst_Only:{@Group_Printer_Name}"

Specifying Number of Copies

To control the number of printed copies, you can use a "Print_Copies" argument. The syntax is constructed as the word “Print_Copies”, followed by a colon and the number of desired copies. For example: "Print_Copies:3"

As always, you can also make the number of copies dynamic by referring to a report field or formula:
"Print_Copies:{@Quantity}"

Arguments to Specify User ID & Password

In some rare cases you may want to override the (encrypted) User_ID & Password information that Visual CUT stores for each report. You can do this by specifying Command Line arguments:

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Test\Report.rpt" "user_id:dba" "password:sql"

Setting Encrypted Password Entries

The Encrypted_Password_Set_Entry command line argument can automate encrypted storage (within DataLink_Viewer.ini) of passwords. This allows an administrator to set or change encrypted passwords for DataLink Viewer or Visual CUT that can later be referenced from command line arguments.

Note: a much easier way to achieve this is described in the section about 'Referring to Saved Encrypted Passwords’.

To generate such entries in a targeted ini file, you call Visual CUT using a command line
(all in 1 line) argument as follows:

"C:\Program Files (x86)\Visual CUT 11\Visual CUT.exe" "Encrypted_Password_Set_Entry: H:\DataLink_Viewer.ini>>Options>>Encrypted_Password_FTP>>sesame"

After the Encrypted_Password_Set_Entry key word and the colon, the 4 arguments are separated by “>>” as a delimiter:

1. The path & name of the ini file

2. The ini section name (typically 'Options')

3. The Password Name

4. The Password to be Encrypted

Argument to avoid Login Dialog

If most of your reports use a data source requiring authentication, you probably have the 'Attempt_Logon_Without_Password' option (Options dialog, Database tab) set to False. To override that global option for specific reports, add this argument to the command line:
… "Attempt_Logon_Without_Password:True"

Database Choice Functionality (Command Line / GUI)

In some cases, you may want to use the same report to connect to different data sources, such as a testing or production server. While each report stores connection properties for only one default data source, Visual CUT allows you to use Command Line arguments to specify a different data source.

The command line argument structure is as follows:

Selecting an Alternative ODBC Data Source

… "ODBC_DSN:Data Source Name"
or

… "ODBC_DSN_From_To:Old_DSN1>>New_DSN1||Old_DSN2>>New_DSN2"

The ODBC_DSN argument overrides all ODBC DSNs used in the report by the new DSN
The ODBC_DSN_From_To argument overrides only tables that use the old DSN.

Notes:

You can combine this functionality with the user_id & password command line arguments described in a previous section.

The target Data Source Name must exist on the PC running Visual CUT. If it doesn't, Visual CUT reverts back to running the report against the ODBC DSN the report was designed for (a warning message is added to the failure.log file).

ODBC_DSN_From_To support multiple pairs separated by "||" as shown in the example above. This addresses scenarios where a report uses multiple ODBC DSNs (e.g. when subreports use different DSNs).

The ODBC_DSN_From_To is not available in the Crystal 8.5 version of Visual CUT.

You can specify ODBC_DSN_From_To as a global entry in the [Options] section of DataLink_Viewer.ini. In cases where a global transition from old DSN to new DSN are desired, this removes the need to specify ODBC_DSN_From_To as a command line argument. The entry can have multiple pairs separated by "||".

If you don't specify User_ID & Password command line arguments, and the data source requires a user id & password, you should let Visual CUT "load" the authentication information by running the report against the alternative ODBC data source. You can do that by clicking the button to the right of the Server name in the login dialog. This expands the display to include a listing of all available ODBC data sources (grouped by ODBC driver type). The original ODBC data source is initially selected and the driver group it belongs to is expanded (and prefixed with a "!").
If you select another ODBC data source, Visual CUT explains the functionality:

Overriding the Database Specified in the Report or ODBC DSN

For ODBC data sources, you can enter a database name into the login dialog if you wish to override the database specified in the ODBC data source or in the report itself. This is useful for situations where the same database (e.g., MS SQL Server) contains multiple databases each with the same table structure. If the number of such databases is large, creating a dedicated ODBC DSN for each and using the select ODBC DSN functionality may be too tedious. Instead, you can directly type in the database name in the login dialog.

To enable database name input into the database field in the login dialog, you need to set the Override_ODBC_DSN_Database entry under the [Options] section in the DataLink_Viewer.ini file to TRUE, like this:

[Options]

Override_ODBC_DSN_Database=TRUE

Note that if that option is set to TRUE, the database specified in the ODBC DSN can no longer override the database specified in the report (if the user doesn't type in a Database, the specified Database remains the one used in the report.
Note: This functionality is not available in the Crystal 8.5 version of Visual CUT.

Overriding ODBC Table Location (.CSV Files as Data Source)

This functionality was added for a user who needed to call DataLink Viewer from his application via a command line. The data source was .csv files via ODBC and a command line argument was needed to control what .csv file should be used (.csv files gets generated and named uniquely by another application).
For example, a report designed to use Risk.csv, the following command line argument:
… "Table_From_To:Risk.csv>>Risk2.csv||old.csv>>new.csv"

would cause Visual CUT to retrieve the data from Risk2.csv instead.

Within each pair of From/To directives, the ‘From’ location is separated by a ‘>>’ from the ‘To’ location. The pairs are separated by a "||" from each other.

Notes:

1. If any of the From table name is not found in the report, the process generates a failure message indicating what From table name were unmatched with report tables.

2. New Table Name should not contain dots (before the .csv). Underscores are fine.

3. This functionality is not available in Visual CUT 8.5

Overriding the Server in Native Oracle Connection

When a report uses a native connection to Oracle, you can edit the Server name in the login dialog and run the report against a different server (rather than the one the report was designed against).

Alternatively, if you are launching a report from a command line, you can override the Oracle server name by using the "Oracle_Server:" command line argument. For example:

__________________________________________________________________
… -v "C:\temp\test.rpt" "user_id:dba" "password:sql" "Oracle_Server:Server2"
__________________________________________________________________

Note: This functionality is not available in the Crystal 8.5 version of Visual CUT.

Selecting an Alternative SQL Server – OLE DB Data Source

… "Connect_To_SQLOLEDB:DataSource>>InitialCatalog>>Integrated_Auth"

The parameters (after the ":") are separated by a ">>" and are as follows:

1. DataSource is the Server Name the report should connect to.

2. InitialCatalog is the Database Name within the given server.

3. Integrated_Auth is a True or False argument indicating if Integrated Authentication should be used (if TRUE, user_id & password are ignored).

Note: This functionality is not available in the Crystal 8.5 version of Visual CUT.

Changing Folder Location for Access/Excel/Pervasive/ACT! Files

If your report uses the native connection to MS Access, Excel, or Pervasive (ddf), you can control the location of the database files using the following section in DataLink_Viewer.ini
----------------------------------------------------------------------
[Database_Path_Selection]

Paths = C:\Old\xtreme.mdb>>C:\New\xtreme.mdb||C:\a\test.mdb>>?

// Or, in the case of Pervasive ddf files:

// for ACT! .pad files: Paths = E:\DB1\DB1.pad>>E:\DB2\DB2.pad
// Paths = E:\Jobtrack\FILE.DDF>>?

----------------------------------------------------------------------
Alternatively, you can specify the desired change using a command line argument such as
…"Database_Path:C:\Prop1\FILE.DDF>>c:\Prop2\File.DDF"

As demonstrated above, the Paths entry may contain multiple pairs of old>>new paths.
Each pair specifies the old path followed by a ">>" separator, followed by the new path.

The pairs are separated by "||"

If the new path is blank, or if it contains just a question mark, Visual CUT will prompt the user to select a new path. If the directive is from the ini file (rather than from a command line argument), the user choice will be recorded in the ini file and the new path will be used without prompting the user in future runs of reports that use the source path. If the new path has one question mark (?) followed by a valid path, that path will be the default location in the dialog asking the user to select a path. If instead of a single question mark, the new path starts with a double question mark (??), DataLink Viewer will always prompt the user to select a path each time a report using the old path runs. The user choice will be added after the ?? and will become the new default value in the path selection dialog.

If the report uses a database file that can’t be found on the machine, and no command line argument or ini entry was provided, Visual CUT prompts the user to select a valid location, creates the [Database_Path_Selection] section (if it doesn’t already exist) and creates/adds the pair information to the Paths entry.

Note: this functionality is not available in the Crystal 8.5 version of Visual CUT.

Arguments to Specify Export Format

If you need to export a report to format and file name that are different from those saved for the report within Visual CUT, you can use the Export_Format in combination with the Export_File command line argument. For example:

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Export_Format:Excel 97" "Export_File:c:\temp\test.xls"

The syntax is constructed as the word "Export_Format:" followed by the export format name (see valid export format options in the Visual CUT drop-down list for export formats).

Dynamic Export Format: you can use field/formula names within the Export_Format command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT). The dynamic content of these fields/formulas would be substituted into the command line argument. For example, you could use the following command line:
"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Export_Format:{@Format}"

The {@Format} formula may return different export formats for different groups, so using a parameter (that influences the {@Format} formula) or during bursting, you can dynamically control what export format is used. For example, you may burst invoices to some customers as PDF and to other customers as Excel files.
In such situations, you will need to construct the export file name to include a formula for controlling the file extension to match the export format. For example:

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Export_Format:{@Format}" "Export_File:c:\temp\Invoice_for_{CustName}.{@ext}"

Releasing File Locks on Exported Files

You can set the Release_Shared_File_Before_Export option via the Options dialog if you wish to always attempt to unlock the exported file from shared use by network users who may have a prior version of the file opened in a shared network destination folder. To override the default behavior controlled by that option for a specific report, use this command line argument:
… "Release_Shared_File:True"

Delaying Processing After Export

In rare cases, a delay may be needed after exporting to a network drive and before doing post-processing. An ini file option called After_Export_Delay sets the default delay period in milliseconds. To override or set a delay for a report, use this command line argument:
… "After_Export_Delay:100" note: 100 milliseconds = 1/10 of a second.

Argument to Specify Email Priority

Email priority can be specified via a command line argument using the following syntax:

… "Email_Priority:Priority_Constant"
The syntax is constructed as the word "Email_Priority:" followed by one of the following priority constants: Highest, High, Normal, Low, or Lowest

As usual, you can dynamically control the email priority by creating a formula within the report that would determine the email priority (for example, if the information shows an extreme exception, increase the email priority to 'Highest'). Then, refer to the formula in the command line argument and Visual CUT would substitute the value of that formula. For example:
… "Email_Priority:{@Message_Priority}"

Argument to Specify Email Headers

Custom Email headers can be specified via a command line argument using the following syntax:

… "Email_Header:header1:::header2:::header3"
The syntax is constructed as the word "Email_Header:" followed by one or more custom email headers. If you are specifying more than one header, they must be separated by ":::".

For example:

… "Email_Header:Sensitivity: Private"

… "Email_Header:Sensitivity: Private:::X-Sensitivity: 3"

As usual, you can dynamically control the content of the custom email headers by referencing field or formula names from the Crystal report. For example:
… "Email_Header:Sensitivity: {@email_Sensitivity}"
or, for return-receipt request, which asks the receiving email server to confirm receipt:
…"Email_Header:Return-Receipt-To:{@CRM_Email}"
or, to ask for confirmation the email has been opened by the recipient:

…"Email_Header:Disposition-Notification-To:{@CRM_Email}"

Argument to Specify Email Subject Emoji

Prefixing the email subject with an emoji can improve response rates and recognition of your emails. Visual CUT allows you to dynamically set the subject emoji using a formula that returns one of several paths to a text file containing the emoji of choice. See video demo.

To create such a file, use a site such as https://emojipedia.org/ to select and copy an emoji. Paste the select emoji into a new notepad file and save as a txt file. Notepad should automatically set the file encoding to uft-8. Here’s what Notepad looks like with a checkmark emoji pasted in:

To add an emoji to the start of an email subject, use an argument such as:

… "Email_Subject_Emoji:c:\temp\Emoji_Check.txt"

As usual, you can dynamically control the selected emoji file by creating a formula within the report that would determine the file path to the matching emoji. Then, refer to the formula in the command line argument. For example:
… "Email_Subject_Emoji:{@Emoji_File}"

Here is what an email with a checkmark emoji looks like:

Note: Visual CUT’s HTML email editor reflects the dynamic emoji in Preview mode.

Arguments to Specify Export/Email Options

If you need to override the values specified in the emailing options in the 3^rd tab of Visual CUT you can use the following command line arguments:

1. Export_File

2. Export_Format e.g. "Adobe Acrobat (pdf)"

3. Export_Mode ("Burst" or "Whole" or blank)

4. Email_To

5. Email_From

6. Email_Reply_To

7. Email_CC

8. Email_BCC

9. Email_Attach

10. Email_Subject

11. Email_Message

12. Email_Mode ("Burst" or "Whole" or blank)

13. Email_SMTP_Server

14. Email_User_ID

15. Email_Password

For example, to override the export file and email_to option, use a command line such as:

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Program Files\Visual CUT\Visual_CUT.rpt" "Parm1:1998" "Export_File:c:\temp\test.pdf" "Email_To:ixm7@psu.edu"

To override a saved value with a blank, use [VC_Blank] as in: … "Email_CC:[VC_Blank]"

Arguments to Process Reports with No Settings

Imagine you have an application that needs to trigger Visual CUT processing for reports that have no saved settings within Visual CUT. Visual CUT can handle such cases provided all the necessary options are specified via command line arguments.

For example, the following command line (all in one line) would trigger exporting and emailing of Sample.rpt. The highlighted arguments (Export_Mode and Email_Mode) control what exporting and/or emailing process is required. They accept values of "Burst" or "Whole" and if one of them is omitted, then that aspect of processing will simply not take place.

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\Test\Sample.rpt" "Parm1:1997" "Export_Format:Adobe Acrobat (pdf)" "Export_File:c:\temp\{Product_Type.Product Type Name}.pdf" "Export_Mode:Burst" "Email_Mode:Burst" "Email_From:ixm7@psu.edu" "Email_To:ixm7@psu.edu" "Email_Subject:Sales Information for {Product_Type.Product Type Name}" "Email_Attach:c:\temp\{Product_Type.Product Type Name}.pdf" "Email_SMTP_Server:127.0.0.1"

Calling Visual CUT From Another Application

Using command lines allows other applications to trigger Visual CUT processing.

Here's a code example of calling Visual CUT from a Visual Basic application and specifying a parameter value. Note that double quotes are "escaped" by using "" instead of ".
__________________________________________________________________
Dim ls_temp As String
ls_temp = "c:\Program Files\Visual CUT 9\Visual CUT.exe " & _
"-e ""c:\temp\Sales.rpt"" ""Parm1:2005"""

RetVal = Shell(ls_temp)
__________________________________________________________________

Here's another code example for calling Visual CUT from a vba event and dynamically setting the report path, name, and parameter value:
__________________________________________________________________
Private Sub Combo0_AfterUpdate()
Dim rs As Object
Set rs = Me.Recordset.Clone
rs.FindFirst "[txtReportName] = '" & Me![Combo0] & "'"
If Not rs.EOF Then Me.Bookmark = rs.Bookmark

Dim myreport As String
Dim stAppName As String
Dim myvalret As String
' me.fullrep is a field that concatenates the report path & name
myreport = Me.fullrep
myvalret = Str(MyCaseno)
stAppName = "C:\Program Files\Visual CUT 9\Visual CUT.exe" & _
" -e """ & myreport & """ ""Parm1:" & myvalret & """"
DoCmd.Close
Call Shell(stAppName, 1)
End Sub
__________________________________________________________________

Note: your application can monitor success/failure of the command line call using the functionality described in the "Job Status Functionality" section of this user manual.

Specifying Arguments from the GUI

You can save and apply command line arguments through the GUI.
The Arguments field shown below gets saved into the "Arguments" (memo) column in the Report_Opt table in Visual CUT.mdb.

A minor benefit is that you can simplify command lines in batch files by using the minimal command line and storing all the arguments in the database.

A major benefit is that you can take advantage of these arguments even during interactive use. For example:

· Use Skip_Recent to avoid duplicate emails during interactive processing

· Use any of the PDF, XLS, Word, … options such as password-protecting files during interactive processing

· Request printing (e.g., "Printer_Burst:Default") while also Exporting and Emailing

· Etc.

Notes:

1. A double-click on the Arguments field opens the text in a multi-line editing mode. This makes it easier to view and change the arguments. When clicking OK, the content gets saved to the field as a single line.

2. Command line processing honors these saved arguments but can override them.

3. Users of prior versions who wish to take advantage of this new feature should add an Arguments column (Memo data type) to the Report_Opt table in Visual CUT.mdb

Referring to Saved Encrypted Passwords

This section describes how to centralize and protect passwords by avoiding specifying them directly inside command line argument. Instead, you can name, encrypt and store the passwords inside DataLink_Viewer.ini. Besides protecting your passwords, this also allows you to change the passwords in one location, instead of in multiple command line arguments.

Visual CUT already encrypts passwords for connecting reports to data sources, sending emails, exporting to ODBC, and capturing incoming emails. But plain password might be used in the following command line argument: After_Success_SQL, Email_Password, FTP_Upload, SFTP_Upload, Password, PDF_Protect, PDF_Merge, Word_Protect, XLS_Protect, XLS_Protect_Sheets, XLS_Modify_Protect, ZIP_Files. In addition, Email_To, Email_CC, and Email_BCC can contain passwords when using the option to get email addresses via an ODBC call.

To protect and centralize password in the later scenarios, go to the Process tab in the Options dialog and click on the 'Encrypt & Save Password' button. This provides the following dialog:

In the case above, I named the password for my SFTP_Upload as SFTP.

The ini file entry is always named as "Encrypted_Password_" followed by the password name you specify. So in my case, the full name is Encrypted_Password_SFTP.

From that point on, command line arguments can refer to Encrypted_Password_SFTP and Visual CUT would make the appropriate substitution. For example:
"SFTP_Upload:22>>{@server}>>PW>>ido>>Encrypted_Password_SFTP>>>>>>c:\temp\*.html>>>>10"

If you need to change a previously saved password, use the drop-down to select the previously saved password name and enter a new password.

Other Options and Features

Using Saved Data

When you open an rpt with saved data in Visual CUT, you are asked if you wish to use the saved data or refresh. In some cases, you may wish to avoid retrieving the data from the database. For example, the rpt may be exported to a Crystal Report format (an rpt with saved data) and you wish to process that data as-is.

Global Option to Use Saved Data In Command Line Processing

To set that default globally, turn on the checkbox shown in the Options dialog below:

Command Line Argument for Saved Data Action

To override the global option when processing a specific report, use a command line argument:
… "Use_Saved_Data:True" or …"Use_Saved_Data:False"

Use_Saved_Data_Recent Command Line Argument

… "Use_Saved_Data_Recent:60" tells Visual CUT to use saved data only if it is not older than 60 minutes. Otherwise, fresh data is retrieved.
A typical use scenario is to export a report over itself (refreshing the saved data inside the report) as well as exporting and/or emailing a requested format (Visual CUT can export to multiple semi-colon separated files). Future requests for the same output avoid repeated data retrievals if the saved data is fresh enough.
Note: if the source rpt/rpz file is included in the semi-colon separated list of export files, and the process uses saved data (due to this command line argument), then the export of the source rpt/rpt file over itself is skipped if it's not the first file in the list.

Partially Delegating Exporting/Bursting to DataLink Viewer 2011

You can delegate exporting/bursting operations to DataLink Viewer 2011 in order to support Crystal 2008/2011/2013/2016/2020 features:

· Calculated CrossTab members

· Dissociate Formatting Page Size and Printer Paper Size

· Auto-Arrange option for chart layouts

· The group expert options of 'New Page After N Visible Groups'

· Mixed portrait & landscape sections

· Embedded Flash objects.

· Optional Parameters.

The argument to request this is "Proxy:DLV". If you wish to use saved data in the source report, specify dlv in lower case, like this: "Proxy:dlv".

All the parameters and login info used for running the report in Visual CUT are automatically applied to the DataLink Viewer 2011 process as well. During bursting, the DataLink Viewer 2011 process communicates back to the Visual CUT progress window. For example:

Note: to export to rptr file format, use 'Crystal Report' as export format and set the export file extension to '.rptr'.

Proxy Processing Using a Data Snapshot

If you wish to save the report -- as currently previewed in Visual CUT -- to a snapshot for proxy processing, use "Proxy:dlv_snapshot". This allows you to retrieve the data only once and ensure the data processed by DataLink Viewer is as fresh as the data seen by Visual CUT. Note that such snapshot processing doesn't support features from later Crystal versions because the snapshot report is a version XI R2 report.

Another way to retrieve the data only once is to include in your batch file:
Step 1: a call to DataLink Viewer to export the report to rpt (or rpz) so the data is fresh
Step 2: a call to Visual CUT to process the report with "Use_Saved_Data:True" and a proxy call with lower-case argument ("Proxy:dlv"), so that both Visual CUT and the proxy processing by DataLink Viewer use the same saved data that was refreshed in step 1. This is a bit more involved but supports features from later versions of Crystal.

Fully Delegated Processing (Preview/Export/Burst)

To avoid preview failure in cases such as crosstabs with embedded summaries, you can delegate all processing (including report preview) to DataLink Viewer 2011.

You indicate which reports should be delegated using the following section in the ini file. The targeted reports are delimited by '||' like this:
[Delegated_Processing]

Reports=||Your_Special_CrossTab.rpt||Visual_CUT_11.rpt||

To target all reports, you can specify ||ALL||
but, it is suggested you target only specific reports.

When a targeted report is launched via a command line or a double-click from the report grid the Visual CUT Preview tab is hidden. Instead of being previewed and exported by Visual CUT, those aspects are handled by DataLink Viewer 2011.

Right-Click Menu to Toggle Delegation

When you right-click a report row in the grid, a Delegate menu option (see image) allows you to turn on or off delegation for that report. That option is currently visible only if the ini file has a [Delegated_Processing] section with a Reports entry. Toggling the option takes care of updating the ini file.

Triggering a Batch File with Dynamic Content Before/After Export

Imagine that you need to export some reports and then trigger some command line processing such as packaging the files into a .RAR archive before uploading the archive to an FTP server.

The After_Export_Batch or After_Success_Batch command line arguments allow you to insert batch file operations after exporting or processing a report. After_Burst_Batch does the same after each group export step). Visual CUT then waits for the batch file to complete processing before continuing with any other Visual CUT processing such as emailing or uploading to FTP.

The Before_Export_Batch command line argument does the same before Visual CUT exports the report. A typical use is to archive previously exported files.

The key feature is that you can embed field/formula names within the batch file just as you can within the Visual CUT 3^rd tab options. Visual CUT substitutes the appropriate values for these field/formula names before launching the batch file processing. A typical use for this is to make sure dynamic export file names are used within the batch file.

For example, using the following command line (all in one line):
------------------------------------------------------------------------------------------------------------

"C:\Program Files\Visual CUT\Visual CUT.exe" -e "C:\test.rpt" "After_Export_Batch:C:\test.cmd>>Show>>Wait" "FTP_Upload:Passive_1>>ftp://server1.RSB.com>>user1>>Pass1>>
c:\test{[yy]}{[MM]}{[dd]}.rar>>MyFolder"
------------------------------------------------------------------------------------------------------------

would cause Visual CUT, after exporting test.rpt, to:

1. Look into the c:\test.cmd batch file to locate and temporarily replace Crystal fields/formula references with their dynamic values.
For example, the following batch file:

"C:\Program Files\WinRAR\rar.exe" a "c:\test{[yy]}{[MM]}{[dd]}.rar" "c:\temp\*{[yy]}{[MM]}{[dd]}.txt"

Would be executed as if it was

"C:\Program Files\WinRAR\rar.exe" a "c:\test101014.rar" "c:\temp\*101014.txt"

2. Execute the batch file with its dynamically replaced content.

Note that in the example above 2 optional arguments are specified: (>>Show>>Wait).
You can hide the batch file window by setting the 1^st optional argument to Hide instead of Show. You can tell Visual CUT to not wait for the batch file to finish by setting the
2^nd optional argument to NoWait instead of Wait.

3. Visual CUT would then continue by executing the FTP upload the resulting RAR file.

Note: for scheduled processing under Windows 2008 you may need to set the batch file properties to: ‘Run this program in compatibility mode for’ Windows XP (Service Pack 3).
Use the option (a button in the Properties dialog) to set the compatibility for all users.

Triggering Reports Based on Database, File, and Email Events

The After_Export_Batch or After_Success_Batch arguments allow one report to monitor a database, file, or email (Crystal can use the file system or Exchange folders as data source), and locate new entries based on record selection logic or based on Skip_Recent (or process log) logic. Then, if a new and valid Database/File/Email event is detected, export to a dummy file and trigger a second report, passing to it (via a batch file) parameters from the first report.

Note: starting August 2020 the ActionQ software provides a better solution for this use case.

Update a Database After a Successful Process

See details in Update a Database After Success (After_Success_SQL).

Update a Database Before Report Runs

See details in Update a Database Before Report Runs (Before_Report_Run_SQL).

Extract Files Stored in Database

Databases can store images, documents, and media in binary column data types. You may need to extract such files to the file system for further processing (merging, emailing, etc.). Visual CUT can automate this using the SQL_Extract_Files command line argument:

… "SQL_Extract_Files:DSN>>User ID>>Password>>Column>>Folder>>
File Name>>Extention>>SQL Statement>>Unzip?"

The parameters (after the ":") are separated by a ">>" and are as follows:

1. DSN: The ODBC DSN pointing to the database. Doesn’t have to match DSN used in report.

2. User ID: Leave blank if no user id is needed to connect.

3. Password: Leave blank if no password is needed. May refer to named encrypted password.

4. Column: column name (in the SQL result set) storing the file content.

5. Folder: Path to folder where file is extracted (VC creates missing folders on the fly).
Note: can refer to a column name.

6. File Name: Name for extracted file. If this includes the path, leave the previous option blank.
Note: can refer to a column name.

7. File Extension: leave blank if File Name above already contains extension.

Note: can refer to a column name.

8. SQL Statement: the SQL statement to execute. Typically references Crystal fields/formulas. If statement returns multiple rows, one file is extracted for each row.

9. Unzip?: If 'True' the binary content is assumed to be zipped, so it gets unzipped.
Note: can refer to a column name.

For example, the following command line argument
----------------------------------------------------------------

… SQL_Extract_Files:DSN1>>>>>>St_Picture>>c:\temp\>>St_Name>>.png>>
Select * From Students Where Major='{@Major}'>>False"

----------------------------------------------------------------

Would trigger a SQL statement through the DSN1 ODBC DSN, without user id and password, and materialize all Student images stored in the St_Picture column into the c:\temp\ folder as .png files named according to the St_Name column.

The Folder, File Name, File Extension, and Unzip? Parameters may refer to database column names in the result set. This allows a result set with multiple rows to extract each file to a different name (or even to a different folder) and to unzip the content only when needed. Alternatively, they may be static text or references to Crystal fields/formulas.

Upload Files to a BLOB column in a Database

Databases can store images, documents, and media in binary column data types. For example, you may need to upload an exported PDF or XML File to a varbinary(MAX) column in a SQL Server table.
Visual CUT can automate this using the SQL_Insert_File command line argument:

… "SQL_Insert_File:DSN>>User ID>>Password>>SQL Statement>>FilePath>>"

The parameters (after the ":") are separated by a ">>" and are as follows:

1. DSN: The ODBC DSN pointing to the database. Doesn’t have to match DSN used in report.

2. User ID: Leave blank if no user id is needed to connect.

3. Password: Leave blank if no password is needed. May refer to named encrypted password.

4. SQL Statement: the INSERT SQL statement to execute. Typically references Crystal fields/formulas.
Use a ? character as the token for the file content to upload.

5. FilePath: the path and name of the file to upload into the BLOB column

6. Options: leave blank

For example, the following command line argument
----------------------------------------------------------------

… SQL_Insert_File:DSN1>>>>>>
INSERT into Sigs (Delivery_ID, Signature, Status) Values ({@ID}, ?, 'New')
>>C:\Temp\Signature_{@ID}.pdf>>"

----------------------------------------------------------------

Would insert a new row into the Sigs table and populate the Signature column with the binary content of the dynamically referenced pdf file.

As always, you can use report field/formula names within the command line argument.
The dynamic content of these fields/formulas would be substituted into the argument.
For example, the command line above is referring to the {@ID} formula.

Call a Web Service

See detail in Call a Web Service after Success (After_Success_HTTP).

ZIP and Password Protect Files

You can instruct Visual CUT to ZIP and, if you provide a password, password protect any number of files. This can be particularly useful when emailing files that need to be protected or combined into a single attachment. The zip processing occurs before emailing processing.
The command line argument structure is as follows:

… "ZIP_Files:File_List>Password>Zip_File"

Or, if you wish to use stronger encryption:
… "ZIP_Files:File_List>Password>Zip_File>AES256"

The parameters (after the ":") are separated by a ">" and are as follows:

1. File_List: comma separated list of the files you wish to zip.
If all files share the same folder, you can specify the full path just for the first file.
If a file is not found, a warning is written to Failure.log and that file is skipped.
Note: you can specify file names using wild cards.

2. Password: leave this option blank if you don't need to password protect the zip file. When avoiding password protection, the command line look like this:
… "ZIP_Files:File_List>>Zip_File"

3. Zip_File: The path and name of the target zip file. If the specified path doesn't exist, Visual CUT would create it on the fly.

4. [optional, but recommended] encryption method. Specify AES or AES256 to use the stronger and more standard AES 128-bit or AES 256-bit Deflate encryption instead of Zip 2.0 encryption (AKA "password-protected" zip).

Important Note: you can use field or formula names within the command line arguments.
The dynamic content of these fields/formulas would be substituted into the command line. Among other things, this allows you to easily zip and protect file exports with different passwords for each group you are bursting. For example (all in one line):

"ZIP_Files:c:\temp\{@Product} Sales.pdf,{@Product} Returns.pdf>
{@Password}>c:\temp\{@Product} Reports.zip>AES"

Global Tokens from INI File

You can add to the list of dynamic fields & formulas global tokens. This is useful, for example, if you want to store & reuse email distribution lists across multiple reports. The names and values of these tokens are stored in the [Tokens] section of the ini file.

[Tokens]

{[eml_Admin]}=ido@MilletSoftware.com;ixm7@psu.edu

{[eml_Sales]}=jd@acme.com;rn@acme.com

{[eml_Signature]}=<br>Regards, <br>- Ido <br><A href="http://www.acme.com/">www.acme.com</A>

Visual CUT makes it easy to add, delete, and modify these global tokens.
Simply click the ellipsis button as shown in the image below:

Load ini Values into Parameters

By naming parameters in a certain way, you can ask Visual CUT to automatically load their values from ini file entries.

One possible use may be for reports where some parameters change only once per quarter. Another case could be a situation where you develop and sell reports (probably .rpt files converted to .rpz files) to clients in a vertical market. These reports are designed to work against a known database structure, but each client may need to customize the reports with text elements, conditional formatting, or record selection criteria without changing the report design. Or perhaps you wish to restrict use of your reports to only paying customers by providing a license code that must match (using secret logic) the company name in the customer’s database.

Instructions:

First, add to the [Options] section in DataLink_Viewer.ini (in the application folder) an entry with a key name (Company) and value (Millet Software) of your choice. For example:
[Options]
…
Company=Millet Software

Then, add a String Single-Value parameter named "DLV_INI_Option_KeyName" to the report. Visual CUT automatically sets the value of such parameters to the value found for the Key Name under the [Options] section of DataLink_Viewer.ini. So, in the case above,
the parameter value of DLV_INI_Option_Company would be set to "Millet Software".

Notes:

· The user never gets prompted for the value of such parameters.

If a matching key name can’t be found, the parameter gets the value of:
"Failed INI Lookup"
You can have as many parameters like this as you wish, each with a different key name.
To pass such parameters to subreports, create a formula in the main report that simply returns the value of the parameter. Then, pass that formula as a link to the subreport.

Securing Reports against Unauthorized Use

If you wish to secure your reports against unauthorized use, you can provide authorized users a License Key string for the ini entry. Within the report (later distributed to clients as an .rpz file) you design a record selection criterion that returns true only if the license key matches a condition, such as the company name in the database. As a simple example, you could check the number of characters in the license key is equal to the length of the actual company name (in the database) plus the number of R’s in that company’s name.

FTP/SFTP

Exporting to an FTP Server (old approach)

One option for exporting to an ftp server is to map the target FTP folder into a "drive" letter on the machine where Visual CUT is running. From that point on, Visual CUT can simply export to that drive as if it’s exporting to a local drive.

In cases where due to security or operating system restriction the mapping can’t be done using Windows, you can use specialized utilities that take care of this mapping.

One such utility is free: FTPDrive: http://www.killprog.com/fdrve.html

Another is WebDrive ($69.95): http://www.southrivertech.com/products/webdrive/index.html

Note: if you are exporting a PDF file to an FTP drive, and you don’t need the extra PDF file properties and bookmark functionality provided by Visual CUT, consider turning that option off (in the Options dialog within Visual CUT). This functionality requires Visual CUT to reach out and handle the exported PDF file. In the case where that file sits on an FTP drive, this can slow down processing. Alternatively, you can use 2 command lines in the batch file: the first to export to the local hard drive, and the 2^nd line that simply copies the resulting file to the FTP destination.

Uploading to an FTP Server (new approach)

You can instruct Visual CUT to FTP files to a web server. This can be particularly useful when you wish to export reports but email only a link to the exported file (avoiding the need to attach the export file).

The FTP Upload process occurs before emailing but after exporting and post-export processing. This allows you, for example, to merge pdf files, add bookmarks, table of content, and page numbers, and then upload the final pdf file so users can access it via the web.

The command line argument structure is as follows:
…"FTP_Upload:Mode>>Server>>User>>Password>>file(s)>>directory"

The parameters (after the ":") are separated by a ">>" and are as follows:

1. FTP Connection Mode. Possible Values are:

a. Passive_1

b. Active_1

c. AUTH_SSL/TLS_1
Visual CUT will detect server options and automatically selects SSL 3.0 or TLS 1.0 known as "AUTH SSL" or "AUTH TLS"

d. FTPS_1 (known as "Implicit SSL")

2. FTP Server: the Name or IP address of the FTP host

3. User _ID for authenticating to the ftp server

4. Password for authenticating to the ftp server (can reference Encrypted Password Name)

5. File_List: comma separated list of the files (path & name) you wish to upload. You can specify file names using wild cards, and Visual CUT will upload all matching files.

6. Target directory: The destination folder for the uploaded file(s).
For example : Sales/{@Year}/{@Product}
If some target folder levels don't exist they are created by Visual CUT.

7. Maximum_Age_In_Minutes (optional). If specified, older files are skipped. Useful when specifying files via wild card expressions and targeting newly created files.

…"FTP_Upload:Passive_1>>74.220.207.67>>user>>pass>>{@Export_File}>>/public_html/Download>>10"

Uploading to an SFTP Server

You can instruct Visual CUT to upload files via the SFTP protocol using SFTP_Upload command line argument. SFTP and FTP are two completely different protocols.
Don’t confuse FTP_Upload (described in the prior page) with SFTP_Upload.

The SFTP_Upload process occurs before emailing but after exporting and post-export processing. This allows you, for example, to merge pdf files, add bookmarks, table of content, and page numbers, and then upload the final pdf file so users can access it via the web.

The command line argument structure is as follows:
…"SFTP_Upload:Arguments"

The arguments (after the ":") are separated by a ">>" and are as follows:

1. FTP Port. Typically 22

2. FTP Server: the Name or IP address of the SFTP host

3. Authentication Mode: PW (Password), PK (Private Key), PWPK (Both)

4. User _ID for authenticating to the server

5. Password for authenticating to server (leave blank if Authentication Mode is PK)

6. Private Key File e.g., MyPrivateKey.pem (leave blank if Authentication Mode is PW)

7. Private Key File Password needed only for encrypted Private Key Files. Blank otherwise

8. File_List: comma separated list of the files (path & name) you wish to upload. You can specify file names using wild cards, and Visual CUT will upload all matching files.

9. Target directory (can be blank) The destination folder for the uploaded file(s).
Specified as absolute path or as relative to the user’s account home directory.
If this argument is left blank, the file would be placed in the user’s account home directory.
If some target folder levels don’t exist they are created by Visual CUT.

10. Maximum_Age_In_Minutes (can be blank). If specified, older files are skipped. Useful when specifying files via wild card expressions and targeting newly created files.

As always, you can use report field/formula names within the command line argument.
The dynamic content of these fields/formulas would be substituted into the argument.
For example:
…"SFTP_Upload:22>>ms.com>>PW>>user1>>pass1>>>>>>{@Export_File}>>public_html/Download>>"
or
"SFTP_Upload:22>>ms.com>>PK>>user1>>>>c:\keys\ido_dsa>>>>{@Export_File}>>public_html/Download>>10"

Downloading from an FTP Server

The FTP Download process occurs before emailing but immediately after exporting.
The command line argument structure is as follows:
…"FTP_Download:Mode>>Server>>User>>Password>>file(s)>>directory"

The parameters (after the ":") are separated by a ">>" and are as follows:

1. FTP Connection Mode. Possible Values are:

a. Passive_1

b. Active_1

c. AUTH_SSL/TLS_1
Visual CUT will detect server options and automatically selects SSL 3.0 or TLS 1.0 known as "AUTH SSL" or "AUTH TLS"

d. FTPS_1 (known as "Implicit SSL")

2. FTP Server: the Name or IP address of the FTP host

3. User _ID for authenticating to the ftp server

4. Password for authenticating to the ftp server (can reference Encrypted Password Name)

5. File_List: semi-colon (;) separated list of the files (path & name) you wish to download. You can specify file names using wild cards (*), and Visual CUT will download all matching files.

6. Target directory: The local destination folder for the downloaded file(s).
For example : c:\temp\
If some target folder levels don't exist they are created by Visual CUT.

As always, you can use report field/formula names within the command line argument.
The dynamic content of these fields/formulas would be substituted into the argument.
For example:

This downloads 2 specific files (if source folder remains the same, can specify it only once):
"FTP_Download:Passive_1>>www.MilletSoftware.com>>milletso>>Encrypted_Password_SFTP>>/public_html/Download/Sales/{@Year_Parameter}/Sales for Hybrid in 2004.pdf;Sales for Locks in 2004.pdf>>c:\temp\FTP_Download"

This uses wild card (*) expression to download multiple files:
"FTP_Download:Passive_1>>www.MilletSoftware.com>>milletso>>Encrypted_Password_SFTP>>/public_html/Download/Sales/{@Year_Parameter}/*.pdf>>c:\temp\FTP_Download"

Downloading from an SFTP Server

The SFTP Download process occurs before emailing but immediately after exporting.
The command line argument structure is as follows:
…"SFTP_Download:Arguments"

The arguments (after the ":") are separated by a ">>" and are as follows:

1. FTP Port. Typically 22

2. FTP Server: the Name or IP address of the SFTP host

3. Authentication Mode: PW (Password), PK (Private Key), PWPK (Both)

4. User _ID for authenticating to the server

5. Password for authenticating to server (leave blank if Authentication Mode is PK)

6. Private Key File e.g., MyPrivateKey.pem (leave blank if Authentication Mode is PW)

7. Private Key File Password needed only for encrypted Private Key Files. Blank otherwise

8. Match_Patterns: list of file patterns separated by semicolons (e.g. *.txt;*.csv)
If left blank, all files would be targeted.

9. Remote directory (e.g. inv/test)relative to HOME directory of user account.

10. Local directory (e.g. c:\temp) The destination folder for the uploaded file(s).

11. Mode (files to download). 0: all files, 1: missing in local folder, 2: newer/missing, 3: newer files (ignore missing) 5: missing or different size, 6: missing, different size, or newer files

For example:
…"SFTP_Download:22>>ms.com>>PW>>user1>>pass1>>>>>>*.csv;*.xls>>inv/test>>c:\temp>>0"
This downloads all csv files (aged up to 24 hours) found in the Invoices folder under the user's home folder.

SharePoint

Uploading Files to SharePoint

The SharePoint_Upload process occurs before emailing but after exporting and post-export processing.

The command line argument structure is as follows:
… "SharePoint_Upload:Files>>Folder>>URL>>User>>Pwd>>MaxAge>>Options"

The arguments (after the ":") are separated by a ">>" and are as follows:

1. File_List: comma separated list of the files (path & name) you wish to upload.
You can use wild cards and Visual CUT will upload all matching files.

2. Target_Folder: e.g., Shared Documents/Sales_Dashboard

3. Target_Site_URL: e.g., https://mycompany.sharepoint.com/sites/mysit

4. User _ID for authenticating to the server

5. Password for authenticating to server (leave blank if Authentication Mode is PK)

6. Maximum_Age_In_Minutes (can be left as blank or 0). If more than 0, older files are skipped.
Useful when specifying files via wild card expressions and targeting newly created files.

7. Options: Leave blank

As always, you can use report field/formula and Visual CUT tokens within the command line argument.
The dynamic content of these references would be substituted into the arguments.
For example:
… "SharePoint_Upload:{[Export_File]}>>Shared Documents/Dash>>
https://acme.sharepoint.com/sites/Sales>>me@acme.com>>abc123>>0>>"

File Location Functionality

Visual CUT uses several files to store user preferences, report processing options & information:

1. Visual CUT.mdb stores report processing options

2. DataLink_Viewer.ini stores general options and user preferences

3. ReportList.txt stores information about previously opened reports for use in the 1^st tab grid

4. ReportList.grd stores grid style information (grouping, column visibility, font size, etc.)

5. Failure.log records processing failure information

6. Visual_Cut.log records email communications with the SMTP server

By default, these files are in the common application data folder. However, for security or other reasons you may direct Visual CUT to use a different folder location for these main files. To do so, open DataLink_Viewer.ini in the application folder and add a line such as:

[File_Locations]

Main_Files_Folder=c:\Visual CUT\

The specified folder must exist and the user should have full permissions on it.
When Visual CUT starts, if it doesn’t find Visual CUT.mdb, DataLink_Viewer.ini, ReportList.txt, and ReportList.grd in the specified folder, it will attempt to copy these files from the application folder to the specified folder.

Direct Processing of a Report to Use a Different Settings Folder

To direct command line processing to use a different Main_Files_Folder, you can use a command line argument like this:
… "Main_Files_Folder:some path to a folder"
This is useful in scenarios where a centralized scheduler triggers processing on behalf of multiple users who maintain settings in their own folders.

Write Main Files Folder Location to a Text File

If you develop an application that needs to find out the location of the main files folder, add to an existing command line the following argument:
… "Write_INI_Location:c:\temp\VC_ini_Location.txt"
The location of DataLink_Viewer.ini would be then written to the specified text file, where your application can access it.

Automatic Handling of Write-Protected Application Folders

When a user doesn’t have write permissions to the application folder (typical of Vista and Windows 7 machines), Visual CUT handles that scenario as follows:

On load, if the user can't write to the DataLink_Viewer.ini, and the ini file doesn't already have a "Main_Files_Folder" entry in the [File_Locations] section then use DataLink_Viewer.ini if found in one of the following locations:
- common appdata (ProgramData) folder (common to all users), under "MilletSoftware\VC_11\"
- local appdata folder (local to the user), under "MilletSoftware\VC_11\"
- roaming appdata folder (follows the user to other machines), under "MilletSoftware\VC_11\"

Otherwise, this is probably the first time VC was started on that machine so we::

a) create a common appdata folder (e.g., c:\ProgramData\MilletSoftware\VC_11\

    b) copy the DataLink_Viewer.ini to that folder
    c) set its Main_Files_Folder option to that path
    d) copy all the main files to that folder

e) provide a message to the user indicating the main files have been redirected

Note: The version information dialog shows the paths to the main files. Double-Click that text area to open the folder in File Explorer.

Directing the Visual CUT database to Another DBMS

By default, Visual CUT uses Visual CUT.mdb (or Visual CUT.accdb) as its repository for report processing settings. However, if you would like to use a more robust DBMS, particularly if you want multiple users to concurrently update report processing options in the same centralized database, you may redirect Visual CUT to use any OLE DB compliant database.

First, you need to create or import 4 required tables into your database (Report_Opt, Login_Opt, Export_Opt, and Report_Export_Options).
For SQL Server, send me an email requesting the SSMS script to create the tables and instructions for using an Import Data task to easily complete the migration.

Specifying a Connection String

Use the [Options] section in the DataLink_Viewer.ini to specify the connection string

Example 1 - connecting to SQL Server Express using NT Authentication:
Connection_String="Provider=SQLNCLI11;Server=Srv1\SQL2;Database=Visual CUT;Trusted_Connection=yes;"

Example 2 - using SQL Server Authentication:
Connection_String="Provider=SQLNCLI11;Server=Srv1\SQL2;Database=Visual CUT;Uid=ido;Pwd=shhh;"

Example 3 - protecting password by referring to VC_Password_Encrypted
Connection_String="Provider=SQLNCLI11;Server=Srv1\SQL2;Database=VC;Uid=ido;Pwd=@VC_Password_Encrypted@;"

The ini file should have either a manually created entry named VC_Password_Encrypted, such as this:

VC_Password_Encrypted= F13210C40859455851BD7BE84880241A18BAFEE0E349C8ED
- or -
an entry called Encrypted_Password_VC generated via Options dialog, Process tab,
Encrypt & Save Password button with a name of VC:

Encrypted_Password_VC=F13210C40859455851BD7BE84880241A18BAFEE0E349C8ED

Export/Import Report Processing Options

The report grid right-click menu provides options to export/import reports along with their processing options:

· Export .rpt and Settings à ZIP allows you to package an rpt and its saved processing options to a ZIP file that you can copy to another machine and place in a folder where you wish to extract the rpt file. Using Visual CUT on that other machine you can then use

· Import.rpt and Settings ß ZIP to import the rpt and its settings.

This is useful when you need to replicate processing options for a report across multiple machines.

Updating DataLink_Viewer.ini via a Delta File

You may want to automate the process of updating some of the DataLink_Viewer.ini settings. You can do that by placing a DataLink_Viewer_Delta.ini file in the application folder. Any entries found in that file will update DataLink_Viewer.ini when the application is launched.

Here is an example of a DataLink_Viewer_Delta.ini file:

[Delta_Options]

Delete_After=NEVER

//USE or NEVER or Some Date specified as yyyyMMdd

// if entry above not found, then default is USE

Update_Master_INI=False

// if entry above not found, then default is False

Update_Slave_INI=True

// if entry above not found, then default is True

[Options]

Attempt_Logon_Without_Password=False
Strip_Table_Qualifiers=True

Saved_Data_Action=Display
Parameter_Values_Remember_Max_Chars=900

Saved_Parameter_Set_Minimum_N=5

[Integrated_Authentication]

Enable_Integrated_Authentication=True

The [Delta_Options] section is used only to control the following aspects of the process:

· The Delete_After option controls when the Delta ini file is deleted:

o NEVER - the file will not be deleted

o USE - the file is deleted after being used once

o yyyyMMdd - the file is deleted after the specified date

· Update_Master_INI controls whether the Master ini file is updated.

· Update_Slave_INI controls whether the User ini file is updated.

Restricting User Actions

In some scenarios you may wish to restrict what the user is allowed to do with Visual CUT. For example, as an Administrator, you may want to set things up so users can run only some reports and process them only with saved settings.

You can elect to specify some or all of the following restricting options in the [Options] section of a Master_DataLink_Viewer.ini file in the application folder:

[Options]

// Disable Preview Buttons

Disable_Print_Button=TRUE

Disable_Export_Button=TRUE

Disable_Select_Button=TRUE

Disable_Search_Button=TRUE

Disable_Refresh_Button=TRUE

// Disable Visual CUT Buttons

Disable_Options_Dialog=TRUE

Disable_Browse_Dialog=TRUE

Disable_Version_Info=TRUE

Disable_Check_for_Updates=TRUE

// Make Processing Options Read Only

Processing_Options=Read_Only

// Disable the 'Log Email Activity' checkbox and hide the Notepad button to open the log Disable_Email_Log_Activity_GUI=True
// Hide Email Queue (smtpQ) panels in the status bar
Disable_Email_Statusbar_GUI=True

// Disable certain Search & Replace categories

Disable_Find_and_Replace_Categories= Email_Addresses||Email_Information

// Disable/Hide the Scheduler GUI
Disable_Scheduler_GUI=True

Integrated Interactive Authentication

While command line processing relies on encrypted login information stored in
Visual CUT.mdb, some users may also wish to avoid repeated logins during interactive use.

Integrated Authentication ("Remember Me")

To support interactive integrated authentication, the database login information is stored, highly encrypted, inside DataLink_Viewer.ini as shown below:

To ensure full security, this encrypted format includes an internal identification of which Windows User & PC this login information belongs to. Visual CUT uses this encrypted database login information only after checking that the same Windows user is running from the same PC. In other words, users cannot break the login security by attempting to copy and paste the encrypted information to their own ini file entry).

For example, in the example shown above integrated authentication has been enabled. This can be done via a checkbox in the Option dialog (Process Tab). The user (ixm7) then logged in to a secure database by providing a database user id & password. The user turned on the "Rememebr Me" option (visible only when integrated authentication is enabled):

The information was then saved for the ixm7 user, running on the SOBPC02 PC as shown in the ini file above. From that point on, the same user (ixm7), once logged to the same PC (SOBPC02), doesn't need to manually login to the same data source.

The same user can turn on the "Remember Me" option for unlimited number of secure data sources and the information for all of them would be maintained inside the encrypted entry. The Options dialog allows each user to delete their own integrated authentication information by clicking a button.

Shared Machine Authentication

This section describes how one user can elect to share their integrated authentication information with any other user who successfully logged in to the same machine.

Step 1: First, add the entry in bold to the DataLink_Viewer.ini file:
-------------------------------------------------
[Integrated_Authentication]
Enable_Integrated_Authentication=TRUE
ixm7@SOBPC02=18CB9CAE3D8BF3484000123301DD155638EAD4AD6B4D622C04DF125B7404BCBC4717A5DA2FBCD94314A7CE63BBF7357E
Enable_Shared_Machine_Authentication=TRUE
-------------------------------------------------

Step 2: Then, as the "key" user who will share integrated authentication, run a report and get to a login dialog. Note: if you already have integrated authentication for yourself, use Forced Login.
Alternatively, discard your integrated authentication (using the Trash Can button in the Options dialog). Make sure you turn on the Remember Me option in the login dialog, just like setting up integrated authentication for yourself.

Step 3: Because of the Enable_Shared_Machine_Authentication=TRUE
you would get a dialog asking you if you wish to share your integrated authentication functionality with other users who logged in to the same machine. This ensures a user can’t be tricked into sharing integrated information without their knowledge and expressed consent.
Click YES. If you then open the DataLink_Viewer.ini file you would notice this process generated a new entry (in bold):
-------------------------------------------------
[Integrated_Authentication]
Enable_Integrated_Authentication=TRUE
ixm7@SOBPC02=18CB9CAE3D8BF3484000123301DD155638EAD4AD6B4D622C04DF125B7404BCBC4717A5DA2FBCD94314A7CE63BBF7357E
Enable_Shared_Machine_Authentication=TRUE
Shared_Machine_Authentication=C8B6CD373D5D5ADDC6FE9F379521C7318FA297CB595B992C
-------------------------------------------------
That entry, in my particular case, points to the ixm7@SOBPC02 integrated authentication entry.

Notes:
1. There can be only one shared machine authentication entry. If you need to change to another administrator, delete the Shared_Machine_Authentication line and let the new administrator go through the Remember Me and dialog step.

2. If the administrator adds data sources and login information to their integrated authentication information, all the machine users would have access to the new data sources. This is because the entry is really a "pointer" to whatever that administrator has accumulated in their entry.

3. If you interactively switch between DSNs and you want Integrated Authentication functionality, set Enable_Integrated_Authentication_For_DSN_Changes to True
This is a rare scenario so, for more detail, contact Millet Software.

Google Functionality

Add Events to Google Calendar(s)

You may want to insert an event to Google Calendars and, optionally, invite others to confirm participation. To automate this type of workflow, you can use the Calendar_Add_Event command line argument. The argument structure is as follows:
… "Calendar_Add_Event:Google_Calendar_1"

Google_Calendar_1 refers to a DataLink_Viewer.ini file section that looks like this:

[Google_Calendar_1]

JSON_Key_Path=C:\Visual CUT\Google\milletsoftware-0e770c5970d5.json

Template_Path=C:\Visual CUT\Google\Event_Sample.json

Send_Notifications=True

JSON_Key_Path points to the location of a text file downloaded by first using this link to create a Google API project and enable access to the Googler Calendar API. Then, following steps 1-5 in Creating a service account here. The downloaded json key file is used for authentication.

Template_Path points to the location of a text file providing the calendar event properties. Here's an example of such an event template file:

{

"start": {"dateTime": "2017-09-23T19:15:00", "timeZone": "America/New_York"},

"end": {"dateTime": "2017-09-23T20:15:00", "timeZone": "America/New_York"},

"description": "Complete Job Quote for {Product_Type.Product Type Name} and\nThen
email it to the customer.\n\nSubject of quote: {@Subject}",

"attendees": [{ "email": "jane.doe@gmail.com" }, { "email": "joe.doe@acme.com" }],

"summary": "Job Quote for {Product_Type.Product Type Name}"

}

Items highlighted in yellow demonstrate how you can embed dynamic references to Crystal fields/formulas inside the template. They get replaced with their actual values doing processing.
\n are used to insert new lines in the event text.

You may add other properties, such as location as described in Google's documentation here.

Send_Notifications – if set to True – sends email invitation to attendees, allowing them to confirm attendance. Here is a sample image of such a notification. The email recipient can simply click to confirm/deny participation. Those choices are then reflected by the calendar.

Adding Events to Multiple Calendars

If you wish to insert multiple calendar events, separate the ini file sections with ^^^^ like this:
… "Calendar_Add_Event:Google_Calendar_1^^^^Google_Calendar_2"

Upload Files to Google Drive

You can use Google_Drive_Upload argument to upload a file under the "Shared with me" section of the Google Drive. The uploaded file is shared with you by the service account, which you need to create as described in the previous section (Calendar_Add_Event). Similarly, you need to enable the Google Drive API.

The argument structure is as follows:
… "Google_Drive_Upload:Google_Drive_Upload_1>>c:\temp\Sales in {@Year}.pdf"

Google_Drive_Upload_1 refers to a DataLink_Viewer.ini file section that looks like this:

[Google_Drive_Upload_1]

JSON_Key_Path=C:\Visual CUT\Google\milletsoftware-0e770c5970d5.json

Template_Path=C:\Visual CUT\Google\Drive_Upload_Sample.json

Share_With=joe@acme.com||jane@acme.com

JSON_Key_Path points to the a file used for authentication. See detail in previous section.

Template_Path points to the location of a text file providing upload properties. Here's an example of such an upload template file:

{ "parents":

[ { "id": "0B27Dz6f0a81TXEhlSnJvclFOS2c" } ],

"description": "A test upload for {Product_Type.Product Type Name}"

}

Items highlighted in yellow demonstrate how you can embed dynamic references to Crystal fields/formulas inside the template. They get replaced with their actual values doing processing.

The id property is the identifier of a Google Drive folder. If you right-click a folder on Google Drive and select 'Get Shareable link', the id is at the end of the link: https://drive.google.com/open?id=0B27Dz6f0a81XTEhlSnJvclFOS2c

Auto-Refreshing Web Dashboards

You can use Visual CUT to easily implement auto-refreshing dashboards on a web server. This allows users with only a web browser to monitor relevant information. See video demo.

Web Dashboard Expert

When exporting to HTML 40, the options button launches a window allowing you to set various options for post-processing the HTML file. These options include: a) adding an auto-refresh behavior, b) Setting hyperlinks to launch to new tabs, c) Specifying tab titles & icons, d) Removing GUIDs from referenced.png image files, and e) SFTP Uploading HTML and Other files to the web server.

You can copy the generated command line arguments to the ‘Arguments’ area in the Export/Email tab.
A web dashboard using that approach is available at: https://www.milletsoftware.com/Labs/Labs.html

The dynamic tokens panel on the right allows you to embed dynamic values into these options. For example, the web page tab in the browser can reflect the date/time or the name of the sales rep in a current burst step.

iFrame Approach

Alternatively, Visual CUT can export a report to HTML "display" page every N seconds. A "dashboard" web page, visited by the users web browser:
a) reloads itself every N seconds using an HTML tag such as:
<META http-equiv=refresh content=30>
b) loads the html "display" page into an IFrame areas
(think about an iFRame as a picture frame for displaying another HTML page).

Using iFrames allows the hosting page to display multiple reports and use various GUI elements (Menus, Tabs, Accordions, and Data Tables). A sample web dashboard using that approach is available at: http://www.milletsoftware.com/dash/dash_demo_tabs.html
user id & password: demo

Visual CUT keeps refreshing the HTML display page by exporting to it every N seconds, and the dashboard page keeps refreshing itself and reloading the HTML display page. Hence, the user experiences an auto-refreshing dashboard by simply having that page open in a browser.

Here is a free web page that makes it easy to generate code for an iFrame with various options:
https://www.iframe-generator.com/

Here is what the dashboard HTML page may look like:

<HTML><HEAD><TITLE>Backlog Dashboard</TITLE>

<BODY>

<P><IFRAME border=0 name=I1

src="E:\Dashboards\Dashboard_1.html"

frameBorder=0 width=1048 height=20000>

</body>

</html></IFRAME></P></BODY></HTML>

Multi-Panel Dashboard Layout

The iFrame approach plus a JavaScript widget for dashboard layout (such as this) can produce a multi-panel auto-refreshing web dashboard. Please visit this live sample.
Each panel contains an iFrame whose source is a Crystal Report exported to html by Visual CUT:

Multi-Panel Dashboard with Drill-Across

As demonstrated by this dashboard sample, clicking a hyperlink in one panel cam load details in a related panel.
A click on the employee name in the left panel loads a report for that employee into the right panel.

To do this, you need to:

1. Assign a name to the target iFrame. Here's the right panel info in the hosting web page.

    <div class="e-panel-container">
    <iframe src="https://www.milletsoftware.com/Dashboard_TopN_Customers_for_King.html"
                     name="Employee_Detail"></iframe> </div>

2. Set the iFrame name as the target property for the Crystal report hyperlinks. Visual CUT can replace the _self target assigned by Crystal by default to hyperlinks with the name of the target iFrame:

"TXT_Replace:C:\Web_Dashboards\Multi_Panel_Dash\Upload\
Revenue_and_Delivery_By_Employee2.html||||target="_self">>target="Employee_Detail"||"

Preventing File Locking

In order to prevent any chance of file locking, Visual CUT can export the reports to one folder and then copy (or FTP) the resulting HTML file to the web folder. Here is an example of a simple batch file that executes the Visual CUT export and then copies the resulting HTML page:

"C:\Program Files\Visual CUT 11\Visual CUT.exe" -E "c:\Reports\Dash1.rpt"

Copy c:\temp\Dashboard_1.html E:\Dashboards\Dashboard_1.html

Case Study

Phillip Scheel, a data analyst at CPS Energy, was kind enough to provide a pdf file describing the approach and several dashboards he has developed.

Hyperlinks

To allow users to click and open other web pages or any other document type you can assign to any report object within Crystal a hyperlink expression.

A typical approach is to have Visual CUT export a dashboard report, say a summary report of Sales By Product Type, to one HTML page as the main web dashboard. The batch file triggering the process can have another command line to trigger bursting of another report, creating one HTML page showing Sales by Product within each Product Type:
Detail_ for_{Product_Type.Product Type Name}.html
You would then set the hyperlink expression for the Product Type field in the main dashboard report to dynamically point to its related detailed HTML page. The user can then click on each Product Type field in the main dashboard to drill-down into the detailed information in the bursted HTML pages. In a similar manner, drill-downs to related PDF or Excel files can be provided.

Note: use the Web Dashboard Expert to change hyperlink properties so that they open related web pages in a separate Window rather than replacing the content in the dashboard frame.

Tooltips

To provide users with related information when hovering over elements in the web dashboard, simply specify a dynamic tooltip expression for these objects in Crystal.
By inserting a line break character in these expressions, as in:
{@Cust} + Chr(10) + {@Cust_Info}
you can present that content as multiple lines
note: Firefox seems to be the only browser that doesn’t honor such line breaks.

Generating HTML via Email Message Body

Instead of relying on Crystal’s HTML export, you may take advantage of the email message HTML editor and Visual CUT’s ability to embed dynamic values from report fields/formulas in the message body.

You can instruct Visual CUT to save the email message body to an HTML file using the Email_Message_Save command line argument. You can also skip the actual emailing by specifying "VC_Skip_Email" in the Email_To option.

This technique provides you with full control over the HTML being generated. As shown in the video demo above, it allows tables in your web dashboard to adjust to the browser screen size. It also allows you to directly add CSS and JavaScript to the generated HTML page.

Cleaning png File References

When the exported report contains images, Crystal generates uniquely named (using GUIDs) png files, which are referenced from within the HTML file. In many cases, you may wish to "clean" these file references by removing the GUIDs from the file references and renaming the png files. Visual CUT provides two command line arguments to achieve this: TXT_DeGUID_png and TXT_Replace_Tokens. See the following user manual sections for more detail:

· Removing GUIDs from png Files Referenced in HTML Exports

· Replacing Content in Text/HTML Files – Token Approach

Restricting Access to Web Dashboards

If you wish to restrict access to your web dashboards, a simple and secure method is described here: http://www.javascriptkit.com/howto/htaccess3.shtml

Web Widget Features

You can use Visual CUT to export report/Excel/SQL data directly to a web page (.html file extension) hosting the data in a JavaScript widget such as Web Grid or Web Pivot Table. See video demo

As shown in the image below, Visual CUT takes care of several intermediate steps:

1. Export to Excel (Data Only).

2. Convert the data in the Excel file to JSON file for consumption by the web widget

3. Copying the master template from the installation folder to the export folder.
This step is skipped if the template file already exists in the export folder.
You may modify the template file in the export folder to suit your needs for extra content or different design/options.

4. Creating the web page (.html file) based on the template file in the export folder.
This step is skipped if: a) the page already exists, and b) the TXT_Replace directive does not contain {AsOf} text (indicating a need to refresh Date/Time info).
The process copies the template file (in the export folder) to the export html file and injects into it:

· Column definitions based on the data and its formatting in the excel export

· Design choices based on your export options dialog choices
(favicon, title, auto-refresh, default color theme, etc.)

· Widget tweaks to tie it to this particular export

5. SFTP upload (if so desired) the JSON file and html file. Note that the html file typically doesn’t change so its upload can be skipped based on file age.

Web Grid Export

The WebGrid export format generates a web page with an interactive grid allowing grouping, sorting, filtering, column selection, etc. The grid adjusts to accommodate different screen sizes. Here is a live sample.

Functionality (see video demo)

1. Grouping: Drag column header(s) to the grouping area to group the grid.

2. Filtering: Each column has a Filter button, allowing you to select/unselect certain values or to create a value filter expression.

3. Column Selection: The Columns drop-down provides a dialog for removing/adding columns to the grid.

4. Column-Reorder: Drag column headers to reorder them.

5. Printing/Exporting: Use the Print/Export buttons.

6. Color Theme selection: a toolbar drop-down provides a choice of color scheme.

7. Single-Column Sort: Click column headers to sort Ascending, Descending, or Unsort.

8. Persistence: the browser remembers your layout and theme choices.

9. Multi-Column Sort: Ctrl-Click a column header adds it to the sort logic.
A number reflects the position of the column in the sort logic.
In this case, the grid (using Bootstrap4 color theme) is grouped on Product Type within Employee. The sort within this grouping is by Value descending and within that by Discount.

10. Paging: a paging control at the bottom of the grid supports page navigation and changing number of rows per page.

Processing Logic

The export process uses a WebGrid_Template.html file as a basis for generating the exported HTML file. The template file is also copied to the export folder where you may tweak it for use by subsequent uses (if you wish to override default styling/content).

The process actually generates 3 files:
1. HTML file specified by you as the export file (e.g. c:\temp\mygrid.html)

6. JSON file holding the exported data (e.g. c:\temp\mygrid_Data.js)

7. Excel (Data Only) version for reviewing the export (c:\temp\mygrid.xlsx)

The creation of the HTML file (based on the WebGrid_Template.html) occurs only if the HTML file doesn’t already exist or if {AsOf} token is detected in TXT_Replace argument..
Otherwise, only the data files are refreshed. This allows you to schedule the process and use SFTP_Upload to refresh just the JSON file on your web server.

Conditional Formatting

By adding a few CSS & JavaScript lines to the template, you can add conditional formatting. See sample:

Format URLs as hyperlink icons.

If a column contains nothing but URLs (or blanks), it gets rendered as a hyperlink icon, as shown in the image above. If you'd rather display the URL text, concatenate a space to its start or ending.

Monitoring SQL Server Health

Using the free sp_Blitz stored procedure (from Brent Ozar), and a sample report (available upon request), you can use Visual CUT to monitor the health of your SQL Servers (see image above).
This video demo explains how Visual CUT can populate an auto-refreshing web grid and send you email alerts when critical issues are found.

Use HTML as Column Content

You can use HTML tags to control the rendering of grid cells. For example, the Product column in the grid below was populated using the following formula:
Replace({Product.Product Name}, "Crochet", "<Mark>Crochet</Mark>")

Notes:

1. To add the WebGrid export format to existing Visual CUT installation, you need to add it to the list of export formats in the Export_Opt table in the Visual CUT database:

Export Constant	Export Name
WebGrid	WebGrid

- Click Version Info button, and double-click text area at bottom to open the folder where the Visual CUT database is located.

- Close Visual CUT and open the Visual CUT database in MS Access

- Open Export_Opt table and add the row shown above.

2. The report should not suppress column headers. This is because column headers in the intermediate Excel (Data Only) export are needed to generate the column definitions for the JavaScript widget.
Avoid special characters in the column header names (though ‘%’ ‘#’ ‘/’ and ‘&’ characters are tolerated).

3. Keep the report to a single level of details (no Grouping).

Web Pivot Table/Chart Export

The WebPivotTable export format generates a web page with an interactive pivot table/chart.

Here is a sample web page generated by Visual CUT using this export format:

Functionality (see video demo)

This Widget has many useful options such as:

1. Toolbar buttons to switch from Pivot Table to Pivot Chart:

2. Toolbar button to export to Excel, PDF, or CSV:

3. Toolbar buttons to control visibility of subtotals and grand totals:
(the sample hides grand totals)

4. Toolbar button to apply number formatting and conditional formatting:
(the sample shown highlights average discounts above 2%)

5. Color Theme selection: a toolbar drop-down provides a choice of color scheme (persisted across sessions):

6. Top-Right corner toolbar button: for creating/modifying Pivot Tables:

Pivot Table Design: On first-time viewing in a browser, since the pivot table needs a layout defined, this dialog displays automatically so the user can design the Pivot Table. That design is persisted for future sessions by that user & browser. But the user can click to revisit and change the design.

Number Formatting: Visual CUT takes care of configuring number formatting and precision for all numeric data fields (e.g. Currency, Percent, or regular numbers) to match their formatting in the Crystal report. You can override these options using the toolbar button for formatting: That drop-down also supports Conditional Formatting.

Sort rows by Value: in the sample shown earlier, note that the rows are sorted by the grand total value. This was done by simply clicking the column header for the grand total.

Filtering: filtering (for example, to a subset of Years or Product Classes is available via the filter icons:

Grouping: via a right-click menu

Reports Functionality

You can manage and switch between report layouts. These layout definitions are not saved with data. Instead, they apply the layouts to the latest data (<pageName>_Data.js file). See video demo

The drop-down shows 5 saved report layouts. The first two are user reports, created by the user and saved to their own browser’s localStorage. The last three are master reports provided via a <pageName>_Reports.js file and available to all users. This allows you to deploy the web pivot with pre-populated master reports.

If you do not wish to use this functionality, contact MilletSoftware for instructions on how to revert to the simplified GUI (shown in the video demo in the previous section).

The toolbar buttons to the left of the reports drop-down:

Allow the user to:
1. Create a new report layout

2. Save the current report layout

3. Save the current report layout under a new name

4. Rename the current report layout

5. Download all report layouts to a new <pageName>_Reports.js file
(this allows you to create, and later deploy, that file)

6. Delete the current report layout.

Creating <pageName>_Reports.js file

When Visual CUT is installed, the following file is included:
"C:\Program Files (x86)\Visual CUT 11\WebPivotTable_Template_Reports.js"
It initializes the masterReports variable to an empty array: var masterReports = [];

On export to a Web Pivot Table (assuming the export file name is x.html), if the target export folder doesn’t already contain a file named x_Reports.js, the template file gets copied & renamed to that file. You include that file in the SFTP_Upload.

After saving some report layouts, they are available only to you (since they are stored only in your browser’s localStorage and not in the x_Reports.js file.
But you can turn your “private” layouts to master layouts by using the button to download and replace the old x_Reports.js with a new x_Reports.js file (see yellow arrow in the diagram above). You then upload the new x_Reports.js, which now contains report layout definitions, to establish them as master report layouts available to anyone with access to your web (or shared) folder.

Drill-Down

A double-click allows you to drill-down and display the detail rows for a single pivot table summary cell or chart element.

By default, only the columns included in the Rows, Columns, Filters, and Summary value are displayed. But you can use the Columns drop-down to add any other columns from the data set.

You can also use the Export buttons to download the drill-down data to Excel, PDF, or CSV.

Chart Options

The chart drop-down provides a choice of chart types and options. In the example below, the Discount metric is selected. Note: double-clicking a riser would provide a drill-down grid.

Processing Logic

The export process uses a WebPivotTable_Template.html file as a basis for generating the exported HTML file. The template file is also copied to the export folder where you may tweak it for use by subsequent uses (if you wish to override default styling/content).

The process actually generates 4 files:

1. HTML file specified by you as the export file (e.g. c:\temp\Sales_PivotTable.html)

2. JSON file holding the exported data (e.g. c:\temp\Sales_PivotTable_Data.js)

3. <name>_Reports.js file for storing master reports (see next section for explanation)

4. Excel (Data Only) version for reviewing the export (c:\temp\Sales_PivotTable.xlsx)

The creation of the HTML file (based on the WebPivotTable_Template.html) occurs only if the HTML file doesn’t already exist. If the target HTML file already exists, only the data files are refreshed. This allows you to schedule the process and use SFTP_Upload to refresh just the JSON file on your web server, since the html file didn’t change.

Notes

1. To add the WebPivotTable export format to existing Visual CUT installation, you need to add it to the list of export formats in the Export_Opt table in the Visual CUT database:

Export Constant	Export Name
WebPivotTable	WebPivotTable

- Click Version Info button, and double-click text area at bottom to open the folder where the Visual CUT database is located.

- Close Visual CUT and open the Visual CUT database in MS Access

- Open Export_Opt table and add the row shown above.

2. The report should not suppress column headers. This is because column headers in the intermediate Excel (Data Only) export are needed to generate the column definitions for the JavaScript widget. Avoid special characters in the column header names ( ‘%’ ‘#’ ‘/’ and ‘&’ characters are tolerated).

3. Keep the report to a single level of details (no Grouping).

Web Schedule Export

The WebSchedule export format generates a web page with Calendar Schedule.
Here is a sample web page generated by Visual CUT using this export format:

Processing Logic

The report must have the following columns. Column header names are case-sensitive!

The Color column is optional. It controls the background color of appointments (in hex).
This allows you to assign different appointment types different colors.

The Description is available in a detail popup when clicking on an events. It can use HTML syntax to offer hyperlinks. For example, if the Description contains this text:

<A href="https://www.MilletSoftware.com">MilletSoftware</A> User Group Agenda:

<ol>

<li><a href="https://www.milletsoftware.com/ActionQ.htm">ActionQ</a>: New Software</li>

<li><a href="https://www.milletsoftware.com/CUT_Light.htm">CUT Light</a>: Barcode Functions</li>

<li><a href="https://www.milletsoftware.com/DataLink_Viewer.htm">DataLink Viewer</a>: Desktop Shortcuts</li>

</ol>

A click on that event in your browser shows this:

The export process uses a WebSchedule_Template.html file as a basis for generating the exported HTML file. The template file is also copied to the export folder where you may tweak it for use by subsequent runs. For example, you can change the default view from ‘Week’ to ‘WorkWeek’.

The process actually generates 3 files:

1. HTML file specified by you as the export file (e.g. c:\temp\MySchedule.html)

2. JSON file holding the exported data (e.g. c:\temp\MySchedule_Data.js)

3. Excel (Data Only) version for reviewing the export (c:\temp\MySchedule.xlsx)

The creation of the HTML file (based on the WebSchedule_Template.html) occurs only if the HTML file doesn’t already exist. If the target HTML file already exists, only the data files are refreshed. This allows you to schedule the process and use SFTP_Upload to refresh just the JSON file on your web server, since the html file didn’t change.

Notes:

1. To add the WebSchedule export format to existing Visual CUT installation, you need to add it to the list of export formats in the Export_Opt table in the Visual CUT database:

Export Constant	Export Name
WebSchedule	WebSchedule

- Click Version Info button, and double-click text area at bottom to open the folder where the Visual CUT database is located.

- Close Visual CUT and open the Visual CUT database in MS Access

- Open Export_Opt table and add the row shown above.

2. The report should not suppress column headers. This is because column headers in the intermediate Excel (Data Only) export are needed to generate the column definitions for the JavaScript widget. Also, avoid special characters in the column header names.

3. Keep the report to a single level of details (no Grouping).

Web Page Options & Upload Expert

To facilitate deployment and to boost the functionality, you can click the ellipsis button to the right of WebGrid, WebPivotTable, and WebSchedule export formats:

This results in the following dialog:

This facilitates setting options and SFTP uploading the web page and its data file to a web server.

Notes:

· Use the dynamic tokens panel on the right to embed references to dynamic report fields/formulas in the web page tab name and other options. The tooltips reflect the dynamic values of such references.

· SFTP Uploads File(s) option automatically includes the HTML file and its corresponding DATA.js file.

· If the page needs to show refresh date/time (sample), use the checkbox to add ::{AsOf}|>>|{@AsOf} to the TXT_Replace directives. Place {AsOf} text in your html template and {@AsOf} formula in the report’s RH/RF section. Example: ToText (CurrentDateTime, "MMMM dd, HH:mm")
Detecting {AsOf} in TXT_Replace argument causes html page to be recreated from template.

PDF Functionality

Creating Bookmarks (Group Tree) in Exported PDF Files [Old Approach]

Visual CUT can create a "Group Tree" of bookmark inside exported pdf document.

It allows users to easily navigate through large PDF files.

You specify the Bookmark label & page by inserting a string formula in each Group Header that contributes a level to the "Group Tree." The formula/section can be suppressed.

Naming the Bookmark Formulas:

For Group Header Level 1, the name of the formula must be VC_pdf_bookmark1 , …
For Group Header Level 5, the name of the formula must be VC_pdf_bookmark5
Note: you can add other formulas at the same level (in the same section or split section) by adding a digit between 1 and 9. For example, if you used VC_pdf_bookmark2 for GH2a you can use VC_pdf_bookmark21 in GH2b and VC_pdf_bookmark22 in GH2c.

Structuring the Formulas:

The formulas must return a string structured as the Bookmark Label, followed by "::" and ending with the Page Number where the formula was evaluated.

The sample report (Visual CUT.rpt) demonstrates this functionality:

¨ On Group Header 1 the VC_pdf_bookmark1 formula is defined as:

IF InRepeatedGroupHeader THEN ""
ELSE {Product_Type.Product Type Name} + "::" + Cstr(PageNumber,0,"")

¨ On Group Header 2 the VC_pdf_bookmark2 formula is defined as:
IF InRepeatedGroupHeader THEN ""
ELSE GroupName ({Product.Product Name}) + "::" + Cstr(PageNumber,0,"")

After a PDF export, the resulting file has a 2-level hierarchy of Bookmarks and
clicking on any bookmark takes you to the page associated with that bookmark:

Controlling PDF Bookmark Colors (& Text)

If you include (anywhere) in the Bookmark Label the color constants of crRed, crBlue or crGreen (note: case sensitive) Visual CUT would set the color of the bookmark text accordingly (and remove the color constant text from the label).
This functionality is useful for indicating item performance or status visually (e.g., red color indicating poor performance). Note: remember that since you control (via a formula) the bookmark text, you can also add various label indicators such as [+], [~], [!], or [-].

The level 2 bookmark formula (VC_pdf_bookmark2) in the sample report demonstrates this approach as follows:

WhilePrintingRecords;

IF InRepeatedGroupHeader THEN ""

ELSE

(

IF Average ({@Days_To_Ship}, {Product.Product Name}) > 5.0 THEN
"[!]crRed " + GroupName ({Product.Product Name}) + "::" + Cstr(PageNumber,0,"")

ELSE IF Average ({@Days_To_Ship}, {Product.Product Name}) < 3.0 THEN
"[+]crGreen " + GroupName ({Product.Product Name}) + "::" + Cstr(PageNumber,0,"")

ELSE
"[~]crBlue " + GroupName ({Product.Product Name}) + "::" + Cstr(PageNumber,0,"")

);

Controlling How Many Bookmark Levels Are Initially Expanded

By default, the resulting PDF file will show only 1 (the top) level of bookmarks expanded, so that level-2 bookmarks (if there are any) are visible. Obviously, users can expand/collapse the bookmarks by clicking on the + or – nodes within the Adobe Acrobat reader. However, you may wish to present the users with a pdf where only the top-level bookmarks are initially visible or where more levels are initially expanded.

To change the default number of expanded levels for all processed reports, change the value of the PDF_Bookmarks_Open_Levels option in the DataLink_Viewer.ini

For example:
[Options]

PDF_Bookmarks_Open_Levels=0

To override the default number of expanded levels when processing a specific report, use the PDF_Bookmarks_Open_Levels command line argument as follows:

… "PDF_Bookmarks_Open_Levels:N"

Where N is the number of levels to be initially expanded.

For example, to have only the top bookmarks visible, use:
… "PDF_Bookmarks_Open_Levels:0"

Guarding Against Null Bookmark Values

If the field(s) used to control the bookmark label is Null, the whole formula would result in a Null value and bookmark processing would be compromised. If this is a possibility given your data you should guard against it using a formula like this:

WhilePrintingRecords;

IF InRepeatedGroupHeader THEN

ELSE

IF IsNull({Product_Type.Product Type Name}) THEN

" " + "::" + Cstr(PageNumber,0,"")

ELSE

{Product_Type.Product Type Name} + "::" + Cstr(PageNumber,0,"");

Generating PDF Bookmarks from within Subreports

As an alternative to generating bookmark information from Group Header sections in a main report (as described above), Visual CUT allows you to specify bookmarks for a given PDF file by providing a text file (PDF_Bookmarks.txt) containing the bookmark information. This file must be located in the Visual CUT application folder and must be structured as follows:

1. The 1^st line must match the RPT file name of the report being processed

2. The following lines provide 4 data elements separated by a "::" delimiter:

1. Bookmark Level

2. Bookmark Label

3. Page Number

4. Group Level 1 Value (used only in bursting operations)

Using "CUT Light" (a User Function Library described on my web site) or any other UFL that adds the ability to append text to text files from within Crystal formulas, you can generate this text file automatically by embedding formulas in any report or subreport sections.

Note that this provides functionality that goes beyond the Group Tree limitations of Crystal reports. Crystal can’t generate Group Tree information based on information within subreports. However, using this technique you can generate Group Tree information as PDF bookmarks based on information from both main as well as subreports!

There are 2 main steps in the process:

Visual CUT runs the report and, because the report has special UFL formulas, the PDF_Bookmarks.txt file gets populated with bookmark information,
Visual CUT export the report to PDF, detects the presence of PDF_Bookmarks.txt and uses it to generate the bookmarks in the exported pdf file.

If you are interested in using this functionality, I can e-mail you a sample report (demonstrating the formulas needed to generate the text file information). I can also e-mail you download instructions for evaluating CUT Light (UFL allowing Crystal formulas to create and add data to text files).

Adding Bookmarks Using Crystal Formulas as Tags [New Approach]

Using a command line argument, you can instruct Visual CUT to look for invisible tags inside the pdf file (Crystal formulas with font color set to background color) and to use their content to generate bookmarks. Compared to the old approach (described in the previous section), this new technique has several advantages:

1. The bookmarks link to the exact vertical location (on the linked page) where the rendered formula is located. In the old approach, bookmarks only pointed to at the top of the page.

2. You can easily generate bookmarks from within subreport and from any report section (not just Group Headers). For example, you can generate bookmarks from Detail Sections or Group Footers.

3. You can control the bookmark text color more completely (instead of a few color constants, you can specify any color using RGB (Red/Green/Blue) values.

4. You can control the expanded/collapsed state of each bookmark node

5. You can control the style of the bookmark node (Regular, Bold, Italics, Bold&Italic)

6. No need to worry about PageNumber resets, Keep Together, and WhilePrintingRecords properties that can cause headaches with the old approach. This is because the new approach doesn’t require specifying a page number and doesn’t depend on the evaluation time of the bookmark formulas.

7. You can avoid the need to use a command line argument by setting PDF_Bookmark_Tags_Default=True
under the [Options] section of DataLink_Viewer.ini (only applies to files < 100MB)
Visual CUT would then process bookmark tags within an exported PDF file.

Here's an example of the command line argument structure:

… "PDF_Bookmark_Tags:c:\temp\Sales in {@Year_Parameter}.pdf" Or

… "PDF_Bookmark_Tags:Source_pdf_file>target_pdf_file"

If only one pdf file is specified (as in top example), the source file becomes also the target file.

The Crystal formulas act as tags for controlling the level, vertical location, text, color, expand/collapse status, and style (regular/bold/italic) of the desired pdf bookmarks.

Setting Up a Crystal Report with pdf formula tags

You can download a sample report demonstrating the technique from:
www.milletsoftware.com/Download/Visual_CUT_PDF_Bookmark_Tags.rpt

And the resulting pdf file from:
www.milletsoftware.com/Download/Visual_CUT_PDF_Bookmark_Tags.pdf

The sample report uses 3 formulas to generate bookmarks:
{@Bookmark_L1} is placed in the Group Header level 1 to generate Product Type Name bookmarks with bold blue text. These level 1 nodes are expanded.

{@Bookmark_L2} is placed in the Group Header level 2 to generate Product Name bookmarks with bold text. These level 1 nodes are collapsed
.

{@Bookmark_L3} is placed inside the subreport in the Group Header level 1 to generate Customer Name. Bookmarks with text colored in different shades of red or green depending on the average time it takes to ship orders of that product to the customer.

The generated bookmarks link not only to the page where the formula was rendered, but also to the exact vertical position on that page (minus 20 millimeters to provide some margin). The bookmarks are created for each rendered instance of the formula. For example, if you place the formula in a Group Header 1 you will generate a bookmark for each Group at level 1.

The formula text must be rendered within the formula boundaries in a single line. Use small font sizes: 2 or even 1 to achieve this. Then, turn the font color to White (or same color as the background) to make the formula invisible or, keep the PDF_Tags_Delete_Default option in DataLink_Viewer.ini as True and Visual CUT would remove the tag text after processing it. See box below for Sample formula.

Notes:

1. As always, you can use field or formula names within the command line argument. The dynamic content of these fields/formulas would be substituted into the argument.
For example, {@Bookmark_L3} (inside the subreport) dynamically sets the color of the bookmark based on the performance of records in that node. Similarly, you may dynamically expand the bookmarks for groups with extreme performance measure to focus the manager’s attention on those areas.

2. Visual CUT can remove pdf processing tags from the pdf file after processing those tags. This is controlled by an entry called PDF_Tags_Delete_Default under the [Options] section of DataLink_Viewer.ini. By default, this option is set to True. To ensure all tags are removed, use the Replace() function in Crystal to change double quotes into single. For example, the expression for the title in PDF_Bookmark_Tags could be:
Replace({Customer.Customer Name},"""","'")

3. In Crystal, use non-proportional font for the tag formula (avoid Calibri and Bold/Italic)

Here is the commented {@Bookmark_L2} formula from the sample report at:
www.milletsoftware.com/Download/Visual_CUT_PDF_Bookmark_Tags.rpt

// Make the font size very small (2 or even 1 point) so content fits in a SINGLE line.

// The vertical location of the tag (minus default margin of 20 millimeters) controls the vertical
// location of bookmark page target. You can override the margin using an optional argument.

// The formula always starts with "#BM_Tag::" and ends with "#"

"#BM_Tag::" +

"2" + "||" + // Bookmark Level. During bursting, levels are shifted up automatically

Replace({Product.Product Name},"""","’") + "||" + // Bookmark Text (" >> ‘)

"-" + "||" + //"Expand Status: + to open the bookmark or - to collapse it.

"1" + "||" + // Text Style: 0=regular 1=Bold 2=Italic 3=Italic Bold

"0;0;0" + // Color as RGB: 3 numbers between 0 and 255 separated by ";"
// "||10" + // [Optional] Vertical Margin. Leave commented or uncomment to
// override the default of 20 millimeters.

"#"

Making PDF Files Accessible

Accessible pdf files make it easier for people with disabilities to read the document using assistive technology such as a screen reader. Using Visual CUT, you can generate an accessible pdf export by:

1. Ensuring the pdf export includes bookmarks.
This is typically achieved by Adding Bookmarks Using Crystal Formulas as Tags.

2. Using the command line argument of "PDF_Export_Options:Tagged"

3. Setting the natural language property of the pdf file using a command line like this:
"PDF_Properties:c:\temp\test.pdf>Ido> test>test>>MS>Visual CUT>Normal>1>100>/Lang::en-US"

You can test the accessibility of the resulting file using this web service: http://checkers.eiii.eu/en/pdfcheck/

Here is an example of test results:

Adding a Table of Content to a PDF File

You can generate a Table of Contents (TOC) inside a PDF file based on its Bookmarks.
Bookmarks are used during online viewing – a TOC is more useful for a printed document.

The command line argument structure is as follows:
… "PDF_TOC:1>40>11>6>5>2>pdf_file_path_and_name"

The parameters (after the ":") are separated by a ">" and are as follows:

1. Page where the TOC is inserted. 1 is a typical choice. Specify 999999 to insert as last page(s).
Note: you can specify two numbers separated by two vertical bars in cases where you want to offset the page numbers shown in the TOC. For example, 2||1 would insert the TOC in page 2 (after a title page perhaps) but refer to page #2 as page #1 and apply a similar offset to all other page numbers that are displayed in the TOC.

2. The right (& left) page margin (in millimeters). 40 is a typical choice
3. The font size (in points). 11 or 12 are typical choices.
4. The row spacing (in millimeters). 6 is a typical choice.
5. The indentation (in millimeters) added to each hierarchy level. 5 is a typical choice.
6. The Minimum Bookmark Level below which bookmarks are ignored. 2 is a typical choice.
7. OPTIONAL: The PDF file path & name (for example, c:\temp\other_file.pdf).
    Leaving this argument blank, would default processing to the file being exported.
    Providing a file name would direct processing to the specified file (even if it's not the
    exported PDF file.

Overriding the default "Table of Contents" Header Text
You can control the "Table of Contents" header text by adding/updating the [Text_Change] section in the DataLink_Viewer.ini file. For example:

[Text_Change]

Table of Contents=Table des matières

Table of Contents (cntd)=Table des matières (suite)

Notes:

· In DataLink_Viewer.ini, find and set this entry to True: PDF_Bookmark_Tags_Default=True

· If you enter no text after the equal sign, Visual CUT will suppress the header text.

· A "Table of Contents" (or the equivalent text as per the section above) is set to the 1^st page where the Table of Contents was inserted (regardless of the page number specified by you).

· Visual CUT assigns the top level of the TOC a bold font and a slightly larger row spacing and assigns level 3 and below a smaller font and a smaller row spacing.

· If the TOC requires more than 1 page, Visual CUT inserts additional pages for the TOC.

· The TOC rows (just as Bookmarks) are linked to the specified page so clicking on a TOC row takes you to that page. Regardless of the number and location of the inserted TOC pages, all page links (bookmarks and TOC rows) are adjusted accordingly.
The process takes care of generating a bookmark for the Table of Contents.

Advanced Table of Content Options

You can add page header images and gain fine control of font type, font size, font color, row spacing, bullets, indents, page orientation, and vertical page margins for the Table of Content by specifying these options in a [PDF_TOC] section inside DataLink_Viewer.ini.

For example, the following section starts by specifying vertical page margins for the first and continued Table of Content pages. It then specifies the images (with web hot links) to be inserted at the top of these pages. The rest of the items control font type, size, color, bullets, spacing, and indentation for each level in the Table of Content hierarchy.

[PDF_TOC]

// the Page_Margin_Top entry is required to enable this functionality

Page_Margin_Top=50

Page_Margin_Top_Continued=30

Page_Margin_Bottom=30
Page_Orientation=Portrait

// elements are: Left>Top>Width>Height>web link>image file>border (0=no border, 1=border)
// Left, Top, Width and height are all in millimeters. Left & Top are relative to top corner of the page

Top_Image_1st=0>0>216>40>http://www.MilletSoftware.com>C:\temp\header.jpg>0

Top_Image_Continued=0>0>216>20>http://www.milletsoftware.com/Visual_CUT.htm>C:\temp\VC.jpg>0

// True Type font specified as TT||Font Name||point size||Style: Regular/Bold/Italic/BoldItalic||RGB color

Default_Font=TT||Garamond||11||Regular||0;0;0

// Standard font specified as:

// = ST||Font Name: Helvetica/Courier/TimesRoman||point size||Style: Regular/Bold/Italic/BoldItalic||RGB color

Header_Font=TT||Garamond||16||Bold||16;78;139

Level_1_Font=TT||Garamond||12||Bold||225;0;0

Level_1_Row_Spacing=8

Level_1_Bullet=

Level_1_Bullet_Spaces=

Level_1_Indent=

Level_2_Font=TT||Garamond||11||Regular||0;0;0

Level_2_Row_Spacing=6

Level_2_Bullet=149

Level_2_Bullet_Spaces=3

Level_2_Indent=1

You can see a sample pdf generated using these options at:
www.MilletSoftware.com\Download\VC_PDF_Table_of_Contents_Sample.pdf

To override the settings above for a specific report, create a similar section and call it:
[PDF_TOC_YourReport.rpt]

Note: you can use field or formula names within the ini entry values, just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT. The dynamic content of these fields/formulas would be substituted into the ini values. For example, this allows a different image to be used for the Table of Contents header depending on data in the report.

Adding Page Numbers to a PDF File

You can instruct Visual CUT to add page numbers to the exported PDF file. This is useful when also adding a Table of Contents (as described above) since in such a case the page numbers from Crystal would be wrong. The command line argument structure is as follows:
… "PDF_PAGE_N:2>10>10>11>Bottom>Center>Page_NofM>pdf_file>TimesBold"
or
… "PDF_PAGE_N:2>10>10>11>Bottom>Center>Page_NofM>pdf_file>TT||Garamond||Bold||225;0;0"

The parameters (after the ":") are separated by a ">" and are as follows:

1. Starting with Page: 2 is used in cases where the 1^st title page shouldn’t be numbered.
* specify two numbers separated by || (N||M) to start page numbering on page N with the number M. For example, 2||1 would start numbering on page 2, but with the number 1.
* specify 3 numbers separated by || (N||M||X) to start page numbering on page N with the number M, but skip the last X pages. For example, 3||2||1 would start numbering on page 3, with the number 2, but skip 1 last page.

2. Horizontal page margin (in millimeters). Doesn’t apply to Centered layouts. 10 is typical.

3. Vertical page margin (in millimeters). 10 is typical.

4. The font size (in points). 11 or 12 are typical.

5. The vertical position on the page (Top or Bottom). Bottom is typical.

6. The horizontal position on the page (Left, Center, or Right). Center is typical.

7. The format (N, Page_N, or Page_NofM). Page_NofM is typical (e.g., Page 3 of 210).

8. OPTIONAL: The PDF file path & name (for example, c:\temp\other_file.pdf).
Leaving this argument blank, would default to processing the file being exported.
Providing a file name would process the specified file.

9. OPTIONAL: The font type (default is Helvetica).
Possible font types:

Courier, CourierBold, CourierBoldItalic, CourierItalic

Helvetica, HelveticaBold, HelveticaBoldItalic, HelveticaItalic

    TimesRoman, TimesBold, TimesItalic, TimesBoldItalic
    * or * any TrueType Font specified as 4 elements separated by || like this::
    TT||FontName||Style||Red;Green;Blue
    TT constant indicating this is a True Type font (target machine should have it installed)
    Font Name such as Garamond
    Style: Regular, Bold, Italic, or BoldItalic
    Color as RGB: 3 numbers between 0 and 255 separated by ";"
        Black=0;0;0 Maroon=225;0;0 etc. (see RGB #s at: http://web.njit.edu/~kevin/rgb.txt.html )
    For example: TT||Garamond||Bold||225;0;0

Adding Text to a PDF File

You can instruct Visual CUT to add text to PDF pages. A typical scenario is date stamping, adding content after merging files, or targeting files generated by other processes. The argument structure is as follows:
… "PDF_Add_Text:2>10>10>11>Bottom>Center>{@SomeText}>pdf_file>TimesBold"
or
… "PDF_Add_Text:2>10>10>11>Bottom>Right>{Customer.Name}>pdf_file>TT||Garamond||Bold||225;0;0"

The parameters (after the ":") are separated by a ">" and are as follows:

1. Starting with Page: 2 is used in cases where the 1^st title page shouldn’t be numbered.
    l Specify 2 numbers separated by || (N||M) to start adding the text on page N but skip the last M pages.
       For example, 3||1 would start numbering on page 3, but skip 1 last page.
    l To target a single page, specify a large M value. For example 3||9999

2. Horizontal page margin (in millimeters). Doesn’t apply to Centered layouts. 10 is typical.

3. Vertical page margin (in millimeters). 10 is typical.

7. The Text to add.

8. The PDF file path & name (for example, c:\temp\other_file.pdf).

9. The font type. Possible font types:

Courier, CourierBold, CourierBoldItalic, CourierItalic

Helvetica, HelveticaBold, HelveticaBoldItalic, HelveticaItalic

· You can use multiple PDF_Add_Text arguments in a single command line.
Or simply separate multiple directives with "^^".

· As usual, you can refer to field/formula names.

Adding Web/File/email Hotspot to a PDF File

You can instruct Visual CUT to add a rectangular hotspot to a pdf file that acts as a web browser link to a web URL, email address (mailto), or a file on your local machine.

The command line argument structure is as follows:

…"PDF_LinkToWeb:c:\test.pdf>1>99>40>60>50>10>http://www.MilletSoftware.com>>>0"

The parameters (after the ":") are separated by 10 ">" and are as follows:

1. pdf file to which the hotspot would be added.

2. Starting with Page

3. Ending with Page: use a very large number if you want to apply the hotspot to all pages and you don’t know how many pages are in the document).

4. Left (in millimeters): The left edge of the hotspot rectangle (relative to top left corner of the page).

5. Top (in millimeters). The top edge of the hotspot rectangle (relative to top left corner of the page).

6. Width (in millimeters). The width of the hotspot rectangle

7. Height (in millimeters). The height of the hotspot rectangle.

8. Link. for example: "http://www.MilletSoftware.com" or "mailto:ido@MilletSoftware.com" or "file:///c:\\temp\\helloworld.bat"

9. Text: the text to add inside the hotspot rectangle (the text font size will be adjusted to automatically fit the text inside the rectangle area. Leave blank (as demonstrated above) if you don’t want to add any text. Do not include the character ‘>’ inside the text.

10. Text Vertical Alignment: Top, Center, or Bottom. Leave blank (as demonstrated above) if you don’t want to add any text.

11. Border: 1 for visible border, 0 for no border (default for missing or invalid value is 1)

Notes:

You can have multiple PDF_LinkToWeb command line arguments in a single command line.

You can use field or formula names within the command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT. The dynamic content of these fields/formulas would be substituted into the command line argument. For example (all in one line):
…"PDF_LinkToWeb:{@pdf_file}>1>99>40>60>50>10>{@Link}>{@Text}>Center>1"

Adding an Images with an Optional Hotspot to a PDF File

You can instruct Visual CUT to add an image with an optional hotspot (a link to a web page, email, or a local file. This can be useful when you wish to use a button image as a hotspot indication or when you wish to add a company logo to a range of pages.

The command line argument structure is as follows:

…"PDF_AddImage:c:\test.pdf>1>99>40>60>50>10>http://www.IBM.com>c:\temp\IBM.png>0"

The parameters (after the ":") are separated by 10 ">" and are as follows:

1. pdf file to which the hotspot would be added.

2. Starting with Page

6. Width (in millimeters). The width of the hotspot rectangle (image will be resized to fit)

7. Height (in millimeters). The height of the hotspot rectangle (image will be resized to fit)

8. Link. for example: "http://www.MilletSoftware.com" or "mailto:ido@MilletSoftware.com" or "file:///c:\\temp\\helloworld.bat" or "c:/temp/my_media_file.wmf"
Leave blank if you don’t want the image to act as a hotspot.

9. Image File: the path and name of the image file. You can use images of the following types:
BMP, TIFF, JPEG, PNG, GIF, WMF and EMF.

10. Border: 1 for visible border, 0 for no border (default for missing or invalid value is 1)

Notes:

You can have multiple PDF_LinkToWeb command line arguments in a single command line.

You can use field or formula names within the command line argument. The dynamic content of these fields/formulas would be substituted into the argument. For example (all in one line):
…"PDF_AddImage:{@pdf_file}>1>99>40>60>50>10>{@Link}>{@Logo}>1"

You can use this site to create .png button images with text of your choice:
http://nyphp.org/content/presentations/GDintro/gd26.php

Adding Links to Files/URL/eMail/Pages Using Formulas as Tags

Using a command line argument, you can instruct Visual CUT to look for invisible tags inside the pdf file (Crystal formulas with font color set to white) and to replace them with links (hotspot with optional image) to other files, web urls, email, or another PDF page. Here's an example of the command line argument structure:

… "PDF_Link_Tags:c:\temp\Sales in {@Year_Parameter}.pdf" Or

… "PDF_Link_Tags:Source_pdf_file>target_pdf_file"
If only one pdf file is specified (as in the top example), then the source file becomes also the target file. The Crystal formulas act as tags for controlling the location, size, border, image, and behavior of the desired links.

Setting Up a Crystal Report with pdf field tags

You can download a sample report demonstrating the technique from:
www.milletsoftware.com/Download/Visual_CUT_9_PDF_Link_Tag.rpt
Sample pdf output is at: www.milletsoftware.com/Download/Link_Test.pdf

The sample report uses a {@PDF_Link_Tag_Sample} formula to demonstrate a File link to an image file and a {@PDF_Link_To_Page_N_Plus_1} formula to demonstrate a Page link to another page in the same document. There are no restrictions on the number or names of the formulas you can use.

The location of the link tag formula on the report layout controls the location of the file links it would generate. The links would be created for each rendered instance of the formula. For example, if you place the formula in a Group Footer you will generate a link for each Group.

The location (top left corner) of the rendered formula instances controls the location of the hyperlink in the pdf file. The width and height of the hyperlink hotspot is controlled by the formula text, not by the formula field size.

The formula text must be rendered within the formula boundaries in a single line. Use very small font sizes (even 2 or 1) to achieve this. Set font color to White to hide the formula or, if you keep the PDF_Tags_Delete_Default option as True, Visual CUT removes the tag text after processing it.
The following page demonstrates (and comments on) the structure of the required formula text.

Notes:

As always, you can use field or formula names within the command line argument. The dynamic content of these fields/formulas would be substituted into the argument.
Also, Report/Group L1 tags may refer to fields/formulas (e.g. "#Link_Tag::{@Tag_GF1_Info}#"). But keep in mind that the referenced field/formula must be placed on Report or Group-level section to be recognized. And also remember that if you are not bursting the report, you should not be referencing only Report-level fields/formulas.

The hyperlink hotspot rectangle created by Visual CUT doesn’t provide any text. You can provide the text within the Crystal report or you can include a directive to fit an image into the hotspot rectangle. This can provide an intuitive button for the user to click & follow the hyperlink. There are several free web sites that generate.png button images with text of your choice.

In Crystal, use non-proportional font for the tag formula (avoid Calibri and Bold/Italic).
Avoid Paragraph spacing option of "Exact".

Visual CUT can remove pdf processing tags from the pdf file after processing those tags. This is controlled by an entry called PDF_Tags_Delete_Default under the [Options] section of DataLink_Viewer.ini. By default, this option is set to True.

Formula Example from the Sample Report

Here is the {@PDF_Link_Tag_Sample} formula from the sample report at:
www.milletsoftware.com/Download/Visual_CUT_9_PDF_Link_Tag.rpt

// Make the font size very small (2 or even 1 point) so that the whole

// content displays within the formula boundaries in a SINGLE line.

// The location (top left corner) of the rendered formula instances

// control the location of the link.

// link to pdf file in same folder: "file name"

// link to non-pdf file in same folder: ".file name"

// link to non-pdf file in 1-level higher folder: "..file name"

// The formula always starts with "#Link_Tag::" and ends with "#"

"#Link_Tag::" +

"PDF" + "||" + // Link Type: "PDF" for links to a page in another pdf file.
// "Page" for links to a page in same pdf file

// "File" for links to other file types.

// "MAIL" for mailto.

// "HTTP" for web link. Instead of file, specify URL (e.g. www.abc.com)
// "" (blank) for other types of links (e.g. Tel:)

{Product.Product Name} + ".pdf" + "||" + // The file/url to link to. Blank if Link Type = "Page"
"" + "||" + // [optional] file to test it exists, and abort otherwise.

"1" + "||" +   // page destination in target file (ignored if not pdf). Zoom is inherited.
                    // to specify both PageN & Zoom,
                    // use a ";" separator: "1;100" (page 1, zoom 100%)
                    // -1 zoom value = Fit Page
                    // -2 zoom value = Fit Width

"70;20" + "||" + // hot spot boundaries in points: width;height

// (note: if 4 arguments are provided,

// they are treated as: shift_x;shift_y;width;height)

"1" + "||" + // New Window Option. 1: opens target pdf file in a new Window

// 0: opens target in current window)

"0" + "||" + // Border Option: 1: Show Border. 0: No border

"c:\temp\Click_to_View.png" + // [optional] path & name of Image File to fit

// You can use images of the following types:

// BMP, TIFF, JPEG, PNG, GIF, WMF and EMF.

"#"

Embedding Files as Attachments inside a PDF File

Note: in most cases, you should skip this page. The following section describes a more powerful technique that not only embeds files, but also provides links to them.

Using a command line argument, you can instruct Visual CUT to embed files as internal attachments inside a given pdf file. The command line argument structure is as follows:

… "PDF_Embed:PDF_File<<file1::Mime Type::title||file2::Mime Type::title…"

The parameters (after the ":") begin with

1. PDF_File: The PDF file within which you wish to embed files.

Then, after a "<<" separator, you can specify any number of embedded files separated by "||"
Each embedded file is specified as 3 arguments separated by "::"

1. File Path and Name
Note: If a path is not specified, the path from a previous embedded file is used

2. The MIME Type of the file. For example, application/pdf or image/jpg, etc.
see http://www.w3schools.com/media/media_mimeref.asp for a list of MIME types
If you leave blank, Visual CUT would detect the MIME type based on file extension.

3. The Title to uniquely identify the embedded file.

For example:
"PDF_Embed:c:\temp\test.pdf<<c:\temp\INV.pdf::application/pdf::Invoice||Sig.jpg::image/jpg::Signature"

Important Note: you can use field or formula names within the command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT). The dynamic content of these fields/formulas would be substituted into the command line argument.

Adding Links and Embedded Files Using Crystal Formulas as Tags

A command line argument can instruct Visual CUT to look for tags inside the pdf file (text from Crystal formulas). When a Link_Tag with EMBED directive is found, the file specified in the tag is embedded inside the pdf file and a hotspot area designated with an icon, in the location of the tag, is created to link to that embedded file. Any file can be embedded, and embedded pdf files can have their own embedded files, which supports multi-level drill-down scenarios. See video demo: www.milletsoftware.com/Download/Visual_CUT_PDF_Embed/Visual_CUT_PDF_Embed.html

This allows you to deliver a PDF with drill-down or added content that the user can bring up by double-clicking a link. This is like on-demand subreports, except that:
1. the content has been pre-rendered
2. the subreports can contain their own subreports
3. the embedded files can be any file type (pdf, excel, Word, image, audio, video ...)
4. the container pdf can be password protected and/or digitally signed by Visual CUT

If the embedded file is a pdf file, PDF Xchange Viewer opens it as new tab inside the main pdf. Other viewers, such as Acrobat Reader 9 open the embedded pdf in a new viewer window.

Here's an example of the command line argument structure:

… "PDF_Link_Tags2:c:\temp\Sales in {@Year_Parameter}.pdf"

… "PDF_Link_Tags2:Source_pdf_file>target_pdf_file"
If only one pdf file is specified the source file becomes also the target file.

Setting Up a Crystal Report with Link_Tag Formulas

You can download a sample report demonstrating the technique from:
www.milletsoftware.com/Download/Visual_CUT_PDF_Link_Tag_File_Embed.rpt

Sample pdf output is at: www.milletsoftware.com/Download/Visual_CUT_PDF_Embedded_Drill_Down_Sample.pdf

The sample report uses a {@PDF_Link_Tag_1} formula in Group Header 1 to demonstrate a file embedding link. There are no restrictions on the number or names of the formulas you can use.

The location of the link tag formula on the report layout controls the location of the hotspot and link icon it create for each rendered instance of the formula. The top left corner of the rendered formula instance controls the location of the hyperlink in the pdf file. The width and height of the hyperlink hotspot is controlled by the formula text, not by the formula field size.

The formula text must be rendered all within the formula boundaries in a single line. Use very small font sizes: 2 or even 1 to achieve this. Then, turn the font color to White to make the formula invisible or, if you keep the PDF_Tags_Delete_Default option in DataLink_Viewer.ini as True, Visual CUT removes the tag text after processing it.

The following page demonstrates (and comments on) the structure of the required formula text.

As always, you can use field or formula names within the command line argument. The dynamic content of these fields/formulas would be substituted into the argument.

Formula Example from the Sample Report

Here is the {@PDF_Link_Tag_Sample} formula from the sample report at:
www.milletsoftware.com/Download/Visual_CUT_PDF_Link_Tag_File_Embed.rpt

// Make the font size very small (2 or even 1 point) so that the whole

// content displays within the formula boundaries in a SINGLE line.

// The location (top left corner) of the rendered formula controls the location of the link.

// The formula always starts with "#Link_Tag::" and ends with "#"

"#Link_Tag::" +

"Embed" + "||" + // Link Type. Use lower case "embed" to ignore (skip) missing files

"c:\temp\Sales for " + {Product_Type.Product Type Name} + ".pdf" + "||" + // The file to embed

"" + "||" + // MIME Type of the file to embed. Leave blank for automatic identification

"Double-Click to See" + "||" + // Hotspot Tooltip Header Line

"Detail for " + {Product_Type.Product Type Name} + "||" + // link description (tooltip 2^nd line)

"18;18" + "||" + // hot spot boundaries in points: width;height
// (4 arguments instead of 2 are treated as: shift_x; shift_y; width; height)

"0" + "||" + // Icon Option for the link:
// 0 = Standard Icon (push-pin)

// 1 = 28x28 disk image

// 2 = No icon

// 3 = Graph

// 4 = Paperclip

// 5 = Tag
// 6 = Solid white rectangle

// You may add 1000 to 1100 for transparency of 0% to 100%
// the last digit indicates the icon. 1074 = 70% transparent Paperclip

"" + // [optional] Image File to fit as background e.g. c:\temp\file.png

//supported types: BMP, TIFF, JPEG, PNG, GIF, WMF and EMF.

"#"

The sample PDF:
www.milletsoftware.com/Download/Visual_CUT_PDF_Embedded_Drill_Down_Sample.pdf

demonstrates a case of embedded pdf files within embedded pdf files. It was created using a batch file with 3 command lines:
1st line bursts a report to generate the lowest-level pdf files (one file for each Product).

2nd line bursts a report to Product Type PDFs and embed in them the Product PDFs.

3rd line exports the Master PDF and embeds in it the Product Type PDFs.

"C:\Program Files\Visual CUT 11\Visual CUT.exe" -e "C:\temp\DrillDowns2_By_Product.rpt"

"C:\Program Files\Visual CUT 11\Visual CUT.exe" -e "C:\temp\DrillDowns1.rpt"
"PDF_Link_Tags2:c:\temp\Sales for {Product_Type.Product Type Name}.pdf"

"C:\Program Files\Visual CUT 11\Visual CUT.exe" -e "C:\temp\Master.rpt"
"PDF_Link_Tags2:c:\Temp\Visual_CUT_PDF_Embedded_Drill_Down_Sample.pdf"

Note: the PDF_Compress command line argument can reduce the resulting pdf file size.

Generating ZUGFeRD Invoices

Visual CUT can generate PDF invoices following the ZUGFeRD electronic data exchange standard. It embeds the XML file (providing the invoice data as machine readable format) and also sets up the document as PDF/A-3b according to the ZUGFeRD specification.

You achieve this by using the same PDF_Link_Tags2 command line argument as above. For example: "PDF_Link_Tags2:c:\temp\invoice.pdf>c:\temp\ZUGFeRD_invoice.pdf".
You also use the same "#Link_Tag:: …" content in the tag formula but instead of 'Embed' you use 'Embed_ZUGFeRD' as shown in this example:

"#Link_Tag::" +

"Embed_ZUGFeRD" + "||" + // Link Type

"c:\temp\ZUGFeRD-invoice.xml" + "||" + // The file to embed

"" + "||" + // MIME Type of the file to embed. Leave blank for automatic identification

"Double-Click to Open" + "||" + // Hotspot Tooltip Header Line

"Invoice" + "||" + // link description

"18;18" + "||" + // hot spot boundaries

"0" + "||" + // Icon Option

"c:\temp\Yellow_BackGround.png" + // [optional] Image File to fit as background

"#"

Adding Links to Files by Detecting File References in PDF Text

Using a command line argument, you can instruct Visual CUT to look for file references in the text of a pdf file and automatically add colored hotspots over these file references that link to the specified files. Here's an example of the command line argument structure (all in 1 line):

… "PDF_Auto_File_Link:c:\In.pdf>>.>>.pdf;.mp3>> (>>0>>)>>255;255;0>>True>>c:\Out.pdf"

The parameters (after the ":") are separated by ">>" and are as follows:

1. Source pdf file to process

2. Base Path where the linked files are found. There are several options here:
    a) no base path (leave blank) if the file references in the pdf are specified with full paths
    b) simple base path (e.g., c:\my archive\) to prefix any file reference
    c) relative path: . (for same folder as the pdf file) .. (for parent folder), etc.

3. File Extensions to process (separated by a semi-colon).

4. Start Text indicating start of file reference. In the example above, file references are assumed to always start after a (

5. Number of characters to include in the file reference from the Start Text. In the example above, no text (0 characters) from the Start Text is included. However, there can be many cases where some text should be included. For example, if the Start Text is (c:\ then the number of characters to include should be 3.

6. End Text indicating end of a file reference. In the example above, file references are assumed to always end with a ) (note: can be left blank)

7. Color of Hot Spot in RGB Values (e.g., yellow: 255;255;0). Note: drawn with 80% transparency, so use strong colors. (see RGB #s at: http://web.njit.edu/~kevin/rgb.txt.html )

8. True/False: Should Visual CUT check for file existence of the file references and generate a failure message listing missing files (note: the output file with the generated links is generated, but the process will report a failure and further actions such as emailing would be aborted).

9. The Output PDF File. If left blank, the source pdf file would be updated.

Notes:

- Machine must have at least one printer installed

- Here is an example of yellow hotspots & links generated for file references detected inside a pdf file:

Detecting Additional File References Using Wild Card Tokens

The approach above relies on start and end strings. However, there are scenarios where the text to be detected doesn’t have consistent start and end strings. Instead, the target text may have a predictable structure such as DOC##### where the text always starts with ‘DOC’ and continues with 5 digits (e.g., ‘DOC01207’).

When a command line already has a PDF_Auto_File_Link argument, you can direct Visual CUT to search for and generate links for additional targets by adding a command line argument such as this:
…"PDF_Auto_File_Link_Tokens:..\Multimedia\MM#####.wmv||..\Documents\DOC#####.pdf"

Alternatively, you can set this as a global option by adding the following entry in DataLink_Viewer.ini (under the [Options] section):

PDF_Auto_File_Link_Tokens=..\Multimedia\MM#####.wmv||..\Documents\DOC#####.pdf

Additional target are separated by ‘||’ and include the relative or absolute path to the target files.

The process attempts to locate text targets with the specified file extension as well as without it. In the examples above, the first additional target is any text containing a pattern matching:
a) MM#####.wmv (for example MM12345.wmv)

Or,
b) MM##### (for example MM12345)

Note: the only wild cards allowed for this option are:

1. # : matched any single digit in that position

2. ? : matches any single character (including digits) in that position

Adding Digital Signature to a PDF File

You can instruct Visual CUT to add a digital signature to a PDF file. The command line argument structure is as follows (as always, it must be all in one line):

…"PDF_Sign:Input_File>>Output_File>>Open_Password>>Sig_Field
… >>pfx_File>>pfx_Password>>Reason>>Location>>Contact"

The parameters (after the ":") are separated by ">>" and are as follows:
1. Input File: path and name of the pdf file to sign
2. Output File: leave blank if you wish to overwrite the original pdf file

3. Open_Password: if the pdf file is not password protected, leave this option blank
4. Signature Field Name: if the field doesn’t already exist, Visual CUT creates it
5. pfx File: path and name of the PKCS#12 certificate/private key file (.pfx file)
6. pfx_Password: password to open the pfx file
7. Reason: optional text indicating reason for signing
8. Location: optional text indicating where the document was signed (e.g., New York)
9. Contact: optional text indicating contact information for the signer

Notes:

As always, you can use field or formula names within the command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT. The dynamic content of these fields/formulas would be substituted into the command line argument.

Using a Digital Certificate Token

To sign using a usb token (e.g. AATL digital certificate signature token from Globalsign), replace the pfx File argument with the cn (Subject Name) of your certificate
(e.g. Development). And leave the pfx_Password argument as blank.

To avoid repeated prompts for token password, set the token options to remember the password. For example, using SafeNet Authentication Client Tools, go to Settings, Client Settings, Advanced tab, and set the option of Automatic logoff after token inactivity to 'Never'. See image.

Redacting Text in a PDF File

To redact text in a PDF file, the command line argument structure is as follows (as always, it must be all in one line):

…"PDF_Redact:Input_File>>Output_File>>Open_Password>>Target_Strings
… >>Target_Wild_Cards>>Target_Regular_Expressions>>
… >>Color>>Options "

The parameters (after the ":") are separated by ">>" and are as follows:
1. Input File: path and name of the source pdf file
2. Output File: leave blank if you wish to overwrite the original pdf file

3. Open_Password: if the pdf file is not password protected, leave this option blank
4. Target_Strings: literal strings separated by ‘||’
5. Target Wild Cards: wild card expressions separated by ‘||’
6. Target Regular Expressions: separated by ‘||’
7. Color: e.g. Black or Silver
8. Options: leave blank (for future use)

Example: "PDF_Redact:C:\temp\Source.pdf>>C:\temp\Redacted.pdf>>
>>trump||clinton>>???@gmail.com>>\d{3}-?\d{2}-?\d{4}>>Silver>>"

See Video Demo. See Sample image.

Notes:

1. As always, you can use field or formula names within the command line argument.

2. Regular Expressions are more powerful and more predictable than wild cards.
Here is a good resource for experimenting with Regular Expressions.

3. The redaction provided by Visual CUT is true redaction, as opposed to fake redaction. Visual CUT truly removes the underlying text as opposed to just drawing black boxes over it. Read about how lawyers used fake redaction by mistake.

Highlighting Text in a PDF File

To highlight text in a PDF file, the command line argument structure is as follows
(as always, it must be all in one line):

…"PDF_Highlight:Input_File>>Output_File>>Open_Password>>Target_Strings
… >>Target_Wild_Cards>>Target_Regular_Expressions>>
… >>Color>>Options "

The parameters (after the ":") are separated by ">>" and are as follows:
1. Input File: path and name of the source pdf file
2. Output File: leave blank if you wish to overwrite the original pdf file

Example: "PDF_Highlight:C:\temp\Source.pdf>>C:\temp\Redacted.pdf>>
>>trump||clinton>>???@gmail.com>>\d{3}-?\d{2}-?\d{4}>>Silver>>"

See Sample pdf with resulting highlights.

Notes:

1. As always, you can use field or formula names within the command line argument.

2. Regular Expressions are more powerful and more predictable than wild cards.
Here is a good resource for experimenting with Regular Expressions.

3. The Sample pdf provides a table of colors and names.

4. The color highlights are actually pdf annotations that the recipient can click to add notes to (and others can reply to).

Encrypting & Protecting a PDF File

You can instruct Visual CUT to protect (using advanced 128/256-bit AES encryption) the exported (or any other) PDF file. The command line argument structure is as follows:

… "PDF_PROTECT:Owner_Pass>User_Pass>1>1>0>1>1>pdf_file_path_and_name"

The parameters (after the ":") are separated by a ">" and are as follows:

1. Owner_Password: Keep this password to yourself. It provides full control over the PDF file.

2. User_Password: Give this password to the recipient. The following arguments control
     what the user can do with the PDF file.
     NOTE: If you wish to protect the file but not prompt the user for a Password, leave the
     User_Password option blank.
     For example: "PDF_PROTECT:Owner_Pass>>1>1>0>1>1>"

3. Allow User to Print the File: (1=Yes, 0=No) 1 is typical.
4. Allow User to Copy Text & Images from the File: (1=Yes, 0=No) 1 is typical.
5. Allow User to Edit/Change the File: (1=Yes, 0=No) 0 is typical.
6. Allow User to Add Notes to the File: (1=Yes, 0=No) 1 is typical.
7. Allow User to Print in Full Resolution: (1=Yes, 0=No) 1 is typical.
Setting this to zero would force low-resolution printing, preventing the document from being
distilled into a new unrestricted PDF document.

8. OPTIONAL: The PDF file path & name (for example, c:\temp\other_file.pdf).
    Leaving this argument blank, would default to processing the file being exported.
    Providing a file name would direct processing to the specified file (even if it's not the
    exported PDF file.
9.   OPTIONAL: Allow user to Fill Form Fields (if blank, assigned same value as #5 above)

10. OPTIONAL: Allow Copy for Accessibility (if blank, assigned same value as #4 above)
11. OPTIONAL: Allow user to assemble document (if blank, assigned same value as #5 above)
12. OPTIONAL: New PDF file path & name (for example, c:\temp\protected.pdf)

      When left blank, the protected version is saved under the original file path & name.
      Specify a new file here if you wish to retain the original unprotected version.
-- option below is new in 6.4002 ---
13. OPTIONAL: Encryption Strength:   128 = Default 128-bit AES (requires Acrobat 7 or later)
                        256 = 256-bit AES (requires Acrobat 9 or later), 256B (requires Acrobat X or later)
for example:
   "PDF_PROTECT:123>{@Pass}>1>1>0>0>1>c:\test.pdf>1>1>0>c:\protected.pdf>256"

Note: you can use field or formula names within the command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT. The dynamic content of these fields/formulas would be substituted into the command line argument. Among other things, this allows you to easily protect individual PDF exports with different passwords for each group. For example (all in one line):
…"PDF_PROTECT:my_pass>{@Emp_Pass}>1>1>0>1>1>c:\{@Year} Archive\Sales
For {Emp_Name} in {@Month_Name}.pdf"

Merging PDF Files

Using a command line argument, you can instruct Visual CUT to merge any number of PDF files. While each Crystal report is limited to a single paper orientation (either portrait or landscape), this feature allows you to combine multiple report outputs even if they have different paper orientations. The command line argument structure is as follows:

… "PDF_MERGE:PDF_File_List>PDF_File_Target"

The parameters (after the ":") are separated by a ">" and are as follows:

1. PDF_File_List: comma separated list of the source files in the order they should be merged.
    If all source files share the same folder, you may specify the full path just for the first file.
    As discussed in the next few pages, you can use wild cards, file lists in text files, and
    dynamic references to specify the files to be merged.

2. PDF_File_Target: the file path & name for the resulting merged PDF file.

3. Optional: BM_By_FileName add a bookmark for each file according to its file name.

4. Optional: leave blank or specify: M1 , M2, or M3
These codes direct Visual CUT to use alternative merge methods that differ in their speed and approach. If the default approach is not 100% successful, try one of these alternatives.

5. Optional: owner password in case one or more of the source files is password protected. All the encryption settings (owner and user passwords, and protection settings) of the last protected file in the list of source files would be applied to the resulting merged document.
Note: If the owner password is blank, specify VC_BLANK as the password.

Notes:

· If a source file is not found, a warning is written to Failure.log and the process continues after skipping that file.

· specifying the 4^th / 5^th optional argument requires that you also specify the 3^rd / 4^th arguments
(you can leave the 3^rd /4^th arguments blank as in: file list>target>>M2>>sesame). For example:
"PDF_MERGE:c:\temp\F1.pdf,F2.pdf,F3.pdf>c:\temp\Result.pdf>>M2>sesame"

· M2 is fast but may have problems with input files that have different page orientations.

· M3 should not be used when using the techniques described in "Specifying Bookmarks when Merging PDF Files" or in "Using the Merged File Names to Generate Bookmarks". It is useful in cases where M2 fails to handle certain malformed pdf files.

Dynamic File Names

You can use field or formula names within the command line argument. The dynamic content of these fields/formulas would be substituted into the command line argument.

For example, you can use Visual CUT to:
1. burst Sales information (Portrait) by Product Type into individually named pdf files
2. burst Returns information (Landscape) by Product Type into individually named pdf files
3. burst Complaints information (Portrait) by Product Type into individually named pdf files
    AND at that stage, use a command line argument to merge the 3 outputs for each Product
    Type, by using the following command line argument
    (Note: you should have no line breaks in the actual command line):

"PDF_MERGE:C:\temp\Sales_{@Prod_Type}.pdf,Returns_{@Prod_Type}.pdf,
Complaints_{@Prod_Type}.pdf>c:\temp\{@Prod_Type}.pdf"

If the current bursting cycle is for a Product_Type of "Gloves," the command line argument then gets processed as:

"PDF_MERGE:C:\temp\Sales_Gloves.pdf,Returns_Gloves.pdf,Complaints_Gloves.pdf>
c:\temp\Gloves.pdf"

You can then e-mail (or staple-print) the combined PDF file to each Product Type manager.

Using a Text File to Specify Files for Merging

If you have a text file containing the list of files to be merged, such as shown below, you can instruct Visual CUT to use the text within that file as the list of files to be merged using the key word "List_File:" followed by the path & name of the text file. For example:
"PDF_MERGE:List_File:c:\temp\FileList.txt>c:\temp\Result.pdf"

Using Wild Cards to Specify Files for Merging

You can also specify file names using wild cards.

For example, to send all pdf files in the current month folder under the current customer:

"PDF_MERGE:C:\VC_Export\{customer.cust_id}\{@Month}\*.pdf>c:\temp\Result.pdf"

and to merge all pdf files that start with the current Customer ID:

"PDF_MERGE:C:\VC_Export\{customer.cust_id}*.pdf>c:\temp\Result.pdf"

Controlling Merged Bookmark Colors

Note: these instructions are no longer needed. From November 9, 2009, Visual CUT keeps bookmark colors during merging of pdf files. Only for backward compatibility, the older functionality below is preserved.

During the merging process, bookmark colors (see Controlling PDF Bookmark Colors (& Text) on page 172) from the first file in the merged list are maintained. To apply colors to the merged bookmarks from any file, you include (anywhere) in the Bookmark Label the color constants of crMrgRed, crMrgBlue or crMrgGreen (note: case sensitive). Visual CUT would then set the color of the bookmark text accordingly (and remove the color constant text from the label).

Specifying Bookmarks when Merging PDF Files

During the merge process, you may want to add bookmarks for each input pdf file, so that the user can easily navigate the merged pdf file. To demonstrate how this can be done with Visual CUT, imagine you need to merge 4 pdf files:

2 pdf files with information about sales:
    Product_Sales.pdf
    Region_Sales.pdf

2 pdf files with information about profits:
    Product_Profits.pdf
    Region_Profits.pdf

You want the merged pdf to include bookmarks linking to the starting page of each of these 4 sections. The bookmarks should look like the example above.

Visual CUT allows you to specify, for each pdf file being merged, a chain of bookmark levels to which the content would be linked.

Let's assume you use the option to specify the list of files to merge using a text file (c:\temp\my_list.txt). The command line may look like this:

… "PDF_MERGE:List_File:C:\temp\my_list.txt>c:\temp\result.pdf"

and the c:\temp\my_list.txt would look like this:

c:\temp\Product_Sales{BM:Sales||+||1||225;0;0>>By Product||-||0||0;0;0}.pdf

c:\temp\Region_Sales{BM:Sales||+||1||225;0;0>>By Region||-||0||0;0;0}.pdf

c:\temp\Product_Profits{BM:Profit||+||1||225;0;0>>By Product||-||0||0;0;0}.pdf

c:\temp\Region_Profits{BM:Profit||+||1||225;0;0>>By Region||-||0||0;0;0}.pdf

The information about the top-level bookmarks associated with each file is embedded within an optional {BM: … } tag, just before the ".pdf" ending the file name.

Each node in the top-level bookmark chain is separated by >> and contains 4 elements separated by || (2 vertical bars):

1. Title: the text to appear as the label of the bookmark
2. Expand Status: + to open the bookmark or – to collapse it.
3. Style: 0=regular 1=Bold 2=Italic 3=Italic Bold
4. Color as RGB: 3 numbers between 0 and 255 separated by ";"
Black=0;0;0 Maroon=225;0;0 etc. (see RGB #s at: http://web.njit.edu/~kevin/rgb.txt.html )

So the first line in the file merges Product_Sales.pdf and link its starting page to a "Sales" bookmark (expanded, bold, Maroon) and, below that, a "By Product" bookmark (collapsed, regular, Black). The second file uses the same top node and adds a "By Region" Bookmark.
Notes:

If the top nodes in the chain already exist, only the lower new nodes would be created. This is why in the example above, the Sales and Profit nodes are each created only once.
If the merged pdf file contains bookmarks, they will be transferred under the lowest node in the specified node chain for the file.
The resulting bookmarks are detected by the PDF_TOC command line argument, so you can automatically create a table of contents based on them.
You can use field or formula names within the PDF_Merge command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT. You can even do the same with the content of the text file specifying the files to merge. The dynamic content of these fields/formulas would be used. In the case of specifying bookmarks during the merge process, this means that the title, style, and color of these bookmarks can be controlled via the Crystal report fields, parameters, and formula logic.

Using the Merged File Names to Generate Bookmarks

Particularly when using wildcards to merge files, but also when wishing to avoid the effort of manually specifying bookmark labels and styles, you can simply instruct Visual CUT to add bookmarks based on the file name of each merged pdf file.

To enable this functionality, you add a 3^rd part to the PDF_MERGE command line argument:

… "PDF_MERGE:c:\{@Branch}\*.pdf >c:\temp\{@Branch} Reports.pdf>BM_By_FileName"

As shown in the example above, you simply add >BM_By_FileName to the end of the command line argument.

In the example above, several reports may be bursted to different {@Branch} folders. The last report may include a PDF_Merge command line argument so that each bursting step for that report will also take care of merging all the pdf files in the currently processed Branch and add bookmarks based on the file names being merged.

Obviously, the bookmark labels do not include the path to the pdf file nor the ‘.pdf’ extension.

Using the Merged Folder & File Names to Generate 2-Level Bookmarks

If you specify multiple folders in your merge process, you may want to generate a 2-level bookmark structure whereby:
a) the bottom folder name sets the level-1 bookmark name and
b) the file name controls the level-2 bookmark name.

This is similar to the previous section except that instead of BM_By_FileName you need to specify BM_By_Folder_FileName like this:

…"PDF_Merge:c:\tmp\Accessories\*.pdf,c:\tmp\Bikes\*.pdf>c:\tmp\My.pdf>BM_By_Folder_FileName"

Here is the resulting bookmark structure:

Notes:
a) lowest-level folders specified explicitly in the list of files do NOT generate a bookmark if the first letter in the folder name is spelled with a lower-case letter in the argument (it doesn't matter if the first letter in the actual name of the folder is upper case).
b) lowest-level folders located via wildcard search (e.g. *.pdf) do NOT generate a folder bookmark if their name starts with a lower case letter.
c) wildcard searches are recursive, so sub-sub… folders are searched as well. But currently, lowest-level folders (regardless of how deep they are) simply become t1st-level bookmarks.

Using the Merged File Names to Generate Multi-Level Bookmarks

Imagine you need to merge 6 employee files into a PDF with 3-level bookmarks. However, you want to avoid using a text file to specify the multi-level bookmarks:

To do this, you embed the multi-level bookmark information inside the pdf file names like so:

The Bookmark information is contained within the [BM{…}] portion. You can use the rest of the text in the file name for other purposes. In the example above, the numbers at the start of the file name are used to ensure proper alphabetical sorting when using wildcards to specify the files to be merged. For example:
... "PDF_MERGE:c:\temp\0?? [BM{*.pdf>c:\temp\Merge_result.pdf>BM_By_FileName"

Each Bookmark level is specified inside a {…} and has 4 elements separated by a ^ character:

Merging 1-Page PDF Files into Layers in a Single PDF File

Using a command line argument, you can instruct Visual CUT to merge several PDF files into multiple layers inside a single pdf file. This is particularly useful for mapping applications where users wish to turn on or off the visibility of certain map layers.

Here is an example of such a merged file, opened in Adobe Acrobat reader with the visibility of layers 1 (Streets Layer) & 3 (Stores) turned on:

The command line argument structure is as follows:

… "PDF_MERGE_Files_to_Layers:PDF_File_List>PDF_File_Target"

The parameters (after the ":") are separated by a ">" and are as follows:

1. PDF_File_List: comma separated list of the source files in the order they should be merged.
If all source files share the same folder, you can specify the full path just for the first file.
If a source file is not found, a warning is written to Failure.log and that file is skipped.

2. PDF_File_Target: the file path & name for the resulting merged PDF file.

For example:
"PDF_MERGE_Files_to_Layers:c:\temp\File1.pdf,File2.pdf,File3.pdf>c:\temp\Result.pdf"

Dynamic File Names

As always, you can use field or formula names within the command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT.

Using a Text File to Specify Files for Merging

If you have a text file containing the list of files to be merged, such as shown below, you can instruct Visual CUT to use the text within that file as the list of files to be merged using the key word "List_File:" followed by the path & name of the text file. For example:
"PDF_MERGE_Files_to_Layers:List_File:c:\temp\FileList.txt>c:\temp\Result.pdf"

Controlling Layer Name & Visibility

By default, the name of each layer is set to its source file name (without the .pdf portion) and the visibility of each layer is turned on. You can override these default settings by embedding the desired information inside a {OCG: … } token as demonstrated by the text file sample above.

The OCG token is inserted just before the ".pdf" portion of each source file.

The token contains 2 elements separated by || (2 vertical bars):

1. Layer’s name
2. Layer’s initial visibility (True or False).

Printing PDF Files

Using a command line argument, you can instruct Visual CUT to print a PDF file. This is useful in combination with the previously discussed option of merging PDF files (see page 196).
It allows you to merge multiple reports, even if they use different page orientations, and then print and staple the combined output as a single print job.

PDF_Print

The command line argument structure is as follows:
… "PDF_PRINT:PDF_File>Printer_Name>Page_Scaling>Auto_Rotate_and_Center"

The parameters (after the ":") are separated by a ">" and are as follows:

1. PDF_File: The PDF file you wish to print.

2. Printer_Name: the Windows name of the printer.
Note: If you use "Default" as the printer name, the report gets printed to the default printer.

3. [Optional] Page Scaling: None, Fit, or Shrink (to fit paper size)

4. [Optional] Auto Rotate & Center: True or False

For example:
"PDF_PRINT:c:\temp\Result.pdf>\\myprintsrvr\LASER 02"

"PDF_PRINT:c:\temp\Result.pdf>\\myprintsrvr\LASER 02>Shrink>True"

Important Note: you can use field or formula names within the command line argument. The dynamic content of these fields/formulas would be substituted into the command line argument.
For example, after you burst and merge multiple reports into a single PDF file for each Product Type (as described in Merging PDF Files), you can print and staple the resulting PDF file for each Product Type using the following command line argument:
"PDF_PRINT:c:\temp\{@Product_Type}.pdf>\\myprintsrvr\LASER 02>Shrink>True"

If the current bursting cycle is for a Product_Type of "Gloves," the command line argument then gets processed as:
"PDF_PRINT:c:\temp\Gloves.pdf>\\myprintsrvr\LASER 02>Shrink>True"

and the combined output for just Gloves from 3 different reports (with different page orientations) would then be printed and stapled together. The process would then continue to print and staple the output for the next Product Type.

Notes:
To control number of copies printed, use the Print_Copies command line argument. If the dynamic value is zero, the printout would be skipped.
To control print quality/speed, use the PDF_Print_Mode command line argument.

Shared printers should be named like this: \\SEEMORE3\HP LaserJet P2035n
rather than like this: HP LaserJet P2035n on SEEMORE3

PDF_Clone_And_Print

You may need to print multiple copies within a single print job (perhaps you wish to staple all these copies together). In such cases you can use the PDF_Clone_And_Print argument.
It is identical to PDF_Print except for the addition of number of copies as the last element.

The command line argument structure is as follows:
…"PDF_Clone_And_Print:PDF_File>Printer_Name>Page_Scaling>
Auto_Rotate_and_Center>Copies"

For example:
"PDF_Clone_And_Print:\temp\Result.pdf>\\myprintsrvr\LASER 02>4"

"PDF_Clone_And_Print:\temp\Result.pdf>\\myprintsrvr\LASER 02>Shrink>True>4"

Important Note: you can use field or formula names within the command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT. The dynamic content of these fields/formulas would be substituted into the command line argument, including the number of copies.
For example:
"PDF_Clone_And_Print:\temp\Result.pdf>\\myprintsrvr\LASER 02>{@Copies}"

Printing PDF Files To Multiple Printer Trays

You can instruct Visual CUT to split the printout of a single PDF file to multiple printer trays. For example, you may want to print the first page of a pdf file using a tray containing your company's letterhead, while the rest of the printout should use regular paper from another tray.

Visual CUT provides two ways to split the printout of a PDF file to multiple printer trays:

Use the PDF_Print_Split command line argument to specify the page ranges
Use the PDF_Print_Split_Tag command line argument to indicate that Crystal (or any other process) has embedded text tags (#Tray::tray_name/number#) in the pdf on each page or on each page where a tray change should occur.

Using PDF_Print_Split

This command line argument structure is as follows:
… "PDF_PRINT_SPLIT:c:\temp\Test.pdf>1::\\srv2\Laser3::Top||2to5::\\srv2\Laser3::Tray 2 ||6to999::\\srv2\Laser3::Bypass Tray"

The parameters (after the ":") are as follows:

1. PDF_File: The PDF file you wish to print.

2. Page_Range::Printer_Name::Tray_Name

The 2^nd element can be repeated as many times as you need, with different page ranges, different trays, and even different printers. Use "||" to separate each instance from the instance following it.

Page range can be specified as a single page or as a range, using 'to' to separate the numbers.

If you use "Default" as the printer name, the report gets printed to the default printer.

Trays can be specified using their names or using their internal numbers.

Important Note: you can use field or formula names within the command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT. The dynamic content of these fields/formulas would be substituted into the command line argument. This allows you to dynamically control the page ranges that are sent to each printer tray!

To control print quality/speed, use the PDF_Print_Mode command line argument.

Using PDF_Print_Split_Tag

The advantage of this option is its ability to dynamically control paper trays using formula logic from within Crystal reports. For example, it makes it easy to print the first and last pages in each group using one tray and print the rest of the pages from another tray.

This command line argument structure is as follows:
… "PDF_PRINT_SPLIT_TAG:c:\temp\Test.pdf>\\srv2\Laser3"

The parameters (after the ":") are as follows:

1. PDF_File: The PDF file you wish to print.

2. Printer_Name (use "Default" to print to the default printer)

Visual CUT searches each page in the pdf document for text tags that look like:
#Tray::2# (in a case where the tray number is used) or
#Tray::Bypass Tray# (in a case where the tray name is used)

Typically, these tags would be placed as Crystal formulas on the report being exported to pdf.

For example, this formula (placed in the page header of the report) would cause the 1^st page to use tray 3 and the rest of the pages would alternate between Tray 2 and Tray 1:

WhilePrintingRecords;

Global StringVar gs_Printer_Tray;

IF gs_Printer_Tray = "" THEN gs_Printer_Tray := "3"

ELSE gs_Printer_Tray := Cstr(Remainder(PageNumber,2) + 1,0);

"#Tray::" & gs_Printer_Tray & "#";

Notes:

1. set the font color of the formula to white, the tag would be invisible on the report as well as on the pdf file, but Visual CUT would still have access to it. Alternatively, if you keep the PDF_Tags_Delete_Default option in DataLink_Viewer.ini as True, Visual CUT removes the tag text after processing it. Use non-proportional font for the tag formula (avoid Calibri and Bold/Italic).

2. The tag doesn't have to appear on every page of the report. Pages that don't have the tag would be printed to the paper tray last specified in previous pages.

3. Tray numbers are not always obvious; "Tray 2" could actually be Tray #3 internally. Hence, you should probably use Tray Names instead of Tray Numbers in the Tags.

4. Visual CUT sets the print job names shown in the printer queue to reflect the page range and tray name. This makes it easy to monitor the process.

5. Make sure the printer is not setup to automatically select the paper source.

6. To control print quality/speed, use the PDF_Print_Mode command line argument.

Controlling Print Quality/Speed

You can use the PDF_Print_Mode command line argument to control print quality and speed. The command line argument structure is as follows:

… "PDF_Print_Mode:Quality_Option"

The possible Quality_Option values (after the ":") are
1 for Normal quality
2 for high quality
3 for highest quality

Adding Back-Pages

In some scenarios, you may need to add to each page in the exported pdf a standard back-page. For example, invoices may require some legal language on the back of each page.
Assuming you have the standard back-page as a single-page pdf file, Visual CUT can automate the process of:

a) Exporting the report to a pdf file

b) Using the PDF_Insert_BackPage command line argument, Inserting the standard
back-page after each page and saving to a new or to the original pdf export

c) Printing the resulting pdf file via PDF_Print command line argument.

Since the PDF_Print command line argument is already described in the sections above, this section explains how the PDF_Inseret_BackPage command line argument is used:

Using PDF_Insert_BackPage

This command line argument structure is as follows:

… "PDF_Insert_BackPage:c:\temp\Export.pdf||c:\temp\BackPage.pdf||c:\temp\Result.pdf"

The parameters (after the ":") are as follows:

1. PDF_File: The PDF file that needs a back-page added to each page.

2. BackPage File: The 1-page PDF file to be inserted into the first file.

3. The Final File: (that’s the file you would use with PDF_Print)

Notes:

If a Final File option is not specified, the process will simply update the source PDF_File. For example:
… PDF_Insert_BackPage:c:\temp\{Invoice_N}.pdf||c:\temp\BackPage.pdf"
As always (as demonstrated in the example above), you can use field or formula names within the command line argument (just like you drag & drop fields & formulas into the various options in the 3^rd tab within Visual CUT.

Saving PDF Files to Image Files

Using a command line argument, you can instruct Visual CUT to take a PDF file and save it to an image file. The supported image types are: BMP, JPEG, WMF, EMF, EPS, PNG, GIF, or multi-page TIFF. Here's an example of the command line argument structure:

… "PDF_Save_As:c:\temp\Invoice.pdf>c:\temp\Invoice.bmp>BMP>96"

The parameters (after the "PDF_Save_As:") are separated by a ">" and are as follows:

The path & name of the PDF file (typically, this would be the exported file, but you can convert any PDF file).
The path & name of the target image file

Multi-Page Note: for TIF and G4 TIF export types, a multi-page pdf file results in a Multi-Page TIFF file. For all other image types, an image file for each page would be created with the page number at the end of the file name. For example, if the Invoice.pdf file in the example above had 3 pages, Visual CUT would create 3 bitmap files: Invoice1.bmp, Invoice2.bmp, and Invoice3.bmp
Image Type: BMP, JPEG, WMF, EMF, EMF+, EPS, PNG, GIF, HTML5, TIF, G4 TIF
Image Quality in Dots Per Inch (DPI): start with 96 and use multiples of that for better quality (but larger file).

Notes:

TIF and G4 TIF are not supported on Windows XP or earlier versions.

as usual, any of these arguments can contain references to fields or formulas and Visual CUT would dynamically replace the reference with the value in the report. For example:
… "PDF_Save_As:{@export_File_Name}.pdf>{@export_File_Name}.bmp>BMP>96"

For PNG, BMP, and JPEG image formats, Visual CUT crops, pads, and borders the images as per global options specified in the Image_Export_Options ini file entry. For detail, see: Embedding Report as Image(s) in Email (new approach).

Adding Form Fields & Submit Buttons to PDF Files

Using a command line argument, you can instruct Visual CUT to look for invisible tags inside the pdf file (Crystal formulas with font color set to background color) and to replace them with form fields such as Text, Checkboxes, Drop-Downs, Digital Signature, and even Submit Buttons (to send form data as XML via email or URL). This means that you can use Crystal Reports to design pdf forms, and Visual CUT to generate and distribute these forms.

Here's an example of the command line argument structure:

… "PDF_Form_Tags:c:\temp\Sales in {@Year_Parameter}.pdf"
or, to save to a new file: … "PDF_Form_Tags:{@SourceFile}.pdf>{@TargetFile}.pdf"

The Crystal formulas act as tags for controlling the location, size, and content of these form fields. Visual CUT adds the form fields and any required JavaScript code. Users can then enter information into the pdf file, submit (via email or url), print, or save the completed form.

Sample PDF File with Form Fields & Submit Buttons

You can download a sample of such a pdf export with form fields at:
www.milletsoftware.com/Download/Visual_CUT_PDF_Form_Tags_Unsigned.pdf

Sample Crystal Report with Formulas as Form Field Tags

You can download a sample report demonstrating the technique from:
www.milletsoftware.com/Download/Visual_CUT_PDF_Form_Tags.rpt

The sample report uses several formulas:

PDF_Form_Field_Product_Comment (GF2) provides short text area for each Product

PDF_Form_Field_Product_Checkbox (GF2) provides a checkbox to indicate if performance is OK

PDF_Form_Field_Product_Type_Comment (GF1) provide multi-line text area for each Product Type.
PDF_Form_Field_Product_Type_DropDown (GF1) provides a DropDown to indicate required Action

PDF_Form_Field_Submit_Button_Email_XML (RF) Button to submit form data as XML via email
PDF_Form_Field_Submit_Button_URL_XML (RF) Button to submit form data as XML via url

PDF_Form_Field_Text_Secret (RH) provides a hidden form field (to include in XML)
PDF_Form_Field_Text_URL (RH) provides a visible but uneditable form field

PDF_Form_Field_Date (RF) provides a Date Picker (in Acrobat Reader) to select (and enforce) a valid date.
PDF_Form_Field_Signature (RF) prompts for, accepts and displays the user's digital signature.

Setting Up a Crystal Report with pdf field tags

There are no restrictions on the number or names of the formulas you can use. However, each rendered instance must provide a unique form field title (avoid dots). The formula text must be rendered all within the formula boundaries in a single line. Use very small font sizes: 2 or even 1 to achieve this.
Use non-proportional font for the tag formula (avoid Calibri andBold/Italic).

Obviously, you may not want to show the formula text on the resulting pdf file. You can turn the font color to White (or same as section background) to make the formula invisible. Better yet, if you keep the PDF_Tags_Delete_Default option in DataLink_Viewer.ini as True, Visual CUT removes the tag text after processing it. In order to allow Visual CUT to remove the tag text after it has been processed, be sure to replace any double quotes or parentheses in the tag text with single quote or square brackets.

Each formula instance (Group Footer/Header as well as Page Header/Footer formulas may have many instances) can trigger the creation of a pdf form field. The location (top left corner) of each rendered formula instance controls the location of the pdf form field. The width and height of the form field is controlled internally -- not by the formula field size.

Note: besides Acrobat Reader, there are several 3^rd-party PDF Viewers that allow saving PDF files after filling form fields. For example:
http://www.tracker-software.com/product/pdf-xchange-viewer

Formula Example from the Sample Report

The following page demonstrates and comments the structure of the required formula text for one of the formulas in the sample report. You can open the sample report to see the fully-commented syntax for the other form field types.

Here is the {@PDF_Form_Field} formula from the sample report at:
http://www.milletsoftware.com/Download/Visual_CUT_PDF_Form_Tag.rpt

// Make the font size small (even 1 point). Text must stay in formula boundaries in SINGLE line!

// Turn the font color to White to make the formula invisible. Or, if PDF_Tags_Delete_Default in
// DataLink_Viewer.ini is True, tag text is removed automatically after processing.

// Location (top left corner) of the rendered formula instance control location of pdf form field.

// The formula always starts with "#Form_Tag::" and ends with "#"

"#Form_Tag::" +

"350;50" + "||" + // field boundaries in points: width;height (or shift_x;shift_y;width;height)

{Product_Type.Product Type Name} + "_Comments" + "||" + // UNIQUE title of form field

"TEXT" + "||" + // type of form field: TEXT/Date/DropDown/CheckBox/Submit_Button/Signature
"0" + "||" + // For TEXT, max length (0 is no limit). For DropDown, list of values delimited by :::
"NotComb" + "||" + // "Comb" or "NotComb" field (if Comb, specify max number of characters
// above to create an equally spaced "comb" field effect)

"Left" + "||" + // alignment: "Left", "Center" or "Right"

"1;Inset;0;0" + "||" + // Field Border: line width;style (Solid, Dashed, Beveled, or Inset);
// length of dash;length of dash space

"230;230;230" + "||" + // Border color using RGB (0;0;128 = Navy Blue)

"255;255;255" + "||" + // Background Color ("255;248;220" = cornsilk1, "255;255;255" = White)

"0;0;0" + "||" + // Text Color ((0;0;0 = Black)

// Possible font types: Courier, CourierBold, CourierBoldItalic, CourierItalic

// Helvetica, HelveticaBold, HelveticaBoldItalic, HelveticaItalic

// TimesRoman, TimesBold, TimesItalic, TimesBoldItalic

"CourierBold;10" + "||" + // Font type and size

// Initial Field Text Value (Use "" to specify an empty field)

iif({Product_Type.Product Type Name} in ["Saddles", "Locks"], "", "Comments on the information for " + {Product_Type.Product Type Name} + ": ") + "||" +

"NoScroll" + "||" + // Scroll or NoScroll

"MultiLine" + "||" + // SingleLine or MultiLine

"SpellCheck" + "||" + // SpellCheck or NoSpellCheck

// --- new options in 6.2002: ---

// tool tip shown when hovering over field. Use "Same_As_Text" to display Field Text value

"Product Type Comments [Mandatory if Action is 'Meeting' or 'Conference Call']" + "||" +

"False" + "||" + // Read Only status. If True, user can see but not change the value

"False" + // Hide Field? Useful when user should not see a submitted value

"#" // The formula always ends with "#"

· VC removes pdf processing tags from the pdf file (after processing) if PDF_Tags_Delete_Default under the [Options] section of DataLink_Viewer.ini is left as True. To ensure all tags are removed, use Replace() to change double quotes into single. For example, the form field title can be:
Replace({Product_Type.Product Type Name},"""","'") + "_Comments"

· To accommodate more text in the tag, you may embed references to fields/formulas in it.

· To specify child form fields, specify a title of Parent_Field_title.Child_Field_Title.

Adding a Digital Signature Form Field

As demonstrated by the sample report, one of the supported form fields is a digital signature. The formula for the digital signature field is simple:

"#Form_Tag::" +

"250;50" + "||" + // field boundaries in points: width;height

// (note: if 4 arguments are provided, they are treated as: shift_x;shift_y;width;height)

"Signature1" + "||" + // title of form field. Use something unique

"Signature" + "||" + // type of form field

"#"

When opening the pdf, the user is prompted by the field to digitally sign the document:

After clicking the field and providing a digital signature:

the user has the option to Lock the Document (so no other changes can be made to it without invalidating the signature):

After saving the PDF to a new file, the field looks like this:

Populating Form Field Text or Description via ODBC Query

When dealing with multiline text form fields, you may need to populate the text of the field with very long text that might cause the tag content to spill over more than 1 line. To address that scenario you may embed a directive to execute a SQL Query via ODBC inside the options for Initial Text or Field Description (tooltip) and Visual CUT would replace the directive with its dynamic result.

Here is an example of what the Crystal formula may look like:

"#Form_Tag::" + "350;50" + "||" + {Product_Type.Product Type Name} + "_Comments" + "||" + "TEXT" + "||" + "0" + "||" + "NotComb" + "||" + "Left" + "||" + "1;Inset;0;0" + "||" + "230;230;230" + "||" + "255;255;255" + "||" + "0;0;0" + "||" + "CourierBold;10" + "||" +

// Initial Field Text Value (populated via SQL Query

"{ODBC:Customers:: :: ::SELECT [Name] FROM [CUST] WHERE [Cust_ID] = 6}" + "||" +

"Scroll" + "||" + "MultiLine" + "||" + "SpellCheck" + "||" +

"Product Type Comments [Mandatory if Action is 'Meeting' or 'Conference Call']" + "||" +

"False" + "||" + "False" +"#"

The expression starts with {ODBC: followed by 4 elements separated by :: and

ends with }

1. ODBC DSN (Note: could be different from the DSN used for the Crystal report)

2. User ID (use a single space if not needed, as shown above)

3. Password (use a single space if not needed, as shown above)

4. SQL Statement

MS Access Example:
{ODBC:Customers::User_ID::Password::SELECT [email] FROM [Contacts] WHERE [Customer_ID] = '301'}

SQL Server Example:

{ODBC:CONTACTS::sa::xxxxx::SELECT AHD.ctct.Comments FROM

AHD.ctct where AHD.ctct.Comments IS NOT NULL}

Notes:

§ If the SQL statement returns multiple rows, Visual CUT takes care of concatenating the text from all the rows to a single string with carriage return and line feed as the delimiter.

§ The SQL statement syntax depends on your database. For example, as shown in the samples above, MS Access uses [ ] around field/table names but SQL Server doesn't.

§ You would typically build the expression while using some field/formula values (not names) to control the WHERE clause.

Filling PDF Forms

Using a command line argument, you can instruct Visual CUT to fill the fields in a given PDF Form and save the result into a new PDF file. Here's an example of the command line argument structure:

… "PDF_FORM:c:\temp\MyForm.pdf>False"

The parameters (after the "PDF_FORM:") are separated by a ">" and are as follows:

1. The path & name of the PDF form file (used as a template).

2. Flatten form fields (True or False)? If True, as field values get substituted by formula values from the Crystal report, Visual CUT turns the form field into a static portion of the PDF file. This means the field will no longer act as a field in the new pdf file. It will simply behave as a static portion of the new PDF file.

Setting Up a Crystal Report to Act as a PDF Form Filler

Each field in a PDF form has a name ("title" in pdf lingo). In order to fill (or substitute) the value of such a field, your Crystal report should have a string formula with the same name as the PDF form field. For example, if you desire to fill a PDF form field called "f1-1", you should create a Crystal formula called "f1‑1" providing the desired value for that field. In order to supply a value for a checkbox field (as shown below), use "Yes" as the value for checked and "No" for the value for unchecked.

The Crystal formulas should be placed in the report header/footer if the value is the same for all records in the report. It should be placed in Group Level 1 Header/Footer if the value changes for each Level 1 group and you are bursting (generating a different PDF file for each Level 1 Group). As usual, you may suppress the formulas.

Setting Up the Report in Visual CUT

In Visual CUT, simply set the report to export to PDF and specify the export file name. As usual, you may make the export file path and/or name dynamic (reflecting field/formula values from the report. Note that if you use the PDF_FORM command line argument, Visual CUT will not export the report to PDF. Instead, Visual CUT would substitute the form fields in the Form File (specified in the command line argument) and then save the result to the specified export file name.

Setting PDF Document Properties after Export (Automatic)

After PDF exports, Visual CUT sets the PDF document summary information according to the summary information set for the report in Crystal.

This functionality, as well as the PDF Bookmarks functionality described in the previous section, are enabled by default. To turn it off, use the Options dialog and uncheck the option of "PDF Exports include Document Properties and Bookmark Processing."

Setting PDF Document Properties

You can specify the pdf document properties via the command line argument of PDF_Properties. Here's an example of the command line argument structure:

…"PDF_Properties:c:\test.pdf>Ido>{@Invoice_N}>Invoice>Invoice>Ido>Millet Software"

The parameters (after the "PDF_Properties:") are separated by a ">" and are as follows:

PDF file(s): comma separated list. Can use wild cards!
Author of the PDF file
Title
Subject
Keywords
Creator
Producer
----------------------------------------------------------------------
Page Mode: Normal (or blank)/Outlines/Thumbnails/FullScreen/OCG/Attachments
Open Page (1 is default)
Zoom (75 for 75%, 0 for default, -1 for fit in window, -2 for fit width)

----------------------------------------------------------------------

11. Custom Properties (Name1::Value1||Name2::Value2)
For example, "…>Case Type::Abduction||Case Manager::Officer Krupke"
Any number of pairs delimited by || with a :: separating Key Name from Key Value.

Notes:

To target multiple files, specify a list separated by commas.
You can use wild cards to target multiple files (e.g. c:\temp\test.pdf,c:\temp\Inv*.pdf)
Specify the first 7 elements, or all 10 elements, or all 11 elements
As usual, any of these elements can contain references to fields or formulas and Visual CUT would dynamically replace the reference with the value in the report.
Page Mode controls what panels are visible when the pdf file is initially opened.
Outlines: Show the bookmarks pane
Thumbnails: Show the thumbnails pane
FullScreen: Show the pdf in full screen mode
OCG: shows the Optional content group pane
Attachments: shows the attachments pane
If you wish to avoid setting/overriding any of these properties, just leave them blank.
For example, to set just the author and the subject, the command line may look like this:

…"PDF_Properties:c:\Inv\*.pdf,c:\test.pdf>Ido>>{@Invoice_N}>>>>Outlines>1>100"

· Specifying Custom Properties is the same as manually specifying them in Acrobat Pro using File, Properties, Custom Tab. These properties show up in the list of document properties and can be useful for users and for document management systems.

Flatten PDF Files

You can flatten form fields and annotations in pdf files via the command line argument of PDF_Flatten. Here's an example of the command line argument structure:

…"PDF_Flatten:c:\Before\*.pdf>>MyPassword>>c:\After\"
or (for a case with no password):

…"PDF_Flatten:c:\Before\*.pdf>>>>c:\After\"
or (for a case without target folder:

…"PDF_Flatten:c:\Before\*.pdf>>MyPassword>>"
or (for a case without password and no target folder:

…"PDF_Flatten:c:\Before\*.pdf>>>>"

The parameters (after the "PDF_Flatten:") are separated by a ">>" and are as follows:

PDF file(s): comma separated list. Can use wild cards!
Password (leave blank if the pdf files are not password protected)
Target Folder (leave blank if the flattened pdf files should replace the original files)

Building an Index PDF Documents

You can build a full-text index for multiple pdf files via the command line argument of PDF_Build_Index. Here's an example of the command line argument structure:

…"PDF_Build_Index:c:\temp\dir1||c:\temp\dir2>c:\temp\Index.pdx>"

The parameters (after the "PDF_Build_Index:") are separated by a ">" and are as follows:

List of folders (separated by "||") containing pdf files to be indexed
Notes:
1. All pdf files found in these folders and all subfolder (recursive) will be indexed.
2. Do not include a backslash at the end of each folder path.
Index (.pdx) file path and name
Notes:
1. The pdx file will be deleted, if it already exists, when the process starts
2. If an "Index" folder exists under the folder destination for the pdx file, that folder is deleted when the process starts because this folder needs to be created from scratch by the indexing process.
Options: leave blank. Reserved for future needs such as specifying maximum amount of time the process should require. The default is 2 hours.

Notes:

On the Visual CUT machine, Acrobat Pro must be installed and the build index button must be located on the toolbar like this:

As usual, any of these arguments can contain references to fields or formulas and Visual CUT would dynamically replace the reference with the value in the report. For example:
… "PDF_Build_Index:{@Folders}>c:\temp\Index.pdx>"

Adding an Index File to a PDF Document

You can add an index (.pdx file) reference to a pdf document via the command line argument of PDF_Add_Index. Here's an example of the command line argument structure:

…"PDF_Add_Index:c:\test.pdf>c:\textMyIndex.pdx>PDX"

The parameters (after the "PDF_Add_Index:") are separated by a ">" and are as follows:

PDF file path & name
Index (.pdx) file path and name (on the machine where the pdf file will be used)
Index Label (must always be "PDX" - Other values would be converted to "PDX")

Note: Index file path can be specified as relative to the PDF file location.
For example: ..\Index.pdx

Adding Named Destinations to a PDF Document

You can add named destinations to a pdf document based on its bookmarks.
A typical benefit from this is that a url link to the PDF can then direct the browser to open the pdf and position to the page where the named destination is located. For example:
http://www.milletsoftware.com/Download/test_Add_Destinations.pdf#Mountain__SlickRock

Here's an example of the command line argument structure:

…"PDF_Add_Destinations:c:\temp\{@Region_Sales}.pdf>>>>BM>>"

The parameters (after the "PDF_Add_Destinations:") are separated by a ">>" and are as follows:

Source PDF file (with bookmarks) path & name
Target PDF path & name. If left blank, as in example, source file gets updated.
BM (indicated the method used to add Destinations)
Options (leave blank)

Notes:

· Destination names reflect the bookmark hierarchy by chaining the labels with 2 underscores ('__') as separators. For example, Mountain__SlickRock was assigned for the bookmark 'SlickRock' located under the top-level bookmark of 'Mountain'.

· PDF_Bookmark_Tags is always processed beforePDF_Add_Destinations, so you can include both in a single command line.

· The browser needs to be set to Open rather than download PDF files in order to handle specified destinations.

Adding Multimedia to PDF Document

You can ask Visual CUT to add a sound file to be played when the pdf file is opened in Acrobat Reader via the command line argument of PDF_Add_Media. Here's an example of the command line argument structure:

…"PDF_Add_Media:Pdf_In>>Pdf_Out>>Media_File>>1>>X>>Y>>Width>>Height>>Options"

The parameters (after the "PDF_Build_Index:") are separated by a ">>" and are as follows:

PDF File to open
PDF File to Save As (leave blank if same as source file above)
Media File (e.g. c:\temp\Greeting.mps)
Page where the multimedia box would be added (currently, must be 1)
X: horizontal offset of the multimedia box
Note: relative to drop-down highlighted in image below. Can be negative (e.g. -20)
Y: vertical offset of the multimedia box
Width of multimedia box
Height of multimedia box
Media Type: currently must be "Sound"
Options: leave blank. Reserved for future needs.

Notes:

Acrobat Pro must be installed and the Add Multimedia dropdown must be located on the toolbar at the position indicated in the image below:

You may need to experiment with the coorindates (X, Y, Width, Height) to avoid conflict with existing objects on the page.

As usual, any of these arguments can contain references to fields or formulas and Visual CUT would dynamically replace the reference with the value in the report.
For example (all in 1 line):
… "PDF_Add_Media:{@Catalog}>>{@Catalog_with_Greeting}>>c:\temp\Greeting.mp3>>
1>>-20>>100>>140>>16>>Sound>>"

Importing Multi-Page TIFF Files into PDF Files

Imagine you wish to use Visual CUT to burst a Crystal report and email customers invoices as PDF files. The customers wish to see documentation (scanned as multi-page TIFF files) included at the end of each invoice. Since Crystal can only display the first page of such TIFF files, you need a way to append the related TIFF file at the end of each invoice, before emailing the resulting pdf file to the customer.

Using a command line argument, you can instruct Visual CUT to take a multi-page TIFF file and turn it into a pdf file or append it to the end of an existing pdf file.
Here's an example of the command line argument structure:

…"PDF_From_TIFF:c:\tmp\Invoice_{@Inv_N}.pdf>{@Tiff_File}>0>True>True"

The parameters (after the "PDF_From_TIFF:") are separated by a ">" and are as follows:

The path & name of the PDF file (typically, this would be the exported file, but you can use any PDF file). In bursting scenarios, you would typically refer to the dynamic exported file name by embedding a reference to a field or formula (marked in blue in the example above).
The path & name of the TIFF file(s)
A semi-colon (;) separated list of the TIFF files in the order they should be merged into the pdf file. If all source files share the same folder, you can specify the full path just for the first file. If a source file is not found, a warning is written to Failure.log and that file is skipped.
Typically, you would use a field or a formula (marked in blue in the example above) from the report to dynamically provide the path and name of the TIFF file(s) related to the Group Level 1 in the current bursting step.
Scaling relative to original image size: 100 = original size. 120 = 20% larger.
0 = requests automatic scaling of the image to fully occupy the page size.
Append (True/False): set to true if the TIFF should be appended to the pdf file, if that target file already exists. Otherwise, if the pdf file already exists, it would be transferred to the recycle bin and the TIFF content would be used to create a new version of that pdf file. When Append is set to False, page dimensions are controlled by the TIFF image dimensions and scaling, rather than by the page dimensions of the "receiving" pdf file.
Critical (True/False): controls what should happen if the TIFF file is not found. If set to TRUE, Visual CUT processing would be aborted. If set to False, only a Warning is logged but processing continues (if the Invoice pdf can't find a matching TIFF file, it would be emailed without that content).

Note: as usual, any of these arguments can contain references to fields or formulas and Visual CUT would dynamically replace the reference with the value in the report.

Inserting Image/PDF Files as New Pages (Tag Approach)

Imagine Visual CUT burst an invoices report to PDF for emailing to each customer. Each customer may have multiple invoices and you wish to insert at the end of each invoice an image, multi-page TIFF file and/or a related pdf file reflecting a scanned proof-of-delivery. Visual CUT can do this if you include on the last page for each invoice a tag specifying the image, multi-page TIFF, or pdf files that should be inserted after that page in the exported pdf file.

Supported pdf or image file types include: PDF, PNG, GIF, BMP, JPEG/JPG, PNG, GIF, WMF, EMF, TIF/TIFF

Here's an example of the command line argument structure:

… "PDF_Insert_Pages_Tags:c:\temp\{@Cust}_Invoices.pdf"

… "PDF_Insert_Pages_Tags:c:\temp\{@Cust}_Invoices.pdf>>c:\temp\{@Cust}_Invoices.pdf"

If only one pdf file is specified (as in the top example), then the source file becomes also the target file. Otherwise, the resulting file is saved to the 2^nd pdf file.

You can download a sample report demonstrating the technique from:
http://www.milletsoftware.com/Download/VC11_PDF_Insert_Pages_Tags.rpt

The formula acting as a tag can be placed anywhere on the report. It specifies what image files should be inserted as following pages. In this sample report, the tag formula is called {@Insert_Pages_Tag} and is located in the page footer. The formula name doesn't matter, but the logic should follow this example:

"#Insert_Pages_Tag::" +

"C:\temp\sample1.jpg;sample2.pdf;sample3.tif" + // list of files. Wild cards OK.

"||" + // Separator

"100" + // Scaling: 100 = original. 120 = 20% larger, etc. 0 = auto-fit to page.

"#"

The formula text must be rendered all within the formula boundaries in a single line. Use very small font sizes: 2 or even 1 to achieve this. You may turn the font color to White (or same color as the background) to make the formula invisible.

Notes:

1. Scaling argument is ignored for inserted pdf files.

2. To ignore (rather than fail) cases where an image file is not found, use:
…"PDF_Insert_Pages_Tags:c:\temp\Source.pdf>>Resulting.pdf>>[Ignore_Missing_Files]"

3. In Crystal, use non-proportional font for the tag formula (avoid Calibri and Bold/Italic)

4. As always, you can use field or formula names within the command line argument. The dynamic content of these fields/formulas would be substituted into the argument.

5. In the list of files, if path is same, you may specify just the file name for subsequent files.

6. The list of files can use wild cards (e.g. c:\scans\{cust_id}\*.tiff).

7. Visual CUT can remove pdf processing tags from the pdf file after processing those tags. This is controlled by an entry called PDF_Tags_Delete_Default under the [Options] section of DataLink_Viewer.ini. By default, this option is set to True.

Splitting PDF Files

Visual CUT provides two ways to split pdf files:

1. Using pdf bookmarks, VC can create a new pdf file for each bookmark at a specified level and name the pdf file based on the bookmark labels and as well as based on Crystal report formulas.

2. Using invisible text tags placed on the pdf pages (typically Crystal formulas with font color to make them invisible). These tags act as split directives indicating file names for the pages starting with the tag location and ending with the next tag. These tags can also direct Visual CUT to encrypt the resulting pdf files with different passwords. Visual CUT takes care or removing these tags from the resulting pdf files.

Splitting By Bookmarks

Imagine you have a pdf file with bookmarks at 2 levels: Product Type & Product. The bookmarks were generated during a Crystal report export by Visual CUT, or perhaps they are part of an existing pdf file. Using the command line argument of PDF_Split_By_Bookmarks you can direct VC to Split the pdf to a separate pdf file for each bookmarks at a specified level, name the file based on the bookmark label, and even place the resulting file in a dynamically specified/created folder based on the bookmark name.

Here's an example of the command line argument structure (all in 1 line):
… "PDF_Split_By_Bookmarks:c:\Sales.pdf>>2>>
c:\{[Bookmark_Name]}\Sales for {[Bookmark_Name]} in {[yyyy]}.pdf

The parameters (after the "PDF_Split_By_Bookmarks:") are separated by a ">>" and are as follows:

The path & name of the source PDF file
The targeted bookmark level (level 2 in this example targets the Product level)
The path & name of the split pdf file to create for each targeted bookmark

A {[Bookmark_Name]} reference gets replaced by the bookmark label. For example, Mozzie

A {[Bookmark_Chain_A]} reference gets replaced by a hyphen-separated sequence of bookmark labels leading to/including the targeted node. For example: Competition – Mozzie

Notes:

· For each targeted bookmark, a separate pdf is created from the page associated with the bookmark up to (but not including) the page associated with the next targeted bookmark.

· If the target folder doesn’t exist, VC creates it on the fly.

· Invalid file name characters are automatically substituted with valid ones.

· If a path to the target folder is not specified, the path to the source file is used.

· As usual, any of these arguments can contain references to fields or formulas, and VC would dynamically replace the reference with the value in the report. In the example above, the {[yyyy]} gets replaced with the current year.

· The process is very fast

Splitting By Embedded Tags

Using a command line argument, you can instruct Visual CUT to look for invisible tags inside the pdf file (Crystal formulas with font color set to background color) and to split the file into multiple pdf files. The following situations can benefit from this splitting of a pdf file (as opposed to bursting the Crystal report directly to multiple pdf files):

1. Speed of bursting is VERY fast, particularly for huge pdf files with many group values.

2. You can split the main pdf file based on any logic (e.g., level 4 grouping).

3. You can split any pdf file, even if it was not exported from Visual CUT.

4. You can "Print" reports to pdf before splitting (avoiding pdf export font issues)

5. Using {ppp} token, you can include number of pages in the name of each split file.
See sample image.

Here's an example of the command line argument structure:

… "PDF_Split_Tags:c:\temp\Sales.pdf>>True>>True>>False"

The parameters (after the "PDF_Split_Tags:") are separated by a ">>" and are as follows:

The path & name of the PDF file
Compress the split pdf files? (set to False for faster execution)
Create missing folders? (set to False for faster execution)
Assume Tag is always Nth text object on page? (set to True for faster execution)

Within the pdf file, you should embed text tags (Crystal formulas) that indicate the page locations for starting a new split pdf file, and the path & name of that new file.

Notes:

- If the target folder of the split files does not exist, Visual CUT creates it on the fly.

- In Crystal, use non-proportional font for the tag formula (avoid Calibri and Bold/Italic)

Here is an example of such a formula that can be placed, for example, in a Group Header section:

// Set small font. Text must display within the boundaries in a SINGLE line.

// The page where the tag is detected becomes the first page of the split pdf

// The last page of the split pdf is the page before the next tag.

// If a single page has 2 Split Tags, only the first one is detected.

// {ppp} gets replaced by zero-padded number of pages in the split file (2 pages = '002')

// The formula always starts with "#Split_Tag::" and ends with "#"

"#Split_Tag::" +

"c:\" + {@Folder} + "\" + {Product_Type.Product Type Name} + ".pdf" + // Split PDF File

"#"

Notes: Visual CUT can remove pdf processing tags from the pdf file after processing those tags. This is controlled by an entry called PDF_Tags_Delete_Default under the [Options] section of DataLink_Viewer.ini. By default, this option is set to True. To ensure all tags are removed, use the Replace() function in Crystal to change double quotes into single quotes. For example, the expression for the file name could be:
Replace({Product_Type.Product Type Name},"""","'")

Splitting and Emailing PDF Files By Embedded Tags

See video demo.

This option uses the same command line argument as the previous section.
The email destination for each split pdf is specified at the end of the text tag embedded in the pdf like this:

// Set small font. Text must display within the boundaries in a SINGLE line.

// The page where the tag is detected becomes the first page of the split pdf

// The tag always starts with #Split_Tag:: and ends with #

// The email destination is specified after a || delimiter

#Split_Tag::c:\temp\Invoice_2466.pdf||ido@MilletSoftware.com#

You can use a PDF file that is not exported from a Crystal report. Simply use a dummy report and set the export to a dummy file or to VC_Skip_Export

You can use the GUI of the Export/Email tab to set the email options for Email From, CC, BCC, Subject, and Message.

Set the Email Attach option to {[PDF_Split_Tags_File]} . Visual CUT will populate that token with the file name for each split pdf..

Set the Email To option to {[PDF_Split_Tags_Email_To]} . Visual CUT will populate that token with the email destination specified in the text token for each split pdf file.

Use {[PDF_Split_Tags_FileName_NoExtension]} to embed the file name (without path and without extension) in the email subject or in the message body.

Notes

· In the text tag, after the || delimiter, leave the email address blank to skip emailing for some files.

· Use email queing to increase speed and facilitate testing.

Splitting, Protecting, and Emailing PDF Files By Embedded Tags

This option is identical to previous section, except that the tag also provides a password for protecting the pdf file against unauthorized access. The password protection uses a strong AES 256B encryption.

The email destination for each split pdf is specified at the end of the text tag embedded in the pdf like this:

// Set small font. Text must display within the boundaries in a SINGLE line.

// The page where the tag is detected becomes the first page of the split pdf

// The tag always starts with #Split_Tag:: and ends with #

// The email destination is specified after a || delimiter
// The password is specified after a second ||delimiter

#Split_Tag::c:\temp\Invoice_2466.pdf||ido@MilletSoftware.com||Sesame123#

Notes

· In the text tag, leave the email address blank to skip emailing for some files.

· In most cases, dynamic email address and password would be concatenated into the tag using a formula expressions such as:
"#Split_Tag::" +

"c:\temp\Direct_Deposit_" + {@Emp} + ".pdf" + // Split PDF File

"||" + {@Emp_Email} + // email address
"||" + {@Emp_Password} + // password

"#"

Splitting and Protecting PDF Files By Embedded Tags

Note: if all you need is strong password protection against opening the file by unauthorized users, the previous section describes a newer and simpler approach. Use this option only if you need control over document permissions.

to This option iUsing a command line argument, you can instruct Visual CUT to look for invisible tags inside the pdf file (Crystal formulas with font color set to background color) and to split the file into multiple protected pdf files. The following situations can benefit from this splitting of a pdf file (as opposed to bursting the Crystal report directly to multiple pdf files):

5. Speed of bursting is incredible, particularly for huge pdf files with many group values.

6. You can split the main pdf file based on any logic (e.g., level 4 grouping).

7. You can split any pdf file, even if it was not exported from Visual CUT.

Here's an example of the command line argument structure (all in 1 line):

… "PDF_Split_Protect_Tags:c:\temp\Sales.pdf>>False>>True>>False…
>>Owner_Password>>1>>1>>0>>1>>1>>1>>1>>0"

The parameters (after the "PDF_Split_Protect_Tags:") are separated by a ">>" and are as follows:

The path & name of the PDF file
Compress the split pdf files? (set to False for faster execution)
Create missing folders? (set to False for faster execution)
Assume Tag is always Nth text object on page? (set to True for faster execution)
Owner_Password: Keep this password to yourself. It provides full control over the PDF file. Note: user password is provided in the Tag embedded in the pdf.
Allow User to Print the File: (1=Yes, 0=No) 1 is typical.
Allow User to Copy Text & Images from the File: (1=Yes, 0=No) 1 is typical.
Allow User to Edit/Change the File: (1=Yes, 0=No) 0 is typical.
Allow User to Add Notes to the File: (1=Yes, 0=No) 1 is typical.
Allow User to Print in Full Resolution: (1=Yes, 0=No) 1 is typical.
Setting this to zero would force low-resolution printing, preventing the document from being distilled into a new unrestricted PDF document.
Allow user to Fill Form Fields: (1=Yes, 0=No) 1 is typical.
Allow Copy for Accessibility: (1=Yes, 0=No) 1 is typical.
Allow user to assemble document: (1=Yes, 0=No) 0 is typical.