Document ID: 28401.1
Subject: (V2.5) Oracle Reports ASCII Output on Windows
Author: LGIAMBRU
Last Revision Date: 05 November 1996
INTRODUCTION
The Oracle Reports ASCII Driver was developed and included with versions of
Oracle Reports 2.5 up to version 2.5.4. It was introduced because of
limitations with the Microsoft Generic/Text Driver which frequently prevented
the creation of ASCII output on Microsoft Windows with
Oracle Reports V2.0. The inability to create ascii output was only a problem
with Oracle Reports V2.0 on Microsoft Windows because other platforms include a
character mode runtime that generates ascii output. Since there is no
character mode runtime on Microsoft Windows and because of the above mentioned
limitations of the Generic/Text Driver, it is virtually impossible to create
proper ascii output with Oracle Reports V2.0 on Microsoft Windows.
For all versions of Oracle Reports of 2.5.4.0.8 (Developer 200 v1.2) and above,
this Reports ASCII Driver is no longer used. Oracle Reports now writes
character mode reports directly to file using the appropriate .prt files
provided.
This bulletin attempts to clarify and illustrate how Oracle Reports ASCII
output works by explanation and example. It is intended as a supplement to the
Oracle Reports V2.5 Reference Guide. Appendix B of this manual specifically
addresses printer definitions.
The Oracle Reports improved ASCII ouput is a very powerful new feature of
Oracle Reports V2.5. Not only does it allow the creation of ascii output, but
it allows the user to simulate running a report in character mode. When a
report is run with the Oracle Reports ASCII Driver it uses PRT files to format
the output.
(For those of you who used SQL*ReportWriter V1.1, these PRT files are very
similar to the drivers you generated using printdef.dat.) PRT files can be
used to embed escape sequences in your output in order to send directions to
your printer. For instance, you might want to send a report to a particular
tray or perhaps print in compressed mode. Customized PRT files can easily be
used to place these escape sequences in the proper place in your final output.
While there are many advantages to postscript printing, if your report does not
contain graphical objects that require postscript printing you might want to
consider using the ASCII output since ascii
output is generally faster to create and print.
DESIGNING REPORTS TO PRODUCE ORACLE REPORTS ASCII OUTPUT
In order to get valid ASCII output, your report must be designed to run in
character mode. (Your reports must also be designed to run
character mode if they are going to be run with the character mode runtime
executable on another platform.) Please refer to Chapter 8 of your Building
Reports Manual for complete directions on designing a character mode report.
RUNNING AN ASCII REPORT
For Oracle Reports lower than version 2.5.4, The Oracle Reports ASCII Driver is
automatically be installed when the product is installed. Oracle does not
recommend setting the Oracle Reports ASCII Driver as the default driver or
using it with other products. It was designed for use with Oracle Reports and
there is no guarantee it will work with other products. Please see your Oracle
Reports release notes for details on the installation and configuration of the
ascii driver.
For Oracle Reports version 2.5.4 and above, it is not necessary to install any
additional drivers, Oracle Reports has all the information it needs in the
supplied .prt files.
Once your report is designed in character mode, you are ready to run using
ascii output. To do so, simply set the system parameter MODE to have a
value of CHARACTER. The MODE parameter can either be set at runtime or be
given a default value through the designer. By default, the MODE parameter's
initial value is DEFAULT. This means the report will run in the mode of the
executable that invoked it. (On windows this will always mean BITMAP since
there is no CHARACTER runtime.) By setting the MODE parameter to CHARACTER,
Oracle Reports automatically produces ASCII output.
PRT FILES
When running a report with MODE=CHARACTER, unless otherwise specified the DFLT.
PRT file is used to format your report. This PRT file and several
others are located in your C:\ORAWIN\REPORT25\PRINTERS directory. (For the
purpose of this bulletin it is assumed that oracle home is set to C:\ORAWIN).
The DESFORMAT system parameter is what points to the PRT file you want to use.
The DESFORMAT parameter must have an initial value. By default the initial
value is DFLT to point to DFLT.PRT. Oracle Reports searches your working
directory and then the C:\ORAWIN\REPORT25\PRINTERS directory to find the PRT
file specified in the DESFORMAT parameter.
Oracle Reports is shipped with several printer definitions. The list below
are the definitions most commonly shipped with the product. (This is port
specific so you may not have all these definitions or you may have others not
listed here.)
dec.prt Generic printer file for most DEC printers that
supports 66x80 page sizes.
decland.prt Generic printer file that prints in landscape
mode and supports 66x132 page sizes.
decwide.prt Is the same as dec, but supports 66x132
page sizes.
dec180.prt Is the same as decland, but supports 66x180 page
sizes.
dflt.prt Generic printer file that ignores highlighting
attributes and supports 66x80 page sizes.
bold.prt Same as dflt but recognizes highlighting and
underlining attributes.
hpl.prt Generic printer file for the HP LaserJet that
supports 66x80 page sizes.
hplwide.prt Same as hpl but supports 66x132 page sizes
wide.prt Generic printer file that ignores highlighting
attributes and supports 66X132 pages sizes. (Does
not print report in landscape mode.)
wide180.prt Same as wide but supports 66X180 page sizes
In most cases, one of the above PRT files will suit your particular needs.
However, you can modify or create your own PRT files to address your
specific requirements.
CREATING LANDSCAPE OUTPUT FOR AN HP PRINTER
Notice that a printer driver to print in landscape on an HP printer is not
provided. You will need to create your own driver to do this. Below is an
example of what that PRT file should look like:
printer "hpl_land"
height 66
width 132
before report esc "&110"
after page control(L)
return ""
linefeed control(J)
code "bold on" esc "(s7B"
code "bold off" esc "(s0B"
code "underline on" esc "&dD"
code "underline off" esc "&d@"
*Note: Escape sequences are found in your printer manual.
While the examples used throughout this bulletin should work on
most HP printers, it is not guaranteed and your printer manual
should be consulted to verify appropriate escape sequences.
The above printer definition will always place reports in landscape mode.
You can also create a defintion that will only place reports in landscape mode
if the ORIENTATION parameter is used and set to LANDSCAPE.
printer "por_or_land"
height 66
width 132
before report esc "(s0P" esc "&k2S" esc "&17.27c66F"
landscape esc "&110"
after page control(L)
return ""
linefeed control(J)
code "bold on" esc "(s7B"
code "bold off" esc "(s0B"
code "underline on" esc "&dD"
code "underline off" esc "&d@"
Notice the use of the landscape parameter in the above defintion. This
parameter will only be invoked if the ORIENTATION parameter is used and set
to LANDSCAPE at runtime. If the ORIENTATION parameter is not used or is
instead set to PORTRAIT at runtime then the landscape parameter within this prt
file will be ignored. When the ORIENTATION parameter is set to LANDSCAPE the
escape sequence in the landscape parameter will be sent to the output after the
BEFORE REPORT escape sequence and before the first page. None of the sample
PRT files supplied with the product contain the landscape parameter.
Notice too that if desired a series of escape sequences can be specified for a
parameter in the PRT file. In the above example several escape sequences are
being specified to execute before the report prints by placing them in the
BEFORE REPORT parameter.
CREATING A FLAT FILE
Another common request is to create a file that has absolutely no escape
sequences. This is easy to do with the Oracle Reports Ascii Driver. Again,
you will need to create your own PRT file to do this. See below:
printer "FLATFILE"
height 66
width 80
return ""
linefeed control(J)
*Note: All I did to create this PRT was remove the AFTER REPORT line from
DFLT.PRT.
EMBEDDING ESCAPE SEQUENCES IN YOUR REPORT
Those of you who used SQL*ReportWriter will recall the ability to embed escape
sequences by creating printer codes within your printer driver and then placing
these within the text screens. Oracle Reports character mode runtime allows
you to place printer codes within format objects under the PRINTER CODES tab.
You can specify a printer code to execute either before or after the formatting
of the format object. Prior to V2.5 of Oracle Reports you could only make use
of this functionality when running on an operating system that had a character
mode runtime. With V2.5 you can now make use of this on Microsoft Windows
because the Oracle Reports allows you to simulate running character mode and
make use of the PRT files.
As an example, suppose you want just one particular field in your report to
print in compressed mode. You would first need to create a PRT file like
this:
printer "compress"
height 66
width 80
after page control(L)
return ""
linefeed control(J)
code "123" esc "(s16.66H"
code "456" esc "(s10H"
Then in your report, in the PRINTER CODES selection for the field, place &123
for BEFORE and &456 for AFTER. This will cause the compress escape sequence to
execute BEFORE the object is formatted, thus place that text in compressed mode.
After this object has formatted then the code specified for AFTER will fire
and place text formatted after that in non-compressed mode.
PRINTING WITH THE ORACLE REPORTS ASCII DRIVER (< 2.5.4)
Reports that are formatted and run with the Oracle Reports ASCII Driver can be
sent directly to the printer or sent to file and then printed from the command
line. By default the Oracle Reports Ascii Driver is set up to print to file.
You can easily change this by going into the printers selection from your
windows control panel and changing the direction of the Oracle ASCII Driver.
After you first install Oracle Reports you should see the following entry in
your control panel:
Oracle Reports ASCII Driver on FILE:
You can change the direction to specify a printer:
Oracle Reports ASCII Driver on LPT1
If you are going to use the Oracle ASCII Driver to send reports to both the
printer and filesystem then it is recommended that you can change your
direction to specify a printer because you will then have the choice of
running to either printer or file. (You will see a checkbox choice for FILE.)
If you have it set to FILE then you can only direct to a file.
PRINTING ASCII REPORTS (2.5.4 and above)
Specify DESTYPE=Printer and specify the printer name in the DESNAME parameter,
ensuring the report has been designed with all the settings as described above.
MIGRATING PRINTER DEFINTIONS FROM V1.1 TO V2.5
If you created custom printer drivers in V1.1 you can migrate those to V2.5.
You migrate printer drivers with the same executable you use to migrate V1.1
reports (R25MREP). The dialog box is self-explanatory. All printer
definitions specified in the V1.1 PRINTDEF.DAT file will be migrated to V2.5
PRT files. Currently it is not possible to specify particular definitions, all
will be migrated.
Depending on how many drivers you need to migrate, it may be easier to just
create the new driver from scratch in V2.5. Since the V2.5 printer drivers are
ascii files and no longer require generation like V1.1 it may be faster to just
create a brand new one.
COMMON QUESTIONS/PROBLEMS/BUGS
1.
REP 826 'INVALID PRINTER DEFINITION'
REP 1804 'UNABLE TO OPEN PRINTER DEFINITION FILE'
These errors are caused when running with an initial value for DESFORMAT is
blank or invalid. This parameter must have a value. Initially it is set to
DFLT. If this is removed or replaced with an invalid value then you will get
one of these two errors. Oracle Reports searches for the PRT file specified in
DESFORMAT in your working directory and
then the C:\ORAWIN\REPORT25\PRINTERS directory.
2.
BUG 245170
This bug prevents you from placing comments in your PRT files.
3.
BUG 276944
This bug prevents you from using the PS*.PRT files on Microsoft Windows. The
purpose of these files is to create output that can be read by a postscript
printer when generated through the character mode runtime or with the Oracle
Ascii Driver. Currently these PRT files do work when used on an operating
system with the character mode runtime. These files do not create true
postscript output, but rather output that can be read by a postscript printer.
Creating output with these files is necessary when you only have the character
mode runtime and a printer that will only accept postscript. There probably is
not too much of a need for this on Microsoft Windows. This problem does not
occur with Oracle Reports 2.5.5.
4.
BUG 271801
This bug prevents you from migrating a single driver from V1.1 to V2.5.
Currently, all drivers specified in your printdef.dat file will be migrated.
This may be a little confusing to users who used V2.0 on operating systems
other than Microsoft Windows because V2.0 did allow this. The workaround is to
remove the drivers which you do not require.
5.
BUG 271458
Migrating the V1.1 supplied DECLAND printer defintion causes an error.
Will receive the message: Error in line 27 of file printdef.dat
Last ':' is missing or line ends prematurely
It does result in a prt file though. However the prt file generated does
not work correctly. This is bug 271455.
6.
BUG 271455
After migration to V2.0 or V2.5, the V1.1 DECLAND printer defintion does not
contain the correct escape sequence to place output in landscape. To correct,
modify the BEFORE REPORT clause so it looks like this:
before report esc "[!p" esc "[?21 J" esc "[15m"
TROUBLE SHOOTING
The escape sequences used in this bulletin should work on most HP LaserJet
printers. However, escape sequences are specific to a printer and your printer
manual should be consulted for appropriate escape sequences. If you send your
report to a file and see the escape sequences specified in your PRT file in the
correct place in the output, then Oracle Reports has done its job. If the
report is not printing as expected after verifying this then the problem almost
certainly has to do with the escape sequences used.