![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to librosap.3n 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 / rosap|
Return to librosap.3n CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / rosap |
1.1 root 1: .TH LIBROSAP 3N "21 Aug 1986"
2: .\" $Header: /f/osi/rosap/RCS/librosap.3n,v 7.0 89/11/23 22:21:11 mrose Rel $
3: .\"
4: .\" Based on an TCP-based implementation by George Michaelson of University
5: .\" College London.
6: .\"
7: .\"
8: .\" $Log: librosap.3n,v $
9: .\" Revision 7.0 89/11/23 22:21:11 mrose
10: .\" Release 6.0
11: .\"
12: .SH NAME
13: librosap \- Remote Operations Services library
14: .SH SYNOPSIS
15: .B "#include <isode/rosap.h>"
16: .sp
17: \fIcc\fR\0...\0\fB\-lisode\fR
18: .SH DESCRIPTION
19: The \fIlibrosap\fR library contains a set of routines which implement
20: remote operations facilities.
21: In essence,
22: they implement a Remote Operations Service Point
23: (RoSAP) interface for connection-oriented user applications.
24: .PP
25: The information contained herein is skeletal:
26: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
27: clients are coded and interact with the \fIlibrosap\fR library.
28: .SH "SERVICE DISCIPLINES"
29: Three remote operation service disciplines are implemented by the library:
30: \*(lqbasic\*(rq, \*(lqadvanced\*(rq, and \*(lqcomplete\*(rq.
31: The basic service is based on the ECMA technical report and an underlying
32: session service.
33: This remote operation service is selected when the \fBRoBeginRequest\fR and
34: \fBRoBeginResponse\fR routines are used.
35: In addition to making minimal requirements on the provider at the remote site,
36: the \*(lqbasic\*(rq discipline also limits the users by permitting only the
37: initiator to make invocations.
38: Certain applications, e.g., message handling systems, require more freedom
39: (such as two\-way invocations) along with more reliability.
40: The advanced service uses a different underlying service for ROS,
41: namely the reliable transfer service.
42: If the \fBRtBeginRequest\fR and \fBRtBeginResponse\fR routines
43: (from the \fIlibrtsap\fR\0(3n) library)
44: are used
45: to establish an association for remote operations services,
46: then the \*(lqadvanced\*(rq remote operation service is selected.
47: Finally,
48: the complete service supports linked operations,
49: and can be selected by using the \fBAcAssocRequest\fR and
50: \fBAcAssocResponse\fR routines (from the \fIlibacsap\fR\0(3n) library) are
51: used to establish an association.
52: .PP
53: In the addressing and initialization descriptions that follow,
54: keep in mind the distinctions described above.
55: Finally,
56: note that the corresponding \*(lqend\*(rq routines should be used based on
57: the \*(lqbegin\*(rq routines selected.
58: .SH ADDRESSES
59: RoSAP addresses are represented by the \fBRoSAPaddr\fR structure.
60: This contains a session address,
61: and the port number of the RoSAP as found in the \fIisoservices\fR\0(5)
62: database.
63: .SH "SERVER INITIALIZATION"
64: A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
65: with the argument vector listed in the ISODE services database.
66: The server's very first action is to re\-capture the RoSAP state as
67: recorded by \fItsapd\fR.
68: This is accomplished by calling \fBRoInit\fR.
69: Information returned by this call is equivalent to the parameters passed by a
70: RO\-BEGIN.INDICATION event.
71: If the call is successful,
72: the program can then examine the argument vector that was passed via
73: \fIexecvp\fR
74: (it's important to call \fBRoInit\fR prior to reading \fBargc\fR and
75: \fBargv\fR).
76: If the call to \fBRoInit\fR is not successful,
77: information returned by the call indicates the reason for failure.
78: .PP
79: After examining the information provided by \fBRoInit\fR
80: (and possibly the argument vector),
81: the server should either accept or reject the association.
82: If accepting, the \fBRoBeginResponse\fR routine is called with the parameter
83: \fBstatus\fR set to
84: .sp
85: .in +.5i
86: .nf
87: .ta \w'ROS_VALIDATE 'u
88: ROS_ACCEPT association accepted
89: .re
90: .fi
91: .in -.5i
92: .sp
93: (which corresponds to the accepting RO\-BEGIN.RESPONSE action).
94: If the call is successful,
95: the association has been bound.
96: If un\-successful,
97: information returned by the call indicates the reason for failure.
98: If rejecting, the \fBRoBeginResponse\fR routine is also called,
99: but with the parameter \fBstatus\fR set to one of:
100: .sp
101: .in +.5i
102: .nf
103: .ta \w'ROS_VALIDATE 'u
104: ROS_VALIDATE authentication failure
105: ROS_BUSY busy
106: .re
107: .fi
108: .in -.5i
109: .sp
110: (which corresponds to the refusing RO\-BEGIN.RESPONSE action),
111: and the program may exit.
112: .SH "CLIENT INITIALIZATION"
113: A program requesting an ISO service calls \fBRoBeginRequest\fR
114: (which corresponds to the RO\-BEGIN.REQUEST action).
115: If successful (depending on the responder's choice of \fBstatus\fR),
116: the association is bound.
117: If un\-successful,
118: information returned by the call indicates the reason for failure.
119: .SH ASSOCIATION\-DESCRIPTORS
120: Once an association has been bound via a successful return from
121: \fBRoBeginResponse\fR (for servers) or \fBRoBeginRequest\fR (for clients),
122: an association is referenced by a small integer
123: (returned in a structure passed to these calls) called an
124: \fIassociation\-descriptor\fR.
125: The association\-descriptor appears as an argument to the peer routines
126: described below.
127: .PP
128: By default,
129: events associated with a association\-descriptor are synchronous in nature:
130: activity in the network won't generate an INDICATION event without program
131: first asking to be told of any activity.
132: To mark an association\-descriptor as asynchronous,
133: a call to \fBRoSetIndications\fR is made with the address of an integer
134: function to handle incoming events.
135: Upon a successful return from \fBRoSetIndications\fR,
136: the event handler will be called in this fashion:
137: .sp
138: .in +.5i
139: .B "(*handler) (sd, roi);"
140: .in -.5i
141: .sp
142: where \fBsd\fR is the association\-descriptor,
143: and \fBroi\fR is a pointer to a \fBRoSAPindication\fR structure.
144: Any value returned by the event\-handler is ignored.
145: .PP
146: Note well: the \fB\-lisode\fR library uses the \fB\-ltsap\fR library to
147: provide this interface.
148: The latter library uses the SIGEMT signal to provide this service.
149: Programs loaded with \fB\-ltsap\fR that use asynchronous
150: association\-descriptors should NOT use SIGEMT for other purposes.
151: .PP
152: For synchronous multiplexing of several associations,
153: the routine \fBRoSelectMask\fR
154: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
155: .SH PEER
156: A fatal failure (consult the \fIUser's Manual\fR)
157: on return from any of these routines results in the association being unbound.
158: .sp
159: .in +.5i
160: .nf
161: .ta \w'\fBRoRejectURequest\fR 'u
162: \fIroutine\fR \fIaction\fR
163: \fBRoInvokeRequest\fR RO\-INVOKE.REQUEST
164: \fBRoResultRequest\fR RO\-RESULT.REQUEST
165: \fBRoErrorRequest\fR RO\-ERROR.REQUEST
166: \fBRoRejectURequest\fR RO\-REJECT\-U.REQUEST
167: \fBRoWaitRequest\fR RO\-WAIT.REQUEST (synchronous wait)
168: \fBRoEndRequest\fR RO\-END.REQUEST
169: \fBRoEndResponse\fR RO\-END.RESPONSE
170: .re
171: .fi
172: .in -.5i
173: .sp
174: Note that the \fBRoWaitRequest\fR routine returns data from the peer by
175: allocating memory.
176: It should be freed before the structure is re\-used.
177: .PP
178: Finally,
179: the routine \fBRoErrString\fR takes a failure code from a \fBRoSAPpreject\fR
180: structure and returns a null\-terminated diagnostic string.
181: .SH FILES
182: .nf
183: .ta \w'\*(EDisoservices 'u
184: \*(EDisoentities ISODE entities database
185: \*(EDisobjects ISODE objects database
186: \*(EDisoservices ISODE services database
187: .re
188: .fi
189: .SH "SEE ALSO"
190: libacsap (3n), librtsap (3n), isoentities(5), isobjects (5), isoservices(5)
191: .br
192: \fIThe ISO Development Environment: User's Manual\fR,
193: .br
194: ISO 9072/1:
195: \fIInformation Processing Systems \-\- Text Communication \-\- MOTIS \-\-
196: Remote Operations Part 1: Model, Notation and Service Definition\fR,
197: .br
198: CCITT Recommendation X.410:
199: \fIMessage Handling Systems: Remote Operations and Reliable Transfer Server\fR,
200: .br
201: ECMA Technical Report:
202: \fIRemote Operations: Concepts, Notation and Connection\-Oriented Mappings\fR,
203: Final Draft, July, 1985
204: .SH DIAGNOSTICS
205: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
206: .SH AUTHOR
207: Marshall T. Rose
208: .PP
209: This library is based on an initial implementation by George
210: Michaelson,
211: University College London.
212: .SH BUGS
213: Do not confuse association\-descriptors with file\-descriptors.
214: Unlike file\-descriptors which are implemented by the kernel,
215: association\-descriptors to not work across \fIfork\fRs and \fIexec\fRs.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.