diff options
Diffstat (limited to 'xpa/doc/pod/xpacommon.pod')
-rw-r--r-- | xpa/doc/pod/xpacommon.pod | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/xpa/doc/pod/xpacommon.pod b/xpa/doc/pod/xpacommon.pod new file mode 100644 index 0000000..9fc9746 --- /dev/null +++ b/xpa/doc/pod/xpacommon.pod @@ -0,0 +1,266 @@ +=pod + +=head1 NAME + + + +B<XPACommon: Getting Common Information About Access Points> + + + +=head1 SYNOPSIS + + + + + +There are various kinds of generic information you can retrieve about +an XPA access point by using the xpaget command. + + + +=head1 DESCRIPTION + + + + + +You can find out which XPA access points have been registered with +the currently running +XPA name server +by executing the +xpaget +command to retrieve info from the XPA name server: + + xpaget xpans + +If, for example, the +stest test server program +is running, the following XPA access points will be returned (the specifics +of the returned info will vary for different machines and users): + + 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 + +Note that access to this information is subject to the usual +XPA Access Control restrictions. + + +Each XPA 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 +XPAGet() +or +XPASet() +in programs, e.g: + + xpaget ds9 -acl + xpaget ds9 -help + xpaget ds9 env FOO + + xpaset -p ds9 env FOO foofoo + +With the exception of B<-help> and B<-version>, reserved +sub-commands are available only on the machine on which the XPA server +itself is running. + +The following reserved sub-commands are defined for all access points: + + +=over 4 + + + + + + +=item * + +B<-acl> get (set) the access control list [options: host type acl, for set] + + +The 'xpaset' option allows you to add a new acl for a given host, or change +the acl for an existing host. See +XPA Access Control +for more information. +This access point is available only on the server machine. + + + + +=item * + +B<-env> get (set) an environment variable [options: name (value, for set)] + + +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.) + + + + +=item * + +B<-clipboard> set(get) information on a named clipboard + + +Clients can store ASCII 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: + + [data] | xpaset [server] -clipboard add|append [clipboard_name] + xpaset -p [server] -clipboard delete [clipboard_name] + +Use "add" to create a new clipboard or replace the contents of an existing +one. Use "append" to append to an existing clipboard. + +Information on a named clipboard is retrieved using: + + xpaget [server] -clipboard [clipboard_name] + + + + +=item * + +B<-exec> set: execute commands from buffer [options: none] + + +If -exec is specified in the paramlist of an 'xpaset' call, then further +sub-commands will be retrieved from the data buffer. + + + + +=item * + +B<-help> get: return help string for this XPA or sub-command [options: name (for sub-commands)] + + +Each XPA access point and each XPA 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 XPA 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. + + + + +=item * + +B<-ltimeout> get (set) the long timeout value [options: seconds|reset] + + +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 "reset" is +specified, then the timeout value will be reset to the default value. + + + + +=item * + +B<-nsconnect> set: re-establish name server connection to all XPA's [options: none] + + +If the +XPA 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 XPA name (since the latter requires the xpans +connection!): + + xpaset -p 838e2f67:1268 -nsconnect + +See xpans for more information. + + + + +=item * + +B<-nsdisconnect> set: break name server connection to all XPA's [options: none] + + +This sub-command will terminate the connection to the +XPA 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. + + + + +=item * + +B<-stimeout> get (set) the short timeout value [options: seconds|reset] + + +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 "reset" is +specified, then the timeout value will be reset to the default value. + + + + +=item * + +B<-remote> set: register xpa with remote server [options: host[:port] [acl]] [-proxy] + + +This sub-command will register the XPA access point with the XPA 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 "+" (meaning the remote +host can xpaset, xpaget, xpainfo or xpaaccess). If the acl is +specified as "-", then the access point is unregistered. +See Communication Between Machines +for more information on how this sub-command is used. + + + + +=item * + +B<-version> get: return XPA version string [options: none] + + +The version refers to the version of XPA used to define this access point +(currently something like 2.0). + + + +=back + + + + +You can add your own reserved commands to all XPA access points by using the +XPACmdAdd() +routine, passing the XPA handle returned by I<XPA XPAGetReserved(void)> +as the first argument. Note again that these will only be available on the +machine where the XPA service is running. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut |