Difference between revisions of "TREPORT"

Latest revision as of 09:26, 23 August 2011

Purpose

Free format text based report writer

Syntax

TREPORT FROM <.trf filename> | (<expC>)

[FOOTER <expC1>, <expC2>, <expC3>]

[HEADING <expC4>, <expC5>, <expC6>]

[LPP <expN>]

[TO FILE <.txt filename> | (<expC>)]

[TO PRINT]

[TO TERMINAL]

Description

TREPORT is a free format text based report writer, which formats a file of text and commands written in the TREPORT report definition language (RDL). Reports defined in RDL can extract data from one or more tables.

FOOTER <expC1>,<expC2>,<expC3>

The FOOTER clause specifies a footer line to appear at the bottom of each report page. The character expression <expC1> represents text to appear on the left side of the footer line. Expression <expC2> represents text to appear in the center of the footer line, and <expC3> will appear on the right side of the footer line. The FOOTER clause is synonymous with the #FOOTER report definition language directive.

HEADING <expC4>,<expC5>,<expC6>

The HEADING clause specifies a heading line to appear at the top of each report page. The character expression <expC4> represents text to appear on the left side of the heading line. Expression <expC5> represents text to appear in the center of the heading line, and <expC6> will appear on the right side of the heading line. The HEADING clause is synonymous with the #HEADING report definition language directive.

LPP

The LPP clause is used to specify the number of lines per page. The numeric expression <expN> represents the number of lines. By default the number of lines is 60.

TO FILE <file>

If the TO FILE <.txt filename> clause is specified, then the report is output to a file, which can be printed later with the PRINT command. The file name can be substituted with an <expC>, enclosed in round brackets, which returns a valid filename. If no file extension is specified, '.txt' is used.

TO PRINT

If the TO PRINT clause is specified, the report is output to the printer. The printer can be assigned to be the system printer, a location specific printer, or a printer attached to the printer port of the issuing terminal. See the SET PRINTER TO command for full details.

TREPORT operates by reading the specified <.trf filename> and formatting the free format text contained within it, as specified by the RDL directives which are intermingled within the text. The text contained in the <.trf filename> can be printed in bold or underlined. To define text to be printed in bold, surround the text with ^B and ^ (e.g. ^BHAMLET^ would be printed in bold). To define text to be printed underlined, surround the text with ^S and ^ (e.g. ^SHAMLET^ ) would be printed underlined. The RDL contains a wide range of directives. These directives are defined by preceding them with a '#' character. There must be no space between the '#' character and the RDL directive. RDL directives can be entered in upper or lower case.

Lines of text which do not have '#' as the first printable character, are output just as they appear in the <.trf filename>. & macro substitution is performed on each line as it is read from the <.trf filename>. You can indent directives to assist in the readability of the RDL program. You can also use Recital/4GL expressions as the arguments to RDL directives.

Report Definition Language (RDL)

The following RDL layout directives are available:

#HEADING "'<left>'<middle>'<right>'"

The HEADING, or HD directive defines a one line heading to appear at the top of each report page. The heading is specified in three parts. The <left> part is displayed at the leftmost side of the page. The <right> part is displayed at the rightmost side of the page, and the <middle> part is displayed in the center of the page. If '#' appears in any of the heading text, it is replaced with the current page number.

#HEADING2 "'<left>'<middle>'<right>'"

THE HEADING2, or HD2 directive defines a one line heading to appear below the HEADING line. The heading is defined in the same way as HEADING. If the '#' character appears in any of the HEADING2 text, it is replaced with the current page number.

#HEADER_START...#HEADER_END

#HEADER_START

#HEADER_END

The HEADER_START...HEADER_END, or HS...HE directives define a block of text to be displayed as a header below the HEADING line at the top of each page. & macro substitution is not performed until the header block is processed. This allows & macros to be included in the header block.

#FOOTER "'<left>'<middle'<right>'"

The FOOTER, or FO directive defines a one line footer to appear at the bottom of each report page. The FOOTER text is defined in the same way as HEADING. The <left> part is displayed at the leftmost side of the page. The <right> part is displayed at the rightmost side of the page, and the <middle> part is displayed in the center of the page. If '#' appears in any of the footer text, it is replaced with the current page number.

#FOOTER_START...#FOOTER_END

#FOOTER_START

#FOOTER_END

The FOOTER_START...FOOTER_END, or FS...FE directives define a block of text to be displayed as a footer above the FOOTER line at the bottom of each page. & macro substitution is not performed until the footer block is processed. This allows & macros to be included in the footer block.

#NEEDLINES <expN>

The NEEDLINES, or NE directive informs TREPORT that if less than <expN> lines are available at the bottom of the current page, then it should eject to the next page. This directive is used when you want to keep a block of text together on the same page, rather than split it across a page boundary.

#BLANKLINES <expN>

The BLANKLINES, or SP directive outputs <expN> blank lines in the report.

#CENTRE_ON [(<expN>)]

The CENTRE_ON, or CE directive instructs TREPORT to center all text lines from the next line onwards. The optional numeric expression <expN> may be used to specify a line length in which to center the text. The default line length for centering is 80 characters.

#CENTRE_OFF

The CENTRE_OFF, or CF directive instructs TREPORT to turn off centering of text lines.

#MACROS_ON

The MACROS_ON, or MO directive instructs TREPORT to macro substitute field names that are prefixed with the '?' character.

#MACROS_OFF

The MACROS_OFF, or MF directive instructs TREPORT to turn off macro substitution of field names prefixed with the '?' character.

#NUMBER_ON

The NUMBER_ON, or NO directive instructs TREPORT to number each remaining text line from the <.trf filename>. This directive can be used to produce program listings to include in system documentation. The line numbers restart at 1 each time NUMBER_ON is encountered.

