doc/html/jobcompplugins.shtml

<!--#include virtual="header.txt"-->

<h1><a name="top">SLURM Job Completion Logging Plugin API</a></h1>

<h2> Overview</h2>
<p> This document describes SLURM job completion logging plugins and the API that defines 
them. It is intended as a resource to programmers wishing to write their own SLURM 
job completion logging plugins. This is version 0 of the API.</p>
<p>SLURM job completion logging plugins are SLURM plugins that implement the SLURM 
API for logging job information upon their completion. This may be used to log job information 
to a text file, database, etc. The plugins must conform to the SLURM Plugin API with the following 
specifications:</p>
<p><span class="commandline">const char plugin_type[]</span><br>
The major type must be &quot;jobcomp.&quot; The minor type can be any recognizable 
abbreviation for the type of scheduler. We recommend, for example:</p>
<ul>
<li><b>none</b>&#151;No job logging.</li>
<li><b>filetxt</b>&#151;Log job information to a text file.</li>
<li><b>script</b>&#151;Execute a script passing in job information in environment variables.</li>
</ul>
<p>The <span class="commandline">plugin_name</span> and 
<span class="commandline">plugin_version</span> 
symbols required by the SLURM Plugin API require no specialization for 
job completion logging support. 
Note carefully, however, the versioning discussion below.</p>
<p>The programmer is urged to study 
<span class="commandline">src/plugins/jobcomp/jobcomp_filetxt.c</span> and
<span class="commandline">src/plugins/jobcomp/jobcomp_none.c</span> 
for sample implementations of a SLURM job completion logging plugin.</p>
<p class="footer"><a href="#top">top</a></p>

<h2>Data Objects</h2>
<p>The implementation must maintain (though not necessarily directly export) an 
enumerated <span class="commandline">errno</span>  to allow SLURM to discover 
as practically as possible the reason for any failed API call. Plugin-specific enumerated 
integer values should be used when appropriate. It is desirable that these values 
be mapped into the range ESLURM_JOBCOMP_MIN and ESLURM_JOBCOMP_MAX 
as defined in <span class="commandline">slurm/slurm_errno.h</span>.
The error number should be returned by the function
<a href="#get_errno"><span class="commandline">slurm_jobcomp_get_errno()</span></a> 
and this error number can be converted to an appropriate string description using the 
<a href="#strerror"><span class="commandline">slurm_jobcomp_strerror()</span></a> 
function described below.</p>

<p>These values must not be used as return values in integer-valued functions 
in the API. The proper error return value from integer-valued functions is SLURM_ERROR. 
The implementation should endeavor to provide useful and pertinent information by 
whatever means is practical. 
Successful API calls are not required to reset any errno to a known value. However, 
the initial value of any errno, prior to any error condition arising, should be 
SLURM_SUCCESS. </p>
<p class="footer"><a href="#top">top</a></p>

<h2>API Functions</h2>
<p>The following functions must appear. Functions which are not implemented should 
be stubbed.</p>

<p class="commandline">int slurm_jobcomp_set_location (char * location);</p>
<p style="margin-left:.2in"><b>Description</b>: Specify the location to be used for job logging.</p>
<p style="margin-left:.2in"><b>Argument</b>:<span class="commandline"> location</span>&nbsp; 
&nbsp;&nbsp;(input) specification of where logging should be done. The interpretation of 
this string is at the discression of the plugin implementation.</p>
<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure, 
the plugin should return SLURM_ERROR and set the errno to an appropriate value 
to indicate the reason for failure.</p>

<p class="commandline">int slurm_jobcomp_log_record ( struct job_record *job_ptr);</p>
<p style="margin-left:.2in"><b>Description</b>: Note termation of a job with the specified 
characteristics.</p>
<p style="margin-left:.2in"><b>Argument</b>: <br>
<span class="commandline"> job_ptr</span>&nbsp;&nbsp;&nbsp;(input) Pointer to job record as defined
in <i>src/slurmctld/slurmctld.h</i></p>
<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure, 
the plugin should return SLURM_ERROR and set the errno to an appropriate value 
to indicate the reason for failure.</p>
<p class="footer"><a href="#top">top</a></p>

<a name="get_errno"><p class="commandline">int slurm_jobcomp_get_errno (void);</p></a>
<p style="margin-left:.2in"><b>Description</b>: Return the number of a job completion
logger specific error.</p>
<p style="margin-left:.2in"><b>Arguments</b>: None</p>
<p style="margin-left:.2in"><b>Returns</b>: Error number for the last failure encountered by 
the job completion logging plugin.</p>

<p class="commandline"><a name="strerror">const char *slurm_jobcomp_strerror(int errnum);</a></p>
<p style="margin-left:.2in"><b>Description</b>: Return a string description of a job completion 
logger specific error code.</p>
<p style="margin-left:.2in"><b>Arguments</b>:
<span class="commandline"> errnum</span>&nbsp; &nbsp;&nbsp;(input) a job completion logger
specific error code.</p>
<p style="margin-left:.2in"><b>Returns</b>: Pointer to string describing the error 
or NULL if no description found in this plugin.</p>
<p class="footer"><a href="#top">top</a></p>

<h2>Versioning</h2>
<p> This document describes version 0 of the SLURM job completion API. Future 
releases of SLURM may revise this API. A job completion plugin conveys its ability 
to implement a particular API version using the mechanism outlined for SLURM plugins.</p>
<p class="footer"><a href="#top">top</a></p>

<p style="text-align:center;">Last modified 10 July 2005</p>

<!--#include virtual="footer.txt"-->