NAME¶

pbs_rescquery, avail, totpool, usepool - query resource availability

SYNOPSIS¶

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

int pbs_rescquery(int connect, char **resourcelist, int arraysize,
int *available, int *allocated, int *reserved, int *down )

char *avail(int connect, char *resc)

int totpool(int connect, int update)

int usepool(int connect, int update)

DESCRIPTION¶

pbs_rescquery
Issue a request to the batch server to query the availability of resources. connect is the connection returned by pbs_connect(). resourcelist is an array of one or more strings specifying the resources to be queried. arraysize is the is the number of strings in resourcelist. available, allocated, reserved, and down are integer arrays of size arraysize. The amount of resource specified in the corresponding resourcelist string which is available, already allocated, reserved, and down/off-line is returned in the integer arrays.

At the present time the only resources which may be specified is "nodes". It may be specified as
    nodes
    nodes=
    nodes=specification
where specification is what a user specifies in the -l option arguement list for nodes, see qsub(1B) and the various pbs_resource_* man pages.

Where the node resourcelist is a simple type, such as "nodes", "nodes=", or "nodes=type", the numbers returned reflect the actual number of nodes (of the specified type) which are available, allocated, reserved, or down.

For a more complex node resourcelist, such as "nodes=2" or "nodes=type1:type2", only the value returned in available has meaning. If the number in available is positive, it is the number of nodes requried to satisified the specification and that some set of nodes are available which will satisify it, see avail (). If the number in available is zero, some number of nodes requried to satisified the specification are currently unavailable, the request might be satisifed at a later time. If the number in available is negative, no combination of known nodes can satisified the specification.

avail
The avail () call is provided as conversion aid for scheduler written for early versions of PBS. The avail() routine uses pbs_rescquery() and returns a character string answer. connect is the connection returned by pbs_connect(). resc is a single node=specification specification as discussed above. If the nodes to satisify the specification are currently available, the return value is the character string yes . If the nodes are currently unavailable, the return is the character string no . If the specification could never be satified, the return is the string never . An error in the specification returns the character string ? .

totpool
The totpool () function returns the total number of nodes know to the PBS server. This is the sum of the number of nodes available, allocated, reserved, and down. The parameter connection is the connection returned by pbs_connect(). The parameter update if non-zero, causes totpool() to issue a pbs_rescquery() call to obtain fresh information. If zero, numbers from the prior pbs_rescquery() are used.

usepool
usepool () returns the number of nodes currently in use, the sum of allocated, reserved, and down. The parameter connection is the connection returned by pbs_connect(). The parameter update if non-zero, causes totpool() to issue a pbs_rescquery() call to obtain fresh information. If zero, numbers from the prior pbs_rescquery() are used.

SEE ALSO¶

qsub(1B), pbs_connect(3B), pbs_disconnect(3B), pbs_rescreserve(3B) and pbs_resources(7B)

DIAGNOSTICS¶

When the batch request generated by the pbs_rescquery() function has been completed successfully by a batch server, the routine will return 0 (zero). Otherwise, a non zero error is returned. The error number is also set in pbs_errno.

The functions usepool() and totpool() return -1 on error.