How to Add or Remove Job Template Level Submission or Activation Filters

  • Article

Applies To: Microsoft HPC Pack 2008 R2, Microsoft HPC Pack 2012, Microsoft HPC Pack 2012 R2, Windows HPC Server 2008 R2

This topic describes how a cluster administrator can add one or more job submission and activation filters at the job template level. This option is supported in clusters that are running at least Microsoft HPC Pack 2008 R2 with Service Pack 2. Filters that are specified at the job template level must be defined as a DLL (and will run in the same process as the HPC Job Scheduler Service), rather than as an executable or script like the cluster-wide filters (which run in a separate process).

Important

Unlike the cluster-wide filters that are reloaded each time they are called, job template level filters are kept loaded in the same process as the HPC Job Scheduler Service. This decreases the impact of custom filtering on job throughput. To minimize unintended interaction with the job scheduler and to allow the unloading of a filter, the filter DLLs are loaded in a separate application domain from the scheduler. However, uncaught exceptions or other issues in the filter DLL can cause the job scheduler to fail. Ensure that you test custom filters before adding them to your production environment.

In this topic:

  • Step 1: Copy the DLL filters to the head node

  • Step 2: Add one or more filters to a job template

  • How to remove a job template filter

  • Additional considerations

Step 1: Copy the DLL filters to the head node

DLL filters, and any dependencies that they have, must be copied to the %CCP_DATA%Filters folder on the head node.

Note

If your filters have more than one file, or if they create output files, it is good practice to create a sub-folder for each filter in the %CCP_DATA%Filters folder.

To copy a DLL filter to the head node

  1. Log on to the head node as an administrator.

  2. Open the %CCP_DATA%Filters folder (typically, this is %CCP_DATA%Filters).

  3. Create a new sub-folder for the filter.

  4. Copy the filter DLL and any supporting files into the new folder that you created.

Step 2: Add one or more filters to a job template

Job template level filters are added to the cluster by specifying the filter in one or more job templates. These filters cannot be deleted or changed until all references are removed from the job templates. For more information, see How to remove a job template filter.

To add DLL filters to a job template

  1. In HPC Cluster Manager, in Configuration, select Job Templates.

  2. Right-click the job template that you want to add one or more filters to, and then click Edit.

  3. Click Add, and then select SubmissionFilters or ActivationFilters.

  4. In Valid Values, specify the location of the filter relative to the %CCP_DATA%Filters folder. You can specify more than one filter in the value field. List each filter on its own line (filters are delimited by a carriage return). Filters run in the listed order, and will run before the cluster-wide filter, if specified.

    Note

    If the filter and relative path name are long, the name will wrap to the next line in the text box. This can appear to be a carriage return when you are viewing a list of filters in the job template editor. If the name on a line starts with a backslash () or does not end with “.dll”, then it is probably word wrap and not another filter.

    If an invalid filter is specified, a Could not find filter error message will be displayed.

  5. Click Save.

    Note

    The job template settings are validated when you save your changes. When you specify a DLL filter, the HPC Job Scheduler tries to load the DLL as part of validation. If the HPC Job Scheduler is unable to load the DLL, the filter is rejected and your changes are not saved to the template.

For example, the following screen shot illustrates how to add two activation filters to the Default job template. The filters are named Activation1.dll and Activation2.dll and are each in their own sub-folders:

Add job filters (DLL-based) to HPC job template

How to remove a job template filter

To remove a job template filter, remove the reference to the filter from every job template that calls it. The filter will be automatically unloaded when no more references to it exist in the job templates. The DLL filter must be unloaded before you can delete or replace the DLL file.

Additional considerations

  • If you create two job templates that reference the same DLL filter, both templates will call the same loaded instance of the DLL. If you want separate instances loaded for each template (loaded in separate app domains), you can make separate copies of the DLL and assign distinct file names. For example “myDLLa” and “myDLLb”.

  • The filter DLLs must be built using .NET Framework 3.5. If the filter DLL is built using .NET Framework 4, jobs will fail to pass the filter with a message similar to the following:

    Failed to pass job submission filter. Error:

    Microsoft.Hpc.Scheduler.AddInFilter.HpcServer.AddInFilterTimeBoundedCallException: Exception during time bounded call. See Inner Exception. --> System.BadImageFormatException: This assembly is built by a runtime newer than the currently loaded runtime an

    [message truncated]

Additional references