Reports

Appendix D. Report Output Procedures

This appendix explains how to write your own procedure to write or filter report output to a text driver. This function must be installed as a prototyped function; for more information on installation, refer to "Installing Prototyped Functions" in Application Development Guide.

To use an installed output function, specify it in the device file's procedure statement. Use the obuffsize statement to specify a buffer size greater than the default of 256 bytes. Refer to Appendix C, "Report Device Configuration Files," for more information on device configuration files.

Arguments

The output function is declared with two parameters in this order: an integer-type code, and an output buffer.

Integer type code

This parameter can be supplied one of the following arguments:

RW_P_OPEN
RW_P_CLOSE
RW_P_WRITE

Panther calls the function once with RW_P_OPEN, once per line of output with RW_P_WRITE, and once with RW_P_CLOSE.

Output buffer

The second argument is an output buffer:

When the type code is RW_P_WRITE, the buffer contains a line of output, terminated by the NEWLINE and NULL characters. Your procedure can modify the contents of the buffer.
When the type code is RW_P_OPEN, the buffer contains the initialization string, as specified in the device file; the string is terminated by the NULL character.
When the type code is RW_P_CLOSE, the buffer contains the reset string, as specified in the device file; the string is terminated by the NULL character.

Note: Because the initialization and reset strings are terminated with the NULL character when passed to the output function, neither can contain this character as part of the string.

Return Values

Custom output procedures should return one of the codes listed in the following table.


Return code	Effect
`SM_RW_OK`	Panther should output the buffer; the developer-written procedure has only filtered or analyzed the data.
`SM_RW_DIDOUTPUT`	Panther should not output the buffer; the developer-written procedure has handled this step.
`SM_RW_ERROR`	Request for Panther to abort the rest of the report.

Invoking the Output Procedure

To use a custom report output procedure, specify the procedure's name in the procedure parameter of the device configuration file. The default size for the output buffer is 256 bytes. You can specify a different size through the obuffsize parameter of the device configuration file.