startcond

Use this keyword to build into the job stream a mechanism which checks for specific events and conditions and releases the job stream when the specified events or conditions take place.

You can check for one of the following event types:
filecreated
You can check whether one or more files have been created on the specified workstation.
filemodified
You can check for modifications in one or more files present on the specified workstation.
job
You can define a job definition whose output condition is to be monitored.
For conditions based on files being created or modified, when you save the job stream, a monitoring job is automatically created to monitor the specified condition. This job becomes the first job in the job stream and remains in EXEC status until the condition it is monitoring is met or the job's deadline expires.
Note: If you do not specify a deadline, by default the value is defined using the startConditionDeadlineOffset optman option.
This job type is identified by the +AUTOGEN+ label in the command line and by an icon with the A character in the Dynamic Workload Console.
For conditions based on the result of a specified job, when you save the job stream, the job becomes the first job in the job stream and restarts until the condition is satisfied, or the job's deadline expires.
Note: If you do not specify a deadline, by default the value is defined using the startConditionDeadlineOffset optman option.
This applies also if the job completes in Success status. This is the monitoring job. When you specify this condition type, HCL Workload Automation automatically defines a success output condition on the monitoring job. As a result, the monitoring job completes successfully when any of its output conditions is satisfied, including the condition on the monitoring job itself. You can apply this logic to the job stream or to specific jobs in the job stream. For more information about output conditions, see Applying conditional branching logic.

If you do not specify a name for the monitoring job, by default the file_StartCond name is used. This value is defined using the fileStartConditionJobName optman option. For more information about the fileStartConditionJobName option, see Global options - detailed description.

By default, HCL Workload Automation keeps monitoring the condition also after it is first met. This is accomplished by automatically creating a new Job Stream Submission job and adding it to the job stream as a successor of the monitoring job. This job type is identified by the +AUTOGEN+ label in the command line and by an icon with the A character in the Dynamic Workload Console. To have HCL Workload Automation stop when the condition is first met, select the Start once check box in the Workload Designer, or omit the rerun keyword in the composer command line.

The Job Stream Submission job is defined on a specific pool workstation named MASTERAGENTS. This pool workstation contains the dynamic agent installed on the master domain manager and on the backup domain manager, if present. The dynamic agent installed on the master domain manager and backup domain manager (if present) are automatically added at installation time to this pool workstation. If you delete the MASTERAGENTS pool workstation and then recreate it, you must stop and restart the dynamic agent to add it back to the MASTERAGENTS pool workstation. See Automatically register agents to pools for more information about the MASTERAGENTS pool workstation.
Note: The default name for the pool workstation, MASTERAGENTS, can be modified using the optman global option resubmitJobName. See Global options - detailed description for details about this option.

The Job Stream Submission job creates a new instance of the job stream in which the start condition is defined. By default, the new job stream instance starts also if the previous instance is still running and the two instances run concurrently. To change this behavior, in the Workload Designer, switch to the Scheduling options tab and select Queue the new instance in the Actions section. From the composer command line, use the onoverlap keyword. For more information, see onoverlap. The newly-generated instance is identical to the previous one it and is set to repeat the condition check, therefore a series of new instances is created until the job stream's deadline expires.

The name of the Job Stream Submission job is defined using the value set for the resubmitJobname optman option. By default, the value assigned to this option is restart_StartCond. For more information about the resubmitJobname option, see Global options - detailed description.

Syntax

startcond filecreated | filemodified | job
startcond filecreated [folder/]workstation_name#file_name user username interval seconds [alias startcond_jobname rerun batch outfile outputfilename params "filemonitor additional parameters"]
startcond filemodified [folder/]workstation_name#file_name user username interval seconds [alias startcond_jobname rerun batch outfile outputfilename params "filemonitor additional parameters"]
startcond job [folder/]workstation_name#[folder/]job_name outcond joboutputcondition interval seconds [alias startcond_jobname rerun]

