path: root/xpa/man/mann/xpacommon.n

.\" 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 "xpacommon n"
.TH xpacommon n "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"
\&\fBXPACommon: Getting Common Information About Access Points\fR
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
There are various kinds of generic information you can retrieve about
an \s-1XPA\s0 access point by using the xpaget command.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
You can find out which \s-1XPA\s0 access points have been registered with
the currently running 
\&\s-1XPA\s0 name server
by executing the
xpaget
command to retrieve info from the \s-1XPA\s0 name server:
.PP
.Vb 1
\&  xpaget xpans
.Ve
.PP
If, for example, the
stest test server program
is running, the following \s-1XPA\s0 access points will be returned (the specifics
of the returned info will vary for different machines and users):
.PP
.Vb 4
\&  XPA xpa gs 838e2f67:1262 eric
\&  XPA xpa1 gs 838e2f67:1266 eric
\&  XPA c_xpa gs 838e2f67:1267 eric
\&  XPA i_xpa i 838e2f67:1268 eric
.Ve
.PP
Note that access to this information is subject to the usual
\&\s-1XPA\s0 Access Control restrictions.
.PP
Each \s-1XPA\s0 access point supports a number of reserved sub-commands that provide
access to different kinds of information, e.g. the access control for
that access point.  These sub-commands can be executed by using
xpaset
or
xpaget
at the command line, or
\&\fIXPAGet()\fR
or
\&\fIXPASet()\fR
in programs, e.g:
.PP
.Vb 3
\&  xpaget ds9 \-acl
\&  xpaget ds9 \-help
\&  xpaget ds9 env FOO
\&
\&  xpaset \-p ds9 env FOO foofoo
.Ve
.PP
With the exception of \fB\-help\fR and \fB\-version\fR, reserved
sub-commands are available only on the machine on which the \s-1XPA\s0 server
itself is running.
.PP
The following reserved sub-commands are defined for all access points:
.IP "\(bu" 4
\&\fB\-acl\fR get (set) the access control list [options: host type acl, for set]
.Sp
The 'xpaset' option allows you to add a new acl for a given host, or change
the acl for an existing host. See
\&\s-1XPA\s0 Access Control
for more information.
This access point is available only on the server machine.
.IP "\(bu" 4
\&\fB\-env\fR get (set) an environment variable [options: name (value, for set)]
.Sp
The 'xpaget' option will return the value of the named environment
variable.  The 'xpaset' option will set the value of the names
variable to the specified value.
This access point is available only on the server machine.
(Please be advised that we have had problems setting environment
variables in static Tcl/Tk programs such as ds9 running under Linux.)
.IP "\(bu" 4
\&\fB\-clipboard\fR set(get) information on a named clipboard
.Sp
Clients can store \s-1ASCII\s0 state information on any number of named
clipboards. Clipboards of the same name created by clients on
different machines are kept separate.  The syntax for creating a
clipboard is:
.Sp
.Vb 2
\&  [data] | xpaset [server] \-clipboard add|append [clipboard_name]
\&  xpaset \-p [server] \-clipboard delete [clipboard_name]
.Ve
.Sp
Use \*(L"add\*(R" to create a new clipboard or replace the contents of an existing
one. Use \*(L"append\*(R" to append to an existing clipboard.
.Sp
Information on a named clipboard is retrieved using:
.Sp
.Vb 1
\&  xpaget [server] \-clipboard [clipboard_name]
.Ve
.IP "\(bu" 4
\&\fB\-exec\fR set: execute commands from buffer [options: none]
.Sp
If \-exec is specified in the paramlist of an 'xpaset' call, then further
sub-commands will be retrieved from the data buffer.
.IP "\(bu" 4
\&\fB\-help\fR get: return help string for this \s-1XPA\s0 or sub-command [options: name (for sub\-commands)]
.Sp
Each \s-1XPA\s0 access point and each \s-1XPA\s0 sub-command can have a help string
associated with it that is specified when the access point is defined.
The \-help option will return this help string.  For \s-1XPA\s0 access points
that contain user-defined sub-commands, you can get the help string
for a particular sub-command by specifying its name, or else get the
help strings for all sub-commands if not name is specified.
.IP "\(bu" 4
\&\fB\-ltimeout\fR get (set) the long timeout value [options: seconds|reset]
.Sp
The 'xpaget' option will return the value of the long timeout (in seconds).
The 'xpaset' option will set the value of the long timeout. If \*(L"reset\*(R" is
specified, then the timeout value will be reset to the default value.
.IP "\(bu" 4
\&\fB\-nsconnect\fR set: re-establish name server connection to all \s-1XPA\s0's [options: none]
.Sp
If the 
\&\s-1XPA\s0 Name Server (xpans)
process has terminated unexpectedly and then re-started, this
sub-command can be used to re-establish the connection.  You use it by
sending the command to the [name:port] or [file] of the access point
instead of to the \s-1XPA\s0 name (since the latter requires the xpans
connection!):
.Sp
.Vb 1
\&  xpaset \-p 838e2f67:1268 \-nsconnect
.Ve
.Sp
See xpans for more information.
.IP "\(bu" 4
\&\fB\-nsdisconnect\fR set: break name server connection to all \s-1XPA\s0's [options: none]
.Sp
This sub-command will terminate the connection to the
\&\s-1XPA\s0 Name Server (xpans), thereby making
all access points inaccessible except through their underlying [name:port]
or [file] identifiers.  I forget why we added it, it seems pretty useless.
.IP "\(bu" 4
\&\fB\-stimeout\fR get (set) the short timeout value [options: seconds|reset]
.Sp
The 'xpaget' option will return the value of the short timeout (in seconds).
The 'xpaset' option will set the value of the short timeout. If \*(L"reset\*(R" is
specified, then the timeout value will be reset to the default value.
.IP "\(bu" 4
\&\fB\-remote\fR set: register xpa with remote server [options: host[:port] [acl]] [\-proxy]
.Sp
This sub-command will register the \s-1XPA\s0 access point with the \s-1XPA\s0 name
server (xpans) on the specified host (which must already be running).
The specified host also is given access control to the access point,
using the specified acl or the default acl of \*(L"+\*(R" (meaning the remote
host can xpaset, xpaget, xpainfo or xpaaccess). If the acl is
specified as \*(L"\-\*(R", then the access point is unregistered. 
See Communication Between Machines
for more information on how this sub-command is used.
.IP "\(bu" 4
\&\fB\-version\fR get: return \s-1XPA\s0 version string [options: none]
.Sp
The version refers to the version of \s-1XPA\s0 used to define this access point
(currently something like 2.0).
.PP
You can add your own reserved commands to all \s-1XPA\s0 access points by using the
\&\fIXPACmdAdd()\fR
routine, passing the \s-1XPA\s0 handle returned by \fI\s-1XPA\s0 XPAGetReserved(void)\fR
as the first argument. Note again that these will only be available on the
machine where the \s-1XPA\s0 service is running.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See xpa(n) for a list of \s-1XPA\s0 help pages