9 Defining Report Sets

This section contains information on the following topics:

Figure 9-1 Process of Creating a Report Set Definition and Instance

Description of Figure 9-1 follows
Description of ''Figure 9-1 Process of Creating a Report Set Definition and Instance''

About Report Sets

A Report Set provides a way to organize, manage, and run a set of reports together under version control. You can define numbered chapters, sections within the chapters, and any number of levels of subsections, with reports and/or narrative text at any level. When you choose to use postprocessing, the Oracle Life Sciences Data Hub (Oracle LSH) generates a table of contents and hyperlinks to each report.

Each report in a Report Set is generated by the execution of a Program instance whose corresponding Planned Output is assigned to the particular chapter, section, or subsection (all of which are called Report Set Entries) where the report appears in the final output. A single Program instance can generate multiple reports, each of which can be assigned to a different Report Set Entry. Reports can take the form of tables, listings, figures, or text, depending on the technology you use to create them and how you define them.

You can include Program instances of different technology types—including SAS, Oracle Reports, and PL/SQL—in the same Report Set. When you execute the Report Set, the system sends each Program instance to the appropriate engine for execution and integrates the results.

Postprocessing Oracle LSH includes Oracle XML Publisher for use in an optional postprocessing step for Report Sets. During postprocessing, after the system has generated all the reports, Oracle XML Publisher generates a single PDF file for the entire Report Set (or breaks the Report Set into volumes if you choose), paginates and concatenates the individual reports, numbers the pages, and creates PDF bookmarks.

To use the postprocessing feature you must create reusable Overlay Template RTF files that include publishing specifications such as multilayered page layouts, graphics, and watermarks for each type of page in your Report Set (for example, the table of contents, listings, and figures, in landscape and portrait orientations). You upload these RTF template files to an Overlay Template File, which is part of an Overlay Template definition in Oracle LSH.

You can execute a Report Set without the postprocessing step to save time while you are developing and testing the Report Set and its Program instances. In that case the system generates an output for the Planned Output assigned to each included Report Set Entry, with the file type specified for the Planned Output. The Post-Processing Parameter called Post Process controls whether or not postprocessing is included in a particular execution.

If you plan to use postprocessing you must define the file type of all Planned Outputs assigned to Report Set Entries as PDF.

Parameter Value Propagation You can set up value sharing among Parameters to promote consistency and reduce the work required to submit the Report Set for execution.

For example, many Program instances may have a Parameter for Study Name or Study ID. You can define a Report Set Parameter to collect the Study Name or ID at runtime at the top level of the Report Set, and set up value sharing so that the person submitting the Report Set for execution enters the value for Study Name or ID once, and the system automatically propagates that value to the Study Name or ID Parameter of all the Program instances you specify.

You can also use an output Parameter value of one Program to populate the value of an input Parameter of another Program. See "Setting Up Parameter Value Propagation" for further information.

Concurrent Editing Multiple people can simultaneously modify a single Report Set. The first person to modify it must check out the definition, but while it is checked out, anyone else with Modify privileges on the Report Set definition can modify it.

However, only one person can work on any one section at a time; see "Concurrent Editing of Report Sets" for further information.

Note:

Shared editing works only in a Report Set instance that is contained directly in a Work Area. It does not work in a Report Set instance that is contained in a Workflow.

Execution Oracle LSH does not necessarily execute a Report Set in the order displayed in the Structure view, but takes dependencies into account. If you have set up value propagation from the output Parameter of one Program to the input Parameter of another Program, the system executes the Program that produces the output value before the Program that takes the input value.

The log file the system generates each time it runs a Report Set contains detailed information about each stage of the Report Set execution.

Report Set submissions include two jobs, both of which are displayed on your My Home page. The first job starts the second, which is a batch process.

Partial Execution Using the Execution Setup for the Report Set as a whole you can submit the whole Report Set or specify one or more Report Set Entries to execute. You can also select a single Report Set Entry in the Structure view and submit it with or without Report Set Entries under it in the Report Set hierarchy. You can also submit a single Program and the system will produce the Report Set Entries to which it is assigned.

Validation of Individual Report Set Entries You can validate different sections of the Report Set at different times. See "Validating Report Set Definitions and Outputs" for details.

Reports on Report Set Definitions and Instances From the Actions drop-down list, you can generate reports that provide information on a Report Set definition or instance; see Chapter 14, "System Reports" for information.

How to Work on a Report Set

Report Sets can be very large and complex, and many people can work on them at the same time; see "Concurrent Editing". To make Report Set development work best, use the following general process:

  1. Create overlay template files and Overlay Template Definitions. To produce a unified PDF output of your Report Set you must create RTF templates, upload them to Oracle LSH, and define Overlay Template Definitions (OTDs) in Oracle LSH. You must define OTDs before you can set values for the predefined Overlay Template Parameters to specify which template(s) to use for each Report Set Entry, or branch, of the Report Set.

    You can use the same OTDs and OTD files for many Report Sets. See "Creating Overlay Templates" and "Setting Overlay Template Parameter Values" for further information.

  2. Create the Report Set. Create the Report Set definition and an instance of it, then click Update to set the Strict and Unique numbering properties for the Report Set. See "Creating a Report Set" for further information.

  3. Set Parameter values at the top Report Set level. Set values at the top Report Set level for predefined Overlay Template and Post-Processing Parameters. This ensures that all Report Set Entries have values for these Parameters in the Report Set instance and in the Execution Setup. "Creating and Setting Report Set Parameters".

  4. Create Report Set Parameters (optional). To make the Report Set easier to submit and to help ensure data consistency, you may want to define one or more Parameters at the Report Set level. For example, if all the reports in a Report Set are about the same study, and the Programs that create the reports have an input Parameter to identify the study, you may want to define a Study Parameter at the Report Set level and share its value with each Program's Study Parameter. The Report Set Study Parameter appears at the top of the Report Set's Execution Setup where the user can easily find it and set it once for the whole Report Set. See "Setting Up Parameter Value Propagation" for further information.

  5. Define the Report Set structure. A Report Set has top-level chapters that contain subchapters that can in turn contain any number of levels of sections and subsections. All of these are called Report Set Entries. You must define a Report Set's structure by defining hierarchical Report Set Entries from the top down; see "Using the Report Set Structure View".

  6. Develop, test, and validate Report Set Entries and Programs. Develop the Programs that generate the Report Set's reports. Assign each Program Planned Output to the Report Set Entry (chapter, section, or subsection) where it should appear. Add pre- and post-report narratives as necessary to Report Set Entries. Adjust the settings for Post-Processing and Overlay Template Parameters as necessary. Test and validate Programs, Report Set Entries, and report outputs according to your company's standards. See "Defining Report Set Entries" and "Validating Report Set Definitions and Outputs" for further information.

Concurrent Editing of Report Sets

More than one person can work on a Report Set at the same time. After one person checks out the Report Set, any other user with Modify privileges on the Report Set can also work on it. In order to protect each person's work, the system enforces the following behavior:

Note:

If you try to make a change that is not allowed because of the activity of another person, you get an error message with the username of the person whose work is conflicting with yours. In most cases you can click Apply again immediately and the system applies your change.
  • Report Set Structure. Many people can create, move, copy, modify, or remove Report Set Entries as long as they are all working in different branches of the Report Set.

    One person cannot move, reorder, copy, or remove a Report Set Entry that is a parent in the same hierarchy (branch) of a Report Set Entry that another person is currently modifying.

  • Report Set Entry. Only one person at a time can modify a particular Report Set Entry's properties. Different people can modify different Report Set Entries in different branches of the Report Set hierarchy.

  • Program Instance. Only one person at a time can modify a particular Program instance contained in the Report Set. Different people can modify different Program instances.

  • Install Program Instance. One person can install a single Program instance in the Report Set at any time without impacting the work of other people on the Report Set. Installing a Program instance implicitly checks in the Report Set definition and instance, installs the Report Set instance, and checks out the Report Set definition and instance again.

  • Install Report Set. Installing a Report Set from a Work Area is permitted but not recommended during concurrent editing. Oracle recommends installing a Program instance from the Report Set Structure view as a means of installing the Report Set structure during concurrent editing.

    During installation of a Program in a Report Set, other people can continue to work on the Report Set definition through the instance, including making changes to the Report Set structure and Programs. However, noone can work on the Report Set instance during installation of the Report Set in a Work Area. This includes mapping Program instances. See "Installing Report Sets" for further information.

    Note:

    If the person running the Work Area installation has Checkin Administrator privileges, all Program instances are checked in without warning, including those checked out by other users.
  • Execute Report Set. One person can execute a Report Set or a portion of a Report Set without impacting the work of other people.

Creating Overlay Templates

This section contains the following topics:

Description of otd_process.gif follows
Description of the illustration ''otd_process.gif''

About Overlay Templates

Oracle LSH's postprocessing feature uses Oracle XML Publisher to generate a single- or multi-volume PDF-format Report Set with a unified Table of Contents from the individual PDF reports and narratives generated by the first stage of Report Set execution.

To use the postprocessing feature, you must design and create RTF templates that can include graphics, watermarks, hyperlinks, text variables, and the font styles and sizes you prefer.

You create template files in Microsoft Word or a similar tool, save them as RTF files, and upload each one to an Overlay Template Definition (OTD) File definition in an OTD. In the OTD File definition you specify the file's orientation, paper size, language, and rotation.

Note:

For information on creating template files, see the Oracle XML Publisher User's Guide, which is available on My Oracle Support and the Oracle Technology Network.

Templates Applied at Runtime For the Table of Contents and Narratives, Oracle LSH uses the runtime values of the Post-Processing Parameters Paper Size, Language, and Orientation to determine which template files associated with the OTD to apply. To determine which template files to use for the actual reports, or content, Oracle LSH uses Paper Size, Language, and the orientation of the actual PDF report output.

Therefore you can, for example, create a single OTD with template files for both A4 and US letter-sized paper, and use different values for the Paper Size Post-Processing Parameter to print it out on A4 paper in Europe or Japan and letter-sized paper in the US or Canada.

Note:

In Oracle LSH Release 2.4.8 the only language supported is US English.

Overlay You can create multiple template files in the same Overlay Template definition with the same values for Paper Size, Orientation, and Language. In this case, Oracle XML Publisher uses all of them, overlaying them on top of each other on each page. For example, you can create one template file with a rotation of 90 degrees to print the Report Set title and your company logo vertically along the side margin, and another template file for the main body of the page with a rotation of 0. Because both files have the same orientation and paper size, the system applies both; see Figure 9-2, "Example with Banner Template File".

Creating Template Files

Oracle recommends creating a single OTD containing all the template files you may need to postprocess a single Report Set. Decide which options represented by Post-Processing Parameters you want to support—A4 and/or US Letter-sized paper, landscape and/or portrait orientation— and create the template files necessary to support them in a single OTD. The values for the Post-Processing Parameters can be set in the Report Set definition, in the Execution Setup definition, or by a user submitting the Report Set for execution. Oracle LSH selects the template(s) to use for each section of the Report Set based on these Parameter values at runtime.

OTD File Types You must create at least one RTF template file for each OTD File type that you plan to use: Coversheet, Table of Contents, Content, Narrative, Narrative Content, Page Numbering, TOC Overlay, and In Progress; see "Creating an Overlay Template File Definition" for a description of each file type.

Text Variables You can use text variables in your template files to substitute an actual value from the Report Set at runtime. These variables are sensitive to context within the Report Set. For example, if you use the text variable <?xdo66:title?> it displays the title of the Report Set when used in the Coversheet or Table of Contents template, and it displays the Report Set Entry title when displayed in a Narrative or Content template for a chapter or section.

You can also use text variables to display the runtime value of user-defined Parameters; for example, <?study?>. The variable displays the value of the Study Parameter appropriate for the context: Report Set, Report Set Entry, or Program.

Footers You can include a footer in any of the OTDs if required. Enter the following variable in the OTD RTF's footer: <?/xdobb:item/footer?>.

Creating an Overlay Template Definition

You create Overlay Template definitions directly in an Application Area or Domain library, not a Work Area. They do not have instances.

To create an Overlay Template, do the following:

  1. In a Domain or Application Area, click Manage Definitions.

  2. From the Create drop-down list, select Overlay Template. The Create Overlay Template screen opens.

  3. Enter a Name for the Overlay Template.

  4. Enter a Description for the Overlay Template.

  5. From the Default Paper Size drop-down list, select one of the following:

    • A4. The standard paper size used in Europe and Japan: 21 x 29.5 cm.

    • US Letter. The standard paper size used in North America: 8.5 x 11 inches.

    This value serves as the default value for the corresponding Parameter of each Overlay Template File. You can change the value for any Overlay Template File definition as necessary.

    Tip:

    If you have some template files for A4 paper and others for US Letter-sized paper, you can set this value to A4 first, for example, upload all the template files for A4 paper, then change the default to US Letter and upload all the template files for US Letter-sized paper.
  6. From the Default Language drop-down list, select a language. In Oracle LSH Release 2.4.8 the only option is US English.

    This value serves as the default value for the corresponding Parameter of each Overlay Template File in the Overlay Template.

  7. Classify the Overlay Template definition; see "Classifying Objects and Outputs" for further information.

  8. Click Apply. The Overlay Template Definition Properties screen appears.

  9. Click Add to add Overlay Template File definitions (see "Creating an Overlay Template File Definition" below).

