Automation Engine Script Guide > Ordered by Function > Data Sequences > PREP_PROCESS_COMMENTS

PREP_PROCESS_COMMENTS

Script function: Uses filter settings to retrieve the time stamp, user and text of task comments, and provides the result for further processing in the form of an internal list (data sequence).

Syntax

PREP_PROCESS_COMMENTS([RunID], [Text], [User])

Syntax	Description/Format
RunID	Run number (RunID) of the task whose comments should be read. Format: script literal, script variable or number If no RunID has been specified, the comments of the task which calls this script statement are read.
Text	Filter for a particular text used in the comment Format: script literal or script variable Maximal 200 characters Default value: "" The wildcard characters "" and "?" can be used. "*" stands for any characters, "?" for exactly one character.
User	Filter for the name of a User object Format: script literal or script variable Maximal 200 characters Default value: "" The wildcard characters "" and "?" can be used. "*" stands for any characters, "?" for exactly one character. The first colon is also required if you only filter by the user. See the following example: :SET &HND# = PREP_PROCESS_COMMENTS(,,"SMITH/AE")

Syntax

Description/Format

RunID

Run number (RunID) of the task whose comments should be read.
Format: script literal, script variable or number

If no RunID has been specified, the comments of the task which calls this script statement are read.

Text

Filter for a particular text used in the comment
Format: script literal or script variable
Maximal 200 characters
Default value: "*"

The wildcard characters "*" and "?" can be used. "*" stands for any characters, "?" for exactly one character.

User

Filter for the name of a User object
Format: script literal or script variable
Maximal 200 characters
Default value: "*"

The wildcard characters "*" and "?" can be used. "*" stands for any characters, "?" for exactly one character.

The first colon is also required if you only filter by the user. See the following example:

:SET &HND# = PREP_PROCESS_COMMENTS(,,"SMITH/AE")

Return code
Reference to the data sequence of comments

Comments

This script function reads a task's comments. The result may be limited using the parameters Text and User.

Upper and lower case are considered in the filter specifications.

Keep in mind that an empty string ("") used as a filter specification has the same effect as "*" - all values are returned.

The return code of this script function is the reference to a data sequence which is assigned to the script statements :PROCESS and :ENDPROCESS as a start parameter. Each of a task's comments may now be accessed using the script function GET_PROCESS_LINE.

No error message is sent if the values that are searched for are not included in the comment. The processing of the data sequence that is defined between :PROCESS and :ENDPROCESS simply does not take place.

No new value can be assigned to the script variable containing the data sequence reference. The data sequence must first be discarded with the script statement CLOSE_PROCESS and then the variable can be re-used.

Examples

The following comments have already been started:

The first example retrieves all comments and :PRINT supplies the user and the text.

:SET &HND# = PREP_PROCESS_COMMENTS()

:PROCESS &HND#
:   SET &USER# = GET_PROCESS_LINE(&HND#,2)
:   SET &TEXT# = GET_PROCESS_LINE(&HND#,3)
:   PRINT "&USER#: &TEXT#"
:ENDPROCESS

:CLOSE_PROCESS &HND#

The second example only reads the entries of Mr. Smith and prints them including the time stamp.

:SET &HND# = PREP_PROCESS_COMMENTS(,,"SMITH/AE")

:PROCESS &HND#
:   SET  &TIME# = GET_PROCESS_LINE(&HND#,1)
:   SET &TEXT# = GET_PROCESS_LINE(&HND#,3)
:   PRINT "&TIME#: &TEXT#"
:ENDPROCESS

:CLOSE_PROCESS &HND#

In the third example, the script function is called from a different task, hence the RunID. The result supplies all texts of the comment which include the word "file".

:SET &RunID = GET_UC_OBJECT_NR(MM.RETRIEVE.FILES)

:SET &HND# = PREP_PROCESS_COMMENTS(&RunID,"*file*")

:PROCESS &HND#
: SET &TEXT# = GET_PROCESS_LINE(&HND#,3)
: PRINT "Comment: &TEXT#"
:ENDPROCESS

:CLOSE_PROCESS &HND#

Script element	Description
:ADD_COMMENT	Adds a comment to a task
:CLOSE_PROCESS	Discards an unnecessary data sequence
:PROCESS... :TERM_PROCESS... :ENDPROCESS	Loop for line-by-line processing of a data sequence - a sequential file or a command result, for example
GET_PROCESS_LINE	This is used to retrieve content from the current line of a data sequence.