The data reporter runs in problem state, with a key of 8, and in 31-bit addressing mode. The data reporter must be reenterable. It receives control by a BALR instruction and must save the registers when it receives control and restore the registers when it returns control. Register 13 contains the address of the register save area; register 14 contains the return address; and register 15 contains the entry address.
The data reporter formats each line in the report, using the data placed in the type 79 SMF record by the data gatherer. The RMF™ putline routine is used to perform the actual output operation.
Because the putline routine handles the actual output operations, your data reporter can function identically during a background session, a display session, a display session in hardcopy mode, or an execution of the Postprocessor. The putline routine writes the line to a logical screen buffer for a display session, to a logical screen buffer and an output data set for a display session in hardcopy mode, or to an output data set for a background session or an execution of the past processor. For a display session, the screen is updated to show the lines collected by the putline routine when your data reporter returns control. Note that RMF handles any framing required for the display session user to view all the frames in a multi-frame table report after the data reporter completes its processing.
The data reporter you code can generate either a row report or a table report. The maximum number of header lines is two.
A row report consists of one or two header lines and a single data line. For a row report, RMF invokes the data reporter twice: once to format the header line(s) and once to format the data line. When a row report is executed repetitively, RMF invokes the reporter to format the header line(s) for the first execution; for all subsequent executions, the reporter is invoked to format a data line.
A table report consists of one or two header lines and a variable number of data lines. For a table report, RMF invokes the data reporter once to format both the header line(s) and the data lines. The number of data lines must be less than or equal to the number of relocate blocks created in the SMF record by the data gatherer.
Upon entry to the data reporter, register 1 points to a contiguous list of eleven addresses that point to eleven input parameters. The first address points to the first parameter, the second address points to the second parameter, and so forth. The input parameters are:
First Parameter: A full word entry code that can be either X‘1’ or X‘2’. X‘1’ indicates that the reporter is to format the header line(s) for a row report. X‘2’ indicates, for a row report, that the reporter is to format the single data line. For a table report, the entry code should always be X‘2’, indicating that the reporter is to format both the header line(s) and the data lines.
Third Parameter: The operands, if any, specified by the report user when he requested the report, in the form:
| Operand 1 | Operand 2 |
|---|---|
| LL | text |
When the report has no operands or the report request did not include operands, LL is set to zeros.
Fourth Parameter: The default operands from ERBFMENU or ERBBMENU, in the form:
| Operand 1 | Operand 2 |
|---|---|
| LL | text |
When the report has no operands or no default operands, LL is set to zeros.
Fifth Parameter: The address of the current SMF record buffer; that is, the buffer where the data gatherer has placed the data for the current execution of the reporter.
Sixth Parameter: The address of the previous SMF record buffer; that is, the buffer where the data gatherer placed the data for the previous execution of the report. When the report mode (the second parameter) indicates delta mode, the data fields in the previous SMF record enable your data reporter to calculate the changes that have occurred since the last request for the report.
Seventh Parameter: The first of the two words reserved for the use of your routines.
Eighth Parameter: The second of the two words reserved for the use of your routines.
Ninth Parameter: A byte containing the number of the subpool to use when you issue a GETMAIN to obtain the storage your routine requires.
Tenth Parameter: The address of the RMF putline routine. When the data reporter has formatted a report line, it calls the putline routine to perform the actual output operation.
Eleventh Parameter: The control block address that your data reporter must pass to the putline routine.
The processing your data reporting routine performs is determined largely by the nature of the report for which you are formatting report lines. This processing should include a validation of the entry code. If it is not a valid code, set a return code of 8 in register 15 and return control. If your report is a row report, examining the entry code determines whether your routine has been invoked to format the header line(s) or the data line for the report.
If the report has operands that can be specified when the report is requested, check the third input parameter to determine if the request specified operands. If it did, validate the syntax of the operands; if the syntax is invalid, set a return code of 4 in register 15 and return control. If the request did not specify operands, verify the syntax of the menu default operands passed as the fourth input parameter; if the syntax is invalid, set a return code of 24 in register 15 and return control.
If your report contains fields that are affected by the session mode – either delta mode or total mode – check the second input parameter to determine which mode is in effect. When delta mode is in effect, use the data fields in the previous SMF record buffer (pointed to by the sixth parameter) and the data fields in the current SMF record buffer (pointed to by the fifth parameter) to calculate the changes that have occurred since the last report request.
When your routine has formatted a report line, it should invoke the RMF putline routine to perform the actual output operation. To use the putline routine, perform the following steps:
First Putline Parameter: The record you have formatted, preceded by a two-byte length field. The length specified must not include the two bytes of the length field. The maximum record length is 79 characters. Note that the 3270 field attribute bytes must not be included; RMF supplies these bytes.
Header lines generally contain column headings. These lines are repeated when the terminal user frames forward through a multi-frame table report or when the hardcopy output crosses a page boundary.
Fourth Putline Parameter: The control block address that RMF passed to your data reporter in the eleventh input parameter.
When your data reporter has finished processing, set a return code in register 15 and return control by branching on the contents of register 14. Table 1 shows the possible return codes, their meaning, and the action RMF takes in response to each code.