Click above to get retro games delivered to your door ever month!

Function:    STARTREPORT()

Purpose:     General purpose report format and print control function.

Syntax:      STARTREPORT( [ reportname  [, say_colors  [, msg_color ]]] )

Arguments:   reportname  - Optional character string name of the report.
                           This name can be a name identified in a .PRG
                           module or dynamically retrieved from a pick
                           list of reports in the database REPORTS.DBF.
                           If specified, this name is LOCATEd in the
                           reports definition database REPORTS.DBF.  If
                           not specified or the given name is not found in
                           REPORTS.DBF then the default report
                           configuration is used.  See below for this
                           default configuration.

             say_colors  - Optional character color string in the same
                           format as other Clipper color strings which is
                           used for the report definition window.  Normal
                           text is displayed in the Standard color, and
                           GETs are displayed in the Enhanced color.  If
                           not specified or an invalid parameter is passed
                           the default color settings will be the current
                           SETCOLOR().

             msg_color   - Optional character color string used to display
                           the SAYINBOX() message that the report is being
                           printed.  If not specified or an invalid
                           parameter is passed, the default color is the
                           current Enhanced color setting (that used for
                           GETs).

Returns:     True if all is a go, false otherwise (escaped or canceled)

Description: STARTREPORT() is a high level printer function which
             simplifies the process of formatting printed reports.  Its
             main use is in automating all the steps necessary to set up a
             printer for a report.  It is used in conjunction with the
             REPORTINIT() and STOPREPORT() RLIB functions.  REPORTINIT()
             initializes the printer and reports databases for use by
             STARTREPORT() while STOPREPORT() cleans up printer settings
             when the report is finished.

             In addition to performing the necessary settings to send
             output to a printer, STARTREPORT() pops up a generic report
             configuration window which lets the end user customize the
             appearance of any report.  The STARTREPORT() screen appears
             as follows:


                         +--------------------------------------------+
                         |         REPORT PRINT CONFIGURATION         |
                         |              Destination: PRN              |
                         ---------------------------------------------|
                         | Report Title:         Purchase Requisition |
                         |                                            |
                         | Printer Driver:           Epson FX Printer |
                         |                                            |
                         | Print size (width):                 Normal |
                         | Page orientation:                 Portrait |
                         | Line spacing (lines per inch):       6 LPI |
                         | Top margin (in lines):                   0 |
                         | Bottom margin (in lines):                0 |
                         | Left margin (in columns):                0 |
                         | Report width (in columns):              80 |
                         | Report setup string:                       |
                         +--------------------------------------------+
                           Press S to start, F to format, ESC to quit


             The basic control functions extended to the user are:

                         * Report title and width
                         * Printer driver selection
                         * Page orientation and line spacing
                         * Top, left, and bottom margins
                         * Customized printer control codes

             All of these settings are saved in the REPORTS.DBF database
             so they may be easily retrieved repeatedly.

             For the programmer, STARTREPORT() initializes a set of PUBLIC
             variables which can be used programmatically to control the
             appearance of printed output.  There are two basic sets of
             PUBLIC variables; those that begin with "PRN_" are printer
             control codes and printer information, those that begin with
             "RPT_" are report definition settings.  The complete list is:


             Printer setup information
             prn_name         Descriptive name of the selected printer
             prn_pgheight     Printable page height in inches
             prn_pgwidth      Printable page width in inches
             prn_setup        Printer setup string for the report which is
                              the combination of codes necessary to
                              implement the report format configuration
                              selected.


             Printer control codes (escape sequences)
             prn_reset        Printer reset (initialize) code
             prn_6lpi         Six lines per inch line spacing
             prn_8lpi         Eight lines per inch line spacing
             prn_boldon       Bold print on
             prn_boldoff      Bold print off
             prn_condon       Condensed mode on
             prn_condoff      Condensed mode off
             prn_wideon       Wide print on
             prn_wideoff      Wide print off
             prn_italon       Italics font on
             prn_italoff      Italics font off
             prn_undron       Underline on
             prn_undroff      Underline off
             prn_supron       Superscript on
             prn_suproff      Superscript off
             prn_subson       Subscript on
             prn_subsoff      Subscript off
             prn_portrait     Portrait mode on (Laser only)
             prn_landscape    Landscape mode on (Laser only)


             Report definitions
             rpt_title     Char     User definable title for report
             rpt_width     Num      Report width in columns
             rpt_pitch     Char     "N"=Normal, "C"=Condensed
             rpt_orient    Char     "P"=Portrait, "L"=Landscape
             rpt_space     Num      6=Six LPI, 8=Eight LPI
             rpt_lmarg     Num      Left margin (in columns)
             rpt_tmarg     Num      Top margin (in lines)
             rpt_bmarg     Num      Bottom margin (in lines)
             rpt_setup     Char     User defined additional report setup
                                    string which is sent to the printer
                                    after PRN_SETUP.

             Other
             rpt_popbox    This is the SAYINBOX() saved screen from the
                           prompt that is displayed after the user selects
                           the Startreport() option.  This public variable
                           is used in STOPREPORT() to restore the screen
                           area under the SAYINBOX() message when the
                           report has finished printing.

