Setting Dependencies on Jobs

Job Dependency Definition Dialog

The Job Dependency Definition dialog displays when you add or edit a job dependency from the Dependencies tab of the Job or Job Group Definition dialogs.

This dialog contains these elements:

• Job/Group – The job(s) or job group(s) that the current job depends on. You can search for jobs or job groups by clicking Browse , which opens the Job Search dialog. You can also view a job/group drop-down list by clicking down arrow.

  By default, a list of all the jobs and the job groups irrespective of the owner are displayed. Configure the Sysval to display the list of jobs and the job groups based on the flag set.

  Sysval	Value	Description
  187	N	Only the jobs and the job groups that you or your workgroup(s) own are displayed.
  		All the jobs and the job groups irrespective of the owner are displayed.

  If you narrowed your search for jobs using the Job Search dialog, the list displays the subset of jobs found.

  If you choose more than one job or job group, dependencies will be created for each one selected, and when you click OK, they appear on the Dependencies tab. You can then update dependency criteria for an individual job by double-clicking them from the Dependencies tab.

  Note: You cannot directly type a job or job group name in this field.

• Operator – Defines whether the dependency should be satisfied when the preceding job equals or does not equal the specified status.

• Status – The status of the job dependency. Choose Launched, Active, Completed Normally, Completed Normally (Output Pending), Completed Abnormally, Completed Abnormally (Output Pending), Error Occurred, Externally Defined, or Externally Defined (Output Pending) as the condition for which the job dependency is satisfied.

  If you want to compare a range of job statuses, select one of these job states:

  • Exists – Indicates that the job exists in the schedule for that day with any status.

  • Waiting – Includes any status that indicates that the job is waiting and not yet in the Running state. Waiting statuses are: Waiting on Group, Waiting on Operator, Waiting on Dependencies, Terminate Waiting, Waiting on Resource, Terminate Ready, Held, Deferred, Cancel Pending, Agent Unavailable, Agent Disabled, and Agent Outage.

  • Running – Includes any status that indicates that the job has launched and not yet in the Done state. Running statuses are: Active, Launched, Suspended, Waiting on Children, Active Waiting On Children, Orphaned, Completed Normally (Pending Output), Completed Abnormally (Pending Output), and Externally Defined (Pending Output).

  • Completed – Includes any status that indicates that the job has completed running. Completed statuses are: Completed Normally, Completed Abnormally, Externally Defined, and Cancelled Normally.

  • Done – Includes any status that indicates that the job has completed running or was not able to run. Done statuses are: Completed Normally, Completed Abnormally, Unrecoverable, Externally Defined, Cancelled Normally, Error Occurred, Timed Out, Cancelled, Timed Out For Day, Skipped, and Aborted.

  • Exit code – When selected, the job status condition and the specified exit code criteria must be satisfied for the job dependency to be met.

  • Last Run – When the Last Run option is checked, the job dependency is satisfied by looking up the predecessor’s Last Run Status.

    These fields are disabled when this option is selected:

    Occurrence

    Offset

    Relative to group (otherwise, for day)

    Relative to specified group in job activity (otherwise, for day)

    Date Offset

When saving changes with the Last Run option checked, make sure that these conditions are met so that the job’s last run completes within the same production day. Otherwise, a warning message is displayed.

A calender is defined in the Schedule tab of the Job Definition dialog.

Carryover is disabled. To complete this action, check the Disable carryover option in the Options tab of the Job Definition dialog.