#NUMBER_OFF

The NUMBER_OFF, or NF directive turns off line numbering which has been turned on with NUMBER_ON.

#LINESPACING <expN>

The LINESPACING or LS directive defines the spacing between lines in the report. A LINESPACING of 2 will produce a double spaced report.

#INDENT <expN>

The INDENT, or IN directive defines an indentation of <expN> spaces from the left margin. To stop the indentation, specify a second INDENT directive.

#EJECT

The EJECT, or BP directive ejects to the head of the next page. The footer is output at the bottom of the current page, and the header is displayed at the head of the next page. This directive should only be used if you specifically want to "force" a page eject, as TREPORT handles pagination automatically.

#LEFTMARGIN <expN>

The LEFTMARGIN, or PO directive defines the left margin offset where the printer report lines should start. TREPORT pads lines out to the required column before outputting them.

#LINELENGTH <expN>

The LINELENGTH, or LL directive defines the maximum width of a line of text. Lines that are wider than LINELENGTH are truncated.

#TEMPINDENT <expN>

The TEMPINDENT, or TI directive defines an indentation of <expN> for the next line only. Following processing of the next line, indentation will return to that defined with the INDENT directive.

#SUBTITLE <expC>

The SUBTITLE, or SH directive is used to output a subtitle as specified by <expC>. The SUBTITLE directive is processed as follows: if there are less than 3 lines left on the current page then eject to the next page, output one blank line, output the specified text <expC>, then output one more blank line.

#PAGELENGTH <expN>

The PAGELENGTH, or PL directive defines the number of lines to be placed on each output page of the report. The number specified in <expN>, is reduced by 3, to leave space for HEADING, HEADING2, and FOOTER. By default, PAGELENGTH is 60.

#PARAGRAPH

The PARAGRAPH, or PP directive is processed in the following way: if there are less than 2 lines left on the current page then eject to a new page, output one blank line, then set a temporary indentation of 4 spaces.

The following RDL processing directives are available:

#SINGLE_SHEET

The SINGLE_SHEET, or SS directive informs TREPORT that the report is to be printed on a printer which does not have an automatic sheet feeder. Whenever a new page is ejected, TREPORT asks you to place the next sheet in the printer, then press the RETURN key.

#TRANSLATE "<expC1>,<expC2>"

The TRANSLATE directive is used to translate the meaning of a significant character to a different character. The <expC1> is the character whose meaning you wish to translate. The <expC2> is the character you wish to translate to.

#INCLUDE "<.trf filename>"

The INCLUDE, or SO directive causes TREPORT to read the specified <.trf filename> and process the text or RDL directives contained within it.

#EXECUTE <command>

The EXECUTE, or EX directive is used to execute a Recital/4GL command. EXECUTE is normally used to perform report calculations. Typical commands used with EXECUTE are SKIP, SEEK, and STORE. You should not execute TREPORT from an EXECUTE directive. Any output from the Recital/4GL command executed with EXECUTE is not included in TREPORT formatting.

#IF...#ELSEIF...#ELSE...#ENDIF

#IF <condition>

#ELSEIF

#ELSE

#ENDIF

The IF...ELSEIF...ELSE...ENDIF directives conditionally process the text and RDL directives of a <.trf filename>, depending upon the specified <condition>. The ELSE and ELSEIF blocks are optional. IF...ELSEIF...ELSE...ENDIF may contain other IF...ELSE...ENDIF directives as well as DO WHILE...ENDDO repetition directives.

#DO WHILE...#ENDDO

#DO WHILE <condition>

#ENDDO

The DO WHILE...ENDDO directives repeatedly process the <text or RDL directives> until the specified <condition> is .F. These directives are typically used in conjunction with the EXECUTE directive.

#SCAN FOR...#ENDSCAN

#SCAN FOR <condition>

#ENDSCAN

The SCAN FOR...ENDSCAN directives locate all records that match the <condition> and repeatedly process the <text or RDL directives> until the specified <condition> is .F.. These directives are typically used in conjunction with the EXECUTE directive.

#! <comment line>

The ! directive allows comments to be included in the <.trf filename>. Text contained on a ! line is not formatted, but can be used to improve the readability and maintainability of the RDL program.

Example

#!**********************************************
#!* REPORT IDENTIFICATION SECTION*
#!**********************************************
#! FILE : patrons.trf
#! PURPOSE: report for event HAMLET
#!
#!*************************************
#!* REPORT LAYOUT SECTION *
#!*************************************
#macros_on
#execute store date() to today
#heading "'HAMLET'Patron List'&today'"
#heading2 "'------'-----------'--------'"
#header_start
NAME OF              NUMBER OF           ADDRESS OF
PATRON                SEATS                      PATRON
=====                      ====                        ====
#header_end
#!
#footer_start
 
----------
Total patrons this page: &m_totpatrons
Total seats sold this page:  &m_totseats
#footer_end
#footer "''- # -''"
#!
#!********************************************
#!* REPORT PROCESSING SECTION *#!********************************************
#execute use patrons index events,dates,names
 
The following report provides details of the patrons who attended the showing of ^BHAMLET^.
This is a summary report only; a full report is also available if you need it.
#execute store 0 to m_totpatrons
#execute store 0 to m_totseats
#ex seek "HAMLET"
#do while event="HAMLET"
#needlines 4
 
?name?seats ?street
?city?postcode
#execute store m_totpatrons+1 to m_totpatrons
#execute store m_totseats+m_seats to m_totseats
#ex skip
#enddo
#execute use
#! ** End of TREPORT definition **

Products

Recital Server, Recital