PROCESS REPORTER

`PROCESS` `REPORTER ACTION`

		`INITIALIZE`
		`TERMINATE`
		`OPEN`
		`CLOSE`
		`REPLACE-TABLE`			`operand1`
		`SET-PRINTER`		`WITH`
		`SET-PRINT-OPTIONS`			`PARAMETERS-clause`
		`PRINT`
		`PREVIEW`
		`EDIT`	`WITH`	`operand1`
				`PARAMETERS-clause`
	[`GIVING` `operand2`]

This document covers the following topics:

Function
Syntax Description
Examples

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Function

The PROCESS REPORTER statement is used to communicate with the Natural Reporter from within a program, instructing the reporter to perform a particular action.

For a description of the reporter, please refer to the Natural Reporter online help.

Note:
For actions that apply to a specific report, you may abbreviate the second keyword to REPORT. This is only to enhance the readability of your programs; Natural does not distinguish between the written-out and abbreviated forms of the keyword.

Syntax Description

Operand Definition Table:

Operand	Possible Structure					Possible Formats													Referencing Permitted	Dynamic Definition
`operand1` *	C	S				A		N	P	I	F	B	D	T	L				yes	no
`operand2`		S						N	P	I									yes	no

* The structure and format actually possible depend on the action to be performed.

Syntax Element Description:

Syntax Element	Description
`ACTION`	Actions: You can specify one of the following actions to be performed by the reporter:
`INITIALIZE`	Initialize Reporter: This action initializes and loads the reporter. This must always be the first action to be performed.
`TERMINATE`	Terminate Reporter: This action terminates and unloads the reporter. This must always be the last action to be performed.
`OPEN`	Open Report: This action opens a specified report, and returns a handle which can be used to identify the report for subsequent actions.
`CLOSE`	Close Report: This action closes a specified report, after which the report handle can no longer be used.
`REPLACE-TABLE`	Replace Table: This action replaces the path name of a table.
`SET-PRINTER`	Select Printer: This action selects a printer to be used for subsequent printing of all reports. The print method for the selected printer must be set to `TTY` in `NATPARM`.
`SET-PRINT-OPTIONS`	Set Print Options: This action is used to set print options for a specified report.
`PRINT`	Print Report: This action prints a specified report on the currently selected printer.
`PREVIEW`	Preview Report: This action previews a specified report, based on the currently selected printer.
`EDIT`	If no report is specified, this action shows the main reporter window. If a report is specified, this action shows the main reporter window together with the edit window for the specified report.
`WITH`	WITH Clause: As `operand1`, you specify the parameter(s) to be passed to the action.
`PARAMETERS-clause`	PARAMETERS Clause: Alternatively to the `WITH` clause, you can use the `PARAMETERS clause` described below.
`GIVING operand2`	GIVING Clause: With the `GIVING` clause, you can retrieve the response code from the invoked action. As `operand2`, you specify the field to receive the response code. The response code is returned in format/length I4. Response code 0 indicates that the action was successful. Any other response code corresponds to a Natural system error number (`NATnnnn`).

PARAMETERS Clause

PARAMETERS {parameter-name=operand1}

END-PARAMETERS

With this clause, you specify the parameter(s) by name (instead of by position):

Parameters for OPEN Action
Parameters for REPLACE-TABLE Action
Parameter for SET-PRINTER Action
Parameters for SET-PRINT-OPTIONS Action
Parameters for CLOSE, PRINT, PREVIEW, EDIT Actions

Parameters for OPEN Action

For this action, you specify as first parameter the name of the report to be opened (without .rpt extension or path specification), and as second parameter the field to receive the handle. The format/length of the first parameter must be compatible with A8, that of the second parameter with I4.

The report is searched for in the logon library's RES subdirectory first, then in the RES subdirectory of each steplib, then in the directory assigned to the environment variable NATGUI_BMP.

Note that the report data is first searched for in the path specified when the report was created (if it exists), then in the directory in which the report was found.

If you use the PARAMETERS-clause, the parameter-name must be:

REPORT-NAME for the report name
REPORT-ID for the handle field

Parameters for REPLACE-TABLE Action

For this action, you specify as first parameter the handle identifying the report to which the action is to be applied, as second parameter the work file number, and, optionally, as third parameter the table name. The format/length of the first two parameters must be compatible with I4, that of the third parameter with A8.

If you use the PARAMETERS-clause, the parameter-names must be REPORT-ID, WORK-FILE and TABLE-NAME respectively.

Parameter for SET-PRINTER Action

For this action, you specify as operand1 the logical device name (LPT1 to LPT31) of the printer to be selected. The format/length of operand1 must be compatible with A8.

If you use the PARAMETERS-clause, the parameter-name must be DEVICE-NAME.

Parameters for SET-PRINT-OPTIONS Action

For this action, you specify as first parameter (No. 1 in the table below) the handle identifying the report to which the action is to be applied, followed by the printer options to be set - all of which are optional. If a parameter is omitted, the corresponding option remains unchanged.

