.\" OpenPBS (Portable Batch System) v2.3 Software License .\" .\" Copyright (c) 1999-2000 Veridian Information Solutions, Inc. .\" All rights reserved. .\" .\" --------------------------------------------------------------------------- .\" For a license to use or redistribute the OpenPBS software under conditions .\" other than those described below, or to purchase support for this software, .\" please contact Veridian Systems, PBS Products Department ("Licensor") at: .\" .\" www.OpenPBS.org +1 650 967-4675 sales@OpenPBS.org .\" 877 902-4PBS (US toll-free) .\" --------------------------------------------------------------------------- .\" .\" This license covers use of the OpenPBS v2.3 software (the "Software") at .\" your site or location, and, for certain users, redistribution of the .\" Software to other sites and locations. Use and redistribution of .\" OpenPBS v2.3 in source and binary forms, with or without modification, .\" are permitted provided that all of the following conditions are met. .\" After December 31, 2001, only conditions 3-6 must be met: .\" .\" 1. Commercial and/or non-commercial use of the Software is permitted .\" provided a current software registration is on file at www.OpenPBS.org. .\" If use of this software contributes to a publication, product, or service .\" proper attribution must be given; see www.OpenPBS.org/credit.html .\" .\" 2. Redistribution in any form is only permitted for non-commercial, .\" non-profit purposes. There can be no charge for the Software or any .\" software incorporating the Software. Further, there can be no .\" expectation of revenue generated as a consequence of redistributing .\" the Software. .\" .\" 3. Any Redistribution of source code must retain the above copyright notice .\" and the acknowledgment contained in paragraph 6, this list of conditions .\" and the disclaimer contained in paragraph 7. .\" .\" 4. Any Redistribution in binary form must reproduce the above copyright .\" notice and the acknowledgment contained in paragraph 6, this list of .\" conditions and the disclaimer contained in paragraph 7 in the .\" documentation and/or other materials provided with the distribution. .\" .\" 5. Redistributions in any form must be accompanied by information on how to .\" obtain complete source code for the OpenPBS software and any .\" modifications and/or additions to the OpenPBS software. The source code .\" must either be included in the distribution or be available for no more .\" than the cost of distribution plus a nominal fee, and all modifications .\" and additions to the Software must be freely redistributable by any party .\" (including Licensor) without restriction. .\" .\" 6. All advertising materials mentioning features or use of the Software must .\" display the following acknowledgment: .\" .\" "This product includes software developed by NASA Ames Research Center, .\" Lawrence Livermore National Laboratory, and Veridian Information .\" Solutions, Inc. .\" Visit www.OpenPBS.org for OpenPBS software support, .\" products, and information." .\" .\" 7. DISCLAIMER OF WARRANTY .\" .\" THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ANY EXPRESS .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT .\" ARE EXPRESSLY DISCLAIMED. .\" .\" IN NO EVENT SHALL VERIDIAN CORPORATION, ITS AFFILIATED COMPANIES, OR THE .\" U.S. GOVERNMENT OR ANY OF ITS AGENCIES BE LIABLE FOR ANY DIRECT OR INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, .\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" This license will be governed by the laws of the Commonwealth of Virginia, .\" without reference to its choice of law rules. .if \n(Pb .ig Ig .TH pbs_submit 3B "" Local PBS .so ../ers/ers.macros .Ig .SH NAME pbs_submit \- submit a pbs batch job .SH SYNOPSIS #include .br #include .sp .ft 3 .nf char *pbs_submit(\^int\ connect, struct\ attropl\ *attrib, char\ *script, char\ *destination, char\ *extend) .fi .ft 1 .SH DESCRIPTION Issue a batch request to submit a new batch job. .LP A .I "Queue Job" batch request is generated and sent to the server over the connection specified by .Ar connect which is the return value of \fBpbs_connect\fP(). The job will be submitted to the queue specified by .Ar destination . .LP The parameter, .Ar attrib , is a list of .I attropl structures which is defined in pbs_ifl.h as: .sp .Ty .nf struct attrl { char *name; char *resource; char *value; struct attrl *next; enum batch_op op; }; .fi .sp .ft 1 The .Ar attrib list is terminated by the first entry where .Ty next is a null pointer. .LP The .Ty name member points to a string which is the name of the attribute. The .Ty value member points to a string which is the value of the attribute. The attribute names are defined in pbs_ifl.h: .br .RS .IP #define\ ATTR_a\ "Execution_Time" Defines the job's execution time. .IP #define\ ATTR_A\ "Account_Name" Defines the account string. .IP #define\ ATTR_c\ "Checkpoint" Defines the checkpoint interval. .IP #define\ ATTR_e\ "Error_Path" Defines the path name for the standard error of the job. .IP #define\ ATTR_g\ "Group_List" Defines the list of group names under which the job may execute. .IP #define\ ATTR_h\ "Hold_Types" Defines the hold types, the only allowable value string is .Ty \&"u" . .IP #define\ ATTR_j\ "Join_Paths" Defines whether standard error and standard output are joined (merged). .IP #define\ ATTR_k\ "Keep_Files" Defines which output of the job is kept on the execution host. .IP #define\ ATTR_l\ "Resource_List" Defines a resource required by the job. .IP #define\ ATTR_m\ "Mail_Points" Defines the points at which the server will send mail about the job. .IP #define\ ATTR_M\ "Mail_Users" Defines the list of users who would receive mail about the job. .IP #define\ ATTR_N\ "Job_Name" Defines the job name. .IP #define\ ATTR_o\ "Output_Path" Defines the path name for the standard output of the job. .IP #define\ ATTR_p\ "Priority" Defines the priority of the job. .IP #define\ ATTR_r\ "Rerunable" Defines the rerunable flag. .IP #define\ ATTR_S\ "Shell_Path_List" Defines the path to the shell which will interpret the job script. .IP #define\ ATTR_t\ "job_array_request" Requests specific array IDs. Makes this submission a job array submit. .IP #define\ ATTR_u\ "User_List" Defines the list of user names under which the job may execute. .IP #define\ ATTR_v\ "Variable_List" Defines the list of additional environment variables which are exported to the job. .IP #define\ ATTR_depend\ "depend" Defines the inter\-job dependencies. .IP #define\ ATTR_stagein\ "stagein" Defines the list of files to be staged in prior to job execution. .IP #define\ ATTR_stageout\ "stageout" Defines the list of files to be staged out after job execution. .RE .LP If an attribute is not named in the .Ar attrib array, the default action will be taken. It will either be assigned the default value or will not be passed with the job. The action depends on the attribute. If .Ar attrib itself is a null pointer, then the default action will be taken for each attribute. .LP Associated with an attribute of type ATTR_l (the letter ell) is a resource name indicated by .Ty resource in the .I attrl structure. All other attribute types should have a pointer to a null string for .Ty resource . .LP The .Ty op member is forced to a value of .Ty SET by pbs_submit(). .LP The parameter, .Ar script , is the path name to the job script. If the path name is relative, it will be expanded to the processes current working directory. If .Ar script is a null pointer or the path name pointed to is specified as the null string, no script is passed with the job. .LP The .Ar destination parameter specifies the destination for the job. It is specified as: .Ty [queue] If .Ar destination is the null string or the queue is not specified, the destination will be the default queue at the connected server. .LP The parameter, .Ar extend , is reserved for implementation defined extensions. .if !\n(Pb .ig Ig It is not currently used by this function. .Ig .LP The return value is a character string which is the .Ar job_identifier assigned to the job by the server. The space for the .Ar job_identifier string is allocated by \fBpbs_submit\fP() and should be released via a call to \fBfree\fP() by the user when no longer needed. .SH "SEE ALSO" qsub(1B) and pbs_connect(3B) .SH DIAGNOSTICS When the batch request generated by pbs_submit() function has been completed successfully by a batch server, the routine will return a pointer to a character string which is the job identifier of the submitted batch job. Otherwise, a null pointer is returned and the error code is set in pbs_error. \" turn off any extra indent left by the Sh macro .RE