1pbs_selstat(3B) PBS pbs_selstat(3B)
2
6 pbs_selstat - obtain status of selected pbs batch jobs
7
9 #include <pbs_error.h>
10 #include <pbs_ifl.h>
11 struct batch_status *pbs_selstat(int connect, struct attropl *sel_list,
13 char *extend)
14 void pbs_statfree(struct batch_status *psj)
16
18 Issue a batch request to examine the status of jobs which meet certain
19 criteria. pbs_selstat() returns a list of batch_status structures for
20 those jobs which met the selection criteria.
21 This function is a combination of pbs_selectjobs() and pbs_statjob().
23 It is an extension to the POSIX Batch standard.
24 Initially all batch jobs are selected for which the user is authorized
26 to query status. This set may be reduced or filtered by specifying
27 certain attributes of the jobs.
28 A Select Status batch request is generated and sent to the server over
30 the connection specified by connect which is the return value of
31 pbs_connect().
32 The parameter, sel_list, is a pointer to an attropl structure which is
34 defined in pbs_ifl.h as:
35 struct attropl {
37 struct attropl *next;
38 char *name;
39 char *resource;
40 char *value;
41 enum batch_op op;
42 };
43 The sel_list list is terminated by the first entry where next is a null
45 pointer.
46 The name member points to a string which is the name of the attribute.
48 Not all of the job attributes may be used as a selection criteria. The
49 resource member points to a string which is the name of a resource.
50 This member is only used when name is set to ATTR_l, otherwise it
51 should be a pointer to a null string. The value member points to a
52 string which is the value of the attribute or resource. The attribute
53 names are defined in pbs_ifl.h:
54 #define ATTR_a "Execution_Time"
56 Select based upon the job's execution time.
57 #define ATTR_A "Account_Name"
59 Select (E) based upon the account string.
60 #define ATTR_c "Checkpoint"
62 Select based upon the checkpoint interval.
63 #define ATTR_e "Error_Path"
65 Select (E) based upon the name of the standard error
66 file.
67 #define ATTR_g "Group_List"
69 Select (E) based upon the list of group names under which
70 the job may execute.
71 #define ATTR_h "Hold_Types"
73 Select (E) based upon the hold types.
74 #define ATTR_j "Join_Paths"
76 Select (E) based upon the value of the join list.
77 #define ATTR_k "Keep_Files"
79 Select (E) based upon the value of the keep files list.
80 #define ATTR_l "Resource_List"
82 Select based upon the value of the resource named in
83 resource.
84 #define ATTR_m "Mail_Points"
86 Select (E) based upon the setting of the mail points
87 attribute.
88 #define ATTR_M "Mail_Users"
90 Select (E) based upon the list of user names to which
91 mail will be sent.
92 #define ATTR_N "Job_Name"
94 Select (E) based upon the job name.
95 #define ATTR_o "Output_Path"
97 Select (E) based upon the name of the standard output
98 file.
99 #define ATTR_p "Priority"
101 Select based upon the priority of the job.
102 #define ATTR_q "destination"
104 Select based upon the specified destination. Jobs
105 selected are restricted to those residing in the named
106 queue. If destination is the null string, the default
107 queue at the server is assumed.
108 #define ATTR_r "Rerunable"
110 Select (E) based upon the rerunable flag.
111 #define ATTR_session "session_id"
113 Select based upon the session id assigned to running
114 jobs.
115 #define ATTR_S "Shell_Path_List"
117 Select (E) based upon the execution shell list.
118 #define ATTR_u "User_List"
120 Select (E) based upon the owner of the jobs.
121 #define ATTR_v "Variable_List"
123 Select (E) based upon the list of environment variables.
124 #define ATTR_ctime "ctime"
126 Select based upon the creation time of the job.
127 #define ATTR_depend "depend"
129 Select based upon the list of job dependencies.
130 #define ATTR_mtime "mtime"
132 Select based upon the last modification time of the job.
133 #define ATTR_qtime "qtime"
135 Select based upon the time of the job was placed into the
136 current queue.
137 #define ATTR_qtype "queue_type"
139 Select (E) base on the type of queue in which the job
140 resides.
141 #define ATTR_stagein "stagein"
143 Select based upon the list of files to be staged-in.
144 #define ATTR_stageout "stageout"
146 Select based upon the list of files to be staged-out.
147 #define ATTR_state "job_state"
149 Select based upon the state of the jobs. State is not a
150 job attribute, but is included here to allow selection.
151 The op member defines the operator in the logical expression:
153 value operator current_value
154 The logical expression must evaluate as true for the job to be
155 selected. The permissible values of op are defined in pbs_ifl.h as:
156 enum batch_op { ..., EQ, NE, GE, GT, LE, LT, ... };. The attributes
157 marked with (E) in the description above may only be selected with the
158 equal, EQ, or not equal, NE, operators.
159 If sel_list itself is a null pointer, then no selection is done on the
161 basis of attributes.
162 The return value is a pointer to a list of batch_status structures or
164 the null pointer if no jobs can be queried for status. The batch_sta‐
165 tus structure is defined in pbs_ifl.h as
166 struct batch_status {
168 struct batch_status *next;
169 char *name;
170 struct attrl *attribs;
171 char *text;
172 }
173 The entry, attribs, is a pointer to a list of attrl structures defined
175 in pbs_ifl.h as:
176 struct attrl {
178 struct attrl *next;
179 char *name;
180 char *resource;
181 char *value;
182 };
183 It is up the user to free the list of batch_status structures when no
185 longer needed, by calling pbs_statfree().
186 The parameter, extend, is reserved for implementation defined exten‐
188 sions. TORQUE 2.0.0p1 added the #define'd constant string EXECQUEONLY
189 to only retrieve jobs in execution queues.
190
192 qselect(1B), pbs_alterjob(3B), pbs_connect(3B), pbs_statjob(3B), and
193 pbs_selectjob(3B).
194
196 When the batch request generated by pbs_selstat() function has been
197 completed successfully by a batch server, the routine will return a
198 pointer to the list of batch_status structures. If no jobs met the
199 criteria or an error occurred, the return will be the null pointer. If
200 an error occurred, the global integer pbs_errno will be set to a non-
201 zero value.
202Local pbs_selstat(3B)