Arguments

filecreated [folder/]workstation_name#file_name
Check whether the specified file or files are created, where:
[folder/]workstation_name#file_name
Specifies the workstation name and the fully qualified path to file or files to be monitored.
filemodified [folder/]workstation_name#file_name
Check whether the specified file or files are modified, where:
[folder/]workstation_name#file_name
Specifies the workstation name and the fully qualified path to file or files to be monitored.
job [folder/]workstation_name#[folder/]job_name
Check whether the specified job definition has completed successfully meeting the condition specified with the outcond keyword.
user username
The login information for accessing the workstation where the file or files to be monitored are located. Applicable only to filecreated and filemodified keywords.
interval seconds
How often HCL Workload Automation checks whether the condition is met, expressed in seconds. For the job start condition only, the value will be approximated to 60 seconds, if lower than 60 seconds. If the value is higher than 60 seconds and not divisible by 60, it will be approximated to the nearest value which is also divisible by 60.
alias startcond_jobname
The name of the job which is automatically added to the plan to run the monitoring task.
For conditions of type filecreated or filemodified
If you do not specify any names, the file_StartCond name is used by default. The default name is retrieved from the fileStartConditionJobName global option. For more information, Global options - detailed description.
For conditions of type job,
If you do not specify any value, the name of the job definition is used.
rerun
Have HCL Workload Automation automatically create a Job Stream Submission job, which is added as a successor of the monitoring job. The Job Stream Submission job submits a new instance of the job stream in which the start condition is defined.
batch
When the process returns multiple files at the same time, a single job stream instance is used to process them in batch mode. If do not specify this parameter, a job stream instance is launched for each file retrieved. Applicable only to filecreated and filemodified keywords.
outfile outputfilename
The names of the retrieved file or files are returned as a variable. You can optionally specify an output file where to store the file names. Ensure that the directory where the output file is to be created is already existing. Applicable only to filecreated and filemodified keywords.
params "filemonitor additional parameters"
Optionally specify filemonitor additional parameters. Applicable only to filecreated and filemodified keywords. For more information, see Filemonitor.
outcond
The output condition which, when met, releases the remaining part of the job stream. Applicable only to the job keyword. You can specify this keyword both at the job stream and job level. When you save the job stream, the job restarts until the condition is met or the job's deadline expires.

Comments

Ensure that all the components in the HCL Workload Automation environment are at version 9.4, Fix Pack 1, or later.

The following workstation types are not supported if you specify a start condition based on files being created or modified:
  • Extended agent
  • Workload broker
  • Remote engine

Examples

The following example illustrates a job stream which starts only when the Reports.txt file is created on workstation S_MDM in the /Reports path. The FileMngr user is used to connect to the specified workstation and the check on the condition is performed every 100 seconds. The monitoring job is named ReportCheck and the retrieved information is stored in the /logs/ReportsOutput.txt file. Using the params keyword, two filemonitor parameters (-recursive -maxEventsThreshold) have been inserted to specify that the check is performed also on sub folders and all events must be returned.
SCHEDULE S_MDM#JS1
VARTABLE MAIN_TABLE
ON RUNCYCLE RC2 08/04/2017
( AT 0800 +1 DAYS )
STARTCOND FILECREATED S_MDM#/Reports/Report.txt USER FileMngr INTERVAL 100
( ALIAS ReportCheck PARAMS "-recursive -maxEventsThreshold all"
OUTFILE /logs/ReportsOutput.txt )
LIMIT 5
OPENS S_MDM#"/my file . txt" (-f %p)
:
S_MDM#NATIVE
NOP
FOLLOWS DYNAMIC

S_AGT#DYNAMIC

S_AGT#SLEEP3
FOLLOWS NATIVE
FOLLOWS S_MDM#JS1_EXT.SLEEP3

S_AGT#JOB_MGMT
FOLLOWS SLEEP3
END