![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to acsap.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 acsap.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 {Association Control}\label{libacsap}
4: The \man libacsap(3n) library implements the Association Control Service
5: (ACS).
6: Logically,
7: one views an application to consist of several {\em application service
8: elements\/} (ASE's).
9: Although these ASEs cooperate,
10: each performs a different function for the application.
11: The Association Control Service Element (ACSE) is concerned with the task of
12: ``starting'' and ``stopping'' the network for the application.
13: That is,
14: an application uses the ACSE to establish a connection,
15: termed an {\em association}, between two users.
16: The association {\em binds\/} the two users,
17: which are referred to as
18: the {\em initiator\/} and the {\em responder}.
19: This association, once established is used by other ASEs
20: (e.g., the remote operations service element).
21: Later,
22: the ACSE is called upon to release the association,
23: either gracefully (perhaps with some negotiation),
24: or abruptly (with possible loss of information).
25:
26: Like most models of OSI services,
27: the underlying assumption is one of an asynchronous environment:
28: the service provider may generate events for the service user without the
29: latter entity triggering the actions which led to the event.
30: For example,
31: in a synchronous environment,
32: an indication that data has arrived usually occurs only when the service user
33: asks the service provider to read data;
34: in an asynchronous environment,
35: the service provider may interrupt the service user at any time to announce
36: the arrival of data.
37:
38: The \verb"acsap" module in this release presents a synchronous interface.
39: However once the association is established,
40: an asynchronous interface may be selected.
41: The \verb"acsap" module itself is naive as to the interface being used:
42: the particular application service element which is responsible for
43: transferring data will manage the association once the ACSE has established it.
44:
45: All of the routines in the \man libacsap(3n) library are integer-valued.
46: They return the manifest constant \verb"OK" on success,
47: or \verb"NOTOK" otherwise.
48: In some circumstances,
49: failures are fatal and cause (or are caused by) the association being released.
50: Section~\ref{acs:errors} describes how such failures may be distinguished.
51:
52: \section {An Important Note}\label{acs:note}
53: In the current release
54: there are several ways to establish an association.
55: This is due to recent changes in the OSI application layer,
56: and a desire to remain compatible with previous work.
57: Users are strongly encouraged to use the new facilities described herein,
58: as the older facilities will eventually be removed.
59:
60: Here are the new facilities available:
61: \[\begin{tabular}{|l|l|l|}
62: \hline
63: \multicolumn{1}{|c|}{\bf Desired Service}&
64: \multicolumn{1}{c|}{\bf Association Primitives}&
65: \multicolumn{1}{c|}{\bf Section(s)}\\
66: \hline
67: Remote Operations& {\sf A-ASSOCIATE}& \ref{acs:associations}\\
68: \ (complete discipline)&
69: {\sf A-RELEASE}& \ref{ros:underlying}\\
70: \ \cite{ISO.ROS.Service,CCITT.ROS.Service}&
71: {\sf A-ABORT}& \\[0.1in]
72: \hline
73: Remote Operations& {\sf RT-OPEN}& \ref{rts:associations}\\
74: \ (complete discipline& {\sf RT-CLOSE}& \ref{ros:underlying}\\
75: \ \ with reliable transfer)&& \\
76: \ \cite{ISO.ROS.Service,CCITT.ROS.Service}&
77: & \\[0.1in]
78: \hline
79: Reliable Transfer& {\sf RT-OPEN}& \ref{rts:associations}\\
80: \ \cite{ISO.RTS.Service,CCITT.RTS.Service}&
81: {\sf RT-CLOSE}& \\
82: \hline
83: \end{tabular}\]
84: \clearpage %%% yikes!
85:
86: Here are the old facilities available:
87: \[\begin{tabular}{|l|l|l|}
88: \hline
89: \multicolumn{1}{|c|}{\bf Desired Service}&
90: \multicolumn{1}{c|}{\bf Association Primitives}&
91: \multicolumn{1}{c|}{\bf Section}\\
92: \hline
93: Remote Operations& {\sf RO-BEGIN}& \ref{ros:old-style}\\
94: \ (basic discipline)& {\sf RO-END}& \\
95: \ \cite{ECMA.ROS}& & \\[0.1in]
96: \hline
97: Remote Operations& {\sf X.410 OPEN}& \ref{rts:old-style}\\
98: \ (advanced discipline& {\sf X.410 CLOSE}& \ref{ros:underlying}\\
99: \ \ with reliable transfer)&& \\
100: \ \cite{MHS.RTS}& & \\[0.1in]
101: \hline
102: Reliable Transfer& {\sf X.410 OPEN}& \ref{rts:old-style}\\
103: \ \cite{MHS.RTS}& {\sf X.410 CLOSE}& \\
104: \hline
105: \end{tabular}\]
106:
107: In short, depending on whether a Reliable Transfer Service Element (RTSE) is
108: desired,
109: for the purposes of association control,
110: all new applications should use either the library discussed below,
111: or the reliable transfer routines discussed in
112: Section~\ref{rts:associations} on page~\pageref{rts:associations}.
113:
114: \section {Associations}\label{acs:associations}
115: There are three aspects of association management:
116: {\em association establishment},
117: {\em association release},
118: and,
119: {\em association abort}.
120: Each of these are now described in turn.
121:
122: \subsection {Association Establishment}
123: The \man libacsap(3n) library distinguishes between the user which started an
124: association,
125: the {\em initiator},
126: and the user which was subsequently bound to the association,
127: the {\em responder}.
128: We sometimes term these two entities the {\em client\/} and the {\em server},
129: respectively.
130:
131: \subsubsection {Addresses}\label{acs:addresses}\label{acs:aei}
132: Addresses for the association control service entity consist of two parts:
133: a presentation address (as discussed in Section~\ref{psap:addresses} on
134: page~\pageref{psap:addresses} of \voltwo/),
135: and application-entity information.
136: Internally,
137: the \verb"AEInfo" is used to represent this notion:
138: \begin{quote}\index{AEInfo}\small\begin{verbatim}
139: typedef struct AEInfo {
140: PE aei_ap_title;
141: PE aei_ae_qualifier;
142:
143: int aei_ap_id;
144: int aei_ae_id;
145:
146: int aei_flags;
147: #define AEI_NULL 0x00
148: #define AEI_AP_ID 0x01
149: #define AEI_AE_ID 0x02
150: } AEInfo, *AEI;
151: #define NULLAEI ((AEI) 0)
152: \end{verbatim}\end{quote}
153: This structure contains several elements:
154: \begin{describe}
155: \item[\verb"aei\_ap\_title":] the application-process title;
156:
157: \item[\verb"aei\_ae\_qualifier":] the application-entity qualifier;
158:
159: \item[\verb"aei\_ap\_id":] the application-process invocation identifier;
160:
161: \item[\verb"aei\_ae\_id":] the application-entity invocation identifier;
162: and,
163:
164: \item[\verb"aei\_flags":] flags, indicating which, if any,
165: of the invocation-identifiers are present.
166: \end{describe}
167:
168: The routing \verb"sprintaei" can be used to return a null-terminated
169: string describing the application-entity.
170: \begin{quote}\index{sprintaei}\small\begin{verbatim}
171: char *sprintaei (aei)
172: AEI aei;
173: \end{verbatim}\end{quote}
174:
175: Finally,
176: the routine \verb"oid2aei" converts object identifiers
177: (discussed in Section~\ref{psap:oid} on page~\pageref{psap:oid})
178: and converts them to application-entity information.
179: This is used by the stub-directory service:
180: \begin{quote}\index{oid2aei}\small\begin{verbatim}
181: AEI oid2aei (oid)
182: OID oid;
183: \end{verbatim}\end{quote}
184:
185: In Figure~\ref{getFTAMentity},
186: an example of how one constructs the address for the File Transfer, Access
187: and Management (FTAM) service on host \verb"RemoteHost" is presented.
188: The key routine is \verb"_str2aei":
189: \begin{quote}\index{\_str2aei}\small\begin{verbatim}
190: AEI _str2aei (designator, qualifier, context, interactive)
191: char *designator,
192: *qualifier,
193: *context;
194: int interactive;
195: \end{verbatim}\end{quote}
196: The parameters to this procedure are:
197: \begin{describe}
198: \item[\verb"designator":] input from the user
199: (e.g., ``\verb"hubris, cs, ucl, gb"'' or ``\verb"hubris"'');
200:
201: \item[\verb"qualifier":] the service qualifier (e.g., \verb"filestore");
202:
203: \item[\verb"context":] the \verb"supportedApplicationContext" for the desired
204: service (e.g., \verb"iso ftam");
205: and;
206:
207: \item[\verb"interactive":] non-zero if the user's terminal can be queried for
208: additional information.
209: \end{describe}
210: The routine \verb"_str2aei" will first attempt to resolution using the
211: ``user-friendly nameservice'' with the \verb"designator", \verb"context", and
212: \verb"interactive" parameters.
213: If this fails,
214: the ``stub directory service'' will be used,
215: with the \verb"designator" and \verb"qualifier" parameters.
216:
217: For backwards-compatiblity,
218: a macro, \verb"str2aei" is provided which is equivalent to:
219: \begin{quote}\index{str2aei}\small\begin{verbatim}
220: _str2aei (designator, qualifier, NULLCP, 0)
221: \end{verbatim}\end{quote}
222:
223: The routine \verb"aei2addr" takes application-entity information,
224: and returns the appropriate presentation address.
225: \begin{quote}\index{aei2addr}\small\begin{verbatim}
226: struct PSAPaddr *aei2addr (aei)
227: AEI aei;
228: \end{verbatim}\end{quote}
229: \tagrind[tp]{grind2a-1}%
230: {Constructing the address for the FTAM entity}{getFTAMentity}
231:
232: \subsubsection {Address Encodings}\label{addr:encodings}
233: It may be useful to encode a presentation address for viewing.
234: Although a consensus for a standard way of doing this has not yet been
235: reached,
236: the routines \verb"paddr2str" and \verb"str2paddr" may be used in the interim.
237: These implement the encodings defined in \cite{String.Addresses}.
238: The BNF syntax for this encoding is shown in Figure~\ref{str:format} on
239: page~\pageref{str:format}.
240: \begin{quote}\index{paddr2str}\small\begin{verbatim}
241: char *paddr2str (pa, na)
242: struct PSAPaddr *pa;
243: struct NSAPaddr *na;
244: \end{verbatim}\end{quote}
245: The parameters to this procedure are:
246: \begin{describe}
247: \item[\verb"pa":] the presentation address;
248: and,
249:
250: \item[\verb"na":] a network address to use instead of the network addresses
251: in the \verb"pa" parameter
252: (use the manifest constant \verb"NULLNA" otherwise).
253: \end{describe}
254: If \verb"paddr2str" fails,
255: it returns the manifest constant \verb"NULLCP".
256:
257: The routine \verb"str2paddr" takes an ascii string encoding and
258: returns a
259: presentation address.
260: \begin{quote}\index{str2paddr}\small\begin{verbatim}
261: struct PSAPaddr *str2paddr (str)
262: char *str;
263: \end{verbatim}\end{quote}
264: The parameter to this procedure is:
265: \begin{describe}
266: \item[\verb"str":] the ascii string.
267: \end{describe}
268: If \verb"str2paddr" fails,
269: it returns the manifest constant \verb"NULLPA".
270: \tagrind[tp]{grind2a-2f}{BNF Syntax for paddr2str/str2paddr}{str:format}
271: \tagrind[tp]{grind2a-2g}{BNF Syntax for paddr2str/str2paddr (continued)}\empty
272:
273: \verb"paddr2str" is really a macro which calls the routine \verb"_paddr2str":
274: \begin{quote}\index{\_paddr2str}\small\begin{verbatim}
275: char *_paddr2str (pa, na, compact)
276: struct PSAPaddr *pa;
277: struct NSAPaddr *na;
278: int compact;
279: \end{verbatim}\end{quote}
280: The parameters to this procedure are:
281: \begin{describe}
282: \item[\verb"pa":] the presentation address;
283:
284: \item[\verb"na":] a network address to use instead of the network addresses
285: in the \verb"pa" parameter
286: (use the manifest constant \verb"NULLNA" otherwise);
287: and,
288:
289: \item[\verb"compact":] indicates the style of encoding.
290: \end{describe}
291: If \verb"compact" is greater than zero,
292: then the encoding reflects a normalized network address.
293: This is useful for passing to arbitrary processes in the network.
294: If \verb"compact" is less than zero,
295: then the encoding reflects the BNF in Figure~\ref{str:format},
296: without any macro substitutions.
297: If \verb"compact" is equal to zero (which is what \verb"paddr2str" uses),
298: then the encoding reflects the above BNF with macro substitutions.
299:
300: The routine \verb"pa2str" takes a presentation address and returns a
301: null-ter\-mi\-na\-ted ascii string suitable for viewing:
302: \begin{quote}\index{pa2str}\begin{verbatim}
303: char *pa2str (pa)
304: struct PSAPaddr *pa;
305: \end{verbatim}\end{quote}
306: The parameter to this procedure is:
307: \begin{describe}
308: \item[\verb"pa"]: the presentation address to be printed.
309: \end{describe}
310:
311: \subsubsection {Server Initialization}
312: The \man tsapd(8c) daemon,
313: upon accepting a connection from an initiating host,
314: consults the ISO services database to determine which program
315: on the local system implements the desired application context.
316:
317: Once the program has been ascertained,
318: the daemon runs the program with any arguments listed in the database.
319: In addition,
320: it appends some {\em magic arguments\/} to the argument vector.
321: Hence,
322: the very first action performed by the responder is to re-capture the ACSE
323: state contained in the magic arguments.
324: This is done by calling the routine \verb"AcInit",
325: which on a successful return,
326: is equivalent to a {\sf A-ASSOCIATE.INDICATION\/} event from the association
327: control service provider.
328: \begin{quote}\index{AcInit}\small\begin{verbatim}
329: int AcInit (vecp, vec, acs, aci)
330: int vecp;
331: char **vec;
332: struct AcSAPstart *acs;
333: struct AcSAPindication *aci;
334: \end{verbatim}\end{quote}
335: The parameters to this procedure are:
336: \begin{describe}
337: \item[\verb"vecp":] the length of the argument vector;
338:
339: \item[\verb"vec":] the argument vector;
340:
341: \item[\verb"acs":] a pointer to an \verb"AcSAPstart" structure,
342: which is updated only if the call succeeds;
343: and,
344:
345: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
346: which is updated only if the call fails.
347: \end{describe}
348: If \verb"AcInit" is successful,
349: it returns information in the \verb"acs" parameter,
350: which is a pointer to an \verb"AcSAPstart" structure.
351: \begin{quote}\index{AcSAPstart}\small\begin{verbatim}
352: struct AcSAPstart {
353: int acs_sd;
354:
355: OID acs_context;
356:
357: AEInfo acs_callingtitle;
358: AEInfo acs_calledtitle;
359:
360: struct PSAPstart acs_start;
361:
362: int acs_ninfo;
363: PE acs_info[NACDATA];
364: };
365: \end{verbatim}\end{quote}
366: The elements of this structure are:\label{AcSAPstart}
367: \begin{describe}
368: \item[\verb"acs\_sd":] the association-descriptor to be used to reference
369: this association;
370:
371: \item[\verb"acs\_context":] the application context name;
372:
373: \item[\verb"acs\_callingtitle":] information on the calling application-entity
374: (if any);
375:
376: \item[\verb"acs\_calledtitle":] information on the called application-entity
377: (if any);
378:
379: \item[\verb"acs\_start":] an \verb"PSAPstart" structure
380: (consult page~\pageref{PSAPstart} of \voltwo/);
381: and,
382:
383: \item[\verb"acs\_info"/\verb"acs\_ninfo":] any initial data
384: (and the length of that data).
385: \end{describe}
386: Note that the proposed contexts list in the \verb"acs_start" element will
387: contain a context for the ACSE.
388: The routine \verb"AcFindPCI" can be used to determine the PCI being used by
389: the ACSE:
390: \begin{quote}\index{AcFindPCI}\small\begin{verbatim}
391: int AcFindPCI (sd, pci, aci)
392: int sd;
393: int *pci;
394: struct AcSAPindication *aci;
395: \end{verbatim}\end{quote}
396: The parameters to this procedure are:
397: \begin{describe}
398: \item[\verb"sd":] the association-descriptor;
399:
400: \item[\verb"pci":] a pointer to an integer location,
401: which is updated only if the call succeeds;
402: and,
403:
404: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
405: which is updated only if the call fails.
406: \end{describe}
407:
408: Further,
409: note that the data contained in the structure was allocated via \man malloc(3),
410: and should be released by using the \verb"ACSFREE" macro when no longer
411: referenced.
412: The \verb"ACSFREE" macro,
413: behaves as if it was defined as:\label{ACSFREE}
414: \begin{quote}\index{ACSFREE}\small\begin{verbatim}
415: void ACSFREE (acs)
416: struct AcSAPstart *acs;
417: \end{verbatim}\end{quote}
418: The macro frees only the data allocated by \verb"AcInit",
419: and not the \verb"AcSAPstart" structure itself.
420: Further,
421: \verb"ACSFREE" should be called only if the call to the \verb"AcInit"
422: routine returned \verb"OK".
423:
424: If the call to \verb"AcInit" is not successful,
425: then a {\sf A-P-ABORT.INDICATION\/} event is simulated,
426: and the relevant information is returned in an encoded
427: \verb"AcSAPindication" structure.\label{AcSAPindication}
428: \begin{quote}\index{AcSAPindication}\small\begin{verbatim}
429: struct AcSAPindication {
430: int aci_type;
431: #define ACI_FINISH 0x00
432: #define ACI_ABORT 0x01
433:
434: union {
435: struct AcSAPfinish aci_un_finish;
436: struct AcSAPabort aci_un_abort;
437: } aci_un;
438: #define aci_finish aci_un.aci_un_finish
439: #define aci_abort aci_un.aci_un_abort
440: };
441: \end{verbatim}\end{quote}
442: As shown, this structure is really a discriminated union
443: (a structure with a tag element followed by a union).
444: Hence, on a failure return,
445: one first coerces a pointer to the \verb"AcSAPabort" structure contained
446: therein,
447: and then consults the elements of that structure.
448: \begin{quote}\index{AcSAPabort}\small\begin{verbatim}
449: struct AcSAPabort {
450: int aca_source;
451:
452: int aca_reason;
453:
454: int aca_ninfo;
455: PE aca_info[NACDATA];
456:
457: #define ACA_SIZE 512
458: int aca_cc;
459: char aca_data[ACA_SIZE];
460: };
461: \end{verbatim}\end{quote}
462: The elements of an \verb"AcSAPabort" structure are:
463: \begin{describe}
464: \item[\verb"aca\_source":] the source of the abort, one of:
465: \[\begin{tabular}{|l|l|}
466: \hline
467: \multicolumn{1}{|c|}{\bf Value}&
468: \multicolumn{1}{c|}{\bf Source}\\
469: \hline
470: \tt ACA\_USER& service-user (peer)\\
471: \tt ACA\_PROVIDER& service-provider\\
472: \tt ACA\_LOCAL& local ACPM\\
473: \hline
474: \end{tabular}\]
475:
476: \item[\verb"aca\_reason":] the reason for the provider-initiated abort
477: (meaningful only if \verb"aca_source" is not \verb"ACA_REQUESTOR"),
478: consult Table~\ref{AcSAPreasons};
479:
480: \item[\verb"aca\_info"/\verb"aca\_ninfo":] any abort data
481: (and the length of that data) from the peer
482: (if \verb"aca_source" is \verb"ACA_USER");
483: and,
484:
485: \item[\verb"aca\_data"/\verb"aca\_cc":] a diagnostic string from the provider.
486: \end{describe}
487: \tagtable[tp]{2a-1}{AcSAP Failure Codes}{AcSAPreasons}
488: Note that the data contained in the structure was allocated via \man malloc(3),
489: and should be released by using the \verb"ACAFREE" macro when no longer
490: referenced.
491: The \verb"ACAFREE" macro,
492: behaves as if it was defined as:\label{ACAFREE}
493: \begin{quote}\index{ACAFREE}\small\begin{verbatim}
494: void ACAFREE (aca)
495: struct AcSAPabort *aca;
496: \end{verbatim}\end{quote}
497: The macro frees only the data contained in the structure,
498: and not the \verb"AcSAPabort" structure itself.
499:
500: After examining the information returned by \verb"AcInit" on a successful call
501: (and possibly after examining the argument vector),
502: the responder should either accept or reject the association.
503: For either response,
504: the responder should use the \verb"AcAssocResponse" routine
505: (which corresponds to the {\sf A-ASSOCIATE.RESPONSE\/} action).
506: \begin{quote}\index{AcAssocResponse}\small\begin{verbatim}
507: int AcAssocResponse (sd, status, reason, context,
508: respondtitle, respondaddr, ctxlist, defctxresult,
509: prequirements, srequirements, isn, settings, ref,
510: data, ndata, aci)
511: int sd;
512: int status,
513: reason;
514: OID context;
515: AEI respondtitle;
516: struct PSAPaddr *respondaddr;
517: int prequirements,
518: srequirements,
519: settings,
520: ndata;
521: long isn;
522: struct PSAPctxlist *ctxlist;
523: int defctxresult;
524: struct SSAPref *ref;
525: PE *data;
526: struct AcSAPindication *aci;
527: \end{verbatim}\end{quote}
528: The parameters to this procedure are:\label{AcAssocResponse}
529: \begin{describe}
530: \item[\verb"sd":] the association-descriptor;
531:
532: \item[\verb"status":] the acceptance indicator
533: (either \verb"ACS_ACCEPT" if the association is to be accepted,
534: or one of the user-initiated rejection codes listed in
535: Table~\ref{AcSAPreasons} on page~\pageref{AcSAPreasons});
536:
537: \item[\verb"reason":] the diagnostic
538: (either \verb"ACS_USER_NULL" if the association is to be accepted,
539: or one of the user-initiated diagnostic codes listed in
540: Table~\ref{AcSAPdiagnostics} on page~\pageref{AcSAPdiagnostics});
541:
542: \item[\verb"context":] the application context to be used over the
543: association (defaults to the context proposed);
544:
545: \item[\verb"respondtitle":] information on the responding application-entity
546: (optional);
547:
548: \item[\verb"data"/\verb"ndata":] an array of user data
549: (and the number of elements in that array,
550: consult the warning on page~\pageref{AcSAPdata});
551: and,
552:
553: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
554: which is updated only if the call fails.
555: \end{describe}
556: The remaining parameters are for the presentation service,
557: consult the description of the \verb"PConnResponse" routine on
558: page~\pageref{PConnResponse} of \voltwo/.
559: \tagtable[tp]{2a-2}{AcSAP Diagnostic Codes}{AcSAPdiagnostics}
560:
561: If the call to \verb"AcAssocResponse" is successful,
562: and the \verb"status" parameter is set to \verb"ACS_ACCEPT",
563: then association establishment has now been completed.
564: If the call is successful,
565: but the \verb"status" parameter is not \verb"ACS_ACCEPT",
566: then the association has been rejected and the responder may exit.
567: Otherwise,
568: if the call failed and the reason is ``fatal'',
569: then the association is lost.
570:
571: \subsubsection {Client Initialization}
572: A program wishing to associate itself with another application-level user
573: calls the \verb"AcAssocRequest" routine,
574: which corresponds to the user taking the {\sf A-ASSOCIATE.REQUEST\/} action.
575: \begin{quote}\index{AcAssocRequest}\small\begin{verbatim}
576: int AcAssocRequest (context, callingtitle, calledtitle,
577: callingaddr, calledaddr, ctxlist, defctxname,
578: prequirements, srequirements, isn, settings, ref,
579: data, ndata, qos, acc, aci)
580: OID context;
581: AEI callingtitle,
582: calledtitle;
583: struct PSAPaddr *callingaddr,
584: *calledaddr;
585: int prequirements,
586: srequirements,
587: settings,
588: ndata;
589: long isn;
590: struct PSAPctxlist *ctxlist;
591: OID defctxname;
592: struct SSAPref *ref;
593: PE *data;
594: struct QOStype *qos;
595: struct AcSAPconnect *acc;
596: struct AcSAPindication *aci;
597: \end{verbatim}\end{quote}
598: The parameters to this procedure are:\label{AcAssocRequest}
599: \begin{describe}
600: \item[\verb"context":] the application context to be used over the
601: association;
602:
603: \item[\verb"callingtitle":] information on the calling application-entity
604: (use the manifest constant \verb"NULLAEI" if not specified);
605:
606: \item[\verb"calledtitle":] information on the called application-entity
607: (use the manifest constant \verb"NULLAEI" if not specified);
608:
609: \item[\verb"data"/\verb"ndata":] an array of initial data
610: (and the number of elements in that array,
611: consult the warning on page~\pageref{AcSAPdata});
612:
613: \item[\verb"qos":] the quality of service on the connection
614: (see Section~\ref{tsap:qos} in \voltwo/);
615:
616: \item[\verb"acc":] a pointer to an \verb"AcSAPconnect" structure,
617: which is updated only if the call succeeds;
618: and,
619:
620: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
621: which is updated only if the call fails.
622: \end{describe}
623: The remaining parameters are for the presentation service,
624: consult the description of the \verb"PConnRequest" routine on
625: page~\pageref{PConnRequest} of \voltwo/ for additional information.
626: Note that the \verb"ctxlist" parameter is mandatory:
627: the association control service element will look for the ACSE PCI there.
628: If not present,
629: it will add the PCI to the list.
630:
631: If the call to \verb"AcAssocRequest" is successful
632: (the {\sf A-ASSOCIATE.CON\-FIR\-MA\-TION\/} event occurs),
633: it returns information in the \verb"acc" parameter
634: which is a pointer to an \verb"AcSAPconnect" structure.
635: \begin{quote}\index{AcSAPconnect}\small\begin{verbatim}
636: struct AcSAPconnect {
637: int acc_sd;
638:
639: int acc_result;
640: int acc_diagnostic;
641:
642: OID acc_context;
643:
644: AEInfo acc_respondtitle;
645:
646: struct PSAPconnect acc_connect;
647:
648: int acc_ninfo;
649: PE acc_info[NACDATA];
650: };
651: \end{verbatim}\end{quote}
652: The elements of an \verb"AcSAPconnect" structure are:\label{AcSAPconnect}
653: \begin{describe}
654: \item[\verb"acc\_sd":] the association-descriptor to be used to reference
655: this association;
656:
657: \item[\verb"acc\_result"/\verb"acc\_diagnostic":] the association response
658: and diagnostic;
659:
660: \item[\verb"acc\_context":] the application context name;
661:
662: \item[\verb"acc\_respondtitle":] information on the responding
663: application-entity (if any);
664:
665: \item[\verb"acc\_connect":] an \verb"PSAPconnect" structure
666: (consult page~\pageref{PSAPconnect} of \voltwo/);
667: and,
668:
669: \item[\verb"acc\_info"/\verb"acc\_ninfo":] any initial data
670: (and the length of that data).
671: \end{describe}
672: Note that the negotiated contexts list in the \verb"acc_connect" element
673: will contain a context for the ACSE.
674: To determine the PCI for the ACSE context,
675: the routine \verb"AcFindPCI" routine,
676: described above can be used.
677:
678: If the call to \verb"AcAssocRequest" is successful,
679: and the \verb"acc_result" element is set to \verb"ACC_ACCEPT",
680: then association establishment has completed.
681: If the call is successful,
682: but the \verb"acc_result" element is not \verb"ACC_ACCEPT",
683: then the association attempt has been rejected;
684: consult Table~\ref{AcSAPreasons} on page~\pageref{AcSAPreasons}
685: and Table~\ref{AcSAPdiagnostics} on page~\pageref{AcSAPdiagnostics}
686: to determine the reason for the rejection
687: (further information can be found in the \verb"aci" parameter).
688: Otherwise, if the call fails then the association is not established and
689: the \verb"AcSAPabort" structure of the \verb"AsCAPindication" discriminated
690: union has been updated.
691:
692: Note that the data contained in the structure was allocated via \man malloc(3),
693: and should be released by using the \verb"ACCFREE" macro when no longer
694: referenced.
695: The \verb"ACCFREE" macro,
696: behaves as if it was defined as:\label{ACCFREE}
697: \begin{quote}\index{ACCFREE}\small\begin{verbatim}
698: void ACCFREE (acc)
699: struct AcSAPconnect *acc;
700: \end{verbatim}\end{quote}
701: The macro frees only the data allocated by \verb"AcAssocRequest",
702: and not the \verb"AcSAPconnect" structure itself.
703: Further,
704: \verb"ACCFREE" should be called only if the call to the \verb"AcAssocRequest"
705: routine returned \verb"OK".
706:
707: Normally \verb"AcAssocRequest" returns only after an association has succeeded
708: or failed.
709: This is termed a {\em synchronous\/} association initiation.
710: If the user desires, an {\em asynchronous\/} association may be initiated.
711: This routine is really a macro which calls the routine
712: \verb"AcAsynAssocRequest" with an argument indicating that a association should
713: be attempted synchronously.
714: \begin{quote}\index{AcAsynAssocRequest}\small\begin{verbatim}
715: int AcAsynAssocRequest (context, callingtitle, calledtitle,
716: callingaddr, calledaddr, ctxlist, defctxname,
717: prequirements, srequirements, isn, settings, ref,
718: data, ndata, qos, acc, aci, async)
719: OID context;
720: AEI callingtitle,
721: calledtitle;
722: struct PSAPaddr *callingaddr,
723: *calledaddr;
724: int prequirements,
725: srequirements,
726: settings,
727: ndata,
728: async;
729: long isn;
730: struct PSAPctxlist *ctxlist;
731: OID defctxname;
732: struct SSAPref *ref;
733: PE *data;
734: struct QOStype *qos;
735: struct AcSAPconnect *acc;
736: struct AcSAPindication *aci;
737: \end{verbatim}\end{quote}
738: The additional parameter to this procedure is:
739: \begin{describe}
740: \item[\verb"async":] whether the association should be initiated
741: asynchronously.
742: \end{describe}
743: If the \verb"async" parameter is non-zero,
744: then \verb"AcAsynAssocRequest" returns one of four values:
745: \verb"NOTOK", which indicates that the association request failed;
746: \verb"DONE", which indicates that the association request succeeded;
747: or, either of \verb"CONNECTING_1" or \verb"CONNECTING_2", which indicates that
748: the connection request is still in
749: progress.
750: In the first two cases,
751: the usual procedures for handling return values from \verb"AcAssocRequest" are
752: employed
753: (i.e., a \verb"NOTOK" return from \verb"AcAsynAssocRequest" is equivalent to a
754: \verb"NOTOK" return from \verb"AcAssocRequest", and,
755: a \verb"DONE" return from \verb"AcAsynAssocRequest" is equivalent to a
756: \verb"OK" return from \verb"AcAssocRequest").
757:
758: In the final case, when either \verb"CONNECTING_1" or
759: \verb"CONNECTING_2" is returned,
760: only the \verb"acc_sd" element of the \verb"acc" parameter has been updated;
761: it reflects the association-descriptor to be used to reference this
762: association.
763: To determine when the association attempt has been completed,
764: the routine \verb"xselect" (consult Section~\ref{acs:select})
765: should be used after calling \verb"PSelectMask".
766: In order to determine if the association attempt is successful,
767: the routine \verb"AcAsynRetryRequest" is called:
768: \begin{quote}\index{AcAsynRetryRequest}\small\begin{verbatim}
769: int AcAsynRetryRequest (sd, acc, aci)
770: int sd;
771: struct AcSAPconnect *acc;
772: struct AcSAPindication *aci;
773: \end{verbatim}\end{quote}
774: The parameters to this procedure are:
775: \begin{describe}
776: \item[\verb"sd":] the association-descriptor;
777:
778: \item[\verb"acc":] a pointer to an \verb"AcSAPconnect" structure, which is
779: updated only if the call succeeds;
780: and,
781:
782: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure, which is
783: updated only if the call fails.
784: \end{describe}
785: Again, one of three values are returned:
786: \verb"NOTOK", which indicates that the association request failed;
787: \verb"DONE", which indicates that the association request succeeded;
788: and, \verb"CONNECTING_1" or \verb"CONNECTING_2" which indicates that
789: the connection request is still in progress.
790:
791: Refer to Section~\ref{tsap:async} on page~\pageref{tsap:async} in \voltwo/
792: for information on how to make efficient use of the asynchronous connection
793: facility.
794:
795: \subsection {Association Release}
796: The \verb"AcRelRequest" routine is used to request the release of an
797: association,
798: and corresponds to a {\sf A-RELEASE.REQUEST\/} action.
799: \begin{quote}\index{AcRelRequest}\small\begin{verbatim}
800: int AcRelRequest (sd, reason, data, ndata, secs, acr, aci)
801: int sd;
802: int reason;
803: PE *data;
804: int ndata;
805: int secs;
806: struct AcSAPrelease *acr;
807: struct AcSAPindication *aci;
808: \end{verbatim}\end{quote}
809: The parameters to this procedure:
810: \begin{describe}
811: \item[\verb"sd":] the association-descriptor;
812:
813: \item[\verb"reason":] the reason why the association should be released,
814: one of:
815: \[\begin{tabular}{|l|l|}
816: \hline
817: \multicolumn{1}{|c|}{\bf Value}&
818: \multicolumn{1}{c|}{\bf Reason}\\
819: \hline
820: \tt ACF\_NORMAL& normal\\
821: \tt ACF\_URGENT& urgent\\
822: \tt ACF\_UNDEFINED& undefined\\
823: \hline
824: \end{tabular}\]
825:
826: \item[\verb"data"/\verb"ndata":] an array of final data
827: (and the number of elements in that array,
828: consult the warning on page~\pageref{AcSAPdata});
829:
830: \item[\verb"secs":] the maximum number of seconds to wait for a response
831: (use the manifest constant \verb"NOTOK" if no time-out is desired);
832:
833: \item[\verb"acr":] a pointer to an \verb"AcSAPrelease" structure,
834: which is updated only if the call succeeds;
835: and,
836:
837: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
838: which is updated only if the call fails.
839: \end{describe}
840: If the call to \verb"AcRelRequest" is successful,
841: then this corresponds to a {\sf A-RELEASE.CONFIRMATION\/} event,
842: and it returns information in the \verb"acr" parameter,
843: which is a pointer to an \verb"AcSAPrelease" structure.
844: \begin{quote}\index{AcSAPrelease}\small\begin{verbatim}
845: struct AcSAPrelease {
846: int acr_affirmative;
847:
848: int acr_reason;
849:
850: int acr_ninfo;
851: PE acr_info[NACDATA];
852: };
853: \end{verbatim}\end{quote}
854: The elements of this structure are:\label{AcSAPrelease}
855: \begin{describe}
856: \item[\verb"acr\_affirmative":] the acceptance indicator;
857:
858: \item[\verb"acr\_reason":] the reason for the indicator,
859: one of:
860: \[\begin{tabular}{|l|l|}
861: \hline
862: \multicolumn{1}{|c|}{\bf Value}&
863: \multicolumn{1}{c|}{\bf Reason}\\
864: \hline
865: \tt ACR\_NORMAL& normal\\
866: \tt ACR\_NOTFINISHED& not finished\\
867: \tt ACR\_UNDEFINED& undefined\\
868: \hline
869: \end{tabular}\]
870:
871: \item[\verb"acr\_info"/\verb"acr\_ninfo":] any final data
872: (and the length of that data).
873: \end{describe}
874: Note that the data contained in the structure was allocated via \man malloc(3),
875: and should be released by using the \verb"ACRFREE" macro when no longer
876: referenced.
877: The \verb"ACRFREE" macro,
878: behaves as if it was defined as:\label{ACRFREE}
879: \begin{quote}\index{ACRFREE}\small\begin{verbatim}
880: void ACRFREE (acr)
881: struct AcSAPrelease *acr;
882: \end{verbatim}\end{quote}
883: The macro frees only the data allocated by \verb"AcRelRequest",
884: and not the \verb"AcSAPrelease" structure itself.
885: Further,
886: \verb"ACRFREE" should be called only if the call to the \verb"AcRelRequest"
887: routine returned \verb"OK".
888:
889: If the call to \verb"AcRelRequest" is successful,
890: and the \verb"acr_affirmative" element is set,
891: then the association has been released.
892: If the call is successful,
893: but the \verb"acr_affirmative" element is not set (i.e., zero),
894: then the request to release the association has been rejected by the remote
895: user,
896: and the association is still established.
897: Otherwise the \verb"AcSAPabort" element of the \verb"AcSAPindication"
898: parameter \verb"aci" contains the reason for failure.
899:
900: Note that if a non-negative value is given to the \verb"secs" parameter and a
901: response is not received within this number of seconds,
902: then the value contained in the \verb"aca_reason" element is \verb"ACS_TIMER".
903: The user can then call the routine \verb"AcRelRetryRequest" to continue waiting
904: for a response:
905: \begin{quote}\index{AcRelRetryRequest}\small\begin{verbatim}
906: int AcRelRetryRequest (sd, secs, acr, aci)
907: int sd;
908: int secs;
909: struct AcSAPrelease *acr;
910: struct AcSAPindication *aci;
911: \end{verbatim}\end{quote}
912: The parameters to this procedure are:
913: \begin{describe}
914: \item[\verb"sd":] the association-descriptor;
915:
916: \item[\verb"secs":] the maximum number of seconds to wait for a response
917: (use the manifest constant \verb"NOTOK" if no time-out is desired);
918:
919: \item[\verb"acr":] a pointer to a \verb"AcSAPrelease" structure, which is
920: updated only if the call succeeds;
921: and,
922:
923: \item[\verb"aci":] a pointer to a \verb"AcSAPindication" structure, which is
924: updated only if the call fails.
925: \end{describe}
926: If the call to \verb"AcRelRetryRequest" is successful,
927: and the \verb"acr_affirmative" element is set,
928: then the association has been closed.
929: If the call is successful,
930: but the \verb"acr_affirmative" element is not set (i.e., zero),
931: then the request to release the assocation has been rejected by the remote
932: user, and the association is still open.
933: Otherwise the \verb"AcSAPabort" structure contained in
934: the \verb"AcSAPindication" parameter
935: \verb"aci" contains the reason for failure.
936: As expected,
937: the value \verb"ACS_TIMER" indicates that no response was received within the
938: time given by the \verb"secs" parameter.
939:
940: Upon receiving a {\sf A-RELEASE.INDICATION\/} event,
941: the user is required to generate a {\sf A-RELEASE.RESPONSE\/} action
942: using the \verb"AcRelResponse" routine.
943: \begin{quote}\index{AcRelResponse}\small\begin{verbatim}
944: int AcRelResponse (sd, status, reason, data, ndata, aci)
945: int sd;
946: int status,
947: reason;
948: PE *data;
949: int ndata;
950: struct AcSAPindication *aci;
951: \end{verbatim}\end{quote}
952: The parameters to this procedure:
953: \begin{describe}
954: \item[\verb"sd":] the association-descriptor;
955:
956: \item[\verb"status":] the acceptance indicator
957: (either \verb"ACS_ACCEPT" if the association is to be released,
958: or \verb"ACS_REJECT" otherwise);
959:
960: \item[\verb"reason":] the reason for the indicator,
961: one of:
962: \[\begin{tabular}{|l|l|}
963: \hline
964: \multicolumn{1}{|c|}{\bf Value}&
965: \multicolumn{1}{c|}{\bf Reason}\\
966: \hline
967: \tt ACR\_NORMAL& normal\\
968: \tt ACR\_NOTFINISHED& not finished\\
969: \tt ACR\_UNDEFINED& undefined\\
970: \hline
971: \end{tabular}\]
972:
973: \item[\verb"data"/\verb"ndata":] an array of final data
974: (and the number of elements in that array,
975: consult the warning on page~\pageref{AcSAPdata});
976: and,
977:
978: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
979: which is updated only if the call fails.
980: \end{describe}
981: If the call to \verb"AcRelResponse" is successful,
982: and if the \verb"result" parameter is set to \verb"ACS_ACCEPT",
983: then the association has been released.
984: If the call is successful,
985: but the \verb"result" parameter is not \verb"ACS_ACCEPT",
986: then the association remains established.
987:
988: \subsection {Association Abort}
989: To unilaterally abort an association,
990: the routine \verb"AcUAbortRequest" routine is used
991: which corresponds to the {\sf A-ABORT.REQUEST\/} action.
992: \begin{quote}\index{AcUAbortRequest}\small\begin{verbatim}
993: int AcUAbortRequest (sd, data, ndata, aci)
994: int sd;
995: PE *data;
996: int ndata;
997: struct AcSAPindication *aci;
998: \end{verbatim}\end{quote}
999: The parameters to this procedure:
1000: \begin{describe}
1001: \item[\verb"sd":] the association-descriptor;
1002:
1003: \item[\verb"data"/\verb"ndata":] an array of abort data
1004: (and the number of elements in that array,
1005: consult the warning on page~\pageref{AcSAPdata});
1006: and,
1007:
1008: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure,
1009: which is updated only if the call fails.
1010: \end{describe}
1011: If the call to \verb"AcUAbortRequest" is successful,
1012: then the association is immediately released,
1013: and any data queued for the association may be lost.
1014:
1015: \section {Association Events}
1016: Typically,
1017: the presentation service generates events which lead to the
1018: {\sf A-RELEASE.INDICATION}, {\sf A-ABORT.INDICATION},
1019: and {\sf A-P-ABORT.IN\-DI\-CA\-TION\/} events being raised.
1020: For those interested in writing application service elements which interpret
1021: this information,
1022: this section describes the necessary mappings.
1023:
1024: \subsection {Release Indication}
1025: Upon receiving a {\sf P-RELEASE.INDICATION\/} event,
1026: the routine \verb"AcFINISHser" should be called to map this into a
1027: {\sf A-RELEASE.INDICATION\/} event.
1028: \begin{quote}\index{AcFINISHser}\small\begin{verbatim}
1029: int AcFINISHser (sd, pf, aci)
1030: int sd;
1031: struct PSAPfinish *pf;
1032: struct AcSAPindication *aci;
1033: \end{verbatim}\end{quote}
1034: The parameters to this procedure:
1035: \begin{describe}
1036: \item[\verb"sd":] the association-descriptor;
1037:
1038: \item[\verb"pa":] a pointer to an \verb"PSAPfinish" structure,
1039: containing information on the presentation-level release;
1040: and,
1041:
1042: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure.
1043: \end{describe}
1044: If the call to \verb"AcFINISHser" is successful,
1045: then the \verb"aci_type" field of the \verb"aci" parameter contains the value
1046: \verb"ACI_FINISH",
1047: and an \verb"AcSAPfinish" structure is contained inside the \verb"aci"
1048: parameter.
1049: \begin{quote}\index{AcSAPfinish}\small\begin{verbatim}
1050: struct AcSAPfinish {
1051: int acf_reason;
1052:
1053: int acf_ninfo;
1054: char acf_info[NACDATA];
1055: };
1056: \end{verbatim}\end{quote}
1057: The elements of this structure are:
1058: \begin{describe}
1059: \item[\verb"acf\_reason":] the reason for the release request,
1060: one of:
1061: \[\begin{tabular}{|l|l|}
1062: \hline
1063: \multicolumn{1}{|c|}{\bf Value}&
1064: \multicolumn{1}{c|}{\bf Reason}\\
1065: \hline
1066: \tt ACF\_NORMAL& normal\\
1067: \tt ACF\_URGENT& urgent\\
1068: \tt ACF\_UNDEFINED& undefined\\
1069: \hline
1070: \end{tabular}\]
1071:
1072: \item[\verb"acf\_info"/\verb"acf\_ninfo":] any final data
1073: (and the length of that data).
1074: \end{describe}
1075: Note that the data contained in the structure was allocated via \man malloc(3),
1076: and should be released by using the \verb"ACFFREE" macro when no longer
1077: referenced.
1078: The \verb"ACFFREE" macro,
1079: behaves as if it was defined as:\label{ACFFREE}
1080: \begin{quote}\index{ACFFREE}\small\begin{verbatim}
1081: void ACFFREE (acf)
1082: struct AcSAPfinish *acf;
1083: \end{verbatim}\end{quote}
1084: The macro frees only the data allocated by \verb"AcFINISHser",
1085: and not the \verb"AcSAPfinish" structure itself.
1086: Further,
1087: \verb"ACFFREE" should be called only if the call to the \verb"AcFINISHser"
1088: routine returned \verb"OK".
1089:
1090: Otherwise,
1091: if the call fails,
1092: the \verb"aci" parameter contains information pertaining to the failure.
1093:
1094: \subsection {Abort Indication}
1095: Upon receiving a {\sf P-U-ABORT.INDICATION\/} or {\sf P-P-ABORT.INDICATION\/}
1096: event,
1097: the routine \verb"AcABORTser" should be called to map this into a
1098: {\sf A-ABORT.INDICATION\/} or {\sf A-P-ABORT.INDICATION\/} event.
1099: \begin{quote}\index{AcABORTser}\small\begin{verbatim}
1100: int AcABORTser (sd, pa, aci)
1101: int sd;
1102: struct PSAPabort *pa;
1103: struct AcSAPindication *aci;
1104: \end{verbatim}\end{quote}
1105: The parameters to this procedure:
1106: \begin{describe}
1107: \item[\verb"sd":] the association-descriptor;
1108:
1109: \item[\verb"pa":] a pointer to an \verb"PSAPabort" structure,
1110: containing information on the presentation-level abort;
1111: and,
1112:
1113: \item[\verb"aci":] a pointer to an \verb"AcSAPindication" structure.
1114: \end{describe}
1115: If the call to \verb"AcABORTser" is successful,
1116: then the \verb"aci" parameter is updated to reflect information on the abort
1117: indication.
1118: Otherwise,
1119: if the call fails,
1120: the \verb"aci" parameter contains information pertaining to the failure.
1121:
1122: \section {Select Facility}\label{acs:select}
1123: Ideally,
1124: the \man select(2) system call should be used on all descriptors,
1125: regardless of the level of abstraction
1126: (e.g., association-descriptor, presentation-descriptor, and so on).
1127: The routines with a \verb"SelectMask" suffix,
1128: such as \verb"PSelectMask"
1129: are supplied to determine if there are already queued events.
1130: These routines should always be called prior to using the select facility
1131: of the kernel.
1132: Sadly, some networking subsystems used by the software do not support
1133: \man select(2).
1134: To provide a consistent interface,
1135: the \verb"xselect" routine should be used instead of \man select(2).
1136: \begin{quote}\index{xselect}\small\begin{verbatim}
1137: int xselect (nfds, rfds, wfds, efds, secs)
1138: int nfds;
1139: fd_set *rfds,
1140: *wfds,
1141: *efds,
1142: secs;
1143: \end{verbatim}\end{quote}
1144: The parameters to this procedure are:
1145: \begin{describe}
1146: \item[\verb"nfds":] the number of descriptors present in the masks
1147: (actually the \verb"width" of descriptors from zero to the highest meaningful
1148: descriptor);
1149:
1150: \item[\verb"rfds"/\verb"wfds"/\verb"efds":] the locations of
1151: masks interested in read, write, and exception events;
1152: and,
1153:
1154: \item[\verb"secs":] the maximum number of seconds to wait for an event
1155: (a value of \verb"NOTOK" indicates that the call should block indefinitely,
1156: whereas a value of \verb"OK" indicates that the call should not block at all,
1157: e.g., a polling action).
1158: \end{describe}
1159: Unlike most routines,
1160: the \verb"xselect" routine returns one of several values:
1161: \verb"NOTOK" (on failure),
1162: \verb"OK" (if no events occurred within the time limit),
1163: or,
1164: the number of descriptors on which events occurred
1165: (the masks are updated appropriately).
1166:
1167: \section {Generic Server Dispatch}\label{acs:server}
1168: Ideally,
1169: one should write a server which can operate in one of two modes:
1170: \begin{itemize}
1171: \item Each incoming connection results in \man tsapd(8c) invoking another
1172: instance of the server; or,
1173:
1174: \item All incoming connections are given to exactly one instance of the
1175: server (the server is invoked without arguments during system
1176: initialization).
1177: \end{itemize}
1178: The choice as to which mode is used is made by the system administrator.
1179: By default,
1180: the first mode, termed the {\em dynamic\/} approach, is used.
1181: The second mode, termed the {\em static\/} approach,
1182: is described in Section~\ref{static:services} on
1183: page~\pageref{static:services}.
1184:
1185: There are several ways in which this dual-approach scheme can be realized.
1186: One such implementation is based on the routine
1187: \verb"isodeserver".\label{isodeserver}
1188: \begin{quote}\index{isodeserver}\small\begin{verbatim}
1189: int isodeserver (argc, argv, aei, initfnx, workfnx,
1190: losefnx, td)
1191: int argc;
1192: char **argv;
1193: AEI aei;
1194: IFP initfnx,
1195: workfnx,
1196: losefnx;
1197: struct TSAPdisconnect *td;
1198: \end{verbatim}\end{quote}
1199: The parameters to this procedure are:
1200: \begin{describe}
1201: \item[\verb"argc":] the length of the argument vector which the program was
1202: invoked with;
1203:
1204: \item[\verb"argv":] the argument vector which the program was invoked with;
1205:
1206: \item[\verb"aei":] the information on the application-entity offering the
1207: service;
1208:
1209: \item[\verb"initfnx":] the address of an event-handler routine to be invoked
1210: when a new connection arrives;
1211:
1212: \item[\verb"workfnx":] the address of an event-handler routine to be invoked
1213: when activity occurs on an association;
1214:
1215: \item[\verb"losefnx":] the address of an event-handler routine to be invoked
1216: if \verb"TNetAccept" (described in Section~\ref{tsap:listen}) fails
1217: and,
1218:
1219: \item[\verb"td":] a pointer to an \verb"TSAPdisconnect" structure,
1220: which is updated only if the call fails.
1221: \end{describe}
1222: If the call is successful,
1223: then the program may terminate immediately,
1224: as no work remains to be done
1225: (in the case of the single instance mode,
1226: \verb"isodeserver" returns only on error).
1227: Otherwise,
1228: the \verb"td" parameter indicates the reason for failure
1229: (consult Section~\ref{TSAPdisconnect} on page~\pageref{TSAPdisconnect}
1230: of \voltwo/).
1231:
1232: When an event associated with a new connection occurs,
1233: the event-handler routine is invoked with two parameters:
1234: \begin{quote}\small\begin{verbatim}
1235: (*initfnx) (vecp, vec);
1236: int vecp;
1237: char **vec;
1238: \end{verbatim}\end{quote}
1239: The parameters are:
1240: \begin{describe}
1241: \item[\verb"vecp":] the length of the argument vector;
1242: and,
1243:
1244: \item[\verb"vec":] the argument vector.
1245: \end{describe}
1246: The event-handler should then call \verb"AcInit" with these parameters
1247: to achieve an {\sf A-ASSOCIATION.INDICATION\/} event.
1248: If \verb"AcInit" is successful,
1249: the event-handler should decide if it wishes to honor the association
1250: and then call \verb"AcAssocResponse" with the appropriate parameters.
1251: The event-handler should return the assocation-descriptor if it accepted the
1252: association.
1253: Otherwise (or upon any errors),
1254: it should return \verb"NOTOK".
1255:
1256: When an activity associated with an association occurs,
1257: the event-handler routine is invoked with one parameter:
1258: \begin{quote}\small\begin{verbatim}
1259: (*workfnx) (fd);
1260: int fd;
1261: \end{verbatim}\end{quote}
1262: The parameter is:
1263: \begin{describe}
1264: \item[\verb"fd":] the association-descriptor of the association.
1265: \end{describe}
1266: The event-handler should then call the appropriate routine to read the next
1267: event from the association
1268: (e.g., \verb"RoWaitRequest" if remote operations are being used).
1269: The event-handler should return \verb"NOTOK" if the association is terminated
1270: or aborted,
1271: or \verb"OK" otherwise.
1272:
1273: The \verb"isodeserver" routine uses the \verb"TNetAccept" routine to
1274: wait for the next event on existing associations and for new connections.
1275: It is possible, though unlikely for a failure to occur during this operation.
1276: In this event,
1277: the event-handler routine is invoked with one parameter:
1278: \begin{quote}\small\begin{verbatim}
1279: (*losefnx) (td);
1280: struct TSAPdisconnect *td;
1281: \end{verbatim}\end{quote}
1282: The parameter is:
1283: \begin{describe}
1284: \item[\verb"td":] a pointer to an \verb"TSAPdisconnect" structure updated
1285: by \verb"TNetAccept".
1286: \end{describe}
1287: The event-handler should handle the error however it deems proper
1288: (usually by logging it and then returning).
1289:
1290: An example of this facility is presented in Section~\ref{acs:example} below.
1291:
1292: Another interface to this approach is provided for servers that may be
1293: engaged in other operations besides answering incoming calls (e.g.
1294: initiating outgoing calls too). This interface provides indentical
1295: functionality to the \verb|isodeserver| interface, but allows access
1296: to other events.
1297:
1298: The interface is provided by two calls. The first is \verb|iserver_init|.
1299: \begin{quote}\index{iserver\_init}\small\begin{verbatim}
1300: int iserver_init (argc, argv, aei, initfnx, td)
1301: int argc;
1302: char **argv;
1303: AEI aei;
1304: IFP initfnx;
1305: struct TSAPdisconnect *td;
1306: \end{verbatim}\end{quote}
1307:
1308: The parameters to this procedure are similar in part to the
1309: \verb|isodeserver| procedure:
1310: \begin{describe}
1311: \item[\verb|argc|:] the length of the argument vector which the
1312: program was invoked with;
1313:
1314: \item[\verb|argv|:] the argument vector which the program was
1315: invoked with;
1316:
1317: \item[\verb|aei|:] the information on the application-entity
1318: offering the service;
1319:
1320: \item[\verb"initfnx":] the address of an event-handler routine to be invoked
1321: when a new connection arrives, and
1322:
1323: \item[\verb|td|:] a pointer to an \verb"TSAPdisconnect" structure,
1324: which is updated only if the call fails.
1325: \end{describe}
1326:
1327: This procedure registers a listener for the address and may may call
1328: the \verb|initfnx| if the server is running in dynamic mode. If the
1329: call fails the \verb|td| parameter will indicate the reason for
1330: failure.
1331:
1332: One this function has been called, the \verb|iserver_wait| procedure
1333: should be called at regular intervals to handle incoming events,
1334: typically in a loop of some kind. It is called as follows:
1335: \begin{quote}\index{iserver\_wait}\small\begin{verbatim}
1336: int iserver_wait (initfnx, workfnx, losefnx, nfds,
1337: nfds, rfds, wfds, efds, secs, td)
1338: IFP initfnx,
1339: workfnx,
1340: losefnx;
1341: int nfds;
1342: fd_set *rfds,
1343: *wfds,
1344: *efds;
1345: int secs;
1346: struct TSAPdisconnect *td;
1347: \end{verbatim}\end{quote}
1348: The parameters to this procedure are:
1349: \begin{describe}
1350:
1351: \item[\verb"initfnx":] the address of an event-handler routine to be invoked
1352: when a new connection arrives;
1353:
1354: \item[\verb"workfnx":] the address of an event-handler routine to be invoked
1355: when activity occurs on an association;
1356:
1357: \item[\verb"losefnx":] the address of an event-handler routine to be invoked
1358: if \verb"TNetAccept" (described in Section~\ref{tsap:listen}) fails;
1359:
1360: \item[\verb|nfds/rfds/wfds/efds|:] additional
1361: association-descriptors/file descriptors to await for activity on;
1362:
1363: \item[\verb|secs|:] the maximum number of seconds to wait for
1364: activity (a value of \verb|NOTOK| indicates that the call should block
1365: indefinitely, whereas a value of \verb|OK| indicates that the call
1366: should not block at all, e.g., a polling action); and
1367:
1368: \item[\verb"td":] a pointer to an \verb"TSAPdisconnect" structure,
1369: which is updated only if the call fails.
1370: \end{describe}
1371:
1372: This routine calls the \verb|TNetAccept| routine to wait for incoming
1373: calls. It will call the procedures \verb|initfnx|, \verb|workfnx| and
1374: \verb|losefnx| in an indetical way to the \verb|isodeserver|. The
1375: routine returns on a number of conditions.
1376: \begin{itemize}
1377: \item If one of the supplied association/file descriptors registers
1378: activity the procedure returns with the mask updated.
1379:
1380: \item If an incoming association occurs. It should be accepted or
1381: rejected by the \verb|initfnx| then the procedure will return.
1382:
1383: \item If some activity happens on one of the accepted calls. This is
1384: handled by the \verb|workfnx| then the procedure will return.
1385:
1386: \item If the time given runs out, the procedure will return.
1387: \end{itemize}
1388:
1389: An outline usage of these procedures might be something like:
1390: \begin{quote}\small\begin{verbatim}
1391: if (iserver_init (argc, argv, aei, ros_init, td) == NOTOK)
1392: /* error */
1393: for (;;) {
1394: /* set up descriptors */
1395: switch (iserver_wait (ros_init, ros_work, ros_lose, nfds,
1396: &rfds, &wfds, NULLFD, timeout, td)) {
1397: case DONE:
1398: exit (0);
1399:
1400: case NOTOK:
1401: /* error */
1402:
1403: case OK:
1404: /* check fds for activitiy, do other things */
1405: }
1406: \end{verbatim}\end{quote}
1407:
1408:
1409: Please note that \verb"isodeserver" and \verb|iserver_wait| implement
1410: one possible discipline for association management. Many others are
1411: possible, depending on the needs of the service being provided.
1412: Further, note that while the text above and the example below are
1413: expressed in terms of association control (i.e., they make use of
1414: \verb"AcInit" and \verb"AcAssocResponse"), this facility will provide
1415: similar support at any other layer in the system (e.g.,
1416: \verb"isodeserver" can be used for transport or session entities).
1417:
1418: Also note that as these routines use the \verb|TNetAccept| routines,
1419: child process are collected automatically. If you wish to start child
1420: processes and wait for their exit status, you should take note of the
1421: warnings associated with the \verb|TNetAccept| procedure (see
1422: Section~\ref{tsap:accept} on page~\pageref{tsap:accept} of \voltwo/).
1423:
1424: \section {Restrictions on User Data}\label{AcSAPdata}
1425: To quote the \cite{ISO.ACS.Service} specification:
1426: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
1427: \bf NOTE:& Use of the services $\ldots$ may be subject to some
1428: constraints from (the) session services until work on
1429: providing unlimited length user data field parameters
1430: on session primitives is completed.
1431: \end{tabular}}\]
1432:
1433: \section {Error Conventions}\label{acs:errors}
1434: All of the routines in this library return the manifest constant \verb"NOTOK"
1435: on error,
1436: and also update the \verb"aci" parameter given to the routine.
1437: The \verb"aci_abort" element of the \verb"AcSAPindication" structure encodes
1438: the reason for the failure.
1439: One coerces the pointer to an \verb"AcSAPabort" structure,
1440: and consults the \verb"aca_reason" element of this latter structure.
1441: This element can be given as a parameter to the routine \verb"AcErrString"
1442: which returns a null-terminated diagnostic string.
1443: \begin{quote}\index{AcErrString}\small\begin{verbatim}
1444: char *AcErrString (c)
1445: int c;
1446: \end{verbatim}\end{quote}
1447: The \verb"" macro can be used to determine if the failure is fatal
1448: (the association has been lost).
1449: \begin{quote}\index{ACS\_FATAL}\small\begin{verbatim}
1450: int ACS_FATAL(r)
1451: int r;
1452: \end{verbatim}\end{quote}
1453: For protocol purists,
1454: the \verb"ACS_OFFICIAL" macro can be used to determine if the error is an
1455: ``official'' error as defined by the specification,
1456: or an ``unofficial'' error used by the implementation.
1457: \begin{quote}\index{ACS\_OFFICIAL}\small\begin{verbatim}
1458: int ACS_OFFICIAL (r)
1459: int r;
1460: \end{verbatim}\end{quote}
1461:
1462: \section {Compiling and Loading}
1463: Programs using the \man libacsap(3n) library should include
1464: \verb"<isode/acsap.h>".
1465: The programs should also be loaded with \verb"-lisode".
1466:
1467: \section {An Example}\label{acs:example}
1468: One example of the use of the \man libacsap(3n) library is found in
1469: Section~\ref{ros:example:server} on page~\pageref{ros:example:server}.
1470: This example is straight-forward in presenting the interaction of association
1471: control and remote operations.
1472: Now let's consider how to rewrite the server to use the facilities described
1473: above in Section~\ref{acs:server}.
1474: Instead of using an asynchronous interface,
1475: a synchronous interface will be employed.
1476: Only Figure~\ref{initROSresponder} from the example in
1477: Section~\ref{ros:example:server} need be changed.
1478:
1479: We assume that there are three exception-logging routines:
1480: {\em fatal}, which prints a diagnostic and terminates the process;
1481: {\em error}, which prints a diagnostic and then executes the statement
1482: \begin{quote}\small\begin{verbatim}
1483: longjmp (toplevel, NOTOK);
1484: \end{verbatim}\end{quote}
1485: and,
1486: {\em warn}, which simply prints a diagnostic.
1487:
1488: In Figure~\ref{doROSserver},
1489: the replacement routines are shown.
1490: First, the application-entity title for the service is deteremined.
1491: The routine \verb"isodeserver" is then called with its requisite arguments.
1492: If the routine fails, the process terminates after printing a diagnostic.
1493: Otherwise the process exits.
1494: In the case where the \man tsapd(8c) daemon invokes a new instance of
1495: the server each time an incoming connection is received,
1496: \verb"isodeserver" will return after that assocation has been released.
1497: In the case where all incoming connections are given to a single
1498: instance of the server,
1499: then \verb"isodeserver" returns only if a fatal error is detected.
1500:
1501: The routine \verb"ros_init" is called for each incoming connection.
1502: First, the ACSE state is re-captured by calling \verb"AcInit".
1503: If this succeeds,
1504: then any command line arguments are parsed.
1505: These arguments are present only if the server was invoked by
1506: the \man tsapd(8c) daemon,
1507: and are specified in the \man isoservices(5) file described in
1508: Chapter~\ref{isoservices} of \voltwo/.
1509: Assuming that the responder is satisfied with the proposed association,
1510: the routine then calls \verb"AcAssocResponse" to accept the association.
1511: Then,
1512: \verb"RoSetService" is called
1513: to set the underlying service to be used for remote operations.
1514: Finally,
1515: the association-descriptor is returned to \verb"isodeserver".
1516:
1517: The routine \verb"ros_work" is called when activity occurs on an association.
1518: The routine sets a global return vector using \man setjmp (3)
1519: and then calls \verb"RoWaitRequest" to read the next indication.
1520: This usually results in the routine \verb"ros_indication"
1521: (found in Figure~\ref{doROSresponder} on page~\pageref{doROSresponder})
1522: being called.
1523: If the association was not released,
1524: then \verb"ros_work" returns \verb"OK".
1525: Otherwise if some error occurred,
1526: use of the routine \verb"error" will cause control to return to the
1527: \verb"setjmp" call.
1528: In this case,
1529: \verb"AcUAbortRequest" is called to make sure that the association is
1530: (ungracefully) released,
1531: then \verb"NOTOK" is returned to \verb"isodeserver".
1532:
1533: The routine \verb"ros_lose" simply logs the failure of \verb"TNetAccept" when
1534: called from \verb"isodeserver".
1535: {\let\small=\scriptsize %%% yikes!
1536: \clearpage
1537: \tagrind[tp]{grind2a-2a}{The generic ROS server}{doROSserver}
1538: \clearpage
1539: \tagrind[tp]{grind2a-2b}{The generic ROS server (continued)}\empty
1540: \clearpage
1541: \tagrind[tp]{grind2a-2c}{The generic ROS server (continued)}\empty
1542: \clearpage
1543: \tagrind[tp]{grind2a-2d}{The generic ROS server (continued)}\empty}
1544:
1545: \section {For Further Reading}
1546: The ISO specification for association control services is defined in
1547: \cite{ISO.ACS.Service}.
1548: The corresponding protocol definition is \cite{ISO.ACS.Protocol}.
1549:
1550: %%% \section {Changes Since the Last Release}\label{acsap:changes}
1551: %%% A brief summary of the major changes between v~\acsaprevrsn/ and
1552: %%% v~\acsapvrsn/ are now presented.
1553: %%% These are the user-visible changes only;
1554: %%% changes of a strictly internal nature are not discussed.
1555:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.