Table of Content  Branch Up  

Command general format

A legal command has the following format:

    COMMAND ARGUMENTS

COMMAND is one of the following words:

    find
    set
    login
    logout
    help

'find' is the default command. If no command is given, command 'find' will be assumed.

ARGUMENTS is a sequence of none or more words separate by white spaces. Its format varies depending on the command.

The 'find' command has the following format:

    find OBJECT ARGS JOIN EXPRESSION

as for example:

--> find wire orange at rack RK-27

OBJECT is the kind of element we want in the result. It can be one of the following:

   location
   device
   wire

In the example above, 'wire' is an OBJECT.

ARGS is a list of attributes this object possesses. In the above example 'orange' is an argument referring the wire's color.

The arguments list can be longer, for example:

--> find wire AES orange at rack RK-27

where the second argument, AES, refers to the signal type carried by resulting wires. The Search Engine knows in advance what wire colors, signal types etc. are available, hence it will not get confused.

OBJECT ARGS as a whole comprises what we call an "expression". JOIN is a keyword connecting EXPRESSIONS. Hence, a more generic definition of the find command format is:

   find EXPRESSION JOIN EXPRESSION

In the above example, 'at' is a JOIN connecting the expressions 'wire AES orange' and 'rack RK-27'.

JOIN is one of the following keywords:

    at
    with

The right hand EXPRESSION expresses more specific conditions about the left hand EXPRESSION.

The following examples illustrates the use of the JOIN 'with'.

--> find device frame with VDA 7700ADA
--> find location room with desk

In the first example, we try to find devices of type frame containing devices type VDA model 7700ADA. Again, the Search Engine has knowledge of these words ("frame", "VDA", "7700ADA") and what they mean.

In the second example, we look for rooms having desks inside.

Both, 'at' and 'with', express inclusion but in opposite directions:

    EXP1 at EXP2

means that objects in EXP1 are contained into those of EXP2, while

    EXP1 with EXP2

means that objects in EXP2 are contained into those of EXP1.

We mentioned that 'find' is the default command. This means that we don't actually need to write that word in the Search Box. The following expression is equivalent to our last example:

--> device frame with VDA 7700ADA

Likewise, object names can be omitted if the arguments are not ambiguous. In this example, 'frame' is clearly a device. The following expression yields to the same result:

--> frame with VDA 7700ADA

In general we can always omit the command 'find' and we can also omit the OBJECT in cases when it can be implied from the argument's list. If the omitted object can not be implied, objects of all kinds (location, device, wire) will be returned.

Objects can also be implied by the expression's pattern. That is the case of wire numbers and location numbers.

The following entry:

--> C-123

Is equivalent to this:

--> find wire C-123

because the object 'wire' is directly implied from the argument's format.

Similarly, the following two entries are equivalent:

--> RK-27
--> find location rack RK-27

The following expression,

--> obsolete at rack RK-27

will return all devices and wires with status 'obsolete' found in rack RK-27. This is a case when the object has been omitted and can not be implied from the arguments list.

It follows from the previous discussion that expressions can be reduced to a list of objects (location, device, wire) since, ultimately, they describe nothing but objects. At this point we will add that EXPRESSION JOIN EXPRESSION is also an EXPRESSION. We call this a joint expression.

Joint expressions permits to construct more complex entries, recursively, as, for example:

--> wire orange at frame with device ADA at rack RK-27

This joint expression attempts to find orange wires in all frames located in rack RK-27 that happens to have ADA devices inside.

Notice that the first JOIN (at) defines two expressions, but the one to the right is a joint expression (frame with device...) which is turn contains another joint expression (device ADA at rack RK-27).

We can extend this recursion indefinitely to obtain more accurate results, as long as the expression as a whole makes sense to the user.

Some elements have textual descriptions (strings) we may want to search for, such as "Final DA" or "Roof CAM". By surrounding those strings with quotes, we make clear those are strings proper, not keywords.

Here is an example:

--> FS1 "Roof CAM"

This expression is asking for a device model FS1 which description field is exactly "Roof CAM".

We can omit the quotes, but that may yield to a different result because 'CAM' will be interpreted a as a type of device.

We can also use quotes around keywords such as command or object names to mean they are not keywords but strings. For example,

--> "wire" at RK-27

is asking for any object at RK-27 which description string is exactly "wire". Without quotes, 'wire' would be the wire object.

--> device "preliminary"

will look for a device having the string "preliminary" in its description field, and not for devices which status is 'preliminary'.

If a keyword if found in the "wrong" place, it will be assumed as a single-word quoted string. For example,

--> wire find

will look for wires with the word "find" in its label field, same as:

--> wire "find"

This rule applies to any keyword found in non expected places.

Strings within quotes ask for exact matches. Some times, however, we want to give only a substring of the intended match. The asterisk if employed in these cases, as illustrated in the following example:

--> find device "roof*"

The asterisk (*) represents any possible string placed in its position. In the example, the string "roof cam" will match the inquiry.

Asterisks can be used with or without quotes. The following examples are equivalent to the previous one.

--> find device "roof"*
--> find device roof*

The use of quotes and asterisk together is better justified in cases where the substring contains more that one word, as for example:

--> find device "digital video *"

possibly intended to match "digital video HD" and "digital video SD".

We can place more that one asterisk in the string. For example,

--> find device "*-SDI *PUT"

will match any of the following values:

   SD-SDI INPUT
   SD-SDI OUTPUT
   HD-SDI INPUT
   HD-SDI OUTPUT

Any attribute is of certain "type". For example, a wire argument 'orange' if of type color. In all of the examples seen so far, we have implied the attribute type from its value. However we can write this type explicitly in front of the intended attribute. For example,

--> find wire color orange

This can be useful to disambiguate argument values. Say for instance, we have expressed our status in terms of colors instead of descriptive words. Under this circumstances, the expression

--> wire orange

could express either cables of color 'orange' or with status 'orange'. To disambiguate, we need to preceed the argument with a keyword expressing its type.

--> wire color orange

or

--> wire status orange

The keyword expressing the attribute's type (color, status in the example) is called a qualifier.

Argument types are directly related to the database fields holding the information we look for. Therefor, pertinent qualifiers depends on the object type.

Qualifiers for locations are:

... pending ...

Qualifiers for devices are:

... pending ...

Qualifiers for wires are:

... pending ...

Logical operations AND, OR, NOT apply to elements in any arguments list. For example, we may want to look for wires which status is 'preliminary' and its color is 'orange' (logical AND), or we may want to find wires that are either 'preliminary' or 'orange' (logical OR').

AND is assumed if no other operator is present, meaning that arguments separated just by white spaces are and-ed together. For example,

--> wire AES blue

means objects wire that are both color 'blue' and signal type AES.

The OR operator is denoted with a comma. For example,

--> wire AES, blue

will return all wires that are either color blue or carry AES signals.

The NOT operator is denoted by the keyword 'not' preceding the word. For example,

--> wire AES not orange

means any wire carrying AES signal which color is any but 'orange'.

Logical operators can also appear preceding JOINs in which case they will affect the whole right hand EXPRESSION.

Examples:

--> wire AES not at RK-27

will return all AES wires placed elsewhere except in RK-27.

--> wire AES , at RK-27

will return all AES wires as well as wires of any kind located in RK-27,

--> device frame not with VDA at RK-27 obsolete

will return all frame devices except those marked as obsolete and containing VDA cards.