Notes:       STARTREPORT() performs the following sequence of events:

             1.  Initializes report  "rpt_" PUBLIC variables
             2.  Initializes printer "prn_" PUBLIC variables
             3.  Queries the user for target destination with TARGET()
             4.  Opens the PRINTERS and REPORTS databases, retrieves any
                 existing formats for the named report.
             5.  Pops up a report format description window and asks the
                 user to press "S" to start report or "F" to format.
             6.  If they respond with Start, the printer is set to the
                 specified target with the following sequence:

                    IF .NOT.  target == "CON"
                       SET PRINTER TO (M->rpt_target)
                       SET DEVICE TO PRINT
                       SET CONSOLE OFF
                       SET PRINT ON
                       SET MARGIN TO rpt_lmarg
                       ?? M->prn_reset + M->prn_setup + M->rpt_setup
                    ENDIF

                             * * *   W A R N I N G   * * *

             Always remember to make a call to the STOPREPORT() function
             when you are finished.  When you do all the SET PRINTER stuff
             by hand, you usually remember to end with a corresponding SET
             PRINTER TO to close the print output from a printer or file
             or whatever.  With STARTREPORT() this is done for you, and if
             you do not finish with a call to STOPREPORT(), your
             application will remain directed to wherever you selected
             with TARGET().  If this was to a printer or a file, SET
             CONSOLE will remain off and all screen writes will go to that
             device.  Furthermore, to make it appear everything is screwed
             up, some screen writes will go to the screen; things like
             @...  BOX, RESTORE SCREEN etc, things that write to the
             screen.

             The STOPREPORT() function is included in the STARTREPORT()
             module rather than being contained in a separate library
             module.  Since STOPREPORT() will ALWAYS be called when
             STARTREPORT() is being used it makes sense to include it in
             the same code.

             The STOPREPORT() function issues a form feed and printer
             reset then returns print and device control back to the
             screen.

Example:     *-- instead of lines and lines of code necessary to
             *-- prepare a report, use one function
             IF StartReport()
                DO MyReort
                StopReport()
             ENDIF
             RETURN


             *-- This procedure assumes target output was selected by a
             *-- call to STARTREPORT() which also initializes the printer
             *-- control codes beginning with PRN_
             PROCEDURE MyReport
             ? prn_undron + "C U S T O M E R   S T A T U S" + prn_undroff
             ?
             ?
             ? "Customer: " + BOLD(CUST->name)
             ? "Account#: " + BOLD(CUST->acctno)
             ? "Last Chg: " + BOLD(DTOC(CUST->lastchg))
             ? "Balance:  " + BOLD(TRANSFORM(CUST->balance,"###,###.##"))
             ? "Avail Cr: " + BOLD(TRANSFORM(CUST->availcr,"###,###.##"))
             RETURN


             *-----------------------------------------------------------
             * Function: BOLD()
             * Syntax:   BOLD( string )
             * Assumes:  StartReport() printer control code variables are
             *           visible
             *-----------------------------------------------------------
             FUNCTION Bold
             PARAMETER string
             RETURN prn_boldon + string + prn_boldoff

Source:      RL_START.PRG

See also:    REPORTINIT()