![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to initiator.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual|
Return to initiator.tex CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual |
1.1 root 1: % run this through LaTeX with the appropriate wrapper
2:
3: \chapter {Boilerplate for Initiators}\label{cook:initiator}
4: Let's consider how to build an initiator which is also an invoker.
5: In Chapter~\ref{cook:discipline},
6: two forms for an initiator were identified:
7: {\em interactive}, and {\em embedded}.
8: The interactive initiator can be thought of as simply being a special case of
9: an embedded initiator.
10: Hence,
11: we will start by describing the embedded initiator and then describe the
12: additional structure added to form an interactive initiator.
13:
14: If you have access to the source tree for this release,
15: the directory \file{others/lookup/} contains the boilerplate described herein.
16:
17: \section {Embedded Initiator}
18: An embedded initiator is characterized as automatically managing an association
19: and invoking operations as required.
20: There are four areas: association establishment, operation invocation,
21: association release, and error handling.
22:
23: \subsection {Association Establishment}
24: The application-entity information and presentation address for the desired
25: service are computed,
26: along with the application context and default presentation context
27: information for the service.
28: In addition,
29: a session reference identifier is chosen.
30:
31: The routine \verb"AcAssocRequest" is called to establish an association for
32: the service.
33: The arguments are strictly boilerplate:
34: they will work unaltered for most applications.
35: If the association is established,
36: then the routine \verb"RoSetService" is used to tell the remote operations
37: library to use the presentation service as its underlying service.
38:
39: \tgrindfile{ryinit-estab}
40: \newpage
41:
42: \subsection {Operation Invocation}
43: We'll consider how an operation is invoked using both the synchronous and
44: asynchronous interfaces.
45:
46: \subsubsection {Synchronous Invocation}
47: First, the argument (if any) for the operation is allocated and initialized.
48: Then the macro \verb"op_MODULE_operation" is called,
49: which is really a call to the \verb"RyOperation" routine described in
50: Section~\ref{ryoperation} on page~\pageref{ryoperation}.
51: One of three values is expected to be returned.
52:
53: If the manifest constant \verb"NOTOK" is returned,
54: then some error has occured prior to invoking the operation.
55: The most common error is the association being abruptly terminated due to
56: network failure.
57:
58: If the manifest constant \verb"OK" is returned,
59: then the responder replied with either a result or an error for the invocation.
60: The variable \verb"response" is consulted to determine if a result is
61: present, or if not, which error is present.
62: For each case,
63: the \verb"out" variable is cast to the appropriate variable,
64: the application-specific code is executed,
65: and then the structure is freed.
66:
67: If the manifest constant \verb"DONE" is returned,
68: then the responder indicated that it wished to terminate the association.
69: Since the association was established in a way which prohibited this behavior,
70: this return is unlikely.
71:
72: \tgrindfile{ryinit-invoke}
73: \newpage
74:
75: \subsubsection {ASynchronous Invocation}
76:
77: \tgrindfile{ryinit-async}
78: \newpage
79:
80:
81: \subsection {Association Release}
82: Terminating the assocation is simple:
83: the routine \verb"AcRelRequest" is called.
84:
85: \tgrindfile{ryinit-release}
86: \newpage
87:
88: \subsection {Error Handling}
89: These routines for the most part are all straight-forward.
90: \begin{describe}
91: \item[\verb"ros\_adios":] used to report a ROS error and terminate;
92:
93: \item[\verb"ros\_advise":] used to report a ROS error;
94:
95: \item[\verb"acs\_adios":] used to report an ACS error and terminate;
96:
97: \item[\verb"acs\_advise":] used to report an ACS error;
98:
99: \item[\verb"adios":] used to report an error and terminate;
100: and,
101:
102: \item[\verb"advise":] used to report an error.
103: \end{describe}
104: It is assumed that there is a definition of the form
105: \begin{quote}\small\begin{verbatim}
106: char *myname = "myname";
107: \end{verbatim}\end{quote}
108: for use by the \verb"advise" routine.
109:
110: \tgrindfile{ryinit-error}
111: \newpage
112:
113: \section {Interactive Initiator}
114: Now, let's build on these routines to write an initiator which is interactive:
115: the user runs a program and interactively directs the invocation of
116: operations.
117:
118: \subsection {Include File}
119: Let's consider what an \verb"#include" file, say \verb"ryinitiator.h",
120: might look like.
121: First, the standard \man librosy(3n) definitions are included,
122: then a \verb"dispatch" structure is defined,
123: along with the boilerplate routines.
124: The \verb"dispatch" structure will be used by the boilerplate to invoke a
125: user-supplied routine that will invoke the operation.
126:
127: \tgrindfile{ryinitiator-h}
128: \newpage
129:
130: \subsection {Worker Routines}
131: Now, let's consider the routines which implement the interactive initiator.
132: There are only two: \verb"ryinitiator" and \verb"getline".
133:
134: The \verb"ryinitiator" routine does most of the work:
135: \begin{quote}\index{ryinitiator}\small\begin{verbatim}
136: int ryinitiator (argc, argv, myservice, mycontext,
137: mypci, ops, dispatches, quit)
138: int argc;
139: char **argv,
140: *myservice,
141: *mycontext,
142: *mypci;
143: struct RyOperation ops[];
144: struct dispatch *dispatches;
145: IFP quit;
146: \end{verbatim}\end{quote}
147: The parameters to this procedure are:
148: \begin{describe}
149: \item[\verb"argc"/\verb"argv":] the argument vector (and its length)
150: that the program was invoked with;
151:
152: \item[\verb"myservice":] the non-host portion of the application-entity
153: information;
154:
155: \item[\verb"mycontext":] the application context name of the service;
156:
157: \item[\verb"mypci":] the abstract syntax of the service;
158:
159: \item[\verb"ops":] the operations defined for the service;
160:
161: \item[\verb"dispatches":] a pointer to a \verb"dispatch" table;
162: and,
163:
164: \item[\verb"quit":] a routine to call when the association is to be
165: terminated.
166: \end{describe}
167: The function of this routine is straight-forward though tedious.
168: First, \verb"myname" is initialized to the name that the program was invoked
169: with.
170: Next, a rudimentary argument check is done,
171: and the application-entity information and presentation address for the desired
172: service are computed.
173: This is followed by computing the application context and default
174: presentation context information for the service,
175: along with a session reference identifier.
176: Finally, some diagnostic information may be printed out if the program will
177: operate in interactive mode.
178:
179: The routine \verb"AcAssocRequest" is called to establish an association for
180: the service.
181: If successful,
182: the routine \verb"RoSetService" is used to tell the remote operations library
183: to use the presentation service as the underlying service.
184:
185: The interactive loop is then entered:
186: a line is read from the standard input (the \verb"getline" routine is called),
187: it is broken into components,
188: a search is performed on the dispatch table to find a matching keyword,
189: and then finally the user-supplied routine is called.
190: When end-of-file is reached
191: (or if the user-supplied routine returns the manifest constant \verb"DONE"),
192: the assocation is released.
193:
194: If additional arguments were present on the invocation line,
195: then the named operation is invoked instead of entering an interactive loop.
196:
197: \tgrindfile{ryinitiator-c}
198: \newpage
199:
200: \subsection {An Example}
201: An example of an interactive initiator written using this boilerplate is
202: shown in Section~\ref{passwd:initiator} on page~\pageref{passwd:initiator}.
203: However,
204: a brief exposition of the \verb"dispatch" structure and possible
205: \verb"help" and \verb"quit" routines are shown here.
206:
207: \tgrindfile{ryinit-example}
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.