source: pvMail/doc/build/html/cli.html @ 933

Last change on this file since 933 was 933, checked in by jemian, 10 years ago

report the documentation build date rather than SVN revision number

  • Property svn:mime-type set to text/html
File size: 21.8 KB
Line 
1
2
3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
6
7<html xmlns="http://www.w3.org/1999/xhtml">
8  <head>
9    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
10   
11    <title>pvMail.py: command-line interface &mdash; PvMail (v3.0, 2012-06-14) documentation</title>
12   
13    <link rel="stylesheet" href="_static/sphinxdoc.css" type="text/css" />
14    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
15   
16    <script type="text/javascript">
17      var DOCUMENTATION_OPTIONS = {
18        URL_ROOT:    '',
19        VERSION:     '(v3.0, 2012-06-14)',
20        COLLAPSE_INDEX: false,
21        FILE_SUFFIX: '.html',
22        HAS_SOURCE:  true
23      };
24    </script>
25    <script type="text/javascript" src="_static/jquery.js"></script>
26    <script type="text/javascript" src="_static/underscore.js"></script>
27    <script type="text/javascript" src="_static/doctools.js"></script>
28    <link rel="top" title="PvMail (v3.0, 2012-06-14) documentation" href="index.html" />
29    <link rel="up" title="Contents" href="contents.html" />
30    <link rel="next" title="pvMail.py: graphical user interface" href="gui.html" />
31    <link rel="prev" title="Contents" href="contents.html" /> 
32  </head>
33  <body>
34    <div class="related">
35      <h3>Navigation</h3>
36      <ul>
37        <li class="right" style="margin-right: 10px">
38          <a href="genindex.html" title="General Index"
39             accesskey="I">index</a></li>
40        <li class="right" >
41          <a href="py-modindex.html" title="Python Module Index"
42             >modules</a> |</li>
43        <li class="right" >
44          <a href="gui.html" title="pvMail.py: graphical user interface"
45             accesskey="N">next</a> |</li>
46        <li class="right" >
47          <a href="contents.html" title="Contents"
48             accesskey="P">previous</a> |</li>
49        <li><a href="index.html">PvMail (v3.0, 2012-06-14) documentation</a> &raquo;</li>
50          <li><a href="contents.html" accesskey="U">Contents</a> &raquo;</li> 
51      </ul>
52    </div>
53      <div class="sphinxsidebar">
54        <div class="sphinxsidebarwrapper">
55  <h3><a href="index.html">Table Of Contents</a></h3>
56  <ul>
57<li><a class="reference internal" href="#">pvMail.py: command-line interface</a><ul>
58<li><a class="reference internal" href="#starting-pvmail-from-the-command-line">Starting PvMail from the command-line</a></li>
59<li><a class="reference internal" href="#starting-pvmail-from-the-command-line-at-the-aps">Starting PvMail from the command-line at the APS</a></li>
60</ul>
61</li>
62<li><a class="reference internal" href="#command-line-parameters">command-line parameters</a><ul>
63<li><a class="reference internal" href="#usage">usage</a></li>
64<li><a class="reference internal" href="#positional-argument-trigger-pv">positional argument: <tt class="docutils literal"><span class="pre">trigger_PV</span></tt></a></li>
65<li><a class="reference internal" href="#positional-argument-message-pv">positional argument: <tt class="docutils literal"><span class="pre">message_PV</span></tt></a></li>
66<li><a class="reference internal" href="#positional-argument-email-addresses">positional argument: <tt class="docutils literal"><span class="pre">email_addresses</span></tt></a></li>
67<li><a class="reference internal" href="#option-version-or-v">option: <tt class="docutils literal"><span class="pre">--version</span></tt>  or  <tt class="docutils literal"><span class="pre">-v</span></tt></a></li>
68<li><a class="reference internal" href="#option-help-or-h">option: <tt class="docutils literal"><span class="pre">--help</span></tt>  or  <tt class="docutils literal"><span class="pre">-h</span></tt></a></li>
69<li><a class="reference internal" href="#option-gui-or-g">option: <tt class="docutils literal"><span class="pre">--gui</span></tt>  or <tt class="docutils literal"><span class="pre">-g</span></tt></a></li>
70<li><a class="reference internal" href="#option-l-log-file">option: <tt class="docutils literal"><span class="pre">-l</span> <span class="pre">LOG_FILE</span></tt></a></li>
71<li><a class="reference internal" href="#option-i-logging-interval">option: <tt class="docutils literal"><span class="pre">-i</span> <span class="pre">LOGGING_INTERVAL</span></tt></a></li>
72<li><a class="reference internal" href="#option-r-sleep-duration">option: <tt class="docutils literal"><span class="pre">-r</span> <span class="pre">SLEEP_DURATION</span></tt></a></li>
73</ul>
74</li>
75</ul>
76
77  <h4>Previous topic</h4>
78  <p class="topless"><a href="contents.html"
79                        title="previous chapter">Contents</a></p>
80  <h4>Next topic</h4>
81  <p class="topless"><a href="gui.html"
82                        title="next chapter">pvMail.py: graphical user interface</a></p>
83  <h3>This Page</h3>
84  <ul class="this-page-menu">
85    <li><a href="_sources/cli.txt"
86           rel="nofollow">Show Source</a></li>
87  </ul>
88<div id="searchbox" style="display: none">
89  <h3>Quick search</h3>
90    <form class="search" action="search.html" method="get">
91      <input type="text" name="q" />
92      <input type="submit" value="Go" />
93      <input type="hidden" name="check_keywords" value="yes" />
94      <input type="hidden" name="area" value="default" />
95    </form>
96    <p class="searchtip" style="font-size: 90%">
97    Enter search terms or a module, class or function name.
98    </p>
99</div>
100<script type="text/javascript">$('#searchbox').show(0);</script>
101        </div>
102      </div>
103
104    <div class="document">
105      <div class="documentwrapper">
106        <div class="bodywrapper">
107          <div class="body">
108           
109  <div class="section" id="pvmail-py-command-line-interface">
110<h1>pvMail.py: command-line interface<a class="headerlink" href="#pvmail-py-command-line-interface" title="Permalink to this headline">¶</a></h1>
111<p>Basically, you use it either as a background daemon or as a GUI. Call
112it with a <tt class="docutils literal"><span class="pre">-g</span></tt> or <tt class="docutils literal"><span class="pre">--gui</span></tt> command line option to force the GUI to run,
113otherwise you get the background daemon.  Either way, it makes a log
114file (based on PID number) with any program output.</p>
115<p id="index-0">background daemon:</p>
116<div class="highlight-python"><pre>pvMail.py triggerPV messagePV user1@email.domain,user2@host.server &amp;</pre>
117</div>
118<p>GUI:</p>
119<div class="highlight-python"><pre>pvMail.py triggerPV messagePV user1@email.domain,user2@host.server -g &amp;</pre>
120</div>
121<p>PvMail uses Matt Newville&#8217;s <a class="reference external" href="http://cars9.uchicago.edu/software/python/pyepics3/">PyEpics</a>
122package for EPICS CA connections and Enthought&#8217;s
123<a class="reference external" href="http://code.enthought.com/projects/traits/">Traits</a>
124package to build the GUI (which means it could use either WX or QT).</p>
125<div class="section" id="starting-pvmail-from-the-command-line">
126<h2>Starting PvMail from the command-line<a class="headerlink" href="#starting-pvmail-from-the-command-line" title="Permalink to this headline">¶</a></h2>
127<p id="index-1">PvMail is started from the command line:</p>
128<div class="highlight-python"><pre>$ ./pvMail.py pvMail:trigger pvMail:message jemian</pre>
129</div>
130<p id="index-2">No program output is printed to the screen.  Instead, the output is directed
131to a log file.  Here is an example:</p>
132<div class="highlight-python"><pre>INFO:root:(pvMail.py,2011-11-27 19:03:23.072392) ############################################################
133INFO:root:(pvMail.py,2011-11-27 19:03:23.072826) startup
134INFO:root:(pvMail.py,2011-11-27 19:03:23.072897) trigger PV       = pvMail:trigger
135INFO:root:(pvMail.py,2011-11-27 19:03:23.073323) message PV       = pvMail:message
136INFO:root:(pvMail.py,2011-11-27 19:03:23.073401) email list       = ['jemian']
137INFO:root:(pvMail.py,2011-11-27 19:03:23.073463) log file         = logfile.log
138INFO:root:(pvMail.py,2011-11-27 19:03:23.073667) logging interval = 5.0
139INFO:root:(pvMail.py,2011-11-27 19:03:23.073735) sleep duration   = 0.2
140INFO:root:(pvMail.py,2011-11-27 19:03:23.073795) interface        = command-line
141INFO:root:(pvMail.py,2011-11-27 19:03:23.073855) user             = jemian
142INFO:root:(pvMail.py,2011-11-27 19:03:23.073952) host             = como-ubuntu64
143INFO:root:(pvMail.py,2011-11-27 19:03:23.074053) program          = ./pvMail.py
144INFO:root:(pvMail.py,2011-11-27 19:03:23.074124) PID              = 8903
145INFO:root:(pvMail.py,2011-11-27 19:03:23.074196) do_start
146INFO:root:(pvMail.py,2011-11-27 19:03:23.074280) test connect with pvMail:message
147INFO:root:(pvMail.py,2011-11-27 19:03:23.445334) test connect with pvMail:trigger
148INFO:root:(pvMail.py,2011-11-27 19:03:23.468540) passed basicChecks(), starting monitors
149INFO:root:(pvMail.py,2011-11-27 19:03:23.477917) checkpoint
150INFO:root:(pvMail.py,2011-11-27 19:03:27.373142) pvMail:trigger = 1
151INFO:root:(pvMail.py,2011-11-27 19:03:27.373908) SendMessage
152INFO:root:(pvMail.py,2011-11-27 19:03:27.374199) sending email to: jemian
153INFO:root:(pvMail.py,2011-11-27 19:03:27.374716) mail -s "pvMail.py: pvMail:trigger" jemian &lt; /tmp/pvmail_message.txt
154INFO:root:(pvMail.py,2011-11-27 19:03:27.538022) message(s) sent
155INFO:root:(pvMail.py,2011-11-27 19:03:28.092551) checkpoint
156INFO:root:(pvMail.py,2011-11-27 19:03:29.440516) pvMail:trigger = 0</pre>
157</div>
158<p>The program starts, reports its configurations, and connects with the
159EPICS PVs, and then goes into a background mode.  A checkpoint (command-line
160option <tt class="docutils literal"><span class="pre">-i</span></tt>) is reported periodically.  The default is 5 seconds.  This may
161be changed to 10 minutes or longer for production use, but is always
162specified in seconds.</p>
163<p>Observe that, in the above example, the trigger PV changed from 0 to 1 at
16419:03:27.373142 (and back to 0 at 19:03:29.440516).
165The change at ~19:03:27 triggered PvMail to send an email as configured.
166For now, the code writes the text of the email to a temporary file
167(command-line option <tt class="docutils literal"><span class="pre">-m</span></tt>, default is &#8220;/tmp/pvmail_message.txt&#8221;).
168In this example, the message reads:</p>
169<div class="highlight-python"><pre>pvMail default message
170
171user: jemian
172host: como-ubuntu64
173date: 2011-11-27 19:03:27.374135
174program: ./pvMail.py
175PID: 8903
176trigger PV: pvMail:trigger
177message PV: pvMail:message
178recipients: jemian</pre>
179</div>
180<p>The message shows up in the mail browser (here my Linux <tt class="docutils literal"><span class="pre">mail</span></tt> program):</p>
181<div class="highlight-python"><pre>jemian@como-ubuntu64$ mail
182Mail version 8.1.2 01/15/2001.  Type ? for help.
183"/var/mail/jemian": 3 messages 3 new
184&gt;N  1 jemian@como-ubunt  Sun Nov 27 18:27   25/730   pvMail.py: pvMail:trigger
185 N  2 jemian@como-ubunt  Sun Nov 27 18:58   25/730   pvMail.py: pvMail:trigger
186 N  3 jemian@como-ubunt  Sun Nov 27 19:03   25/730   pvMail.py: pvMail:trigger</pre>
187</div>
188<p id="index-3">The full message, as seen in the mail browser is:</p>
189<div class="highlight-python"><pre>Message 3:
190From jemian@como-ubuntu64 Sun Nov 27 19:03:27 2011
191Envelope-to: jemian@como-ubuntu64
192Delivery-date: Sun, 27 Nov 2011 19:03:27 -0600
193To: jemian@como-ubuntu64
194Subject: pvMail.py: pvMail:trigger
195From: Pete R Jemian &lt;jemian@como-ubuntu64&gt;
196Date: Sun, 27 Nov 2011 19:03:27 -0600
197
198pvMail default message
199
200user: jemian
201host: como-ubuntu64
202date: 2011-11-27 19:03:27.374135
203program: ./pvMail.py
204PID: 8903
205trigger PV: pvMail:trigger
206message PV: pvMail:message
207recipients: jemian</pre>
208</div>
209</div>
210<div class="section" id="starting-pvmail-from-the-command-line-at-the-aps">
211<h2>Starting PvMail from the command-line at the APS<a class="headerlink" href="#starting-pvmail-from-the-command-line-at-the-aps" title="Permalink to this headline">¶</a></h2>
212<p>At the APS, Enthought Python Distribution is installed on the /APSshare partition
213available to all beam lines.</p>
214<p id="index-4">Here is a command to run the PvMail and get the help message:</p>
215<div class="highlight-python"><pre>/APSshare/epd/rh5-x86_64/bin/python /APSshare/epd/demos/pvMail.py -h</pre>
216</div>
217<p>or the 32-bit version:</p>
218<div class="highlight-python"><pre>/APSshare/epd/rh5-x86/bin/python /APSshare/epd/demos/pvMail.py -h</pre>
219</div>
220<div class="admonition note">
221<p class="first admonition-title">Note</p>
222<p class="last">Support for both RHEL5 and RHEL6 use the same Enthought Python Distribution.</p>
223</div>
224</div>
225</div>
226<div class="section" id="command-line-parameters">
227<h1>command-line parameters<a class="headerlink" href="#command-line-parameters" title="Permalink to this headline">¶</a></h1>
228<span class="target" id="index-5"></span><div class="section" id="usage">
229<span id="index-6"></span><h2>usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
230<p id="index-7">When PvMail is started from the command line with no additional parameters:</p>
231<div class="highlight-python"><pre>$ pvMail.py
232
233usage: pvMail.py [-h] [-l LOG_FILE] [-i LOGGING_INTERVAL]
234                 [-r SLEEP_DURATION] [-g] [-v]
235                 trigger_PV message_PV email_addresses
236pvMail.py: error: too few arguments</pre>
237</div>
238<p>This is the <em>usage</em> message.
239It tells us we must supply three <span class="target" id="index-8"></span>positional arguments:
240<tt class="docutils literal"><span class="pre">trigger_PV</span> <span class="pre">message_PV</span> <span class="pre">email_addresses</span></tt>.</p>
241</div>
242<div class="section" id="positional-argument-trigger-pv">
243<h2>positional argument: <tt class="docutils literal"><span class="pre">trigger_PV</span></tt><a class="headerlink" href="#positional-argument-trigger-pv" title="Permalink to this headline">¶</a></h2>
244<p>EPICS process variable name to watch using a CA monitor.
245When <tt class="docutils literal"><span class="pre">trigger_PV</span></tt> makes a transition from 0 (zero) to 1 (one),
246then get the string from the <tt class="docutils literal"><span class="pre">message_PV</span></tt> and send an email
247to all of the <tt class="docutils literal"><span class="pre">email_addresses</span></tt> on the list.</p>
248</div>
249<div class="section" id="positional-argument-message-pv">
250<h2>positional argument: <tt class="docutils literal"><span class="pre">message_PV</span></tt><a class="headerlink" href="#positional-argument-message-pv" title="Permalink to this headline">¶</a></h2>
251<p>EPICS process variable name pointing to a (short) message that will
252be used as the first part of the email message to be sent.</p>
253</div>
254<div class="section" id="positional-argument-email-addresses">
255<h2>positional argument: <tt class="docutils literal"><span class="pre">email_addresses</span></tt><a class="headerlink" href="#positional-argument-email-addresses" title="Permalink to this headline">¶</a></h2>
256<p>List of email addresses, separated by commas if more than one.  For example,
257<tt class="docutils literal"><span class="pre">user1&#64;email.domain,user2&#64;host.server</span></tt> will send one email to
258<tt class="docutils literal"><span class="pre">user1&#64;email.domain</span></tt> and another email to <tt class="docutils literal"><span class="pre">user2&#64;host.server</span></tt>.</p>
259<div class="admonition note" id="index-9">
260<p class="first admonition-title">Note</p>
261<p class="last">At Argonne, it is possible to send email to a pager using
262the email address <tt class="docutils literal"><span class="pre">####&#64;pager.anl.gov</span></tt> and the pager number.
263Be sure not to use a preceding <tt class="docutils literal"><span class="pre">4-</span></tt> or the email will not be
264deliverable.</p>
265</div>
266</div>
267<div class="section" id="option-version-or-v">
268<span id="index-10"></span><h2>option: <tt class="docutils literal"><span class="pre">--version</span></tt>  or  <tt class="docutils literal"><span class="pre">-v</span></tt><a class="headerlink" href="#option-version-or-v" title="Permalink to this headline">¶</a></h2>
269<p>The current version of the program can always be printed using the
270<tt class="docutils literal"><span class="pre">-v</span></tt> or <tt class="docutils literal"><span class="pre">--version</span></tt>.  With this option, the program prints
271the version number and then quits.</p>
272<div class="highlight-python"><pre>$ pvMail.py --version
2733.0-663</pre>
274</div>
275</div>
276<div class="section" id="option-help-or-h">
277<h2>option: <tt class="docutils literal"><span class="pre">--help</span></tt>  or  <tt class="docutils literal"><span class="pre">-h</span></tt><a class="headerlink" href="#option-help-or-h" title="Permalink to this headline">¶</a></h2>
278<p>It may be easier to review the short help instructions for command-line options:</p>
279<div class="highlight-python"><pre>$ ./pvMail.py --help
280usage: pvMail.py [-h] [-l LOG_FILE] [-i LOGGING_INTERVAL]
281                 [-r SLEEP_DURATION] [-g] [-v]
282                 trigger_PV message_PV email_addresses
283
284Watch an EPICS PV. Send email when it changes from 0 to 1.
285
286positional arguments:
287  trigger_PV           EPICS trigger PV name
288  message_PV           EPICS message PV name
289  email_addresses      email address(es), comma-separated if more than one
290
291optional arguments:
292  -h, --help           show this help message and exit
293  -l LOG_FILE          for logging program progress and comments
294  -i LOGGING_INTERVAL  checkpoint reporting interval (s) in log file
295  -r SLEEP_DURATION    sleep duration (s) in main event loop
296  -g, --gui            Use the graphical rather than command-line interface
297  -v, --version        show program's version number and exit</pre>
298</div>
299</div>
300<div class="section" id="option-gui-or-g">
301<h2>option: <tt class="docutils literal"><span class="pre">--gui</span></tt>  or <tt class="docutils literal"><span class="pre">-g</span></tt><a class="headerlink" href="#option-gui-or-g" title="Permalink to this headline">¶</a></h2>
302<p>This command line option is used to start the GUI (see <a class="reference internal" href="gui.html#gui"><em>pvMail.py: graphical user interface</em></a>).
303If either GUI option is used, then the positional arguments
304(<tt class="docutils literal"><span class="pre">triggerPV</span> <span class="pre">messagePV</span> <span class="pre">email&#64;address</span></tt>) are optional.</p>
305</div>
306<div class="section" id="option-l-log-file">
307<h2>option: <tt class="docutils literal"><span class="pre">-l</span> <span class="pre">LOG_FILE</span></tt><a class="headerlink" href="#option-l-log-file" title="Permalink to this headline">¶</a></h2>
308<p>Both the command-line and GUI versions of PvMail log all
309program output to a log file.  If a LOG_FILE is not specified on the command
310line, the default file will be <tt class="docutils literal"><span class="pre">pvMail-PID.log</span></tt> in the current directory
311where <em>PID</em> is the process identifier of the running pvMail.py program.</p>
312<div class="admonition note">
313<p class="first admonition-title">Note</p>
314<p class="last">If the LOG_FILE already exists, new information will be appended.
315It is up to the account owner to delete a LOG_FILE when it is no
316longer useful.</p>
317</div>
318<p>The PID number is useful when you wish to end a program that is running
319as a background daemon.  The UNIX/Linux command is:</p>
320<div class="highlight-python"><pre>kill PID</pre>
321</div>
322</div>
323<div class="section" id="option-i-logging-interval">
324<h2>option: <tt class="docutils literal"><span class="pre">-i</span> <span class="pre">LOGGING_INTERVAL</span></tt><a class="headerlink" href="#option-i-logging-interval" title="Permalink to this headline">¶</a></h2>
325<table class="docutils field-list" frame="void" rules="none">
326<col class="field-name" />
327<col class="field-body" />
328<tbody valign="top">
329<tr class="field-odd field"><th class="field-name">units:</th><td class="field-body">seconds</td>
330</tr>
331</tbody>
332</table>
333<p>When a program runs in the background, waiting for occasional activity,
334there is often some concern that the program is actually prepared to act
335when needed.  To offset this concern, PvMail will report a
336<em>checkpoint</em> message periodically (every LOGGING_INTERVAL seconds,
337default is every 5 minutes) to the LOG_FILE.  The program ensures that
338LOGGING_INTERVAL is no shorter than 5 seconds or longer than 1 hour.</p>
339</div>
340<div class="section" id="option-r-sleep-duration">
341<h2>option: <tt class="docutils literal"><span class="pre">-r</span> <span class="pre">SLEEP_DURATION</span></tt><a class="headerlink" href="#option-r-sleep-duration" title="Permalink to this headline">¶</a></h2>
342<table class="docutils field-list" frame="void" rules="none">
343<col class="field-name" />
344<col class="field-body" />
345<tbody valign="top">
346<tr class="field-odd field"><th class="field-name">units:</th><td class="field-body">seconds</td>
347</tr>
348</tbody>
349</table>
350<p>For operation as a background daemon process, the command-line version
351must check periodically for new EPICS CA events, using a call to
352<tt class="xref py py-meth docutils literal"><span class="pre">epics.ca.poll()</span></tt>.  In between calls, the application is told to sleep
353for SLEEP_DURATION seconds.  The default SLEEP_DURATION is 0.2 seconds and
354is limited to values between 0.1 ms and 5 s.</p>
355</div>
356</div>
357
358
359          </div>
360        </div>
361      </div>
362      <div class="clearer"></div>
363    </div>
364    <div class="related">
365      <h3>Navigation</h3>
366      <ul>
367        <li class="right" style="margin-right: 10px">
368          <a href="genindex.html" title="General Index"
369             >index</a></li>
370        <li class="right" >
371          <a href="py-modindex.html" title="Python Module Index"
372             >modules</a> |</li>
373        <li class="right" >
374          <a href="gui.html" title="pvMail.py: graphical user interface"
375             >next</a> |</li>
376        <li class="right" >
377          <a href="contents.html" title="Contents"
378             >previous</a> |</li>
379        <li><a href="index.html">PvMail (v3.0, 2012-06-14) documentation</a> &raquo;</li>
380          <li><a href="contents.html" >Contents</a> &raquo;</li> 
381      </ul>
382    </div>
383    <div class="footer">
384        &copy; Copyright (c) 2009-2012, UChicago Argonne, LLC (see LICENSE file for details).
385      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.2.
386    </div>
387  </body>
388</html>
Note: See TracBrowser for help on using the repository browser.