<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_help_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{uQueryDB: Querying the MOOSDB from the Command Line}
\vspace{0.1in}
\labdate{June 2018}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labsrc{project-pavlab/appdocs/app\_uquerydb} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UQueryDB}
\wikidoc{bugz=uQueryDB}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_uqdb_overview}
%\index{uQueryDB}

The \app{uQueryDB} utility is a command-line tool for querying a
MOOSDB with a logic condition provided on the command line.  It finds
the MOOSDB via a mission file provided on the command line, or the IP
address and port number given on the command line. It will connect to
the DB, register for the variables involved in the logic condition and
determine if the condition holds. It will then exit with 0 if it holds
or 1 otherwise.  It will return its value as soon as the app has
received mail for all variables involved in the logic
condition. Otherwise it will wait for 10 seconds. This can be changed
with the \var{--wait=N} parameter. If a variable in the logic
condition is unknown to the MOOSDB, then the whole condition will fail
after the wait period.

\pskip

\noindent
The motivation for \app{uQueryDB} is to facilitate automated testing
of missions launched from within a shell script, by checking for
termination criteria and automatically halting the test mission.

%=================================================================
\subsection{A Simple Example}

As a simple example, try launching the alpha mission in the \var{s1\_alpha}
example mission folder. From the command line, launch with:

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp/ivp/missions/s1_alpha
 $ ./launch.sh
\end{consoleverb}
\vspace{0.1in}

\noindent
Once this simulation has started, deploy the vehicle with the button
on the viewer. At this point we can try out the \app{uQueryDB} utility.
In another terminal window try typing: 

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp/ivp/missions/s1_alpha
 $ uQueryDB alpha.moos --condition="DB_UPTIME&lt;130" 
\end{consoleverb}
\vspace{0.1in}

\noindent
This will check the value of the MOOS variable \mvar{DB\_UPTIME} which
is the number of seconds that the MOOSDB has been up. The above check
will simply report success until after 130 seconds has passed. The
report comes in human-readable form in the terminal output:

\vspace{0.1in}
\begin{consoleverb}
$ uQueryDB alpha.moos --condition="DB_UPTIME&lt;130"
Mission File was provided: alpha.moos
Condition: [DB_UPTIME&lt;130]

-------------- moos connect ----------------------
  contacting a MOOS server localhost:9000 -  try 00001 
  Handshaking as uQueryDB               [ok]
  DB reports async support is           [on]
  DB is running on                      leonardo
  Timing skew estimation is             [off] (not needed)
--------------------------------------------------

uQueryDB is Running:
 |-Baseline AppTick   @ 5.0 Hz
 |--Comms is Full Duplex and Asynchronous
 -Iterate Mode 0 :
   |-Regular iterate and message delivery at 5 Hz

==============================================================
uQueryDB alpha                                          0/0(1)
==============================================================
Config:
  m_sServerHost: localhost
  m_lServErport: 9005
  Max Time:      n/a
State:           
  Start Time:    1640112857.63442
  Curr Time:     1640112857.83831
  Elapsed Time:  n/a
  Exit Value:    1
Config (pass/fail):
  pass_conditions: 1
  fail_conditions: 0
Result: fail: DB_UPTIME&lt;13


InfoBuffer: (pass condition vars)            
============================================ 
DB_UPTIME  107.35
    WFLAG  waypoints=3

InfoBuffer: (fail condition vars)            
============================================ 
DB_UPTIME  107.35
    WFLAG  waypoints=3

InfoBuffer: (check vars)                     
============================================ 
WFLAG  waypoints=3

\end{consoleverb}
\vspace{0.1in}

\noindent
Note in the last two lines the current value of the MOOS variable
\mvar{DB\_UPTIME} is reported and the result of the logic condition is
declared along with the value returned by the command, \var{exit(1)}.

%=================================================================
\section{Using the Output Generated by uQueryDB}
%=================================================================

In addition to the human-readable output above, the \app{uQueryDB}
utility also generates a return value available on the command line.
In line with common GNU/Linux tradition, this utility returns 0 when
it is successful and a non-zero value when not successful. In our case
\app{uQueryDB} returns 0 when the logic condition succeeds, and 1 when
it does not. As a simple exercise, launch the alpha mission again as
in the previous example. After it has again launched, enter the
following in another terminal window:

\vspace{0.1in}
\begin{consoleverb}
$ uQueryDB alpha.moos --condition="DB_UPTIME&lt;130" &gt;&amp; /dev/null
\end{consoleverb}
\vspace{0.1in}

\noindent
By redirecting to \var{/dev/null} the normal terminal output
is suppressed but the result is generated nevertheless, and can be
seen by examining the special shell variable \var{\$?} with:

\vspace{0.1in}
\begin{consoleverb}
$ echo $?
0
\end{consoleverb}
\vspace{0.1in}

\noindent
The 0 indicates success, i.e., the logic condition succeeded. This
approach is especially useful when used inside a shell script, described
next.

%=================================================================
\section{Using uQueryDB within a Shell Script}
%=================================================================

The motivation for \app{uQueryDB} is to support the automation of
simulation experiments by launching a mission from within a script
and exiting the script (and the mission) when a specified condition
is met within the simulation environment. By example we return to the
alpha mission. The example script below launches the alpha mission
and halts the alpha mission after 20 seconds.

\vspace{0.1in}
\begin{fileverb}
#!/bin/bash -e   

# Part 1: Launch the mission
pAntler alpha.moos &gt;&amp; /dev/null &amp;

# Part 2: After a short wait deploy the vehicle
sleep 5
uPokeDB alpha.moos MOOS_MANUAL_OVERRIDE=false DEPLOY=true	
sleep 5

# Part 3: Continually check for the termination criteria
while true; do
    uQueryDB alpha.moos --condition="DB_UPTIME&gt;30"
    if [ "$?" = 0 ]; then 
        echo -n "Quitting..."
        killall pAntler
        sleep 2
        echo "Done."
        exit 0
    fi
    sleep 5
    echo "continuing..."
done
\end{fileverb}
\vspace{0.1in}

\noindent
Of course the above example simply uses {\em time} as a termination
criteria, which could be accomplished by just changing the \cmd{sleep}
command and terminating. But \app{uQueryDB} allows the termination
to be based on mission related criteria. For example, in the alpha
mission, termination can be set to happen after the vehicle traverses
its set of waypoints twice, by setting the logic condition with
\var{--condition="CYCLE\_INDEX&gt;2"}.

%=================================================================
\section{Command-line Arguments of uQueryDB}
%=================================================================
\label{sec_uqdb_cmdline}
%\index{uQueryDB!Command Line Usage}
%\index{Command Line Usage!uQueryDB}
%\index{Configuration Parameters!uQueryDB}

Configuration parameters can be passed to \app{uQueryDB} from the command
line or from the mission (\var{.moos}) configuration file. Launching it
without logic conditions will simply result in \app{uQueryDB} returning
immediately with a value of 0 (success). 

\vspace{0.1in}
\noindent
The specification of a MOOS file on the command line is optional. The
primary two pieces of information \app{uQueryDB} needs from this file
are (a) the \var{server\_host} IP address, and (b) the
\var{server\_port} number of the running MOOSDB to poke. These values
can instead be provided on the command line:

\vspace{0.1in}
\begin{consoleverb}
 $ uQueryDB --condition="NUM&gt;30" --host=18.38.2.158  --port=9000
\end{consoleverb}
\vspace{0.1in}

\noindent
If the \var{host} or the \var{port} are not provided on the command
line, and a MOOS file is also not provided, the user will be prompted
for the two values. Since the most common scenario by convention has
the MOOSDB running on the local machine ("localhost") with port 9000,
these are the default values and the user can simply hit the return
key.

\vspace{0.1in}
\footnotesize
\begin{consoleverb}
$ uQueryDB --condition="DEPLOY=true"  // User launches with no server host/port info
$ Enter Server: [localhost]           // User accepts default by hitting Return key
$    The server is set to "localhost" // Server host confirmed to be set to "localhost"
$ Enter Port: [9000] 9123             // User overrides the default 9000 port with 9123
$    The port is set to "9123"        // Server port confirmed to be set to "9123"
\end{consoleverb}
\normalsize

%=================================================================
\subsection{Logic Pass Conditions on the Command Line}
\label{sec_uqdb_pass}

On the command line \app{uQueryDB} takes any number of logic pass
conditions. If {\em all} pass conditions are satisfied, then
\app{uQueryDB} will return with 0, indicating success. A pass
condition may be specified with either the \var{--condition} or
\var{--pass\_condition} parameter.  They are interchangeable.  A
conjuction of pass conditions can be applied simply by specifying
mulitiple conditions:

\vspace{0.1in}
\begin{consoleverb}
 $ uQueryDB alpha.moos --condition="DEPLOY=true" --condition="STATION=false"
\end{consoleverb}
\vspace{0.1in}

\noindent
A disjunction of conditions can be specified as described in
\urlx{http://oceanai.mit.edu/ivpman/logic}, within a single
condition. For example:

\vspace{0.1in}
\begin{consoleverb}
 $ uQueryDB alpha.moos --condition="((DB_TIME&gt;36000) or (MISSION=complete))"
\end{consoleverb}
\vspace{0.1in}

\noindent
Since white-space characters on a command line delineate arguments,
the use of double-quotes must be used if using white space as in the
examples above.

%=================================================================
\subsection{Logic Fail Conditions on the Command Line}
\label{sec_uqdb_fail}

Similar to the pass conditions described above, a {\em fail} condition
may also be specified. Depending on what you're trying to do, it may
be just easier to express things with a fail condition(s) instead of
pass conditions. If {\em any} fail condition is satisfied, then
\app{uQueryDB} will return with a value of $1$, indicating failure.
For example:

\vspace{0.1in}
\begin{consoleverb}
 $ uQueryDB alpha.moos --fail_condition="DEPLOY=false"   \
                       --fail_condition="STATION=true"
\end{consoleverb}
\vspace{0.1in}

\noindent
Pass and fail conditions may both be used simultaneously. If {\em all} pass
conditions are satisfied, and {\em no} fail conditions are satisfied, then
\app{uQueryDB} will return with a value of $0$, success. Otherwise it will
return with a value of $1$, failure.

%=================================================================
\subsection{Waiting for Success}
\label{sec_uqdb_wait}

A note of caution: by default, \app{uQueryDB} will immediately connect
to the MOOSDB, evaluate conditions and return with either a $0$ or
$1$. In some cases the user may want to allow \app{uQueryDB} a period
of time before exiting with failure. The \app{--wait=N} command line
parameter may be used, with the default being \var{N=0}. If
\app{uQueryDB} detects success, it will return immediately. Otherwise,
if the pass conditions are not initially all satisfied, or if one or
more fail conditions are satisfied initially, \app{uQueryDB} will
continue to evaluate for $N$ seconds before returning with failing
($1$) value.


%=================================================================
\subsection{Waiting for a Logic Variable to be Published}

Normally a logic condition of the form \var{(FOO&lt;20)} would evaluate
to false if the variable \mvar{FOO} has never been written to. This
may seem counter-intuitive in conditions like \var{(DEPLOY!=true)}
since clearly \mvar{DEPLOY} does not have the value of true if
\mvar{DEPLOY} has never been written to. But nevertheless the latter
condition would also evaluate to false.


%=================================================================
\section{Check Variables}
%=================================================================
\label{sec_uqdb_checkvars}
%\index{uQueryDB!Check Variables}

\app{uQueryDB} can be optionally configured to report the values of
one or more {\em check variables} at the time that \app{uQueryDB}
exits, regardless of the return value.  Check variables are named on
either the command line or in the mission configuration. A variety
of formats are supported. The motivation for check variables is to
enable \app{uQueryDB} to be further useful in scripts that may be
involved in automated mission testing.

%=================================================================
\subsection{Specifying Check Variables on the Command Line}
\label{sec_uqdb_checkvars_cl}

One or more check variables may be specified on the command line. If
variables are also specified in the mission file, the union of all
variables will be used.

\vspace{0.1in}
\begin{consoleverb}
  $ uQueryDB --check_var=RESULT --check_var=SCORE
\end{consoleverb}
\vspace{0.1in}

%=================================================================
\subsection{Specifying Check Variables in the Mission File}
\label{sec_uqdb_checkvars_mf}

One or more check variables may be specified in the mission file. If 
variables are also specified on the command line, the union of all
variables will be used.

\vspace{0.1in}
\begin{fileverb}
  check_var = RESULT 
  check_var = SCORE
\end{fileverb}
\vspace{0.1in}

%=================================================================
\subsection{Check Variable Output and Format}
\label{sec_uqdb_checkvars_format}

The output of check variables is written to a file \var{.checkvars}. This
file will be overwritten upon each run of \app{uQueryDB}. By default the
output will be \var{equals-separated-value}. For example:

\vspace{0.1in}
\begin{fileverb}
  RESULT = pass 
  SCORE = 98
\end{fileverb}
\vspace{0.1in}

\noindent
Another format option is \var{comma-separated-value}. For example:

\vspace{0.1in}
\begin{fileverb}
  RESULT,pass 
  SCORE,98
\end{fileverb}
\vspace{0.1in}

\noindent
Another format option is \var{whitespace-separated-value}. For example:

\vspace{0.1in}
\begin{fileverb}
  RESULT pass 
  SCORE 98
\end{fileverb}
\vspace{0.1in}

\noindent
Another format option is \var{value-only}. For example:

\vspace{0.1in}
\begin{fileverb}
  pass 
  98
\end{fileverb}
\vspace{0.1in}

\noindent
The format option can be specified on the command line with
\var{--esv} for \var{equals-separated-value}, or
\var{--csv} for \var{comma-separated-value}, or
\var{--wsv} for \var{whitespace-separated-value}, 
\var{--vo} for \var{value-only}. 

\vspace{0.1in}
\noindent
The format option can also specified in mission file with:

\vspace{0.1in}
\begin{fileverb}
  check_var_format = esv          // Default setting
  check_var_format = wsv
  check_var_format = csv
  check_var_format = vo
\end{fileverb}
\vspace{0.1in}

\noindent
If conflicting formats are specified between the command line and the
mission file, the mission file setting will take precedence.

%=================================================================
\section{Configuration Parameters for uQueryDB}
%=================================================================
%\index{uQueryDB!Configuration Parameters}
%\index{Configuration Parameters!uQueryDB}

In addition to accepting query parameters from the command line,
\app{uQueryDB} may accept configuration parameters from a
configuration block with a \var{.moos} file, similar to most MOOS
applications. This feature was added {\em after} Release 19.8.x.

\vspace{0.1in}
\noindent
The following parameters are defined for \app{uQueryDB}. A more
detailed description is provided in other parts of this
section. Parameters having default values indicate so in parentheses
below.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for uQueryDB}
\label{lst_uqdb_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.75\textwidth}} 

  \pvar{check\_var}: &amp; When the query results in a return value of
  zero, an optional variable report can be written to a file. Section
  \ref{sec_uqdb_checkvars}. \\

  \pvar{check\_var\_format}: &amp; Sets the output format for check
  variables written to the \var{.checkvars} file. Options are
  \var{esv}, or \var{csv}, or \var{wsv}, or \var{vo}. The default is
  \var{esv}.  \ref{sec_uqdb_checkvars_format}. \\

  \pvar{condition}: &amp; Same as \pvar{pass\_condition}. When {\em all}
  pass conditions are met, the query will result in a return value of
  zero. Section \ref{sec_uqdb_pass}. \\

  \pvar{fail\_condition}: &amp; When {\em any} fail condition is
  unsatisfied, the query will result ina return value of zero. Section
  \ref{sec_uqdb_fail}. \\

  \pvar{pass\_condition}: &amp; When {\em all} pass conditions are met,
  the query will result in a return value of zero. Section
  \ref{sec_uqdb_pass}. \\

  \pvar{wait}: &amp; If \app{uQueryDB} initially fails, rather than
  returning with a value of 1 immediatly, it will wait $N$ seconds to
  receive new mail updates that may perhaps result in successfully
  satisfying conditions. Default is 0 seconds. Section
  \ref{sec_uqdb_wait}. \\

\end{longtable}
\end{listing}

%=================================================================
\section{Publications and Subscriptions for uQueryDB}
%=================================================================
%\index{uQueryDB!Publications and Subscriptions}
%\index{Publications and Subscriptions!uQueryDB}

%=================================================================
\subsection*{Variables published by the uQueryDB application}

The \app{uQueryDB} application publishes no variables. In fact there will
likely be no trace at all in a mission alog file, with the possible exception
being the MOOS variable \mvar{DB\_CLIENTS}. If \app{uQueryDB} does not
immediately find the values for all variables involved in the logic expression,
it will stay connected for as long as the \var{--wait} parameter specifies.
The default is 0 seconds. In this case \app{uQueryDB} will be logged in
the list of clients in \mvar{DB\_CLIENTS} during this period.

%=================================================================
\subsection*{Variables subscribed for by the uPokeDB application}

All MOOS variables involved in the logic conditions provided to
\app{uQueryDB} will be subscribed for automatically.

\end{document}

</pre></body></html>