![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rosap.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 rosap.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 {Remote Operations}\label{librosap}
4: The \man librosap(3n) library implements the Remote Operations Service (ROS).
5: Three service disciplines are implemented:
6: when the ECMA interpretation of the ROS is used,
7: we term this the {\em basic\/} service discipline;
8: when the CCITT X.400 interpretation is used,
9: we term this the {\em advanced\/} service discipline;
10: and,
11: when the new ISO and CCITT MOTIS interpretation is used,
12: we term this the {\em complete\/} service discipline.
13: The advanced discipline is somewhat less restrictive than the basic
14: discipline,
15: at the cost of requiring a more complex implementation on the part of both
16: the provider and the user.
17: The complete discipline, in addition to all of the facilities provided by the
18: advanced discipline, also supports the notion of {\em linked\/} operations.
19:
20: The abstraction provided to applications is that of an {\em association\/}
21: for remote operations.
22: An association is a binding between two users:
23: the {\em initiator\/} of the association,
24: and the {\em responder\/} to the association.
25: Once an association is established,
26: the initiator requests the responder to perform remote operations.
27: The responder in turn attempts these operations,
28: replying with either a result or an error.
29: This process continues until the initiator decides to release the association.
30:
31: Like most models of OSI services,
32: the underlying assumption is one of an asynchronous environment:
33: the service provider may generate events for the service user without the
34: latter entity triggering the actions which led to the event.
35: For example,
36: in a synchronous environment,
37: an indication that data has arrived usually occurs only when the service user
38: asks the service provider to read data;
39: in an asynchronous environment,
40: the service provider may interrupt the service user at any time to announce
41: the arrival of data.
42:
43: The \verb"rosap" module in this release presents a synchronous interface.
44: However once the association is established,
45: an asynchronous interface may be selected.
46:
47: All of the routines in the \man librosap(3n) library are integer-valued.
48: They return the manifest constant \verb"OK" on success,
49: or \verb"NOTOK" otherwise.
50:
51: \section {Notice}
52: Please read the following important message.
53: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
54: \bf NOTE:& The interface described herein is a ``raw'' interface to the
55: remote operations service.
56: Consult \volfour/ for a ``cooked'' interface.
57: \end{tabular}}\]
58:
59: \section {Service Disciplines and Associations}\label{ros:disciplines}
60: There are three service disciplines for remote operations:
61: {\em basic}, {\em remote}, and {\em complete}.
62: The basic service discipline limits its users by permitting only the
63: initiator to invoke remote operations.
64: Certain applications,
65: e.g., message handling systems,
66: require more freedom than this,
67: along with more reliability.
68:
69: The Remote Operations Service Element does not establish associations.
70: Consult Section~\ref{acs:note} to determine which mechanism you should use to
71: manage associations for your application.
72: Since the advanced and complete disciplines are both proper supersets of the
73: basic service discipline,
74: two users of an association can utilize exactly the features of the basic
75: service discipline even though the advanced or complete service discipline has
76: been selected,
77: without a loss of generality.
78:
79: \section {Remote Operations}\label{ros:operations}
80: Once the association has been established,
81: an association-descriptor is used to reference the association.
82: This is usually the first parameter given to any of the remaining routines in
83: the \man librosap(3n) library.
84: Further,
85: the last parameter is usually a pointer to a \verb"RoSAPindication"
86: structure.
87: If a call to one of these routines fails,
88: then the structure is updated.
89: \begin{quote}\index{RoSAPindication}\small\begin{verbatim}
90: struct RoSAPindication {
91: int roi_type;
92: #define ROI_INVOKE 0x00
93: #define ROI_RESULT 0x01
94: #define ROI_ERROR 0x02
95: #define ROI_UREJECT 0x03
96: #define ROI_PREJECT 0x04
97: #define ROI_END 0x05
98: #define ROI_FINISH 0x06
99:
100: union {
101: struct RoSAPinvoke roi_un_invoke;
102: struct RoSAPresult roi_un_result;
103: struct RoSAPerror roi_un_error;
104: struct RoSAPureject roi_un_ureject;
105: struct RoSAPpreject roi_un_preject;
106: struct RoSAPend roi_un_end;
107: struct AcSAPfinish roi_un_finish;
108: } roi_un;
109: #define roi_invoke roi_un.roi_un_invoke
110: #define roi_result roi_un.roi_un_result
111: #define roi_error roi_un.roi_un_error
112: #define roi_ureject roi_un.roi_un_ureject
113: #define roi_preject roi_un.roi_un_preject
114: #define roi_end roi_un.roi_un_end
115: #define roi_finish roi_un.roi_un_finish
116: };
117: \end{verbatim}\end{quote}
118: As shown, this structure is really a discriminated union
119: (a structure with a tag element followed by a union).
120: Hence, on a failure return,
121: one first coerces a pointer to the \verb"RoSAPpreject" structure contained
122: therein,
123: and then consults the elements of that structure.
124: \begin{quote}\index{RoSAPpreject}\small\begin{verbatim}
125: struct RoSAPpreject {
126: int rop_reason;
127:
128: int rop_id;
129: PE rop_apdu;
130:
131: #define ROP_SIZE 512
132: int rop_cc;
133: char rop_data[ROP_SIZE];
134: };
135: \end{verbatim}\end{quote}
136: The elements of a \verb"RoSAPpreject" structure are:
137: \begin{describe}
138: \item[\verb"rop\_reason":] the reason for the provider-initiated reject
139: (codes are listed in Table~\ref{RoSAPreasons}),
140:
141: \item[\verb"rop\_id"/\verb"rop\_apdu":] if an APDU could not be transferred
142: (\verb"rop_reason" is \verb"ROS_APDU"), then this is the invocation ID
143: of the APDU and (possibly) the APDU itself, respectively;
144: and,
145:
146: \item[\verb"rop\_data"/\verb"rop\_cc":] a diagnostic string from the provider.
147: \end{describe}
148: \tagtable[tp]{2b-1a}{RoSAP Failure Codes}{RoSAPreasons}
149: \tagtable[tp]{2b-1b}{RoSAP Failure Codes (continued)}\empty
150: Note that the \verb"rop_apdu" element is allocated via \man malloc(3) and
151: should be released using the \verb"ROPFREE" macro when no longer referenced.
152: The \verb"ROPFREE" macro behaves as if it was defined as:
153: \begin{quote}\index{ROPFREE}\small\begin{verbatim}
154: void ROPFREE (rop)
155: struct RoSAPpreject *rop;
156: \end{verbatim}\end{quote}
157: The macro frees only the data allocated in the \verb"RoSAPpreject" structure
158: and not the structure itself.
159:
160: On a failure return,
161: if the \verb"rop_reason" element of the \verb"RoSAPpreject" structure is
162: associated with a fatal error,
163: the the association is released.
164: The \verb"ROS_FATAL" macro can be used to determine this.
165: \begin{quote}\index{ROS\_FATAL}\small\begin{verbatim}
166: int ROS_FATAL (r)
167: int r;
168: \end{verbatim}\end{quote}
169: For protocol purists,
170: the \verb"ROS_OFFICIAL" macro can be used to determine if the error is an
171: ``official'' error as defined by the specification,
172: or an ``unofficial'' error used by the implementation.
173: \begin{quote}\index{ROS\_OFFICIAL}\small\begin{verbatim}
174: int ROS_OFFICIAL (r)
175: int r;
176: \end{verbatim}\end{quote}
177:
178: Finally,
179: some of these routines also take a \verb"priority" parameter indicating the
180: relative importance of the remote operation.
181: Under the basic service discipline,
182: this parameter is ignored.
183: Under the advanced or complete service discipline,
184: each application decides on its own integer-valued definitions.
185: The manifest constant \verb"ROS_NOPRIO" can be used if the application is
186: unconcerned with the priority.
187:
188: \subsection {Selecting an Underlying Service}\label{ros:underlying}
189: As should be obvious from Section~\ref{ros:disciplines},
190: the \man librosap(3n) library supports the use of three different underlying
191: services,
192: depending on the method used to establish the association.
193: The \man librosap(3n) library is constructed in such a way as to
194: avoid loading the object code for all three underlying services
195: when only one is desired.
196: In order to effect this,
197: it is necessary to give the loader a small hint.
198:
199: Once an association has been established,
200: the \verb"RoSetService" routine should be called.
201: \begin{quote}\index{RoSetService}\small\begin{verbatim}
202: int RoSetService (sd, bfunc, roi)
203: int sd;
204: IFP bfunc;
205: struct RoSAPindication *roi;
206: \end{verbatim}\end{quote}
207: The parameters to this procedure are:
208: \begin{describe}
209: \item[\verb"sd":] the association-descriptor;
210:
211: \item[\verb"bfunc":] a {\em magic\/} argument, use:
212: \[\begin{tabular}{|l|l|l|}
213: \hline
214: \multicolumn{1}{|c|}{\bf Value}&
215: \multicolumn{1}{c|}{\bf Underlying Service}&
216: \multicolumn{1}{c|}{\bf Routine}\\
217: \hline
218: \tt RoRtService& Reliable Transfer& \tt RtOpenResponse\\
219: & & \tt RtOpenRequest\\
220: & & \tt RtBeginResponse\\
221: & & \tt RtBeginRequest\\
222: \hline
223: \tt RoPService& Presentation& \tt AcAssocResponse\\
224: & & \tt AcAssocRequest\\
225: \hline
226: \tt RoSService& Session& \tt RoBeginResponse\\
227: & & \tt RoBeginRequest\\
228: \hline
229: \end{tabular}\]
230:
231: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
232: which is updated only if the call fails.
233: \end{describe}
234: The call to \verb"RoSetService" should be made after a succesful return from
235: any of the routines listed above.
236:
237: \subsection {Invoking Operations}
238: The \verb"RoInvokeRequest" routine is used to request an operation to be
239: performed remotely,
240: and corresponds to a {\sf RO-INVOKE.REQUEST\/} action.
241: Under the basic service discipline,
242: this action may be taken by only the initiator of an association;
243: under the advanced or complete service discipline,
244: no such restriction is made.
245: \begin{quote}\index{RoInvokeRequest}\small\begin{verbatim}
246: int RoInvokeRequest (sd, op, class, args, invoke,
247: linked, priority, roi)
248: int sd;
249: int op,
250: class,
251: invoke,
252: *linked,
253: priority;
254: PE args;
255: struct RoSAPindication *roi;
256: \end{verbatim}\end{quote}
257: The parameters to this procedure are:
258: \begin{describe}
259: \item[\verb"sd":] the association-descriptor;
260:
261: \item[\verb"op":] the operation code;
262:
263: \item[\verb"class":] the operation class
264: (either \verb"ROS_SYNC" for a synchronous operation,
265: or \verb"ROS_ASYNC" for an asynchronous one);
266:
267: \item[\verb"args":] the arguments for the operation;
268:
269: \item[\verb"invoke":] the invocation ID of this request;
270:
271: \item[\verb"linked":] the linked ID of this request
272: (only present if the complete service discipline has been selected,
273: use \verb"NULLIP" otherwise);
274:
275: \item[\verb"priority":] the priority of this request
276: (use \verb"ROS_NOPRIO" if the priority is undetermined);
277: and,
278:
279: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
280: always updated on synchronous operations,
281: and only updated if the call fails for asynchronous operations.
282: \end{describe}
283: If the \verb"class" parameter was \verb"ROS_ASYNC",
284: then \verb"RoInvokeRequest" returns immediately.
285: Otherwise,
286: after queuing the request,
287: the \verb"RoWaitRequest" routine
288: (described in Section~\ref{replies} on page~\pageref{replies})
289: is called implicitly to return the reply of the request.
290: Every attempt will be made to return the corresponding reply to the request.
291: Nevertheless,
292: it is the responsibility of the user to verify the invocation ID which is
293: returned.
294:
295: The routine \verb"RoIntrRequest" is similar to \verb"RoInvokeRequest"
296: with a \verb"class" argument of \verb"ROS_SYNC":
297: it invokes an operation and then waits for a response.
298: However,
299: if the user generates an interrupt,
300: usually by typing control-C (`\verb"^C"'),
301: then \verb"RoIntrRequest" will return immediately by simulating
302: a {\sf RO-U-REJECT.INDICATION\/} with reason \verb"ROS_INTERRPUTED"
303: (see section~\ref{rejections} on page~\pageref{rejections}).
304: This is useful for users of remote operations which support an
305: ``abandon'' functionality (e.g., the OSI Directory).
306: \begin{quote}\index{RoInvokeRequest}\small\begin{verbatim}
307: int RoIntrRequest (sd, op, args, invoke, linked,
308: priority, roi)
309: int sd;
310: int op,
311: invoke,
312: *linked,
313: priority;
314: PE args;
315: struct RoSAPindication *roi;
316: \end{verbatim}\end{quote}
317: The parameters to this procedure are:
318: \begin{describe}
319: \item[\verb"sd":] the association-descriptor;
320:
321: \item[\verb"op":] the operation code;
322:
323: \item[\verb"args":] the arguments for the operation;
324:
325: \item[\verb"invoke":] the invocation ID of this request;
326:
327: \item[\verb"linked":] the linked ID of this request
328: (only present if the complete service discipline has been selected,
329: use \verb"NULLIP" otherwise);
330:
331: \item[\verb"priority":] the priority of this request
332: (use \verb"ROS_NOPRIO" if the priority is undetermined);
333: and,
334:
335: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
336: always updated on synchronous operations,
337: and only updated if the call fails for asynchronous operations.
338: \end{describe}
339:
340:
341: \subsection {Replying to Requests}
342: When a request to perform a remote operation has been received by the
343: responder to an association,
344: the responder either returns a result or an error
345: (or in some cases, returns nothing at all).
346:
347: The \verb"RoResultRequest" routine is used to return a result,
348: and corresponds to the {\sf RO-RESULT.REQUEST\/} action.
349: Under the basic service discipline,
350: this action may only be taken by the responder to an association;
351: under the advanced or complete service discipline,
352: no such restriction is made.
353: \begin{quote}\index{RoResultRequest}\small\begin{verbatim}
354: int RoResultRequest (sd, invoke, op, result, priority, roi)
355: int sd;
356: int invoke,
357: op,
358: priority;
359: PE result;
360: struct RoSAPindication *roi;
361: \end{verbatim}\end{quote}
362: The parameters to this procedure are:
363: \begin{describe}
364: \item[\verb"sd":] the association-descriptor;
365:
366: \item[\verb"invoke":] the invocation ID of the request corresponding to this
367: reply;
368:
369: \item[\verb"op":] the operation code of the operation performed
370: (meaningful only in the complete service discipline);
371:
372: \item[\verb"result":] the results of the operation;
373:
374: \item[\verb"priority":] the priority of this reply;
375: and,
376:
377: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
378: updated only if the call fails.
379: \end{describe}
380:
381: The \verb"RoErrorRequest" routine is used to return an error,
382: and corresponds to the {\sf RO-ERROR.REQUEST\/} action.
383: Under the basic service discipline,
384: this action may only be taken by the responder to an association;
385: under the advanced or complete service discipline,
386: no such restriction is made.
387: \begin{quote}\index{RoErrorRequest}\small\begin{verbatim}
388: int RoErrorRequest (sd, invoke, error, params,
389: priority, roi)
390: int sd;
391: int invoke,
392: error,
393: priority;
394: PE params;
395: struct RoSAPindication *roi;
396: \end{verbatim}\end{quote}
397: The parameters to this procedure are:
398: \begin{describe}
399: \item[\verb"sd":] the association-descriptor;
400:
401: \item[\verb"invoke":] the invocation ID of the request corresponding to this
402: reply;
403:
404: \item[\verb"op":] the error code;
405:
406: \item[\verb"params":] the parameters for the error;
407:
408: \item[\verb"priority":] the priority of this request;
409: and,
410:
411: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
412: updated only if the call fails.
413: \end{describe}
414:
415: \subsection {Reading Replies}\label{replies}
416: The \verb"RoWaitRequest" routine is used to await either a request or a
417: reply from the other user.
418: \begin{quote}\index{RoWaitRequest}\small\begin{verbatim}
419: int RoWaitRequest (sd, secs, roi)
420: int sd;
421: int secs;
422: struct RoSAPindication *roi;
423: \end{verbatim}\end{quote}
424: The parameters to this procedure are:
425: \begin{describe}
426: \item[\verb"sd":] the association-descriptor;
427:
428: \item[\verb"secs":] the maximum number of seconds to wait for the data
429: (a value of \verb"NOTOK" indicates that the call should block indefinitely,
430: whereas a value of \verb"OK" indicates that the call should not block at all,
431: e.g., a polling action);
432: and,
433:
434: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
435: which is always updated.
436: \end{describe}
437: Unlike the other routines in the \man librosap(3n) library,
438: the \verb"RoWaitRequest" routine returns one of three values:
439: \verb"NOTOK" (on failure),
440: \verb"OK" (on reading a request or a reply),
441: or
442: \verb"DONE" (when something else happens).
443:
444: If the call to \verb"RoWaitRequest" returns the manifest constant
445: \verb"NOTOK",
446: then the \verb"RoSAPpreject" structure contained in
447: the \verb"RoSAPindication" parameter
448: \verb"roi" contains the reason for the failure.
449:
450: Otherwise if the call to \verb"RoWaitRequest" returns the manifest constant
451: \verb"OK",
452: then a request or a reply has arrived.
453: This event is encoded in the \verb"roi" parameter,
454: depending on the value of the \verb"roi_type" element.
455: Currently,
456: when \verb"RoWaitRequest" returns \verb"OK",
457: the \verb"roi_type" element is set to one of four values:
458: \[\begin{tabular}{|l|l|}
459: \hline
460: \multicolumn{1}{|c|}{\bf Value}&
461: \multicolumn{1}{c|}{\bf Event}\\
462: \hline
463: \tt ROI\_INVOKE& \sf RO-INVOKE.INDICATION\\
464: \tt ROI\_RESULT& \sf RO-RESULT.INDICATION\\
465: \tt ROI\_ERROR& \sf RO-ERROR.INDICATION\\
466: \tt ROI\_UREJECT& \sf RO-U-REJECT.INDICATION\\
467: \hline
468: \end{tabular}\]
469:
470: Otherwise if the call to \verb"RoWaitRequest" returns the manifest constant
471: \verb"DONE",
472: then some event other than a request or reply arriving has occurred.
473: This event is encoded in the \verb"roi" parameter,
474: depending on the value of the \verb"roi_type" element.
475: Currently,
476: when \verb"RoWaitRequest" returns \verb"DONE",
477: the \verb"roi_type" element is set to one of two values:
478: \[\begin{tabular}{|l|l|}
479: \hline
480: \multicolumn{1}{|c|}{\bf Value}&
481: \multicolumn{1}{c|}{\bf Event}\\
482: \hline
483: \tt ROI\_END& \sf RO-END.INDICATION\\
484: & \ \ (for old-style associations)\\
485: \hline
486: \tt ROI\_FINISH& \sf A-RELEASE.INDICATION\\
487: & \ \ (or {\sf RT-CLOSE.INDICATION\/})\\
488: \hline
489: \end{tabular}\]
490:
491: \subsubsection {Invocation Indication}
492: When an {\sf RO-INVOKE.INDICATION\/} event occurs,
493: the \verb"roi_type" field of the \verb"roi" parameter contains the value
494: \verb"ROI_INVOKE",
495: and a \verb"RoSAPinvoke" structure is contained inside the \verb"roi"
496: parameter.
497: \begin{quote}\index{RoSAPinvoke}\small\begin{verbatim}
498: struct RoSAPinvoke {
499: int rox_id;
500:
501: int rox_linkid;
502: int rox_nolinked;
503:
504: int rox_op;
505: PE rox_args;
506: };
507: \end{verbatim}\end{quote}
508: The elements of this structure are:
509: \begin{describe}
510: \item[\verb"rox\_id":] the invocation ID of this request;
511:
512: \item[\verb"rox\_linkid":] if \verb"rox_nolinked" is not set,
513: then this contains the invocation ID of the linked request;
514:
515: \item[\verb"rox\_nolinked":] the linked ID indicator
516: (if set, then this invocation is not linked to another operation);
517:
518: \item[\verb"rox\_op":] the operation code;
519: and,
520:
521: \item[\verb"rox\_args":] the arguments for the operation.
522: \end{describe}
523: Note that the \verb"rox_data" element is allocated via \man malloc(3) and
524: should be released using the \verb"ROXFREE" macro when no longer referenced.
525: The \verb"ROXFREE" macro behaves as if it was defined as:
526: \begin{quote}\index{ROXFREE}\small\begin{verbatim}
527: void ROXFREE (rox)
528: struct RoSAPinvoke *rox;
529: \end{verbatim}\end{quote}
530: The macro frees only the data allocated in the \verb"RoSAPinvoke" structure
531: and not the structure itself.
532:
533: Under the basic service discipline,
534: only the responder to an association will receive this event;
535: it is expected that the user will (eventually) call either
536: the \verb"RoResultRequest", the \verb"RoErrorRequest",
537: or perhaps the \verb"RoURejectRequest" routine in response.
538:
539: \subsubsection {Result Indication}
540: When an {\sf RO-RESULT.INDICATION\/} event occurs,
541: the \verb"roi_type" field of the \verb"roi" parameter contains the value
542: \verb"ROI_RESULT",
543: and a \verb"RoSAPresult" structure is contained inside the \verb"roi"
544: parameter.
545: \begin{quote}\index{RoSAPresult}\small\begin{verbatim}
546: struct RoSAPresult {
547: int ror_id;
548:
549: PE ror_result;
550: };
551: \end{verbatim}\end{quote}
552: The elements of this structure are:
553: \begin{describe}
554: \item[\verb"ror\_id":] the invocation ID of this reply,
555: which is identical to the ID of the request which generated the results;
556:
557: \item[\verb"ror\_op":] the operation code of the operation performed
558: (meaningful only in the complete service discipline);
559: and,
560:
561: \item[\verb"ror\_result":] the results of the operation.
562: \end{describe}
563: Note that the \verb"ror_result" element is allocated via \man malloc(3) and
564: should be released using the \verb"RORFREE" macro when no longer referenced.
565: The \verb"RORFREE" macro behaves as if it was defined as:
566: \begin{quote}\index{RORFREE}\small\begin{verbatim}
567: void RORFREE (ror)
568: struct RoSAPresult *ror;
569: \end{verbatim}\end{quote}
570: The macro frees only the data allocated in the \verb"RoSAPresult" structure
571: and not the structure itself.
572:
573: Under the basic service discipline,
574: only the initiator to an association will receive this event in response to
575: an earlier call to \verb"RoInvokeRequest".
576:
577: \subsubsection {Error Indication}
578: When an {\sf RO-ERROR.INDICATION\/} event occurs,
579: the \verb"roi_type" field of the \verb"roi" parameter contains the value
580: \verb"ROI_ERROR",
581: and a \verb"RoSAPerror" structure is contained inside the \verb"roi"
582: parameter.
583: \begin{quote}\index{RoSAPerror}\small\begin{verbatim}
584: struct RoSAPerror {
585: int roe_id;
586:
587: int roe_error;
588: PE roe_param;
589: };
590: \end{verbatim}\end{quote}
591: The elements of this structure are:
592: \begin{describe}
593: \item[\verb"roe\_id":] the invocation ID of this reply,
594: which is identical to the ID of the request which generated the error;
595:
596: \item[\verb"roe\_error":] the error code;
597: and,
598:
599: \item[\verb"roe\_param":] the parameters of the error.
600: \end{describe}
601: Note that the \verb"roe_param" element is allocated via \man malloc(3) and
602: should be released using the \verb"ROEFREE" macro when no longer referenced.
603: The \verb"ROEFREE" macro behaves as if it was defined as:
604: \begin{quote}\index{ROEFREE}\small\begin{verbatim}
605: void ROEFREE (roe)
606: struct RoSAPerror *roe;
607: \end{verbatim}\end{quote}
608: The macro frees only the data allocated in the \verb"RoSAPerror" structure
609: and not the structure itself.
610:
611: Under the basic service discipline,
612: only the initiator to an association will receive this event in response to
613: an earlier call to \verb"RoInvokeRequest".
614:
615: \subsubsection {User-Reject Indication}\label{rejections}
616: When an {\sf RO-U-REJECT.INDICATION\/} event occurs,
617: the \verb"roi_type" field of the \verb"roi" parameter contains the value
618: \verb"ROI_UREJECT",
619: and a \verb"RoSAPureject" structure is contained inside the \verb"roi"
620: parameter.
621: \begin{quote}\index{RoSAPureject}\small\begin{verbatim}
622: struct RoSAPureject {
623: int rou_id;
624: int rou_noid;
625:
626: int rou_reason;
627: };
628: \end{verbatim}\end{quote}
629: The elements of this structure are:
630: \begin{describe}
631: \item[\verb"rou\_id":] if \verb"rou_noid" is not set,
632: then this contains the invocation ID of the request which generated the
633: rejection;
634:
635: \item[\verb"rou\_noid":] the invocation ID indicator
636: (if set, then no request in particular caused the rejection to be generated);
637: and,
638:
639: \item[\verb"rou\_reason":] the reason for the rejection
640: (a ``non-fatal'' user-initiated rejection code listed in
641: Table~\ref{RoSAPreasons}).
642: \end{describe}
643:
644: \subsubsection {End Indication}\label{ros:end}
645: When the \verb"roi_type" field of the \verb"roi" parameter contains the value
646: \verb"ROI_END",
647: a \verb"RoSAPend" structure is contained inside the \verb"roi"
648: parameter.
649: \begin{quote}\index{RoSAPend}\small\begin{verbatim}
650: struct RoSAPend {
651: int roe_dummy;
652: };
653: \end{verbatim}\end{quote}
654: Depending on whether the reliable transfer service was used to start the
655: association,
656: a {\sf X.400 CLOSE.INDICATION\/} or a {\sf RO-END.INDICATION\/} event has
657: occurred,
658: and the user should respond appropriately.
659:
660: \subsubsection {Finish Indication}\label{ros:finish}
661: When the \verb"roi_type" field of the \verb"RoSAPindication" parameter
662: \verb"roi" contains the value
663: \verb"ROI_FINISH",
664: a \verb"AcSAPfinish" structure is contained inside the \verb"roi" parameter.
665: Depending on whether the reliable transfer service was used to start the
666: association,
667: an {\sf RT-CLOSE.INDICATION\/} or an {\sf A-RELEASE.INDICATION\/} event has
668: occurred, and the user should respond appropriately.
669:
670: \subsection {Rejecting Requests and Replies}
671: The \verb"RoURejectRequest" routine is used to perform user-level
672: error-recovery.
673: Usually,
674: it signals the rejection of a previously received request or reply.
675: \begin{quote}\index{RoURejectRequest}\small\begin{verbatim}
676: int RoURejectRequest (sd, invoke, reason, priority, roi)
677: int sd;
678: int *invoke,
679: reason,
680: priority;
681: struct RoSAPindication *roi;
682: \end{verbatim}\end{quote}
683: The parameters to this procedure are:
684: \begin{describe}
685: \item[\verb"sd":] the association-descriptor;
686:
687: \item[\verb"invoke":] a pointer to the invocation ID of the request in
688: question (or \verb"NULLIP" if this rejection does not apply to a particular
689: request or reply);
690:
691: \item[\verb"reason":] a ``non-fatal'' user-initiated rejection code as
692: listed in Table~\ref{RoSAPreasons} on page~\pageref{RoSAPreasons};
693:
694: \item[\verb"priority":] the priority of this request;
695: and,
696:
697: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
698: updated only if the call fails.
699: \end{describe}
700: Upon a successful return from this call,
701: a {\sf ROU-U-REJECT.INDICATION\/} event has been queued for the other user.
702:
703: \subsection {Asynchronous Event Handling}
704: The request/reply events discussed thus far have been synchronous in nature.
705: Some users of the remote operations service may wish an asynchronous interface.
706: The \verb"RoSetIndications" routine is used to change the service associated
707: with an association-descriptor to an asynchronous interface.
708: \begin{quote}\index{RoSetIndications}\small\begin{verbatim}
709: int RoSetIndications (sd, indication, roi)
710: int sd;
711: IFP indication;
712: struct RoSAPindication *roi;
713: \end{verbatim}\end{quote}
714: The parameters to this procedure are:
715: \begin{describe}
716: \item[\verb"sd":] the association-descriptor;
717:
718: \item[\verb"indication":] the address of an event-handler routine to be
719: invoked when an event occurs;
720: and,
721:
722: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
723: updated only if the call fails.
724: \end{describe}
725: If the service is to be made asynchronous,
726: then \verb"indication" is specified;
727: otherwise,
728: if the service is to be made synchronous,
729: it is not specified (use the manifest constant \verb"NULLIFP").
730: The most likely reason for the call failing is \verb"ROS_WAITING",
731: which indicates that an event is waiting for the user.
732:
733: When an event occurs,
734: the event-handler routine is invoked with two parameters:
735: \begin{quote}\small\begin{verbatim}
736: (*handler) (sd, roi);
737: int sd;
738: struct RoSAPindication *roi;
739: \end{verbatim}\end{quote}
740: The parameters are:
741: \begin{describe}
742: \item[\verb"sd":] the association-descriptor;
743: and,
744:
745: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure encoding
746: the event.
747: \end{describe}
748: Note that the data contained in the structure was allocated via \man malloc(3),
749: and should be released with the appropriate macro
750: (i.e., \verb"ROPFREE", \verb"ROXFREE", \verb"RORFREE", or \verb"ROEFREE")
751: when no longer needed.
752:
753: When an event-handler is invoked,
754: future invocations of the event-hander are blocked until it returns.
755: The return value of the event-handler is ignored.
756: Further,
757: during the execution of a synchronous call to the library,
758: the event-handler will be blocked from being invoked.
759: The one exception to this is a call to \verb"RoInvokeRequest" with the
760: \verb"class" parameter set to \verb"ROS_SYNC".
761: In this circumstance,
762: replies to invocations other than the one being waited for will result in the
763: event-handler being invoked as appropriate.
764:
765: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
766: \bf NOTE:& The \man librosap(3n) library uses the SIGEMT signal to
767: provide these services.
768: Programs using asynchronous association-descriptors should NOT
769: use SIGEMT for other purposes.
770: \end{tabular}}\]
771:
772: \subsection {Synchronous Event Multiplexing}
773: A user of the remote operations service may wish to manage multiple
774: association-descriptors simultaneously;
775: the routine \verb"RoSelectMask" is provided for this purpose.
776: This routine updates a file-descriptor mask and associated counter for use
777: with \verb"xselect" (consult Section~\ref{acs:select}),
778: as assocation-descriptors are file-descriptors.
779: \begin{quote}\index{RoSelectMask}\small\begin{verbatim}
780: int RoSelectMask (sd, mask, nfds, roi)
781: int sd;
782: fd_set *mask;
783: int *nfds;
784: struct RoSAPindication *roi;
785: \end{verbatim}\end{quote}
786: The parameters to this procedure are:
787: \begin{describe}
788: \item[\verb"sd":] the association-descriptor;
789:
790: \item[\verb"mask":] a pointer to a file-descriptor mask meaningful to
791: \verb"xselect";
792:
793: \item[\verb"nfds":] a pointer to an integer-valued location meaningful to
794: \verb"xselect";
795: and,
796:
797: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure, which is
798: updated only if the call fails.
799: \end{describe}
800: If the call is successful, then the \verb"mask" and \verb"nfds" parameters can
801: be used as arguments to \verb"xselect".
802: The most likely reason for the call failing is \verb"ROS_WAITING",
803: which indicates that an event is waiting for the user.
804:
805: If \verb"xselect" indicates that the association-descriptor is ready for
806: reading,
807: \verb"RoWaitRequest" should be called with the \verb"secs" parameter equal to
808: \verb"OK".
809: If the network activity does not constitute an entire event for the user,
810: then \verb"RoWaitRequest" will return \verb"NOTOK" with error code
811: \verb"ROS_TIMER".
812:
813: \section {Error Conventions}
814: All of the routines in this library return the manifest constant \verb"NOTOK"
815: on error,
816: and also update the \verb"roi" parameter given to the routine.
817: The element called \verb"roi_preject" in the \verb"RoSAPindication" structure
818: encodes the reason for the failure.
819: To determine the reason,
820: one coerces a pointer to a \verb"RoSAPpreject" structure,
821: and consults the \verb"rop_reason" element of this latter structure.
822: This element can be given as a
823: parameter to the routine \verb"RoErrString" which returns a null-terminated
824: diagnostic string.
825: \begin{quote}\index{RoErrString}\small\begin{verbatim}
826: char *RoErrString (c)
827: int c;
828: \end{verbatim}\end{quote}
829:
830: \section {Compiling and Loading}
831: Programs using the \man librosap(3n) library should include
832: \verb"<isode/rosap.h>",
833: which automatically includes the header file \verb"<isode/psap.h>" described in
834: Chapter~\ref{libpsap} and the header file \verb"<isode/acsap.h>" described in
835: Chapter~\ref{libacsap}.
836: The programs should also be loaded with \verb"-lisode".
837:
838: \section {Two Examples}\label{ros:example}
839: Two examples are now presented:
840: a detailed exposition on the construction of a responder for remote operations;
841: and,
842: a terse presentation of an initiator process.
843:
844: \subsection {The Generic Server}\label{ros:example:server}
845: Let's consider how one might construct a generic server which uses remote
846: operations services.
847: This entity will use an asynchronous interface.
848:
849: There are two parts to the program:
850: initialization and the request/reply loop.
851: In our example,
852: we assume that the routine \verb"error" results in the process being
853: terminated after printing a diagnostic.
854:
855: In Figure~\ref{initROSresponder},
856: the initialization steps for the generic responder,
857: including the outer {\em C\/} wrapper,
858: is shown.
859: First, the ACSE state is re-captured by calling \verb"AcInit".
860: If this succeeds,
861: then any command line arguments
862: (as specified in the \man isoservices(5) file described in
863: Chapter~\ref{isoservices} of \voltwo/)
864: are parsed.
865: Assuming that the responder is satisfied with the proposed association,
866: it calls \verb"AcAssocResponse" to accept the association.
867: Then,
868: \verb"RoSetService" is called
869: to set the underlying service to be used for remote operations.
870: The
871: \verb"RoSetIndications" routine is called
872: to specify an asynchronous event handler.
873: Finally,
874: the main request/reply loop is realized.
875: The server simply uses \man pause(2) to wait for the next event.
876:
877: In Figure~\ref{doROSresponder} on page~\pageref{doROSresponder},
878: the \verb"ros_indication" routine simply dispatches based on the value of the
879: \verb"roi_type" element of the \verb"RoSAPindication" structure.
880: {\let\small=\scriptsize %%% yikes!
881: \clearpage
882: \tagrind[tp]{grind2b-2}{Initializing the generic ROS responder}%
883: {initROSresponder}
884: \clearpage
885: \tagrind[tp]{grind2b-3a}{The request/reply loop for the generic ROS responder}%
886: {doROSresponder}
887: \clearpage
888: \tagrind[tp]{grind2b-3b}%
889: {The request/reply loop for the generic ROS responder (continued)}%
890: \empty
891: \clearpage
892: \tagrind[tp]{grind2b-3c}%
893: {The request/reply loop for the generic ROS responder (continued)}%
894: \empty
895: \clearpage
896: \tagrind[tp]{grind2b-3d}%
897: {The request/reply loop for the generic ROS responder (continued)}%
898: \empty
899: \clearpage
900: \tagrind[tp]{grind2b-3e}%
901: {The request/reply loop for the generic ROS responder (continued)}%
902: \empty}
903:
904: If the event was caused by a request to invoke an operation,
905: then \verb"ros_invoke" is called.
906: This routine consults a dispatch table to find the function which will
907: execute the operation.
908: Based on the return value of the function,
909: either the result is returned,
910: an error is returned,
911: or the request to perform the operation is rejected.
912:
913: If the event was caused by a reply to the invocation of an operation
914: (i.e., either results or an error),
915: this is rejected.
916: The basic service discipline prohibits this event from happening to
917: responders;
918: hence, the \verb"ros_result" and \verb"ros_error" routines are used as stubs.
919:
920: If the event was caused by a rejection of a previous reply,
921: then the \verb"ros_ureject" routine is called to handle this.
922: If the event was caused by the provider initiating a rejection,
923: then the \verb"ros_preject" routine is called to handle this.
924:
925: Finally,
926: if the event was caused by the association being released,
927: the \verb"ros_finish" routine is called to handle this.
928:
929: \subsection {The Generic Client}
930: As the previous example described~---~in great detail~---~how users of the
931: remote operations services employ the \man librosap(3n) library,
932: we now present a short example of how a client connects to the server.
933:
934: In Figure~\ref{initROSinitiator},
935: the initialization steps for the generic initiator,
936: including the outer {\em C\/} wrapper,
937: is shown.
938: First, the application-entity information and presentation address are
939: looked-up.
940: Second, the application context and protocol control information objects are
941: looked-up
942: (and copied, since \verb"ode2oid" returns a pointer to a static area).
943: Next, the session connection reference is initialized.
944: Then, the call to \verb"AcAssocRequest" is made.
945: The arguments to this routine are the minimal required for remote operations.
946: If the call succeeds,
947: then the client checks to see if the association is successfully established.
948: If so, the association descriptor is captured, and then the routine
949: \verb"invoke",
950: which is not described in this example,
951: is called.
952: This routine presumably requests remote operations from the responder
953: previously described.
954: Upon the return of the \verb"invoke" routine,
955: the association is (forcibly) released,
956: and the program exits.
957: {\let\small=\scriptsize %%% yikes!
958: \clearpage
959: \tagrind[tp]{grind2b-4a}{Initializing the generic ROS initiator}%
960: {initROSinitiator}
961: \clearpage
962: \tagrind[tp]{grind2b-4b}{Initializing the generic ROS initiator (continued)}%
963: \empty}
964:
965: \section {For Further Reading}\label{ros:reading}
966: The ECMA technical report on remote operation services is defined in
967: \cite{ECMA.ROS}.
968: The CCITT recommendation describing remote operations,
969: as supported by the reliable transfer service,
970: is \cite{MHS.RTS}.
971: These both assume the use of old-style associations;
972: the draft CCITT work which assumes the use of new-style associations is
973: defined in \cite{CCITT.ROS.Service} and \cite{CCITT.ROS.Protocol}.
974: Similarly,
975: the corresponding ISO work is
976: \cite{ISO.ROS.Service} and \cite{ISO.ROS.Protocol}.
977:
978: %%% \section {Changes Since the Last Release}\label{rosap:changes}
979: %%% A brief summary of the major changes between v~\rosaprevrsn/ and
980: %%% v~\rosapvrsn/ are now presented.
981: %%% These are the user-visible changes only;
982: %%% changes of a strictly internal nature are not discussed.
983:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.