Processing Reports outside of SAS Web Report Studio :: SAS(R) 9.3 Intelligence Platform: Web Application Administration Guide, Third Edition

Overview of Processing Reports outside of SAS Web Report Studio

SAS Web Report Studio enables you to run queries against reports and provide the pre-generated, static results to users. From within SAS Web Report Studio, pre-generated reports can be created manually, created on a scheduled basis, or distributed. As an alternative to using SAS Web Report Studio, you can create pre-generated, static versions of reports from the command line by using the report output generation tool. You can then use scheduling software to run the command and update the reports at specified times or intervals. For example, you might use the tool when you want to update reports on a system that does not have SAS Web Report Studio installed. You can also use Platform Suite for SAS or In-process Scheduler to run the report output generation tool and redistribute the report at specified times.

Requirements for Report Batch Processing

These are the requirements for running the report output generation tool:

SAS BI Report Services (previously SAS Query and Reporting Services) must be installed on the system.
To schedule report jobs using Platform Suite for SAS or In-process Scheduler, you must first enable the scheduling of reports. For more information, see Scheduling in SAS.

You can use alternate scheduling software with the report output generation tool. However, if you intend to distribute reports, then you will need Platform Process Manager.
To distribute reports, you must first set up a recipient list. See Setting Up a Recipient List for Report Distribution .
To enable the distribution function in the Report Output Generation tool in environments with multihomed machines, the -Djgroups.bind_addr command should be specified in the Outputgen.ini file. For more information, see Configuring the JGroups Bind Address in SAS Intelligence Platform: Middle-Tier Administration Guide.

The Report Output Generation Tool

There are three modes for running the report output generation tool:

The extract mode extracts prompt information (report parameters) from reports and then writes that information to a specified file. The extract mode is used to generate a file that is then used as input for the batch or burst mode. This two-part process enables you to edit prompt values before you generate a report. Prompts enable users to input report parameters at run time. For example, a prompt for the year can be used to narrow the focus of a sales report.

If you run a report that has prompts and do not provide prompt information, then the report output generation tool uses default prompt values if they have been defined. If no default values have been defined, then the command fails.
The batch mode generates a static report file.
The burst mode distributes a report snapshot to specified recipients. For an overview of distribution using the report output generation tool, see Using the Report Output Generation Tool to Distribute Reports.

Here are the commands for the report output generation tool:

Commands for the Report Output Generation Tool

Platform	Command
Windows	`rptbatch.bat --extract\|--batch\|--burst` <parameters>
UNIX and z/OS	`rptbatch.sh --extract\|--batch\|--burst` <parameters>

You use the report output generation tool (rptbatch.bat on Windows and rptbatch.sh on UNIX and z/OS) to call upon outputgen.exe file in the Windows environment. The rptbatch.bat file is located in the SAS-configuration-directory \Lev1\ReportBatch directory. The outputgen.exe file is located in the SAS-installation-directory \SASBIReportSevices\4.3 directory.

Parameters for the Report Output Generation Tool

The following table describes the parameters for the report output generation tool.

Note: If a parameter value contains one or more spaces, then enclose the value in quotation marks.

Report Output Generation Tool Parameters

