Knowledge Center         Contents    Previous  Next    
Platform Computing Corp.

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:

When one or more of the above exceptions is detected, you can specify one of the following actions to be taken:

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:

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