• Occurrence – Used if the job dependency is a job that repeats within a production day.

  • Select First Occurrence when the first instance of the job should be used to satisfy the dependency.

  • Select Last Occurrence when the last instance of the job should be used to satisfy the dependency. If the job does not repeat, the last instance of the job dependency is used. If the dependent job has more repeating instances, the last instance of the job dependency is used to satisfy the dependency for the other instances of the dependent job.

  • Select Match Occurrence when jobs (predecessor and successor) repeat within a day, and the instance of the job dependency should match the instance of the job that depends on it.

  • Select All Occurrences when all existing instances of the job for the production day are used to satisfy the dependency. For example, if Job B depends on Job A, and Job A has 5 instances, each instance of Job B depends on all 5 instances of Job A. If one instance of Job A is removed from the schedule, then each instance of Job B depends only on the 4 of the remaining instances of Job A. If there are no instances of Job A, then each instance of Job B would not depend on any instance of Job A.

  • Select All Prior Occurrences when all instances of the job excluding current instance are used to satisfy the dependency. For example, instance #5 of Job B would depend on instances 1-4 of Job A, instance #4 of Job B would depend on instances 1-3 of Job A, and so on. Instance #1 of Job B would not depend on any instance of Job A.

  • Select All Prior and Match Occurrences when all instances of the job including current instance are used to satisfy the dependency. For example, instance #5 of Job B would depend on instances 1-5 of Job A, instance # 4 of Job B would depend on instances 1-4 of Job A, and so on. Instance #1 of Job B would depend on instance #1 of Job A.

• Offset – The number of instances to offset from either the first or the last instance. When set from the First Occurrence setting, the dependency is met using the offset+1 job instance. For example, if the offset is set to 1, the dependency is met using the second instance.

  When set from the Last Occurrence setting, the dependency is met using the Last Occurrence – offset job instance. For example, if a job is repeated 10 times, and the offset is 1, then the dependency is met using the ninth instance.

  Note: The Offset option does not apply to Match Occurrence.

• Relative to group (otherwise, for day) – Indicates whether this dependency refers to a group instance or a day instance. Use this option to establish job dependencies within separate instances of a repeating group. Job dependency is then defined by a group instance number. If this option is not selected, job dependency is defined by the day instance, using the total number of jobs that run that day.

  Note: With repeating groups, this option should be selected most of the time.

• Relative to Root Group in Job Activity – Defines dependency between two jobs that do not share the same direct parent group but fall anywhere under the same hierarchy. In this option, job instance matching is performed relative to the root group, rather than globally for the day.

  Example: Job_1 within Parent Level Group would depend on Job_2 within Parent Level Group when Relative to Root Group checkbox is selected. If this checkbox is not selected, Job_1 will look for the matching global instance of Job_2 anywhere within the today’s schedule (the existing behavior).

  The Relative to Root Group checkbox is not selected by default for new job dependencies if the sysval is set to Y. You can change the default to be checked for new job dependencies by defining these sysval and setting it to R:

  SQL(MSSQL): insert into sysval (sysval_id, sysval_string, sysval_lstchgtm) values (176, 'R', GETDATE())

  SQL(ORACLE): insert into sysval (sysval_id, sysval_string, sysval_lstchgtm) values (176, 'R', SYSDATE)

• Relative to specified group in job activity (otherwise, for day) – Defines dependency between two jobs with dissimilar direct parent groups that share a common ancestor group under the same root hierarchy. In this case, job instance matching is performed relative to the common ancestor group, rather than globally for the day.

  When the Relative to specified group in job activity (otherwise, for day) checkbox is selected, a Group dropdown field is displayed. From the down arrow, you can select the common ancestor from the ancestors of the job the current job depends on. You can also click Browse to select any group to be the common ancestor that this dependency will be relative to in job activity.

  Note: When the Relative to specified group in job activity (otherwise, for day) checkbox is selected, Job B within Group B is dependent on Job A within Group A with Group A and Group B sharing the same ancestor group Common Ancestor. When this checkbox is not selected, Job B will look for a matching global instance of Job A anywhere within the current day schedule.

  When this option is selected:

  • the Relative to group (otherwise, for day) and the Relative to Root Group in Job Activity checkboxes are cleared, if selected earlier.

  • the Date Offset option is disabled as the job dependencies within the common ancestor group are met on the same production day.

