diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2018-01-23 16:54:55 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2018-01-23 16:54:55 (GMT) |
| commit | 5bf617b1e9347322b8b16419fd5e74107e8b1c26 (patch) | |
| tree | e5bbb785b82b35bc62df41bebca8b540078aaf76 /xpa/doc/xpamb.html | |
| parent | 51e1f85047b34f095ed69a3024d696997d2667c8 (diff) | |
| parent | 0ebcd152c10d2eae6b62f16e7138aa187a8a1bdd (diff) | |
| download | blt-5bf617b1e9347322b8b16419fd5e74107e8b1c26.zip blt-5bf617b1e9347322b8b16419fd5e74107e8b1c26.tar.gz blt-5bf617b1e9347322b8b16419fd5e74107e8b1c26.tar.bz2 | |
Merge commit '0ebcd152c10d2eae6b62f16e7138aa187a8a1bdd' as 'xpa'
Diffstat (limited to 'xpa/doc/xpamb.html')
| -rw-r--r-- | xpa/doc/xpamb.html | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/xpa/doc/xpamb.html b/xpa/doc/xpamb.html new file mode 100644 index 0000000..c1e27c8 --- /dev/null +++ b/xpa/doc/xpamb.html @@ -0,0 +1,197 @@ +<!-- =defdoc xpamb xpamb 1 --> +<HTML> +<HEAD> +<TITLE>The XPA Message Bus (xpamb)</TITLE> +</HEAD> +<BODY> + +<!-- =section xpamb NAME --> +<H2><A NAME="xpamb">xpamb: the XPA Message Bus</A></H2> + +<!-- =section xpamb SYNOPSIS --> +<H2>Summary</H2> +<P> +The xpamb program can act as a "classical" message bus interface +between clients and servers. A client can send a data request to +the message bus, which then interfaces with multiple servers and +returns the data back to the client. + +<!-- =section xpamb DESCRIPTION --> +<H2>Description</H2> +<P> +A "classical" message bus (such as ToolTalk) consists of servers and +clients, along with a mediating program that transfers data between +different processes. XPA takes a slightly different approach in that +communication between clients and servers is direct. This generally +is the correct technique when there is only one connection (or even a +small number of connections), but can become inefficient for the +serving program if a large amount of data is being transferred to many +clients. For example, if a real-time data acquisition program is +broadcasting a FITS image to several clients, it would need to +transmit that image to each client individually. This might interfere +with its own processing cycles. The preferable mechanism would be to +pass the image off to an intermediate program that can then broadcast +the data to the several clients. +<P> +The <B>xpamb</B> program can alleviate such problems by functioning +as a message bus in cases where such an intermediary process is +wanted. It pre-defines a single access point named +<B>XPAMB:xpamb</B> to which data can be sent for re-broadcast. You +also can tell <B>xpamb</B> to save the data, and associate with that +data a new access point, so that it can be retrieved later on. + +<P> +All interaction with <B>xpamb</B> is performed through +<B>xpaset</B> and <B>xpaget</B> (or the corresponding API +routines, <B>XPASet()</B> and <B>XPAGet()</B>) to the +<B>XPAMB:xpamb</B> access point. That is, <B>xpamb</B> is just +another XPA-enabled program that responds to requests from +clients. The paramlist is used to specify the targets to which +the data will be for re-broadcast, as well as the re-broadcast paramlist: +<PRE> + data | xpaset xpamb [switches] broadcast-target broadcast-paramlist +</PRE> +Optional switches are used to store data, and manipulate stored data, +and are described below. + +<P> +In its simplest form, you can, for example, send a FITS image to xpamb for +broadcasting to all ds9 image simply by executing: +<PRE> + cat foo.fits | xpaset xpamb "DS9:*" fits foo.fits +</PRE> +Since <B>DS9</B> is the class name for the ds9 image display +program, this will result in the FITS image being re-sent to all fits +access points for all active image display programs. + +<P> +You can send stored data and new data to the same set of access points at +the same time. The stored data always is sent first, followed by the new +data: +<PRE> + cat foo2.fits | xpaset xpamb -send foo "DS9:*" fits foo.fits +</PRE> +will first send the foo.fits file, and then the foo2.fits file to all +access points of class <B>DS9</B>. Notice that in this example, +the foo2.fits file is not stored, but it could be stored by using the +<B>-store [name]</B> switch on the command line. + +<P> +The <B>xpaget</B> command can be used to retrieve a data from XPA +access points or from a stored data buffer, or retrieve information +about a stored data buffer. If no arguments are given: +<PRE> + xpaget xpamb +</PRE> +then information about all currently stored data buffers is returned. This +information includes the data and time at which the data was stored, the +size in bytes of the data, and the supplied info string. + +<P> +If arguments are specified, they will be in the form: +<PRE> + xpaget xpamb [-info] [-data] [name [paramlist]] +</PRE> +If the optional <B>-info</B> and/or <B>-data</B> switches are specified, then +information and/or data will be returned for the named data buffer +following the switches. You can use either or both of these switches +in a single command. For example, if the -info switch is used: +<PRE> + xpaget xpamb -info foo +</PRE> +then the info about that stored data buffer will be returned. +If the -data is used with a specific name: +<PRE> + xpaget xpamb -data foo +</PRE> +then the stored data itself will be returned. If both are used: +<PRE> + xpaget xpamb -info -data foo +</PRE> +then the info will be returned, followed by the data. Note that it is an +error to specify one of these switches without a data buffer name and that +the paramlist will be ignored. + +<P> +If neither the <B>-info</B> or <B>-data</B> switch is specified, then +the name refers to an XPA access point (with an optional paramlist +following). +For example: +<PRE> + xpaget xpamb ds9 file +</PRE> +is equivalent to: +<PRE> + xpaget ds9 file +</PRE> + +<!-- =section xpamb OPTIONS --> +<H2>Options</H2> +<P> +For xpaset, several optional switches are used to save data and +manipulate the stored data: +<DL> + +<P> +<DT><B>-data [name]</B> +<DD> Add the supplied data buffer to a pool of stored data buffers, +using the specified name as a unique identifier for later retrieval. +An error occurs if the name already exists (use either <B>replace</B> +or <B>del</B> to rectify this). The <B>-add</B> switch is supported +for backwards compatibility with xpa 2.0. + +<P> +<DT><B>-replace [name]</B> +<DD> Replace previously existing stored data having the same unique name +with new data. This essentially is a combination of the <B>del</B> +and <B>data</B> commands. + +<P> +<DT><B>-info ["'info string'"]</B> +<DD> When adding a data buffer, you can specify an informational +string to be stored with that data. This string will be returned +by xpaget: +<PRE> + xpaget xpamb foo -info +</PRE> +(along with other information such as the date/time of storage and the size of +the data buffer) if the -info switch is specified. If the info string contains +spaces, you must enclose it in <B>two</B> sets of quotes: +<PRE> + cat foo | xpaset xpamb -data foo -info "'this is info on foo'" +</PRE> +The first set of quotes is removed by the shell while the second is used to +delineate the info string. + +<P> +<DT><B>-send [name]</B> +<DD> Broadcast the stored data buffer to the named template. + +<P> +<DT><B>-del [name]</B> +<DD> Delete the named data buffer and free all allocated space. +</DL> + +<P> +Switches can be used in any combination that makes sense. For example: +<PRE> + cat foo.fits | xpaset xpamb -data foo -info "FITS" "DS9:*" fits foo.fits +</PRE> +will broadcast the foo.fits image to all access points of class +<B>DS9</B>. In addition, the foo.fits file will be stored under the +name of <B>foo</B> for later manipulation such as: +<PRE> + xpaset -p xpamb -send foo "DS9:*" fits foo.fits +</PRE> +will re-broadcast the foo.fits image to all access points of class "DS9". + +<!-- =section xpamb SEE ALSO --> +<!-- =text See xpa(n) for a list of XPA help pages --> +<!-- =stop --> + +<P> +<A HREF="./help.html">Go to XPA Help Index</A> + +<H5>Last updated: September 10, 2003</H5> +</BODY> +</HTML> |