Insight II

11       Background_Job Pulldown


Much of the computational work within Biosym products is performed by background jobs that are run using the Insight II program as the user interface. Background jobs run concurrently with the interactive Insight II program; this is possible because, once started, they do not require user interaction. If you have access to more than one computer (mainframe or workstation), you may wish to run some of the background jobs on a different computer (hereafter called remote host) than the computer which is running Insight II (hereafter called local host).

In order to run the background job on a remote host, there are several general requirements:

The local host must be able to communicate statuses, submit jobs, and copy files to the remote host.

Making an executable image compatible with a remote host involves recompiling and relinking the program; this is done by Biosym for host types which the company supports.

Network Queuing System and Background Jobs

Background jobs are started up from Insight II in immediate submission mode: the job is run on the selected machine immediately upon submission. In queued mode, background jobs are submitted to a queue. The queueing mechanism pulls jobs from the queue and starts them on one of the machines available for the queue. Typically, each job is run to completion before the next job is pulled off the queue. Support for a queuing software package, known as the Network Queuing System (NQS), is now available to allow the you to submit background jobs to a queue on a local or remote machine.

Brent A. Kingsbury (Sterling Software) explains the origins of NQS in a report entitled The Network Queueing System (see the NQS documentation). "The invention of the NQS was driven by the need for a good UNIX batch and device queueing facility capable of supporting such requests in a networked environment of UNIX machines. More specifically, NQS was developed as a part of an effort aimed at tying together a diverse assortment of UNIX based machines into a useful computational complex for the National Aeronautics and Space Administration (NASA)."

It is up to you to acquire and install NQS products and deal with its support issues. The Background_Job queueing mechanism takes a properly configured NQS for granted.

NQS is available over the internet via anonymous ftp from archie sites. It is also available with a GNU license.


The Background_Job pulldown interface is the access point to a system which allows submission of background jobs on both local and remote hosts. This is a generic pulldown, which means that it appears in more than one module of the Insight II program. The commands found within this pulldown are used to set up, monitor, and kill background job execution. Refer to the System Guide for a detailed description of the mechanism used to invoke background jobs.

The machinery for using NQS is available from within the Background_Job/Setup_Background_Job command.

The Background_Job/Control_Bkgd_Job command allows interactive control of an already running background job. This command is currently available only for background jobs submitted by the DGII/DGII_Run command. Attempting to use the Control_Bkgd_Job command from any command other than DGII_Run simply results in no execution of the command.

Command Summary

Background_Job Pulldown

The Background_Job pulldown allows you to set up background jobs to run concurrently or interactively with the Insight II program. You are given the choice of whether to send background jobs to a local or remote host. This pulldown is generic and is found in many Insight II modules that run background jobs. The Background_Job pulldown contains the following commands: Setup_Bkgd_Job, Completion_Status, Kill_Bkgd_Job, and Control_Bkgd_Job.


The Background_Job/Setup_Bkgd_Job command allows you to set up the execution mode and select the host upon which to run a job. In addition, this command can be used to control the notification method for background job completion and cleanup options.


The Background_Job/Control_Bkgd_Job command allows you to coordinate running background jobs by detaching or attaching selected background jobs to the Insight II program. In addition, this command allows you to specify the interval for invoking a task specific to a particular background job for processing its output.


The Background_Job/Completion_Status command allows you to monitor and evaluate the completion status of one or all of the background jobs. In addition, this command can be used to look up the meaning of a given return status code.


The Background_Job/Kill_Bkgd_Job command is used to terminate execution of a background job that has been submitted during the current session.


Use of the Background_Job pulldown is optional. If not used, the default is to run all jobs on the local host in Cont_Insight mode of the Background_Job/Setup_Bkgd_Job command. When the Background_Job/Setup_Bkgd_Job command is used, the background job list only shows those background jobs which are run from the current module and which can be run on a remote host. If the module contains only one job, the parameter is automatically filled. The list of hosts only shows those hosts which are associated with that background job in the background_job_hosts file at your site. It is possible for you to specify a remote host that is unavailable (off line, for instance) or for which you have no login account.

Use the Background_Job/Control_Background_Job command to coordinate running background jobs by detaching or attaching selected background jobs to the Insight II program. In addition, you can use this command to specify the interval for invoking a task specific to a particular background job for processing its output.

