You may have application workflows where the jobs in them cannot be allowed to run concurrently. Normally, this can be handled by creating reactive jobs in Automate Schedule. However, reactivity only works if your jobs have prerequisites that would ensure a specific order of execution. So, what should you do if the jobs in your workflow can run in any order as long as they do not run concurrently? The answer is FileLocker.

Automate Schedule provides a FileLocker utility that can be embedded into a workflow to ensure that sections of the workflow are not allowed to run at the same time. The FileLocker utility can be used to ensure that the items in your process—whether they are one or more commands in a job, entire jobs or suites, or a complex workflow consisting of multiple jobs and job suites—are mutually exclusive.


How It Works

This is what the FileLocker utility does:

  1. The FileLocker process is a java class that can be called from a command line embedded in an Automate Schedule job.
  2. When called, the FileLocker process attempts to create a specified file (the "lock" file). If the lock file already exists, the process will retry after a short wait time.
  3. The retry process will be repeated until the lock file can be created.
  4. After creating the lock file, the FileLocker process has the "lock" and completes successfully.
  5. This allows subsequent commands, jobs, and job suites in the process to continue.
  6. When the section of the process that requires mutual exclusivity completes, the process releases the lock by deleting the lock file that was created by the FileLocker process. This allows the other processes, which are waiting to create the same lock file, the opportunity to continue.

Note: Only one process can have the lock. When it's released, whichever FileLocker process that happens to be firing at that time will get the next lock.

Command Definition

To run the FileLocker java class, you will need to use a Java runtime environment. This should be available since it's installed with the Automate Schedule agent.

Use the following syntax in a command to run the FileLocker utility:

"{java executable}" -cp "{jar file}" {file locker class} {lock file name} {attempts} {retry interval}

Command information

{java executable}
The path to the java runtime executable.

{jar file}
The jar file in the Automate Schedule application which contains the Filelocker class.

{file locker class}
The FileLocker class name is always: "com.helpsystems.enterprise.core.util.FileLocker".

{lock file name}
The name of the lock file for the set of mutually exclusive processes (default="filelocker.lock"; in the current working directory).

The number of times the FileLocker should attempt to create the lock file before failing (default=0; valid values are 0 to 2147483646, with 0=unlimited).

{retry interval}
The wait interval, in seconds, between attempts to create the lock file (default=2; valid values are 1 to 3600).

Windows example

The following example invokes the FileLocker process with a lock file named "c:\myapp\temp.lock.file".

The "0" (zero) value for the "attempts" parameter indicates unlimited attempts.

The "5" value for the "retry interval" parameter indicates the FileLocker will retry every 5 seconds while the lock file exists from another of the mutually exclusive processes.

"C:\Program Files (x86)\Help Systems\Automate Schedule Agent\jvm\bin\java.exe"

""cp "C:\Program Files (x86)\Help Systems\Automate Schedule Agent\lib\schent-mp-module.jar"





Restrictions and Suggestions

Following are some restrictions that you should be aware of, along with some helpful tips:

  • The processes that are running the FileLocker utility must be on the same agent or have access to the same shared file system, because the FileLocker depends on access to the same file system to use the existence and creation of a specific file to determine which process has obtained the lock.
  • If mutually exclusive processes run on different agents, it may require the FileLocker processes to be created in separate jobs that run on the same agent and have the subsequent processes be initiated via reactivity with the FileLocker job as prerequisites.
  • Defining the elements of the FileLocker command as environment variables in a shared agent environment can be helpful to reduce subsequent maintenance.
    Showing examples of FileLocker environment variables.
  • Defining separate FileLocker Jobs that use a shared command set containing the FileLocker command can be helpful to reduce subsequent maintenance.
    Showing an example of a FileLocker command in an Automate Schedule job.

Workflow Example

In the example pictured below:

  • The FileLocker jobs (SFL_Demo_A_Locker and SFL_Demo_B_Locker) are the initial jobs in two processes that are mutually exclusive.
  • The job, SFL_Demo_A_Process, cannot run at the same time as the jobs, SFL_Demo_B1_Process, SFL_Demo_B2_Process, and SFL_Demo_B3_Process.
  • The "Locker" jobs and the "Unlocker" job all run on the same agent to access the same file system for the lock file.
  • The two separate lines pointing to the job, SFL_Demo_Unlocker, indicate an "OR" prerequisite setting that allows it to delete the lock file when either the "A" process or the "B" process completes.


Joblog Example

The text below is an excerpt from the joblog of an Automate Schedule job that ran the FileLocker command.

The string of periods (".") below the "Attempting to create file: C:\work\temp.lock.file" line indicates how many retry intervals have occurred while waiting for the file lock. Each period in the string represents a failed attempt. Therefore, this process waited approximately 94 seconds (47*2) to get the lock.

"C:\Program Files (x86)\Help Systems\Automate Schedule Agent\bin\Win32\eecho" COMPLETED_CMDID_20131121.100004.025: %Errorlevel%

Lock File Name: temp.lock.file
Attempt Interval (seconds): 2

Attempting to create file: C:\work\temp.lock.file

Locker file C:\work\temp.lock.file was created.
REMINDER: Delete the lock file when the exclusive function is complete.

C:\work>COMPLETED_CMDID_20131121.100004.025: 0

Calling the FileLocker from a Batch Script

You may find it easier to write a batch script on the Automate Schedule agents that can then be customized for your environment rather than embedding the FileLocker java details into the Automate Schedule configuration.

This can also be used to try the FileLocker function from interactive command shells to see how it works in your environment.

You can also make the lock file name a parameter to the batch file so it can be used by multiple sets of mutually exclusive processes.

For Windows .bat files:

  1. Create a batch file with a text editor and paste the code from below into the file.
  2. Verify the paths and parameters in the file and save it.
  3. Call the file from your Automate Schedule process as needed.

@ECHO off

set "SFL_CLASSPATH=C:\Program Files (x86)\Help Systems\Automate Schedule Agent\lib\schent-mp-module.jar"
set "SFL_CLASS=com.helpsystems.enterprise.core.util.FileLocker"
set "SFL_JAVA=C:\Program Files (x86)\Help Systems\Automate Schedule Agent\jvm\bin\java.exe"

set SFL_LOCKFILE=c:\work\my_process.lock




For other operating systems that use .sh files:

  1. Create a batch file with a text editor and paste the code from below into the file.
  2. Verify the paths and parameters in the file and save it.
  3. Use chmod to set the batch file as executable.
  4. Call the batch file from your Automate Schedule process as needed.







Still have questions? We can help. Submit a case to Technical Support.

Last Modified On: October 24, 2019