Parameter	Description	Mode
`--batch, -a`	Specifies that the tool will run in batch mode.	Batch
`--burst, -b`	Specifies that the tool will run in burst mode.	Burst
`--extract, -e`	Specifies that the tool will run in extract mode.	Extract
`--prompt-sets`	Specifies an .xml file that contains values that are passed to the report when it is run.	All
`--username` <userName>, `-u` <userName>	Is the login ID of a user registered in the metadata repository that is specified with the `--repository` parameter. The user should have all the permissions necessary for generating the report, including permission to access the underlying information maps or stored processes. If you want to run a report that has been saved in a metadata schedule job definition, then provide a trusted account for the `--username` option (for example, sastrust), add the `--trusted` option to indicate that this is a trusted account, and provide the fully qualified ID of the job.	All
`--password` <password>,`-pw` <password>	Is the password that belongs to the user specified for `--username`.	All
`--repository` <repository>,`-r` <repository>	Specifies the name of the SAS metadata repository in which the report resides.	All
`--spring-xml-file` <filePath>,`-sxf` <filePath>	Used at run time to connect to the configuration service. The configuration service is used to obtain metadata connection information such as host, port, user name, mail server host, and port. The `spring.xml` file is in XML format, and is automatically deployed and configured in the SAS-configuration-directory`\Lev1\Applications\SASBIReportServices4.3` directory. Do not edit this file.	All
`--source` <identifier>,`-s` <identifier>	Specifies a value such as a path URL, metadata key, or a fully qualified ID for the following: report (extract and batch mode) job (extract, batch, and burst mode) burst definition (extract, batch, and burst mode) The path URL specifies an individual report or a directory in the report repository using a path URL that starts with SBIP:// and has a root tree name and an entity name. If the report name contains any spaces, the path URL should be enclosed within quotation marks (for example, `"SBIP://METASERVER/Enterprise Reporting/SalesReports` `/MyReport.srx"`). A metadata key specifies an individual report or a directory in the report repository by referencing a unique identifier for a particular metadata object. The advantage of using a metadata key instead of a report URL is that the metadata key remains the same when the report is moved or renamed. A fully qualified ID uses xxxxxxxx.xxxxxxxx notation to identify objects in a metadata repository (for example, A0000001.FR569JWX). The distribution definition is the command that is displayed for the distribution job in the Schedule Manager's properties dialog box. A distribution definition is associated with a single report.	All
`--log-file` <logFilePath>,`-l` <logFilePath>	(Optional) Specifies the path and name of the log file. By default, the command logs to the console.	All
`--log-level` <level>,`-v` <level>	(Optional) Specifies the level of detailed information provided in the log. The value can be one of the following: `debug`, `info`, `warn` , `error`, or `fatal`. The default value is `warn`.	All
`--help, -?`	Prints the syntax for the command.	All
`--prompts-file` <promptsFile>,`-pf` <promptsFile>	(Optional) In extract mode, this option is used to create the prompts file for the report that is specified for `--source`. In batch or burst mode, this is the name and path of the file that contains prompt information for the report to be generated.	All
`--no-pdf, -n`	(Optional) Specifies a Boolean value that indicates whether a PDF file is generated. If this option is not specified, then a PDF is generated.	Batch
`--channels` <channelIdentifiers>,`-ch` <channelIdentifiers>	(Optional) Specifies a comma-separated list of channels to which the report will be published. The channel identifier can be a channel name, metadata key, path URL, or fully qualified ID. Channels are conduits for publishing particular categories of information. You can set up a channel for a particular topic, organizational group, user audience, or any other category.	Batch Burst
`--channel-age` <channel-age> `--ca` <channel-age>	(Optional) Specifies the number of days that the report will remain in the channel before it is deleted. If this parameter is not specified, the report does not expire.	Batch Burst
`--mail-server` <mailServer>,`-ms` <mailServer>	(Optional) Specifies the host name or IP address of the e-mail server that is used to distribute reports.	Burst
`--mail-port` <mailPort>,`-mp` <mailPort>	(Optional) Specifies the port that is used by the e-mail server. Typically, the port value is `25`.	Burst
`--test-run, -t`	(Optional) Specifies a Boolean value that indicates that a test distribution will be performed. This enables you to verify that your distribution configuration is correct.	Burst

Logging Directory Permissions for Report Output Generation Tool

The log file, SASBIReportServices4.3.log, is typically located in the SAS-configuration-directory\Lev1\Applications\SASBIReportServices4.3\Logs directory.

The SASBIReportServices4.3.log file is created when you first run the report output generation tool with default permission.

In order to generate a log file, the user who is running the rptbatch.bat must be granted Read, Write, and Execute permissions for the log directory. If multiple users run the rptbatch.bat, each of those users must be granted Read, Write, and Execute permissions to both the log file and the directory. This access must be granted both to users who run the tool directly from the command line, and any scheduler user such as the LSF user.

Viewing Console Output

To view console output, modify the rptbatch_usermods.bat for Windows or the rptbatch_usermods.sh file (for UNIX and z/OS) to call upon outputgen_console.exe. These files correspond to the rptbatch.bat and the rptbatch.sh file. Any editing should be performed only in the rptbatch_usermods.bat or the rptbatch_usermods.sh file. You can also add command parameters to these files.

Here is an example of the rptbatch_usermods.sh file:

#!/bin/sh
#
# javabatchsrv_usermods.sh
#
# Script for managing the sasapp - Logical SAS Java Batch Server
#
# Uncomment the set  -x to run  in debug mode
# set -x

# Source usermods file
. /local/install/SAS/93/configdirBIDashBIRepsrv/lev1/ReportBatch
/rptbatch_usermods.sh

