| <!--#include virtual="header.txt"--> |
| |
| <h1><a name="top">SLURM Accounting Storage Plugin API</a></h1> |
| |
| <h2> Overview</h2> |
| <p> This document describes SLURM Accounting Storage plugins and the API that |
| defines them. It is intended as a resource to programmers wishing to write |
| their own SLURM Job Accounting Storage plugins. This is version 1 of the API. |
| |
| <p>SLURM Accounting Storage plugins must conform to the |
| SLURM Plugin API with the following specifications: |
| |
| <p><span class="commandline">const char |
| plugin_name[]="<i>full text name</i>"</span> |
| <p style="margin-left:.2in"> |
| A free-formatted ASCII text string that identifies the plugin. |
| |
| <p><span class="commandline">const char |
| plugin_type[]="<i>major/minor</i>"</span><br> |
| <p style="margin-left:.2in"> |
| The major type must be "accounting_storage." |
| The minor type can be any suitable name |
| for the type of accounting package. We currently use |
| <ul> |
| <li><b>filetxt</b>—Information written to a text file. |
| <li><b>mysql</b>— Store information in a mysql database. |
| <li><b>pgsql</b>— Store information in a postgresql database. |
| <li><b>none</b>— Information is not stored anywhere. |
| </ul> |
| <p>The programmer is urged to study |
| <span class="commandline">src/plugins/accounting_storage/mysql</span> |
| for a sample implementation of a SLURM Accounting Storage plugin. |
| <p> The Accounting Storage plugin was written to be a interface |
| to storage data collected by the Job Accounting Gather plugin. When |
| adding a new database you may want to add common functions in a common |
| file in the src/database dir. Refer to src/database/mysql_common.c|.h for an |
| example so other plugins can also use that database type to write out |
| information. |
| <p class="footer"><a href="#top">top</a> |
| |
| |
| <h2>API Functions</h2> |
| |
| The Job Accounting Storage API uses hooks in the slurmctld. |
| |
| <p>All of the following functions are required. Functions which are not |
| implemented must be stubbed. |
| |
| <h4>Functions called by the accounting_storage plugin</h4> |
| |
| <p class="commandline">void *acct_storage_p_get_connection(bool |
| make_agent, int conn_num, bool rollback, char *location) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| acct_storage_p_get_connection() is called to get a connection to the |
| storage medium. acct_storage_p_close_connection() should be used to |
| free the pointer returned by this function. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">make_agent</span> (input) to make an agent |
| thread of not. This is primarily used in the slurmdbd plugin.<br> |
| <span class="commandline">conn_num</span> (input) connection number to |
| the plugin. In many cases you should plan on multiple simultaneous |
| connections to the plugin. This number is useful since the debug |
| messages can print this out to determine which connection the message |
| is from.<br> |
| <span class="commandline">rollback</span> (input) Allow rollback to |
| happen or not (in use with databases that support rollback).<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">void *</span> which is an opaque structure |
| used inside the plugin to connection to the storage type on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline">int acct_storage_p_close_connection(void **db_conn) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| acct_storage_p_close_connection() is called at the end of the program that has |
| called acct_storage_p_get_connection this function closes the connection to |
| the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input/output) connection to |
| the storage type, all memory will be freed inside this function and |
| set to NULL. |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline">int acct_storage_p_commit(void *db_conn, bool commit) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| acct_storage_p_commit() is called at a point where you would either |
| want changes to storage be committed or rolled back. This function |
| should also send appropriate update messages to the various slurmctlds. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">commit</span> (input) true for commit, false |
| to rollback if connection was set up to rollback. <br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_add_users(void *db_conn, uint32_t uid, List user_list) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to add users to the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">user_list</span> (input) list of |
| acct_user_rec_t *'s containing information about the users being added.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_add_coord(void *db_conn, uint32_t uid, List acct_list, acct_user_cond_t *user_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to link specified users to the specified accounts as coordinators. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">acct_list</span> (input) list of |
| acct_account_rec_t *'s containing information about the accounts to |
| add the coordinators to. <br> |
| <span class="commandline">user_cond</span> (input) contain a list of |
| users to add to be coordinators of the acct_list.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_add_accts(void *db_conn, uint32_t uid, List acct_list) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to add accounts to the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function. <br> |
| <span class="commandline">acct_list</span> (input) list of |
| acct_account_rec_t *'s containing information about the accounts to add. <br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_add_clusters(void *db_conn, uint32_t uid, List cluster_list) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to add clusters to the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">cluster_list</span> (input) list of |
| acct_cluster_rec_t *'s containing information about the clusters to add. <br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_add_associations(void *db_conn, uint32_t uid, List association_list) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to add associations to the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">association_list</span> (input) list of |
| acct_association_rec_t *'s containing information about the |
| associations to add. <br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_add_qos(void *db_conn, uint32_t uid, List qos_list) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to add QOS' to the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">qos_list</span> (input) list of |
| acct_qos_rec_t *'s containing information about the qos to add. <br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_add_wckeys(void *db_conn, uint32_t uid, List wckey_list) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to add wckeys to the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">wckey_list</span> (input) list of |
| acct_wckey_rec_t *'s containing information about the wckeys to add. <br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_add_reservation(void *db_conn, |
| acct_reservation_rec_t *resv) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to add reservations to the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">resv</span> (input) Reservation to be added. <br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_modify_users(void *db_conn, uint32_t uid, |
| acct_user_cond_t *user_cond, acct_user_rec_t *user) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to modify existing users in the storage type. The condition |
| could include very vague information about the user, so this |
| function should be robust in the ability to give everything the user |
| is asking for. This is the reason a list of modified users is |
| returned so the caller knows what has been changed, sometimes by mistake. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">user_cond</span> (input) conditional about |
| which users need to change. User names or ids should not need to be stated.<br> |
| <span class="commandline">user</span> (input) what the changes |
| should be on the users identified by the conditional.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of users |
| modified on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_modify_accounts(void *db_conn, uint32_t uid, |
| acct_account_cond_t *acct_cond, acct_account_rec_t *acct) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to modify existing accounts in the storage type. The condition |
| could include very vague information about the account, so this |
| function should be robust in the ability to give everything the account |
| is asking for. This is the reason a list of modified accounts is |
| returned so the caller knows what has been changed, sometimes by mistake. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">acct_cond</span> (input) conditional about |
| which accounts need to change. Account names should not need to be stated.<br> |
| <span class="commandline">acct</span> (input) what the changes |
| should be on the accounts identified by the conditional.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of users |
| modified on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_modify_clusters(void *db_conn, uint32_t uid, |
| acct_cluster_cond_t *cluster_cond, acct_cluster_rec_t *cluster) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to modify existing clusters in the storage type. The condition |
| could include very vague information about the cluster, so this |
| function should be robust in the ability to give everything the cluster |
| is asking for. This is the reason a list of modified clusters is |
| returned so the caller knows what has been changed, sometimes by mistake. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">cluster_cond</span> (input) conditional about |
| which clusters need to change. Cluster names should not need to be stated.<br> |
| <span class="commandline">cluster</span> (input) what the changes |
| should be on the clusters identified by the conditional.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of clusters |
| modified on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_modify_associations(void *db_conn, uint32_t uid, |
| acct_association_cond_t *assoc_cond, acct_association_rec_t *assoc) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to modify existing associations in the storage type. The condition |
| could include very vague information about the association, so this |
| function should be robust in the ability to give everything the association |
| is asking for. This is the reason a list of modified associations is |
| returned so the caller knows what has been changed, sometimes by mistake. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">assoc_cond</span> (input) conditional about |
| which associations need to change. Association ids should not need to be stated.<br> |
| <span class="commandline">assoc</span> (input) what the changes |
| should be on the associations identified by the conditional.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of associations |
| modified on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_modify_qos(void *db_conn, uint32_t uid, |
| acct_qos_cond_t *qos_cond, acct_qos_rec_t *qos) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to modify existing qos in the storage type. The condition |
| could include very vague information about the qos, so this |
| function should be robust in the ability to give everything the qos |
| is asking for. This is the reason a list of modified qos is |
| returned so the caller knows what has been changed, sometimes by mistake. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">qos_cond</span> (input) conditional about |
| which qos need to change. Qos names should not need to be stated.<br> |
| <span class="commandline">qos</span> (input) what the changes |
| should be on the qos identified by the conditional.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of qos |
| modified on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_modify_wckeys(void *db_conn, uint32_t uid, |
| acct_wckey_cond_t *wckey_cond, acct_wckey_rec_t *wckey) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to modify existing wckeys in the storage type. The condition |
| could include very vague information about the wckeys, so this |
| function should be robust in the ability to give everything the wckey |
| is asking for. This is the reason a list of modified wckey is |
| returned so the caller knows what has been changed, sometimes by mistake. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">wckey_cond</span> (input) conditional about |
| which wckeys need to change. Wckey names should not need to be stated.<br> |
| <span class="commandline">wckey</span> (input) what the changes |
| should be on the wckey identified by the conditional.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of wckeys |
| modified on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_modify_reservation(void *db_conn, |
| acct_reservation_rec_t *resv) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to modify reservations in the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">resv</span> (input) Reservation to be |
| modified (id) must be set in the structure. <br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_remove_users(void *db_conn, uint32_t uid, |
| acct_user_cond_t *user_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to remove users from the storage type. This will remove all |
| associations. Must check to make sure all running jobs are finished |
| before this is allowed to execute. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">user_cond</span> (input) conditional about |
| which users to be removed. User names or ids should not need to be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of users |
| removed on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_remove_coord(void *db_conn, uint32_t uid, |
| List acct_list, acct_user_cond_t *user_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to remove coordinators from the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">acct_list</span> (input) list of accounts |
| associated with the users.<br> |
| <span class="commandline">user_cond</span> (input) conditional about |
| which users to be removed as coordinators. User names or ids should be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of users |
| removed as coordinators on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_remove_accounts(void *db_conn, uint32_t uid, |
| acct_account_cond_t *acct_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to remove accounts from the storage type. This will remove all |
| associations from these accounts. You need to make sure no jobs are |
| running with any association that is to be removed. If any of these |
| accounts are default accounts for users that must also change before |
| an account can be removed. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">acct_cond</span> (input) conditional about |
| which accounts to be removed. Account names should not need to be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of accounts |
| removed on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_remove_clusters(void *db_conn, uint32_t uid, |
| acct_cluster_cond_t *cluster_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to remove clusters from the storage type. This will remove all |
| associations from these clusters. You need to make sure no jobs are |
| running with any association that is to be removed. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">cluster_cond</span> (input) conditional about |
| which clusters to be removed. Cluster names should not need to be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of clusters |
| removed on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_remove_associations(void *db_conn, uint32_t uid, |
| acct_association_cond_t *assoc_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to remove associations from the storage type. You need to make |
| sure no jobs are running with any association that is to be removed. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">assoc_cond</span> (input) conditional about |
| which associations to be removed. Association ids should not need to be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of associations |
| removed on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_remove_qos(void *db_conn, uint32_t uid, |
| acct_qos_cond_t *qos_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to remove qos from the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">qos_cond</span> (input) conditional about |
| which qos to be removed. Qos names should not need to be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of qos |
| removed on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_remove_wckeys(void *db_conn, uint32_t uid, |
| acct_wckey_cond_t *wckey_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to remove wckeys from the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">wckey_cond</span> (input) conditional about |
| which wckeys to be removed. Wckey names should not need to be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing names of wckeys |
| removed on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_remove_reservation(void *db_conn, |
| acct_reservation_rec_t *resv) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Called to remove reservations in the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">resv</span> (input) Reservation to be |
| removed (id) must be set in the structure. <br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_get_users(void *db_conn, uint32_t uid, |
| acct_user_cond_t *user_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Get a list of acct_user_rec_t *'s based on the conditional sent. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the |
| function.<br> |
| <span class="commandline">user_cond</span> (input) conditional about |
| which users are to be returned. User names or ids should not need to |
| be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing acct_user_rec_t *'s |
| on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_get_accts(void *db_conn, uint32_t uid, |
| acct_account_cond_t *acct_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Get a list of acct_account_rec_t *'s based on the conditional sent. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the |
| function.<br> |
| <span class="commandline">acct_cond</span> (input) conditional about |
| which accounts are to be returned. Account names should not need to |
| be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing acct_account_rec_t *'s |
| on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_get_clusters(void *db_conn, uint32_t uid, |
| acct_cluster_cond_t *cluster_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Get a list of acct_cluster_rec_t *'s based on the conditional sent. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the |
| function.<br> |
| <span class="commandline">cluster_cond</span> (input) conditional about |
| which clusters are to be returned. Cluster names should not need to |
| be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing acct_cluster_rec_t *'s |
| on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_get_associations(void *db_conn, uint32_t uid, |
| acct_association_cond_t *assoc_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Get a list of acct_association_rec_t *'s based on the conditional sent. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the |
| function.<br> |
| <span class="commandline">assoc_cond</span> (input) conditional about |
| which associations are to be returned. Association names should not need to |
| be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing acct_association_rec_t *'s |
| on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_get_qos(void *db_conn, uint32_t uid, |
| acct_qos_cond_t *qos_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Get a list of acct_qos_rec_t *'s based on the conditional sent. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the |
| function.<br> |
| <span class="commandline">qos_cond</span> (input) conditional about |
| which qos are to be returned. Qos names should not need to |
| be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing acct_qos_rec_t *'s |
| on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_get_wckeys(void *db_conn, uint32_t uid, |
| acct_wckey_cond_t *wckey_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Get a list of acct_wckey_rec_t *'s based on the conditional sent. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the |
| function.<br> |
| <span class="commandline">wckey_cond</span> (input) conditional about |
| which wckeys are to be returned. Wckey names should not need to |
| be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing acct_wckey_rec_t *'s |
| on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| List acct_storage_p_get_txn(void *db_conn, uint32_t uid, |
| acct_txn_cond_t *txn_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Get a list of acct_txn_rec_t *'s (transactions) based on the conditional sent. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">uid</span> (input) uid of user calling the |
| function.<br> |
| <span class="commandline">txn_cond</span> (input) conditional about |
| which transactions are to be returned. Transaction ids should not need to |
| be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List</span> containing acct_txn_rec_t *'s |
| on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_get_usage(void *db_conn, uint32_t uid, void *in, int type, |
| time_t start, time_t end) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Get usage for a specific association or wckey. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">uid</span> (input) uid of user calling the |
| function.<br> |
| <span class="commandline">in</span> (input/out) can be anything that |
| gathers usage like acct_association_rec_t * or acct_wckey_rec_t *.<br> |
| <span class="commandline">type</span> (input) really |
| slurmdbd_msg_type_t should let the plugin know what the structure is |
| that was sent in some how.<br> |
| <span class="commandline">start</span> (input) start time of the usage.<br> |
| <span class="commandline">end</span> (input) end time of the usage.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_roll_usage(void *db_conn, time_t sent_start) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| roll up association, cluster, and wckey usage in the storage. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">start</span> (input) start time of the rollup.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int clusteracct_storage_p_node_down(void *db_conn, char *cluster, |
| struct node_record *node_ptr, time_t event_time, char *reason) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Mark nodes down in the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">cluster</span> (input) name of cluster node |
| is on.<br> |
| <span class="commandline">node_ptr</span> (input) pointer to the node |
| structure marked down.<br> |
| <span class="commandline">event_time</span> (input) time event happened.<br> |
| <span class="commandline">reason</span> (input) if different from what |
| is set in the node_ptr, the reason the node is down.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int clusteracct_storage_p_node_up(void *db_conn, char *cluster, |
| struct node_record *node_ptr, time_t event_time) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Mark nodes up in the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">cluster</span> (input) name of cluster node |
| is on.<br> |
| <span class="commandline">node_ptr</span> (input) pointer to the node |
| structure marked up.<br> |
| <span class="commandline">event_time</span> (input) time event happened.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int clusteracct_storage_p_cluster_procs(void *db_conn, char *cluster, |
| char *cluster_nodes, uint32_t procs, time_t event_time) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Update storage type with the current number of processors on a given cluster. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. <br> |
| <span class="commandline">cluster</span> (input) name of cluster.<br> |
| <span class="commandline">cluster_nodes</span> (input) ranged list of |
| nodes on system.<br> |
| <span class="commandline">procs</span> (input) number of processors on |
| system.<br> |
| <span class="commandline">event_time</span> (input) time event happened.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int clusteracct_storage_p_get_usage(void *db_conn, uint32_t uid, void |
| *cluster_rec, int type, time_t start, time_t end) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Get usage for a specific cluster. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">uid</span> (input) uid of user calling the |
| function.<br> |
| <span class="commandline">cluster_rec</span> (input/out) |
| acct_cluster_rec_t * already set with the cluster name. Usage will be |
| filled in.<br> |
| <span class="commandline">type</span> (input) really |
| slurmdbd_msg_type_t should let the plugin know what the structure is |
| that was sent in some how for this it is just DBD_GET_CLUSTER_USAGE.<br> |
| <span class="commandline">start</span> (input) start time of the usage.<br> |
| <span class="commandline">end</span> (input) end time of the usage.<br> |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type. |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int clusteracct_storage_p_register_ctld(void *db_conn, char *cluster, |
| uint16_t port) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used when a controller is turned on to tell the storage type where the |
| slurmctld for a given cluster is located at. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">cluster</span> (input) name of cluster.<br> |
| <span class="commandline">port</span> (input) port on host cluster is |
| running on the host is grabbed from the connection.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int jobacct_storage_p_job_start(void *db_conn, struct job_record *job_ptr) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| jobacct_storage_p_job_start() is called in the jobacct plugin when a |
| job starts, inserting information into the database about the new job. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">job_ptr</span> (input) information about the job in |
| slurmctld. |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int jobacct_storage_p_job_complete(void *db_conn, struct job_record *job_ptr) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| jobacct_storage_p_job_complete() is called in the jobacct plugin when |
| a job completes, this updates info about end of a job. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">job_ptr</span> (input) information about the job in |
| slurmctld. |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int jobacct_storage_p_step_start(void *db_conn, struct step_record *step_ptr) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| jobacct_storage_p_step_start() is called in the jobacct plugin at the |
| allocation of a new step in the slurmctld, this inserts info about the |
| beginning of a step. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">step_ptr</span> (input) information about the step in |
| slurmctld. |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int jobacct_storage_p_step_complete(void *db_conn, struct step_record *step_ptr) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| jobacct_storage_p_step_complete() is called in the jobacct plugin at |
| the end of a step in the slurmctld, this updates the ending |
| information about a step. |
| <p style="margin-left:.2in"><b>Arguments</b>:<br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">step_ptr</span> (input) information about the step in |
| slurmctld. |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int jobacct_storage_p_job_suspend(void *db_conn, struct job_record *job_ptr) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| jobacct_storage_p_suspend() is called in the jobacct plugin when a |
| job is suspended or resumed in the slurmctld, this updates the |
| database about the suspended time of the job. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">job_ptr</span> (input) information about the job in |
| slurmctld. |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">none</span> |
| |
| <p class="commandline"> |
| List jobacct_storage_p_get_jobs_cond(void *db_conn, uint32_t uid, |
| acct_job_cond_t *job_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| jobacct_storage_p_get_jobs_cond() is called to get a list of jobs from the |
| database given the conditional. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">uid</span> (input) uid of user calling the function.<br> |
| <span class="commandline">job_cond</span> (input) conditional about |
| which jobs to get. Job ids should not need to be stated.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">List of job_rec_t's</span> on success, or<br> |
| <span class="commandline">NULL</span> on failure. |
| |
| <p class="commandline"> |
| int jobacct_storage_p_archive(void *db_conn, acct_archive_cond_t *arch_cond) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| used to archive old data. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">arch_cond</span> (input) conditional about |
| what to archive.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int jobacct_storage_p_archive_load(void *db_conn, acct_archive_rect *arch_rec) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| used to load old archive data. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">arch_rec</span> (input) information about |
| what to load.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_update_shares_used(void *db_conn, List acct_list) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| Used to update shares used in the storage type. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">acct_list</span> (input) List of shares_used_object_t.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="commandline"> |
| int acct_storage_p_flush_jobs_on_cluster(void *db_conn, char *cluster, time_t event_time) |
| <p style="margin-left:.2in"><b>Description</b>:<br> |
| used to mark all jobs in the storage type as finished. |
| <p style="margin-left:.2in"><b>Arguments</b>: <br> |
| <span class="commandline">db_conn</span> (input) connection to |
| the storage type.<br> |
| <span class="commandline">cluster</span> (input) name of cluster to |
| apply end to.<br> |
| <span class="commandline">event_time</span> (input) when the flush happened.<br> |
| <p style="margin-left:.2in"><b>Returns</b>: <br> |
| <span class="commandline">SLURM_SUCCESS</span> on success, or<br> |
| <span class="commandline">SLURM_ERROR</span> on failure. |
| |
| <p class="footer"><a href="#top">top</a> |
| |
| |
| <h2>Parameters</h2> |
| <p>These parameters can be used in the slurm.conf to set up |
| connections to the database all have defaults based on the plugin type |
| used. |
| <dl> |
| <dt><span class="commandline">AccountingStorageType</span> |
| <dd>Specifies which plugin should be used. |
| <dt><span class="commandline">AccountingStorageLoc</span> |
| <dd>Let the plugin the name of the logfile/database name to use. |
| <dt><span class="commandline">AccountingStorageHost</span> |
| <dd>Let the plugin know the host where the database is. |
| <dt><span class="commandline">AccountingStoragePort</span> |
| <dd>Let the plugin know the port to connect to. |
| <dt><span class="commandline">AccountingStorageUser</span> |
| <dd>Let the plugin know the name of the user to connect to the |
| database with. |
| <dt><span class="commandline">AccountingStoragePass</span> |
| <dd>Let the plugin know the password of the user connecting to the database. |
| <dt><span class="commandline">AccountingStorageEnforce</span> |
| <dd>Specifies if we should enforce certain things be in existence |
| before allowing job submissions and such valid options are |
| "associations, limits, qos, and wckeys". You can use any combination |
| of those listed. |
| </dl> |
| |
| <h2>Versioning</h2> |
| <p> This document describes version 1 of the SLURM Accounting Storage API. Future |
| releases of SLURM may revise this API. An Accounting Storage plugin conveys its |
| ability to implement a particular API version using the mechanism outlined |
| for SLURM plugins. |
| <p class="footer"><a href="#top">top</a> |
| |
| <p style="text-align:center;">Last modified 2 March 2009</p> |
| |
| <!--#include virtual="footer.txt"--> |
