![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to appendix2.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 appendix2.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 {Old-Style Associations}\label{old-style}
4: As discussed in Section~\ref{acs:note},
5: there are several ways to establish an association.
6: In the interests of compatibility with previously specified applications,
7: the \man librosap(3n) and \man librtsap(3n) libraries support ``old-style''
8: mechanisms for binding associations.
9: These are discussed in this appendix.
10: Use of these facilities for new applications is strongly discouraged.
11:
12: \section {Remote Operations}\label{ros:old-style}
13: Under old-style association handling for remote operations,
14: the mechanism used for establishing the association determines the
15: remote operations service discipline to be used.
16: If the basic service discipline is desired,
17: then continue reading this section which describes the addressing and
18: initialization mechanisms for native ROS associations.
19: These make use of the {\sf RO-BEGIN\/} and {\sf RO-END\/} primitives.
20: Instead,
21: if the advanced service discipline is desired,
22: then read Section~\ref{rts:old-style} on page~\pageref{rts:old-style}
23: which describes how
24: associations are established and released by the reliable transfer service
25: (RTS) using the {\sf X.410 OPEN\/} and {\sf X.410 CLOSE\/} primitives.
26: (Be sure to also read Section~\ref{ros:underlying} on
27: page~\pageref{ros:underlying}).
28:
29: \subsection {Addresses}
30: Addresses at the remote operations service access point are represented by the
31: \verb"RoSAPaddr" structure.
32: \begin{quote}\index{RoSAPaddr}\small\begin{verbatim}
33: struct RoSAPaddr {
34: struct SSAPaddr roa_addr;
35:
36: u_short roa_port;
37: };
38: \end{verbatim}\end{quote}
39: This structure contains two elements:
40: \begin{describe}
41: \item[\verb"roa\_addr":] the session address,
42: as described in Section~\ref{ssap:addresses} on page~\pageref{ssap:addresses}
43: of \voltwo/;
44: and,
45:
46: \item[\verb"roa\_port":] the port number of the entity residing above the
47: RoSAP,
48: as described in the \man isoservices(5) database,
49: for the service provider \verb"rosap".
50: \end{describe}
51:
52: In Figure~\ref{getDSentity},
53: an example of how one constructs the RoSAP address for the directory services
54: entity on host \verb"RemoteHost" is presented.
55: (The routine \verb"is2saddr" is described on page~\pageref{ssap:addresses}
56: of \voltwo/.)
57: \tagrind[tp]{grindB-1}%
58: {Constructing the RoSAP address for the Directory Services entity}%
59: {getDSentity}
60:
61: \subsection {Association Establishment}
62: The \man librosap(3n) library distinguishes between the user which started an
63: association,
64: the {\em initiator},
65: and the user which subsequently was bound to the association,
66: the {\em responder}.
67: We sometimes term these two entities the {\em client\/} and the {\em server},
68: respectively.
69:
70: \subsubsection {Server Initialization}
71: The \man tsapd(8c) daemon,
72: upon accepting a connection from an initiating host,
73: consults the ISO services database to determine which program
74: on the local system implements the desired RoSAP entity.
75: In the case of the remote operations service,
76: the \pgm{tsapd} program contains the bootstrap for the remote operations
77: provider.
78: The daemon will again consult the ISO services database to determine which
79: program on the system implements the desired RoSAP entity.
80:
81: Once the program has been ascertained,
82: the daemon runs the program with any arguments listed in the database.
83: In addition,
84: it appends some {\em magic arguments\/} to the argument vector.
85: Hence,
86: the very first action performed by the responder is to re-capture the RoSAP
87: state contained in the magic arguments.
88: This is done by calling the routine \verb"RoInit",
89: which on a successful return,
90: is equivalent to a {\sf RO-BEGIN.INDICATION\/} from the remote operations
91: service provider.
92: \begin{quote}\index{RoInit}\small\begin{verbatim}
93: int RoInit (vecp, vec, ros, roi)
94: int vecp;
95: char **vec;
96: struct RoSAPstart *ros;
97: struct RoSAPindication *roi;
98: \end{verbatim}\end{quote}
99: The parameters to this procedure are:
100: \begin{describe}
101: \item[\verb"vecp":] the length of the argument vector;
102:
103: \item[\verb"vec":] the argument vector;
104:
105: \item[\verb"ros":] a pointer to a \verb"RoSAPstart" structure, which is
106: updated only if the call succeeds;
107: and,
108:
109: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
110: updated only if the call fails.
111: \end{describe}
112: If \verb"RoInit" is successful,
113: it returns information in the \verb"ros" parameter,
114: which is a pointer to a \verb"RoSAPstart" structure.
115: \begin{quote}\index{RoSAPstart}\small\begin{verbatim}
116: struct RoSAPstart {
117: int ros_sd;
118:
119: struct RoSAPaddr ros_initiator;
120:
121: u_short ros_port;
122:
123: PE ros_data;
124: };
125: \end{verbatim}\end{quote}
126: The elements of this structure are:
127: \begin{describe}
128: \item[\verb"ros\_sd":] the association-descriptor to be used to
129: reference this association;
130:
131: \item[\verb"ros\_initiator":] the ``unique identifier'' of the initiator
132: (containing the initiator's host address);
133:
134: \item[\verb"ros\_port":] the application number the initiator wishes to use
135: to govern the association;
136: and
137:
138: \item[\verb"ros\_data":] any initial data (this is a pointer to a
139: \verb"PElement" structure, which is fully explained in Chapter~\ref{libpsap}).
140: \end{describe}
141: Note that the \verb"ros_data" element is allocated via \man malloc(3) and
142: should be released using the \verb"ROSFREE" macro when no longer referenced.
143: The \verb"ROSFREE" macro behaves as if it was defined as:
144: \begin{quote}\index{ROSFREE}\small\begin{verbatim}
145: void ROSFREE (ros)
146: struct RoSAPstart *ros;
147: \end{verbatim}\end{quote}
148: The macro frees only the data allocated by \verb"RoInit",
149: and not the \verb"RoSAPstart" structure itself.
150: Further,
151: \verb"ROSFREE" should be called only if the call to the \verb"RoInit"
152: routine returned \verb"OK".
153:
154: If the call to \verb"RoInit" is not successful,
155: then a {\sf RO-P-REJECT.IN\-DI\-CA\-TION\/} event is simulated,
156: and the relevant information is returned in an encoded
157: \verb"RoSAPindication" structure.
158:
159: After examining the information returned by \verb"RoInit" on a successful call
160: (and possibly after examining the argument vector),
161: the responder should either accept or reject the association.
162: For either response,
163: the responder should use
164: the \verb"RoBeginResponse" routine
165: (which corresponds to the {\sf RO-BEGIN.RESPONSE\/} action).
166: \begin{quote}\index{RoBeginResponse}\small\begin{verbatim}
167: int RoBeginResponse (sd, status, data, roi)
168: int sd;
169: int status;
170: PE data;
171: struct RoSAPindication *roi;
172: \end{verbatim}\end{quote}
173: The parameters to this procedure are:
174: \begin{describe}
175: \item[\verb"sd":] the association-descriptor;
176:
177: \item[\verb"status":] the acceptance indicator
178: (either \verb"ROS_ACCEPT" if the association is to be accepted,
179: or one of the ``fatal'' user-initiated rejection codes listed in
180: Table~\ref{RoSAPreasons} on page~\pageref{RoSAPreasons});
181:
182: \item[\verb"data":] any initial data if the association is to be accepted;
183: and,
184:
185: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
186: updated only if the call fails.
187: \end{describe}
188: If the call to \verb"RoBeginResponse" is successful,
189: and the \verb"status" parameter is set to \verb"ROS_ACCEPT",
190: then association establishment has now been completed.
191: If the call is successful,
192: but the \verb"status" parameter is not \verb"ROS_ACCEPT",
193: then the association has been rejected and the responder may exit.
194: Otherwise,
195: if the call fails and the reason is ``fatal'',
196: then the association is closed.
197:
198: \subsubsection {Client Initialization}
199: A program wishing to associate itself with another user of remote operation
200: services calls the \verb"RoBeginRequest" routine,
201: which corresponds to the {\sf RO-BEGIN.REQUEST\/} action.
202: \begin{quote}\index{RoBeginRequest}\small\begin{verbatim}
203: int RoBeginRequest (called, data, roc, roi)
204: struct RoSAPaddr *called;
205: PE data;
206: struct RoSAPconnect *roc;
207: struct RoSAPindication *roi;
208: \end{verbatim}\end{quote}
209: The parameters to this procedure are:
210: \begin{describe}
211: \item[\verb"called":] the RoSAP address of the responder;
212:
213: \item[\verb"data":] any initial data;
214:
215: \item[\verb"roc":] a pointer to a \verb"RoSAPconnect" structure, which is
216: updated only if the call succeeds;
217: and,
218:
219: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
220: updated only if the call fails.
221: \end{describe}
222: If the call to \verb"RoBeginRequest" is successful
223: (this corresponds to a {\sf RO-BEGIN.CONFIRMATION\/} event),
224: it returns information in the \verb"roc" parameter,
225: which is a pointer to a \verb"RoSAPconnect" structure.
226: \begin{quote}\index{RoSAPconnect}\small\begin{verbatim}
227: struct RoSAPconnect {
228: int roc_sd;
229:
230: int roc_result;
231:
232: PE roc_data;
233: };
234: \end{verbatim}\end{quote}
235: The elements of this structure are:
236: \begin{describe}
237: \item[\verb"roc\_sd":] the association-descriptor to be used to
238: reference this association;
239:
240: \item[\verb"roc\_result":] the association response;
241: and,
242:
243: \item[\verb"roc\_data":] any initial data if the association was accepted.
244: \end{describe}
245: If the call to \verb"RoBeginRequest" is successful,
246: and the \verb"roc_result" element is set to \verb"ROS_ACCEPT",
247: then association establishment has completed.
248: If the call is successful,
249: but the \verb"roc_result" element is not \verb"ROS_ACCEPT",
250: the the association attempt has been rejected,
251: consult Table~\ref{RoSAPreasons} to determine the reason for the reject.
252: Otherwise, if the call fails then the association is not established and
253: the \verb"RoSAPpreject" structure of the \verb"RoSAPindication" discriminated
254: union has been updated.
255:
256: Note that the \verb"roc_data" element is allocated via \man malloc(3) and
257: should be released using the \verb"ROCFREE" macro when no longer referenced.
258: The \verb"ROCFREE" macro behaves as if it was defined as:
259: \begin{quote}\index{ROCFREE}\small\begin{verbatim}
260: void ROCFREE (roc)
261: struct RoSAPconnect *roc;
262: \end{verbatim}\end{quote}
263: The macro frees only the data allocated by \verb"RoBeginRequest",
264: and not the \verb"RoSAPconnect" structure itself.
265: Further,
266: \verb"ROCFREE" should be called only if the call to the \verb"RoBeginRequest"
267: routine returned \verb"OK".
268:
269: Note that in the basic service the arguement parameter to an Invoke request
270: cannot be NULL.
271: As well only the initiator may make invoke requests.
272:
273: \subsection {Association Release}
274: The \verb"RoEndRequest" routine is used to request the release of an
275: association,
276: and corresponds to a {\sf RO-END.REQUEST\/} action.
277: This action may be taken by only the initiator of an association.
278: \begin{quote}\index{RoEndRequest}\small\begin{verbatim}
279: int RoEndRequest (sd, priority, roi)
280: int sd;
281: int priority;
282: struct RoSAPindication *roi;
283: \end{verbatim}\end{quote}
284: The parameters to this procedure are:
285: \begin{describe}
286: \item[\verb"sd":] the association-descriptor;
287:
288: \item[\verb"priority":] the priority of this request;
289: and,
290:
291: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
292: updated only if the call fails.
293: \end{describe}
294: If the call to \verb"RoEndRequest" is successful,
295: then the association has been released.
296: Otherwise if the call fails and the error is not fatal,
297: then the association remains established and the \verb"RoSAPpreject" structure
298: contained in
299: the \verb"RoSAPindication" parameter \verb"roi" contains the reason for the
300: failure.
301:
302: Upon receiving a {\sf RO-END.INDICATION\/} event,
303: the user is required to generate a {\sf RO-END.RESPONSE\/} action
304: using the \verb"RoEndResponse" routine.
305: \begin{quote}\index{RoEndResponse}\small\begin{verbatim}
306: int RoEndResponse (sd, roi)
307: int sd;
308: struct RoSAPindication *roi;
309: \end{verbatim}\end{quote}
310: The parameters to this procedure are:
311: \begin{describe}
312: \item[\verb"sd":] the association-descriptor;
313: and,
314:
315: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
316: updated only if the call fails.
317: \end{describe}
318: If the call to \verb"RoEndResponse" is successful,
319: then the association has been released.
320:
321: \subsection {An Example}
322: Let's consider how one might construct a generic server which uses remote
323: operations services.
324: This entity will use an asynchronous interface and the basic service
325: discipline.
326: Note that we could have selected the advanced service discipline by using
327: \verb"RtBInit" instead of \verb"RoInit",
328: \verb"RtBeginResponse" instead of \verb"RoBeginResponse",
329: and
330: \verb"RtEndResponse" instead of \verb"RoEndResponse" (respectively).
331: This is demonstrated later in this appendix.
332:
333: There are two parts to the program:
334: initialization and the request/reply loop.
335: In our example,
336: we assume that the routine \verb"error" results in the process being
337: terminated after printing a diagnostic.
338:
339: In Figure~\ref{initROS:OLDresponder},
340: the initialization steps for the generic responder,
341: including the outer {\em C\/} wrapper,
342: is shown.
343: First, the RoSAP state is re-captured by calling \verb"RoInit".
344: If this succeeds,
345: then the association is authenticated and any command line arguments (as
346: specified in the \man isoservices(5) file) are parsed.
347: Assuming that the responder is satisfied with the proposed association,
348: it calls \verb"RoBeginResponse" to accept the association.
349: Then,
350: \verb"RoSetIndications" is set to specify an asynchronous event handler.
351: Finally,
352: the main request/reply loop is realized.
353: The server simply uses \man pause(2) to wait for the next event.
354: {\let\small=\scriptsize %%% yikes!
355: \tagrind[tp]{grindB-2}{Initializing the generic ROS responder}%
356: {initROS:OLDresponder}}
357:
358: Figure~\ref{doROSresponder} on page~\pageref{doROSresponder}
359: contains the definition of the
360: \verb"ros_indication" routine and associated routines.
361: Since the remote operations service was used to establish the association,
362: a different closing handler must be used.
363: This is shown in Figure~\ref{finROS:OLDresponder}.
364: {\let\small=\scriptsize %%% yikes!
365: \tagrind[tp]{grindB-3}%
366: {Finalizing the generic ROS responder}{finROS:OLDresponder}}
367:
368: \section {Reliable Transfer}\label{rts:old-style}
369: Under old-style association handling for reliable transfer,
370: the {\sf X.410 OPEN\/} and {\sf X.410 CLOSE\/} primitives are used.
371:
372: \subsection {Addresses}
373: Addresses at the reliable transfer service access point are represented by the
374: \verb"RtSAPaddr" structure.
375: \begin{quote}\index{RtSAPaddr}\small\begin{verbatim}
376: struct RtSAPaddr {
377: struct SSAPaddr rta_addr;
378:
379: u_short rta_port;
380: };
381: \end{verbatim}\end{quote}
382: This structure contains two elements:
383: \begin{describe}
384: \item[\verb"rta\_addr":] the session address,
385: as described in Section~\ref{ssap:addresses} on page~\pageref{ssap:addresses}
386: of \voltwo/;
387: and,
388:
389: \item[\verb"rta\_port":] the port number of the entity residing above the
390: RtSAP,
391: as described in the \man isoservices(5) database,
392: for the service provider \verb"rtsap".
393: \end{describe}
394:
395: In Figure~\ref{getP1entity},
396: an example of how one constructs the RtSAP address for the message transfer
397: entity on host \verb"RemoteHost" is presented.
398: (The routine \verb"is2saddr" is described on page~\pageref{ssap:addresses}
399: of \voltwo/.)
400: \tagrind[tp]{grindB-4}%
401: {Constructing the RtSAP address for the Message Transfer entity}%
402: {getP1entity}
403:
404: \subsection {Association Establishment}
405: The \man librtsap(3n) library distinguishes between the user which started an
406: association,
407: the {\em initiator},
408: and the user which was subsequently bound to the association,
409: the {\em responder}.
410: We sometimes term these two entities the {\em client\/} and the {\em server},
411: respectively.
412:
413: \subsubsection {Server Initialization}
414: The \man tsapd(8c) daemon,
415: upon accepting a connection from an initiating host,
416: consults the ISO services database to determine which program
417: on the local system implements the desired SSAP entity.
418: In the case of the reliable transfer service,
419: the \pgm{tsapd} program contains the bootstrap for the reliable transfer
420: provider.
421: The daemon will again consult the ISO services database to determine which
422: program on the system implements the desired RtSAP entity.
423:
424: Once the program has been ascertained,
425: the daemon runs the program with any arguments listed in the database.
426: In addition,
427: it appends some {\em magic arguments\/} to the argument vector.
428: Hence,
429: the very first action performed by the responder is to re-capture the RtSAP
430: state contained in the magic arguments.
431: This is done by calling the routine \verb"RtBInit",
432: which on a successful return,
433: is equivalent to a {\sf X.410 OPEN.INDICATION\/} from the reliable transfer
434: service provider.
435: \begin{quote}\index{RtBInit}\small\begin{verbatim}
436: int RtBInit (vecp, vec, rts, rti)
437: int vecp;
438: char **vec;
439: struct RtSAPstart *rts;
440: struct RtSAPindication *rti;
441: \end{verbatim}\end{quote}
442: The parameters to this procedure are:
443: \begin{describe}
444: \item[\verb"vecp":] the length of the argument vector;
445:
446: \item[\verb"vec":] the argument vector;
447:
448: \item[\verb"rts":] a pointer to a \verb"RtSAPstart" structure, which is
449: updated only if the call succeeds;
450: and,
451:
452: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
453: updated only if the call fails.
454: \end{describe}
455: If \verb"RtBInit" is successful,
456: it returns information in the \verb"rts" parameter,
457: which is a pointer to a \verb"RtSAPstart" structure.
458: \begin{quote}\index{RtSAPstart}\small\begin{verbatim}
459: struct RtSAPstart {
460: int rts_sd;
461:
462: struct RtSAPaddr rts_initiator;
463:
464: int rts_mode;
465: #define RTS_MONOLOGUE 0
466: #define RTS_TWA 1
467:
468: int rts_turn;
469: #define RTS_INITIATOR 0
470: #define RTS_RESPONDER 1
471:
472: u_short rts_port;
473:
474: PE rts_data;
475: };
476: \end{verbatim}\end{quote}
477: The elements of this structure are:
478: \begin{describe}
479: \item[\verb"rts\_sd":] the association-descriptor to be used to
480: reference this association;
481:
482: \item[\verb"rts\_initiator":] the address of the initiator;
483:
484: \item[\verb"rts\_mode":] the dialogue mode (either monologue or two-way
485: alternate),
486:
487: \item[\verb"rts\_turn":] the owner of the turn initially;
488:
489: \item[\verb"rts\_port":] the application number the initiator wishes to use
490: to govern the association;
491: and
492:
493: \item[\verb"rts\_data":] any initial data (this is a pointer to a
494: \verb"PElement" structure, which is fully explained in Chapter~\ref{libpsap}).
495: \end{describe}
496: Note that the \verb"rts_data" element is allocated via \man malloc(3) and
497: should be released by using the \verb"RTSFREE" macro when no longer referenced.
498: The \verb"RTSFREE" macro behaves as if it was defined as:
499: \begin{quote}\index{RTSFREE}\small\begin{verbatim}
500: void RTSFREE (rts)
501: struct RtSAPstart *rts;
502: \end{verbatim}\end{quote}
503: The macro frees only the data allocated by \verb"RtBInit",
504: and not the \verb"RtSAPstart" structure itself.
505: Further,
506: \verb"RTSFREE" should be called only if the call to the \verb"RtBInit"
507: routine returned \verb"OK".
508:
509: If the call to \verb"RtBInit" is not successful,
510: then a {\sf RT-P-ABORT.INDICATION\/} event is simulated,
511: and the relevant information is returned in an encoded
512: \verb"RtSAPindication" structure.
513:
514: After examining the information returned by \verb"RtBInit" on a successful call
515: (and possibly after examining the argument vector),
516: the responder should either accept or reject the association.
517: For either response,
518: the responder should use
519: the \verb"RtBeginResponse" routine
520: (which corresponds to the {\sf X.410 OPEN.RESPONSE\/} action).
521: \begin{quote}\index{RtBeginResponse}\small\begin{verbatim}
522: int RtBeginResponse (sd, status, data, rti)
523: int sd;
524: int status;
525: PE data;
526: struct RtSAPindication *rti;
527: \end{verbatim}\end{quote}
528: The parameters to this procedure are:
529: \begin{describe}
530: \item[\verb"sd":] the association-descriptor;
531:
532: \item[\verb"status":] the acceptance indicator
533: (either \verb"RTS_ACCEPT" if the association is to be accepted,
534: or one of the ``fatal'' user-initiated rejection codes,
535: other tha \verb"RTS_REJECT",
536: listed in Table~\ref{RtSAPreasons} on page~\pageref{RtSAPreasons});
537:
538: \item[\verb"data":] any initial data if the association is to be accepted;
539: and,
540:
541: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
542: updated only if the call fails.
543: \end{describe}
544: If the call to \verb"RtBeginResponse" is successful,
545: and the \verb"status" parameter is set to \verb"RTS_ACCEPT",
546: then association establishment has now been completed.
547: If the call is successful,
548: but the \verb"status" parameter is not \verb"RTS_ACCEPT",
549: then the association has been rejected and the responder may exit.
550: Otherwise,
551: if the call fails and the reason is ``fatal'',
552: then the association is closed.
553:
554: \subsubsection {Client Initialization}
555: A program wishing to associate itself with another user of reliable transfer
556: services calls the \verb"RtBeginRequest" routine,
557: which corresponds to the {\sf X.410 OPEN.REQUEST\/} action.
558: \begin{quote}\index{RtBeginRequest}\small\begin{verbatim}
559: int RtBeginRequest (called, mode, turn, data, rtc, rti)
560: struct RtSAPaddr *called;
561: int mode,
562: turn;
563: PE data;
564: struct RtSAPconnect *rtc;
565: struct RtSAPindication *rti;
566: \end{verbatim}\end{quote}
567: The parameters to this procedure are:
568: \begin{describe}
569: \item[\verb"called":] the RtSAP address of the responder;
570:
571: \item[\verb"mode":] the dialogue mode;
572:
573: \item[\verb"turn":] who gets the initial turn;
574:
575: \item[\verb"data":] any initial data;
576:
577: \item[\verb"rtc":] a pointer to a \verb"RtSAPconnect" structure, which is
578: updated only if the call succeeds;
579: and,
580:
581: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
582: updated only if the call fails.
583: \end{describe}
584: If the call to \verb"RtBeginRequest" is successful
585: (this corresponds to a {\sf X.410 OPEN.CONFIRMATION\/} event),
586: it returns information in the \verb"rtc" parameter,
587: which is a pointer to a \verb"RtSAPconnect" structure.
588: \begin{quote}\index{RtSAPconnect}\small\begin{verbatim}
589: struct RtSAPconnect {
590: int rtc_sd;
591:
592: int rtc_result;
593:
594: PE rtc_data;
595: };
596: \end{verbatim}\end{quote}
597: The elements of this structure are:
598: \begin{describe}
599: \item[\verb"rtc\_sd":] the association-descriptor to be used to
600: reference this association;
601:
602: \item[\verb"rtc\_result":] the association response;
603: and,
604:
605: \item[\verb"rtc\_data":] any initial data if the association was accepted.
606: \end{describe}
607: If the call to \verb"RtBeginRequest" is successful,
608: and the \verb"rtc_result" element is set to \verb"RTS_ACCEPT",
609: then association establishment has completed.
610: If the call is successful,
611: but the \verb"rtc_result" element is not \verb"RTS_ACCEPT",
612: the the association attempt has been rejected;
613: consult Table~\ref{RtSAPreasons} to determine the reason for the reject.
614: Otherwise, if the call fails then the association is not established and
615: the \verb"RtSAPabort" structure of the \verb"RtSAPindication" discriminated
616: union has been updated.
617:
618: Note that the \verb"rtc_data" element is allocated via \man malloc(3) and
619: should be released using the \verb"RTCFREE" macro when no longer referenced.
620: The \verb"RTCFREE" macro behaves as if it was defined as:
621: \begin{quote}\index{RTCFREE}\small\begin{verbatim}
622: void RTCFREE (rtc)
623: struct RtSAPconnect *rtc;
624: \end{verbatim}\end{quote}
625: The macro frees only the data allocated by \verb"RtBeginRequest",
626: and not the \verb"RtSAPconnect" structure itself.
627: Further,
628: \verb"RTCFREE" should be called only if the call to the \verb"RtBeginRequest"
629: routine returned \verb"OK".
630:
631: \subsection {Association Release}
632: The \verb"RtEndRequest" routine is used to request the release of an
633: association,
634: and corresponds to a {\sf X.410 CLOSE.REQUEST\/} action.
635: This action may be taken by only the initiator of an association,
636: and, if the dialogue mode is two-way alternate,
637: if the initiator has the turn as well.
638: \begin{quote}\index{RtEndRequest}\small\begin{verbatim}
639: int RtEndRequest (sd, rti)
640: int sd;
641: struct RtSAPindication *rti;
642: \end{verbatim}\end{quote}
643: The parameters to this procedure are:
644: \begin{describe}
645: \item[\verb"sd":] the association-descriptor;
646: and,
647:
648: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
649: updated only if the call fails.
650: \end{describe}
651: If the call to \verb"RtEndRequest" is successful,
652: then the association has been released.
653: Otherwise if the call fails and the error is not fatal,
654: then the association remains established and the \verb"RtSAPabort" structure
655: contained in
656: the \verb"RtSAPindication" parameter \verb"rti" contains the reason for the
657: failure.
658:
659: Upon receiving a {\sf X.410 CLOSE.INDICATION\/} event,
660: the user is required to generate a {\sf X.410 CLOSE.RESPONSE\/} action
661: using the \verb"RtEndResponse" routine.
662: \begin{quote}\index{RoEndResponse}\small\begin{verbatim}
663: int RtEndResponse (sd, rti)
664: int sd;
665: struct RtSAPindication *rti;
666: \end{verbatim}\end{quote}
667: The parameters to this procedure are:
668: \begin{describe}
669: \item[\verb"sd":] the association-descriptor;
670: and,
671:
672: \item[\verb"rti":] a pointer to a \verb"RtSAPindication" structure, which is
673: updated only if the call fails.
674: \end{describe}
675: If the call to \verb"RtEndResponse" is successful,
676: then the association has been released.
677:
678: \subsection {An Example}
679: Let's consider how one might construct a generic server that uses
680: reliable transfer services to establish an association,
681: but then uses remote operation services to communicate with its peer.
682: This entity will use a synchronous interface.
683:
684: There are two parts to the program:
685: initialization and the request/reply loop.
686: In our example,
687: we assume that the routine \verb"error" results in the process being
688: terminated after printing a diagnostic.
689:
690: In Figure~\ref{initRTS:OLDresponder},
691: the initialization steps for the generic responder,
692: including the outer {\em C\/} wrapper,
693: is shown.
694: First, the RtSAP state is re-captured by calling \verb"RtBInit".
695: If this succeeds,
696: then the association is authenticated and any command line arguments (as
697: specified in the \man isoservices(5) file) are parsed.
698: Assuming that the responder is satisfied with the proposed association,
699: it calls \verb"RtBeginResponse" to accept the association.
700: The \verb"RoSetService" routine is called to set the underlying service to be
701: used for remote operations.
702: Finally,
703: the main request/reply loop is realized.
704: The responder calls \verb"RoWaitRequest" to get the next event,
705: and then calls \verb"ros_indication" to decode that event.
706: {\let\small=\scriptsize %%% yikes!
707: \tagrind[tp]{grindB-5}{Initializing the generic RTS responder}%
708: {initRTS:OLDresponder}}
709:
710: Figure~\ref{doROSresponder} on page~\pageref{doROSresponder}
711: contains the definition of the
712: \verb"ros_indication" routine and associated routines.
713: Since the reliable transfer service was used to establish the association,
714: a different closing handler must be used.
715: This is shown in Figure~\ref{finRTS:OLDresponder}.
716: {\let\small=\scriptsize %%% yikes!
717: \tagrind[tp]{grindB-6}{Finalizing the generic RTS responder}%
718: {finRTS:OLDresponder}}
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.