Creating an Overlay Template File Definition

An Overlay Template Definition (OTD) File is an Oracle LSH definitional object contained in an OTD. It consists of an uploaded XML template—an RTF file that contains formatting design information (see "Creating Template Files") and a set of Parameters that serve as labels.

To create an Overlay Template Definition File, do the following:

  1. In the Overlay Template Definition Properties screen, click Add in the Overlay Template Definition Files section. The Overlay Template Definition File screen opens.

  2. Click the Browse button to find the RTF template file you want to upload. The system opens a standard Browse window.

  3. Navigate to the location of the file you want to upload, select the file, and click Open.

  4. Select a Type:

    • Content. Files of type Content determine the appearance of the actual Report Set reports. This is the default Type.

    • Coversheet. Files of type Coversheet determine the appearance of the Report Set's title page.

    • In Progress. Create one OTD file of type In Progress. When the system cannot execute a Report Set Entry because its associated Program instance is checked out or fails execution, the system uses the In Progress OTD file as a placeholder for the unexecuted report.

    • Narrative. Files of type Narrative are used to display the pre- or post- narratives for the report.

    • Narrative Content. Create and upload a PDF file (usually blank) for Oracle XML Publisher to use to format the text content for the narrative specified in the Report Set definition.

    • Page Numbering. Oracle XML Publisher requires a special OTD file for page numbering because it must generate a page number dynamically for each page. There is an XML tag that for the position and format of the page number. See the Oracle XML Publisher documentation for further information.

      To produce a Report Set with page numbers, you must define and upload one OTD file of the Page Numbering type for each paper size/orientation combination represented in this Overlay Template Definition.

    • Table of Contents. Files of type Table of Contents determine the appearance of the Report Set's table of contents.

    • TOC Overlay. If necessary, use this type to provide a header and footer or other overlay formatting for the table of contents.

  5. Select a printing Orientation:

    • Portrait. Portrait files must be printed vertically.

    • Landscape. Landscape files must be printed horizontally.

    The default value is Portrait.

  6. Select a Paper Size. The default value comes from the Paper Size Parameter of the Overlay Template definition.

    • A4. The standard paper size used in Europe and Japan: 21 x 29.5 cm.

    • US Letter. The standard paper size used in North America: 8.5 x 11 inches.

  7. Select a Language. In the Oracle LSH Release 2.4.8 there is only one option: US English.

  8. Select a Rotation (in number of degrees):

    Description of a.gif follows
    Description of the illustration ''a.gif''

    For example, you can use a rotation of 90 or 270 degrees to create a banner along one side of a page. The figure below shows the direction in which text appears when you define two template files with a partite orientation and the same paper size. The Content template has a rotation of zero (0) and the banner template file has a rotation of 90.

    Figure 9-2 Example with Banner Template File

    Banner Template File

    Tip:

    Do not change the setting for Orientation (for example, from landscape to portrait) simply because you are using a 90- or 270-degree rotation. The rotated file should have the same Orientation setting as the other files with which it is to be used. Further information is available in the Oracle XML Publisher User's Guide.

Creating a Report Set

When you create a Report Set in a Work Area, you are actually creating an instance of a Report Set definition.

To create a new Report Set instance:

  1. In a Work Area, select Report Set from the Add drop-down list.

  2. Click Go.

    The system displays the Create Report Set screen.

  3. Choose one of the following options:

    • Create a new Report Set definition and instance. Choose this option if no Report Set definition exists that can meet your needs, either as it is or with some modification.

    • Create an instance from an existing Report Set definition. Choose this option if a Report Set definition already exists that meets your needs.

      If you can adapt an existing Report Set definition to make it fit your needs, first copy it into the current Application Area, then choose this option and select the copied definition. See "Finding an Appropriate Definition" and "Reusing Existing Definitions" for further information.

  4. Depending on your choice, follow one of the following sets of instructions:

Creating a New Report Set Definition and Instance

When you select Create a new Report Set definition and instance in the Create Report Set screen, additional fields appear.

  1. Enter values in the following fields:

    • Name. See "Naming Objects". The system uses the Name internally. It must be unique within the container.

    • Title. The system enters the value you entered for the Name as the default value. You can change it. It is the Title, not the Name, that appears on the Report Set output. The Title is not required to be unique.

    • Description. See "Creating and Using Object Descriptions".

  2. In the Classification section, select the following for both the definition and the instance:

  3. Click Apply to save your work and continue defining the Report Set.

    The system opens the Properties screen for the new Report Set instance with the Report Set definition checked out. The Report Set properties Strict Numbering and Unique Numbering are both set to Yes by default. If you want to change their values, you must go to the Report Set definition and change them there; click on the Definition hyperlink in the Instance Properties section.

    The properties are:

    • Strict Numbering. If set to Yes, Report Set Entries must be numbered sequentially, with no gaps. The system automatically generates sequential numbers. This is the default setting.

      If set to No, gaps are allowed in the numbering of Report Set Entries. The system generates sequential numbers by default, but you can override the entry number and if you remove a Report Set Entry the system does not renumber the remaining Report Set Entries to close the gap (however, you can do this manually).

    • Unique Numbering. If set to Yes, each Report Set Entry must have a number that is different from the number of all other Report Set Entries in the same Report Set. The system automatically generates unique numbers.

      If set to No, unique numbers are not required. The system generates unique numbers by default, but you can override the entry number to create duplicate numbers.

    Table 9-1 Possible Combinations or Strict and Unique Numbering Settings

    Unique Numbering Strict Numbering Automatic Renumbering Possible? Valid Example Invalid Example

    Y

    Y

    Yes

    14.2.1 Table

    14.2.2 Listing

    14.2.3 Table

    14.2.1 Table

    14.2.1 Listing

    14.2.3 Table

    Y

    N

    No

    14.2.1 Table

    14.2.3 Listing

    14.2.6 Table

    14.2.1 Table

    14.2.1 Listing

    14.2.3 Table

    N

    Y

    No

    14.2.1 Table

    14.2.1 Listing

    14.2.2 Table

    14.2.1 Table

    14.2.1 Listing

    14.2.3 Table

    N

    N

    No

    No restriction

    No restriction


Creating an Instance of an Existing Report Set Definition

Use this option if there is an existing Report Set that you can use exactly as it is. If you use an existing Report Set as a definition source, you can use all the Report Set Entries, Program instances, Planned Outputs, Execution Templates, Post-Processing and Overlay Template Parameter values, and Parameter value propagation that are already defined. See "Creating an Instance of an Existing Definition" for instructions.

After you have created the Report Set instance, you must map the Table Descriptors of all the Program instances contained in it to Table instances; see "Mapping Table Descriptors to Table Instances" for instructions.

Using the Report Set Properties Screen

This section contains the following topics:

See also Figure 9-1, "Process of Creating a Report Set Definition and Instance".

See "Modifying Report Sets" for information on modifying Report Sets.

If you are working in a Work Area, you see the properties of both the Report Set instance and the Report Set definition it references. If you are working directly on the definition in an Application Area or Domain, you see only the properties of the definition.

Instance Properties

You can see the following instance properties:

Name You can click Update and modify the name. See "Naming Objects" for further information.

Description You can click Update and modify the description. See "Creating and Using Object Descriptions" for further information.

Definition This field specifies the Report Set definition to which this Report Set instance points. For information on modifying this field, see "Definition Source".

To upgrade to a new version of the same definition, use the Upgrade to Latest button. See "Upgrading to a Different Definition Version from an Instance".

Version This field displays the current version number of the Report Set instance.

Version Label This field displays the version label, if any, for the current Report Set instance version.

For further information on object versions, see "Understanding Object Versions and Checkin/Checkout".

Validation Status This field displays the current validation status of the Report Set instance. If you have the necessary privileges, you can change the validation status by selecting Validation Supporting Information from the Actions drop-down list. See "Validating Objects and Outputs" for further information.

Status This field displays the install status of the Report Set: installable or noninstallable. See Appendix A, "Installation Requirements for Each Object Type".

Definition Properties

Checked Out Status This field displays the status of the definition: either Checked Out or Checked In. You must check out the definition to modify the Report Set structure or to add, remove, assign, or reassign Program instances. You can change Table Descriptor mappings without checking out the definition. See "Mapping" and "Understanding Object Versions and Checkin/Checkout" for further information.

Latest Version If set to Yes, this Report Set instance is pointing to the latest version of the Report Set definition. If set to No, this Report Set instance is pointing to an older version of the Report Set definition.

View Latest You can see this button only if the current Report Set instance does not point to the latest definition version. Click this button to view the latest Report Set definition.

Upgrade to Latest This button is grayed out if the current Report Set instance already points to the latest Report Set definition. Click this button to upgrade the current Report Set instance to the latest definition version. For more information on upgrading instances, see "Upgrading Object Instances to a New Definition Version".

Checked Out By This field displays the username of the person who has the Report Set definition checked out. See "Understanding Object Versions and Checkin/Checkout" for further information.

Version Label This field displays the version label, if any, for this definition version.

Strict Numbering If set to Yes, numbers must be sequential, with no gaps. If set to No, gaps are allowed. You must be in the Report Set definition in its Application Area or Domain to change this value.

Unique Numbering If set to Yes, numbers must be unique within the parent. If set to No, duplicate numbers are allowed. You must be in the Report Set definition in its Application Area or Domain to change this value.

Title This field displays the Report Set definition title.

Validation Status This field displays the current validation status of the Report Set definition. If you are working directly in the definition in an Application Area or Domain and you have the necessary privileges, you can change the validation status by selecting Validation Supporting Information from the Actions drop-down list. If you are working in an instance of the Report Set in a Work Area, and you want to change the validation status of the definition, you must go to the definition. See "Validating Objects and Outputs" for further information.

Status This field displays the installable status of the Report Set: Installable or Non Installable. See Appendix A, "Installation Requirements for Each Object Type".

Buttons

From a Report Set instance in a Work Area, you can use the following buttons:

Submit Click Submit to run the Report Set instance. Before you can run the Report Set, you must install it and create an Execution Setup for it (select Execution Setups from the Actions drop-down list).

Update Click Update to modify the Report Set instance properties. See "Modifying Report Set Instance Properties".

Check In/Out and Uncheck Click these buttons to check out, check in, or uncheck the Report Set definition. Different buttons are displayed in the Report Set Definition Properties section depending on the checked out status and whether or not you are the person who has the definition checked out. If someone else has checked out the definition, you cannot check it in or uncheck it. The username of the person who has checked it out is displayed. See "Understanding Object Versions and Checkin/Checkout".

View Latest/Upgrade to Latest If the definition is not the latest version, you can click to view the latest version and upgrade to the latest version if you want to. See "Upgrading to a Different Definition Version from an Instance".

Using the Report Set Structure View

This section contains the following topics:

Navigating to the Report Set Structure View

To view, build, or modify a Report Set's structure, do the following:

  1. Navigate to the Report Set instance in its Work Area in the Applications tab.

  2. Click the Report Set name's hyperlink. The Report Set opens.

  3. If it is not already showing, select Structure from the View drop-down list.

Building and Modifying the Report Set

This section contains the following topics:

The Report Set's Structure view, with Structure selected in the View drop-down, shows the structure of the Report Set in a display similar to a table of contents.

Each chapter, section, and subsection is called a Report Set Entry. You can define any number of levels of Report Set Entries. You must define Report Set Entries from the top level down, creating each new Report Set Entry (RSE) as a child of an existing Report Set Entry or of the Report Set itself.

Modifying the Report Set

In the Report Set Structure view you can build and modify the Report Set structure and do many other things as follows:

  1. Select the Report Set itself or a Report Set Entry (RSE).

  2. From the Select and drop-down list, select the action you want to perform on the selected Report Set or Report Set Entry.

    Use Add RSE, Remove RSE, Reorder, Copy, and Move to create and modify the Report Set structure. Details for all options are given below.

  3. Click Go.

The following options are available:

Add Program

The Create Program screen opens and you can either create (add) an instance of an existing Program definition or create a new Program definition and instance. If you add an instance of an existing Program that has at least one primary Planned Output, the system assigns the first primary Planned Output to the selected Report Set Entry. You can change the assignment if necessary by using the Assign Planned Output option. See "Defining Programs to Generate Reports" for information about Programs inside Report Sets and "Creating a Program" for general instructions.

Add RSE

The Add Entries screen opens and you can add one or more Report Set Entries under (at the child level of) the one you selected or modify existing Entries; see "Creating Multiple Report Set Entries" for instructions. If the selected Report Set or Report Set Entry already contains one or more child Report Set Entries, the system adds the new ones below the existing ones.

After you have added Report Set Entries you can define additional details; see "Setting Report Set Entry Properties" and assign a Planned Output to the Report Set Entry; see"Assign Planned Output" below.

Assign Planned Output