• Date Offset – Used to find the job dependency, this is the number of previous days to apply to an offset.

  Note: Enter only a positive value in the Date Offset field.

  Note: Existing jobs with negative values remain unchanged. Update these jobs manually if needed.

  Example: If Job A runs daily, and you want the job to depend on the instance finishing three days ago, specify 3. This value should not exceed the retention history for the job. If it does, the job dependency is never met.

• Ignore dependency if job not in schedule – Select this option if the job dependency should be ignored when the predecessor job configured in the job dependency is not found in the schedule.

• Do not re-evaluate once job is waiting on resource – Job dependencies that do not require re-evaluation when the job is in the Waiting On Resource status. If you do not select this option, TA re-evaluates job dependencies when the job is in the Waiting On Resource status. When unmet job dependencies are detected during re-evaluation, the job status changes to Waiting On Dependencies.

File Dependency Definition Dialog

The File Dependency Definition dialog displays when adding or editing a file dependency from the Dependencies tab of the Job or Job Group Definition dialogs.

This dialog contains these elements:

• File Name – The file that the underlying job depends on. The filename should be an UNC (Universal Naming Convention) pathname from the agent running the job. (Do not use a mapped drive in the file name.) For more information on file dependencies, see Wildcards in File Dependencies.

• Agent Name – The agent on which the file is located. The agent doesn’t have to be the same agent on which the job runs.

  If the job being defined uses an agent list, then the Inherit Agent from Job option is automatically selected and the agent list name displays in the Agent Name field.

• Inherit Agent from Job – Choose this option if you want the dependent file to use the same agent as the job or job group you are adding or editing. The default for this option is unchecked.

  If the job uses an agent list instead of a specified agent, the dependent file uses the first agent in the agent list unless the agent list is the broadcast type. (The order of the agents on the selected list is determined by the sequence they were added to the agent list.) If the agent list is a broadcast type, then the dependent file uses the same agent the job runs on.

• Exists – The file dependency is satisfied when the file exists at the specified path on the specified agent.

• Does Not Exist – The file dependency is satisfied when the file does not exist at the specified path on the specified agent.

• Has Changed In DD:HH:MM – The file dependency is satisfied when the file has changed within the specified time in days, hours, and minutes prior to when the job entered the production schedule. For example, if the job entered the schedule at 1:00 PM, the period specified is 6 hours, and the file changed after 7:00 AM (or later), the dependency is met.

• Stable For DD:HH:MM – The file dependency is satisfied when the file contents have not changed for the specified time in days, hours and minutes from the present time. For example, if the file’s modified time is 1:00 PM, the period specified is six hours and the job enters the schedule at 3:00 PM, the dependency is satisfied in four hours, i.e., 7:00 PM.

• Size >= – The file dependency is satisfied when the file size increases to or exceeds the value specified in bytes. The maximum file size is 4,294,967,296 bytes.

• Size <= – The file dependency is satisfied when the file size decreases to or drops below the value specified in bytes.

Wildcards in File Dependencies

The question mark (?) and the asterisk (*) are supported as wildcards in the filenames of file dependencies.

Wildcard Usage Summary

• The question mark (?) wildcard represents any single character in a string

• The asterisk (*) wildcard represents any character or group of characters in that position in the string

You may combine the wildcards (for example, T?dal.*). UNC paths must be used if the user account under which the agent runs has the required access to the network share. Wildcards are accepted in filenames only, not elsewhere in the path specification

Note: If the Has Not Changed For or Stable For option is selected with a wildcard file dependency, a large match set may result, delaying the check for file dependencies for other jobs.

FAQs on Wildcard Functionality

What are the benefits of using wildcards in file dependencies?

There are programs, applications, scripts and batch files that need to depend on the existence of a file. In some situations, the exact name of the file that the program depends is unknown. The filename may include a date or time stamp, or a sequence number may be appended to the filename at the time of creation of the file. For example, an order file might be named ORD<sequence_number>.RDY.

The wildcard enhancement makes it quick, easy and efficient to set up and manage file dependencies where the filename is not constant.

