.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" 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 "AMSSHELL 1"
.TH AMSSHELL 1 "2016-07-07" "perl v5.24.1" "AMS executables"
.\" 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"
amsshell \- Asynchronous Message Service (AMS) test message sender (UNIX)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBamsshell\fR \fIunit_name\fR \fIrole_name\fR \fIapplication_name\fR \fIauthority_name\fR \fI[{ p | s | q | a }]\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBamsshell\fR is a message issuance program designed to test \s-1AMS\s0 functionality.
.PP
When \fBamsshell\fR is started, it registers as an application module in the
unit identified by \fIunit_name\fR of the venture identified by
\&\fIapplication_name\fR and \fIauthority_name\fR; the role in which it registers
must be indicated in \fIrole_name\fR.  A configuration server for the local
continuum and a registrar for the indicated unit of the indicated venture
(which may both be instantiated in a single \fBamsd\fR daemon task) must be
running in order for \fBamsshell\fR to run.
.PP
\&\fBamsshell\fR runs as two threads: a background thread that receives watches
for \s-1AMS\s0 configuration events (including shutdown), together with a foreground
thread that acquires operating parameters and message content in lines of
console input to control the issuance of messages.
.PP
The first character of each line of input from stdin to the \fBamsshell\fR
indicates the significance of that line:
.IP "\fB=\fR" 4
.IX Item "="
Sets the name of the subject on which all messages are to be issued, until
superseded by another \*(L"=\*(R" line.  The subject name must begin at the
second character of this line.  Optionally, subject name may be followed
by a single ' ' (space) character and then the text of the first message
to be issued on this subject, which is to be issued immediately.
.IP "\fBr\fR" 4
.IX Item "r"
Sets the number of the role constraining the domain of message issuance.
The role number must begin at the second character of this line.
.IP "\fBc\fR" 4
.IX Item "c"
Sets the number of the continuum constraining the domain of message issuance.
The continuum number must begin at the second character of this line.
.IP "\fBu\fR" 4
.IX Item "u"
Sets the number of the unit constraining the domain of message issuance.
The unit number must begin at the second character of this line.
.IP "\fBm\fR" 4
.IX Item "m"
Sets the number of the module to which subsequent messages are to be issued.
The module number must begin at the second character of this line.
.IP "\fB.\fR" 4
.IX Item "."
Terminates \fBamsshell\fR.
.PP
When the first character of a line of input from stdin is none of the
above, the entire line is taken to be the text of a message that is
to be issued immediately, on the previously specified subject, to the
previously specified module (if applicable), and subject to the previously
specified domain (if applicable).
.PP
By default, \fBamsshell\fR runs in \*(L"publish\*(R" mode: when a message is to be
issued, it is simply published.  This behavior can be overridden by
providing a fifth command-line argument to \fBamsshell\fR \- a \*(L"mode\*(R"
indicator.  The supported modes are as follows:
.IP "\fBp\fR" 4
.IX Item "p"
This is \*(L"publish\*(R" mode.  Every message is published.
.IP "\fBs\fR" 4
.IX Item "s"
This is \*(L"send\*(R" mode.  Every message is sent privately to the application
module identified by the specified module, unit, and continuum numbers.
.IP "\fBq\fR" 4
.IX Item "q"
This is \*(L"query\*(R" mode.  Every message is sent privately to the application
module identified by the specified module, unit, and continuum numbers,
and \fBamsshell\fR then waits for a reply message before continuing.
.IP "\fBa\fR" 4
.IX Item "a"
This is \*(L"announce\*(R" mode.  Every message is announced to all modules in
the domain established by the previously specified role, unit, and
continuum numbers.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
.IP "\-1" 4
.IX Item "-1"
\&\fBamsshell\fR terminated with an error as noted in the ion.log file.
.ie n .IP """0""" 4
.el .IP "``0''" 4
.IX Item "0"
\&\fBamsshell\fR terminated normally.
.SH "FILES"
.IX Header "FILES"
A \s-1MIB\s0 initialization file with the applicable default name (see \fIamsrc\fR\|(5))
must be present.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
No environment variables apply.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.IP "amsshell can't register." 4
.IX Item "amsshell can't register."
\&\fBamsshell\fR failed to register, for reasons noted in the ion.log file.
.IP "amsshell can't set event manager." 4
.IX Item "amsshell can't set event manager."
\&\fBamsshell\fR failed to start its background thread, for reasons noted in
the ion.log file.
.SH "BUGS"
.IX Header "BUGS"
Report bugs to <ion\-bugs@korgano.eecs.ohiou.edu>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIamslog\fR\|(1), \fIamsrc\fR\|(5)