Every background job submitted via the generic background utility is assigned a job number. This number is displayed in the information area when the job is submitted (e.g., Starting RIS background job on iris5 as job 1). You should note the job number when the job is submitted since it can be used later to check on the job's completion status, control the job while it is still running, or to kill the job.

Setting Up a Background Job

The Setup_Bkgd_Job command does not actually run the command; it simply records your host and Execution_Mode preference. The default host is local. Your selected host and Execution_Mode are used for any subsequent background job runs for the duration of the session. When you start up a new session, all background job parameters are again set to their default values.

The Execution_Mode parameter allows you to choose to run a given background job concurrently (Cont_Insight), run the job interactively (Wait_For_Job), or simply create the necessary command files to submit the job, but not actually execute them (Cmd_File_Only).

The Send_Mail parameter allows you to have the system send you an electronic mail message upon completion of the background job. This parameter is not active if Execution_Mode is set to Wait_For_Job. You may find this option useful when running long jobs where you exit the Insight II program before the job completes.

The Save_Cmd_Files parameter allows you to save the command file used to submit the background job (bkgd_job_<run_name><n>.csh). This file is otherwise deleted when the job completes. This parameter is not active when Execution_Mode is set to Cmd_File_Only.

All background jobs return a completion status. The completion status is an integer code that indicates success, failure, and/or reason for failure of the job. The status code is always displayed when you are notified that the job has completed.

If you consistently want to send background jobs to another host, you can modify your personal Insight II program start-up file to invoke Setup_Bkgd_Job for each module/background job(s) that you want to automatically assign. Note that you must first change to the module in which the background job's interface is found before using
Setup_Bkgd_Job to set a preference for that background job.

The Completion_Window parameter can be used to turn off the notification window that appears when the background job completes. The default value is on.

Support for the Network Queuing System (NQS) is now available from within the Background_Job/Setup_Bkgd_Job command.

In order for the user interface to present parameter defaults and a value-aid containing available queues, and to correctly formulate an NQS command, it is necessary to provide the user's NQS queue environment information. The Background_Job_Hosts file contains the NQS queue information, or you may enter the required information directly using the Background_Job/Setup_Bkgd_Job command.

Based on the parameter values provided in the Background_Job/Setup_Bkgd_Job command for Queued_Submission_Mode, the background job mechanism formulates a standard NQS command and starts a process to execute it. It is assumed that the NQS command constructed by the Insight II program functions on your NQS configuration.

Examining Completion Status

The Completion_Status command is used in one of three modes of operation. The One_Job option displays a brief message indicating if a specific job has completed or not. The message is displayed in the information area of the screen. Certain background jobs generate a status file containing additional information while they are running. If this additional status information is available, it is displayed to the textport. See the Implementation section of the module you are interested in for a detailed description of the information provided in the background job status file. If All_Jobs is chosen, the job number, job name, run name, status code, and job status are displayed in the textport for every job submitted during the current session. The Look_Up_
option is used to look up the meaning of a return status code.

The Report_Mode enumerated parameter is used to indicate what information you would like the command to return: status of one job, status of all jobs, or look up the meaning of a return status code from a particular background job.

The Job_Number parameter becomes active when One_Job is selected. It is used to specify a unique background job that you wish to monitor.

The Background_Job and Status parameters become active when Look_Up_Status is chosen. They are used to specify a status code that you would like to look up.

Killing a Background Job

The Kill_Bkgd_Job command is used to stop execution of a background job by killing the process in which it is running and optionally deleting its output files.

The Job_Number parameter is used to specify which background job to kill. A value-aid containing a list of all currently running background jobs is provided.

If the Save_Output parameter is toggled on, then all output files generated by the background job are saved when the job is killed. The default value of this parameter is off, in which case all output files are deleted.


As of this release, most tutorials are now available online for use with the Pilot interface. To access the online tutorial for Background_Job, click the mortarboard icon in the Insight II interface.

Then, from the Open Tutorial window, select Insight II tutorials, then the Viewer module and choose:

Lesson 9 Use of Background Job commands

You can access the Open Tutorial window at any time by clicking the Open File button in the lower left corner of the Pilot window.

For a more complete description of Pilot and its use, click the on-screen help button in the Pilot interface or refer to the Insight II User Guide.

Last updated December 17, 1998 at 04:27PM PST.
Copyright © 1998, Molecular Simulations Inc. All rights reserved.