← Back to branch summary

~ubuntu-branches/debian/experimental/ion/experimental

« back to all changes in this revision

Viewing changes to ams/doc/pod1/amslog.pod

  • Committer: Package Import Robot
  • Author(s): Leo Iannacone
  • Date: 2012-02-01 09:46:31 UTC
  • Revision ID: package-import@ubuntu.com-20120201094631-qpfwehc1b7ftkjgx
Tags: upstream-2.5.3~dfsg1
Import upstream version 2.5.3~dfsg1

Show diffs side-by-side

added added

removed removed

Lines of Context:
ams/doc/pod1/amslog.pod
 
1
=head1 NAME
 
2
 
 
3
amslog - Asynchronous Message Service (AMS) test message receiver
 
4
 
 
5
=head1 SYNOPSIS
 
6
 
 
7
B<amslog> I<unit_name> I<role_name> I<application_name> I<authority_name> I<[{ s | i }]>
 
8
 
 
9
=head1 DESCRIPTION
 
10
 
 
11
B<amslog> is a message reception program designed to test AMS functionality.
 
12
 
 
13
When B<amslog> is started, it registers as an application module in the
 
14
unit identified by I<unit_name> of the venture identified by
 
15
I<application_name> and I<authority_name>; the role in which it registers
 
16
must be indicated in I<role_name>.  A configuration server for the local
 
17
continuum and a registrar for the indicated unit of the indicated venture
 
18
(which may both be instantiated in a single B<amsd> daemon task) must be
 
19
running in order for B<amslog> to run.
 
20
 
 
21
B<amslog> runs as two threads: a background thread that receives AMS messages
 
22
and logs them to standard output, together with a foreground thread that
 
23
acquires operating parameters in lines of console input to control the
 
24
flow of messages to the background thread.
 
25
 
 
26
When the first character of a line of input from stdin to the B<amslog>
 
27
foreground thread is '.' (period), B<amslog> immediately terminates.
 
28
Otherwise, the first character of each line of input from stdin must
 
29
be either '+' indicating assertion of interest in a message subject or
 
30
'-' indicating cessation of interest in a subject.  In each case, the
 
31
name of the subject in question must begin in the second character of
 
32
the input line.  Note that "everything" is a valid subject name.
 
33
 
 
34
By default, B<amslog> runs in "subscribe" mode: when interest in a message
 
35
subject is asserted, B<amslog> subscribes to that subject; when interest
 
36
in a message subject is rescinded, B<amslog> unsubscribes to that subject.
 
37
This behavior can be overridden by providing a third command-line argument
 
38
to B<amslog> - a "mode" indicator.  When mode is 'i', B<amslog> runs in
 
39
"invite" mode.  In "invite" mode, when interest in a message subject is
 
40
asserted, B<amslog> invites messages on that subject; when interest
 
41
in a message subject is rescinded, B<amslog> cancels its invitation for
 
42
messages on that subject.
 
43
 
 
44
The "domain" of a subscription or invitation can optionally be specified
 
45
immediately after the subject name, on the same line of console input:
 
46
 
 
47
=over 4
 
48
 
 
49
Domain continuum name may be specified, or the place-holder domain
 
50
continuum name "_" may be specified to indicate "all continua".
 
51
 
 
52
If domain continuum name ("_" or otherwise) is specified, then domain unit
 
53
name may be specified or the place-holder domain unit name "_" may be
 
54
specified to indicate "the root unit" (i.e., the entire venture).
 
55
 
 
56
If domain unit name ("_" or otherwise) is specified, then domain role
 
57
name may be specified.
 
58
 
 
59
=back
 
60
 
 
61
When B<amslog> runs in VxWorks or RTEMS, the subject and content of each
 
62
message are simply written to standard output in a text line for display
 
63
on the console.  When B<amslog> runs in a UNIX environment, the subject
 
64
name length (a binary integer), subject name (ASCII text), content length
 
65
(a binary integer), and content (ASCII text) are written to standard output
 
66
for redirection either to a file or to a pipe to B<amslogprt>.
 
67
 
 
68
Whenever a received message is flagged as a Query, B<amslog> returns a
 
69
reply message whose content is the string "Got " followed by the first
 
70
128 bytes of the content of the Query message, enclosed in single quote
 
71
marks and followed by a period.
 
72
 
 
73
=head1 EXIT STATUS
 
74
 
 
75
=over 4
 
76
 
 
77
=item -1
 
78
 
 
79
B<amslog> terminated with an error as noted in the ion.log file.
 
80
 
 
81
=item 0
 
82
 
 
83
B<amslog> terminated normally.
 
84
 
 
85
=back
 
86
 
 
87
=head1 FILES
 
88
 
 
89
A MIB initialization file with the applicable default name (see amsrc(5))
 
90
must be present.
 
91
 
 
92
=head1 ENVIRONMENT
 
93
 
 
94
No environment variables apply.
 
95
 
 
96
=head1 DIAGNOSTICS
 
97
 
 
98
=over 4
 
99
 
 
100
=item amslog can't register.
 
101
 
 
102
B<amslog> failed to register, for reasons noted in the ion.log file.
 
103
 
 
104
=item amslog can't set event manager.
 
105
 
 
106
B<amslog> failed to start its background thread, for reasons noted in
 
107
the ion.log file.
 
108
 
 
109
=item amslog can't read from stdin
 
110
 
 
111
B<amslog> foreground thread failed to read console input, for reasons
 
112
noted in the ion.log file.
 
113
 
 
114
=back
 
115
 
 
116
=head1 BUGS
 
117
 
 
118
Report bugs to <ion-bugs@korgano.eecs.ohiou.edu>
 
119
 
 
120
=head1 SEE ALSO
 
121
 
 
122
amsshell(1), amslogprt(1), amsrc(5)