The Assign Program Instance and Planned Output screen opens. Do the following:

  1. Click the Search icon to search for a Program already assigned to the Report Set.

    Note:

    Only checked out Program instances can be assigned to a Report Set Entry.
  2. Select the Planned Output you want to assign.

  3. Click Select.

If you select a Report Set Entry that already has a Planned Output assigned, you can change the assignment by selecting a different one.

Copy

You can copy a Report Set Entry and its child Report Set Entries into another location in the same Report Set or a different one. The Copy operation includes all child Report Set Entries and the Execution Setup fragment for the selected Report Set Entry and all its children (if such Execution Setup fragments exist). You have the option to copy Program instances assigned to Report Set Entries being copied.

  1. Select the Report Set Entry you want to copy and then select Copy from the drop-down list.

  2. Click Go. A message appears asking if you want to include Program instances assigned to the Report Set Entry (and its children).

    • Click No if you do not want to copy Program instance(s).

    • Click Yes to copy Program instance(s).

  3. Select the Report Set into which you want to copy the Report Set Entry; see "Pasting Objects".

If you choose to copy Program instances, the system copies their Execution Setups and Table Descriptor mappings and maintains the existing links to Program definitions and their Planned Outputs.

If there is already a Program with the same name in the target Report Set, the system creates the copy with the name Copy Of Program_Name. When you copy a Report Set Entry into the same Report Set, this always happens. If you prefer to have a single instance of the Program in the Report Set, so that the Program is executed only once during Report Set execution, do one of the following:

  • Remove the copied Program from the Report Set and assign the original Program to the Report Set Entry.

  • Unassign the Program before you do the Copy operation and reassign it afterward.

Note:

You cannot select the Report Set's top level and then select Copy from the drop-down list. You can copy a whole Report Set from the Applications screen but not from the Report Set screen.

Note:

To copy multiple Report Set Entries at the same level, click the hyperlink of the parent Report Set Entry, then select and copy the Report Set Entries.
Default Execution Setup

View and modify the default Execution Setup for selected Report Set instance or Report Set Entry and its child Report Set Entries; see "Report Set and Workflow Execution Setups".

If no Execution Setups are defined, the system generates a default Execution Setup and opens it.

Execution Setup

The system displays all Execution Setups defined for the selected Report Set instance. The list is the same regardless of which Report Set Entry you select; you see the Execution Setups for the Report Set instance as a whole. You can then click on the hyperlink of any Execution Setup and navigate to any Report Set Entry to modify its settings.

If no Execution Setups are defined, the Create Execution Setup screen opens and you can create one.

Install Program

Install the Program instance assigned to the selected Report Set Entry. If the Program instance is not installable you get an error message.

When you install a Program instance from the Report Set Structure view, the system also checks in the Report Set definition and instance and installs the Report Set instance, then checks the Report Set definition and instance back out. You can use this functionality to install changes to the Report Set structure even if no Program instances need to be installed.

Map

You can map or remap (using Automatic Mapping by Name) the Table Descriptors of all Programs assigned to the selected Report Set Entry and all its child Report Set Entries at the same time. If you select the top level of the Report Set you can map the Table Descriptors of all Programs in the Report Set. For further information, see "Automatic Mapping by Name". For other mapping options, see "Mapping".

Note:

The Report Set instance is not installable until all the Table Descriptors of all the Program instances it contains are mapped.
Move

You can move a Report Set Entry into another location in the same Report Set or a different one. The Move operation includes all child Report Set Entries and the Execution Setup fragment for the selected Report Set Entry and all its children.

If you move a Report Set Entry within the same Report Set, the system maintains the existing links to Program instances and their Planned Outputs.

If you move the Report Set Entry to a different Report Set, a message appears asking if you want to include Program instances assigned to the Report Set Entry and its children. If you choose to include Program instances, the system copies all Program instances assigned to the Report Set Entries you are moving, and their Execution Setup fragments (if any) and recreates the Program instance and Planned Output assignments in the new location.

See "Pasting Objects".

Note:

Program instances are never removed implicitly from a Report Set, even if all the Report Set Entries to which they are assigned are moved or removed.

Note:

You cannot select the Report Set's top level and then select Move from the drop-down list. You can move a whole Report Set from the Applications screen but not from the Report Set screen.
Quick Submit

The system submits the selected item—either a Report Set Entry and all its children, the entire Report Set, or a Program instance—using the default Execution Setup with its default values, without opening the Execution Setup screen. The system upgrades the Execution Setup if necessary and validates it. The submission fails if:

  • The Execution Setup cannot be upgraded; for example, if another user is currently modifying the default Execution Setup

  • The Execution Setup is invalid; for example, the Parameters that apply to the portion of the Report Set being submitted have invalid values

In the Job Execution section of the My Home page you see two jobs. A temporary job starts the actual report generation job.

Remove RSE

The system deletes the Report Set Entry you select. If you select a Report Set Entry that contains other Report Set Entries, the system removes them also.

Note:

If you try to remove a Report Set Entry to which other Report Set Entries have links, you receive a warning. If you choose to continue, the system removes the selected Report Set Entry and all links between it and other Report Set Entries. The system does not remove any Program instances assigned to any Report Set Entries being removed.

Note:

You cannot select the Report Set's top level and then select Remove from the drop-down list. You can remove a Report Set from the Applications screen but not from the Report Set screen.
Reorder

Select the Report Set or Report Set Entry whose child Report Set Entries you want to reorder; see "Reordering and Renumbering Objects".

Submit

The system displays the Submit screen based on the default Execution Setup for the selected Report Set instance. If you select a Report Set Entry and then Submit, the Report Set Entry you selected, and all its children, are selected for inclusion in the execution. You must define an Execution Setup and install the Report Set instance before you can submit any part of it for execution.

View All Outputs

The system displays a list of all outputs produced for the selected Report Set or Report Set Entry. The system displays the following information for each output: Output Validation Status, Creation TS (Timestamp), Creation User (the username of the person who ran the job that created the output), Job ID, Program Instance Name, Program Instance Version, Path to Executable (Program) Instance, and Title.

In addition, there is an icon in the View column that you can click to view the output itself.

View Output

The system displays output properties information about the current output produced for the selected Report Set or Report Set Entry, including: title, file name, job ID, execution status, description, validation status, execution user (the username of the person who executed the job), job start time, blinding status, and primary output (yes/no).

To view the output itself, click View File.

Report Set Entry Information Displayed

The Report Set Structure view displays the following information about each Report Set Entry and the Report Set as a whole:

  • Full Title is the Report Set Entry's concatenated title that includes its Entry Number Prefix, Parent Number, Delimiter, Entry Number, Entry Number Suffix, and Title, in that order.

  • VS (Validation Status) refers to the standard validation status of the Report Set Entry; either Development (Dev), Quality Control (QC), or Production (Prod).

  • Summary Output VS (Validation Status) is the calculated validation status derived from outputs' and child Report Set Entries' validation statuses. The possible values are: Null, Not Assigned, N/A (Not Applicable), Development, Quality Control, or Production; see "Summary Output Validation Status".

  • Output Creation TS (Timestamp). The system displays the timestamp of the creation of the current output.

  • Narrative. If the checkbox is checked, there is a Pre- and/or Post-Narrative assigned to the Report Set Entry.

  • Assigned Program Instance. If a Program instance is assigned to the Report Set Entry, the system displays a link to its Properties screen.

  • Program Instance VS (Validation Status). If a Program instance is assigned to the Report Set Entry, the system displays its validation status. You can click the hyperlink to change its validation status if you have the required privileges.

  • Filename Reference of the Program's Source Code.

  • Assigned Planned Output. If a Planned Output of the assigned Program instance is assigned to the Report Set Entry, the system displays its name.

  • Definition Checked Out By displays the username of the person who has checked out the Program definition, if it is checked out.

Creating and Setting Report Set Parameters

This section contains the following topics:

Report Sets have two sets of predefined Parameters—Overlay Template Parameters and Post-Processing Parameters—that determine how Oracle XML Publishes post-processes the Report Set, using templates, to generate a single- or multi-volume PDF output. The Parameters that are part of the Programs in a Report Set are used to execute the Programs during Report Set execution. You can define Parameters directly at the Report Set or Report Set Entry and share their values to Program Parameters to simplify Report Set submission.

When you create an Execution Setup for a Report Set or Report Set Entry, the system copies all these Parameters into the Execution Setup. You can modify them in the Execution Setup without affecting the Parameters in the Report Set or Program definitions.

Setting Overlay Template Parameter Values

This section contains the following topics:

Oracle LSH Overlay Template definitions (OTDs) are designed to include all the template files you need to postprocess a Report Set; see "Creating Overlay Templates". If you define your OTDs that way and this particular Report Set has no unusual characteristics, you can simply enter the name of the OTD in the Default OTD Parameter at the Report Set level and that value is propagated to all other OTD Parameters throughout the Report Set.

Note:

The value is displayed only where it is explicitly set.

However, if you need to use a different OTD for certain Report Set Entries or for certain Narratives or report outputs, you can do so. See "Setting Overlay Template Parameters".

Overlay Template Parameters

The Report Set itself and Report Set Entries have a similar set of Overlay Template Parameters:

The following Parameters apply to the Report Set as a whole only:

  • Coversheet OTD Oracle XML Publisher applies the specified OTD to the Report Set's coversheet.

  • TOC (Table of Contents) OTD Oracle XML Publisher applies the specified OTD to the Report Set's table of contents.

The following Parameters apply to each Report Set Entry and the Report Set itself:

  • Default OTD. If the value for any other OTD Parameter at the top Report Set level is null, XML Publisher uses the Default OTD value for that Parameter.

  • Pre-Narrative OTD. Oracle XML Publisher applies the specified OTD to the Report Set Entry's Pre Narrative (text displayed on a page before the report), if any.

  • Content OTD. Oracle XML Publisher applies the specified OTD to the Report Set Entry's generated report output, if any.

  • Post-Narrative OTD. Oracle XML Publisher applies the specified OTD to the Report Set Entry's Post Narrative (text displayed on a page after the report), if any.

Setting Overlay Template Parameters

Normally you need to set a value only for the Default OTD Parameter at the Report Set level. Its value is automatically propagated to all other OTD Parameters unless you explicitly specify a different value. OTDs are designed to accommodate all possible needs in a Report Set; see "Creating Overlay Templates".

To set an explicit value for an Overlay Template Parameter, do the following:

Note:

You must create at least one Overlay Template definition (OTD) before you can enter a value for the Default OTD Parameter. See "Creating Overlay Templates" for information.
  1. In the Default Value column for an Overlay Template Parameter, click the plus (+) sign. A Search and Select screen opens.

  2. Select the name of the Domain that contains the Overlay Template definition (OTD) that you want to use.

  3. If the OTD is not contained directly in that Domain, drill down to the subdomain or Application Area that contains the OTD.

  4. If you want to search for a specific OTD name or version label, select either Name or Version Label from the Search By drop-down list and enter the value.

  5. Click Go. The system displays the OTDs in the location you specified. If you selected a name or version label it displays only OTDs with that name or version label.

  6. Select the OTD you want.

  7. Click Apply.

    Note:

    When you enter a value for an OTD Parameter, all the OTD Parameters of the same name below it in the Report Set hierarchy inherit that value unless you explicitly set a different value. Therefore if, for example, you are using one OTD throughout the Report Set with a few exceptions, you must set the Parameters of the same name in the immediate child Report Set Entries to the default OTD; see "OTD Parameter Value Sharing".

OTD Parameter Value Sharing

OTD Parameters are predefined with automatic value sharing by name. That is, by default each OTD Parameter gets its value from the next higher OTD Parameter in the Report Set hierarchy with the same name. In addition, if there is no OTD Parameter with the same name higher in the Report Set hierarchy that has an explicitly defined value, it gets its value from the Default OTD Parameter at its own level. (The Default OTD Parameter for each Report Set Entry gets its value using automatic sharing by name from the next Default OTD Parameter above it in the Report Set hierarchy that has an explicitly defined value.)

If you do not want to use the default shared value you can explicitly set any OTD Parameter in any Report Set Entry. The corresponding Parameter of each of its child (and grandchild, and so on) Report Set Entries (whether existing or subsequently defined) gets the new value. If you want the child and grandchild Report Set Entries to use the old value, you must change the value of the corresponding Parameter for each of the immediate children of the Report Set Entry you changed.

All Overlay Template Parameters must have a value or Report Set postprocessing will not work. Therefore at the top level of the Report Set you must do one of the following if you want to use postprocessing:

  • Specify a value for the Default OTD Parameter only. In this case, the other OTD Parameters at the Report Set level get their value from the Default OTD Parameter.

  • Specify a value for the Default OTD Parameter and, if you want any of the other OTD Parameters to have a different value, specify a value for those Parameters.

  • Specify a value for every OTD Parameter except the Default OTD Parameter.

Setting Post-Processing Parameter Values

This section contains the following topics:

Oracle XML Publisher uses the values of a predefined set of Post-Processing Parameters to control various aspects of generating a unified PDF output for the Report Set. There is a similar set of Parameters at the Report Set level and at the Report Set Entry level. Report Set Entry Post-Processing Parameters receive their default value from the corresponding Parameter of their immediate parent Report Set or Report Set Entry.

