1CLASSADS(1) HTCondor Manual CLASSADS(1)
2
6 classads - HTCondor Manual
7 The ClassAd language consists of two parts: structured data (called
9 "ClassAds"), and expressions.
10 HTCondor uses ClassAds to describe various things, primarily machines
12 and jobs; it uses expressions as constraints for querying ClassAds, and
13 for defining what it means for two ClassAds to match each other.
14
16 A ClassAd is a list of attribute-value pairs, separated by newlines.
17 Values may be booleans, integers, reals, strings, dictionaries, lists,
18 or the special values UNDEFINED and ERROR. Dictionaries are marked by
19 square brackets and lists by braces; dictionaries separate elements
20 with semicolons, and lists separate elements with commas.
21 attribute_name = "attribute-value"
23 pi = 3.141
24 count = 3
25 list = { "red", "green", "blue" }
26 dictionary = [ type = "complex"; real = 7.75; imaginary = -3 ]
27 structured_attr = [ hostnames = { "submit-1", "submit", "submit1" };
28 ip = "127.0.0.1"; port = "9618" ]
29 For the list of ClassAd attributes generated by HTCondor, see
31 https://htcondor.readthedocs.io/en/latest/classad-attributes/index.html.
32
34 An expression consists of literals (from the data syntax) and attribute
35 references composed with operators and functions. The value of a Clas‐
36 sAd attribute may be an expression.
37 MY.count < 10 && regexp( ".*example.*", attribute_name )
39 Attribute References
41 An attribute reference always includes an attribute name. In HTCondor,
42 when determining if two ClassAds match, an expression may specify which
43 ad's value is used by prefixing it with MY. or TARGET.. Attribute ref‐
44 erences are case-insensitive.
45 MY.count
47 TARGET.machine
48 An element of a dictionary is referenced by using the subscript opera‐
50 tor ([]) with an expression that evaluates to a string or with a dot
51 (.), as follows:
52 MY.structured_attr.hostnames
54 MY.structured_attr["hostnames"]
55 Note that the following references the attribute named by the attribute
57 hostnames, not the attribute named hostnames:
58 MY.structured_attr[hostnames]
60 List elements are referenced by an expression that evaluates to an in‐
62 teger, where the first element in the list is numbered 0. For example,
63 if colors = { [ x = "1" ], [ x = "2", y = "3" ] }, then MY.struc‐
64 ture_attr.colors[0] results in [ x = "1" ].
65 UNDEFINED and ERROR
67 The ClassAd language includes two special values, UNDEFINED and ERROR.
68 An attribute may be set to either explicitly, but these values typi‐
69 cally result from referring to an attribute that doesn't exist, or ask‐
70 ing for something impossible:
71 undefined_reference = MY.undefined_attribute
73 explicitly_undefined = UNDEFINED
74 one_error_value = "three" * 7
75 another_error_value = 1.3 / 0
76 Most expressions that refer to values that are UNDEFINED will evaluate
78 to UNDEFINED. The same applies to ERROR.
79 Operators
81 The operators *, /, + and - operate arithmetically, on integers and re‐
82 als.
83 The comparison operators ==, !=, <=, <, >= and > operate on booleans,
85 integers, reals and strings. String comparison is case-insensitive.
86 Comparing a string and a non-string value results in ERROR.
87 The special comparison operator =?= is like == except in the following
89 two ways: it is case-sensitive when comparing strings; and, when com‐
90 paring values to UNDEFINED, results in FALSE instead of UNDEFINED. (If
91 comparing UNDEFINED to itself, the operator =?= results in TRUE).
92 The special comparison operator =!= is the negation of =?=.
94 The logical operators && and || operate on integers and reals; non-zero
96 is true, and zero is false.
97 The ternary operator x ? y : z operates on expressions.
99 The default operator x ?: z returns x if x is defined and z otherwise.
101 The IS and ISNT operators are synonyms for =?= and =!=.
103 Functions
105 Function name are case-insensitive. Unless otherwise noted, if any of
106 a function's arguments are UNDEFINED or ERROR, so is the result. If an
107 argument's type is noted, the function will return ERROR unless the ar‐
108 gument has that type.
109 integer INT( expr )
111 If expr is numeric, return the closest integer. If expr evalu‐
112 ates to a string, attempt to convert the string to an integer.
113 Return ERROR if the string is not an integer, or if expr is nei‐
114 ther numeric nor a string.
115 boolean MEMBER( expr, list l )
117 Returns TRUE if expr is equal, as defined by the operator ==, to
118 any member of the list l, or FALSE if it isn't.
119 boolean REGEXP( string pattern, string target[, string options] )
121 Return TRUE if the PCRE regular expression pattern matches tar‐
122 get, or FALSE if it doesn't. Return ERROR if pattern is a not a
123 valid regular expression. If specified, options is a PCRE op‐
124 tion string (one or more of f, i, s, m, and g). See the
125 Specification section for details.
126 list SPLIT( string s[, string tokens ] )
128 Separate s by whitespace or comma, or instead by any of the
129 characters in tokens, if specified, and return the result as a
130 list of strings.
131 boolean STRINGLISTIMEMBER( string s, string list[, string tokens] )
133 Equivalent to MEMBER( *s*, SPLIT( *list*, *tokens* )).
134 string SUBSTR( string s, integer offset[, integer length] )
136 Returns the substring of s from offset to the end of the string,
137 or instead for length characters, if specified. The first char‐
138 acter in s is at position 0. If offset is negative, the sub‐
139 string begins offset characters before the end of the string.
140 If length is negative, the substring ends that many characters
141 before the end of the string. If the substring contains no
142 characters, return the empty string. Thus, the following two
143 calls both return the string "78":
144 substr( "0123456789", 7, 2 )
146 substr( "0123456789", -3, -1 )
147 All ClassAd functions are defined in the references below.
149 Reserved Words
151 The words UNDEFINED, ERROR, IS, ISNT, TRUE, FALSE, MY, TARGET, and PAR‐
152 ENT may not be used as attribute names.
153
155 Use classad_eval to test ClassAd expressions. For instance, if you
156 want to test to see if a regular expression matches some fixed string,
157 you could check in the following way (on Linux or Mac; the quoting
158 rules are different on Windows):
159 $ classad_eval 'regexp( ".*tr.*", "string" )'
161 [ ]
162 true
163 This prints out the ClassAd used as context in the evaluation (in this
165 case, there wasn't one, so it's the empty ad) and the result.
166
168 These examples assume a Linux shell environment and a working HTCondor
169 pool.
170 Selecting a Slot based on Job ID
172 If job 288.7 is running:
173 $ condor_status -const 'JobId == "288.7"'
175 Selecting Jobs based on Execute Machine
177 If jobs are running on the machine example-execute-node:
178 $ condor_q -all -const 'regexp( "@example-execute-node$", RemoteHost )'
180 String Manipulation
182 In this example, an administrator has just added twelve new hosts to
183 the pool -- compute-296 to compute-307 -- and wants to see if they've
184 started running jobs yet.
185 $ condor_status -const '296 <= int(substr( Machine, 8 )) && int(substr( Machine, 8 )) <= 307'
187 You could also write this as follows:
189 $ condor_status -const '296 <= int(split(Machine, "-")[1]) && int(split(Machine, "-")[1]) <= 307'
191 Selecting Machines with a Particular File-Transfer Plugin
193 If you're considering using the gdrive file-transfer plugin, and you'd
194 like to see which machines have it, select from the slot ads based on
195 the corresponding attribute, but only print out the machine name, and
196 then throw away the duplicates:
197 $ condor_status -af Machine \
199 -const 'StringListIMember( "gdrive", HasFileTransferPluginMethods )' \
200 | uniq
201 You could instead use a constraint to ignore dynamic slots for a report
203 on the resources available to run jobs which require the gdrive plugin.
204 Note that you can also use expressions when formatting the output. In
205 this case, it's just to make the output prettier.
206 $ condor_status -af Machine CPUs Memory Disk \
208 '(GPUs =!= undefined && GPUs >= 1) ? CUDACapability : "[no GPUs]"' \
209 -const 'SlotType =!= "Dynamic" && StringListIMember( "gdrive", HasFileTransferPluginMethods )'
210
212 For use in HTCondor, including a complete list of functions, see
213 https://htcondor.readthedocs.io/en/latest/classads/classad-mechanism.html.
214 For the language specification, see
216 https://research.cs.wisc.edu/htcondor/classad/refman/.
217
219 Center for High Throughput Computing, University of Wisconsin-Madison
220
222 Copyright © 1990-2019 Center for High Throughput Computing, Computer
223 Sciences Department, University of Wisconsin-Madison, Madison, WI. All
224 Rights Reserved. Licensed under the Apache License, Version 2.0.
225
227 HTCondor Team
228
230 1990-2023, Center for High Throughput Computing, Computer Sciences De‐
231 partment, University of Wisconsin-Madison, Madison, WI, US. Licensed
232 under the Apache License, Version 2.0.
233 Oct 02, 2023 CLASSADS(1)