Provided by: torque-client_2.4.16+dfsg-1.3ubuntu1.1_amd64 bug

NAME

       basl2c - converts a BASL (BAtch Scheduling Language) code into a C scheduler code.

SYNOPSIS

       basl2c   [-d]   [-l   lexerDebugFile]   [-p   parserDebugFile]  [-y  symtabDebugFile]  [-s
       semanticDebugFile] [-g codegenDebugFile] [-c cFile] baslFile

DESCRIPTION

       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 baslFile, 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
       pbs_sched.c.

       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 pbs_sched
       executable.

OPTIONS

       -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
            lexerDebugFile is the name of a file to write into the debugging  messages  generated
            while scanning for tokens.

       -p parserDebugFile
            parserDebugFile  is the name of a file to write into the debugging messages generated
            while putting together tokens in a usable way.

       -y symtabDebugFile
            symtabDebugFile is the name of a file to write into the debugging messages related to
            the symbol table.

       -s semanticDebugFile
            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
            codegenDebugFile is the name of a file to write into the debugging messages generated
            while converting BASL statements to C statements.

       -c cFile
            cFile is the name of a file where the generated C code is written into.

MAIN STRUCTURE

       The basic structure of a scheduler code written in BASL is as follows:
               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);
               }

       sched_main() is the function that gets called at every scheduling iteration.

FUNCTIONS

       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 );

       basl2c 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
       printStuff, 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 .

VARIABLE DECLARATIONS

       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.

DATA TYPE

       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

BASL-DEFINED CONSTANTS

       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

IDENTIFIER

       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.

STATEMENTS

       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 STATEMENTS 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:
                        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 basl2c  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

OPERATOR PRECEDENCE AND ASSOCIATIVITY

       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

PREDEFINED FUNCTIONS

       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 resources_available.name 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 resources_available.name 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 resources_available.name 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  resources_assigned.name  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  resources_assigned.name  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  resources_assigned.name  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 resources_available.name 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 resources_available.name 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 resources_available.name 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 resources_assigned.name 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  resources_assigned.name  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  resources_assigned.name  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  Resource_List.name  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  Resource_List.name  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  Resource_List.name  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
                            resources_used.name 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
                            resources_used.name 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
                            resources_used.name 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);
                              }

CNode..Get() FUNCTIONS

       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,  CNodeLoadAveGet(node)  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

SEE ALSO

       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).