How are the wildcards structured?

Usage of wildcards in TA is consistent with the standard wildcard practice. A combination of the question mark (?) and asterisk (*) can be used. For example, a file dependency can be set on any files meeting these wildcard criteria, L??d?n*.dat. The file, London101.dat, would make this dependency true.

Can you use wildcards in the path as well as in the filename?

No. The path to the file must be known. The wildcard functionality does not support wildcards in the path to a file. You should enter file dependencies in UNC format:

\\servername\directoryname\filename

Example: \\bpssch2\bpapps\files\ord????.dat

as well as in the format of a mapped drive if on the same machine:

driveletter:\directoryname\filename

Example: c:\files\ord*.dat

This gives you the flexibility to detect the existence of files on any shared server in the domain.

What is the logic applied in fulfillment of wildcard file dependencies?

Once a file arrives whose name qualifies based on the wildcards, the dependency is marked true and the job with the dependency is released. Wildcards are cleanly implemented with the Exists and Does Not Exist options as well as TA ’s advanced file dependency features.

What if more than one file fulfills the dependency?

Multiple files may qualify for a wildcard file dependency. For example, the query ORD*.RDY may result in three files: ORD100.RDY, ORD105.RDY and ORD200.RDY. A dependency could be set on files that have changed in the last 30 minutes. ORD105.RDY might have changed in the last 30 minutes while the other two files did not. In this type of situation, if one file meets the condition, then the dependency has been met.

What happens when dependencies cross day boundaries?

A job can be scheduled to run daily depending on a file. You can use a wildcard in the file dependency to look for the file. For example, the job may need ORD9T.RDY on Tuesday and ORD10W.RDY on Wednesday. You can define this job to have a dependency on file ORD*.RDY. ORD*.RDY matches ORD9T.RDY and ORD10W.RDY.

What if ORD9T.RDY arrives late, after the end of the day?

If Tuesday's job is set to carry over to the next day, Tuesday’s and Wednesday's jobs will be looking for the existence of a file that matches ORD*.RDY. If ORD019.RDY arrives before ORD024.RDY, both jobs will launch on its arrival. To avoid this, you can set the job to reschedule itself when another file is found.

Can you have a dependency on a file that exists on a non-agent machine?

Yes. You are not limited to files on servers with active TA agents. If the agent machine can see and connect to another machine (the machine has a share), it can determine if a file exists on it.

Can we use the wildcard characters as literal characters?

No. TA will interpret the? and * characters as wildcards.

Are wildcard file dependencies supported on all platforms?

No, currently this enhancement applies to Microsoft Windows and Unix systems only.

Are the wildcards supported from the TA command line and API?

Yes. The wildcard functionality is the same for the TA Clients, command line and the TA API. The? and * characters can be typed at the command line or API and will be treated as wildcards.

Variable Dependency Definition Dialog

The Variable Dependency Definition dialog displays when adding or editing a variable dependency from the Dependencies tab of the Job or Job Group Definition dialogs.

This dialog contains these elements:

• Master – The Master that manages the variable dependency being created. If creating an interMaster dependency, select the appropriate remote Master from the drop-down list; otherwise, leave the default.

• Variable Name – The variable that the current job depends on. You select the variable from a list of user-defined variables that you or your workgroup own. If the Master is a remote Master, these variables are a list of published variables cached within the local Master.

• Operator – The relative operator used to determine whether the variable’s value satisfies the dependency.

Equals (=)

Does not equal (<>)

Less than (<)

Less than or equal to (<=)

Greater than (>)

Greater than or equal to (>=)

When text strings are used in comparison, higher letters of the alphabet are greater than lower letters. For example, A < Z. If the first letters of the string match, succeeding letters are used for comparison. For example, AA < AZ. The operation works similar to sorting strings.

• Variable Value – The value of the variable that satisfies the dependency. Using the drop-down menu, you can also select from a list of System and User-defined variables that should be used for comparison.

