Downloads |
 Feedback
|
Table Of Contents
Using the Job and Resource Manager
Locking Resources from Another Application
Understanding the JRM Architecture
An Overview of the JRM Architecture
How JRM Relates to Other CWCS Components
Using JRM from a Java Application
Locking and Unlocking a Device
Handling an Unavailable Resource
Customizing the Job Browser Button Behaviors
Using JRM from the Command Line
About the Job and Resource Lock Attributes
About Displayed Job Status Values
About the Lock Manager Methods
Using the Job Command-Line Commands
Using the Job and Resource Manager
The Job and Resource Manager (JRM) provides a general-purpose interface that allows applications to:
•
Schedule jobs—Jobs are general-purpose and application-defined.
•
Note
The following topics describe JRM and how to use it in your applications:
•
•
•
•
For more information about the Job and Resource Manager, see the Job and Resource Management Functional Specification (BG 1.0/Rigel), ENG 21104.
This document reflects the information found in Revision L of the JRM functional specification, Job and Resource Management Functional Specification (BG 1.0/Rigel), ENG 21104. For the most recent updates to the JRM, refer to the current release of this specification.
Understanding JRM Services
Applications that use Job and Resource Management services can schedule an activity, or job, to occur based on several conditions, including:
•
Using JRM, you can schedule a job to run pending approval. For example, device image update operations are often scheduled by network administrators, but must be approved by a manager.
In this case, the network administrator can schedule an update, but it will be run by the time it is scheduled to run only if it has been approved by a manager. Anyone on the list of authorized approvers can review the jobs that require approval and either approve or reject them.
•
Applications often provide users with the means to schedule a task for a given time. SWIM, for example, lets the user specify when to update a device image. In this case, the application runs on a server, downloads the image to the specified device, and reboots the device. Normally software update tasks are run when the traffic on the device is minimal—for example, 2:00 a.m. Sunday morning. Using JRM services, SWIM can let users schedule a job to run at a specific time.
Another application might need to periodically obtain and analyze device configuration information. Using JRM services, the application can schedule a job to run once a day, once an hour, only on Friday at 3:00 p.m., and so on. JRM also provides the functionality to browse the list of scheduled jobs.
•
•
Note
•
JRM also provides job and resource lock attributes that allow applications to create their own customized functionality.
The following topics describe how JRM schedules a job and locks resources:
•
Managing JRM Services
JRM services use the following logic to schedule and run a job:
1.
2.
3.
a.
b.
c.
Automatic lock release and time-based locking prevent a rogue job from locking the device indefinitely.
d.
Scheduling Jobs
A job can be scheduled to run if it is enabled and approved (or does not require approval), and its start time is in the future. Jobs can be scheduled to run once or periodically.
When the scheduled time arrives, the Job Manager checks for the following conditions before running the job:
•
•
•
Table 19-1 summarizes the job scheduling options.
Locking Resources
Resource locks provide a way to ensure exclusive access to a device. A resource lock secures a device or device subnode, making it inaccessible to other cooperating applications using JRM for a period of time while a job is performed.
Note
When JRM receives a request to lock a resource, it checks the name of the resource against existing locks and performs one of these actions:
•
•
•
Resources are locked for a certain period of time. When a job cannot estimate how long it will need a resource, it can either:
•
or
•
Locking a resource for infinite time is not recommended. A lock can be "stuck," but that only happens when
–
–
The resource is unlocked when:
•
•
•
Locking Resources from Another Application
Although resources are typically locked by jobs run by the JRM server, they can be locked by any application. An application that wants to lock a resource must establish a connection with the JRM CORBA object and request a resource lock by providing the resource path and its ID string.
There are two differences between Job Manager and application resource locks:
•
•
Locking Parts of a Device
Applications that use JRM might need to serialize access to certain parts of the device without necessarily locking the whole device. The device associated with the particular resource must also be easily identified.
JRM's resource naming scheme allows resources to form a hierarchy. The top-level nodes of the hierarchy are fully qualified device names (for example, nm7501.cisco.com) and the subnodes correspond to the parts of the device (for example, card0). Each lock is identified by its resource path, starting from the top level (nm7501.cisco.com/card0).
Locking a particular node prevents other applications from locking any nodes below it and all the nodes on the path to it. For example, if there is a lock for nm7501.cisco.com/card0:
•
•
•
Understanding the JRM Architecture
The following topics describe the JRM architecture:
•
•
•
An Overview of the JRM Architecture
The following figure shows the relationship between JRM, its components, and its clients.
Figure 19-1 JRM Architecture
JRM consists of the following components:
•
–
–
–
–
–
To learn more about the JRM server, see the "Understanding the JRM Server" section.
•
The JRM servlet:
–
–
For information about using the JRM servlet, see the "Using JRM from a Web Browser" section.
•
To learn more about the Job Browser, see the"Understanding the Job Browser" section.
•
For information about designing custom HTML pages, see the "Customizing the Job Browser Button Behaviors" section.
•
For information about using command line applications, see the "Using JRM from the Command Line" section.
Understanding the JRM Server
The JRM server provides job and locking services to various clients, including applications that schedule jobs or lock and unlock resources, jobs that JRM creates in response to a schedule request, the JRM servlet, and the command reference interfaces.
The following topics describe the JRM server components:
About Jobs and Resources
The two fundamental JRM entities are jobs and resource locks:
•
–
–
–
–
Job information is stored in a database table, where each row represents a single job. On startup, JRM reads the table and creates job objects. While running, JRM automatically updates the corresponding row to reflect every change in a job object. When a new job is created, a new row is added to the table. When a job is deleted, the corresponding row in the table is deleted.
•
–
–
–
Note
About JRM Server Classes
The JRM server application class performs these functions:
•
•
•
–
Jobs.JobTableJobs.LaunchQueueJobs.Terminator–
–
–
–
–
–
•
About the IDL Interface
The JRM server implements two objects: JobManager and LockManager. Enumeration interfaces are implemented by the iterator objects, JobIter and LockIter. The JRM IDL (Interface Definition Language) file includes the interfaces of the objects supplied by the JRM server.
Related Topics
•
•
–
–
About the Helper API
The Client class provides a collection of static methods that might be helpful for clients that manipulate jobs and resources. The methods can be categorized by the main class and several inner classes:
•
The Client class contains these methods, which can be used by any client:
–
–
–
•
–
–
–
–
–
–
Related Topics
See the "About the Helper API Methods" section.
About JRM Events
JRM can use Event Services Software (ESS) and the Event Distribution System (EDS) to publish events of interest to applications. JRM sends events when:
•
•
•
•
•
•
•
These events belong to the event category status (EventCategory_Status). The event and resource atoms are listed in com.cisco.nm.cmf.jrm.JrmEdsAtomDev.java.
JRM publishes the following topics using ESS:
•
•
•
•
•
•
•
•
•
JRM publishes the following topics using EDS:
•
•
•
•
•
•
•
•
JRelated Topics
See:
•
•
Understanding the Job Browser
The Job Browser is a configurable Java applet that you can embed in HTML pages to provide a GUI for browsing and managing JRM jobs and resources. The Job Browser uses XML files to specify:
•
•
Figure 19-2 shows the Job Browser interface, which provides the user actions shown in Table 19-2.
Figure 19-2 Sample Job Browser Dialog Box
Figure 19-3 Sample Job Resource Dialog Box
Table 19-3
Job Browser User Actions
Related Topics
•
How JRM Relates to Other CWCS Components
JRM relies on:
•
•
Enabling JRM
JRM is part of CWCS System Services. Since CWCS release 3.0, JRM services are enabledby default. If your application requires services from JRM, remember to register for this service at installation. For instructions, refer to the "Registering for CWCS Services" section on page 5-4. If you prefer to request services after installation, refer to the "Enabling New Service Bundles from the Command Line" section on page 5-5.
Using JRM from a Java Application
To use JRM from a Java application, you must, for example, know how to establish a connection with the Job Manager, create a job, and set the status of the job. The following topics describe some typical job and lock management tasks:
•
•
For a description of the JRM APIs, see the "JRM Command Reference" section.
Establishing a Connection
Example 19-1 shows how to establish a connection with the Job Manager. The host where the JRM server is running is passed as a parameter.
Note
Example 19-1 Connecting with Job Manager
import java.lang.*;import java.net.*;import com.cisco.nm.cmf.jrm.*;import com.cisco.nm.cmf.util.CmfException;import com.cisco.nm.cmf.util.Util;import org.omg.CORBA.*;import com.inprise.vbroker.CORBA.BindOptions;import java.util.*;public class testJpp {public static void main (String[] args) {JrmServiceManager jrm=null;JobManager jm=null;String nmsroot;String host;try {Util.loadBGProperties("md.properties");nmsroot=System.getProperty("NMSROOT");System.out.println("NMSROOT is "+nmsroot);} catch(CmfException cmf) {System.out.println("unable to load md.properties");}try {host=(InetAddress.getLocalHost()).getHostName();System.out.println("host = " + host);Properties ORBProperties = Client.getOrbConnectionProperties();ORBProperties.put("org.omg.CORBA.ORBClass","com.inprise.vbroker.orb.ORB");org.omg.CORBA.ORB orb = (com.inprise.vbroker.CORBA.ORB)com.cisco.nm.util.OrbUtils.initORB(null,ORBProperties);jrm = JrmServiceManagerHelper.bind(orb,Client.getJrmName(),host,null);System.out.println("Connected to JRM service Manager.");LoginInfo loginInfo = new LoginInfo("admin","admin","");jm = jrm.getJobHandle(loginfInfo);} catch (org.omg.CORBA.SystemException e){e.printStackTrace();System.err.println(e.toString());return;} catch (Exception e) {e.printStackTrace();System.err.println(e.toString());return ;}if (jm == null) {System.out.println("Job Manager not bound");return;}//Foll code to create a joblong start=System.currentTimeMillis()+20000;int type=Constants.SCHTYPE_S_Minutes;int increment=3;Schedule sch=new Schedule(start,type,increment);int precedents[]={};JobInfo ji =new JobInfo(0,// id"TestJob",// typenew String("Test job"),// description"D:\\progra~1\\mkstoo~1\\mksnt\\sleep.exe 30",sch,// scheduleprecedents,// dependenciesConstants.RUNST_NeverRan,// stateConstants.SCHST_Enabled,// enabledSystem.currentTimeMillis(),// Time createdSystem.currentTimeMillis(),// Time modified0,// Start0,// Stop"Scheduling Job",// Progresshost,// Host default=localhost)new String("system"),// Account (default=system)new String("Reference"),// Reference"admin",// Owner""// Approver);IntHolder jid=new IntHolder(0);if(ji == null) {System.out.println("Job info is null");System.exit(1);}int status=jm.job_create_hist(ji,jid);if(status != Constants.STATUS_Ok) {System.out.println("Failed to create Job");System.exit(-1); // job creation failed} else {System.out.println("Job "+jid.value+" created sfly.");}}
Creating a Job
Example 19-2 shows how to create a job with these attributes:
•
•
•
•
•
Example 19-2 Creating a Job
// Create a jobJRM.Schedule sch =new Schedule(System.currentTimeMillis()+60*1000, // Start in a minuteSCHTYPE_Once,SCHINC_Months, // Doesn't matter0);int precedents[] = {};JRM.JobInfo ti =new JobInfo( 0,// id"ACLM", // type"Description", // description"$JP -cp $JC $JJ myJavaClass", // command:// run myJavaClasssch, // scheduleprecedents, // dependenciesRUNST_NeverRan, // stateSCHST_RequiresApproval // Approval state:| SCHST_AM_WAITING // requires approval,| SCHST_ENABLED, // enabled0, // Time created0, // Time modified0, // Start0, // Stop"", // Progress"", // Host default=localhost)"", // Account (default=system)"", // Reference"", // Owner"" // Approver);// Create holder for the returned valueIntHolder h_id = new IntHolder(0);// Create a job, test its statustry {int stat = job_manager.job_create(ti,h_id);if (STATUS_Ok == stat) {System.out.println("Created job with id = ", h_id.value);}else {...}catch (org.omg.CORBA.SystemException e) {// Attempt to reconnect explicitly}}
Setting the Job Status
The following code fragment tells JRM that the job has ended successfully and sets its progress string (which will become the completion string) to "Download successful":
import com.cisco.nm.cmf.jrm.Client;...Client.MyJob.set_completion_state(Client.RUNST_Succeeded);Client.MyJob.set_progress("Download successful");You need to keep the following in mind:
•
•
The displayed job status is a dynamic attribute of the job. JRM calculates the status based on the job's run state, scheduled state attributes, and the current time.
•
–
–
•
The job status values for both run-once and periodic jobs are summarized in the tables in the "About Displayed Job Status Values" section.
Getting Job Descriptions
Example 19-3 shows how to get the job descriptions for all scheduled jobs.
Example 19-3 Getting Job Descriptions
jrm.JobIterHolder iter = new JobIterHolder();jrm.JobInfoHolder job_info = new JobInfoHolder();try{//Get the job enumeratorint status = job_manager.job_enum(iter);if (STATUS_Ok == status){while (STATUS_EOF != iter.value.next(job_info)){System.out.println(job_info.value.szDescription);}iter.value.release();}}catch (org.omg.CORBA.SystemException e){// .....}
Handling an Unapproved Job
Use the code fragment in Example 19-4 when a job that requires approval is scheduled and has not been approved by the scheduled time. The job execution is abandoned, and the job deleted if it is not periodic.
Example 19-4 Handling Unapproved Jobs
jrm.JobInfoHolder job_info = new JobInfoHolder();// Find out the job details corresponding to the job.int status = job_manager.job_get_info(idJob,job_info);// If the job is still waiting for approval, then execution of the// job is abandoned.if ((STATUS_Ok == status)&&(SCHST_AM_Waiting == (SCHST_AM_Masks & job_info.value.sch_state))){System.out.println ("Still waiting for approval, so can't start now");jrm.ScheduleHolder schedule = new ScheduleHolder();// Get the job scheduleint stat = job_manager.job_get_schedule(idJob,schedule);// Check the schedule type.If the job is not periodic, delete the jobif (STATUS_Ok == stat){if ((SCHTYPE_Immediate == schedule.value.type)||(SCHTYPE_Once == schedule.value.type)){System.out.println ("Now deleting the job") ;job_manager.job_delete(idJob);}}}
Enabling a Disabled Job
Example 19-5 shows how to create a job in the disabled state, do some operations, and then enable the job.
Example 19-5 Enabling a Disabled Job
// Create a jobjrm.Schedule sch = new Schedule(0,SCHTYPE_Immediate,SCHTYPE_Monthly //Ignored for SCHTYPE_Immediate);int precedents[] = {};// Create the JobInfo structure with appropriate valuesjrm.JobInfo job_info = new JobInfo( 0,// id"ACLM",// type"Description", // description"$JP -cp $JC $JJ myJavaClass",// command:// run myJavaClasssch,// scheduleprecedents, // dependenciesRUNST_NeverRan,// stateSCHST_AM_Approved,// Approval state:0, // Time created0, // Time modified0, // Start0, // Stop"", // Progress"", // Host default=localhost)"", // Account (default=system)"", // Reference"", // Owner"" // Approver);// IntHolder for holding the JobIdorg.omg.CORBA.IntHolder h_id = new org.omg.CORBA.IntHolder(0);// Create a job, test its statustry{int stat = job_manager.job_create(job_info,h_id);if (STATUS_Ok == stat){System.out.println("Job created with id = "+ h_id.value);}else{System.out.println("Job creation failed ");System.exit(0);}//Perform some operations involving the newly created job// ............// Now enable the jobint status = job_manager.job_set_resume(h_id.value,true);if (STATUS_Ok != status){System.out.println("Job resumption failed");}}catch (org.omg.CORBA.SystemException e){System.out.println("Exception while job creation ");System.exit(0);}
Handling a Crashed Job
Example 19-6 shows how to get a job's current running state and delete a crashed job.
Example 19-6 Handling a Crashed Job
org.omg.CORBA.IntHolder result = new org.omg.CORBA.IntHolder();int status = job_manager.job_get_result(idJob, result);if (STATUS_Ok == status){if (result.value == RUNST_Crashed){// Delete the jobstatus = job_manager.job_delete(idJob);if (STATUS_Ok != status){System.out.println("No such job exists");}}}else{System.out.println(" Getting the run state failed!");}
Locking and Unlocking a Device
In Example 19-7, a job locks a device, does some processing, and releases the lock.
Example 19-7 Locking and Unlocking a Device
LockManagerImpl lock_manager = new LockManagerImpl("TEST");int status = lock_manager.lock("device1", "my_app", 1000);/* If no job has locked device1 yet, then status = STATUS_Ok */if (STATUS_Ok == status){System.out.println("No lock exists now for the device ");//... do some processing....lock_manager.unlock("device1","my_app");}
Handling an Unavailable Resource
In Example 19-8, a job is enabled and approved and then, at the scheduled time, it tries to lock a resource and fails.
Example 19-8 Handling an Unavailable Resource
int status = 0;jrm.JobInfoHolder job_info = new JobInfoHolder();try{// Find out the job details corresponding to the job.status = job_manager.job_get_info(idJob,job_info);}catch (org.omg.CORBA.SystemException e){System.exit(0);}//If the job is approved and is enabled then try to run the jobif ((STATUS_Ok == status)&& (SCHST_AM_Approved == (SCHST_AM_Masks & job_info.value.sch_state))&&(SCHST_Enabled == (job_info.value.sch_state & SCHST_Enabled))){try{//Lock the required devicesstatus = lock_manager.lock("device name","owner",1000);// If locking failedif (STATUS_Ok != status){jrm.ScheduleHolder schedule = new ScheduleHolder();// Get the job scheduleint stat = job_manager.job_get_schedule(idJob,schedule);if (STATUS_Ok == stat){// If the job is not periodic, then delete the jobif ((SCHTYPE_Once == schedule.value.type) ||(SCHTYPE_Immediate == schedule.value.type)){System.out.println ("Now deleting the job");job_manager.job_delete(idJob);}}}// Run the jobelse{status = job_manager.job_run(idJob);if (STATUS_Ok != status){System.out.println ("job run failed");}}}catch(org.omg.CORBA.SystemException e){System.exit(0);}}
Accessing a Locked Device
In Example 19-9, a job is trying to lock a device that is already locked by another job. The code finds the information about the other job and, if that job is not running, releases all resources locked by it. Then it tries to lock the device. After the device is locked, the job does some processing and then releases the lock.
Example 19-9 Accessing a Locked Device
/* Current job is trying to lock a device device1 */int status = lock_manager.lock("device1", "my_app", 2000);/* If some job has already locked device1, then status = STATUS_Exists */if (STATUS_Exists == status){/* Find out the complete Lock_info for device1 */jrm.LockInfoHolder lock_info = new LockInfoHolder();status = lock_manager.get_lock("device1",lock_info);/* If Lock_info found for device1, status = STATUS_Ok */if (status==STATUS_Ok){Integer int_id = new Integer(lock_info.value.szJob);int job_id = int_id.intValue();jrm.JobInfoHolder job_info = new JobInfoHolder();// Find out the job details corresponding to the job id obtained.status = job_manager.job_get_info(job_id,job_info);if (status==STATUS_Ok){if (job_info.value.run_state != RUNST_Running){// Release all resources locked by the joblock_manager.unlock_job(lock_info.value.szJob);status = lock_manager.lock("device1","my_app", 1000);// ... do some processing....lock_manager.unlock("device1","my_app");}}elseSystem.out.println("No job exists");}
Using JRM from a Web Browser
The JRM servlet provides the URL interface to the JRM server process. The servlet communicates with the JRM server via CORBA to execute the commands it receives. All responses from the JRM servlet are XML-encoded.
Table 19-4 summarizes the URL commands which the JRM servlet supports via HTTP POST and GET requests.
Customizing the Job Browser Button Behaviors
To customize the behavior of the buttons in the Job Browser dialog box, modify the action configuration file summarized in Table 19-5. The action configuration file contains the tags listed in Table 19-6.
Return values for the BUTTON and URL tags shown in Table 19-6 is as follows:
•
•
Example 19-10 shows the default Job Browser action configuration file.
Example 19-10 Default Job Browser Action Configuration File
<?xml version="1.0"?><ACTIONS><JOBTYPE ID="Test"><ACTION BUTTON="details" URL="/jrm/TestDetails.html" /><ACTION BUTTON="stop" URL="/CSCOnm/servlet/com.cisco.nm.cmf.jrm.JrmServlet" /><ACTION BUTTON="kill" URL="/CSCOnm/servlet/com.cisco.nm.cmf.jrm.JrmServlet" /><ACTION BUTTON="remove" URL="/CSCOnm/servlet/com.cisco.nm.cmf.jrm.JrmServlet" /></JOBTYPE><JOBTYPE ID="NetConfigJob"><ACTION BUTTON="stop" URL="/CSCOnm/servlet/com.cisco.nm.config.netconfig.server.NetConfigUIServlet" /><ACTION BUTTON="kill" URL="/CSCOnm/servlet/com.cisco.nm.config.netconfig.server.NetConfigUIServlet" /><ACTION BUTTON="remove" URL="/CSCOnm/servlet/com.cisco.nm.config.netconfig.server.NetConfigUIServlet" /><ACTION BUTTON="details" URL="/netconfig/netconfig.jsp" /></JOBTYPE><JOBTYPE ID="NetConfigPurge"><ACTION BUTTON="remove" URL="/CSCOnm/servlet/com.cisco.nm.config.netconfig.server.NetConfigUIServlet" /><ACTION BUTTON="kill" URL="/CSCOnm/servlet/com.cisco.nm.config.netconfig.server.NetConfigUIServlet" /><ACTION BUTTON="stop" URL="/CSCOnm/servlet/com.cisco.nm.config.netconfig.server.NetConfigUIServlet" /></JOBTYPE></ACTIONS>To customize the Job Details and Stop Job buttons but rely on the default JRM action for the Remove Job button for the ACL Manager, add the following element to the action configuration file:
<JOBTYPE ID="acl"><ACTION VERB="details" URL="/acl/editjob"/><ACTION Verbosity" URL="/acl/stopjob"/></JOBTYPE>Using this action configuration, if the user selects an ACL job with Id=42 and clicks "Job Details", the JRM browser will issue the following GET request and display the result in a new browser window:
http://server:1741/acl/editjob?jobid=42&button=detailsIf the user clicks "Stop Job" and selects "stop" (not "kill") from the dialog box, the JRM browser will issue the following GET request:
http://server:1741/acl/stopjob?jobid=42&button=stopIf the response is "true," a dialog box is displayed indicating that the operation was initiated successfully. If the response is "false: device not responding" (for example), a dialog box will be displayed with the text, "device not responding."
Using JRM from the Command Line
JRM includes two command line applications, jobcli and lockcli, that provide a command language interface for scheduling jobs and locking resources. These applications are used for debugging purposes and to provide a JRM interface for non-Java applications such as Perl or C++.
The following topics describe jobcli and lockcli:
•
•
Related Topics
See the "Using the Job Command-Line Commands" section
Job Command Line Interface
The job command line application, jobcli (shown in Table 19-7), is a Java application that provides a simple job manipulation command language.
Table 19-7 Jobcli Interface
com.cisco.nm.cmf.jrm.jobcli
Provides a simple command language that allows you to:
•
•
•
•
You can provide inputs to jobcli using either:
•
•
The jobcli commands are described in the "Using the Job Command-Line Commands" section.
classpath
Environment variable that tells the interpreter where to look for user-defined classes.
-f clifile
Reads commands from clifile. If -f option is missing, commands are read from standard input.
Sent to stdout/stderr.
Lock Command Line Interface
The lock command line application, lockcli (shown in Table 19-8), is a Java application that provides a simple lock manipulation command language.
.
JRM Command Reference
JRM provides interfaces from Java, IDL, and servlets, and via command line utilities. These topics describe the reference information for these interfaces:
•
•
•
•
•
About the Job and Resource Lock Attributes
Table 19-9 describes the available job attributes.
Table 19-10 summarizes the available resource lock attributes.
About Displayed Job Status Values
Displayed job status value vary according to how often the job is run and whether approval is required.
Table 19-11 summarizes the displayed job status for run-once, approval-required jobs.
Table 19-12 summarizes the displayed job status for run-once, no-approval-required jobs.
Table 19-13 summarizes the displayed job status for periodic, approval-required jobs.
Table 19-14 summarizes the displayed job status for periodic, no-approval-required jobs.
About the Job Manager Methods
Use the Job Manager methods summarized in Table 19-15 to add JRM scheduling functionality to your application. These methods return Java constants described in the "About the JRM Java Constants" section.
Table 19-15 Job Manager Method Summary
Cancels a running job
Cancels a running job with instance ID.
Cancels a running event
Cancels a running job with instance ID, and specified whether to cancel the instance alone or the entire job
Creates a job
Creates a job with job history
Deletes a job
Creates a job enumerator
Gets information about a job
Adds job information history about a job
Gets job run state
Fills schedule with job schedule
Gets job schedule information
Runs a job immediately
Approves or rejects a job
Updates job information
Updates job information
Sets progress string
Sets job reference attribute
Sets job run state
Enables or disables a job
Sets job schedule
Fills job_info with job information
Fills job_seq with job descriptions
Releases an iterator
job_cancel
int job_cancel (int idJob);Cancels a job if it is running. The job sends a request to stop.
Note
Input Arguments
Return Values
Usage Guidelines
To cancel a running job, send a request to the Daemon Manager to stop the process.
job_cancel_instance
int job_cancel_instance (int idJob, int instanceId, boolean cancelAllInstances);Cancels an instance job if it is running.
Note
Input Arguments
Return Values
Usage Guidelines
To cancel a running job, send a request to the Daemon Manager to stop the process.
job_cancel_event
int job_cancel_event (int idJob)Cancels a job if it is running. Sends a cancel event to the running job. The job should process the event and stop the event by itself.
Note
Input Arguments
Return Values
Usage Guidelines
To cancel a running job, send a request to the Daemon Manager to stop the process.
job_cancel_instance_event
int job_cancel (int idJob, int instanceId, boolean cancelAllInstances);Cancels an instance of an event if it is running.
Note
Input Arguments
Return Values
Usage Guidelines
To cancel a running instance of the job, send a request to the Daemon Manager to stop the process.
job_create
int job_create (JobInfo job_info, org.omg.CORBA.IntHolder idJob);Creates a job. The ID field and all fields related to the last job execution are ignored.
Input Arguments
[JobInfo] Job information. The JobInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Output Arguments
Return Values
job_create_hist
int job_create_hist (JobInfo jiJob, org.omg.CORBA.IntHolder idJob);Creates a job. The ID field and all fields related to the last job execution are ignored.
Input Arguments
[JobInfo] Job information. The JobInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Output Arguments
Return Values
job_delete
int job_delete (int idJob);Deletes the job with the given ID.
Input Arguments
Return Values
job_delete_instance
int job_delete_instance (int idJob, int instanceId, boolean delFlag);Deletes the job with the given ID.
Input Arguments
Return Values
job_enum
int job_enum (JobIterHolder job_iter);Creates the job enumerator.
Output Arguments
Return Values
Example
Use this method with the next and release methods to retrieve the next job.
JobIterHolder jih = new JobIterHolder ();JobInfoHolder jobinfo = new JobInfoHolder ();/* Get the JobIter and browse through it */if (STATUS_Ok == job_manager.job_enum(jih)){while (STATUS_Ok == jih.value.next(jobinfo)){// do the required operations on JobInfo}}//Calling the release of JobIterjih.value.release();The functions next (), next_n() and release() are to be called on the JobIter reference, which can be obtained by calling the job_enum API.
job_enum_hist
int job_enum_hist (JobIterHist job_iter);Creates the job enumerator.
Output Arguments
Return Values
Example
Use this method with the next and release methods to retrieve the next job.
JobIterHolder jih = new JobIterHolder ();JobInfoHolder jobinfo = new JobInfoHolder ();/* Get the JobIter and browse through it */if (STATUS_Ok == job_manager.job_enum(jih)){while (STATUS_Ok == jih.value.next(jobinfo)){// do the required operations on JobInfo}}//Calling the release of JobIterjih.value.release();The functions next (), next_n() and release() are to be called on the JobIter reference, which can be obtained by calling the job_enum API.
job_get_info
int job_get_info (int idJob, JobInfoHolder job_info);Fills the job information data structure with information about a given job.
Input Arguments
Output Arguments
[JobInfoHolder] Job information. The JobInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
job_get_info_hist
int job_get_info (int idJob, int instanceId, JobInfoHistHolder jiJobHist);Fills the job information data structure with information about a given job.
Input Arguments
[int] Unique number assigned to a job at creation time.
[int] Unique number assigned to an instance of a job at creation time.
Output Arguments
[JobInfoHolder] Job information. The JobInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
job_get_result
int job_get_result (int idJob, IntHolder status);Retrieves the current run state of a job.
Input Arguments
Output Arguments
Return Values
job_get_schedule
int job_get_schedule (int idJob, ScheduleHolder schedule);Fills the schedule data structure with the job's scheduling information.
Input Arguments
Output Arguments
[ScheduleHolder] Job scheduling information. The Schedule structure, which is defined in the IDL file (see the "About the IDL Interface" section), includes the next time to start, the type of schedule, and the time increment.
Return Values
job_get_schedule_string
int job_get_schedule_string (int idJob, StringHolder schedule);Puts a displayable representation of the job schedule into the string contained in schedule.
Input Arguments
Output Arguments
Return Values
job_run
int job_run (int idJob);Runs the job immediately.
Input Arguments
Return Values
job_set_approved
int job_set_approved (int idJob,boolean bApproved,String szApprover)Approves or rejects a job. This method approves or rejects a job and records the approver name.
Input Arguments
[int] Unique number assigned to a job at creation time.
[boolean] True = approve job. False = reject job.
[String] Account of the approver.
Return Values
Usage Guidelines
If a nonperiodic job that requires approval has not been approved by the time it is scheduled to run, it is automatically rejected.
job_set_info
int job_set_info (JobInfo job_info);Replaces all job information.
Input Arguments
[JobInfo] Job information. The JobInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
job_set_info_hist
int job_set_info_hist (JobInfoHist jiJobHist);Replaces all job information.
Input Arguments
[JobInfo] Job information. The JobInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
job_set_progress_string
int job_set_progress_string (int idJob, String szStatus);Sets the progress string with update or diagnostic information.
Input Arguments
[int] Unique number assigned to a job at creation time.
[String] Updates or diagnostic information.
Return Values
job_set_reference
int job_set_reference (int idJob, String szReference);Sets the job's reference attribute.
Input Arguments
[int] Unique number assigned to a job at creation time.
[String] An application-specific string. May contain the URL of the job results.
Return Values
job_set_result
int job_set_result (int idJob, int state);Sets the job's current run state. The only states the application is allowed to set are Succeeded, SucceededWithInfo, or Failed.
Input Arguments
Return Values
Success.
No such job.
State was not Succeeded, SucceededWithInfo, Never Ran, Canceled, CanceledInstance, or Failed
job_set_resume
int job_set_resume (int idJob, boolean bResume);Resumes or suspends a job. When a previously suspended job is resumed, it is scheduled to run according to its schedule type (run once or periodic) provided that it is approved or does not require approval.
Input Arguments
[int] Unique number assigned to a job at creation time.
[boolean] True = resume job. False = suspend job.
Return Values
Usage Guidelines
You can use the following technique when a job needs to be run immediately but only after certain actions are performed by the job creator:
•
•
•
job_set_schedule
int job_set_schedule (int idJob, Schedule schedule);Sets the job's schedule to schedule.
Input Arguments
[int] Unique number assigned to a job at creation time.
[Schedule] Job scheduling information. The Schedule structure, which is defined in the IDL file (see the "About the IDL Interface" section), includes the next time to start, the type of schedule, and the time increment.
Return Values
next
int next (JobInfoHolder job_info);Returns the JobInfo instance for the next task entry.
Output Arguments
[JobInfoHolder] Job information. The JobInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
Example
See the"job_enum" section.
next_n
int next_n (int max_jobs, JobInfoSequenceHolder job_seq);Fills the job holder array with the next group of jobs.
Input Arguments
Output Arguments
[JobInfoSequenceHolder] An array of objects that allows you to retrieve the next max_jobs jobs.
Return Values
Example
See the "job_enum" section.
release
int release();Releases the iterator and makes it unavailable to the clients.
Arguments
None
Example
See the "job_enum" section.
About the Lock Manager Methods
Use the Lock Manager methods summarized in Table to add JRM resource locking functionality to your application. These methods return Java constants described in the "About the JRM Java Constants" section.
Table 19-16 JRM Lock Manager Method Summary
Creates an iterator
Finds a lock entry
Gets lock information
Locks a resource
Locks multiple resources
Fills lock_info
Fills lock_seq
Releases an iterator
Unlocks a resource
Unlocks all locks for a job
Unlocks multiple resources
enum_job_locks
Status enum_job_locks (String szJob, LockIterHolder lock_iter);Creates an iterator for all the locks for this job or process.
Input Arguments
[String] For a job, the string representation of the job ID. For a process, the name known to the Daemon Manager.
Output Arguments
[LockIterHolder] Object used to retrieve the next lock. The LockIter structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
Example
Use this method with the next and release methods to retrieve the next lock.
LockIterHolder lih = new LockIterHolder ();LockInfoHolder lockInfo = new LockInfoHolder ();/* Get the LockIter and browse through it */if (STATUS_Ok == lock_manager.enum_job_locks(lih)){while (STATUS_Ok == lih.value.next(lockInfo)){// do the required operations on LockInfo}}//Calling the release of LockIterlih.value.release();find_lock
Status find_lock (String szResource, LockInfoHolder lock_info);Finds the lock entry that prevents a device from being locked. Unlike get_lock, which returns the lock information for a specific device, find_lock returns the lock information for the device that is preventing another resource from being locked.
For more information about the locking hierarchy, see the "Locking Parts of a Device" section.
Input Arguments
Output Arguments
[LockInfoHolder] Lock information. The LockInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
get_lock
Status get_lock(String szResource, LockInfoHolder lock_info);Returns lock information for a device. This method differs from find_lock, which finds the lock entry that is preventing a device from being locked.
Input Arguments
Output Arguments
[LockInfoHolder] Lock information. The LockInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
lock
Status lock (String szResource, String szOwner, int duration);Locks the resource for duration seconds. If the job already owns this resource, this method will change the lock expiration time.
Input Arguments
Return Values
Success (job was killed or is not running).
The lock for that resource already exists.
lock_n
Status lock_n (LockRequest[] Locks, String szOwner);Locks multiple resources.
Input Arguments
Return Values
Success. (All resources have been successfully locked.)
At least one resource could not be locked.
next
Status next (LockInfoHolder lock_info);Fills the lock holder with the lock entry information and advances to the next lock entry in the locks list.
Output Arguments
[LockInfoHolder] Lock information. The LockInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
Example
See the "enum_job_locks" section.
next_n
Status next_n (int max_locks, LockInfoSequenceHolder lock_seq);Fills the lock holder array with the next group of locks.
Input Arguments
Output Arguments
[LockInfoSequenceHolder] An array of objects that allows you to retrieve the next max_locks locks. The LockInfo structure is defined in the IDL file (see the "About the IDL Interface" section).
Return Values
Example
See the "enum_job_locks" section.
release
Status release();The release method releases an iterator and makes it unavailable to the clients.
Arguments
None
Example
See the "enum_job_locks" section.
unlock
Status unlock (String szResource, String szOwner);Unlocks the specified resource.
Input Arguments
[String] Name of the resource to be unlocked.
[String] For a job, the string representation of the resource owner. For a process, the name known to the Daemon Manager.
Return Values
unlock_job
Status unlock_job (String szJob);Release all locks for the specified job.
Input Arguments
[String] For a job, the string representation of the job ID. For a process, the name known to the Daemon Manager.
Return Values
unlock_n
Status unlock_n (String[] Resource, String szOwner);Unlocks all the resources in the specified list.
Input Arguments
[String] Array of device names and any subnodes.
[String] For a job, the string representation of the resource owner. For a process, the name known to the Daemon Manager.
Return Values
About the Helper API Methods
The Helper API consists of the class Client and the inner class of Client, MyJob. Only jobs running under JRM can use the helper methods in the MyJob class. These methods return Java constants described in the "About the JRM Java Constants" section.
Related Topics
Returns a printable representation of the schedule string. Defines SCHTYPE constants.
Returns a printable representation of a job's run and schedule states.
Initializes the ORB and locates servers.
This inner class is a collection of the static methods that can be used only from jobs running under JRM.
The methods in MyJob automatically establish connection with ORB. They obtain the value of Job Id (which they need to communicate to the JRM) from the nm.jrm.jobid property.
The easiest way to set this property is to add the $JJ parameter to the job's command line (see the "About the Job and Resource Lock Attributes" section).
Table 19-17 MyJob Class Method Summary
Gets the job ID
Gets the job instance ID
Fills h_ji with job information
Fills h_ji with job information with additional parameters for req_hist and instance_id
Fills h_li with lock information
Checks server status
Locks the resource for the current job
Locks multiple resources
Sets the running job's status
Sets the running job's progress string
Unlocks the resource
Unlocks all resources for the current job
get_job_id
static int get_job_id();MyJob method returns the job ID by retrieving the value of nm.jrm.jobid property. This property is set by adding $JJ on the job's command line.
Arguments
None
Return Values
get_job_instance_id
static int get_job_instance_id();MyJob method returns the job instance ID by retrieving the value of nm.jrm.jobinstanceid property. This property is set by adding $JJ on the job's command line.
Arguments
None
Return Values
get_job_info
static int get_job_info (JobInfoHolder h_ji);MyJob method sets h_ji.value to JobInfo of self.
Output Arguments
Return Values
get_job_info_hist
static int get_job_info_hist (JobInfoHistHolder h_ji);MyJob method sets h_ji.value to JobInfoHist of self.
Output Arguments
Return Values
get_lock_info
static int get_lock_info (string szLockPath, LockInfoHolder h_li);MyJob method that returns lock information for this lock if the resource szLockPath is locked.
Input Arguments
Output Arguments
Return Values
getOrbConnectionProperties
static public Properties getOrbConnectionProperties()Initializes the ORB and locates servers.
Arguments
None
Returns
getScheduleString
static String getScheduleString (Schedule sch)Returns a printable representation of the schedule string. Defines SCHTYPE constants.
Input Arguments
[Schedule] Schedule object, which includes:
•
•
Returns
getStateStrings
static void getStateStrings (JobInfo ji, StringHolder h_szRunState, StringHolder h_szSchState)Returns a printable representation of a job's run and schedule states.\
Input Arguments
Output Arguments
is_server_running
static boolean is_server_running();MyJob method that checks to see if the server is running.
Arguments
None
Return Values
lock
static int lock (string szLockPath, int duration);MyJob method that locks the resource for the current job for duration seconds.
Input Arguments
[string] Device name and any subnode.
[int] Number of seconds to lock the resource.
Return Values
lock_n
static int lock_n (LockRequestSequence Locks);MyJob methods that locks multiple resources.
Input Arguments
[LockRequestSequence] An array of objects that allows you to specify the resources to be locked.
Return Values
Success.
Not called from job.
At least one resource cannot be locked.
set_completion_state
static int set_completion_state (int run_state);MyJob method that sets the running job's status (completed successfully, failed, canceled).
Input Arguments
Return Values
Success. If some of the resources were not locked, they are ignored.
Not called from job.
set_progress
static int set_progress (string szProgress);MyJob method that sets the running job's progress string.
Input Arguments
Return Values
unlock
static void unlock (string szLockPath);MyJob method that unlocks a resource.
Input Arguments
Return Values
unlock_all
static int unlock_all();MyJob method that releases all the resources for the current job.
Arguments
None
Return Values
About the JRM Java Constants
This section describes the symbolic constants for Java applications. These constants are initialized in the IDL file (see the "About Displayed Job Status Values" section).
Table 19-18 JRM Java Method Return Codes
STATUS_Ok
Success
STATUS_Exists
Entry already exists
STATUS_NotFound
Entry not found
STATUS_EOF
End of iteration
.
Table 19-21 JRM Schedule Types
SCHTYPE_Immediate
Run job immediately
SCHTYPE_Once
Run job once
SCHTYPE_Daily
Run every n days
SCHTYPE_Weekly
Run every n weeks1
SCHTYPE_Monthly
Run every n months2
SCHTYPE_MonthLastDay
Run on the last day of the month every n months
SCHTYPE_MonthSameXday
Run on the given day (Sunday/Monday/...) of the first/second/... week of the month every n months3
SCHTYPE_MonthLastXday
Run on the given day of the last week of the month every n months4
SCHTYPE_S_Seconds
Run every n seconds
SCHTYPE_S_Minutes
Run every n minutes
SCHTYPE_S_Hours
Run every n hours
SCHTYPE_E_Seconds
Run n seconds after the previous run ended
SCHTYPE_E_Minutes
Run n minutes after the previous run ended
SCHTYPE_E_Hours
Run n hours after the previous run ended
1 Start date day of the week.
2 Start date day of the month.
3 Start date week number and the week day.
4 Start date week day.
Note
Parsing ESS Messages
Use the helper class EssMessageCreator to parse and read the variables in the ESS message. After reading the message, your application can create an EssMessageCreator object using the constructor EssMessageCreator(String message). This will parse the details in the message. Your application can then get the values for variables using the member variable of the object. The member variables are shown in Table 19-22.
Using the Job Command-Line Commands
Use jobcli, the job command-line application, to run JRM functions. Table 19-23 summarizes the jobcli commands.
Related Topics
•
•
Table 19-23 jobcli Command Summary
Approves a job
Cancels a job
Creates a job
Creates and suspends a job
Deletes a job
Rejects a job
Resumes a job
Creates and runs a job
Reschedules a job
Suspends a job
Prints the next shcheduled run time for the job details on clicking on the command link
approve
approve jobId approverApproves the job jobId.
Input Arguments
[integer] Unique number assigned to a job at creation time.
[string] Account of the person who approved the job. Valid only if approval is required.
cancel
cancel jobIdCancels the job jobId.
Input Arguments
create
create cmd=command [,descr=description] [,owner=user] [,type=string] [, schedule]Creates a job.
Input Arguments
delay
delay cmd=command [,descr=description] [,owner=user] [,type=string]Creates a job for immediate execution but in the suspended state. The effect is that the job will be run once it is enabled with the resume command.
Input Arguments
delete
delete jobIdDeletes the job jobId.
Input Arguments
getnextschedule
getnextschedule jobIdPrints the next shcheduled run time for the job when the Instance of Job is scheduled for the future.
Input Arguments
reject
reject jobId rejecterRejects the job jobId.
Input Arguments
[integer] Unique number assigned to a job at creation time.
[string] Account of the person who rejected the job. Valid only if approval is required.
resume
resume jobIdResumes the job jobId so it can be scheduled.
Input Arguments
run
run cmd=command [,descr=description] [,owner=user] [,type=string]Creates a job and runs it immediately.
Input Arguments
schedule
schedule jobId scheduleReschedules the job jobId.
Input Arguments
[integer] Unique number assigned to a job at creation time.
[string] See "cancel."
suspend
suspend jobIdSuspends the job jobId so it will not be scheduled until it is resumed.
Input Arguments
