Knowledge Center Contents Previous Next |
lsb_submit()
Submits or restarts a job in the batch system.
DESCRIPTION
lsb_submit() submits or restarts a job in the batch system according to the jobSubReq specification.
SYNOPSIS
#include <lsf/lsbatch.h> LS_LONG_INT lsb_submit (struct submit *jobSubReq, struct submitReply *jobSubReply) struct submit { int options; int options2; char *jobName; char *queue; int numAskedHosts; char **askedHosts; char *resReq; int rLimits[LSF_RLIM_NLIMITS]; char *hostSpec; int numProcessors; char *dependCond; char *timeEvent; time_t beginTime; time_t termTime; int sigValue; char *inFile; char *outFile; char *errFile; char *command; char *newCommand; time_t chkpntPeriod; char *chkpntDir; int nxf; struct xFile *xf; char *preExecCmd; char *mailUser; int delOptions; int delOptions2; char *projectName; int maxNumProcessors; char *loginShell; char *userGroup; char *exceptList; int userPriority; char *rsvId; char *jobGroup; char *sla; char *extsched; int warningTimePeriod; char *warningAction; char *licenseProject; int options3; int delOptions3; char *app; int jsdlFlag; char *jsdlDoc; void *correlator; char *apsString; char *postExecCmd; char *cwd; int runtimeEstimation; char *requeueEValues; int initChkpntPeriod; int migThreshold; char *notifyCmd; }; struct submitReply { char *queue; LS_LONG_INT badJobId; char *badJobName; int badReqIndx; };PARAMETERS
jobSubReq
Describes the requirements for job submission to the batch system. A job that does not meet these requirements is not submitted to the batch system and an error is returned.
jobSubReply
Describes the results of the job submission to the batch system.
structure jobSubReq
The submit structure contains the following fields:
options
<lsf/lsbatch.h> defines the following flags constructed from bits. These flags correspond to some of the options of the bsub command line. Use the bitwise OR to set more than one flag.
SUB_JOB_NAME
Flag to indicate jobName parameter has data. Equivalent to bsub -J command line option existence.
SUB_QUEUE
Flag to indicate queue parameter has data. Equivalent to bsub -q command line option existence.
SUB_HOST
Flat to indicate numAskedHosts parameter has data. Equivalent to bsub -m command line option existence.
SUB_IN_FILE
Flag to indicate inFile parameter has data. Equivalent to bsub -i command line option existence.
SUB_OUT_FILE
Flag to indicate outFile parameter has data. Equivalent to bsub -o command line option existence.
SUB_ERR_FILE
Flag to indicate errFile parameter has data. Equivalent to bsub -e command line option existence.
SUB_EXCLUSIVE
Flag to indicate execution of a job on a host by itself requested. Equivalent to bsub -x command line option existence.
SUB_NOTIFY_END
Flag to indicate whether to send mail to the user when the job finishes. Equivalent to bsub -N command line option existence.
SUB_NOTIFY_BEGIN
Flag to indicate whether to send mail to the user when the job is dispatched. Equivalent to bsub -B command line option existence.
SUB_USER_GROUP
Flag to indicate userGroup name parameter has data. Equivalent to bsub -G command line option existence.
SUB_CHKPNT_PERIOD
Flag to indicatechkpntPeriod parameter has data . Equivalent to bsub -k command line option existence.
SUB_CHKPNT_DIR
Flag to indicate chkpntDir parameter has data. Equivalent to bsub -k command qwreqwqwline option existence.
SUB_CHKPNTABLE
Indicates the job is checkpointable. Equivalent to bsub -k command line option.
SUB_RESTART_FORCE
Flag to indicate whether to forces the job to restart even if non-restartable conditions exist. These conditions are operating system specific. Equivalent to brestart() -f command line option existence.
SUB_RESTART
Flag to indicate restart of a checkpointed job. Only jobs that have been successfully checkpointed can be restarted. Jobs are re-submitted and assigned a new job ID. By default, jobs are restarted with the same output file, file transfer specifications, job name, window signal value, checkpoint directory and period, and rerun options as the original job. To restart a job on another host, both hosts must be binary compatible, run the same OS version, have access to the executable, have access to all open files (LSF must locate them with an absolute path name), and have access to the checkpoint directory. Equivalent to bsub -k command line option existence.
SUB_RERUNNABLE
Indicates the job is re-runnable. If the execution host of the job is considered down, the batch system will re-queue this job in the same job queue, and re-run it from the beginning when a suitable host is found. Everything will be as if it were submitted as a new job, and a new job ID will be assigned. The user who submitted the failed job will receive a mail notice of the job failure, requeueing of the job, and the new job ID.
For a job that was checkpointed before the execution host went down, the job will be restarted from the last checkpoint. Equivalent to bsub -r command line option existence.
SUB_WINDOW_SIG
Flag to indicate sigValue parameter has data. Sends a signal as the queue window closes.
SUB_HOST_SPEC
Flag to indicate hostSpec parameter has data.
SUB_DEPEND_COND
Flag to indicate dependCond parameter has data. Equivalent to bsub -w command line option existence.
SUB_RES_REQ
Flag to indicate resReq parameter has data. Equivalent to bsub -R command line option existence.
SUB_OTHER_FILES
Flag to indicate nxf parameter and structure xf have data.
SUB_PRE_EXEC
Flag to indicate preExecCmd parameter has data. Equivalent to bsub -E command line option existence.
SUB_LOGIN_SHELL
Equivalent to bsub -L command line option existence.
SUB_MAIL_USER
Flag to indicate mailUser parameter has data.
SUB_MODIFY
Flag to indicate newCommand parameter has data. Equivalent to bmod bsub_options existence.
SUB_MODIFY_ONCE
Flag to indicate modify option once.
SUB_PROJECT_NAME
Flag to indicate ProjectName parameter has data . Equivalent to bsub -P command line option existence.
SUB_INTERACTIVE
Indicates that the job is submitted as a batch interactive job. When this flag is given, lsb_submit() does not return unless an error occurs during the submission process. When the job is started, the user can interact with the job's standard input and output via the terminal. See the -I option in bsub for the description of a batch interactive job. Unless the SUB_PTY flag is specified, the job will run without a pseudo-terminal. Equivalent to bsub -I command line option.
SUB3_INTERACTIVE_SSH
Protects the sessions of interactive jobs with SSH encryption. Equivalent to bsub -IS|-ISp|-ISs.
SUB3_XJOB_SSH
Protect the sessions of interactive x-window job with SSH encryption. Equivalent to bsub -IX.
SUB_PTY
Requests pseudo-terminal support for a job submitted with the SUB_INTERACTIVE flag. This flag is ignored if SUB_INTERACTIVE is not specified. A pseudo-terminal is required to run some applications (e.g., vi). Equivalent to bsub -Ip command line option.
SUB_PTY_SHELL
Requests pseudo-terminal shell mode support for a job submitted with the SUB_INTERACTIVE and SUB_PTY flags. This flag is ignored if SUB_INTERACTIVE and SUB_PTY are not specified. This flag should be specified for submitting interactive shells, or applications which redefine the ctrl-C and ctrl-Z keys (e.g., jove). Equivalent to bsub -Is command line option.
SUB_EXCEPT
Exception handler for job.
SUB_TIME_EVENT
Specifies time_event.
options2
Extended bitwise inclusive OR of some of the following flags:
SUB2_HOLD
Hold the job after it is submitted. The job will be in PSUSP status. Equivalent to bsub -H command line option.
SUB2_MODIFY_CMD
New cmd for bmod.
SUB2_BSUB_BLOCK
Submit a job in a synchronous mode so that submission does not return until the job terminates. Note once this flag is set, the lsb_submit() will never return if the job is accepted by LSF. Programs that wishes to know the status of the submission needs to fork, with the child process invoking the API call in the blocking mode and the parent process wait on the child process (see wait() for details.
SUB2_HOST_NT
Submit from NT.
SUB2_HOST_UX
Submit fom UNIX.
SUB2_QUEUE_CHKPNT
Submit to a chkpntable queue.
SUB2_QUEUE_RERUNNABLE
Submit to a rerunnble queue.
SUB2_IN_FILE_SPOOL
Spool job command.
SUB2_JOB_CMD_SPOOL
Inputs the specified file with spooling.
SUB2_JOB_PRIORTY
Submits job with priority.
SUB2_USE_DEF_PROCLIMIT
Job submitted wihtout -n, use queue's default proclimit.
SUB2_MODIFY_RUN_JOB
bmod -c/-M/-W/-o/-e
SUB2_MODIFY_PEND_JOB
bmod options only to pending jobs.
SUB2_WARNING_TIME_PERIOD
Job action warning time. Equivalent to bsub or bmod -wt.
SUB2_WARNING_ACTION
Job action to be taken before a job control action occurs. Equivalent to bsub or bmod -wa.
SUB2_USE_RSV
Use an advance reservation created with the brsvadd command. Equivalent to bsub -U.
SUB2_TSJOB
Windows Terminal Services job
SUB2_LSF2TP Deprecated
Parameter is deprecated
SUB2_JOB_GROUP
Submit into a job group
SUB2_SLA
Submit into a service class
SUB2_EXTSCHED
Submit with -extsched options
SUB2_LICENSE_PROJECT
License Scheduler project
SUB2_OVERWRITE_OUT_FILE
Overwrite the standard output of the job. Equivalent to bsub -oo.
SUB2_OVERWRITE_ERR_FILE
Overwrites the standard error output of the job. Equivalent to bsub -eo.
SUB3_RUNTIME_ESTIMATION
Use in conjunction with SUB3_RUNTIME_ESTIMATION_ACC and SUB3_RUNTIME_ESTIMATION_PERC.
SUB3_RUNTIME_ESTIMATION_ACC
Runtime estimate that is the accumulated run time plus the runtime estimate. Equivalent to bmod -We+. Use in conjunction with SUB3_RUNTIME_ESTIMATION.
SUB3_RUNTIME_ESTIMATION_PERC
Runtime estimate in percentage of completion. Equivalent to bmod -Wep. Two digits after the decimal point are suported. The highest eight bits of runtimeEstimation in the submit structure are used for the integer; the remaining bits are used for the fraction. Use in conjunction with SUB3_RUNTIME_ESTIMATION.
jobName
The job name. If jobName is NULL, command is used as the job name.
queue
Submit the job to this queue. If queue is NULL, submit the job to a system default queue.
numAskedHosts
The number of invoker specified candidate hosts for running the job. If numAskedHosts is 0, all qualified hosts will be considered.
askedHosts
The array of names of invoker specified candidate hosts. The number of hosts is given by numAskedHosts.
resReq
The resource requirements of the job. If resReq is NULL, the batch system will try to obtain resource requirements for command from the remote task lists (see ls_task()). If the task does not appear in the remote task lists, then the default resource requirement is to run on host() of the same type.
rLimits[LSF_RLIM_NLIMITS]
Limits on the consumption of system resources by all processes belonging to this job. See getrlimit() for details. If an element of the array is -1, there is no limit for that resource. For the constants used to index the array, see lsb_queueinfo().
hostSpec
Specify the host model to use for scaling rLimits[LSF_RLIMIT_CPU] and rLimits[LSF_RLIMIT_RUN]. (See lsb_queueinfo()). If hostSpec is NULL, the local host is assumed.
numProcessors
The initial number of processors needed by a (parallel) job. The default is 1.
timeEvent
Time event string.
dependCond
The job dependency condition.
beginTime
Dispatch the job on or after beginTime, where beginTime is the number of seconds since 00:00:00 GMT, Jan. 1, 1970 (See time(), ctime()). If beginTime is 0, start the job as soon as possible.
termTime
The job termination deadline. If the job is still running at termTime, it will be sent a USR2 signal. If the job does not terminate within 10 minutes after being sent this signal, it will be ed. termTime has the same representation as beginTime. If termTime is 0, allow the job to run until it reaches a resource limit.
sigValue
Applies to jobs submitted to a queue that has a run window (See lsb_queueinfo()). Send signal sigValue to the job 10 minutes before the run window is going to close. This allows the job to clean up or checkpoint itself, if desired. If the job does not terminate 10 minutes after being sent this signal, it will be suspended.
inFile
The path name of the job's standard input file. If inFile is NULL, use /dev/null as the default.
outFile
The path name of the job's standard output file. If outFile is NULL, the job's output will be mailed to the submitter.
errFile
The path name of the job's standard error output file. If errFile is NULL, the standard error output will be merged with the standard output of the job.
command
The command line of the job.
newCommand
New command line for bmod.
chkpntPeriod
The job is checkpointable with a period of chkpntPeriod seconds. The value 0 disables periodic checkpointing.
chkpntDir
The directory where the chk directory for this job checkpoint files will be created. When a job is checkpointed, its checkpoint files are placed in chkpntDir/chk. chkpntDir can be a relative or absolute path name.
nxf
The number of files to transfer.
xf
The array of file transfer specifications. (The xFile structure is defined in <lsf/lsbatch.h>.)
preExecCmd
The job pre-execution command.
mailUser
The user that results are mailed to.
delOptions
Delete options in options field .
delOptions2
Extended delete options in options2 field .
projectName
The name of the project the job will be charged to.
maxNumProcessors
Maximum number of processors the required to run the job.
loginShell
Specified login shell used to initialize the execution environment for the job (see the -L option of bsub).
userGroup
The name of the LSF user group (see lsb.users) to which the job will belong. (see the -G option of bsub)
exceptList
Passes the exception handlers to mbatchd during a job. (see the -X option of bsub).
Specifies execption handlers that tell the system how to respond to an exceptional condition for a job. An action is performed when any one of the following exceptions is detected:
- missched - A job has not been scheduled within the time event specified in the -T option.
- overrun - A job did not finish in its maximum time (maxtime).
- underrun - A job finished before it reaches its minimum running time (mintime).
- abend - A job terminated abnormally. Test an exit code that is one value, two or more comma separated values, or a range of values (two values separated by a `-' to indivate a range). If the job exits with one of the tested values, the abend condition is detected.
- startfail - A job did not start due to insufficient system resources.
- cantrun - A job did not start because a dependency condition (see the -w option of bsub) is invalid, or a startfail exception occurs 20 times in a row and the job is suspended. For jobs submitted with a time event (see the -T option of bsub), the cantrun exception condition can be detected once in each time event.
- hostfail - The host running a job becomes unavailable.
When one or more of the above exceptions is detected, you can specify one of the following actions to be taken:
- alarm - Triggers an alarm incident (see balarms(1)). The alarm can be viewed, acknowledged and resolved.
- setexcept - Causes the exception event event_name to be set. Other jobs waiting on the exception event event_name specified through the -w option can be triggered. event_name is an arbitrary string.
- rerun - Causes the job to be rescheduled for execution. Any dependencies associated with the job must be satisfied before re-execution takes place. The rerun action can only be specified for the abend and hostfail exception conditions. The startfail exception condition automatically triggers the rerun action.
- kill - Causes the current execution of the job to be terminated. This action can only be specified for the overrun exception condition.
userPriority
User priority for fairshare scheduling.
rsvId
Reservation ID for advance reservation.
jobGroup
Job group under which the job runs.
sla
SLA under which the job runs.
extsched
External scheduler options.
warningTimePeriod
warning time period in seconds. -1 if unspecified.
warningAction
warning action: SIGNAL, or CHKPNT, or command. NULL if unspecified.
licenseProject
License Scheduler project name.
options3
Extended bitwise inclusive OR of options flags:
SUB3_APP
Application profile name. Equivalent to bsub -app.
SUB3_APP_RERUNNABLE
Job rerunable because of application profile
SUB3_ABSOLUTE_PRIORITY
Job modified with absolute priority. . Equivalent to bmod -aps.
SUB3_DEFAULT_JOBGROUP
Submit into a default job group. Equivalent to bsub -g.
SUB3_POST_EXEC
Run the specified post-execution command on the execution host after the job finishes. Equivalent to bsub -Ep.
SUB3_USER_SHELL_LIMITS
Pass user shell limits to execution host. Equivalent to bsub -ul.
SUB3_CWD
Current working directory specified on on the command line with bsub -cwd
SUB3_RUNTIME_ESTIMATION
Runtime estimate. Equivalent to bsub -We.
SUB3_NOT_RERUNNABLE
Job is not rerunnable. Equivalent to bsub -rn.
SUB3_JOB_REQUEUE
Job level requeue exit values.
SUB3_INIT_CHKPNT_PERIOD
Initial checkpoint period. Equivalent to bsub -k initial_checkpoint_period.
SUB3_MIG_THRESHOLD
Job migration threshold. Equivalent to bsub -mig migration_threshold.
SUB3_APP_CHKPNT_DIR
Checkpoint dir was set by application profile.
SUB3_BSUB_CHK_RESREQ
Bsub only checks the reqreq syntax.
SUB3_BSUB_CHK_RESREQ
Value of BSUB_CHK_RESREQ environment variable, used for select section resource requirement string syntax checking with bsub -R.
SUB3_AUTO_RESIZE
SUB3_RESIZE_NOTIFY_CMD
delOptions3
Extended delete options in options3 field.
app
Application profile under which the job runs.
jsdlFlag
-1 if no -jsdl and -jsdl_strict options:
- 0 -jsdl_strict option
- 1 -jsdl option
jsdlDoc
JSDL file name.
apsString
Absolute priority scheduling string set by administrators to denote static system APS value or ADMIN factor APS value. This field is ignored by lsb_submit().
postExecCmd
Post-execution commands specified by -Ep option of bsub and bmod.
cwd
Current working directory specified by -cwd option of bsub and bmod.
runtimeEstimation
Runtime estimate specified by -We option of bsub and bmod.
requeueEValues
Job-level requeue exit values specified by -Q option of bsub and bmod.
initChkpntPeriod
Initial checkpoint period specified by -k option of bsub and bmod.
migThreshold
Job migration threshold specified by -mig option of bsub and bmod.
notifyCmd
Job resize notification command to be invoked on the first execution host when a resize request has been satisfied.
submitReply structure
The submitReply structure contains the following fields:
queue
The queue the job was submitted to.
badJobId
dependCond contained badJobId but badJobId does not exist in the system.
badJobName
dependCond contained badJobName but badJobName does not exist in the system.
If the environment variable BSUB_CHK_RESREQ is set, the value of lsberrno is either LSBE_RESREQ_OK or LSBE_RESREQ_ERR, depending on the result of resource requirement string checking. The badJobName field contains the detailed error message.
badReqIndx
If lsberrno is LSBE_BAD_HOST, (**askedHosts)[badReqIndx] is not a host known to the system. If lsberrno is LSBE_QUEUE_HOST, (**askedHosts)[badReqIndx] is not a host used by the specified queue. If lsberrno is LSBE_OVER_LIMIT, (*rLimits)[badReqIndx] exceeds the queue's limit for the resource.
RETURN VALUES
character:job ID
The function was successful, and sets the queue field of jobSubReply to the name of the queue that the job was submitted to.
If the environment variable BSUB_CHK_RESREQ is set, lsb_submit() returns a jobid less than zero (0).
integer:-1
Function failed.
ERRORS
If the function fails, lsberrno is set to indicate the error.
If the environment variable BSUB_CHK_RESREQ is set, the value of lsberrno is either LSBE_RESREQ_OK or LSBE_RESREQ_ERR, depending on the result of resource requirement string checking. The badJobName field in the submitReply structure contains the detailed error message.
SEE ALSO
Related API
lsb_modify() - Modifies a submitted job's parameters
ls_info() - Returns a pointer to an lsInfo structure
lsb_queueinfo() - Returns information about batch queues
Equivalent line command
bsub
brestart
Files
${LSF_ENVDIR/etc}/lsf.conf
Platform Computing Inc.
www.platform.com |
Knowledge Center Contents Previous Next |