1pbs_selectjob(3B) PBS pbs_selectjob(3B)
2
6 pbs_selectjob - select pbs batch jobs
7
9 #include <pbs_error.h>
10 #include <pbs_ifl.h>
11 char **pbs_selectjob(int connect, struct attropl *attrib, char *extend)
13
15 Issue a batch request to select jobs which meet certain criteria.
16 pbs_selectjob() returns a array of job identifiers which met the crite‐
17 ria.
18 Initially all batch jobs are selected for which the user is authorized
20 to query status. This set may be reduced or filtered by specifying
21 certain attributes of the jobs.
22 A Select Jobs batch request is generated and sent to the server over
24 the connection specified by connect which is the return value of
25 pbs_connect().
26 The argument, attrib, is a pointer to an attropl structure which is
28 defined in pbs_ifl.h as:
29 struct attropl {
31 struct attropl *next;
32 char *name;
33 char *resource;
34 char *value;
35 enum batch_op op;
36 };
37 The attrib list is terminated by the first entry where next is a null
39 pointer.
40 The name member points to a string which is the name of the attribute.
42 Not all of the job attributes may be used as a selection criteria. The
43 resource member points to a string which is the name of a resource.
44 This member is only used when name is set to ATTR_l. Otherwise,
45 resource should be a pointer to a null string. The value member points
46 to a string which is the value of the attribute or resource. The
47 attribute names are defined in pbs_ifl.h:
48 #define ATTR_a "Execution_Time"
50 Select based upon the job's execution time.
51 #define ATTR_A "Account_Name"
53 Select (E) based upon the account string.
54 #define ATTR_c "Checkpoint"
56 Select based upon the checkpoint interval.
57 #define ATTR_e "Error_Path"
59 Select (E) based upon the name of the standard error
60 file.
61 #define ATTR_g "Group_List"
63 Select (E) based upon the list of group names under which
64 the job may execute.
65 #define ATTR_h "Hold_Types"
67 Select (E) based upon the hold types.
68 #define ATTR_j "Join_Paths"
70 Select (E) based upon the value of the join list.
71 #define ATTR_k "Keep_Files"
73 Select (E) based upon the value of the keep files list.
74 #define ATTR_l "Resource_List"
76 Select based upon the value of the resource named in
77 resource.
78 #define ATTR_m "Mail_Points"
80 Select (E) based upon the setting of the mail points
81 attribute.
82 #define ATTR_M "Mail_Users"
84 Select (E) based upon the list of user names to which
85 mail will be sent.
86 #define ATTR_N "Job_Name"
88 Select (E) based upon the job name.
89 #define ATTR_o "Output_Path"
91 Select (E) based upon the name of the standard output
92 file.
93 #define ATTR_p "Rriority"
95 Select based upon the priority of the job.
96 #define ATTR_q "destination"
98 Select based upon the specified destination. Jobs
99 selected are restricted to those residing in the named
100 queue. If destination is the null string, the default
101 queue at the server is assumed.
102 #define ATTR_r "Rerunable"
104 Select (E) based upon the rerunable flag.
105 #define ATTR_session "session_id"
107 Select based upon the session id assigned to running
108 jobs.
109 #define ATTR_S "Shell_Path_List"
111 Select (E) based upon the execution shell list.
112 #define ATTR_u "User_List"
114 Select (E) based upon the owner of the jobs.
115 #define ATTR_v "Variable_List"
117 Select (E) based upon the list of environment variables.
118 #define ATTR_ctime "ctime"
120 Select based upon the creation time of the job.
121 #define ATTR_depend "depend"
123 Select based upon the list of job dependencies.
124 #define ATTR_mtime "mtime"
126 Select based upon the last modification time of the job.
127 #define ATTR_qtime "qtime"
129 Select based upon the time of the job was placed into the
130 current queue.
131 #define ATTR_qtype "queue_type"
133 Select (E) base on the type of queue in which the job
134 resides.
135 #define ATTR_stagein "stagein"
137 Select based upon the list of files to be staged-in.
138 #define ATTR_stageout "stageout"
140 Select based upon the list of files to be staged-out.
141 #define ATTR_state "job_state"
143 Select based upon the state of the jobs. State is not a
144 job attribute, but is included here to allow selection.
145 The op member defines the operator in the logical expression:
147 value operator current_value
148 The logical expression must evaluate as true for the job to be
149 selected. The permissible values of op are defined in pbs_ifl.h as:
150 enum batch_op { ..., EQ, NE, GE, GT, LE, LT, ... };. The attributes
151 marked with (E) in the description above may only be selected with the
152 equal, EQ, or not equal, NE, operators.
153 If attrib itself is a null pointer, then no selection is done on the
155 basis of attributes.
156 The return value is a pointer to a null terminated array of character
158 pointers. Each character pointer in the array points to a character
159 string which is a job_identifier in the form: sequence_num‐
160 ber.server@server
161 The array is allocated by pbs_selectjob via malloc(). When the array
163 is no longer needed, the user is responsible for freeing it by a call
164 to free().
165 The parameter, extend, is reserved for implementation defined exten‐
167 sions. TORQUE 2.0.0p1 added the #define'd constant string EXECQUEONLY
168 to only retrieve jobs in execution queues.
169
171 qselect(1B), pbs_alterjob(3B), and pbs_connect(3B)
172
174 When the batch request generated by pbs_selectjob() function has been
175 completed successfully by a batch server, the routine will return a
176 pointer to the array of job identifiers. If no jobs met the criteria,
177 the first pointer in the array will be the null pointer.
178 If an error occurred, a null pointer is returned and the error is
180 available in the global integer pbs_errno.
181Local pbs_selectjob(3B)