Using the REPSETVAR Command and Advanced Segment OPAL Code

 

Before You Begin

You can use the Set Reports Variable Data (REPSETVAR) command with segment OPAL code to dynamically create report email subject lines, output report file names, and email addresses. To do so, you extract specific text from a report, load the text into one or more predefined variables, and combine one or more variables with static text (optional) to create the subject line of a report email, the name of the report output file, the email address, or any combination of the three.

Note: If you use Robot Alert to email your reports, you must use Robot Alert R05M48 or higher.

Creating Report Segment OPAL Code

To create dynamic subject lines, file names, or email addresses, you use segment OPAL code to locate text or data in the report, load it into one or more user-defined OPAL variables, and perform the EXECUTE operation with the REPSETVAR command. The REPSETVAR command specifies which variable names to use for dynamic replacements.

Note: If the report has segments that use bursting instructions, contact Fortra Technical Support for help converting bursting instructions to OPAL code.

Creating or Editing OPAL Code

1. Select option 1, Report Sets Menu, from the Robot Reports Main Menu.

2. Select option 2, Maintain Report Sets, to display the Maintain Report Sets panel, locate the report set.

3. Enter 3 to display the Maintain Report Names panel.

4. Enter 1 next to the report name to display the Report Name panel and press F10 to display the Maintain Report Segments panel.

Creating a New Segment

1. Press F6 to display the Report Segment panel.

2. Name the new segment and enter your specifications.

Creating or Editing OPAL Code for a Segment

1. Enter a 2 next to the segment on the Maintain Report Segments panel to display the OPAL Report Segment panel.

   

2. Using OPAL code, specify where the text or data that you want to use dynamically is located in the report. Specify the line number and column range of its exact location on the page.

   Note: Line 30 of this example verifies that the content of the variable is not all blanks.

3. After you locate the text or data, use the OPAL CHGTO operation to store the value using the following OPAL user-defined variables:

   • The variables USRFLD1-USRFLD5 can contain up to 10 characters each and cannot be all blanks.

   • The variables USRLONG1-USRLONG5 can contain up to 45 characters each and cannot be all blanks.

4. Enter the OPAL EXECUTE operation, tab to the Operation Values field, type REPSETVAR, and press F4 to display the Set REPORTS Variable Data (REPSETVAR) panel (see Specifying REPSETVAR Command Parameters).

5. When you are finished writing your OPAL code, press F3 to return to the Maintain Report Segments panel.
   
   Note: Using QUIT or QUITPAGE operations in your OPAL code can speed the processing.

Specifying REPSETVAR Command Parameters

The REPSETVAR command has six parameters, but only two—Dynamic Variable Name and Dynamic Variable Data—are user-specified (the others are filled in automatically by Robot REPORTS during report processing and cannot be changed). You use these two parameters to specify the name of the variable you created and the data it contains.

When Robot REPORTS processes your report segment, the OPAL code you created executes the REPSETVAR command. Use the Set REPORTS Variable Data (REPSETVAR) panel to specify the values for the two parameters.

Getting Started

1. On the Set REPORTS Variable Data (REPSETVAR) panel, specify the name of the variable you are creating (Dynamic Variable Name parameter) and the data it contains (Dynamic Variable Data parameter) for the REPSETVAR command.

   • The Dynamic Variable Data parameter can be a user-defined OPAL variable or an alphanumeric text string.

   • The variable name you specify for the Dynamic Variable Name parameter must start with two ampersands (&&), followed by up to eight characters. When you create variable names, make each name unique—do not use a variable name that is part of another variable name.

     For example, if you have a variable named &&MSG, do not use it with a variable named &&MSGTEXT in the same report segment. The REPSETVAR program will interpret the string &&MSGTEXT as two distinct elements—the &&MSG variable followed by the literal string TEXT—rather than as a unique variable name.

     Note: Use only user-defined OPAL variables with the REPSETVAR command—do not use predefined OPAL variables, such as JOB or DAY. You can display a list of predefined OPAL variables by pressing F4 from the Variable column on the OPAL Report Segment panel.

   • The Report Run Number, Report Set, Report Name, and Report Segment fields cannot be changed. They are resolved with the correct values when Robot REPORTS processes the report.

