![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to librosy.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 librosy.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 {Run-Time Environment}\label{librosy}
4: The \man librosap(3n) library implements the run-time environment for the
5: stubs generated by the \man rosy(1) program.
6:
7: The routines described herein provide a more structured interface to the
8: remote operations service (ROS).
9: They are used in the boilerplate routines which are described in the
10: following chapters.
11: Hence,
12: the more hasty reader may wish to skip this chapter on first reading of this
13: volume.
14:
15: \section {Notice}
16: Please read the following important message.
17: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
18: \bf NOTE:& When using the \man librosy(3n) library,
19: no calls should be made to the \man librosap(3n) library.
20: (That is, the \verb"RoXXX" routines should not be directly
21: referenced.)
22:
23: There are three exceptions: \verb"RoSetService" and
24: its related arguments (e.g., \verb"RoPService"),
25: \verb"RoSelectMask", and \verb"RoErrString".
26: \end{tabular}}\]
27:
28: \section {Conventions}
29: All of the routines in the \man librosy(3n) library are integer-valued.
30: Unless otherwise indicated,
31: they return the manifest constant \verb"OK" on success,
32: or \verb"NOTOK" otherwise.
33:
34: The routines all work on an established association,
35: which is referenced by an association-descriptor.
36: This is usually the first parameter given to any of the routines in the
37: \man librosy(3n) library.
38: Further,
39: the last parameter is usually a pointer to a \verb"RoSAPindication" structure.
40: If a call to one of these routines fails,
41: then the structure is updated.
42: Section~\ref{ros:operations} of \volone/ describes this structure and how to
43: interpret error conditions and their severity.
44:
45: \subsection {Interface from ROSY}
46: For a given module, e.g., \verb"MODULE",
47: \pgm{rosy} will define two tables:
48: \begin{quote}\small\begin{verbatim}
49: struct RyOperation table_MODULE_Operations[];
50:
51: struct RyError table_MODULE_Errors[];
52: \end{verbatim}\end{quote}
53:
54: The \verb"RyOperation" structure is used to define the compiled parts of an
55: operation:
56: \begin{quote}\small\index{RyOperation}\begin{verbatim}
57: struct RyOperation {
58: char *ryo_name;
59: int ryo_op;
60:
61: IFP ryo_arg_encode;
62: IFP ryo_arg_decode;
63: IFP ryo_arg_free;
64:
65: int ryo_result;
66: IFP ryo_res_encode;
67: IFP ryo_res_decode;
68: IFP ryo_res_free;
69:
70: struct RyError **ryo_errors;
71: };
72: \end{verbatim}\end{quote}
73: The elements of this structure are:
74: \begin{describe}
75: \item[\verb"ryo\_name"/\verb"ryo\_op":] the operation name and code;
76:
77: \item[\verb"ryo\_arg\_encode"/\verb"ryo\_arg\_decode":] the address of the
78: routines to encode or decode (respectively) the operation's argument from a
79: {\em C\/} structure to its corresponding abstract syntax
80: (present only if the operation takes an argument);
81:
82: \item[\verb"ryo\_arg\_free":] the routine to free the {\em C\/} structure
83: created by the argument decode routine for the operation;
84:
85: \item[\verb"ryo\_result":] non-zero if this operation returns a result;
86:
87: \item[\verb"ryo\_res\_encode"/\verb"ryo\_res\_decode":] the address of the
88: routines to encode or decode (respectively) the operation's result from a
89: {\em C\/} structure to its corresponding abstract syntax
90: (present only if the operation returns a result);
91:
92: \item[\verb"ryo\_res\_free":] the routine to free the {\em C\/} structure
93: created by the result decode routine for the operation;
94: and,
95:
96: \item[\verb"ryo\_errors":] a pointer to null-terminated list of the errors
97: which this operation may generate (present only if the operation may returns
98: at least one error).
99: \end{describe}
100:
101: The \verb"RyError" structure is used to define the compiled parts of an
102: error:
103: \begin{quote}\small\index{RyError}\begin{verbatim}
104: struct RyError {
105: char *rye_name;
106: int rye_err;
107:
108: IFP rye_param_encode;
109: IFP rye_param_decode;
110: IFP rye_param_free;
111: };
112: \end{verbatim}\end{quote}
113: The elements of this structure are:
114: \begin{describe}
115: \item[\verb"rye\_name"/\verb"rye\_err":] the error name and code;
116:
117: \item[\verb"rye\_param\_encode"/\verb"rye\_res\_decode":] the address of the
118: routines to encode or decode (respectively) the error's parameter from a
119: {\em C\/} structure to its corresponding abstract syntax
120: (present only if the error contains a parameter);
121: and,
122:
123: \item[\verb"ryo\_param\_free":] the routine to free the {\em C\/} structure
124: created by the parameter decode routine for the error.
125: \end{describe}
126:
127: \section {Routines for Initiators}
128: Initiators use the routines in the \man libacsap(3n) library for association
129: control.
130: These are described in Chapter~\ref{libacsap} of \volone/.
131:
132: \section {Routines for Invokers}\label{ryoperation}
133: After forming an association,
134: invokers are able to request operations for execution by the performer.
135: Two interfaces are provided:
136: a synchronous interface and an asynchronous interface.
137:
138: \subsection* {Synchronous Interface}
139: Most invokers desire a simple interface for synchronous execution
140: of operations (the operation blocks until it is completed).
141: The \verb"RyOperation" routine is used to provide such an interface.
142: \begin{quote}\index{RyOperation}\small\begin{verbatim}
143: int RyOperation (sd, ryo, op, in, out, response, roi)
144: int sd;
145: struct RyOperation *ryo;
146: int op,
147: *response;
148: caddr_t in,
149: *out;
150: struct RoSAPindication *roi;
151: \end{verbatim}\end{quote}
152: The parameters to this procedure are:
153: \begin{describe}
154: \item[\verb"sd":] the association-descriptor;
155:
156: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table;
157:
158: \item[\verb"op":] the operation code of the operation to invoke;
159:
160: \item[\verb"response":] an integer-valued location which is updated if the
161: call succeeds;
162:
163: \item[\verb"in":] the address of the {\em C\/} structure for the operation's
164: argument;
165:
166: \item[\verb"out":] an address-valued location which is updated if the call
167: succeeds;
168: and,
169:
170: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
171: which is updated only if the operation was not performed.
172: \end{describe}
173: The \verb"RyOperation" routine returns one of three values:
174: \verb"NOTOK" (on failure),
175: \verb"OK" (on reading a reply),
176: or
177: \verb"DONE" (when something else happens).
178:
179: If the call to \verb"RyOperation" returns the manifest constant \verb"NOTOK",
180: then the \verb"RoSAPpreject" structure contained in
181: the \verb"RoSAPindication" parameter
182: \verb"roi" contains the reason for the failure.
183:
184: If the call to \verb"RyOperation" returns the manifest constant \verb"OK",
185: then the \verb"response" and \verb"out" parameters are updated.
186: If the value of the integer pointed to by \verb"response" is \verb"RY_RESULT",
187: then the value of the address pointed to by \verb"out" is a newly allocated
188: {\em C\/} structure for the operation's result (if any).
189: If the value of the integer pointed to by \verb"response" is any other value,
190: then it indicates the error which the operation returned,
191: and the value of the address pointed to by \verb"out" is a newly allocated
192: {\em C\/} structure for the error's parameter (if any).
193: Note that if a result or parameter is returned,
194: then it is the invoker's responsibility to release the memory used by the
195: {\em C\/} structure, when appropriate.
196:
197: If the call to \verb"RyOperation" returns the manifest constant \verb"DONE",
198: then an indication that the association is pending termination is returned.
199: The value of the \verb"roi_type" element of the \verb"RoSAPindication"
200: parameter is either \verb"ROI_END" or \verb"ROI_FINISH".
201: Consult Section~\ref{ros:end} of \volone/ for the details,
202: as this normally does not happen to initiators.
203:
204: The routine \verb"RyOperation" is simply a comprehensive interface for a more
205: general routine, \verb"RyOpInvoke", which invokes an operation:
206: \begin{quote}\index{RyOpInvoke}\small\begin{verbatim}
207: int RyOpInvoke (sd, ryo, op, in, out, rfx, efx, class,
208: invokeID, linkedID, priority, roi)
209: int sd;
210: struct RyOperation *ryo;
211: int op,
212: class,
213: invokeID,
214: *linkedID,
215: priority;
216: IFP rfx,
217: efx;
218: caddr_t in,
219: *out;
220: struct RoSAPindication *roi;
221: \end{verbatim}\end{quote}
222: The parameters to this procedure are:
223: \begin{describe}
224: \item[\verb"sd":] the association-descriptor;
225:
226: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table;
227:
228: \item[\verb"op":] the operation code of the operation to invoke;
229:
230: \item[\verb"in":] the address of the {\em C\/} structure for the operation's
231: argument;
232:
233: \item[\verb"out":] an address-valued location which is updated if the call
234: succeeds;
235:
236: \item[\verb"rfx":] the address of a dispatch routine to be invoked if
237: the operation returns a result;
238:
239: \item[\verb"efx":] the address of a dispatch routine to be invoked if
240: the operation returns an error;
241:
242: \item[\verb"class":] the operation class
243: (either \verb"ROS_SYNC" for a synchronous operation,
244: or \verb"ROS_ASYNC" for an asynchronous one);
245:
246: \item[\verb"invokeID":] the invocation ID of this request;
247:
248: \item[\verb"linkedID":] the linked ID of this request
249: (use \verb"NULLIP" if not linked);
250:
251: \item[\verb"priority":] the priority of this request
252: (use \verb"ROS_NOPRIO" if the priority is undetermined);
253: and,
254:
255: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
256: which is updated only if the operation was not performed.
257: \end{describe}
258: This routine is exactly equivalent to the \verb"RoInvokeRequest" routine in the
259: \man librosap(3n) library,
260: with the additional functions of:
261: automatically encoding and decoding arguments, results, and parameters.
262: Hence,
263: the routine \verb"RyOperation",
264: is essentially a call to \verb"RyOpInvoke" with a few hard-wired parameters:
265: \begin{describe}
266: \item[\verb"class":] \verb"ROS_SYNC";
267:
268: \item[\verb"invokeID":] a unique-number;
269:
270: \item[\verb"linkedID":] \verb"NULLIP";
271: and,
272:
273: \item[\verb"priority":] \verb"ROS_NOPRIO".
274: \end{describe}
275:
276: \subsection* {Asynchronous Interface}
277: Although
278: most invokers desire a simple interface for synchronous execution,
279: it is also useful to have an asynchronous interface.
280: Further,
281: since a synchronous interface can be thought of as a degenerate subset of an
282: asynchronous interface,
283: most invokers use the asynchronous interface and simply ask for it to block
284: after making the invocation.
285: The \verb"RyStub" routine is used to provide such an interface.
286: \begin{quote}\index{RyStub}\small\begin{verbatim}
287: int RyStub (sd, ryo, op, id, linked, in, rfx, efx,
288: class, roi)
289: int sd;
290: struct RyOperation *ryo;
291: int op,
292: id,
293: *linked,
294: class;
295: caddr_t in;
296: IFP rfx,
297: efx;
298: struct RoSAPindication *roi;
299: \end{verbatim}\end{quote}
300: The parameters to this procedure are:
301: \begin{describe}
302: \item[\verb"sd":] the association-descriptor;
303:
304: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table;
305:
306: \item[\verb"op":] the operation code of the operation to invoke;
307:
308: \item[\verb"id":] the invocation identifier to use;
309:
310: \item[\verb"linked":] the linked invocation identifier to use, if any
311: (use \verb"NULLIP" if this is not a linked reply);
312:
313: \item[\verb"in":] the address of the {\em C\/} structure for the operation's
314: argument;
315:
316: \item[\verb"rfx":] the address of a dispatch routine to be invoked if
317: the operation returns a result;
318:
319: \item[\verb"efx":] the address of a dispatch routine to be invoked if
320: the operation returns an error or is rejected;
321:
322: \item[\verb"class":] the operation class
323: (either \verb"ROS_SYNC" for a synchronous operation,
324: \verb"ROS_ASYNC" for an asynchronous operation,
325: or \verb"ROS_INTR" for a synchronous but user-interruptable operation);
326: and,
327:
328: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
329: which is updated only if the operation was not performed.
330: \end{describe}
331: The \verb"RyStub" routine returns one of three values:
332: \verb"NOTOK" (on failure),
333: \verb"OK" (on success),
334: or
335: \verb"DONE" (when something else happens).
336:
337: If the call to \verb"RyStub" returns the manifest constant \verb"NOTOK",
338: then the \verb"RoSAPpreject" structure contained in
339: the \verb"RoSAPindication" parameter
340: \verb"roi" contains the reason for the failure.
341:
342: If the call to \verb"RyStub" returns the manifest constant \verb"OK",
343: then the operation was queued or completed,
344: depending on the value of the \verb"class" parameter.
345: If the value of the \verb"class" parameter was \verb"ROS_ASYNC",
346: then \verb"RyStub" returns immediately after queuing the invocation.
347: Otherwise,
348: \verb"RyStub" waits for a response to the operation,
349: invokes the appropriate dispatch routine,
350: and then returns.
351: Both the result and error dispatch routines are invoked in the same way:
352: \begin{quote}\small\begin{verbatim}
353: result = (*fnx) (sd, id, reason, value, roi)
354: int sd;
355: int id,
356: reason;
357: caddr_t value;
358: struct RoSAPindication *roi;
359: \end{verbatim}\end{quote}
360: The parameters to this procedure are:
361: \begin{describe}
362: \item[\verb"sd":] the association-descriptor;
363:
364: \item[\verb"id":] the invocation identifier associated with the result or
365: error;
366:
367: \item[\verb"reason":] either \verb"RY_RESULT" if the result dispatch routine
368: is invoked, the error code if the error dispatch routine is invoked with an
369: error, or \verb"RY_REJECT" if the error dispatch routine is invoked with a
370: rejection;
371:
372: \item[\verb"value":] the address of the {\em C\/} structure for the result or
373: error parameter (if any);
374: and,
375:
376: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
377: which is updated only if the result, error, or rejection is faulty.
378: \end{describe}
379: The dispatch routine should return the manifest constant \verb"OK"
380: unless you know what you're doing.
381: Note that if \verb"value" is present,
382: then the \man librosy(3n) library will automatically release the memory used
383: by the {\em C\/} structure when the dispatch routine returns.
384:
385: If the call to \verb"RyStub" returns the manifest constant \verb"DONE",
386: then an indication that the association is pending termination is returned.
387: The value of the \verb"roi_type" element of the \verb"RoSAPindication"
388: parameter is either \verb"ROI_END" or \verb"ROI_FINISH".
389: Consult Section~\ref{ros:end} of \volone/ for the details,
390: as this normally does not happen to initiators.
391:
392: If the value of the \verb"class" parameter was \verb"ROS_INTR",
393: then \verb"RyStub" issues a synchronous call
394: (as described above for the \verb"ROS_SYNC" case).
395: However, if the user generates an interrupt,
396: usually by typing control-C (`\verb"^C"'),
397: while waiting for the response to the operation,
398: then \verb"RyStub" will return immediately with the value \verb"NOTOK"
399: and the \verb"rop_reason" element of the \verb"RoSAPpreject" structure
400: contained in the \verb"RoSAPindication" parameter \verb"roi" will be set to
401: the value \verb"ROS_INTERRUPTED".
402:
403: At this time,
404: the program may do other processing and later return to wait for the outcome
405: of the operation.
406: Instead,
407: the program may direct the run-time environment to silently discard any
408: outcome.
409: This is useful when the user wishes to abandon an inprogress operation and
410: really doesn't care what the results are
411: (i.e., when reading from a database).
412: The verb"RyDiscard" routine is used to accomplish this function:
413: \begin{quote}\index{RyDiscard}\small\begin{verbatim}
414: int RyDiscard (sd, id, roi)
415: int sd,
416: id;
417: struct RoSAPindication *roi;
418: \end{verbatim}\end{quote}
419: The parameters to this procedure are:
420: \begin{describe}
421: \item[\verb"sd":] the association descriptor;
422:
423: \item[\verb"sd":] the invocation-identifier associated with the operation; and,
424:
425: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
426: which is updated only on failure.
427: \end{describe}
428: The \verb"RyDiscard" routine returns either \verb"NOTOK" (on failure)
429: or \verb"OK" (on success).
430:
431: \section {Routines for Responders}
432: Responders use the routines in the \man libacsap(3n) library for association
433: control.
434: These are described in Chapter~\ref{libacsap} of \volone/.
435:
436: \section {Routines for Performers}
437: After forming an association,
438: performers register the operations they are willing to perform.
439: They then typically wait for those operations to be invoked.
440:
441: \subsection {Registering Operations}\label{librosy:register}
442: The routine \verb"RyDispatch" is used to register a handler for an operation:
443: \begin{quote}\index{RyDispatch}\small\begin{verbatim}
444: int RyDispatch (sd, ryo, op, fnx, roi)
445: int sd;
446: struct RyOperation *ryo;
447: int op;
448: IFP fnx;
449: struct RoSAPindication *roi;
450: \end{verbatim}\end{quote}
451: The parameters to this procedure are:
452: \begin{describe}
453: \item[\verb"sd":] the association-descriptor;
454:
455: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table;
456:
457: \item[\verb"op":] the operation code of the operation to be registered;
458:
459: \item[\verb"fnx":] the address of a dispatch routine to be invoked when
460: the operation is invoked;
461: and,
462:
463: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
464: which is updated only if the call fails.
465: \end{describe}
466: An operation may be un-registered by using \verb"NULLIFP" for the \verb"fnx"
467: parameter.
468:
469: When a registered operation is invoked
470: (from the routine \verb"RyWait" described in Section~\ref{librosy:waiting}),
471: the dispatch routine is invoked with five parameters:
472: \begin{quote}\small\begin{verbatim}
473: result = (*fnx) (sd, ryo, rox, in, roi)
474: int sd;
475: struct RyOperation *ryo;
476: struct RoSAPinvoke *rox;
477: caddr_t in;
478: struct RoSAPindication *roi;
479: \end{verbatim}\end{quote}
480: The parameters to this procedure are:
481: \begin{describe}
482: \item[\verb"sd":] the association-descriptor;
483:
484: \item[\verb"ryo":] a pointer to a entry in the \verb"RyOperation" table
485: for this operation;
486:
487: \item[\verb"rox":] a pointer to a \verb"RoSAPinvoke" structure containing
488: miscellaneous information regarding the operation being invoked
489: (e.g., the invocation id);
490:
491: \item[\verb"in":] the address of the {\em C\/} structure for the operation's
492: argument (if any);
493: and,
494:
495: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
496: which is updated only if the operation was not performed.
497: \end{describe}
498: Note that if an argument is present for the operation,
499: then the \man librosy(3n) library will automatically release the memory used
500: by the {\em C\/} structure when the dispatch routine returns.
501:
502: The return value of the dispatch routine is consulted to determine the
503: disposition of the invocation.
504: One of three values should be returned:
505: \verb"NOTOK", which indicates that some non-operational error occured;
506: \verb"OK", which indicates that the operation was handled;
507: or,
508: \verb"DONE", which indicates that the association is pending termination.
509:
510: \subsection {Responding to Operations}
511: If the operation corresponding to the dispatch routine does not return a
512: result,
513: then the routine may simply process the request and return.
514: Otherwise,
515: the dispatch routine should ultimately cause one of three routines to be
516: called to handle an invocation.
517:
518: The routine \verb"RyDsResult" is used to return a result to an invocation.
519: \begin{quote}\index{RyDsResult}\small\begin{verbatim}
520: int RyDsResult (sd, id, out, priority, roi)
521: int sd;
522: int id,
523: priority;
524: caddr_t out;
525: struct RoSAPindication *roi;
526: \end{verbatim}\end{quote}
527: The parameters to this procedure are:
528: \begin{describe}
529: \item[\verb"sd":] the association-descriptor;
530:
531: \item[\verb"id":] the ID of the invocation being responded to;
532:
533: \item[\verb"out":] the address of the {\em C\/} structure for the operation's
534: result (if any);
535:
536: \item[\verb"priority":] the priority of the response
537: (use \verb"ROS_NOPRIO" if the priority is undetermined);
538: and,
539:
540: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
541: which is updated only if the call fails.
542: \end{describe}
543:
544: The routine \verb"RyDsError" is used to return an error to an invocation.
545: \begin{quote}\index{RyDsError}\small\begin{verbatim}
546: int RyDsError (sd, id, err, out, priority, roi)
547: int sd;
548: int id,
549: err,
550: priority;
551: caddr_t out;
552: struct RoSAPindication *roi;
553: \end{verbatim}\end{quote}
554: The parameters to this procedure are:
555: \begin{describe}
556: \item[\verb"sd":] the association-descriptor;
557:
558: \item[\verb"id":] the ID of the invocation being responded to;
559:
560: \item[\verb"err":] the error code being returned;
561:
562: \item[\verb"out":] the address of the {\em C\/} structure for the error's
563: parameter (if any);
564:
565: \item[\verb"priority":] the priority of the response
566: (use \verb"ROS_NOPRIO" if the priority is undetermined);
567: and,
568:
569: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
570: which is updated only if the call fails.
571: \end{describe}
572:
573: The routine \verb"RyDsUReject" is used to reject an invocation.
574: \begin{quote}\index{RyDsUReject}\small\begin{verbatim}
575: int RyDsUReject (sd, id, reason, priority, roi)
576: int sd;
577: int id,
578: reason,
579: priority;
580: struct RoSAPindication *roi;
581: \end{verbatim}\end{quote}
582: The parameters to this procedure are:
583: \begin{describe}
584: \item[\verb"sd":] the association-descriptor;
585:
586: \item[\verb"id":] the ID of the invocation being rejected;
587:
588: \item[\verb"reason":] the reason for the rejection
589: (codes are listed in Table~\ref{RoSAPreasons} on page~\pageref{RoSAPreasons}
590: of \volone/);
591:
592: \item[\verb"priority":] the priority of the response
593: (use \verb"ROS_NOPRIO" if the priority is undetermined);
594: and,
595:
596: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
597: which is updated only if the call fails.
598: \end{describe}
599:
600: \section {Waiting for Events}\label{librosy:waiting}
601: The \verb"RyWait" routine is used by both invokers and performers to wait
602: for some event to occur.
603: Normally,
604: it is not used by invokers,
605: except when it is desired to wait for a previously invoked asynchronous
606: operation to complete.
607: \begin{quote}\index{RyWait}\small\begin{verbatim}
608: int RyWait (sd, id, out, secs, roi)
609: int sd,
610: *id,
611: secs;
612: caddr_t *out;
613: struct RoSAPindication *roi;
614: \end{verbatim}\end{quote}
615: The parameters to this procedure are:
616: \begin{describe}
617: \item[\verb"sd":] the association-descriptor;
618:
619: \item[\verb"id":] the integer-value address of the invocation ID to wait for
620: (use \verb"NULLIP" if any invocation ID is satisfactory);
621:
622: \item[\verb"out":] an address-valued location which is updated if the call
623: succeeds;
624:
625: \item[\verb"secs":] the maximum number of seconds to wait
626: (a value of \verb"NOTOK" indicates that the call should block indefinitely,
627: whereas a value of \verb"OK" indicates that the call should not block at all,
628: e.g., a polling action);
629: and,
630:
631: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
632: which is updated only if the call fails.
633: \end{describe}
634: The \verb"RyWait" routine is analogous to the \verb"RoWaitRequest" routine in
635: the \man librosy(3n) library,
636: with the additional functions of:
637: automatically encoding and decoding arguments, results, and parameters;
638: invoking a dispatch routine for the performer on incoming invocations;
639: and,
640: also queuing events for future retrieval.
641:
642: The \verb"RyWait" routine returns one of three values:
643: \verb"NOTOK" (on failure),
644: \verb"OK" (on reading a reply),
645: or
646: \verb"DONE" (when something else happens).
647:
648: If the call to \verb"RyWait" returns the manifest constant \verb"NOTOK",
649: then the \verb"RoSAPpreject" structure contained in
650: the \verb"RoSAPindication" parameter
651: \verb"roi" contains the reason for the failure.
652:
653: If the call to \verb"RyWait" returns the manifest constant \verb"OK",
654: then either a result or error has been returned from a previous invocation.
655: The value of the \verb"roi_type" element of the \verb"RoSAPindication"
656: parameter is either \verb"ROI_RESULT" or \verb"ROI_ERROR",
657: and the value of the address pointed to by \verb"out" is a newly allocated
658: {\em C\/} structure for the operations result or error's parameter (if any).
659: Note that if a result or parameter is returned,
660: then it is the invoker's responsibility to release the memory used by the
661: {\em C\/} structure, when appropriate.
662:
663: If the call to \verb"RyWait" returns the manifest constant \verb"DONE",
664: then an indication that the association is pending termination is returned.
665: The value of the \verb"roi_type" element of the \verb"RoSAPindication"
666: parameter is either \verb"ROI_END" or \verb"ROI_FINISH".
667: Consult Section~\ref{ros:end} of \volone/ for the details.
668:
669: Note that because the \man librosy(3n) library may queue events while waiting
670: for a particular event,
671: it is important to call \verb"RyWait" with a \verb"secs" parameter of
672: \verb"OK" prior to deciding to explicitly block for activity
673: (e.g., calling \verb"RoSelectMask" or \verb"xselect").
674:
675: \section {Miscellaneous Routines}
676: There are a few miscellaneous routines of interest.
677:
678: \subsection {Association Termination}
679: When an association is either released or aborted,
680: it is important to expunge any information regarding queued operations from
681: the run-time environment.
682: The \verb"RyLose" routine is used to perform this function.
683: \begin{quote}\index{RyLose}\small\begin{verbatim}
684: int RyLose (sd, roi)
685: int sd;
686: struct RoSAPindication *roi;
687: \end{verbatim}\end{quote}
688: The parameters to this procedure are:
689: \begin{describe}
690: \item[\verb"sd":] the association-descriptor;
691: and,
692:
693: \item[\verb"roi":] a pointer to a \verb"RoSAPindication" structure,
694: which is updated only if the call fails.
695: \end{describe}
696:
697: \subsection {Utility Routines}
698: It may be useful,
699: primarily for diagnostic purposes,
700: to retrieve an entry for a particular operation or error from the tables
701: compiled by the \man rosy(1) compiler.
702: There are four routines for this purpose.
703:
704: The routine \verb"findopbyop" takes a table and an operation code and returns
705: the corresponding entry for the operation in the table,
706: or the manifest constant \verb"NULL" on failure.
707: \begin{quote}\index{findopbyop}\small\begin{verbatim}
708: struct RyOperation *findopbyop (ryo, op)
709: struct RyOperation *ryo;
710: int op;
711: \end{verbatim}\end{quote}
712: The parameters to this procedure are:
713: \begin{describe}
714: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table compiled by
715: \pgm{rosy};
716: and,
717:
718: \item[\verb"op":] the operation code of the operation to search for in the
719: table.
720: \end{describe}
721:
722: The routine \verb"findopbyname" takes a table and an operation name and returns
723: the corresponding entry for the operation in the table,
724: or the manifest constant \verb"NULL" on failure.
725: \begin{quote}\index{findopbyname}\small\begin{verbatim}
726: struct RyOperation *findopbyname (ryo, name)
727: struct RyOperation *ryo;
728: char *name;
729: \end{verbatim}\end{quote}
730: The parameters to this procedure are:
731: \begin{describe}
732: \item[\verb"ryo":] a pointer to a \verb"RyOperation" table compiled by
733: \pgm{rosy};
734: and,
735:
736: \item[\verb"name":] the operation name of the operation to search for in the
737: table.
738: \end{describe}
739:
740: The routine \verb"finderrbyerr" takes a table and an error code and returns
741: the corresponding entry for the error in the table,
742: or the manifest constant \verb"NULL" on failure.
743: \begin{quote}\index{finderrbyerr}\small\begin{verbatim}
744: struct RyError *finderrbyerr (rye, err)
745: struct RyError *rye;
746: int err;
747: \end{verbatim}\end{quote}
748: The parameters to this procedure are:
749: \begin{describe}
750: \item[\verb"rye":] a pointer to a \verb"RyError" table compiled by
751: \pgm{rosy};
752: and,
753:
754: \item[\verb"err":] the error code of the error to search for in the
755: table.
756: \end{describe}
757:
758: The routine \verb"finderrbyname" takes a table and an error code and returns
759: the corresponding entry for the error in the table,
760: or the manifest constant \verb"NULL" on failure.
761: \begin{quote}\index{finderrbyname}\small\begin{verbatim}
762: struct RyError *finderrbyname (rye, name)
763: struct RyError *rye;
764: char *name;
765: \end{verbatim}\end{quote}
766: The parameters to this procedure are:
767: \begin{describe}
768: \item[\verb"rye":] a pointer to a \verb"RyError" table compiled by
769: \pgm{rosy};
770: and,
771:
772: \item[\verb"name":] the error name of the error to search for in the
773: table.
774: \end{describe}
775:
776: \section {Error Conventions}
777: All of the routines in this library return the manifest constant \verb"NOTOK"
778: on error,
779: and also update the \verb"roi" parameter given to the routine.
780: The element called \verb"roi_preject" in the \verb"RoSAPindication" structure
781: encodes the reason for the failure.
782: To determine the reason,
783: one coerces a pointer to a \verb"RoSAPpreject" structure,
784: and consults the \verb"rop_reason" element of this latter structure.
785: This element can be given as a
786: parameter to the routine \verb"RoErrString" which returns a null-terminated
787: diagnostic string.
788: \begin{quote}\index{RoErrString}\small\begin{verbatim}
789: char *RoErrString (c)
790: int c;
791: \end{verbatim}\end{quote}
792:
793: \section {Compiling and Loading}
794: Programs using the \man librosy(3n) library should include
795: \verb"<isode/rosy.h>".
796: The programs should also be loaded with \verb"-lisode".
797:
798: %%% \section {Changes Since the Last Release}\label{rosy:changes}
799: %%% A brief summary of the major changes between v~\rosyprevrsn/ and
800: %%% v~\rosyvrsn/ are now presented.
801: %%% These are the user-visible changes only;
802: %%% changes of a strictly internal nature are not discussed.
803:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.