If you set these Parameter values at the Report Set level, the values you set become the default settings for the corresponding Parameters in the Report Set Entries below. For the Post-Processing Parameters that exist only in Report Set Entries, you can set the values in the top-level Report Set Entries for the same effect.

You can override the value for any Post-Processing Parameter for any Report Set Entry at any time. Changing a value for a Report Set Entry also changes the value of the same Parameter for any existing and future child Report Set Entries of that Report Set Entry.

Post-Processing Parameters at the Report Set Level Only

The following Post-Processing Parameters appear at the Report Set level only:

Post Process If set to Yes, the Report Set uses Oracle XML Publishing postprocessing to apply overlay templates and generate one or more volumes of concatenated reports in PDF format.

If set to No, the system disregards all other settings in the Post-Processing and Overlay Templates tabs. The system generates a table of contents and hyperlinks to every report, each of which is a separate file with the type specified for the corresponding Planned Output. This mode requires less time for execution and may be useful during development.

Single Volume Output Name If you enter a value here, the system ignores all Volume Breaks and produces a single postprocessed output, using this value as both the output name and title. The system also uses the value for the output filename, with the extension .pdf.

Start Page Number Enter a number (normally 1). If your Report Set is really a continuation of another Report Set that you have defined separately, you can enter the number of pages in the first Report Set (plus 1) as the value for the Starting Page Parameter, to create continuous page numbering for both Report Sets.

Oracle XML Publisher can display page numbers as "1 of x," "2 of x," and so on. If you enter a Starting Page value of 400, Oracle XML Publisher displays page one as "400 of (x+400)" where x is the number of pages in the current Report Set.

Coversheet If set to Yes, Oracle XML Publisher incorporates the coversheet in the PDF output. The default setting is Yes.

Coversheet Orientation Select either Portrait (vertical) or Landscape (horizontal) for the orientation default value for the coversheet Overlay Template Definition. The default value is Portrait. See "Creating Overlay Templates" for more information.

TOC If set to Yes, Oracle XML Publisher generates a table of contents (TOC) for the Report Set. If set to No, Oracle XML Publisher does not generate a table of contents.

Note:

If TOC is set to Yes for a Report Set that contains multiple volumes, the system generates a single TOC in a separate PDF file.

TOC Orientation Select either Portrait (vertical) or Landscape (horizontal) for the orientation default value for the table of contents Overlay Template Definition. The default value is Portrait. See "Creating Overlay Templates" for more information.

Post-Processing Parameters at the Report Set and Report Set Entry Levels

The following Post-Processing Parameters appear at the Report Set Entry level and, unless otherwise noted, at the Report Set level:

Paper Size Select either A4 (European and Japanese standard) or US Letter (North American standard).

Note:

The system uses this setting to determine which OTD Files to use from the specified OTD. Setting this Parameter does not guarantee that your reports will print correctly for the size of paper. That depends on the OTD file itself and on the output of the Program.

Language In the Oracle LSH Release 2.4.8 there is only one option: English.

Calculated Title (Report Set Entry level only) Use this Parameter to receive a generated title for the Report Set Entry from a Program output Parameter whose value is propagated to calculated_title. The default value is null. If this value is null at runtime, the system uses the Report Set Entry's defined Full Title as the displayed title. See "Passing Report Set Entry Values to and from Programs".

Shared Title (Report Set Entry level only) Use the shared_title Parameter to pass the Title properties values to the Program instance, so that the Program instance can generate a different calculated title (the Program Title). See "Setting Title Properties" and "Passing Report Set Entry Values to and from Programs".

Watermark Text Enter the text, if any, that you want in the watermark. (A watermark is text printed across the page so that it appears to be beneath the content of the report.) If the Overlay Template Definition file you specify does not have a watermark defined, the system ignores this value.

If you want the watermark to display the current validation status (Development, Quality Control, or Production) of the Report Set or Report Set Entry, enter: <VS>

To substitute your own terminology for any of the three validation statuses, enter three pipes (|) after the VS, each followed by the value you want to display when the validation status is Development, Quality Control, or Production, respectively. For example:

  • To display "Dev," "QC," or "Final," enter: <VS|Dev|QC|Final>

  • To display no watermark if the validation status is Production, but "Dev" or "QC" if the validation status is Development or Quality Control, enter: <VS|Dev|QC|>

You can also have a string of fixed text on either side of the validation status or its equivalent, or only fixed text.

  • To display y text before the validation status and x text after it, enter: y <VS|Dev|QC|Final> x

  • To display the string xyz by itself, enter: 'xyz'

Table 9-2 Examples of Validation Status-Based Watermark Values

Parameter Value Development Quality Control Production

<VS>

Development

Quality Control

Production

<VS|Dev|QC|Final>

Dev

QC

Final

<VS|Dev|QC|>

Dev

QC

<none>

y < VS|Dev|QC|Final> x

y Dev x

y QC x

y Final x


Pre-Narrative Orientation Select either Portrait (vertical) or Landscape (horizontal) for the orientation default value for Overlay Template Definitions for narratives that appear before or instead of reports. The default value is Portrait. See "Creating Overlay Templates" for more information.

Post-Narrative Orientation Select either Portrait (vertical) or Landscape (horizontal) for the orientation default value for Overlay Template Definitions for narratives that appear after reports. The default value is Portrait. See "Creating Overlay Templates" for more information.

Hyperlink1...5 Target (Report Set Entry level only) You can set up your Overlay Template to display hyperlinks to other Report Set Entries. If your Overlay Template is set up for this, and you want to create a hyperlink to another Report Set Entry from the current one, click the Search icon and select its Full Title from the list of values.

You can set up the Overlay Template to display up to five (5) of these hyperlinks to other Report Set Entries, using the subsequently numbered Hlinkx Target Parameters.

Hyperlink1...5 Text (Report Set Entry level only) Enter the text to be displayed for each hyperlink. The default text is the Full Title of the Report Set Entry you selected for the corresponding HLinkx Target Parameter.

Setting Program Parameter Values

When you submit the Execution Setup for a Report Set or a Report Set Entry, the system executes the associated Program(s) with the Parameter values supplied in the Execution Setup. You can set Program Parameter values and attributes in the Program definition or the Execution Setup definition.

Creating Parameters for Sharing Values within the Report Set

You can define your own Parameters at the Report Set level (or at the Report Set Entry level) for the purpose of sharing a single value to similar Parameters in Program instances throughout the Report Set (or in a particular Report Set Entry and its child Report Set Entries), and set up automatic value propagation from those Parameters.

For example, if the Report Set should run on data for a single study, and many Program instances included in the Report Set have a Parameter for Study Name or Study ID, define a Report Set-level Parameter Study Name and/or Study ID and set up automatic value propagation. Then the person submitting the Report Set for execution only needs to enter the study name or ID a single time.

See "Setting Up Parameter Value Propagation".

Note:

Do not use spaces in the name of any Parameter you create for use in a Report Set. This will cause an error in postprocessing because the Parameter name becomes an HTML tag, where spaces are not allowed.

If a Parameter value should be the same throughout the Report Set, define the Parameter at the Report Set level.

If the Parameter value should be the same in only a single chapter of the Report Set, you can define the Parameter in the chapter-level Report Set Entry. If you set the Parameter to Required and the Report Set Entry Parameter does not have a value at runtime, the Ready flag is set to No, alerting the user to set a value. Alternatively, define the source Parameter at the top level the Report Set and name it in such a way that it is clear that it is used just in a particular Report Set Entry.

Note:

If a Program Parameter gets its value from another Parameter in a Report Set, at runtime the system gets the value from the source Parameter even if the source Parameter is not included in the submission (because it is in a Report Set Entry that is not included). You can then enter a value manually. If the source Parameter is required and does not have a value, you get an error message.

To create a Parameter for value sharing, do the following:

  1. Go to the Parameters subtab of the Report Set or Report Set Entry.

  2. Click Add.

  3. Create a Parameter, following instructions in "Defining Parameters".

  4. If you want to pass the value of this Parameter to all others in the Report Set (or Report Set Entry) with the same name, do the following:

    1. In the Parameter Instance screen, click Update.

    2. Under Value Propagation, select Automatically pass value(s) to parameters with the same name.

    3. Click Apply.

When you add a Program instance to the Report Set that should receive a Parameter value from this Parameter, define value propagation from this Parameter for the Program instance Parameter; see "Setting Up Value Propagation from the Target Parameter".

Defining Report Set Entries

This section contains the following topics:

Each Report Set Entry can contain one or more of the following:

  • Other Report Set Entries—these are subsections, or children, of the Report Set Entry within which they are defined

  • One assigned Program instance and Planned Output to generate a report in the chapter or section represented by the Report Set Entry.

  • Pre-Narrative—a text narrative displayed either before a report or instead of a report in the chapter or section represented by the Report Set Entry. You can either enter text or upload text from a file

  • Post-Narrative—a text narrative displayed after a report in the chapter or section represented by the Report Set Entry. You can either enter text or upload text from a file.

You assign a Program instance and Planned Output to a Report Set Entry from the Report Set Structure view (see "Assign Planned Output") or from a Report Set Entry's Properties screen (see "Assigning a Planned Output to a Report Set Entry").

Creating Multiple Report Set Entries

To create a Report Set Entry, navigate to the Report Set or Report Set Entry under which you want to create a new Report Set Entry, and:

  1. Click Add. The Add Entries screen appears.

  2. Enter values as necessary in the following fields for each Report Set Entry you want to add at this level. Click Add 30 Entries if you need any additional rows.

    • Entry No. Prefix. (Optional) The system uses text you enter here, if any, in the Full Title in the table of contents to identify the Report Set Entry. You can use the prefix and suffix to include information that is not part of the actual title of the Report Set Entry but which you need to display. For example, you may require a set of reports so large that you decide to create multiple Report Set definitions to manage it, with one for each volume. To make the numbering unique across the larger set of reports, you must add the volume number as a prefix to each Report Set Entry number.

      Oracle truncates spaces at the beginning and end of text in fields. If you want a space to appear between the prefix and the parent number, type \sp\ instead of using the space bar on the keyboard.

      If you want a delimiter character to appear between the prefix and the parent number, you must type it here.

      If you want the system to include the Entry No. Prefix in the Program Title that is available to pass to the Program assigned to the Report Set Entry, leave the checkbox selected. If not, deselect it. See "Passing Report Set Entry Values to and from Programs" for further information.

    • Parent Number. This read-only field contains the number of the Report Set Entry that is the parent of all the Report Set Entries listed here. (If these Report Set Entries are at the top level in the Report Set, this column contains no value.)

      The system automatically concatenates parent and child Report Set Entries' numbers. If parent Report Set Entry 10 contains child Report Set Entries 1-3, the system gives the child Report Set Entries numbers 10.1, 10.2, and 10.3. If Report Set Entry 10.2 has two child Report Set Entries, they become 10.2.1 and 10.2.2, and so on.

      You use the Delimiter Parameter to determine what punctuation the system inserts between numbers; see Delimiter below.

      If you want the system to include the Parent Number in the Program Title that is available to pass to the Program assigned to the Report Set Entry, leave the checkbox selected. If not, deselect it. See "Passing Report Set Entry Values to and from Programs" for further information.

    • Delimiter. Enter the character you want the system to use to separate the Entry Number from the Entry Number of the parent Report Set Entry. If there is no parent Report Set Entry, this value has no effect. The default is a period (full stop) (.), which is used in the examples under Parent Number above. In those examples, if you entered a comma as the Delimiter, for example, the Report Set Entry numbers would be displayed as 10,1 10,2 and 10,3 and 10,2,1 and 10,2,2. Oracle truncates spaces at the beginning and end of text in fields. If you want a space to appear between the delimiter and entry number, type \sp\ instead of using the space bar on the keyboard.

      If you want the system to include the Delimiter in the Program Title that is available to pass to the Program assigned to the Report Set Entry, leave the checkbox selected. If not, deselect it. See "Passing Report Set Entry Values to and from Programs" for further information.

    • Entry No. Accept the default value or enter the number that represents the order number of this Report Set Entry in relation to other Report Set Entries contained within the same parent Report Set Entry.

      Note:

      If you enter numbers in a nonsequential order, after you apply your changes, the system displays sibling Report Set Entries in order, using the numbers you entered, provided that the set of entry numbers does not violate the numbering settings defined in the parent Report Set or Report Set Entry: if Strict is set to Yes, numbers must be sequential, with no gaps; if Unique is set to Yes, numbers must be unique within the parent.

      To change the order, you can use the Reorder feature. See "Reordering and Renumbering Objects" for further information.

      If you want the system to include the Entry No. in the Program Title that is available to pass to the Program assigned to the Report Set Entry, leave the checkbox selected. If not, deselect it. See "Passing Report Set Entry Values to and from Programs" for further information.

    • Entry No. Suffix. (Optional) The system uses text you enter here in the Full Title in the table of contents to identify the Report Set Entry. If you need additional numbers and/or text to follow the Report Set Entry's number in its full title, enter it here. For example, you can include the word "Table," "Listing," or "Figure" (or any other text string) as the suffix.

      If you want a space to appear between the entry number and the suffix, type \sp\ at the beginning of the suffix.

      If you want the system to include the Entry No. Suffix in the Program Title that is available to pass to the Program assigned to the Report Set Entry, leave the checkbox selected. If not, deselect it. See "Passing Report Set Entry Values to and from Programs" for further information.

    • Title. Enter a title for the Report Set or Report Set Entry. The system displays this value as part of the Full Title in the table of contents to identify the Report Set Entry. The title value is not required to be unique in the Report Set. You can pass its value to the Program that generates the Report Set Entry's Planned Output. The system passes the title value to the Report Set Entry name, which is used internally only. (The internal name must be unique. If another Report Set Entry exists with the same name, the system creates a unique name for the newer Report Set Entry by appending or incrementing _1.)

      This field is required unless the Placeholder flag is set to Yes, in which case the system gives the Title the value: Placeholder.

      Note:

      The system concatenates the values of the fields up to and including the Title, in the order shown, to create the Full Title for the Report Set Entry.
    • Subtitle (Optional; Oracle LSH does not use this value). Enter a subtitle for the Report Set Entry. The system can pass this value as a Parameter value for post-processing; see "Passing Report Set Entry Values to and from Programs" for further information.

    • Report Type. (Optional; Oracle LSH does not use this value). From the drop-down list, select Figure, Listing, or Table. The system can pass this value as a Parameter value during execution; see "Passing Report Set Entry Values to and from Programs" for further information. The values displayed are configurable. Instructions are in the Oracle Life Sciences Data Hub System Administrator's Guide

    • Placeholder. Set to Yes to exclude the Report Set Entry from the table of contents. You can use this feature to force the system to accept unconventional numbering. The system does not display a placeholder Report Set Entry in the generated table of contents.

      For example, if you have chapter 16 and subsections 16.1.1 and 16.1.2 but no section 16.1, define section 16.1 as a placeholder. In the table of contents, the system does not display 16.1 but it does display chapter 16 and subsections 16.1.1 and 16.1.2.

      The default value is No (the report set entry is not a placeholder).

    • Strict. Set to Yes if you want to force numbering of Report Set Entries within the Report Set Entry to be sequential, with no gaps. Set to No if you want to allow gaps.

    • Unique. Set to Yes if you want to enforce unique numbering of Report Set Entries within the Report Set Entry. Set to No if you want to allow duplicate numbers.

    • Volume Break. Set to Yes if you want this Report Set Entry to start a new volume in the post-processed PDF Report Set output.

    • Volume Name. If Volume Break is set to Yes, enter the title you want to give the volume that will begin with this Report Set Entry. If Volume Break is set to No, the system ignores the Volume Name, if any.

  3. Repeat for as many Report Set Entries as you need with the same parent Report Set or Report Set Entry.

  4. Click Apply. The Report Set instance screen appears. To complete the definition of these Report Set Entries, navigate to each Report Set Entry in turn and do the following:

    • (Optional) Click Assign to assign a Program instance and Planned Output to the Report Set Entry. This is required if you want to include a report in the chapter or section represented by the Report Set Entry; but it is optional because you can have Report Set Entries that serve only to organize their subentries and/or display narrative text. See "Assigning a Planned Output to a Report Set Entry".

    • (Optional) Click Add a Pre-Narrative or Post-Narrative. Pre- and post-narratives are text that appears immediately before or after the actual generated report, or instead of a report, in a Report Set Entry. See "Adding Narratives".

    • (Optional) Click Update. The system makes all other Report Set Entry property fields modifiable; see "Setting Report Set Entry Properties".

    • (Optional) Create Report Set Entry Parameters and/or change the default value of Overlay Template and Post-Processing Parameters; see "Creating and Setting Report Set Parameters".

