When you use the SPAWN subroutine, when ReportWriter terminates, you are returned to the point in your application at which you called ReportWriter.
You can use an argument string to specify which report definition and repository files to use, as well as to cause ReportWriter to chain to a program of your choice. If you just want to output an existing report (without going into the ReportWriter application), specify the report name in the argument string. You can also specify whether that report is to be output to the screen, a printer, or a file.
When you spawn ReportWriter, the argument string is assigned to the environment variable RPTUSR. ReportWriter looks at this environment variable to determine which options have been specified.
When you chain to ReportWriter, the argument string can either be assigned to the environment variable RPTUSR or passed in the Synergy SEND statement. The ID in the SEND statement is “RPTUSR.” ReportWriter first looks for a message from the SEND statement. If it doesn’t find one, it checks the RPTUSR environment variable.
The argument string can have up to 200 characters. It has the following syntax:
"[def_file]|[chain_file]|[main_file]|[text_file]|[msg_file]|[lib_file]|[rend_file]|[report] & |[output_location]|[output_file]|[output_format]|[page_header]|[separator]|[link_file]"
Arguments
def_file
(optional) The name of the report definition file. If not specified, ReportWriter searches for the file as described in Creating Report Definition Files. (a)
chain_file
(optional) The name of the program to which ReportWriter is to chain upon termination. (a)
main_file
(optional) The name of the repository main file to use. If not specified, ReportWriter searches for main_file (and text_file, below) as described in Determining the repository files used. (a)
text_file
(optional) The name of the repository text file to use. (a)
msg_file
(optional) The name of the text message file to use. If not specified, ReportWriter attempts to open SYNTXT:syntxt.ism. (a)
lib_file
(optional) The name of the ReportWriter window library to use. If not specified, ReportWriter attempts to open RPTDAT:rptctl.ism. (a)
rend_file
(optional) The name of the renditions file to use. (a)
report
(optional) The name of an existing report to be output. (a)
output_location
(optional) Determines the output location as follows: (n)
0 = Output goes to the screen. (default)
1 = Output goes to the printer.
2 = Output goes to a file.
output_file
(optional) The name of the output file to generate. Specify this argument only if output_location is 2. If output_location is 2 and an output file is not specified, you will be prompted for the output filename and format. (a)
output_format
(optional) If you specified 2 for output_location, specify an output format as follows: (n)
0 = Output is generated in report form (including headers, footers, and the like). (default)
1 = Output consists of detail record data only. (See Generating a report to a file for more information on the two available output formats.)
2 = Output consists of detail record data only and is output in a spreadsheet format. ReportWriter looks for the page_header and separator arguments.
page_header
(optional) Determines if a spreadsheet has a page header generated as the first record of the report. Specify this argument only if output_format is 2. (n)
0 = No page header will be generated. (default)
1 = Page header will be generated.
separator
(optional) Determines the separator used for spreadsheet output. Specify this argument only if output_format is 2. If not specified, the separator character defaults to a comma. (n)
1 = Comma (default)
2 = Tab
3 = Space
4 = Semicolon
link_file
(optional) The name of the name link file to use. (a)
Discussion
Arguments must be separated by either a vertical bar ( | ) or a backslash (\). (Do not mix vertical bars and backslashes in the same SEND statement.) The vertical bar or backslash must also be used as a placeholder for omitted arguments. (See Examples below.) If you have a vertical bar anywhere in your command string, it will be used as the argument delimiter. On Windows, because the backslash character is used as a directory separation character, we recommend you use a vertical bar as an argument delimiter.
All filenames can include a logical (for example, RPT:rptctl). The maximum length of each filename is 64 characters.
If you specify the chain_file argument, ReportWriter displays a blinking “Working...” message when chaining to the other program. If you want to change the text of this message or clear it entirely, you can modify the text message file. For instructions see Synergy UI Toolkit Control Panel (synctl).
If you have specified a report definition name or Repository filenames using either the RPTUSR environment variable or the SEND/RECV message (as described in Spawning ReportWriter and Chaining to ReportWriter below), those filenames have precedence over the default selection logic used by the def_file, main_file, and text_file arguments.
The report name is optional. If you pass a report name, ReportWriter generates the report and then either chains to the specified program or stops. If you pass a report name that doesn’t exist, an error message is displayed, and then ReportWriter either chains to the specified program or stops.
If you are chaining to ReportWriter from a non-Synergy application, you must clear the screen before you chain.
If you are chaining to ReportWriter on a multi-user system, we recommend that you pass the terminal number as the third argument in the Synergy SEND statement to ensure the message is received by the correct ReportWriter process.
Here are some examples of valid argument strings:
"RPT:reports.rpt|myfile.dbr" "|myfile.dbr||||RPT:rptctl" "RPT:reports.rpt\myfile.dbr\\\\\\myrpt\1"
Spawning ReportWriter
There are two methods for spawning ReportWriter.
- This method enables you to change the argument string dynamically and specify any of the optional arguments for ReportWriter within your application. Argument_string is explained in Spawning and chaining to ReportWriter.
Set the RPTUSR environment variable as follows:
xcall setlog("RPTUSR", argument_string, sts)
if (sts)
xcall spawn("dbr RPT:rpt")
- This method is useful when you want to change your RPT environment temporarily, without setting and resetting RPT environment variables.
Set the RPTUSR environment variable to your argument string before you run your application. And add the following line to your application:
xcall spawn ("dbr RPT:rpt")
Chaining to ReportWriter
There are two methods for chaining to ReportWriter. Argument_string is explained above in Spawning and chaining to ReportWriter.
- To use the SEND statement, modify your code as follows:
send(argument_string, "RPTUSR")
stop "RPT:rpt"
In the SEND statement, “RPTUSR” is the message ID of ReportWriter.
- To use the RPTUSR environment variable, set it as follows:
xcall setlog("RPTUSR", argument_string, sts)
if (sts)
stop "RPT:rpt"