2. When you are finished, press Enter to save your changes and return to the OPAL Report Segment panel.

3. Press F3 to exit and respond Yes (Y) to the prompt to save your OPAL changes and compile your OPAL code.

Creating Dynamic Subject Lines

You can create a dynamic subject line using variables and text (optional) for the report segment.

Rules and Guidelines

• Robot Reports must be at R07M42 or higher.

• The subject line can contain a maximum of 256 alphanumeric characters, including the contents of the variables and any other text you add.

Getting Started

1. From the Maintain Report Segments panel, enter a 9 next to the segment to display the Email Subject panel.

   

2. Create your subject line.

   

   You can use a combination of text and your Dynamic Variable Name variables to create a dynamic subject line. If you use one or more variables, keep track of the amount of data in the variables—your subject line can contain a maximum of 256 alphanumeric characters.

3. When you are finished, press F3 to return to the Maintain Report Segments panel.

Creating Dynamic Filenames

You can create an output file name dynamically using the contents of one or more variables and text (optional).

Rules and Guidelines

• Robot Reports must be at R07M47 or higher.

• If you use Robot Alert as your distribution software, the resolved file name (the output file name that results from resolving the variables), must be 64 characters or less.

• You cannot create dynamic file names in the QDLS directory.

• You must follow the IBM naming conventions for IFS files.

Getting Started

1. From the Maintain Reports Segment panel, use option 5 to display the Maintain Report Distributions panel.

2. Enter a 1 next to the distribution to display the Report Distribution Output Options panel.

   

3. Verify that the output code is PDF (D), HTML (H), or CLIENT (C).

4. For a dynamic output file name, enter the name using one or more variables and text (optional).

   In this example, we are specifying a dynamic file name that Robot Reports will generate using the contents of the variables &&ACCOUNT and &&DATE.

5. When you press Enter, Robot Reports displays an example of the unresolved file name it will use to process the report.

Creating Dynamic Email Addresses

You can create an email address dynamically using the contents of one or more variables, with or without text.

Rules and Guidelines

• Robot Reports must be at R07M55 or higher.

• The email address that is generated by resolving the variables must be 256 characters or less.

• The Report Email Distribution on the System Defaults panel must be set to R (Recipient Email).

  

Getting Started

1. From the Maintain Reports Segment panel, use option 5 to display the Maintain Report Distributions panel.

2. Enter a 1 next to the distribution you want to edit and press Enter to display the Report Distribution Output Options panel.

3. Verify that the following settings are correct on this panel:

   • The Output Code must be either D (PDF), H (HTML), or C (CLIENT).

   • The E-Mail Upon Completion field must be D (Dynamic).

   

4. Specify one or more variables and text (optional) in the Dynamic Email Variable field. In this example, we are specifying a dynamic email address that Robot Reports will generate using the contents of the variable, &&EMAIL.

Prerequisites, Rules, and Guidelines

• The following is a summary of the prerequisites, rules, and guidelines you should be aware of to use variables to create dynamic subject lines or dynamic filenames. These items are discussed in more detail in this topic.
• You must be using segment OPAL code to process your report segments. If the report has segments using bursting instructions, call Fortra Technical Support for help converting your bursting instruction segments to OPAL code.
• To create dynamic subject lines, Robot/REPORTS must be at R07M42 or higher.

Dynamic Filenames

Dynamic Email Addresses

Variables

• A dynamic variable name must start with two ampersands (&&), followed by up to eight characters.
• Do not use a dynamic variable name that is part of another dynamic variable name. For example, if you have a dynamic variable named &&MSG, do not use it with another dynamic variable named &&MSGTEXT in the same report segment.
• The resolved value of a dynamic variable cannot be all blanks.
• Use only user-defined OPAL variables with the REPSETVAR command. Do not use predefined OPAL variables, such as JOB, DAY, TEXT, and SYSTEM.