PREP_PROCESS_REPORT

Use the PREP_PROCESS_REPORT script function to retrieve the report lines of executable objects from the database. The script function lets you filter by type and content of the reports. The script function returns a reference to a data sequence that you can use for further processing by assigning the return code to the :PROCESS script statement. Use the GET_PROCESS_LINE script function to access a particular line in the report.

Tip: Analyze the job report of the task itself in the Post Process page. For more information, see Process Pages. Depending on the result, use :MODIFY_STATE to specify the definitive end of the job.

More Information:

• Reports
• :PROCESS... :TERM_PROCESS... :ENDPROCESS
• GET_PROCESS_LINE

Notes:

• The report is saved in the same language as the Automation Engine logging.
• You cannot assign a new value to the script variable that contains the reference to the data sequence. Use :CLOSE_PROCESS to discard the existing data sequence, and then assign a new value.
• The script function causes all open transactions of the script to be written to the AE database. For more information, see Script Processing.
• No error message is displayed if the data sequence does not contain the indicated content. In this case, the data sequence that is defined between :PROCESS and :ENDPROCESS is not processed.

Syntax

PREP_PROCESS_REPORT ([Object type] ,[RunID] ,[Report type] [,Filter] [,"COL=Definition1] [,Definition2]")

Parameters

• PREP_PROCESS_REPORT
  Retrieves reports of an executable object

• Object type
  (Optional) Short name of the object type
  Format:AE name, script literal or script variable
  More information: Object Types
  Notes:

  • This parameter is optional as the object can be assigned through the RunID
  • Specify CLNT to access Client reports.

• RunID
  (Optional) RunID of the task whose reports to retrieve
  Format: script variable or number
  Note: You do not need to specify a RunID for Client reports.
  Important! If you are retrieving the report of a predecessor of a Workflow task, activate the Generate Task at: Runtime option in the Attributes tab of the Workflow object. The report is not available yet during activation time. For more information, see Generating at Activation or at Runtime.

• Report type
  (Optional) Short name of the report type
  Format: AE name, script literal or script variable
  More information: Reports
  Note: If you do not specify a report type, the script function accesses the job report (REP) for Job objects, and the activation report (ACT) for other types of tasks.

• Filter
  (Optional) Filters for particular content of a line
  Format: script literal or script variable
  Default value: *
  Notes:

  • The filter is case insensitive.
  • Use the wildcard character * to stand for any number of characters, or ? for a single character in a filter.

• COL
  (Optional) Defines whether and how to split the data sequence lines into columns
  Format: script literal or script variable
  Use the following format: COL=Definition1[, Definition2]. For more information, see Defining Columns.

Notes:

• You do not need to specify the RunID and Report Type when you use PREP_PROCESS_REPORT to access the report of the task that contains the script itself. The script function retrieves the RunID in this case.
• Set the commas of parameters that you omit.
• If a task has already ended, but the report is still incomplete, the script function waits for the report to be complete.

Defining Columns

To split the data sequence lines into columns, specify the column separation as follows:

COL=Definition1[, Definition2]

Where

• COL
  
  Keyword for column separation

• Definition1
  
  Defines whether the data sequence lines are split into columns
  
  Format: script literal or script variable
  
  Allowed values:

  • NONE
    
    Lines are not split into columns (default)
  • LENGTH
    
    Sets a predefined column size
    
    Note: Use LENGTH_TAB in Definition2 to specify the size.
  • DELIMITER
    
    Separates columns with a delimiter
    
    Note: Use DELIMITER in Definition2 to specify the delimiter.

• Definition2
  
  (Optional) Defines column sizes and names, or the delimiter
  
  Format: script literal or script variable
  
  Allowed values:

  • LENGTH_TAB
    
    Specifies column sizes and column names
    
    Example:"COL=LENGTH,LENGTH_TAB='3=drive,100=file name'"
    
    Notes:
    • Separate individual column definitions with commas.
    • Specify up to 22 columns with a total of 2048 bytes.
    • Specify the column size as the number of characters. The maximum size is 255 characters.
    • (Optional) specify column names. Names can be up to 32 characters long.
    • Use quotation marks before the first and after the last column definition. Use double quotation marks if you use single quotation marks for script literals in Definition2, or vice versa.
  • DELIMITER
    
    Defines a delimiter that separates columns
    
    The lines of the data sequence are returned as columns that are placed before, between or after the delimiter string.
    
    Example:
    
    "COL=DELIMITER,DELIMITER=*'*"
    
    'COL=DELIMITER,DELIMITER=@"@'
    
    Default value: ;
    
    Notes:
    • You can use any characters as the delimiter.
    • You can also use the tabulator as a delimiter: 'DELIMITER=<TAB>'
    • The delimiter can be a string of up to 10 characters.
    • Enclose the delimiter with any character: *Delimiter*. The enclosing characters are not displayed in the output.
    • A column is not separated if a line does not include a delimiter.
    • If you use single quotation marks as delimiters, then you must enclose Definition2 in double quotation marks, or vice versa.

Examples

The following example searches for all lines of a job report that refer to drive C:. The script prints those lines in the activation report.

:SET &HND# = PREP_PROCESS_REPORT("JOBS",, "REP", "*C:\*")
:PROCESS &HND#
:   SET &RET# = GET_PROCESS_LINE(&HND#)
:   PRINT &RET#
:ENDPROCESS

A Job called MM.DAY prompts the user for file names. The file names are printed in the activation report of the Job. The following script in a different task reads the file names from the activation report of the Job, and prints them in the activation report of the task that contains the script.

:SET &RUNNR# = GET_UC_OBJECT_NR("MM.DAY")

:SET &HND# = PREP_PROCESS_REPORT(, &RUNNR#, "ACT",,"COL=DELIMITER", "DELIMITER=*'*")
:PROCESS &HND#
:   SET  &RET# = GET_PROCESS_LINE(&HND#,1)
:   PRINT &RET#
:ENDPROCESS

The following script on the Post Process page of a Job retrieves lines which contain "file not found" in the job report of the Job itself. The script sends a message to the user logged in to the Automic Web Interface to inform them that an error occurred while copying.

:SET &HND# = PREP_PROCESS_REPORT(,,,"*file not found*")
:PROCESS &HND#
:   SEND_MSG BU,BU,"Error occurred while copying."
:   MODIFY_STATE RETCODE=50
:ENDPROCESS

See also: