summaryrefslogtreecommitdiffstats
path: root/xpa/man/man1/xpamb.1
diff options
context:
space:
mode:
Diffstat (limited to 'xpa/man/man1/xpamb.1')
-rw-r--r--xpa/man/man1/xpamb.1325
1 files changed, 325 insertions, 0 deletions
diff --git a/xpa/man/man1/xpamb.1 b/xpa/man/man1/xpamb.1
new file mode 100644
index 0000000..37f06f4
--- /dev/null
+++ b/xpa/man/man1/xpamb.1
@@ -0,0 +1,325 @@
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "xpamb 1"
+.TH xpamb 1 "July 23, 2013" "version 2.1.15" "SAORD Documentation"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+\&\fBxpamb: the \s-1XPA\s0 Message Bus\fR
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+The xpamb program can act as a \*(L"classical\*(R" 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.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+For xpaset, several optional switches are used to save data and
+manipulate the stored data:
+.IP "\(bu" 4
+\&\fB\-data [name]\fR
+.Sp
+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 \fBreplace\fR
+or \fBdel\fR to rectify this). The \fB\-add\fR switch is supported
+for backwards compatibility with xpa 2.0.
+.IP "\(bu" 4
+\&\fB\-replace [name]\fR
+.Sp
+Replace previously existing stored data having the same unique name
+with new data. This essentially is a combination of the \fBdel\fR
+and \fBdata\fR commands.
+.IP "\(bu" 4
+\&\fB\-info [\*(L"'info string'\*(R"]\fR
+.Sp
+When adding a data buffer, you can specify an informational
+string to be stored with that data. This string will be returned
+by xpaget:
+.Sp
+.Vb 1
+\& xpaget xpamb foo \-info
+.Ve
+.Sp
+(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 \fBtwo\fR sets of quotes:
+.Sp
+.Vb 1
+\& cat foo | xpaset xpamb \-store foo \-info "\*(Aqthis is info on foo\*(Aq"
+.Ve
+.Sp
+The first set of quotes is removed by the shell while the second is used to
+delineate the info string.
+.IP "\(bu" 4
+\&\fB\-send [name]\fR
+.Sp
+Broadcast the stored data buffer to the named template.
+.IP "\(bu" 4
+\&\fB\-del [name]\fR
+.Sp
+Delete the named data buffer and free all allocated space.
+.PP
+Switches can be used in any combination that makes sense. For example:
+.PP
+.Vb 1
+\& cat foo.fits | xpaset xpamb \-store foo \-info "FITS" "DS9:*" fits foo.fits
+.Ve
+.PP
+will broadcast the foo.fits image to all access points of class
+\&\fB\s-1DS9\s0\fR. In addition, the foo.fits file will be stored under the
+name of \fBfoo\fR for later manipulation such as:
+.PP
+.Vb 1
+\& xpaset \-p xpamb \-send foo "DS9:*" fits foo.fits
+.Ve
+.PP
+will re-broadcast the foo.fits image to all access points of class \*(L"\s-1DS9\s0\*(R".
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+A \*(L"classical\*(R" message bus (such as ToolTalk) consists of servers and
+clients, along with a mediating program that transfers data between
+different processes. \s-1XPA\s0 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 \s-1FITS\s0 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.
+.PP
+The \fBxpamb\fR 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
+\&\fBXPAMB:xpamb\fR to which data can be sent for re-broadcast. You
+also can tell \fBxpamb\fR to save the data, and associate with that
+data a new access point, so that it can be retrieved later on.
+.PP
+All interaction with \fBxpamb\fR is performed through
+\&\fBxpaset\fR and \fBxpaget\fR (or the corresponding \s-1API\s0
+routines, \fB\f(BIXPASet()\fB\fR and \fB\f(BIXPAGet()\fB\fR) to the
+\&\fBXPAMB:xpamb\fR access point. That is, \fBxpamb\fR 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:
+.PP
+.Vb 1
+\& data | xpaset xpamb [switches] broadcast\-target broadcast\-paramlist
+.Ve
+.PP
+Optional switches are used to store data, and manipulate stored data,
+and are described below.
+.PP
+In its simplest form, you can, for example, send a \s-1FITS\s0 image to xpamb for
+broadcasting to all ds9 image simply by executing:
+.PP
+.Vb 1
+\& cat foo.fits | xpaset xpamb "DS9:*" fits foo.fits
+.Ve
+.PP
+Since \fB\s-1DS9\s0\fR is the class name for the ds9 image display
+program, this will result in the \s-1FITS\s0 image being re-sent to all fits
+access points for all active image display programs.
+.PP
+You can send stored data and new data to the same set of access points at
+the same time. The stored data always is send first, followed by the new
+data:
+.PP
+.Vb 1
+\& cat foo2.fits | xpaset xpamb \-send foo "DS9:*" fits foo.fits
+.Ve
+.PP
+will first send the foo.fits file, and then the foo2.fits file to all
+access points of class \fB\s-1DS9\s0\fR. Notice that in this example,
+the foo2.fits file is not stored, but it could be stored by using the
+\&\fB\-store [name]\fR switch on the command line.
+.PP
+The \fBxpaget\fR command can be used to retrieve a data from \s-1XPA\s0
+access points or from a stored data buffer, or retrieve information
+about a stored data buffer. If no arguments are given:
+.PP
+.Vb 1
+\& xpaget xpamb
+.Ve
+.PP
+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.
+.PP
+If arguments are specified, they will be in the form:
+.PP
+.Vb 1
+\& xpaget xpamb [\-info] [\-data] [name [paramlist]]
+.Ve
+.PP
+If the optional \fB\-info\fR and/or \fB\-data\fR 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:
+.PP
+.Vb 1
+\& xpaget xpamb \-info foo
+.Ve
+.PP
+then the info about that stored data buffer will be returned.
+If the \-data is used with a specific name:
+.PP
+.Vb 1
+\& xpaget xpamb \-data foo
+.Ve
+.PP
+then the stored data itself will be returned. If both are used:
+.PP
+.Vb 1
+\& xpaget xpamb \-info \-data foo
+.Ve
+.PP
+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.
+.PP
+If neither the \fB\-info\fR or \fB\-data\fR switch is specified, then
+the name refers to an \s-1XPA\s0 access point (with an optional paramlist
+following).
+For example:
+.PP
+.Vb 1
+\& xpaget xpamb ds9 file
+.Ve
+.PP
+is equivalent to:
+.PP
+.Vb 1
+\& xpaget ds9 file
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See xpa(n) for a list of \s-1XPA\s0 help pages