Sequence No.	Parameter
1	This parameter (which must be compatible with format/length I4) is the handle identifying the report to which the action is to be applied. The `parameter-name` must be `REPORT-ID`. ^*
2	This parameter (which must be compatible with format/length I2) is one of the paper-size constants defined in the local data area `NGULKEY1`. The possible values here are: `CUSTOM-PAPER` (use explicit paper width and height) `LETTER` (8.5 x 11 inches) `LEGAL` (8.5 x 14 inches) `EXECUTIVE` (7.25 x 10.5 inches) `A4` (210 x 297 mm) `COM-10-ENVELOPE` (4.125 x 9.5 inches) `DL-ENVELOPE` (110 x 220 mm) `C5-ENVELOPE` (162 x 229 mm) `B5-ENVELOPE` (176 x 250 mm) `MONARCH-ENVELOPE` (3.875 x 7.5 inches) The `parameter-name` must be `PAPER-SIZE`. ^*
3 and 4	These parameters (which must be compatible with format/length I2) are the paper width and height respectively (in twips; 1 twip = 1/1440 inches). These parameters are only used with paper size `CUSTOM-PAPER`. If you use the `PARAMETERS-clause`, the `parameter-names` must be `PAPER-WIDTH` and `PAPER-HEIGHT`, respectively.
5, 6, 7 and 8	These parameters (which must be compatible with format/length I2) specify the left, top, right and bottom margins respectively (in twips). The `parameter-names` must be `LEFT-MARGIN`, `TOP-MARGIN`, `RIGHT-MARGIN`, `BOTTOM-MARGIN`, respectively.
9	This parameter (which must be of format L) is the paper orientation: `TRUE` = landscape `FALSE` = portrait This parameter is not used with paper size `CUSTOM-PAPER`. The `parameter-name` must be `LANDSCAPE`. ^*
10	This parameter (which must be of format L) is the fast (text only) print option: `TRUE` = suppression of graphics `FALSE` = no suppression The `parameter-name` must be `FAST-PRINT`. ^*
11	This parameter (which must be of format L) determines whether records that consist entirely of blanks are to be suppressed in the output: `TRUE` = suppression `FALSE` = no suppression The `parameter-name` must be `SUPPRESS- BLANK-LINES`. ^*
12	This parameter (which must be of format L) determines whether successive records with identical data are to be ignored: `TRUE` = ignore `FALSE` = do not ignore The `parameter-name` must be `IGNORE-DUPLICATES`. ^*
13	This parameter (which must be of format L) determines whether a printer selection dialog is to be displayed during printing: `TRUE` = display `FALSE` = no display The `parameter-name` must be `SHOW-PRINT-DIALOG`. ^*
14	This parameter (which must be compatible with format/length I2) is one of the paper-source constants defined in the local data area `NGULKEY1`. The possible values here are: `AUTOMATIC` = automatic feed `MANUAL` = manual feed The `parameter-name` must be `PAPER-SOURCE`. ^*

Note:
^* If you use the PARAMETERS-clause.

Parameters for CLOSE, PRINT, PREVIEW, EDIT Actions

For these actions, you specify as operand1 the handle identifying the report to which the action is to be applied. The format/length of operand1 must be compatible with I4.

If you use the PARAMETERS-clause, the parameter-name must be REPORT-ID.

Examples

Example 1 - Parameters for OPEN Action
Example 2 - Parameters for REPLACE-TABLE Action
Example 3 - Parameter for SET-PRINTER Action
Example 4 - Parameters for SET-PRINT-OPTIONS Action
Example 5 - Parameters for CLOSE, PRINT, PREVIEW, EDIT Actions

Example 1 - Parameters for OPEN Action

PROCESS REPORT ACTION OPEN WITH 'MYREPORT' #HANDLE

PROCESS REPORT ACTION OPEN WITH
  PARAMETERS
    REPORT-NAME = 'MYREPORT'
    REPORT-ID   = #HANDLE
  END-PARAMETERS

Example 2 - Parameters for REPLACE-TABLE Action

PROCESS REPORT ACTION REPLACE-TABLE WITH
  PARAMETERS
    REPORT-ID = #HANDLE
    WORK-FILE = 5
  END-PARAMETERS

Example 3 - Parameter for SET-PRINTER Action

PROCESS REPORTER ACTION SET-PRINTER WITH 'LPT1'

Example 4 - Parameters for SET-PRINT-OPTIONS Action

DEFINE DATA LOCAL
  USING 'NGLUKEY1'
END-DEFINE
...
PROCESS REPORT ACTION SET-PRINT-OPTIONS WITH #HANDLE
  A4 0 0 0 0 0 0 FALSE FALSE FALSE FALSE FALSE AUTOMATIC

DEFINE DATA LOCAL
  USING 'NGLUKEY1'
END-DEFINE
...
PROCESS REPORT ACTION SET-PRINT-OPTIONS WITH PARAMETERS
  REPORT-ID = #HANDLE
  PAPER-SIZE = A4
  PAPER-WIDTH = 0
  PAPER-HEIGHT = 0
  LEFT-MARGIN = 0   TOP-MARGIN = 0
  RIGHT-MARGIN = 0  BOTTOM-MARGIN = 0
  LANDSCAPE = FALSE
  FAST-PRINT = FALSE
  SUPPRESS-BLANK-LINES = FALSE
  IGNORE-DUPLICATES = FALSE
  SHOW-PRINT-DIALOG = FALSE
  PAPER-SOURCE = AUTOMATIC
END-PARAMETERS

Example 5 - Parameters for CLOSE, PRINT, PREVIEW, EDIT Actions

PROCESS REPORT ACTION PRINT WITH #HANDLE
PROCESS REPORT ACTION PREVIEW WITH #HANDLE
PROCESS REPORT ACTION CLOSE WITH #HANDLE
PROCESS REPORT ACTION EDIT WITH #HANDLE
PROCESS REPORTER ACTION EDIT