Setting Report Set Entry Properties

This section contains the following topics:

In the main Report Set Entry screen you can set values for many Report Set Entry properties. Reach this screen by clicking on the Report Set Entry's name in the Report Set Structure view, or by navigating to it from the Report Set's Properties screen.

To modify most Report Set Entry properties you must click Update. However, to assign a Program instance and/or Planned Output or to add a Narrative, you must not click Update.

Setting Overall Properties

Enter values for the following properties for the Report Set Entry:

Title Enter a title for the Report Set or Report Set Entry. The system displays this value as part of the Full Title in the table of contents to identify the Report Set Entry. The title value is not required to be unique in the Report Set. The system passes the title value to the Report Set Entry name, which is used internally only and is required to be unique. If another Report Set Entry exists with the same name, the system creates a unique name for the newer Report Set Entry.

This field is required unless the Placeholder flag is set to Yes.

Subtitle (Optional; Oracle LSH does not use this value.) Enter a subtitle for the Report Set or Report Set Entry. The system can pass this value as a Parameter value for post-processing; see "Passing Report Set Entry Values to and from Programs" for further information.

Description (Optional) Enter a description for the Report Set Entry.

Report Type (Optional; Oracle LSH does not use this value.) Select the expected output type; for example, Table, Figure, or Listing. The system can pass this value as a Parameter value during execution; see "Passing Report Set Entry Values to and from Programs" for further information. The values displayed are configurable. Instructions are in the "Modifiable Lookups" section of the lookups chapter in the Oracle Life Sciences Data Hub System Administrator's Guide.

Note:

To change the Program Title or Full Title, see "Setting Title Properties".

Setting Title Properties

The system concatenates the title properties (except Placeholder) in the order shown below, plus the Title, to generate the Full Title. The Report Set table of contents displays the Full Title.

Select the checkbox of each property you want the system to concatenate with the Title to generate the Program Title. The system can pass the Program Title to the assigned Program instance during execution; see "Passing Report Set Entry Values to and from Programs" for further information.

For information about each property, see "Creating Multiple Report Set Entries".

The title properties are:

Setting Assigned Program Properties

Report Set Entries have format-related properties whose values can be passed to the assigned Program instance during Report Set execution. In your Program source code you can use these values to format the report output; see "Passing Report Set Entry Values to and from Programs". Oracle LSH does not use these values. The following properties are available for use. You can add allowed values for some of them. Instructions are in the chapter "Adding and Modifying Lookup Values" in the Oracle Life Sciences Data Hub System Administrator's Guide.

A Report Set Entry inherits default values for the Assigned Program Properties from its parent Report Set Entry. The top-level Report Set uses system defaults. You can reset them manually at any level.

Note:

You can assign a Program instance and Planned Output to a Report Set Entry in either the Report Set Structure View or in the Properties screen of the Report Set Entry.

Page Size Horizontal (Number) Enter the horizontal measurement of the page. If your company does not configure a list of values, the default value is 210 (cms).

Page Size Vertical (Number) Enter the vertical measurement of the page. If your company does not configure a list of values, the default value is 297 (cms).

Page Size Unit The unit in which the horizontal and vertical measurements are given. If your company does not configure a list of values, the default value is cms (centimeters).

Program Title Font Name Select the name of the font in which you want the title to appear. If your company does not configure a list of values, the default value is Courier.

Program Title Font Size (Number) Enter the size of the font in which you want the title to appear. If your company does not configure a list of values, the default value is 10.

Footer Enter the text you want to use as the footer on each page of the report, up to 200 characters.

Page Size Margin Left (Number) Enter the size of the margin you want at the left side of the page. If your company does not configure a list of values, the default value is 3.42 (cms).

Page Size Margin Top (Number) Enter the size of the margin you want at the top of the page. If your company does not configure a list of values, the default value is 3.42 (cms).

Adding Narratives

You can add and remove Narratives only when you are not in update mode; see "Adding Narratives".

Setting Numbering Properties

You can modify the numbering properties as follows:

Strict If you want to require that all Report Set Entries contained in this Report Set Entry have sequential numbering, with no gaps, select Yes. The default value is shared from the parent Report Set Entry or Report Set.

Unique If you want to require that each Report Set Entry contained in this Report Set Entry have a unique number within this Report Set Entry, select Yes. The default value is shared from the parent Report Set Entry or Report Set.

Setting Volume Break Properties

Set the Volume Break properties as follows:

Volume Break If you want this Report Set Entry to be the first in a separate PDF file, or volume of the Report Set, select Yes. The default value is No.

Volume Name If you want this Report Set entry to be the first in a separate PDF file, or volume of the Report Set, enter the name of the volume you want it to start.

Note:

If you enter a Volume Name but set Volume Break to No, Oracle XML Publisher does not create a volume break at this Report Set Entry (and does not use the Volume Name value).

You can override these settings at the Report Set level by defining a value for the Report Set Post-Processing Parameter Single Volume Output Name. If that Parameter has a value, the system generates a single volume with the name specified and ignores all Report Set Entry volume-related values.

Adding Narratives

A narrative is text that you can add to a Report Set Entry either in addition to or instead of reports generated by a Program instance. If a Report Set Entry contains both narratives and a Program instance, the narratives appear on the same page as reports either immediately before or after the report generated by the Program instance.

Narratives added as Pre-Narratives appear before the report, and narratives added as Post-Narratives appear after the report.

To add a narrative, you must not be in Update mode.

  1. In the Report Set Entry's Properties screen, click either the Pre-Narrative or Post-Narrative Add button. The appropriate Add screen opens.

  2. Either upload a file containing the text or enter the text:

    • To upload text, click Browse. The Choose file window opens. Browse and select the text file. Click Open. The system copies the text into the Narrative Description text box.

      Note:

      The system does not store the file in Oracle LSH when you upload it. The system copies the text content as a string.
    • Alternatively, enter text in the Narrative Description text box.

      Note:

      If you both upload a text file and enter text, the file you upload overwrites the text you enter.
  3. Click Apply. The system returns you to the Report Set Entry screen.

Defining Programs to Generate Reports

This section contains the following topics:

About Programs in Report Sets

A Report Set's reports are generated by Program instances in the Report Set. You can create a Program definition and instance from within a Report Set, or you can create an instance in a Report Set of a Program definition in an Application Area or Domain. You can have Programs of different technology types (for example, SAS, PL/SQL, and Oracle Reports) in the same Report Set. See Chapter 5, "Defining Programs" for general information about Programs in Oracle LSH.

Each Program instance in a Report Set can have any number of primary Planned Outputs, each of which corresponds to a single report output. You can assign each Planned Output to a Report Set Entry. When you execute the Report Set, each report appears in the Report Set in the location defined by its Report Set Entry.

Each Program instance in a Report Set is executed once during Report Set execution and can be submitted with only one set of Parameter values. Therefore, when you change a Program Parameter value in the Execution Setup definition or at submission under one Report Set Entry, the value is effectively changed for all Report Set Entries assigned to the same Program instance.

Similarly, when you execute the Report Set, you must select a single currency and blinding status for the Report Set instance.

Only one person can check out and work on a particular Program instance in a Report Set at a time. In addition:

  • Programs that are checked out by other people when you execute a Report Set are not executed and a message to that effect appears in the Report Set output if you create an Overlay Template for that purpose (see "Creating an Overlay Template Definition"). The information is also in the Report Set's log file. If you have a Program checked out, the system executes the installed version of it.

  • Programs that are checked out during Report Set installation by another user are not installed; see "Installing Report Sets".

Developing Programs inside Report Sets is different from developing independent Programs in the following ways:

  • Planned Outputs. You can assign each primary Planned Output that you want to include in the Report Set to a different Report Set Entry. Do this in the Report Set Entry or the Report Set Structure view; see "Assigning a Planned Output to a Report Set Entry". You are not required to assign every Planned Output to a Report Set Entry. Any unassigned Planned Outputs are not included in the Report Set output.

  • Mapping. All the standard Oracle LSH methods of mapping are available:

    • Automatic Mapping by Name is available for multiple Program instances at once from the Report Set Structure View and for one Program instance at a time from the Program View.

    • Create Table Descriptors from Existing Table Instances, which includes mapping, is available from the Actions drop-down on each Program instance's Properties screen.

    • Create Table Instances from Existing Table Descriptors, which includes mapping, is available from the Actions drop-down on the Report Set's Properties screen. You can select Table Descriptors from all Program instances in the Report Set.

      Note:

      If you map or modify the mappings of a checked-in Program instance, the system implicitly checks out the Program instance. This ensures that the Program instance and associated mappings must be installed (and therefore versioned) if any of its mappings are modified.
  • Parameters. As with Programs outside of Report Sets, you can define Parameters as necessary and set them in the Program instance, in the Execution Setup, or at runtime. In addition, you can pass the values of Report Set Entry properties to the Program instance and back; see "Passing Report Set Entry Values to and from Programs".

    You can also define Parameters directly at the Report Set or Report Set Entry level for the purpose of sharing their value with Program input Parameters at runtime, and you can populate the value of one Program's input Parameter with the value of another Program's output Parameter at runtime; see "Creating Parameters for Sharing Values within the Report Set".

  • Output Reuse. Unless you specify otherwise, Oracle LSH does not regenerate an output if the Program instance version, data currency, and Parameter values have not changed since the last execution that produced a nonretired output; see "Output Reuse".

    You can force the system to run the job and regenerate the output by setting the system Parameter Force Execution to Yes in the Execution Setup or at submission.

    Note:

    Setting Force Execution to Yes reruns all the Program instances whose Report Set Entries are included in the execution. Use this option only if you want all of these outputs to be reproduced.

