Query: advanced search, command line: function calls available

Functions listed below can be called from a query expression.

List manipulation

llen(lst)

Determine length of a list.

Arguments:

Return value: integer length of the list.

mklist(args...)

Create a list of the objects passed.

Arguments:

Variable number of objects.

Return value: the list.

layerlist()

Returns a list of all layers.

Math & abstract geometry

distance(x1, y1, x2, y2)

Calculate the distance of two points.

Arguments:

Return value: floating point distance value in nanometers.

abs(number)

Returns the absolute value of a number

int(arg)

Returns the argument converted to an integer (truncating floating point numbers)

double(arg)

Returns the argument converted to a double precision number.

Object geometry

overlap(obj1, obj2, [bloat])

Returns 1 if obj1 and obj2 overlap (even if they are on different layers)

Arguments:

Return value: 1 for overlap, 0 for no overlap.

intersect(obj1, obj2, [bloat])

Returns 1 if obj1 and obj2 intersect (must share a layer)

Arguments:

Return value: 1 for intersection, 0 for no overlap.

pstkring(pstk, minimum_ring_thickness)

Return the number of layers on which the ring of a padstack is too thin.

Arguments:

Return value: negative on wrong arguments, 0 if the padstack does not violate the minimum_ring_thickness requirement, positive integer (number of violations) otherwise.

Networks

netlist()

Return the netlist.

Arguments: None.

Return value: an unordered list of all networks specified on the edited netlist (which is the netlist the board is currently using). Each item of the list is a net.

netterms(net)

Return terminals of a network.

Arguments:

Return value: an unordered list of objects (each terminal of the network as described by the edited netlist).

netobjs(net)

Return terminals and all copper objects galvanically connected to a network.

Arguments:

Return value: an unordered list of copper objects connected to the network.

netsegs(net)

Return a list of objects, one terminal object per disconnecte segment of the network.

Arguments:

Return value: an unordered list of terminal objects, one picked randomly from each disconnected segment of the net.

netbreak(obj, minimum_overlap)

Start a search on a galvanically connected network segment starting from an object (typically returned by netsegs()) and generate a DRC violation if there are copper objects with overlap smaller than the minimum_overlap.

Arguments:

Return value: a list that represents a DRC violation (or empty list).

netshort(obj, minimum_distance)

Start a search on a galvanically connected network segment starting from an object (typically returned by netsegs()) and generate a DRC violation if there are disconnected copper objects with distance smaller than the minimum_distance from the network.

Arguments:

Return value: a list that represents a DRC violation (or empty list).

netlen(net)

Return the length of a 2-terminal network.

Arguments: net object or net name.

Return value: network length.

Object accessors

subcobjs(subc)

Return a list of objects that are within the subc.

Arguments:

Return value: an unordered list of objects.

poly_num_islands(poly)

Return the number of visible polygon islands.

Arguments:

Return value: 0 if the polygon has been cleared out of existnece, 1 for normal polygons and a positive integer higher than 1 if the polygon has the FULLPOLY flag and is sliced into multiple parts not naturally connected by the polygon itself.

thermal_on(tobj, lobj)

Return a string description of thermals of tobj on layer corrseponding to lobj.

Arguments:

Return value: a string that consists of:

obj_by_idpath(idpath)

Returns the object addressed by idpath.

Arguments:

Return value: the addressed object or void.

poly_is_valid(obj)

Returns true if obj is a polygon and has a valid contour. Returns false if obj is a polygon with an invalid contour (e.g. self-intersecting).

Arguments:

Return value: 0 or 1 indicating the validity of the polygon.

text_invalid_chars(obj)

Returns the number of invalid characters of a text object. An invalid character is not rendering with the current font of the text (it is out of range or the font does not have a symbol for the character).

Arguments:

Return value: a positive integer; 0 means all characters would render properly

Advanced layer access

layer_setup(obj, directive [, res])

Takes an object and executes a directive on the layer setup of the object. If the directive matches, retruns either a measure (if result is specified) or returns true.

Directive is a comma separated list of requirements; the directive matches only if all requirements matched. A requirement is specified in the form of key:value.

Key is a dash separated list of:

Examples requirements:

"Above" and "below" are not in the board's coordinate system, but are relative to the object. In other words, the function first assumes above is upward and below is downward, then runs all requirements on the object. If there is no match, above/below directions are reversed and the test is ran again.

Example directive:

above-type:!copper,below-net:gnd,below-netmargin:125mil

This directive requires:

Normally the return value is integer 0 (no match) or 1 (match).

If the optional res parameter is specified, it must be a requirement where key is result. Alternatively the result requirement can be specified in the directive parameter. When a result is specified, the return value of layer_setup() will not be a 0/1 boolean but a readout specified by the result requirement (or the invalid value is returned on no match). The value of a result requirement is one of:

Complex query script example:

layer_setup(OBJ, "above-type:!copper,below-net:gnd", "result:below-substrate").a."thickness"

OBJ will match if it is on the top or bottom copper layer and is fully covered by gnd copper on the adjacent copper layer group on the next internal copper layer group. When matched, the return value of layer_setup is the substrate layer group between the object's layer and that adjacent internal layer group. The .a."thickness" part retrieves the value of the thickness attribute of this substrate layer. On mismatch, the whole expression evaluates to the invalid value.

Misc

action(args...)

Execute a pcb-rnd action.

Arguments: variable nunmber of objects and constants.

Return value: invalid on error, or the return value of the action.

coord(str)

Converts str to coordinates. Useful when using attribute values.

Arguments:

Return value: integer length of the list.

isvoid(value)

Checks whether value is void (invalid).

Arguments:

Return value: 1 if value is void (invalid), 0 otherwise.

getconf(path)

Fetch the value of a config node

Arguments:

Return value: invalid if the config node doesn't exist, else the value of the config node (converted to the most appropriate data type).

violation(i1, v1, ..., iN, vN)

Build a DRC violation report (a list object).

Arguments (a variable number of pairs of instruction and value):

Instruction is one of the following constants:

Return value: a list suitable for the drc_query to process.