pbs_stathook(3B)

NAME
pbs_stathook - obtain status information about PBS site hooks

SYNOPSIS
#include <pbs_error.h>
#include <pbs_ifl.h>

struct batch_status *pbs_stathook(int connect, char *id, struct attrl *attrib, char *extend)

void pbs_statfree(struct batch_status *psj)

DESCRIPTION
Issue a batch request to obtain the status of a specified site hook or a set of site hooks at the current server.

A Status Hook batch request is generated and sent to the server over the connection specified by connect which is the return value of pbs_connect().

This API can be executed only by root on the local server host.

The parameter, id , may be either a hook name or the null string. If id specifies a name, the attribute-value list for that hook is returned. If id is a null string or a null pointer, the status of all hooks at the current server is returned. The parameter, attrib , is a pointer to an attrl structure which is defined in pbs_ifl.h as:

    struct attrl {
        struct attrl *next;
        char         *name;
        char         *resource;
        char         *value;
    };

The attrib list is terminated by the first entry where next is a null pointer. If an attrib list is given, then only the attributes in the list are returned by the server. Otherwise, all the attributes of a hook are returned. The resource member is only used if the name member is ATTR_l, otherwise it should be a pointer to a null string. The value member should always be a pointer to a null string.

The parameter, extend , is reserved for implementation-defined extensions.

The return value is a pointer to a list of batch_status structures or the null pointer if no site hooks can be queried for status. The batch_status structure is defined in pbs_ifl.h as

    struct batch_status {
        struct batch_status *next;
        char                *name;
        struct attrl        *attribs;
        char                *text;
    }

It is up the user to free the structure when no longer needed, by calling pbs_statfree().

SEE ALSO
pbs_hook_attributes(7B), pbs_connect(3B)

DIAGNOSTICS
When the batch request generated by the pbs_stathook() function has been completed successfully and the status of each site hook has been returned by the batch server, the routine will return a pointer to the list of batch_status structures. If no site hooks were available to query or an error occurred, a null pointer is returned. The global integer pbs_errno should be examined to determine the cause.