Note:

It is possible to include Program instances in a Report Set that transform data, or that both transform and report data. However, for the best Report Set execution performance, Oracle recommends including only Program instances that report data, not Programs that transform data, inside a Report Set. Instead, run transform Program instances outside the Report Set and use their target Table instances as the source Table instances for Program instances in the Report Set.

You can add Programs, map their Table Descriptors, and submit them for execution in several different Oracle LSH screens. See the following sections for details:

  • Report Set Structure View. To reach the Structure view, click the Report Set's hyperlink under the Work Area and then select Structure from the View drop-down if it is not already selected; see "Building and Modifying the Report Set".

  • Report Set Program View. To reach the Structure view, click the Report Set's hyperlink under the Work Area and then select Program from the View drop-down if it is not already selected; see "Options from the Report Set Program View Screen"

  • Report Set Entry Add Screen. To reach the Add Report Set Entries screen, go first to the Report Set Properties screen by clicking its hyperlink in the Report Set Structure view. Then click Add Entries; see "Creating Multiple Report Set Entries".

  • Report Set Entry Properties Screen. To reach a Report Set Entry's Properties screen, click its hyperlink in the Report Set Structure view; see "Setting Report Set Entry Properties".

Assigning a Planned Output to a Report Set Entry

After you assign a Program instance to a Report Set Entry, you can assign its primary Planned Outputs to other Report Set Entries in the same Report Set. The system then places the actual report generated by the Program instance for that Planned Output in the chapter or subsection corresponding to the Report Set Entry.

If you select a Report Set Entry that already has a Planned Output assigned, you can change the assignment by selecting a different one.

You can assign a Planned Output as follows:

  • In the Report Set Structure view, select the Report Set Entry to which you want to assign a Planned Output, select Assign Planned Output from the drop-down list, and click Go.

  • In the Report Set Entry Properties screen (not in Update mode), click the Assign button.

In both cases, the Assign Program Instance and Planned Output screen opens. Do the following:

Note:

If the Report Set Entry already has a Planned Output assigned, the screen is populated with the Planned Output's Program instance and all its Planned Outputs. You can select a different Planned Output of the same Program or follow the instructions below to select a different Program instance and Planned Output.
  1. In the Search By Program Instance field, click the Search icon. The Search and Select window opens.

  2. Click Go, or enter the name of the Program instance whose Planned Output you want to assign and then click Go.

    The system lists Program instances already assigned to the Report Set. If you have entered the name of the Program instance, the system displays only that Program instance.

    Note:

    The system displays only checked-in Program instances.
  3. Click the icon in the Quick Select column for the Program instance whose Planned Output you want to assign.

    The system returns you to the Assign Planned Output screen with the Program instance name displayed.

  4. Click Go. The system displays the Planned Outputs of the selected Program instance.

    If a Planned Output is already assigned to a Report Set Entry, the system displays that Report Set Entry's number and title in the Assigned to RSE column.

  5. Select the Planned Output you want to assign and click the Select button. The system assigns the Planned Output to the current Report Set Entry. If you select a Planned Output that is already assigned to another Report Set Entry, the system removes it from that Report Set Entry.

Options from the Report Set Program View Screen

To reach the Program View screen, navigate to the Report Set in the Applications tab hierarchy and click its hyperlink. Then select Program from the View drop-down list.

In the Report Set Structure view you can build and modify the Report Set structure and do many other things as follows:

  1. Select a Program instance.

  2. Select one of the following items from the drop-down list.

  3. Click Go.

The following actions are available:

  • Copy. The system opens the Paste screen and copies the Program instance you selected into the location you specify: either a Report Set or a Work Area. The system copies the Program instance's Execution Setup(s) and Table Descriptor mappings. See "Copying, Cloning, and Moving Objects" for instructions.

  • Default Execution Setup. If a default Execution Setup already exists for this Program, the system displays it. If a default Execution Setup does not yet exist, the system automatically creates one; see "Creating, Modifying, and Submitting Execution Setups" for further information.

  • Install. The system installs the selected Program instance. You can install a Program instance if it is checked in or if you have checked it out.

  • Map. The standard Mapping screen opens. The Table Descriptors of this Program only are available for mapping; see "Defining and Mapping Table Descriptors". You can map Table Descriptors for multiple Program instances at once in the Report Set Structure view.

  • Remove. The system deletes the selected Program instance. If the Program instance is assigned to one or more Report Set Entries, you get a warning. You can see where its Planned Outputs are assigned by clicking its hyperlink to open its Properties screen and then clicking the Planned Outputs tab.

    The Program definition is not affected.

  • Quick Submit. The system submits the Program instance using the default Execution Setup with its default values, without opening the Execution Setup screen. The system upgrades the Execution Setup if necessary and validates it. The submission fails if:

    • The Execution Setup cannot be upgraded; for example, if another user is currently modifying the default Execution Setup

    • The Execution Setup is invalid; for example, the Parameters that apply to the portion of the Report Set being submitted have invalid values

    In the Job Execution section of the My Home page you see two jobs. A temporary job starts the actual report generation job.

  • Submit. The system opens the submission screen for the default Execution Setup. From there you can set Parameters and submit the Program instance. The system automatically includes in the submission all Report Set Entries to which the Program is assigned. See "Creating, Modifying, and Submitting Execution Setups".

    To submit a different Execution Setup, click the Program's hyperlink to open its Properties screen. Select Execution Setups from the Actions drop-down list and follow instructions in "Creating, Modifying, and Submitting Execution Setups".

    Note:

    You can submit a Program instance in a Report Set only if it is installed and assigned to at least one Report Set Entry.

View Programs Click a Program's hyperlink in the Name column to go to that Program's Properties screen.

Viewing Planned Output Assignments

You can see information about Planned Output assignments in the following places:

  • In the Report Set instance's Program view, there is a column that displays the number of primary Planned Outputs each Program has, and another column for the number of primary Planned Outputs that are not currently assigned to a Report Set Entry. To see which Planned Outputs are assigned to which Report Set Entries, click the hyperlink on the Program's name, then open the Planned Outputs tab.

  • In the Report Set instance's Structure view, there is a column for Assigned Planned Output that displays the name of the Planned Output assigned to each Report Set Entry.

  • In the Properties screen for each Report Set Entry, the system displays the name of the Program instance and Planned Output currently assigned to the Report Set Entry. This is the only place where you can create and remove Planned Output assignments. See "Assigning a Planned Output to a Report Set Entry" for instructions.

Passing Report Set Entry Values to and from Programs

This section contains the following topics:

You can pass the values of title- and formatting-related Report Set Entry properties to the Program assigned to a Report Set Entry, use these values in the Program's source code during execution, and then send a values back to the Report Set for use during postprocessing.

Different Report Set Entries assigned to the same Program instance can have different values for the same Report Set Entry properties. If you use this feature, your source code must handle the input from different Report Set Entries, and the output to different Report Set Entries, correctly.

Report Set Entry Properties Available for Passing

You can pass the values of Report Set Entry assigned program properties and several additional properties from a Report Set Entry to its assigned Program and use them in the Program to format the output of the Report Set Entry. See "Setting Assigned Program Properties" for a description of each Program property.

You can also pass values for the following:

  • File Reference Name Each Planned Output can have only one file reference name, and each Planned Output is assigned to only one Report Set Entry. Oracle recommends using the file reference name in your Program code to distinguish the properties of one Report Set Entry from another one to which another Planned Output of the same Program instance is assigned. However, Oracle LSH does not enforce unique File Reference Names among a Program's Planned Outputs; you must do that manually.

  • Full Title. The system uses the full title in the Report Set's table of contents. The Full Title includes all of the following, concatenated in the following order:

    Entry No. Prefix||Parent No.||Delimiter||Entry No.||Entry No. Suffix||" " || Title

  • Program Title. The system does not use the Program title. It always includes the Title and can include any of the other elements that the Full Title can, in the same order, if you so specify; see "Setting Title Properties" and "Passing Report Set Entry Values to and from Programs".

Passing Values from a Report Set Entry to a Program Instance

The method of passing Report Set Entry values to a Program instance differs depending on whether you are working in SAS or Oracle Reports or PL/SQL.

SAS

Oracle LSH includes a SAS data set named LSH_RS.RS_TITLE that is available when you open the SAS IDE or execute a SAS Program from within the context of a Report Set. LSH_RS.RS_TITLE includes the values of all Program properties, plus the file reference name, Full Title, Program Title, and Report Type for all the Report Set Entries to which the Program instance is assigned. The primary key is the file reference name of the Planned Output assigned to each Report Set Entry.

Note:

Oracle LSH does not enforce file reference name uniqueness among a Program's Planned Outputs. If you plan to pass values from a Report Set Entry to its Program instance, you must ensure that each Planned Output assigned to a Report Set Entry has a different file reference name.

Your source code can reference any of the values in LSH_RS.

Table 9-3 Report Set Entry Properties and Corresponding LSH_RS Data Set Variables

Property Number Variable Type Length Format Informat Label

File Reference Name

1

FILE_REF

Char

8

$8.

$8.

FILE_REF

Title

2

TITLE

Char

4000

$4000.

$4000.

TITLE

Full Title

3

TOCTITLE

Char

4000

$4000.

$4000.

TOCTITLE

Program Title

4

RSETITLE

Char

200

$200.

$200.

RSETITLE

Prefix

5

PREFIX

Char

200

$200.

$200.

PREFIX

Parent No.

6

PARENT

Char

4000

$4000.

$4000.

PARENT

Delimiter

7

DELIMIT

Char

30

$30.

$30.

DELIMIT

Entry No.

8

ENTRY

Char

200

$200.

$200.

ENTRY

Suffix

9

SUFFIX

Char

200

$200.

$200.

SUFFIX

Subtitle

10

TITLE2

Char

200

$200.

$200.

TITLE2

Report Type

11

REP_TYPE

Char

4000

$100.

$4000.

REP_TYPE

Footer

12

FOOTER

Char

200

$200.

$200.

FOOTER

Program Title Font Name

13

FONTNAME

Char

4000

$20.

$4000.

FONTNAME

Program Title Font Size

14

FONTSIZE

Num

8

6.

7.

FONTSIZE

Page Size Horizontal

15

PS_HORI

Num

8

6.

7.

PS_HORI

Page Size Vertical

16

PS_VERT

Num

8

6.

7.

PS_VERT

Page Size Unit

17

PS_UNIT

Char

20

$20.

$20.

PS_UNIT

Page Size Margin Left

18

PS_LEFT

Num

8

6.2

8.2

PS_LEFT

Page Size Margin Top

19

PS_TOP

Num

8

6.2

8.2

PS_TOP

Volume Name

20

VOL_NAME

Char

255

$255.

$255.

VOL_NAME


Passing Values from a Program Instance to the Report Set for Post-Processing

You call Oracle LSH APIs from either SAS or Oracle Reports or PL/SQL to pass values from the executed Program instance to the Report Set for postprocessing.

Refer the Oracle Life Sciences Data Hub Application Programming Interface Guide for details.

SAS

The example function below uses APIs to retrieve values from the Program instance and pass them to Oracle LSH for Report Set postprocessing. It uses a PL/SQL wrapper that you call from SAS. Within the wrapper, the function calls several Oracle LSH public APIs to do the work.

If a particular Planned Output is not assigned to a Report Set Entry when you execute the Program instance, the function returns "Title for fileref_name" with the fileref name of the unassigned Planned Output.

Example 9-1 Function to Pass Title and Other Values from SAS to Oracle LSH

SAS code
--------------------------------------------------------------------------------
Proc SQL;
/*set the job context then send the output value*/
connect to oracle (user=%sysget(CDR_SCHEMA) pass=%sysget(CDR_PASSWD)
path=%sysget(CDR_DB) );
 
