basl2c - converts a BASL (BAtch Scheduling Language) code into a C scheduler
code.
basl2c [-d] [-l lexerDebugFile] [-p parserDebugFile] [-y symtabDebugFile] [-s
semanticDebugFile] [-g codegenDebugFile] [-c cFile] baslFile
basl2c is the BASL to C compiler that produces an intermediate code that
can be fed into a regular C compiler, and linked with the PBS libraries to
produce the scheduler executable. Basl2c takes as input a which is a program
written in the BAtch Scheduling Language, containing the main scheduling code.
Basl2c then converts the BASL constructs in the file into C statements, and it
also attaches additional code to produce the PBS scheduler source code. By
default, the resulting C code is written into the file
The full pathname to the resulting C file is what needs to be specified in the
SCHD_CODE variable in local.mk before compiling the BASL scheduler to
produce the executable.
- -d
- Prints additional debugging messages to the lexer (see -l
option), parser (see -p option), symbol table (see -y option), semantic
analyzer (see -s option), and code generator (see -g option).
- -l lexerDebugFile
- is the name of a file to write into the debugging messages
generated while scanning for tokens.
- -p parserDebugFile
- is the name of a file to write into the debugging messages
generated while putting together tokens in a usable way.
- -y symtabDebugFile
- is the name of a file to write into the debugging messages
related to the symbol table.
- -s semanticDebugFile
- is the name of a file to write into the debugging messages
generated while checking to make sure variables and operators are used in
a consistent way.
- -g codegenDebugFile
- is the name of a file to write into the debugging messages
generated while converting BASL statements to C statements.
- -c cFile
- is the name of a file where the generated C code is written
into.
The basic structure of a scheduler code written in BASL is as follows: !.BP
zero or more FUNCTIONS definitions
zero or more global VARIABLE DECLARATIONS
zero or more assignment statements (to initialize global variables)
sched_main()
{
one or more VARIABLE DECLARATIONS
zero or more STATEMENTS
}
For example,
% cat sched.basl
Int sum(Int a, Int b)
{
Int s;
s = a + b;
return(s);
}
Int glob;
sched_main()
{
Int c;
a = 3;
b = 4;
c = sum(a, b);
print(c);
glob = 5;
print(glob);
}
is the function that gets called at every scheduling iteration.
To define a function that can be called in subsequent functions, the syntax is:
ReturnType function-name ( DATATYPE1 IDENTIFIER1,
DATATYPE2 IDENTIFIER2, ... )
{
one or more VARIABLE DECLARATIONS
zero or more STATEMENTS
}
For example,
Void printStuff(Dayofweek dow, DateTime t, String str,
Size sz, CNode cn)
{
print(dow);
print(t);
print(str);
print(sz);
print(cn);
}
Valid function
ReturnType are: Void, Int, Float, Dayofweek, DateTime,
String, Size, Server, Que, Job, CNode, Set Server, Set Que, Set Job, Set
CNode.
Valid data types (
DATATYPE1, DATATYPE2, ... ) for the parameter
identifiers are: Int, Float, Dayofweek, DateTime, String, Size, Server, Que,
Job, CNode, Set Server, Set Que, Set Job, Set CNode, Range Int, Range Float,
Range Dayofweek, Range DateTime, Range Size, Fun Int, Fun Float, Fun Void, Fun
Dayofweek, Fun DateTime, Fun String, Fun Size, Fun Server, Fun Que, Fun Job,
Fun CNode, Fun Set Server, Fun Set Que, Fun Set Job, Fun Set CNode. These data
types will be discussed in the next topic.
Functions are invoked by their name and their arguments as in:
printStuff( MON, (5|1|1997@14:32:00), "sched begins",
30gb, node );
will actually add a "basl_" prefix to the function name given by the
scheduler writer to minimize chance of name collision, which can result when
the resulting C code is linked with the PBS, BASL libraries. For example, if
you look at the generated C code for you would see,
basl_printStuff( MON, (5|1|1997@14:32:00),
"sched begins", 30gb, node );
As in C, all function calls must have been previously defined. The BASL compiler
will check to make sure that arguments in the function call match up exactly
(in terms of types) with the parameters in the function definition.
Two kinds of functions exist in BASL: user-defined functions and predefined
functions. User-defined functions are those that the scheduler writer provided
a definition for, while predefined functions are those that can immediately be
called without a need for defining it. For a list of predefined functions, see
section on
PREDEFINED FUNCTIONS .
Like in C, all variables in a BASL code must be explicitly declared before use.
Those variables declared outside of any function are referred to as global
variables, while variables that are declared within a function body are called
local variables. Global variables are usable anywhere within the BASL code,
while local variables are readable only within the function from which they
were declared.
The syntax of a variable declaration is:
DATATYPE IDENTIFIER ;
where
DATATYPE can be: Int, Float, Dayofweek, DateTime, String, Size,
Server, Que, Job, CNode, Set Server, Set Que, Set Job, Set CNode, Range Int,
Range Float, Range Dayofweek, Range DateTime, Range Size.
- Void
- used for functions that don't return a value.
- Int
- signed, whole numbers given in base 10.
- Sample constants:
- 5, +1, -3, SUCCESS (=1), FAIL (=0), TRUE (=1), FALSE
(=0)
- Float
- real numbers which are represented as doubles in the
translated C code.
Sample constants: 4.3, +1.2, -2.6
- Dayofweek
- constant values: SUN, MON, TUE, WED, THU, FRI, SAT,
internally represented as integer valued constants with SUN=0, MON=1, and
so on.
- DateTime
- specify in one of 3 formats:
- [1]
- (m|d|y) where 1 <= m <= 12, 1 <= d <= 31, 0
<= y, ex. (4|4|1997);
- [2]
- (hh:mm:ss) where 0 <= hh <= 23, 0 <= mm <= 59,
0 <= ss <= 61, ex. (12:01:00);
- [3]
- (m|d|y@hh:mm:ss), ex. (4|4|1997@12:01:00)
During dates/times comparison, "now" time is substituted if the
time portion is not given (format [1]); the "now" date is
substituted if the date portion is not given (format [2]). Also, the full
year portion must be given (i.e. 1997 instead of 97) in dates to avoid
ambiguity.
- String
- A string is enclosed in quotes (") and it can contain
anything except another quote, a newline, and left and right parentheses.
Sample constants: "a sample string", NULLSTR
- Size
- format: <integer><suffix> where suffix is a
multiplier of the form: <multiplier><unit>:
multiplier unit (bytes or words)
=================== =====================
k,m,g,t,p,K,M,G,T,P b,B,w,W
where k=K=1024, m=M=1,048,576, g=G=1,073,741,824, t=T=1,099,511,627,776,
p=P=1,125,899,906,842,624, b=B=1, and word size w=W is locally defined
(i.e. 4 bytes in a 32-bit machine).
When operating on 2 size operands that are of different suffixes, the suffix
of the "lower" of the two will be the resultant suffix. For
example,
10mb + 10gb = 10250mb
Sample constants: -1b, 2w, 1kb, 2mw, +3gb, 4tw, 6Pb
- Range Int
- format: (low Int value, high Int value)
- where low Int value <= high Int value. Sample constant:
(1,3)
- Range Float
- format: (low Float value, high Float value)
- where low value <= high value. Sample constant: (2.3,
4.6)
- Range Dayofweek
- format: (earlier day, later day)
- where earlier day <= later day. Sample constant: (WED,
FRI)
- Range DateTime
- format: (earlier date/time, later date/time)
- where earlier date/time <= later date/time.
NOTE: if range contains only time portions, and earlier time
"appears" to be > later time as in "((18:0:0),
(6:0:0))", then during date/time comparisons, the "later"
time will be adjusted by one day so that it will look like: "(
(<now date>@18:0:0), (<tomorrow date>@6:0:0) )"
- Sample constants:
- ((4|4|1997), (4|10|1997)), ((12:01:00), (12:30:00)),
((4|4|1997@12:01:00), (4|10|1997@12:30:00))
- Range Size
- format: (low size, high size)
- where low size <= high size. Sample constants: (23gb,
50gb)
- Server
- Maps directly to the PBS server object. A Server
manages one or more Que objects.
Sample constant: NOSERVER
- CNode
- for computational node consisting of a single OS image, a
shared memory, and a set of cpus. CNode runs 1 PBS MOM.
Sample constant: NOCNODE
- Que
- Maps directly to the PBS queue object. A Que object
spools one or more Job objects.
Sample constant: NOQUE
- Job
- Maps directly to the PBS job object. A Job object
carries some attributes and resource requirements.
Sample constant: NOJOB
- Set Server
- list of Server objects.
Sample constant: EMPTYSETSERVER
- Set CNode
- list of CNode objects.
Sample constant: EMPTYSETCNODE
- Set Que
- list of Que objects.
Sample constant: EMPTYSETQUE
- Set Job
- list of Job objects.
Sample constant: EMPTYSETJOB
These are constants that cannot be used for naming an identifier (see next
topic). These are always in uppercase.
DATA TYPE BASL-DEFINED CONSTANT
=================== =============================================
Dayofweek SUN, MON, TUE, WED, THU, FRI, SAT
Int SUCCESS, FAIL, FALSE, TRUE, SYNCRUN, ASYNCRUN,
DELETE, RERUN, HOLD, RELEASE, SIGNAL,
MODIFYATTR, MODIFYRES, SERVER_ACTIVE,
SERVER_IDLE, SERVER_SCHED, SERVER_TERM,
SERVER_TERMDELAY, QTYPE_E, QTYPE_R,
SCHED_DISABLED, SCHED_ENABLED, TRANSIT,
QUEUED, HELD, WAITING, RUNNING, EXITING,
CNODE_OFFLINE, CNODE_DOWN, CNODE_FREE,
CNODE_RESERVE, CNODE_INUSE_EXCLUSIVE,
CNODE_INUSE_SHARED, CNODE_TIMESHARED,
CNODE_CLUSTER, CNODE_UNKNOWN, OP_EQ, OP_NEQ,
OP_LE, OP_LT, OP_GE, OP_GT, OP_MAX, OP_MIN,
ASC, DESC
Server NOSERVER
Set Server EMPTYSETSERVER
CNode NOCNODE
Set CNode EMPTYSETCNODE
Que NOQUE
Set Que EMPTYSETQUE
Job NOJOB
Set Job EMPTYSETJOB
String NULLSTR
Identifiers (used for variable names and function names) are in alphanumeric
format, with the special underscore (_) character allowed. Currently, BASL can
only handle identifiers with length of up to 80 chars. Also, you cannot use
the BASL-defined constant names for naming an identifier.
In
BASL(2), you can have a single statement terminated by a semi-colon, or a
group of statements (called compound statement or block) delimited by '{' and
'}'. The different kinds of statements that can appear in a BASL code are:
- 1. expression statement
- Expression statements are anything of the form:
expr ;
where expr can be:
- a)
- Arithmetic expressions
lexpr + rexpr (add)
lexpr - rexpr (subtract)
lexpr * rexpr (multiply)
lexpr / rexpr (divide)
lexpr % rexpr (modulus or remainder)
NOTE: Adding, subtracting, multiplying, dividing, and remaindering will only
be allowed for proper types and if the left and right expressions are of
consistent types. The table below illustrates what types are consistent
among the various operators:
For +:
lexpr rexpr
============ ============
Int or Float Int or Float
Size Size
String String
For -, *, /:
lexpr rexpr
============ ============
Int or Float Int or Float
Size Size
For %:
lexpr rexpr
============ ============
Int or Float Int or Float
Here are some sample arithmetic expressions statements:
Int i1;
Int i2;
Float f1;
Float f2;
Size sz1;
Size sz2;
String str1;
String str2;
i1 + i2;
f1 - i2;
sz1 * sz2 * 2b;
sz1 / 1024b;
str1 = "basl";
str2 = " cool";
// the following is a string concatenation
// operation resulting in the string:
// "basl cool"
str1 + str2;
i1 % 10;
- b)
- Unary expressions
+expr // positive - multiplies by 1 an
// expression that is
// of Int, Float, or
// Size type
-expr // negative - multiplies by -1 an
// expression that is
// of Int, Float, or
// Size type
!expr // not - converts a non-zero expr
// value into 0, and a
// zero expr value into 1
// where expr type must be
// of type Int or Float
Some sample unary expressions:
Int i;
+3;
-(i + 4);
!i;
- c)
- Logical expressions
lexpr EQ rexpr
lexpr NEQ rexpr
lexpr LT rexpr
lexpr LE rexpr
lexpr GT rexpr
lexpr GE rexpr
lexpr AND rexpr
lexpr OR rexpr
lexpr and rexpr must have types that are mutually consistent
as shown in the following table:
lterminal-expr rterminal-expr
============== ==============
Int or Float Int or Float
Dayofweek Dayofweek
DateTime DateTime
String String
Size Size
Server Server
Que Que
Job Job
CNode CNode
Set Server Set Server
Set Que Set Que
Set Job Set Job
Set CNode Set CNode
For AND, OR operators, the lexpr, rexpr
consistent types are Int or Float.
Some sample logical expressions:
i1 EQ i2;
i1 NEQ f2;
dow1 LE dow2;
d1 LT d2;
str1 GT str2;
sz1 GE sz2;
- d)
- Post-operator expressions
These are expressions that are merely shortcut to assignment statements.
IDENTIFIER++; // identifier=identifier+1
IDENTIFIER--; // identifier=identifier-1
IDENTIFIER must be of Int or Float type.
Example:
Int i;
Float f;
i++;
f--;
- e)
- Function call
function-name ( arg1 ,arg2 ... , argN )
where arg1, ..., argN can be any constant or variable. You can't have
another function call as an argument.
Example:
Void pr(Int a) {
print(a);
}
pr(5);
There are certain predefined functions that a scheduler writer can
automatically call in his/her BASL code without a need to define it. These
functions are referred to as assist functions (or helper functions) and
they are discussed under PREDEFINED FUNCTIONS topic.
- f)
- Constants
Some valid constant expressions are given in the following:
5;
+1.2;
SUN;
MON;
TUE;
WED;
THU;
FRI;
SAT;
(4|4|1997);
(12:01:00);
(4|4|1997@12:01:00);
"wonderful";
-1b;
SYNCRUN;
ASYNCRUN;
DELETE;
RERUN;
HOLD;
RELEASE;
SIGNAL;
MODIFYATTR;
MODIFYRES;
(1, 3);
(2.3, 4.6);
(WED, FRI);
((4|4|1997), (4|10|1997));
((12:01:00), (12:30:00));
((4|4|1997@12:01:00), (4|10|1997@12:30:00));
(23gb, 50gb);
NOSERVER;
NOCNODE;
NOQUE;
NOJOB;
EMPTYSETSERVER;
EMPTYSETCNODE;
EMPTYSETQUE;
EMPTYSETJOB;
NULLSTR;
SUCCESS;
FAIL;
SERVER_ACTIVE;
SERVER_IDLE;
SERVER_SCHED;
SERVER_TERM;
SERVER_TERMDELAY;
QTYPE_E;
QTYPE_R;
SCHED_DISABLED;
SCHED_ENABLED;
FALSE;
TRUE;
TRANSIT;
QUEUED;
HELD;
WAITING;
RUNNING;
EXITING;
CNODE_OFFLINE;
CNODE_DOWN;
CNODE_FREE;
CNODE_RESERVE;
CNODE_INUSE_EXCLUSIVE;
CNODE_INUSE_SHARED;
CNODE_TIMESHARED;
CNODE_CLUSTER;
CNODE_UNKNOWN;
OP_EQ;
OP_NEQ;
OP_LE;
OP_LT;
OP_GE;
OP_GT;
OP_MAX;
OP_MIN;
- g)
- Identifier
Example:
Int i;
i;
- 2. Assignment statement
-
IDENTIFIER = expr ;
IDENTIFIER and expr must have types that are mutually
consistent as illustrated in the following table:
identifier expr
=============== ===============
Int Int, Float
Float Int, Float
Dayofweek Dayofweek
DateTime DateTime
String String
Size Size
Que Que
Job Job
CNode CNode
Server Server
Dayofweek Dayofweek
DateTime DateTime
Set Server Set Server
Set Que Set Que
Set Job Set Job
Set CNode Set CNode
Range Int Range Int
Range Float Range Float
Range Dayofweek Range Dayofweek
Range DateTime Range DateTime
Range Size Range Size
- 3. if...else statement
- The format of an if statement is similar to that in C with
the delimiting "{" and "}" always present:
if( expr ) {
zero or more (true) STATEMENTS
}
if( expr ) {
zero or more (true) STATEMENTS
} else {
zero or more (false) STATEMENTS
}
The expr 's type must be either Int or Float, and after evaluation if
its value is non-zero, then the true statements are executed. On the
second form, if the expr evaluates to zero, then the false
statements are executed.
Some sample if statements are given below:
if (2 * x )
{
y = y + 3;
print(y);
}
if (2 * x ) {
y = y + 3;
} else {
if( 3 * x ) {
y = 4;
} else {
y = 5;
}
}
- 4. for loop statement
- The format of a for statement is as follows:
for( start; test; action ) {
zero or more STATEMENTS
}
Just like in C, for first executes start , then evaluates the
test condition to see if it returns a non-zero value. If it does,
the for statements are executed. After the for statements
are executed, then action is evaluated, and then it checks the
test condition again in the same manner as before. start and
action can be a simple assignment expression or a post-operator
expression. test is a logical/relational expression. Some sample
for statements are given in the following:
for (i = 0; i LT 3 ; i = i + 1)
{
print(i);
}
for (i = 0; i LT 2 * x; i++)
{
if (x GT 3)
{
y = 99;
} else
{
x = 73;
}
}
- 5. foreach loop statement
- This statement is primarily used for successively
retrieving each element of a Set data type: Set Server, Set CNode, Set
Job, Set Que. The syntax is:
foreach ( IDENTIFIER1 in IDENTIFIER2 ) {
zero or more STATEMENTS
}
where the following pairing of types for the identifiers are allowed:
IDENTIFIER1 IDENTIFIER2
=========== ===========
Server Set Server
Que Set Que
Job Set Job
CNode Set CNode
Example:
Server s;
Que q;
Job j;
CNode c;
Set Server ss;
Set Que sq;
Set Job sj;
Set CNode sc;
foreach(s in ss){
print(s);
}
foreach(q in sq){
print(q);
}
foreach(j in sj){
print(j);
}
foreach(c in sc){
print(c);
}
- 6. while loop statement
- The syntax of a while loop is:
while ( expr ) {
zero or more STATEMENTS
}
where expr must be of Int or Float type. If expr is non-zero,
then the zero or more are executed and expr is re-evaluated.
Example:
Int i;
i = 3;
while(i) {
if( i EQ 0 ) {
print("break on i = 1");
break;
}
i--;
}
- 7. switch statement
- The switch statement is a mult-way decision that tests
whether an identifier's value matches one of a number of values, and
branches to a group of statements accordingly.
The syntax for a switch statement is:
switch( IDENTIFIER ) {
case constant-expr :
{
zero or more STATEMENTS
}
case constant-expr :
{
zero or more STATEMENTS
}
...
case in constant-rangeOrSet-expr :
{
zero or more STATEMENTS
}
case in IDENTIFIER-rangeOrSettype :
{
zero or more STATEMENTS
}
default :
{
zero or more STATEMENTS
}
}
where constant-expr is an expr of type Int, Float, Dayofweek,
DateTime, Size, String, Server, Que, Job, or CNode.
constant-rangeOrSet-expr and IDENTIFIER-rangeOrSettype can
be of type Set Server, Set CNode, Set Que, Set Job, Range Int, Range
Float, Range Dayofweek, Range DateTime, or Range Size.
IDENTIFIER cannot be of type Void. IDENTIFIER 's type must be
consistent with constant-expr 's, constant-rangeOrSet-expr
's, and IDENTIFIER-rangeOrSettype 's type as illustrated in the
following table: !.BP
IDENTIFIER constant-range-expr, IDENTIFIER-rangetype
=========== =========================================
Server Set Server
Que Set Que
Job Set Job
CNode Set CNode
Int Range Int
Float Range Float
Dayofweek Range Dayofweek
DateTime Range DateTime
Size Range Size
If a case expression matches the IDENTIFIER 's value, then the
corresponding block of statements are executed. Unlike in C, execution
does NOT fall through to the next case statement. The reason for this is
that will translate this switch statement into if-elseif-else
construct. The case labeled default is executed if none of the other cases
are satisfied. The default is optional; if it isn't there, and if
none of the cases match, no action takes place.
Example:
Dayofweek dow;
switch(dow)
{
case MON:
{
print("case MON");
}
case TUE:
{
print("case TUE");
}
case WED:
{
print("case WED");
}
case THU:
{
print("case THU");
}
case FRI:
{
print("case FRI");
}
case SAT:
{
print("case SAT");
}
case SUN:
{
print("case SUN");
}
default:
{
print("case defaulted");
}
}
Int a;
Range Int ri;
ri = (10, 12);
switch(a)
{
case in (1,5):
{
print("case 1,5");
}
case in (6,9):
{
print("case 6,9");
}
case in ri:
{
print("case ri");
}
}
- 8. print statement
- Print statement is capable of printing to stdout the value
of any identifier or constant of type Int, Float, Dayofweek,
DateTime, String, Size, Que, Job, CNode, Server, Range Int, Range Float,
Range Dayofweek, Range DateTime, Range Size.
The syntax is as follows:
print ( IDENTIFIER );
print ( constant );
Example:
DateTime dt;
CNode cn;
dt = (4|4|1997@12:13:36);
cn = AllNodesLocalHostGet();
print(dt);
print(cn);
For Set types, use foreach to go through each element and print as
in:
Server s;
Set Server ss;
ss = AllServersGet();
foreach(s in ss) {
print(s);
}
- 9. continue statement
-
continue ;
The continue statement must have been invoked within a for,
foreach, and while loop. It causes the next iteration of the
enclosing loop to begin.
- 10. break statement
-
break ;
The break statement must have been invoked within a for,
foreach, and while loop. It provides an early exit from the
enclosing loop.
- 11. return statement
-
return(IDENTIFIER) ;
return(constant) ;
return() ;
The return statement provides the value (if any) to be returned by a
function. The type returned by IDENTIFIER and constant must
match the calling function's return type. constant types allowed
are anything except Set and Range types. The last format, return()
is usually called within a function that doesn't return any value ( like
sched_main() ).
- 12. exit statement
-
exit(constant);
where constant is of type Int. Calling this will terminate the
scheduler.
- 13. Comment statement
- These are statements prefixed by "//" and they
are ignored by the BASL compiler.
// this line is ignored
Int i; // string following the slashes is ignored
The following table shows the various operator precedence levels and
associativity defined in the BASL language. The operators are listed in the
order of decreasing precedence. The higher the precedence of an operator, the
earlier it gets executed. The order in which the operators on the same level
are executed depends on the associativity: left means the operators are seen
from left to right, while right means they are seen from right to left.
Operator Associativity
======================================= =============
! ++ -- + (unary plus) - (unary minus) right
* / % left
+ - left
LT LE GT GE left
EQ NEQ left
AND left
OR left
= right
In
BASL(2), a
Server data type maps directly to a batch server object.
Similarly,
CNode is to mom/resmom,
Job is to batch job, and
Que is to batch queue. However, not all attributes to the PBS objects
can be accessed from BASL. Only a subset of attributes, those that seemed to
make sense in the context of a scheduler, are made available, and values to
these attributes can be accessed by calling the following predefined
functions, known also as assist/helper functions.
- (1) Server-related functions
- Set Server AllServersGet(void)
- Returns the list of servers specified in the configuration
file for which the scheduler writer wants the system to periodically check
for status, queues and jobs info. See pbs__sched__basl(8B) for a
discussion on the format of the configuration file.
CAUTION: This function must be called from inside sched_main() so
that at every scheduling iteration, the most up to date Set Server
structure is returned.
- Server AllServersLocalHostGet(void)
- Returns the Server object that represents the local host.
unset value: NOSERVER. This is a simple function to call for non-cluster
environments where only one server host exists.
CAUTION: This function must be called from inside sched_main() (or
from within function called by sched_main) so that at every scheduling
iteration, the most up to date Server structure is returned.
- String ServerInetAddrGet(Server s)
- Returns name for Server s. unset value: NULLSTR
- String ServerDefQueGet(Server s)
- Returns the default_queue attribute of Server s. unset
value: NULLSTR
- Int ServerStateGet(Server s)
- Returns server_state attribute of Server s.
- Return value:
- SERVER_ACTIVE, SERVER_IDLE, SERVER_SCHED, SERVER_TERM,
SERVER_TERMDELAY, -1 (unset value)
- Int ServerMaxRunJobsGet(Server s)
- Returns max_running attribute of Server s. unset value:
0
- Int ServerMaxRunJobsPerUserGet(Server s)
- Returns max_user_run attribute of Server s. unset value:
0
- Int ServerMaxRunJobsPerGroupGet(Server s)
- Returns max_group_run attribute of Server s. unset value:
0
- Set Que ServerQueuesGet(Server s)
- Returns list of queues managed by Server s.
- Set Job ServerJobsGet(Server s)
- Returns list of jobs managed by Server s. For obtaining a
subset of this list, see QueJobsGet().
- Int ServerIntResAvailGet(Server s, String name)
- Returns the value to resource specified in name that
is available to jobs run by this server (Server attribute). Call this
function for resources with values that are of Int type. Sample resource
names are: cput, pcput, walltime, mppt, pmppt, nice, procs, mppe, ncpus,
pncpus, nodect, srfs_assist, mta,..., mth. For a description of these
resource names, see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
Example:
Int cpuAvail;
// return the # of cpus currently available in
// the server
cpuAvail = ServerIntResAvailGet(server, "ncpus");
- Size ServerSizeResAvailGet(Server s, String
name)
- Returns the value to resource specified in name that
is available to jobs run by this server (Server attribute). Call this
function for resources with values that are of Size type. Sample resource
names are: file, mem, pmem, workingset, pf, ppf, srfs_tmp, srfs_wrk,
srfs_big, srfs_fast, sds, psds. For a description of these resource names,
see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
Example:
Size memAvail;
// return the amount of available memory in
// the server
memAvail = ServerSizeResAvailGet(server, "mem");
- String ServerStringResAvailGet(Server s, String
name)
- Returns the value to resource specified in name that
is available to jobs run by this server (Server attribute). Call this
function for resources with values that are of String type. Sample
resource names are: nodes, arch, neednodes. For a description of these
resource names, see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
Example:
String type;
// return the architecture (or os type) of
// the server
type = ServerStringResAvailGet(server, "arch");
- Int ServerIntResAssignGet(Server s, String
name)
- Returns the value to resource specified in name that
is allocated to running jobs (Server attribute). Call this function for
resources with values that are of Int type. Sample resource names are:
cput, pcput, walltime, mppt, pmppt, nice, procs, mppe, ncpus, pncpus,
nodect, srfs_assist, mta,..., mth. For a description of these resource
names, see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
Example:
Int cpuAssn;
// return the # of cpus currently assigned in
// the server
cpuAssn = ServerIntResAssignGet(server, "ncpus");
- Size ServerSizeResAssignGet(Server s, String
name)
- Returns the value to resource specified in name that
is allocated to running jobs (Server attribute). Call this function for
resources with values that are of Size type. Sample resource names are:
file, mem, pmem, workingset, pf, ppf, srfs_tmp, srfs_wrk, srfs_big,
srfs_fast, sds, psds. For a description of these resource names, see
pbs_resources_irix5(7B), pbs_resources_sp2(7B), pbs_resources_sunos4(7B),
pbs_resources_unicos8(7B), pbs_server_attributes(7B),
pbs_resources_irix6(7B), pbs_resources_linux(7B).
Example:
Size sdsAssn;
// return the amount of sds space currently assigned
// in the server
sdsAssn = ServerSizeResAssignGet(server, "sds");
- String ServerStringResAssignGet(Server s, String
name)
- Returns the value to resource specified in name that
is allocated to running jobs (Server attribute). Call this function for
resources with values that are of String type. Sample resource names are:
nodes, arch, neednodes. For a description of these resource names, see
pbs_resources_irix5(7B), pbs_resources_sp2(7B), pbs_resources_sunos4(7B),
pbs_resources_unicos8(7B), pbs_server_attributes(7B),
pbs_resources_irix6(7B), pbs_resources_linux(7B).
- Set CNode ServerNodesGet(Server s)
- Returns the set of nodes managed by server s. unset value:
EMPTYSETCNODE.
NOTE: You can usually call the following functions for the nodes returned by
this call: CNodeStateGet(), CNodePropertiesGet(), and CNodeTypeGet().
- Int ServerNodesQuery(Server s, String spec)
- Issues a request to the specified server to query the
availability of resources specified in spec. At the present time,
the only resource specification allowed is one that involves
"nodes" and it can be of the format "nodes",
"nodes=", or "nodes=<type>". The query results
can be accessed by calling the following functions:
ServerNodesNumAvailGet(), ServerNodesNumAllocGet(),
ServerNodesNumRsvdGet(), ServerNodesNumDownGet().
NOTE: This is a wrapper to the pbs_rescquery(3B) server function.
- Return value:
- SUCCESS, FAIL
- Int ServerNodesNumAvailGet(Server s)
- Returns the number of nodes available for those managed by
the specified server, or as reflected by the most recent query specified
by ServerNodesQuery(). If the return value is zero, then this means that
some number of nodes currently needed to satisfy the specification of
ServerNodesQuery() are currently unavailable. The request maybe satisfied
at some later time. If the result is negative, no combination of known
nodes can satisfy the specification.
- Int ServerNodesNumAllocGet(Server s)
- Returns the number of nodes allocated for those managed by
the specified server, or as reflected by the most recent query specified
by ServerNodesQuery().
- Int ServerNodesNumRsvdGet(Server s)
- Returns the number of nodes reserved for those managed by
the specified server, or as reflected by the most recent query specified
by ServerNodesQuery().
- Int ServerNodesNumDownGet(Server s)
- Returns the number of nodes down for those managed by the
specified server, or as reflected by the most recent query specified by
ServerNodesQuery().
- Int ServerNodesReserve(Server s,String spec,Int
resId)
- Issues a request to the specified server to reserve the
resources specified in spec. A value of 0 for resId means
that this is for doing a new reservation. Otherwise, the number will
represent an existing (partial) reservation. Resources currently reserved
for this resId will be released and the full reservation will be
attempted again. At the present time the only resources which may be
specified are "nodes". It should be specified as
nodes=specification where specification is what a user specifies in
the -l option argument list for nodes, see qsub (1B).
NOTE: This is a wrapper to the pbs_rescreserve(3B) server function.
- Return value:
- a reference number to a successful or partially-successful
reservation, or FAIL
- Int ServerNodesRelease(Server s, Int resId)
- This releases or frees resources reserved with the
reference number specified in resId.
NOTE: This is a wrapper to the pbs_rescrelease(3B) server function.
- Return value:
- SUCCESS, or FAIL
- (2) Que-related functions:
- String QueNameGet( Que que )
- Returns name of Que que. unset value: NULLSTR
- Int QueTypeGet( Que que )
- Returns queue_type attribute of Que que.
Return value: QTYPE_E (Execution), QTYPE_R (Routing), -1 (unset value)
- Int QueNumJobsGet( Que que )
- Returns number of jobs residing in Que que. unset value:
0
- Int QueMaxRunJobsGet( Que que )
- Returns max_running attribute of Que que. unset value:
0
- Int QueMaxRunJobsPerUserGet( Que que )
- Returns max_user_run attribute of Que que. unset value:
0
- Int QueMaxRunJobsPerGroupGet( Que que )
- Returns max_group_run attribute of Que que. unset value:
0
- Int QuePriorityGet( Que que )
- Returns Priority attribute of Que que. unset value: 0
- Int QueStateGet( Que que )
- Returns started attribute of Que que - the job execution
selection state of the que: SCHED_DISABLED, SCHED_ENABLED. unset value:
SCHED_DISABLED
- Set Job QueJobsGet( Que que )
- Returns the list of jobs currently residing in que.
- Int QueIntResAvailGet(Que q, String name)
- Returns the value to resource specified in name that
is available to jobs running from this q (Que attribute). Call this
function for resources with values that are of Int type. Sample resource
names are: cput, pcput, walltime, mppt, pmppt, nice, procs, mppe, ncpus,
pncpus, nodect, srfs_assist, mta,..., mth. For a description of these
resource names, see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
- Size QueSizeResAvailGet(Que q, String name)
- Returns the value to resource specified in name that
is available to jobs running from this q (Que attribute). Call this
function for resources with values that are of Size type. Sample resource
names are: file, mem, pmem, workingset, pf, ppf, srfs_tmp, srfs_wrk,
srfs_big, srfs_fast, sds, psds. For a description of these resource names,
see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
- String QueStringResAvailGet(Que q, String name)
- Returns the value to resource specified in name that
is available to jobs running from this q (Que attribute). Call this
function for resources with values that are of String type. Sample
resource names are: nodes, arch, neednodes. For a description of these
resource names, see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
- Int QueIntResAssignGet(Que q, String name)
- Returns the value to resource specified in name that
is allocated to jobs running from this queue (Que attribute). Call this
function for resources with values that are of Int type. Sample resource
names are: cput, pcput, walltime, mppt, pmppt, nice, procs, mppe, ncpus,
pncpus, nodect, srfs_assist, mta,..., mth. For a description of these
resource names, see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
- Size QueSizeResAssignGet(Que q, String name)
- Returns the value to resource specified in name that
is allocated to jobs running from this q (Que attribute). Call this
function for resources with values that are of Size type. Sample resource
names are: file, mem, pmem, workingset, pf, ppf, srfs_tmp, srfs_wrk,
srfs_big, srfs_fast, sds, psds. For a description of these resource names,
see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
- String QueStringResAssignGet(Que q, String
name)
- Returns the value to resource specified in name that
is allocated to jobs running from this q (Que attribute). Call this
function for resources with values that are of String type. Sample
resource names are: nodes, arch, neednodes. For a description of these
resource names, see pbs_resources_irix5(7B), pbs_resources_sp2(7B),
pbs_resources_sunos4(7B), pbs_resources_unicos8(7B),
pbs_server_attributes(7B), pbs_resources_irix6(7B),
pbs_resources_linux(7B).
- (3) Job-related functions
- String JobIdGet( Job job )
- Returns job identifier of Job job. unset value:
NULLSTR
- String JobNameGet( Job job )
- Returns Job_Name attribute of Job job. unset value:
NULLSTR
- String JobOwnerNameGet( Job job )
- Returns Job_Owner attribute of Job job. unset value:
NULLSTR
- String JobEffectiveUserNameGet( Job job)
- Returns euser attribute of Job job.
- String JobEffectiveGroupNameGet(Job job)
- Returns egroup attribute of Job job. unset value:
NULLSTR
- Int JobStateGet ( Job job )
- Returns job_state attribute of Job job.
- Return value:
- TRANSIT, QUEUED, HELD, WAITING, RUNNING, EXITING, -1 (unset
value)
- Int JobPriorityGet( Job job )
- Returns Priority attribute of Job job. unset value: 0
- Int JobRerunFlagGet( Job job )
- Returns Rerunable attribute of Job job.
Return value: FALSE, TRUE, -1 (unset value)
- Int JobInteractiveFlagGet( Job job )
- Returns interactive attribute of Job job.
Return value: FALSE, TRUE. unset value: FALSE
- DateTime JobDateTimeCreatedGet(Job job)
- Returns the ctime attribute of Job job. unset value:
(0|0|0@-1:-1:-1)
- String JobEmailAddrGet( Job job )
- Returns the Mail_Users attribute of Job job. unset value:
NULLSTR
- String JobStageinFilesGet( Job job )
- Returns the stagein attribute of Job job. unset value:
NULLSTR
- String JobStageoutFilesGet( Job job )
- Returns stageout attribute of Job job. unset value:
NULLSTR
- Int JobIntResReqGet(Job job, String name)
- Returns the value to resource specified in name as
required by the job (Job attribute). Call this function for resources with
values that are of Int type. Sample resource names are: cput, pcput,
walltime, mppt, pmppt, nice, procs, mppe, ncpus, pncpus, nodect,
srfs_assist, mta,..., mth. For a description of these resource names, see
pbs_resources_irix5(7B), pbs_resources_sp2(7B), pbs_resources_sunos4(7B),
pbs_resources_unicos8(7B), pbs_server_attributes(7B),
pbs_resources_irix6(7B), pbs_resources_linux(7B).
Example:
Int cputReq;
// returns the cput requirement of the job
cputReq = JobIntResReqGet(job, "cput");
- Size JobSizeResReqGet(Job job, String name)
- Returns the value to resource specified in name as
required by the job (Job attribute). Call this function for resources with
values that are of Size type. Sample resource names are: file, mem, pmem,
workingset, pf, ppf, srfs_tmp, srfs_wrk, srfs_big, srfs_fast, sds, psds.
For a description of these resource names, see pbs_resources_irix5(7B),
pbs_resources_sp2(7B), pbs_resources_sunos4(7B),
pbs_resources_unicos8(7B), pbs_server_attributes(7B),
pbs_resources_irix6(7B), pbs_resources_linux(7B).
Example:
Size memReq;
// returns the memory requirement of the job
memReq = JobSizeResReqGet(job, "mem");
- String JobStringResReqGet(Job job, String name)
- Returns the value to resource specified in name as
required by the job (Job attribute). Call this function for resources with
values that are of String type. Sample resource names are: nodes, arch,
neednodes. For a description of these resource names, see
pbs_resources_irix5(7B), pbs_resources_sp2(7B), pbs_resources_sunos4(7B),
pbs_resources_unicos8(7B), pbs_server_attributes(7B),
pbs_resources_irix6(7B), pbs_resources_linux(7B).
Example:
String nodes;
// returns the nodes requirement property of
// the job
nodes = JobStringResReqGet(job, "nodes");
- Int JobIntResUseGet(Job job, String name)
- Returns the value to resource specified in name used
by the job (Job attribute). Call this function for resources with values
that are of Int type. Sample resource names are: cput, pcput, walltime,
mppt, pmppt, nice, procs, mppe, ncpus, pncpus, nodect, srfs_assist,
mta,..., mth. For a description of these resource names, see
pbs_resources_irix5(7B), pbs_resources_sp2(7B), pbs_resources_sunos4(7B),
pbs_resources_unicos8(7B), pbs_server_attributes(7B),
pbs_resources_irix6(7B), pbs_resources_linux(7B).
Example:
Int walltUse;
// returns the amount of walltime used by
// the job
walltUse = JobIntResUseGet(job, "walltime");
- Size JobSizeResUseGet(Job job, String name)
- Returns the value to resource specified in name used
by the job (Job attribute). Call this function for resources with values
that are of Size type. Sample resource names are: file, mem, pmem,
workingset, pf, ppf, srfs_tmp, srfs_wrk, srfs_big, srfs_fast, sds, psds.
For a description of these resource names, see pbs_resources_irix5(7B),
pbs_resources_sp2(7B), pbs_resources_sunos4(7B),
pbs_resources_unicos8(7B), pbs_server_attributes(7B),
pbs_resources_irix6(7B), pbs_resources_linux(7B).
Example:
Size srfsUse;
// returns the amount of srfs_fast used by
// the job
srfsUse = JobSizeResUseGet(job, "srfs_fast");
- String JobStringResUseGet(Job job, String name)
- Returns the value to resource specified in name used
by the job (Job attribute). Call this function for resources with values
that are of String type. Sample resource names are: nodes, arch,
neednodes. For a description of these resource names, see
pbs_resources_irix5(7B), pbs_resources_sp2(7B), pbs_resources_sunos4(7B),
pbs_resources_unicos8(7B), pbs_server_attributes(7B),
pbs_resources_irix6(7B), pbs_resources_linux(7B).
- (4) CNode-related functions
- Set CNode AllNodesGet(void)
- Returns list of nodes that are managed by the server
running on the local host. This could also include those nodes that were
specified in the scheduler configuration file for which the scheduler
writer wants the system to periodically check for information like state,
property, and so on. See pbs_sched_basl(8B) for a discussion of
configuration file format.
CAUTION: This function must be called from inside sched_main() so
that at every scheduling iteration, the most up to date Set CNode
structure is returned. Do not call this from an assignment statement
intended to initialize a global variable, as the statement will only be
called once.
- CNode AllNodesLocalHostGet(void)
- Returns the CNode object that represents the local host.
This is a simple function to call for non-clustered systems where only 1
CNode exists. unset value: NOCNODE
CAUTION: This function must be called from inside sched_main() (or
from within functions called by sched_main) so that at every scheduling
iteration, the most up to date CNode structure is returned. Do not
call this from an assignment statement intended to initialize a global
variable, as the statement will only be called once.
- String CNodeNameGet(CNode node)
- Returns the unique (official) name of the node (i.e. ResMom
hostname in a 1 mom/node model). This returns the same string that was
specified in the configuration file. unset value: NULLSTR
- String CNodeOsGet(CNode node)
- Returns the os architecture of the node (i.e.
"irix5", "sp2"). unset value: NULLSTR
- Int CNodeStateGet( CNode node )
- Returns the node's state.
- Return value:
- CNODE_OFFLINE, CNODE_DOWN, CNODE_FREE, CNODE_RESERVE,
CNODE_INUSE_EXCLUSIVE, CNODE_INUSE_SHARED, CNODE_UNKNOWN
- Int CNodeTypeGet( CNode node )
- Returns the node's type.
- Return value:
- CNODE_TIMESHARED, CNODE_CLUSTER, CNODE_UNKNOWN
- String CNodePropertiesGet(CNode node)
- Returns the comma-separated list of other names the node is
known by ( properties, other network name). For example,
"babbage.OpenPBS.org" maybe the node name, but it could also be
known via "babbage1, babbage2". unset value: NULLSTR
- String CNodeVendorGet(CNode node)
- Returns the name of the vendor for the hardware of the
machine (i.e. "sgi", "ibm"). unset value: NULLSTR
- Int CNodeNumCpusGet(CNode node)
- Returns the number of processors attached to the node.
unset value: -1
- Size CNodeMemTotalGet( CNode node, String type
)
- Returns total memory of type for the node.
type is an arbitrary string that the scheduler writer defines in
the scheduler configuration file. unset value: -1b
Example:
// get total physical memory
CNodeMemTotalGet(node, "real")
// get total virtual memory
CNodeMemTotalGet(node, "virtual")
- Size CNodeMemAvailGet( CNode node, String type
)
- Returns available memory of type for the node.
type is an arbitrary string that the scheduler writer defines in
the scheduler configuration file. unset value: -1b
So sample calls will be:
// get available physical memory
CNodeMemAvailGet(node, "real")
// get available virtual memory
CNodeMemAvailGet(node, "virtual")
- Int CNodeIdletimeGet( CNode node )
- Returns number of seconds in which no keystroke or mouse
movement has taken place on any terminal connected to the node. unset
value: -1
- Float CNodeLoadAveGet( CNode node )
- Returns node's load average for all cpus. unset value:
-1.0
- Int CNodeCpuPercentIdleGet( CNode node )
- Returns the percent of idle time that all the processors of
the node have experienced.
- Int CNodeCpuPercentSysGet( CNode node )
- Returns the percent of time that all the processors of the
node have spent running kernel code.
- Int CNodeCpuPercentUserGet( CNode node )
- Returns the percent of time that all the processors of the
node have spent running user code.
- Int CNodeCpuPercentGuestGet( CNode node )
- Returns the percent of time that all the processors of the
node have spent running a guest operating system.
- Int CNodeNetworkBwGet( CNode node, String type
)
- Returns the bandwidth of the node's network of type
in bytes/second. type is defined by the scheduler writer in the
scheduler configuration file. unset value: -1
Some sample calls are:
CNodeNetworkBwGet( node, "hippi" );
CNodeNetworkBwGet( node, "fddi" );
- Size CNodeDiskSpaceTotalGet(CNode node, String
name)
- Returns the node's total space on disk identified by
name where name is the device name arbitrarily defined by
the scheduler writer in the scheduler configuration file. unset value: -1b
Example:
CNodeDiskSpaceTotalGet( node, "/scratch2" );
- Size CNodeDiskSpaceAvailGet(CNode node, String
name)
- Returns the node's available space on disk identified by
name where name is arbitrarily defined by the scheduler
writer in the scheduler configuration file. unset value: -1b
Example:
CNodeDiskSpaceAvailGet( node, "/scratch1" );
- Size CNodeDiskSpaceReservedGet(CNode node, String
name)
- Returns the node's reserved space on disk (user quota?)
identified by name where name is arbitrarily defined by the
scheduler writer in the scheduler configuration file. unset value: -1b
Example:
CNodeDiskSpaceReservedGet( node, "/scratch1" );
- Int CNodeDiskInBwGet( CNode node, String name )
- Returns the write bandwidth (bytes/sec) of the node's disk
identified by name . unset value: -1
Example:
CNodeDiskInBwGet( node, "/fast" );
- Int CNodeDiskOutBwGet( CNode node, String name
)
- Returns read bandwidth (bytes/sec) of the node's disk
identified by name . unset value: -1
Example:
CNodeDiskOutBwGet( node, "/big" );
- Size CNodeSwapSpaceTotalGet( CNode node, String name
)
- Returns the node's total space on swap identified by
name where name is arbitrarily defined by the scheduler
writer in the scheduler configuration file. unset value: -1b
Example:
CNodeSwapSpaceTotalGet( node, "primary" );
- Size CNodeSwapSpaceAvailGet( CNode node, String name
)
- Returns node's available space on swap identified by
name where name is the device name arbitrarily defined by
the scheduler writer in the scheduler configuration file. unset value: -1b
Example:
CNodeSwapSpaceAvailGet( node, "secondary" );
- Int CNodeSwapInBwGet( CNode node, String name )
- Returns swapin rate of the node's swap device identified by
name.
Example:
CNodeSwapInBwGet(node, "secondary");
- Int CNodeSwapOutBwGet( CNode node, String name
)
- Returns the swapout rate of the node's swap device
identified by name. unset value: -1
Example:
CNodeSwapOutBwGet(node, "primary");
- Size CNodeTapeSpaceTotalGet( CNode node, String name
)
- Returns the node's total space on tape identified by
name where name is arbitrarily defined by the scheduler
writer in the scheduler configuration file. unset value: -1b
Example:
CNodeTapeSpaceTotalGet(node, "4mm");
- Size CNodeTapeSpaceAvailGet( CNode node, String name
)
- Returns the node's available space on tape identified by
name where name is arbitrarily defined by the scheduler
writer in the scheduler configuration file. unset value: -1b
Example:
CNodeTapeSpaceAvailGet(node, "8mm");
- Int CNodeTapeInBwGet( CNode node, String name )
- Returns the write bandwidth (bytes/sec) of the node's tape
identified by name . unset value: -1
Example:
CNodeTapeInBwGet( node, "4mm" );
- Int CNodeTapeOutBwGet( CNode node, String name
)
- Returns the read bandwidth (bytes/sec) of the node's tape
identified by name . unset value: -1
Example:
CNodeTapeOutBwGet( node, "8mm" );
- Size CNodeSrfsSpaceTotalGet( CNode node, String name
)
- Returns the node's total space on srfs device identified by
name where name is arbitrarily defined by the scheduler
writer in the scheduler configuration file. unset value: -1b
Example:
CNodeSrfsSpaceTotalGet(node, "/fast");
- Size CNodeSrfsSpaceAvailGet( CNode node, String name
)
- Returns the node's available space on srfs device
identified by name where name is arbitrarily defined by the
scheduler writer in some configuration file. unset value: -1b
Example:
CNodeSrfsSpaceAvailGet( node, "/big" );
- Size CNodeSrfsSpaceReservedGet(CNode node, String
name)
- Returns the node's total amount of reserved space on srfs
device identified by name where name is arbitrarily defined
by the scheduler writer in the scheduler configuration file. unset value:
-1b
Example:
CNodeSrfsSpaceReservedGet( node, "/fast" );
- Int CNodeSrfsInBwGet( CNode node, String name )
- Returns the write bandwidth (bytes/sec) of the node's srfs
device identified by name . unset value: -1
Example:
CNodeSrfsInBwGet( node, "/fast" );
- Int CNodeSrfsOutBwGet( CNode node, String name
)
- Returns the read bandwidth (bytes/sec) of the node's srfs
device identified by name . unset value: -1
Example:
CNodeSrfsOutBwGet( node, "/big" );
- (5) Miscellaneous Functions
- DateTime datetimeGet()
- gets the current date/time.
- Int datetimeToSecs(DateTime dt)
- returns the # of seconds since epoch (beginning of UNIX
time - 00:00:00, January 1, 1970) for the given date/time dt.
- Int JobAction( Job job, Int action, String param
)
- Performs action on job with a param
specified depending on the action. action can be: SYNCRUN,
ASYNCRUN, DELETE, RERUN, HOLD, RELEASE, SIGNAL, MODIFYATTR, MODIFYRES
where:
Action Description
=============== ==========================
SYNCRUN runs the job synchronously,
meaning the call to
JobAction() will only
return when the job has
started running or when
an error has been
encountered.
Param value:
name of host(s) to run
job under.
ASYNCRUN runs the job asynchronously,
meaning the call to
JobAction() will return
immediately as soon as
the run request is
validated by the PBS server,
and not necessarily when
the job has started
execution.
Param value:
name of host(s) to run
job under.
DELETE deletes the job.
Param value:
"deldelay=<# of secs>"
- delay # of seconds
between the sending
of SIGTERM and SIGKILL
to the job before
getting deleted.
RERUN reruns the running job,
which involves terminating
the session leader of the
job and returning the job
to the queued state.
HOLD places one or more holds
on the job.
Param value:
"u", "o", "s", "uo", "os",
"uos"
- type of holds to place
on job: u(ser), o(ther),
s(ystem).
RELEASE removes or releases
holds placed on jobs.
Param value:
"u", "o", "s", "uo", "os",
"uos"
- type of holds to remove
from job: u(ser), o(ther),
s(ystem).
SIGNAL sends a signal to the
executing job.
Param value:
"HUP", "SIGHUP",...
MODIFYATTR modifies the specified
attribute of the job to
the given value, when
the attrib_name is
!= "Resource_List" or
"resources_used".
Param value:
"attrib_name=value"
MODIFYRES modifies the job's
Resource_List
attribute given the
res_name and the
res_value:
Resource_List.res_name=
res_value
Param value:
"res_name=res_val"
param value depends on the action. Specify NULLSTR if no value for
this parameter is desired.
Return value: SUCCESS or FAIL.
NOTE: Any unrecognized action is ignored.
Example:
// run Job j synchronously
JobAction(j, SYNCRUN, NULLSTR);
// run Job j asynchronously on host "db"
JobAction(j, ASYNCRUN, "db");
// delete Job j
JobAction(j, DELETE, NULLSTR);
// delete Job j with a delay of 5 secs
// between the sending of SIGTERM and
// SIGKILL
JobAction(j, DELETE, "deldelay=5");
// rerun Job j
JobAction(j, RERUN, NULLSTR);
// place a u(ser) hold on Job j
JobAction(j, HOLD, "u");
// place an o(ther) hold on Job j
JobAction(j, HOLD, "o");
// place a s(ystem) hold on Job j
JobAction(j, HOLD, "s");
// place a default hold (u) on Job j
JobAction(j, HOLD, NULLSTR);
// release u(ser) hold from Job j
JobAction(j, RELEASE, "u");
// release o(ther) hold from Job j
JobAction(j, RELEASE, "o");
// release s(ystem) hold from Job j
JobAction(j, RELEASE, "s");
// release default hold (u) from Job j
JobAction(j, RELEASE, NULLSTR);
// send SIGHUP signal to Job j
JobAction(j, SIGNAL, "SIGHUP");
// update the comment attribute of Job
// j to "a message".
// The param format is: attribute_name=new_value
// Consult PBS documentation for a list of job
// attribute names that can be specified.
JobAction(j, MODIFYATTR, "comment=a message");
// update the Resource_List.cput attribute of Job
// j to 3600 seconds.
// The param format is: resource_name=new_value
// See pbs_resources* man page for a list of
// resource_names that can be specified.
JobAction(j, MODIFYRES, "cput=3600");
- QueJobFind(Que que,Fun Int func,Int cpr,Int
value);
- QueJobFind(Que que,Fun String func,Int cpr,String
value);
- QueJobFind(Que que,Fun DateTime func,Int cpr,DateTime
value);
- QueJobFind(Que que,Fun Size func,Int cpr,Size
value);
-
where cpr is one of: OP_EQ, OP_NEQ, OP_LE, OP_LT, OP_GE, OP_GT.
func is a function whose ONLY argument is of Job type. Job
is the return type.
Description: Applies func to every job in que , and return the
first job that satisfies the logical comparison: func(job) cpr
value
Example:
Size JobVirtualMemAvailGet(Job job)
{
Size sz;
sz = JobSizeResReqGet(job, "mem");
return(sz);
}
Int JobWallTimeReqGet(Job job)
{
Int wallt;
wallt = JobIntResReqGet(job, "walltime");
return(wallt);
}
Int JobCpuTimeUsedGet(Job job)
{
Int cput;
cput = JobIntResUseGet(job, "cput");
return(cput);
}
Que findQueByName(Set Que queues, String qname)
{
Que q;
foreach(q in queues) {
if( QueNameGet(q) EQ qname ) {
return(q);
}
}
return(NOQUE);
}
sched_main()
{
Server s;
Que que;
Set Que sq;
// get local server
s = AllServersLocalHostGet();
// get the queues of the Server s
sq = ServerQueuesGet(s);
// get the queue named "fast" from the
// local server
que = findQueByName( sq, "fast" );
// Find the 1st job whose walltime requirement
// is == 300s:
QueJobFind(que, JobWallTimeReqGet, OP_EQ, 300);
// Find the 1st job whose email address to
// notify about job activity != "bayucan":
QueJobFind(que, JobEmailAddrGet, OP_NEQ,
"bayucan");
// Find the 1st job that was created after
// or on 3/3/1997:
QueJobFind(que, JobDateTimeCreatedGet, OP_GE,
(3|3|1997));
// Find the 1st job that was created after
// 3:3:44:
QueJobFind(que, JobDateTimeCreatedGet, OP_GT,
(3:3:44));
// Find the 1st job that was created after
// 3:3:44 on 3/3/1997:
QueJobFind(que, JobDateTimeCreatedGet, OP_GT,
(3|3|1997@3:3:44));
// Find the 1st job whose cpu time used < 1600s:
QueJobFind(que, JobCpuTimeUsedGet, OP_LT, 1600);
// Find the 1st job whose virtual memory
// requirement <= 300mb:
QueJobFind(que, JobVirtualMemAvailGet, OP_LE,
300mb);
}
- Job QueJobFind( Que que, Fun Int func, Int cpr)
- Job QueJobFind( Que que, Fun String func, Int
cpr)
- Job QueJobFind( Que que, Fun DateTime func, Int
cpr)
- Job QueJobFind( Que que, Fun Size func, Int
cpr)
-
where cpr can be one of the following: OP_MAX, OP_MIN, func is
a function whose only argument is of Job type.
Description: Returns the Job with the max or min value found for
func(job) as it is applied to every job in que .
Example:
Int JobCpuTimeReqGet(Job job)
{
Int cput;
cput = JobIntResReqGet(job, "cput");
return(cput);
}
sched_main()
{
Que que;
Job job;
// Find the Job with the highest cpu time
// requirement:
job = QueJobFind(que, JobCpuTimeReqGet, OP_MAX);
// Find the Job with the minimum cpu time
// requirement:
job = QueJobFind(que, JobCpuTimeReqGet, OP_MIN);
}
- Que QueFilter(Que que,Fun Int func,Int cpr,Int
value)
- Que QueFilter(Que que,Fun String func,Int cpr,String
value)
- Que QueFilter(Que que,Fun DateTime func,Int cpr,Date
value)
- Que QueFilter(Que que,Fun Size func,Int cpr,Size
value)
-
where cpr can be one of the following: OP_EQ, OP_NEQ, OP_LE, OP_LT,
OP_GE, OP_GT, func is a function whose only argument is of Job
type.
Description: Applies func to every job in que , and returns a
new que containing all jobs that satisfies the comparison condition:
func(job) cpr value
Example:
Int JobWallTimeReqGet(Job job)
{
Int wallt;
wallt = JobIntResReqGet(job, "walltime");
return(wallt);
}
sched_main()
{
Que que;
Que newq;
// Returns a new que containing all jobs in "que"
// with a walltime requirement == 300s:
newq = QueFilter(que, JobWallTimeReqGet, OP_EQ, 300);
// Returns a new que containing all jobs in "que"
// with an email address != "bayucan":
newq = QueFilter(que, JobEmailAddrGet, OP_NEQ, "bayucan");
// Returns a new que containing all jobs in "que"
// created after or on 3/3/1997:
newq = QueFilter(que, JobDateTimeCreatedGet, OP_GE,
(3|3|1997));
// Returns a new que containing all jobs in "que"
// created after 3:3:44:
newq = QueFilter(que, JobDateTimeCreatedGet, OP_GT,
(3:3:44));
// Returns a new que containing all jobs in "que"
// created after 3:3:44 on 3/3/1997:
newq = QueFilter(que, JobDateTimeCreatedGet, OP_GT,
(3|3|1997@3:3:44));
// NOTE: The original "que" is not modified
// whatsoever.
}
- Int Sort(Set Job s, Fun Int key, Int order)
- Int Sort(Set Job s, Fun String key, Int order)
- Int Sort(Set Job s, Fun Float key, Int order)
- Int Sort(Set Job s, Fun DateTime key, Int
order)
- Int Sort(Set Job s, Fun Size key, Int order)
-
where s the set of jobs to sort. key is the sorting key which
is a function whose only argument is of Job type, order is the
sorting order: ASC, DESC.
Description: sorts the elements of s , in either ASCending or
DESCending order of values that were returned by the key function,
as applied to every member of the set of jobs. The s object is
modified with this call. This returns SUCCESS or FAIL depending on outcome
of the sort.
Examples:
Size JobMemReqGet(Job job)
{
Size mem;
mem = JobSizeResReqGet(job, "mem");
return(mem);
}
sched_main()
{
Server master;
Set Job jobs;
Int order;
// get local server
master = AllServersLocalHostGet();
jobs = ServerJobsGet(master);
Sort(jobs, JobPriorityGet, ASC);
Sort(jobs, JobIdGet, DESC);
order = ASC;
Sort(jobs, JobDateTimeCreatedGet, order);
order = DESC;
Sort(jobs, JobMemReqGet, order);
}
- Int Sort(Set Que s, Fun Int key, Int order)
- Int Sort(Set Que s, Fun String key, Int order)
- Int Sort(Set Que s, Fun Float key, Int order)
- Int Sort(Set Que s, Fun DateTime key, Int
order)
- Int Sort(Set Que s, Fun Size key, Int order)
-
where s the set of queues to sort. key is the sorting key
which is a function whose only argument is of Que type, order is
the sorting order: ASC, DESC.
Description: sorts the elements of s , in either ASCending or
DESCending order of values that were returned by the key function,
as applied to every member of the set of queues. The s object is
modified with this call. This returns SUCCESS or FAIL depending on outcome
of the sort.
Examples:
Size QueMemAvailGet(Que que)
{
Size mem;
mem = QueSizeResAvailGet(que, "mem");
return(mem);
}
sched_main()
{
Server master;
Set Que ques;
Int order;
// get local server
master = AllServersLocalHostGet();
ques = ServerQueuesGet(master);
Sort(ques, QuePriorityGet, ASC);
Sort(ques, QueNameGet, ASC);
order = DESC;
Sort(ques, QueMemAvailGet, order);
}
- Int Sort(Set Server s, Fun Int key, Int order)
- Int Sort(Set Server s, Fun String key, Int
order)
- Int Sort(Set Server s, Fun Float key, Int
order)
- Int Sort(Set Server s, Fun DateTime key, Int
order)
- Int Sort(Set Server s, Fun Size key, Int order)
-
where s the set of servers to sort. key is the sorting key
which is a function whose only argument is of Server type, order is
the sorting order: ASC, DESC.
Description: sorts the elements of s , in either ASCending or
DESCending order of values that were returned by the key function,
as applied to every member of the set of servers. The s object is
modified with this call. This returns SUCCESS or FAIL depending on outcome
of the sort.
Examples:
Size ServerMemAvailGet(Server serv)
{
Size mem;
mem = ServerSizeResAvailGet(serv, "mem");
return(mem);
}
sched_main()
{
Set Server sserver;
Int order;
Int ret;
sserver = AllServersGet();
ret = Sort(sserver, ServerMaxRunJobsGet, ASC);
Sort(sserver, ServerInetAddrGet, ASC);
order = DESC;
Sort(sserver, ServerMemAvailGet, order);
}
- Int Sort(Set CNode s, Fun Int key, Int order)
- Int Sort(Set CNode s, Fun String key, Int
order)
- Int Sort(Set CNode s, Fun Float key, Int order)
- Int Sort(Set CNode s, Fun DateTime key, Int
order)
- Int Sort(Set CNode s, Fun Size key, Int order)
-
where s the set of nodes to sort. key is the sorting key which
is a function whose only argument is of CNode type, order is the
sorting order: ASC, DESC.
Description: sorts the elements of s , in either ASCending or
DESCending order of values that were returned by the key function,
as applied to every member of the set of nodes. The s object is
modified with this call. This returns SUCCESS or FAIL depending on outcome
of the sort.
Examples:
Size CNodeMyMemAvailGet(CNode cn)
{
Size mem;
mem = CNodeMemAvailGet(cn, "virtual");
return(mem);
}
sched_main()
{
Set CNode scnode;
Int order;
scnode = AllNodesGet();
Sort(scnode, CNodeIdletimeGet, ASC);
Sort(scnode, CNodeNameGet, ASC);
order = DESC;
Sort(scnode, CNodeMyMemAvailGet, order);
}
The return values of the CNode..Get() functions discussed in the previous
section are obtained by sending resource queries to the CNode's MOM at every
scheduling iteration. For example, will return the value obtained from some
<host resource> query (this could be the string "loadave") as
sent to the node's MOM. The "<host resource> ->
CNode..Get()" mappings are established internally, but they can be
modified or more mappings can be added via the scheduler configuration file.
The config file is discussed in
pbs_sched_basl(8B).
Mappings already established are given in the following:
For all architectures:
CNode..Get() actual call host resource
======================== =============
CNodeOsGet(node) arch
CNodeLoadAveGet(node) loadave
CNodeIdletimeGet(node) idletime
pbs_sched_basl(8B) pbs_job_attributes(7B), pbs_queue_attributes(7B),
pbs_resources_irix5(7B), pbs_resources_sp2(7B), pbs_resources_sunos4(7B),
pbs_resources_unicos8(7B), pbs_server_attributes(7B), and pbs_server(8B),
pbs_resources_irix6(7B), pbs_resources_linux(7B).