z/OS JES Job Dependency Definition Dialog

The z/OS JES Dependency Definition dialog displays when adding or editing a z/OS JES dependency from the Dependencies tab of a job’s definition.

This dialog contains these elements:

• z/OS Gateway Adapter – Choose the appropriate Gateway adapter that is connected to the z/OS mainframe machine that is running the z/OS job you are interested in. Each z/OS machine requires its own Gateway adapter so you must select the machine you are interested in.

• JES Job Name – The name of the job running on the selected z/OS machine that you wish to use as a dependency.

Job Occurrence Section

Since the TA job you select could run multiple times during the day, you must specify which job occurrence you are interested in.

• First – Choose this option if the first instance of the job in the production day should be used to satisfy the job dependency.

• Latest – Choose this option if the most recent occurrence of the job should be used to satisfy the job dependency.

• Match – Choose this option if jobs (predecessor and successor) repeat within a day, and the instance of the job dependency should match the instance of the job depending on it. If the job does not repeat, the first instance of the job dependency is used.

• Specific – Choose this option to use a specific job instance. Type a number or use the arrow buttons to denote which instance of the repeating job instances should be used.

• Offset – Choose this option to specify the number of job instances to offset from the instance of the dependent job. Type a number or use the arrow buttons to enter how many job instances to offset. A positive number adds the specified number from the dependent jobs’ instance number. A negative number subtracts the specified number of job occurrences from the dependent jobs’ instance number.

• Ignore if questionable – Any instance number of a job that the Gateway did not track from the start of the production day is considered questionable because the Gateway cannot verify that the job did not run before the Gateway started tracking it. This might occur if the Gateway is not running at some point during the production day or if the job is not registered with the Gateway at the start of the production day.

  Choose this option if the dependency is critical to a specific instance of the job and there is any uncertainty about the exact instance number. The dependency cannot be met during the day if the z/OS job instance number is questionable.

Dependency Condition Section

In the Dependency Condition field, you specify the condition of the TA job or one of the job steps that comprise the job that will signal that the dependency is satisfied. The condition is based on the state or status of the TA job or job step. A variety of conditions can denote a satisfied dependency.

• Job (or Step) Completed – The dependency is satisfied when the job completes or a specified job step has completed with the a condition code within the range of condition codes specified in the Condition Code Range field.

• Highest Condition Code – The dependency is satisfied only when the job completes with the highest code within the range of condition codes specified in the Condition Code Range field.

• Any Step Condition Code – This dependency is satisfied whenever any job step within the z/OS job completes with a condition code within the specified range in the Condition Code Range field.

• Job Started – The dependency is satisfied if the job or job step starts.

• Job (or Step) Abended – The dependency is satisfied if the job or job step results in a system or user abend.

• Job Flushed (JCL/Alloc Errors) – The dependency is satisfied whenever the job fails to start.

• Job (or Step) Canceled (by SMF Exit) – The dependency is satisfied whenever a job or job step is cancelled.

• Job Abended due to Condition Code – The dependency is satisfied whenever the job completes with an abend condition based on condition code handling.

• Optional (PROC.) Step – This field is optional, but if you wish to specify a particular step within the job, type the name of the job step. The dependency that was specified in the Dependency Condition field will apply only to the job step you specify here. The condition of any other job steps or the overall job is irrelevant once this field is used. (You can include a PROC prefix, if necessary.)

• Condition Code Range – Use this section to set the condition code that signals that the dependency is true. You can use a specific number or type a range of numbers so that anything within the given range means that the dependency is satisfied. The condition code can range from 0 to 4095. This field only applies if you selected these dependency condition options:

Job (or step completed)

Highest Condition Code

Any Step Condition Code

Job Abended due to Condition Code

• Include Abend – Selecting this option, adds the Abend status to the specified condition code options. If a job or job step either completes inside the specified range of condition codes or completes with an Abend status then the job dependency is satisfied.