Reference Manual

Report functions

Functions to produce reports are contained in the report.4gl module. The following example shows a typical program stub to produce a basic report:

call reportopen('myreport','')
call reportinit('')
foreach ...
let rline=item1,column 12,item2,column 50,item3
call reportput(rline)
end foreach
call reportsetup('')
while true
call reportman() returning action, rowid
case action
when 'exit' exit while
end case
end while
call reportclose()

The report object is initialized with 'reportopen' which supplies the report title and opens a full-screen window. A message box containing a 'reporting' message is opened with 'reportinit' which also prepares the report internally so that report lines can be entered with 'reportput'. When all the report lines have been entered, 'reportsetup' closes the message box and displays the first screen of the report.

User responses are handled by 'reportman', which returns some of them for the calling program to handle, along with the current rowid (in the internal report temporary table).

Finally, the report object is removed with 'reportclose'.

Following are more detailed descriptions of the functions in the pick-list system (ordered by approximate importance):

Reportopen

Initializes a report object with a title and opens a full-screen window.

2 parameters:
Title: A title string or a key into the title text file. More than one title line can be defined in the title text file.
Width: The report width. If not specified, the report width is set to at least the widest title line.

Reportinit

Sets up a message box which remains open while the report is being assembled. An internal temporary table is created to house the report lines.

1 parameter:
Message: A message string or a key into the message text file. The message is displayed in the message box. The default value is 'reporting'.

Reportput

Adds a simple report line of text to the report.

1 parameter:
Text: The report line text.

Reportfputrow

Adds a report line of text to the report, with options.

4 parameters:
Format: Character formatting string to produce combinations of bold, italic and underline enhancements to parts or all of a line.
Text: The report line text.
Skip: The number of lines to skip before printing the text line. Skipped lines do not appear on the screen version of the report in order to save space.
Need: The number of available lines needed to print the text line on that page. Otherwise the text line is printed on the next page.

1 return value:
Rowid: The rowid in the report temporary table associated with the text line. This can be remembered by the calling program if it intends to update the text line later in the report assembly.

The character formatting string is a combination of numbers representing lengths of text to be enhanced, and enhancement codes, which can be:
B = Bold on.
b = Bold off.
I = Italics on.
i = Italics off.
U = Underline on.
u = Underline off.
For example: If the format string is '20BI30iU40biu' then the first 20 characters will be normal, the next 30 characters will be bold and italic, the next 40 lines will be bold and underlined, and the characters beyond that will be normal.

Reportline

Adds a full width line of repeated characters to the report. This is typically used to insert line breaks in reports.

5 parameters:
Format: Character formatting string to produce combinations of bold, italic and underline enhancements to parts or all of a line.
Text: The text which is to be repeated.
Length: The length of text to be repeated.
Skip: The number of lines to skip before printing the text line. Skipped lines do not appear on the screen version of the report in order to save space.
Need: The number of available lines needed to print the text line on that page. Otherwise the text line is printed on the next page.

Reportupd

Modifies the text of a report line.

2 parameters:
Rowid: The rowid of the line to be updated in the report temporary table.
Text: The modified text of the line to be updated.

Reportsetup

Indicates the end of the report assembly. The message box is closed and the first page of the report is displayed on the screen.

1 parameter:
Print flag: Indicates whether the user should be warned upon attempted exit from the report without having printed out the report. The default value is false (the user is not warned).

Reportman

Handles user responses to an on-screen report.

2 return values:
Action: A string containing a logical user response that the calling program can act on. Possible responses are and typical uses are as follows:
'enter' = Vew more details of a report line in a window.
'refresh' = Reassemble the report (with the latest database values).
'exit' = Exit the report function.
'filter' = Edit the report selection criteria (followed by report reassembly).
'other' = Other operations, perhaps a menu offering some possibilities.
'prevset' = Regenerate the report with the previous logical set of data.
'nextset' = Regenerate the report with the next logical set of data.
Rowid: The current line number.

Other user responses like 'help', 'print', 'opsys', 'file', cursor movement keys and more are handled automatically within 'reportman'.

Reportclose

Removes the report object, closing the report window and all database cursors.

Reporthead

Displays title text dynamically. This function can be called after a report has been opened to change title lines.

2 parameters:
Text: The new title text to be displayed.
Line: The title line number affected.

Reportprinter

Sets up the name of the default printer to be used in the report. This name will then appear in the print dialogue box when the user presses the logical key 'print'.

1 parameter:
Name: The name of the default printer.

Reportcovput

Adds a simple line of text to the cover sheet.

2 parameters:
Format: Character formatting string to produce combinations of bold, italic and underline enhancements to parts or all of a line.
Text: The report cover line text.

Reportcovtime

Adds timing information to the cover sheet. Included are start and finish times, the real time interval from start to finish, and the CPU time.

Reportcovtext

Adds the contents of a flat file to the cover sheet. This is typically used to include help information about the report, such as explanations of abbreviations used etc.

3 parameters:
Filename: Character formatting string to produce combinations of bold, italic and underline enhancements to parts or all of a line.
Begin: The starting paragraph to be included, which defaults to the first paragraph.
End: The ending paragraph to be included, which defaults to the last paragraph.

Paragraphs are delimited by blank lines. By specifying paragraph numbers, lines can be added to a paragraph without having to alter the accessing program.

Reportget

Retrieves the text from a report line. This is typically used if a viewing window is to be opened, in which case key information may need to be retrieved from the selected line.

1 parameters:
Line: The report line number.

1 return value:
Text: The report line text.

Reportview

Handles a viewing window that has been created. This is typically used when the user has pressed the logical key 'enter' to view a selected line of a report in more detail. After the calling program opens the window and displays the data, it can call this function to handle standard user inputs. An example of this follows:

... {open form/window}
while not done
let text=reportget(rline)
... {retrieve and display additional information}
while true
call reportview('form',rline,'') returning action,rowid
case action
when 'refresh' exit while
when 'exit'
let done=true
exit while
end case
end while
end while
... {close form/window}

The 'reportview' function handles most user responses. The user can page through the report lines in the viewing window.

3 parameters:
Name: A string value which is used to display a title in the viewing window and to select the appropriate help text.
Line: The current report line number.
Text: Message that appears in the viewing window.

2 return values:
Action: A string containing a logical user response that the calling program can act on. Possible responses are and typical uses are as follows:
'exit' = Exit the pick-list function without returning the row.
'other' = Other operations, perhaps a menu offering some possibilities.
'refresh' = Refresh the viewing window (possibly the next/previous row).
Line: The number of the report line to be viewed next.