/* pass output parameter, sub title and title back to LSH */
execute(exec my_plsql_package.CallLSHApi(
'MyParamName'
,'My Param Value'
,'out1'
,'My Output Title'
,'out1'
,My Output Sub Title'
)
by oracle ;
 
PL/SQL code
--------------------------------------------------------------------------------
CREATE OR REPLACE PACKAGE my_plsql_package AS
Procedure CallLSHApi(
pi_vParamName IN varchar2
,pi_vParamValue IN varchar2
,pi_vTitleFileRef IN varchar2
,pi_vTitle IN varchar2
,pi_vSubTitleFileRef IN varchar2
,pi_vSubTitle IN varchar2
);
END my_plsql_package;
/
 
CREATE OR REPLACE PACKAGE BODY my_plsql_package AS
Procedure CallLSHApi(
pi_vParamName IN varchar2
,pi_vParamValue IN varchar2
,pi_vTitleFileRef IN varchar2
,pi_vTitle IN varchar2
,pi_vSubTitleFileRef IN varchar2
,pi_vSubTitle IN varchar2
) IS
 
return_status VARCHAR2(10);
msg_count NUMBER;
msg_data VARCHAR2(2000);
BEGIN
   Cdr_Pub_Exe_User_Utils.setOutputParams(p_api_version => 1
               ,p_init_msg_list => Cdr_Pub_Def_Constants.G_FALSE
               ,p_commit => Cdr_Pub_Def_Constants.G_FALSE
               ,p_validation_level => Cdr_Pub_Def_Constants.G_VALID_LEVEL_FULL
               ,x_return_status => return_status
               ,x_msg_count => msg_count
               ,x_msg_data => msg_data
               ,pi_vparamName => pi_vParamName
               ,pi_vparamValue => pi_vParamValue) ;
   IF return_status <> 'S' THEN
      RAISE_APPLICATION_ERROR(-20200,'Failed to call Cdr_Pub_Exe_User_Utils.setOutputParams: '||msg_data);
   END IF ;
   Cdr_Pub_Exe_User_Utils.SetCustomOutputTitle(p_api_version => 1
               ,p_init_msg_list => Cdr_Pub_Def_Constants.G_FALSE
               ,p_commit => Cdr_Pub_Def_Constants.G_FALSE
               ,p_validation_level =>Cdr_Pub_Def_Constants.G_VALID_LEVEL_FULL
               ,x_return_status => return_status
               ,x_msg_count => msg_count
               ,x_msg_data => msg_data
               ,pi_vFileRef=> pi_vTitleFileRef 
               ,pi_vValue => pi_vTitle ) ;
   IF return_status <> 'S' THEN
      RAISE_APPLICATION_ERROR(-20200,'Failed to call Cdr_Pub_Exe_User_Utils.SetCustomOutputTitle: '||msg_data);
   END IF ;
   Cdr_Pub_Exe_User_Utils.SetCustomOutputSubTitle(p_api_version => 1
               ,p_init_msg_list => Cdr_Pub_Def_Constants.G_FALSE
               ,p_commit => Cdr_Pub_Def_Constants.G_FALSE
               ,p_validation_level => Cdr_Pub_Def_Constants.G_VALID_LEVEL_FULL
               ,x_return_status => return_status
               ,x_msg_count => msg_count
               ,x_msg_data => msg_data
               ,pi_vFileRef=> pi_vSubTitleFileRef 
               ,pi_vValue => pi_vSubTitle ) ;
   IF return_status <> 'S' THEN
      RAISE_APPLICATION_ERROR(-20200,'Failed to call Cdr_Pub_Exe_User_Utils.SetCustomOutputSubTitle: '||msg_data);
   END IF ;
END CallLSHApi;
END my_plsql_package;
/
Oracle Reports or PL/SQL

To pass Title and Program property values from a Program instance to the Report Set for postprocessing in a PL/SQL Program, you can call Oracle LSH public APIs:

  • Cdr_Pub_Exe_User_Utils.SetCustomOutputTitle. Use this API to pass the title from the Report Set Entry to the Program instance.

  • Cdr_Pub_Exe_User_Utils.SetCustomOutputSubTitle. Use this API to pass the subtitle from the Report Set Entry to the Program instance.

  • Cdr_Pub_Exe_User_Utils.setOutputParams. Use this API to pass every other value you need from the Report Set Entry to the Program instance.

Installing Report Sets

This section contains the following topics:

Installing a Report Set is complicated because of its size and the fact that many people can work on it at the same time. Depending on the exact timing of your action and other people's actions, you may receive an error message that the system cannot perform your action immediately because of a conflict with another user. Your work will not be lost and you can try again in a short time.

At the end of the installation process the system upgrades all checked in Report Set Execution Setups as necessary to synchronize them with the Report Set definition.

Note:

If someone is working on an Execution Setup, the Execution Setup is implicitly checked out. Checked out Execution Setups are not upgraded during installation. No message is displayed.

During the installation process, the Report Set instance itself (which includes the mappings of its Program instances to Table instances) is unavailable for modification. If the Report Set is very large the installation process may take a long time, so plan your installation accordingly.

To see a list of reasons Report Set instances may not be installable, see Appendix A, "Installation Requirements for Each Object Type".

Installing the Report Set as a Whole with All Programs Checked In

To install a Report Set as a whole, install its Work Area and include the Report Set in the installation.

If all the Programs in the Report Set are checked in, the system installs the whole Report Set and leaves the Report Set itself and all its Programs checked in. You can look at the installation log to see the details.

See "Installing a Work Area and Its Objects" for further information.

Installing the Report Set as a Whole with Some Programs Checked Out

If you install a Report Set instance and some of its Program instances are checked out by you and noone else, the system checks them in, checks in the Report Set instance and its source definition, and installs the Report Set instance.

If you install a Report Set instance and some of its Program instances are checked out by you and some by someone other than you, and you do not have the LSH Checkin Admin role, the system checks in and installs only the Program instances that were checked out by you. It does not check in the Program instances checked out by others, and it does not check in the Report Set instance or definition or install the Report Set instance.

To see which Programs were and were not installed, look at the installation log file.

Note:

If a user with the LSH Checkin Admin role installs a Report Set, all Program instances in the Report Set are checked in during the installation.

Installing a Single Program Instance in the Report Set

When you install a single Program instance in a Report Set, the system does the following:

  • Checks in the Program instance. its mappings, and its source Program definition. (If the Program definition is checked out by a user other than the user installing the Program instance, the installation fails.)

  • Checks in the Report Set Entry to which the Program instance is assigned and all Report Set Entries above it in the hierarchy

    Note:

    The Report Set definition remains checked out.
  • Installs the Program instance

  • Installs the Report Set Entries, regardless of the setting of the Omit From Install flag

  • Installs the Report Set instance

  • Installs the Table instances to which the Program's Table Descriptors are mapped, if they are not already installed

No other Program instances in the Report Set are checked in or installed.

You can install a Program instance in a Report Set in several different ways:

  • In the Report Set Structure view, select one of the Report Set Entries assigned to the Program instance, select Install Program from the drop-down list, and click Go.

  • In the Report Set Program View, select the Program instance, select Install from the drop-down list, and click Go.

  • In the Program instance's Properties screen, click Install.

Validating Report Set Definitions and Outputs

This section contains the following topics:

A Report Set may have many Report Set Entries and Program instances in different stages of development at the same time, with reports on data that may become stable at different times. Each of these—Report Set Entries, Program instances, and outputs—has a validation status. You can promote different parts of the Report Set to a new validation status at different times.

Because of this complexity, Oracle LSH provides several tools and other functionality to help you manage Report Set validation:

  • Output reuse. Each time you run a Program in a Report Set, the system checks if a duplicate output already exists. If it does, the system does not generate the output again, so that any validation work you have done on the output is still valid. See Output Reuse for further information.

  • Validation Status. Report Set instances and definitions both have a validation status like the validation status of other objects. There are some special rules for Report Sets; see "Report Set Validation Status".

  • Summary Output Validation Status. Report Set instances have an additional status that is automatically calculated for every Report Set Entry and the Report Set instance as a whole; see "Summary Output Validation Status".

There are two basic processes you can use to validate a Report Set output:

  • Validate the content of each report output manually according to your company standards; see "Output-Oriented Validation".

  • Validate each Program definition and instance according to your company standards. The Execution Setup inherits its validation status from the Program instance, and the output inherits its validation status from the Execution Setup; see "Definition-Oriented Validation".

Oracle LSH supports both approaches with a flag for each Program definition; see "Program Output Validation Flag". It is possible to use both approaches within a single Report Set.

See "Validating Objects and Outputs" for general information about validation.

Output Reuse

Each time you run a Program in a Report Set, either directly or through the Report Set, the system checks if a duplicate output already exists. An output is a duplicate if it is generated by the same version of the same Program instance with the same Parameter values on data of the same currency and blinding status.

If the current Program execution would produce an output that is a duplicate of an existing output, the system reuses the existing output in the Report Set unless it has a validation status of Retired.

If all of a Program's Planned Outputs have reusable non-Retired duplicate outputs, the system does not execute the Program at all during the Report Set execution. If one or more Planned Outputs assigned to a Report Set Entry that is included in the execution does not have a reusable duplicate output, the system executes the Program and generates all outputs, but sets the new duplicate outputs' validation status to Retired.

If the system cannot execute a Program instance because it is checked out, or if it fails execution, the Report Set cannot reuse existing outputs because the Program version is different. The Report Set uses the In Progress OTD file as a placeholder for the ungenerated output.

The Jobs screen shows all subjobs that actually ran. The Report Set log file shows which subjobs produced the outputs that were actually used and lists the outputs.

Report Set Entry Properties and Reuse Title- and format-related Report Set Entry properties can be passed to the Program instance assigned to that Report Set Entry. The same Program instance may have multiple Planned Outputs assigned to different Report Set Entries.

Oracle LSH tracks these Report Set Entry-specific values separately from other Parameter values and treats them differently in its duplicate output logic. If one of these values changes, only the output related to the Report Set Entry with the changed value is regenerated. All other outputs—assigned to other Report Set Entries—are reused if a duplicate non-Retired output exists.

For example, if Program A has Planned Outputs assigned to Report Set Entries 1.1, 1.2, and 1.3, and you enter a new value for Title or Font Size in Report Set Entry 1.1 only, and all other Parameter values and the data currency and Program instance version are the same since the last time the Program instance was executed, then the existing outputs for Report Set Entries 1.2 and 1.3 are reused.

Note:

You can force the system to produce and use new outputs for the Report Set Entries included in a submission, even if they are duplicates, by setting the Force Execution flag to Yes in the Execution Setup.

Program Output Validation Flag

The flag Force Output Validation Status to 'Development' is part of every Program definition. If selected, outputs of instances of this Program definition are always created with a validation status of Development. Use this setting if you plan to validate the contents of the output.

If deselected, the outputs inherit the validation status of the Execution Setup that produced them, which in turn can inherit its validation status from the Program instance. Use this setting if you plan to validate the source data and the Program, and allow the output to inherit its validation status from the Program's.

Your company can determine the default setting using an Oracle profile; see "Setting the Default Value for: Force Output Validation Status to Development" in the chapter on setting profile values in the Oracle Life Sciences Data Hub System Administrator's Guide.

You can use both approaches in a single Report Set for different Programs.

Report Set Validation Status

Oracle LSH enforces the following validation rules for Report Sets, their Report Set Entries, and their Program instances:

  • You can change the validation status of any Report Set Entry without affecting the validation status of other Report Set Entries either above or below it in the Report Set structure.

  • A Report Set or Report Set Entry cannot have a higher validation status than any of the Program instances it contains.

  • A Report Set cannot have a higher validation status than any of its Report Set Entries.

  • By default, the system calculates the validation status for a Report Set and for a Report Set volume, if any, as the lowest status of all the Report Set Entries it contains.

The system cascades a validation status promotion as follows:

  • Cascade Promotion from Report Set to Report Set Entries. If you try to promote a Report Set to a higher validation status and all the Program instances in the Report Set are at that status (or higher), but all the Report Set Entries are not, you have the option of cascading the higher status to all the Report Set Entries as part of the Report Set promotion. If you choose not to cascade, the operation fails, because a Report Set cannot have a higher validation status than its Report Set Entries.

    For example, if you want to promote a Report Set from Development to Quality Control (QC), and all of its Program instances are already at QC but some of its Report Set Entries are still at Development, you must promote the Report Set Entries to QC in order to promote the Report Set as a whole to QC. You can do this through a cascade operation as part of the Report Set promotion.

  • Cascade Promotion from Parent to Child Report Set Entries. If you promote a Report Set Entry that has one or more child (or grandchild, etc.) Report Set Entries with a lower validation status, you receive a message offering you the opportunity to cascade the promotion to all its children. If you choose to proceed, the operation upgrades all child (and grandchild, and so on) Report Set Entries.

    If you choose not to cascade, the operation will proceed for just the parent Report Set Entry.

  • Cascade Promotion from Program Instance to Definition. As with Program instances outside Report Sets, you can cascade a validation promotion from the Program instance to its definition. If another user has checked out the definition, the operation fails.

  • Cascade Promotion from the Report Set Output to Contributing Outputs in the Same Job. When you promote a Report Set PDF output, if any of the individual outputs included in it have a validation status lower than the one to which you are promoting the cumulative output, you receive a message asking if you would like to promote the contributing outputs produced in the same job. You must validate all or none of the PDF outputs.

    For example, if you choose to run only one Program instance during the Report Set execution, and that Program instance produces multiple outputs, you can upgrade the validation status of all outputs produced by the Program at the same time.

    Note:

    Because you are forced to validate all or none of the contributing PDF outputs, if you plan to validate a report set output, be sure to selectively remove from the job any Report Set Entries that should not be validated.

Oracle LSH enforces the following behavior for the Report Set and its components at the following validation statuses:

  • Development. When you create a new Report Set Entry, either by defining it or by copying it from another Report Set, it automatically receives a validation status of Development. Anyone with Modify privileges on the Report Set can work on it. Users can check out a Program definition through an instance of it in the Report Set if they have Modify privileges on the Program definition.

  • Quality Control. When a Report Set Entry's validation status is set to Quality Control, a user must have the Modify QC privilege on Report Sets to modify the Report Set Entry in any way, including the addition or removal of a Program instance and Planned Output assignment. A user must have the Modify Validation Status QC privilege on Report Sets to set the validation status back to Development.

  • Production. When a Report Set Entry's validation status is set to Production, a user must have the Modify Production privilege on Report Sets to modify the Report Set Entry in any way, including the addition or removal of a Program instance and Planned Output assignment. A user must have the Modify Validation Status Production privilege on Report Sets to set the validation status back to Development.

  • Retired. You cannot set the validation status of a Report Set Entry, or a Program instance in a Report Set, to Retired. If you no longer want to use a Report Set Entry or Program instance, remove it from the Report Set.

Summary Output Validation Status

In addition to the standard validation status (VS), each Report Set Entry also has a Summary Output Validation Status (SOVS). You can use this status to track which Report Set Entries do not yet have a Planned Output assigned and, if you are validating outputs manually, which outputs have not yet been promoted to a new validation status.

The system automatically calculates the SOVS for each Report Set Entry based on the validation status of its actual "current" output (if any) and on the SOVS of its child Report Set Entries (if any).

The Summary Output Validation Status can have the following values:

  • Null. The system displays no SOVS if a Report Set Entry has a Planned Output assigned but no usable current output, or if the assigned Program instance is checked out.

  • Unassigned. If a Report Set Entry is not marked as a placeholder and does not have a Planned Output or a Narrative assigned, the SOVS is Unassigned.

  • N/A (Not Applicable). If a Report Set Entry has no child Report Set Entries and either is marked as a placeholder or has a Narrative assigned, its SOVS is N/A. If a Report Set Entry does have one or more child Report Set Entries, its SOVS is N/A only if it meets both of the following conditions: all its and, in addition,

    • The SOVS of all its child Report Set Entries is N/A.

    • It is marked as a placeholder or has a Narrative assigned.

    Note:

    Although this status supports a practice of not including Narratives and Planned Outputs in the same Report Set Entry, it is in fact possible to have both. Be aware that if you assign a Narrative to a Report Set Entry before you assign a Planned Output, the SOVS will be N/A instead of Unassigned.
  • Development. If any of a Report Set Entry's child Report Set Entries has an SOVS of Null or Unassigned, the parent Report Set Entry's SOVS is Development.

    In addition, a Report Set Entry inherits the SOVS of its current output (if any) or any of its child Report Set Entries (if any), whichever has the lowest SOVS. If any of these is Development, the Report Set Entry is also set to Development.

  • Retired. If the current output of a Report Set Entry is manually set to Retired, the Report Set Entry's SOVS is also set to Retired. When the Report Set Entry's Program generates a new output, the system changes the Report Set Entry's SOVS to reflect that output's validation status.

  • Quality Control (QC). A Report Set Entry has an SOVS of Quality Control if the lowest SOVS of any of its child Report Set Entries or its current output (if any) is Quality Control.

  • Production. A Report Set Entry has an SOVS of Production if the lowest SOVS of any of its child Report Set Entries or its current output (if any) is Production.

The Report Set definition inherits the SOVS of its child Report Set Entry with the lowest SOVS. The Report Set instance inherits its SOVS from the Report Set definition.

The SOVS is displayed only in the context of a Report Set instance in a Work Area, not for the Report Set definition in its Application Area or Domain.

Output-Oriented Validation

In the output-oriented validation approach, you validate an actual report, including all its data, using the same validation standards your company has always used. The system continues to include the report you have validated in the Report Set as long as you continue to run the same Program instance version with the same currency, blinding status, and Parameter values; see "Output Reuse" for further information.

If you use the same Program instance to generate a new output of data of a different currency or blinding status, or change any other Parameter values, you must validate the resulting new output.

The output-oriented validation process includes the following steps:

  1. When you define Programs for use in a Report Set, set the Force Output Validation Status to 'Development' flag to Yes; see "Creating a Program" for further information.

    Note:

    The Force Output Validation Status to 'Development' flag is a property of the Program definition, not the instance.
  2. Define and test the Report Set structure and Program instances inside the Report Set over time.

  3. When the data a particular Program reports on reaches a point where it should be included in a report for internal use or submission, apply a snapshot label—for example, "Interim"—to the relevant Table instances, either through the job that writes the data to the Table instances or directly in the Work Area("Managing Table Instance Snapshot Labels in a Work Area"). This step is optional but recommended.

  4. Run the Report Set Entries assigned to the Program that runs on the stable data.

  5. Validate each resulting output according to your company's policies, first to Quality Control (QC) and then to Production. The system applies the validation status of the output to the Summary Output Validation Status (SOVS) of the corresponding Report Set Entry; see "Summary Output Validation Status".

  6. Manually upgrade the standard validation status (VS) of the Program instance and definition and the associated Report Set Entry.

  7. Follow the same process for other outputs and their Program instances and definitions and Report Set Entries, until the entire Report Set reaches a higher validation status.

    Note:

    The Report Set output as a whole inherits the validation status of the Program output with the lowest validation status.

    The Report Set definition and instance, and each volume defined in a Report Set, inherit the validation status of the Report Set Entry with the lowest validation status they contain.

When the source data for the original Program reaches another point where it should be included in a report for internal use or submission, apply another snapshot label; for example, "Final," and repeat the process.

Definition-Oriented Validation

In the definition-oriented validation approach, you develop standards for validating the Program instances (and their source Program definitions) that generate each Report Set report output. For example, you can use different sets of test data to test whether the report output contains the correct data. When you have successfully validated the Program definition and instance and set their validation status to Production, the Execution Setups of the Program instances inherit the validation status of Production and the outputs they produce also inherit a validation status of Production.

If you run the same version of the Program instance with different data currency, blinding status, or other Parameter values, the new outputs also have a validation status of Production.

The definition-oriented validation process includes the following steps:

  1. When you define Programs for use in a Report Set, set the Force Output Validation Status to 'Development' flag to No; see "Creating a Program" for further information.

    Note:

    The Force Output Validation Status to 'Development' flag is a property of the Program definition, not the instance.
  2. Define and test the Report Set structure and Program instances inside the Report Set over time.

  3. Promote each Program instance and the Report Set Entries to which it is assigned to Quality Control, according to your company's policies.

  4. Promote each Program instance and the Report Set Entries to which it is assigned to Production, according to your company's policies.

  5. Run the Report Set, or parts of the Report Set, on the appropriate data snapshot(s). The resulting output inherits its validation status from the Execution Setup that generated it, which in turn inherits its validation status from the Report Set instance. If the Report Set instance is set to Production, the output is also set to Production.

    Note:

    The Report Set output inherits the validation status of the Program output with the lowest validation status.

    The Report Set definition and instance, and each volume defined in a Report Set, automatically receive the validation status of the lowest Report Set Entry they contain.

You can manually reset the validation status of an output at any time, subject to your company's policies.

Changing Validation Status

This section contains the following topics:

Changing the Validation Status of an Output

When you upgrade the validation status of an output, you must validate the status off all contributing outputs produced during the same job.

To change the Validation Status of a Report Set output, do the following:

  1. Navigate to the Report Set output in either the Reports or My Home page:

    • In the Reports tab, navigate the hierarchy that contains the Report Set, then click the icon in the Action column for the output.

    • In the Job Executions section of the My Home page, click the Job ID, then on the Output Name.

  2. From the Actions drop-down, select Validation Supporting Info and click Go.

  3. Select the Validation Status you want from the drop-down list and click Update. If any of the contributing Program outputs produced during the same Report Set execution have a validation status lower than the new validation status you are applying, the system displays a message giving the number of such outputs and asks if you want to continue.

    If you choose to continue, all contributing outputs are promoted.

    If you choose not to continue, none of the contributing outputs is promoted.

Changing the Validation Status of a Report Set Entry

To change the Validation Status of a Report Set Entry, do the following:

  1. Navigate to the main page for the Report Set Entry. For example, from the Report Set structure screen, navigate in the Report Set hierarchy to the Report Set Entry and click its name.

  2. From the Actions drop-down, select Validation Supporting Info and click Go.

  3. Select the Validation Status you want from the drop-down list and click Update.

Changing the Validation Status of a Program Instance in a Report Set

To change the Validation Status of a Program instance in a Report Set, do the following:

  1. Navigate to the main page for the Program instance. For example, from the Report Set structure screen, navigate in the Report Set hierarchy to a Report Set Entry to which the Program instance is assigned, then click the Program name in the Assigned Program Instance column.

  2. From the Actions drop-down, select Validation Supporting Info and click Go.

  3. Select the Validation Status you want from the drop-down list and click Update.

About Report Set Planned Outputs

Individual reports in a Report Set are the Planned Outputs of the Program instances associated with the Report Set.

In addition, the system automatically creates two Planned Outputs for the Report Set as a whole:

  • The Report Set log file.

  • The Report Set itself; all reports on data. By default, the system creates one Planned Output and gives it the same name (not the title) as the Report Set.

    You can define volume breaks and volume names in Report Set Entries. The system produces each volume as a separate file. Volumes are not displayed in the Planned Outputs subtab. See "Setting Report Set Entry Properties" for further information.

    You can override Volume Break settings in Report Set Entries by defining a value for the Single Volume Output Name Post-Processing Parameter at the Report Set level.

  • The table of contents is generated as a separate file if the TOC Parameter is set to Yes and the Report Set contains multiple volumes.

Modifying Report Sets

This section contains the following topics:

If you have the necessary privileges, you can modify a Report Set either through an instance of it in a Work Area or directly in the definition in its Domain or Application Area. In most cases it makes sense to work through an instance in a Work Area for the following reasons:

  • In order to use or test changes to the definition you must create and install an instance of it.

  • If you work through an instance, the system automatically repoints the instance to the new version of the definition.

However, if you need to change properties of the definition, you must work directly in the definition in its Domain or Work Area.

Whether you work in an instance or directly in the definition, when you check in the new version of the definition you have the opportunity to upgrade instances of the original definition to the new version; see "Upgrading Object Instances to a New Definition Version".

Modifying Report Set Instance Properties

On the Report Set instance's Properties screen, click Update to enter changes. Oracle LSH creates a new version of the instance you are working on and applies your changes to it when you click Apply. Click Cancel to discard your changes and the new version.

You can modify some properties through the Actions drop-down list; see "Using the Actions Drop-Down List" for further information.

Note:

You must reinstall the Report Set for the changes to take effect.

You can modify the following:

Name See "Naming Objects" for further information.

Description See "Creating and Using Object Descriptions" for further information.

Definition Source This field applies to the instance only. It specifies the Report Set definition to which this Report Set instance points. It generally does not make sense to change the source definition for the following reasons:

  • Changing the definition may result in a new set of Table Descriptors, Source Code, Parameters, and Planned Outputs.

  • Any new Table Descriptors are not mapped.

  • The Report Set's status changes to Non Installable.

If you want to change to a new version of the same definition, use the Upgrade Instance option from the Actions drop-down list.

Modifying Report Set Definition Properties

You can go to a Report Set definition's Properties screen in one of the following ways:

  • From the Report Set's Properties screen: Click the hyperlink of the Report Set definition that appears in the Definition field. See "Definition".

  • From the Domain or Application Area where you created the definition: Click Manage Definitions to view all the definitions in that Domain or Application Area. Click the definition name.

Once on the Report Set definition screen, click Update to enter changes. Oracle LSH creates a new version of the definition. You can change the following properties:

Name See "Naming Objects" for further information.

Description See "Creating and Using Object Descriptions" for further information.

You can modify some properties through the Actions drop-down list; see "Using the Actions Drop-Down List" for further information.

Modifying the Report Set Structure

You can modify the Report Set's structure in two places:

  • Report Set Structure view. You can add, remove, copy, and move Report Set Entries here; see "Using the Report Set Structure View".

  • Report Set or Report Set Entry Properties screen. You can also add, remove, copy, and move Report Set Entries in Entries subtab of the Properties screen of the parent Report Set or Report Set Entry; see "Defining Report Set Entries".

Modifying Report Set Entries

To modify many aspects of a Report Set Entry definition, you must go to its Properties screen. You can go to the Properties screen by clicking its hyperlink in the Report Set Structure view or in its parent Report Set or Report Set Entry's Properties screen, then do the following:

In addition, you can use the Report Set Structure view to change a Report Set Entry's Program or Planned Output assignment or reorder its child Report Set Entries; see "Using the Report Set Structure View".

Modifying Programs

The Program instances contained in a Report Set belong to the Report Set definition. Their mappings belong to the Report Set instance. You modify Programs in a Report Set the same way you modify Programs outside a Report Set; see Chapter 5, "Defining Programs". You can reach the Program instance screen in a Report Set by clicking its hyperlink in any of several places:

  • Click its hyperlink in the Report Set Structure view next to one of the Report Set Entries to which it is assigned.

  • Click its hyperlink in the Report Set Program view.

  • Click it hyperlink in the Properties screen of one of the Report Set Entries to which it is assigned.

You can map the Table Descriptors of a Program in a Report Set in several different ways; see "Mapping".