Quoteme() {
   if [ $# -gt 1 ]; then
      quoteme="\"$*\""
   else
      quoteme=$1
   fi
}

cmd="/local/install/SAS/92/SASBIReportServices/4.3/outputgen"

for arg in "$@" ; do
   Quoteme $arg
   tmp="$quoteme"
   cmd="$cmd $tmp"
done

eval exec $cmd $USERMODS_OPTIONS

The following Java batch server command invokes outputgen.exe with the usermods in the rptbatch_usermods.bat file:

C:\SAS\Config93\Lev1\ReportBatch\rptbatch.bat -spring-xml-file
C:\SAS\Config93\Lev1\Web\Applications\SASBIReportServices4.3\
spring.xml -repository Foundation

Using the Report Output Generation Tool to Distribute Reports

If you have created a report for distribution, then you can use the report output generation tool to perform that distribution.

To distribute reports, follow these steps:

Create a report in SAS Web Report Studio. The report must exist in the metadata repository.
Set up a distribution library and recipient list data set.

Note: You can use PROC SQL to create the data set, and then use SAS Management Console to register the data set. See Create a Recipient List Using PROC SQL.
Use the report output generation tool to distribute the report.

Obtaining the Values for Running the Report Output Generation Tool on Windows and UNIX

To run the report output generation tool for a distribution job at the command line, obtain the command syntax and values from Schedule Manager in SAS Management Console.

To obtain the command syntax and values for a specific distribution job on Windows and UNIX, follow these steps:

In SAS Management Console, navigate to Environment ManagementSchedule Manager.
Expand Schedule Manager node and locate the distribution job that you want to run. Here is an example of the name of a distribution job:

jsaunders_FinanceReport_1261077179801
Click on the distribution job to select it.
Right-click on the distribution job, and select Properties.
In the dialog box that appears, select the Scheduling Details tab.
Click Advanced.
In the Advanced Properties dialog box that appears, retrieve the entire text string by copying it so that you can use this syntax to run the report output generation tool at the command line. Here is an example of a complete text string that you can run at the command line.
```
"C:\SAS\configdir\Lev1\ReportBatch\rptbatch.bat"
--spring-xml-file file:C:\SAS\configdir\Lev1
\Applications\SASBIReportServices4.3\spring.xml
--repository Foundation
--source "A6C9MMI.BO000CFU"
--burst --channel-age 50
--metadata-key "BurstDefinition+omi:\\Foundation\reposname=Foundation
\Transformation;id=A6C9MMI.B0001TUJ"
```
Click Cancel to exit from the dialog box for the distribution job.

Obtaining the Values for Running the Report Output Generation Tool on z/OS

To run the report output generation tool for a distribution job at the command line, follow these steps:

From the Schedule Manager in SAS Management Console, retrieve the server's fully qualified pathname to the generated .in or .jcl file.
Navigate to the SAS-configuration-directory/Lev1/ReportBatch/JCL/ directory.
If an .in file is present, copy the contents of the .in file into the command line text used to run the distribution job.
If an .in file is absent and a .jcl file is present, copy the relevant portion of the command syntax and values from the .jcl file into the command line text used to run the distribution job.

To obtain the command syntax and values for a specific distribution job on z/OS, and run the report output generation tool for the distribution job, follow these steps:

In SAS Management Console, navigate to Environment ManagementSchedule Manager.
Expand Schedule Manager node and locate the distribution job that you want to run. Here is an example of the name of a distribution job:

jsaunders_FinanceReport_1261077179801
Click on the distribution job to select it.
Right-click on the distribution job, and select Properties.
In the dialog box that appears, select the Scheduling Details tab.
Click Advanced.
In the Advanced Properties dialog box that appears, retrieve the server's fully qualified pathname to the generated .in or .jcl file. Make a copy of the complete text string.

You need this information to locate the corresponding .jcl or .in file for it, and run the report output generation tool from the command line. Here is an example of a complete text string:

SAS-configuration-directory/Lev1/ReportBatch/JCL/jsaunders_FinanceReport_1261077179801.jcl
Make a note of the complete text string.
Click Cancel to exit from the dialog box for the distribution job.
Navigate to the SAS-configuration-directory/Lev1/ReportBatch/JCL/ folder on your WebSphere application server.

In the command line text for this distribution job, if all of the text strings are 80 characters or less in length, a .jcl file will be present in the folder. If one or more text strings in the command line text for this distribution job exceed 80 characters, an .in file will be present along with the .jcl file in the folder.
In the SAS-configuration-directory /Lev1/ReportBatch/JCL/ folder, verify whether an .in file is present for the distribution job.
If an .in file is present in the folder, open the .in file and copy the contents of the .in file into the command line text used to run the distribution job. If an.in file is not present in the folder, open the .jcl file. Then, copy the appropriate text from the .jcl file into the command line text used to run the distribution job.
Here is an example of text in a .jcl file that is retrieved and copied into the command line text used to run the distribution job:
```
SH rptbatch.bat --batch
--spring-xml-file  file:C:\SAS\configdir\Lev1\Applications
\SASBIReportServices4.3\spring.xml
--username sastrust@saspw
--password {sas001}VHJ1c3QxMjM=
--repository Foundation
--source A0000001.FR569JWX
```

Report Output Generation Tool Examples

Example: Running a Report

The following command (executed as one line without any breaks) generates a version of the report MyReport.srx:

rptbatch.bat --batch
--spring-xml-file  file:C:\SAS\configdir\Lev1\Applications
\SASBIReportServices4.3\spring.xml
--username sasdemo
--password {sas001}VHJ1c3QxMjM=
--repository Foundation
--source SBIP://METASERVER/MyDepartment/Shared/Reports/MyReport.srx

In the command, the value provided for the source is the fully qualified name of the report.

In the Windows environment, the user name parameter should include the domain name or machine name that is followed by the user name:

--username
<domain>\sasdemo

If you have spaces in the report name, insert the path within quotation marks:

--source
"SBIP://METASERVER/MyDepartment/Shared/Reports/MyReport.srx"

As an alternative, you can specify the report's metadata key instead of the URL. For example, the following command generates a version of the report that is identified by the metadata key:

rptbatch.bat --batch
--spring-xml-file  file:C:\SAS\configdir\Lev1\Applications
\SASBIReportServices4.3\spring.xml
--username sasdemo
--password {sas001}VHJ1c3QxMjM=
--repository Foundation
--source “Report+omi:\\Sales\reposname=Sales\Transformation;
id=A528654F.AY002MVJ”

Example: Running a Scheduled Job

The following command (executed as one line without any breaks) generates the report that is associated with a scheduled job:

rptbatch.bat --batch
--spring-xml-file  file:C:\SAS\configdir\Lev1\Applications
\SASBIReportServices4.3\spring.xml
--username sastrust@saspw
--password {sas001}VHJ1c3QxMjM=
--repository Foundation
--source A0000001.FR569JWX

The value provided for the source is the fully qualified ID for the job.

Example: Using a Prompts File as Input for a Report

Use the extract mode to generate an XML file that contains report prompts. You can then supply the name of the file when you run the report output generation tool in burst or batch mode.

The following command creates an XML file with the prompts extracted from a report named myReport. The command creates the file myPromptFile.xml in C:\temp directory.

rptbatch.bat --extract
--spring-xml-file  file:C:\SAS\configdir\Lev1\Applications
\SASBIReportServices4.3\spring.xml
--username sasdemo
--password {sas001}VHJ1c3QxMjM=
--repository Foundation
--prompts-file c:\temp\myPromptFile.xml
--source SBIP://METASERVER/MyDepartment/Shared/Reports/MyReport.srx

The following command uses the prompts file as input to generate the report.

rptbatch.bat --batch
--spring-xml-file  file:C:\SAS\configdir\Lev1\Applications
\SASBIReportServices4.3\spring.xml
--username sasdemo
--password {sas001}VHJ1c3QxMjM=
--repository Foundation
--prompts-file c:\temp\myPromptFile.xml
--source SBIP://METASERVER/MyDepartment/Shared/Reports/MyReport.srx

Example: Distributing a Report

The following command (executed as one line without any breaks) generates the report associated with the ID value that is specified for the source:

rptbatch.bat --burst
--test-run
--spring-xml-file  file:C:\SAS\configdir\Lev1\Applications
\SASBIReportServices4.3\spring.xml
--source “A5578MBC.AL002DND”

Migrating from the Batch Generation Tool to the Report Output Generation Tool

Comparison Overview

Previous releases of SAS software included a batch generation tool (batchgen.exe). If you created jobs to run batchgen.exe, then you should be able to migrate most of those jobs to the outputgen.exe file, which is invoked by the report output generation tool rptbatch.bat.

In addition to these differences, when you set up the scheduling of jobs, the command that is supplied for the Java Batch server is different. For more information about the command, see Scheduling in SAS.

Parameter Comparison

The following table shows the parameters for batchgen.exe and their rptbatch.bat counterparts:

batchgen.exe and rptbatch.bat Tool Parameters

batchgen.exe			rptbatch.bat (outputgen.exe)
Parameter	Mode (Run, Extract)	Parameter	Mode (Batch, Extract)1
`run`	Batch	`--batch, -a`	Batch
`extract`	Extract	`--extract, -e`	Extract
`-username`	Both	`--username, -u`	Both
`-password`	Both	`--password, -pw`	Both
`-repository`	Both	`--repository, -r`	Both
`-workspaceserver`	Both	Not applicable	Not applicable
`-url \| -file \| -metadatakey`	Both	`--source, -s` Supports the url and metadatakey options, but not the file option.	Both
`-nopdf`	Run	`--no-pdf, -n`	Batch
`-channels`	Run	`--channels, -ch`	Batch
`-logfile`	Both	`--log-file, -l`	Both
`-outputFile`	Extract	No exact equivalent, though `--prompts-file` is used to create a prompts file.	Extract
`-excludePrompts`	Extract	Not applicable	Not applicable
`-recursive`	Extract	Not applicable	Not applicable
1The burst mode is not included in this table because that mode was not supported by the Batch Generation tool.