Getting a Job By Name

This example demonstrates how to retrieve a job based on its name.

Description

A basic task when using the API is retrieving a job based on its name. Previous versions of the API documentation showed how to do this by using Scheduler.GetObjectsForClass to retrieve all jobs and then iterating through them to find the desired job. While this is still a valid approach, it is more efficient to use Scheduler.GetObjectsWhere to do server-side filtering of the data.

Beginning with version 3.0, a job's name no longer has to be unique across the entire adTempus instance, as in previous versions. Instead it must be unique only within the group to which it is assigned. Therefore it is no longer sufficient to search only for a job with a given name: you must include the group name as well.

The JobGetter class below exposes two shated selection functions that both use a server-side filter.

GetJobForName looks for a single job, given a "fully-qualified" job name. A "fully-qualified" job name indicates the hierarchy of groups that the job is found in. For example, consider the following structure in the adTempus Console:

    Jobs Folder
       Job "Job A"
       Group "Group 1"
          Group "Group 1a"
             Job "Job B"

The fully-qualified name for "Job A" is "Job A". The fully-qualified name for job "Job B" is "Group 1\Group 1a\Job B". To retrieve these jobs using the sample code below, you would therefore call

Copy Code

    JobGetter.GetJobForName(aScheduler,"Job A")

Copy Code

    JobGetter.GetJobForName(aScheduler,"Group 1\Group 1a\Job B")

GetJobsForName returns all jobs that match a given name, regardless of what group they are in. The following code would find "Job B", regardless of what group it is in:

Copy Code

    JobGetter.GetJobsForName(aScheduler,"Job B")

Both methods require an existing client connection. See Creating a Client Session for an example of creating a client connection.

Copy Code

Public Class JobGetter

    'Gets the job with the specified name. The jobName is the complete "path" to the job,
    'including its parent groups:
    '   "Job A"                     Finds a job named "Job A" in the root group
    '   "group 1\group 1a\Job B"    Finds a job named "Job B" in group "group 1a" within group "group 1"
    'This function assumes that there will be only one name that matches the criteria. If there are more than one, it returns
    'only the first one. Use GetJobsForName to get multiple jobs.
    Public Shared Function GetJobForName(ByVal connection As IScheduler, ByVal jobName As String) As Job
        Dim filter As New JobByNameFilter(jobName)
        Dim objects As IADTObjects
        Dim recordCount As Int32

        objects = connection.GetObjectsWhere(filter, 1, True, recordCount)
        If objects.Count = 0 Then
            Return Nothing
        Else
            Return CType(objects(0), Job)
        End If

    End Function

    'Gets all jobs with the specified name. The jobName parameter should contain just the job name, without any qualifying group
    'information. GetJobForName will return all jobs that match the name, regardless of what group they are in.
    'Use GetJobForName to get a single job using a qualified job name (i.e., a job name that includes group names)
    Public Shared Function GetJobsForName(ByVal connection As IScheduler, ByVal jobName As String) As IADTObjects
        Dim filter As New JobByNameFilter(jobName)
        Dim recordCount As Int32

        filter.SingleGroupOnly = False
        Return connection.GetObjectsWhere(filter, 0, True, recordCount)

    End Function


    'Use in a call to IScheduler.GetObjectsWhere to get the job with the specified name.
    Private Class JobByNameFilter
        Implements IObjectRequestFilter
        Public JobName As String = ""
        Public SingleGroupOnly As Boolean = True
        Public Sub New(Optional ByVal aJobName As String = "")
            JobName = aJobName
        End Sub
        Public Function GetOrderClause() As String Implements ArcanaDevelopment.adTempus.Client.IObjectRequestFilter.GetOrderClause
            Return ""
        End Function

        Public Function GetSelectClause() As String Implements ArcanaDevelopment.adTempus.Client.IObjectRequestFilter.GetSelectClause
            Return "*"
        End Function

        Public Function GetTableName() As String Implements ArcanaDevelopment.adTempus.Client.IObjectRequestFilter.GetTableName
            Return "job"
        End Function

        Public Function GetWhereClause() As String Implements ArcanaDevelopment.adTempus.Client.IObjectRequestFilter.GetWhereClause

            If Not SingleGroupOnly Then
                'Search for all jobs matching this name, in all job groups
                Return "name='" & JobName & "'"
            End If

            'else we're looking for a single job, located in a specific group

            Dim match As System.Text.RegularExpressions.Match

            'the name may be just the job name (in which case we look in the root group)
            'or it may contain parent group information, delimited by "\"
            match = System.Text.RegularExpressions.Regex.Match(JobName, "(?:(.+)\\){0,1}([^\\]+)")
            If Not match.Success Then
                'it's an error, but let the server handle it.
                Return "name='" & JobName & "'"
            End If

            If match.Groups(1).Success Then
                'a group hierarchy was specified.
                'match.groups(1) contains the group path, e.g., "group 1\group 1a"
                'match.groups(2) contains the job name
                'Search for the job with the specified name within the specified group.
                'the jobGroup table has a "fullName" column that stores its full hierarchical name
                Return "name='" & match.Groups(2).Value & "' and jobGroup in (select OID from jobGroup where fullName='Root\" & match.Groups(1).Value & "')"
            Else
                'else there was no group information specified--the job is in the root.
                'match.groups(2) contains the job name, and we search only in the root group,
                'which always has the same OID.
                Return "name='" & match.Groups(2).Value & "' and jobGroup='{2C13CBB7-57D7-44A7-A74C-92B9F92A2A01}:{9A3EA996-9137-4EA7-8CAC-55E70695B473}'"
            End If

        End Function
    End Class
End Class

adTempus API Reference version 3.0.0.0, revised 10/30/2008

Send feedback on this topic