![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ssap.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 ssap.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 {Session Services}\label{libssap}
4: The \man libssap(3n) library implements the session service.
5:
6: As with most models of OSI services,
7: the underlying assumption is one of a symmetric, asynchronous environment.
8: That is,
9: although peers exist at a given layer,
10: one does not necessary view a peer as either a client or a server.
11: Further,
12: the service provider may generate events for the service user without the
13: latter entity triggering the actions which led to the event.
14: For example,
15: in a synchronous environment,
16: an indication that data has arrived usually occurs only when the service user
17: asks the service provider to read data;
18: in an asynchronous environment,
19: the service provider may interrupt the service user at any time to announce
20: the arrival of data.
21:
22: The \verb"ssap" module in this release initially uses a client/server
23: paradigm to start communications.
24: Once the connection is established,
25: a symmetric view is taken.
26: In addition,
27: initially the interface is synchronous;
28: however once the connection is established,
29: an asynchronous interface may be selected.
30:
31: All of the routines in the \man libssap(3n) library are integer-valued.
32: They return the manifest constant \verb"OK" on success,
33: or \verb"NOTOK" otherwise.
34:
35: \section {Warning}
36: Please read the following important message.
37: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
38: \bf NOTE:& Readers of this chapter should have an intimate understanding
39: of the OSI session service. It is not the intent of this
40: chapter to present a tutorial on these services, so novice
41: users will suffer greatly if they choose to read further.
42: \end{tabular}}\]
43:
44: \section {Addresses}\label{ssap:addresses}
45: Addresses at the session service access point are represented by the
46: \verb"SSAPaddr" structure.
47: \begin{quote}\index{SSAPaddr}\small\begin{verbatim}
48: struct SSAPaddr {
49: struct TSAPaddr sa_addr;
50:
51: #define SSSIZE 64
52: int sa_selectlen;
53: char sa_selector[SSSIZE];
54: };
55: #define NULLSA ((struct SSAPaddr *) 0)
56: \end{verbatim}\end{quote}
57: This structure contains two elements:
58: \begin{describe}
59: \item[\verb"sa\_addr":] the transport address,
60: as described in Section~\ref{tsap:addresses} on page~\pageref{tsap:addresses};
61: and,
62:
63: \item[\verb"sa\_selector"/\verb"sa\_selectlen":] the session selector,
64: as described in the \man isoservices(5) database in Chapter~\ref{isoservices},
65: for the service provider \verb"ssap".
66: \end{describe}
67:
68: In Figure~\ref{getASprovider},
69: an example of how one constructs the SSAP address for the Presentation provider
70: on host \verb"RemoteHost" is presented.
71: The routine \verb"is2saddr" takes a host and service,
72: and then consults the \man isoentities(5) file described in
73: Chapter~\ref{isoentities} of \volone/ to construct a session
74: address.
75: \begin{quote}\index{is2saddr}\small\begin{verbatim}
76: struct SSAPaddr *is2saddr (host, service, is)
77: char *host,
78: *service;
79: struct isoservent *is;
80: \end{verbatim}\end{quote}
81: \tagrind[tp]{grind5b-1}%
82: {Constructing the SSAP address for the Presentation provider}%
83: {getASprovider}
84:
85: \subsection {Calling Address}
86: Certain users of the session service
87: (e.g., the reliable transfer service)
88: need to know the name of the local host when they initiate a connection.
89: The routine \verb"SLocalHostName" has been provided for this reason.
90: \begin{quote}\index{SLocalHostName}\small\begin{verbatim}
91: char *SLocalHostName ()
92: \end{verbatim}\end{quote}
93:
94: \subsection {Address Encodings}
95: It may be useful to encode a session address for viewing.
96: Although a consensus for a standard way of doing this has not yet been
97: reached,
98: the routines \verb"saddr2str" and \verb"str2saddr" may be used in the interim.
99: \begin{quote}\index{saddr2str}\small\begin{verbatim}
100: char *saddr2str (sa)
101: struct SSAPaddr *sa;
102: \end{verbatim}\end{quote}
103: The parameter to this procedure is:
104: \begin{describe}
105: \item[\verb"sa":] the session address.
106: \end{describe}
107: If \verb"saddr2str" fails,
108: it returns the manifest constant \verb"NULLCP".
109:
110: The routine \verb"str2saddr" takes an ascii string encoding and
111: returns a
112: session address.
113: \begin{quote}\index{str2saddr}\small\begin{verbatim}
114: struct SSAPaddr *str2saddr (str)
115: char *str;
116: \end{verbatim}\end{quote}
117: The parameter to this procedure is:
118: \begin{describe}
119: \item[\verb"str":] the ascii string.
120: \end{describe}
121: If \verb"str2saddr" fails,
122: it returns the manifest constant \verb"NULLSA".
123:
124: \section {Connection Establishment}
125: Until the connection has been fully established,
126: the implementation distinguishes between clients and servers,
127: which are more properly referred to as {\em initiators\/} and
128: {\em responders}, to use OSI terminology.
129:
130: \subsection {Connection Negotiation}\label{ssap:negotiation}
131: From the user's perspective,
132: there are several parameters which are negotiated by the session providers
133: during connection establishment.
134: Suggestions as to the values of some of these parameters are made by the user.
135:
136: \subsubsection {Maximum SSDU Size}
137: The session provider will accept arbitrarily large session service data units
138: (SSDUs) and transparently fragment and re-assemble them during transit.
139: Hence, the actual SSDU is of unlimited size.
140: However, for efficiency reasons,
141: it may be desirable for the user to send SSDUs which are no larger than a
142: certain threshold.
143: When a connection has been established,
144: the service providers inform the initiator and responder as to what this
145: threshold is.
146:
147: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}\label{SSDU:atomic}
148: \bf NOTE:& In the current implementation,
149: SSDUs which are no larger than the maximum atomic SSDU size
150: are handled very efficiently.
151: For optimal performance,
152: users of the session service should strive to avoid sending
153: SSDUs which are larger than this threshold.
154: \end{tabular}}\]
155:
156: \subsubsection {Session Requirements}
157: Users may specify the particular services that they will require from the
158: session provider.
159: The particular requirements supported in the current implementation are
160: listed in Table~\ref{SSAPrequirements}.
161: These requirements are always negotiated downward.
162: That is,
163: the initiator of the connection (i.e., the ``client'') indicates the
164: desired session requirements.
165: These are then given to the responder to the connection request
166: (i.e., the ``server'') who may select any (or all) of the indicated session
167: requirements.%
168: \footnote{There is one exception,
169: the responder may not select both the half- and full-duplex requirements.
170: It must choose one.
171: If the initiator selects both initially,
172: it is indicating that the choice is made at the responder's discretion.}
173: This selection is then indicated to the initiator.
174: \tagtable[tp]{5b-1}{Session Requirements}{SSAPrequirements}
175:
176: \subsubsection {Session Tokens}
177: Depending on the session requirements selected,
178: several session tokens may be available in order to coordinate the use of
179: session services.
180:
181: There are two terms commonly used when referring to a session token:
182: \begin{itemize}
183: \item Availability\\
184: If a token is available, then it exists for use during the session
185: connection.
186: The availability of a token depends on the session requirements
187: selected for the connection.
188: \item Ownership\\
189: Certain session services are may not be requested by a user unless
190: that user owns the token associated with those services.
191: \end{itemize}
192: The particular tokens supported in the current implementation,
193: along with their associated availability information are
194: listed in Table~\ref{SSAPtokens}.
195: \tagtable[tp]{5b-2}{Session Tokens}{SSAPtokens}
196:
197: The session requirements are encoded as a single integer
198: (actually, only the low-order 2~octets of an integer).
199: To determine if a token is available,
200: one can use a simple test involving the session requirements:
201: \begin{quote}\small\begin{verbatim}
202: if (requirements & SR_xxx_EXISTS) {
203: ...
204: }
205: \end{verbatim}\end{quote}
206: For example,
207: to determine if the negotiated release token is available:
208: \begin{quote}\small\begin{verbatim}
209: if (requirements & SR_RLS_EXISTS) {
210: ...
211: }
212: \end{verbatim}\end{quote}
213:
214: Finally,
215: the macro \verb"dotokens" may be used to execute {\em C\/} code for each
216: session token (regardless of availability).\index{dotokens}
217: This macro acts as if it executes:
218: \begin{quote}\index{dotoken}\small\begin{verbatim}
219: dotoken (SR_xxx_EXISTS, ST_xxx_SHIFT, ST_xxx_TOKEN, "xxx");
220: \end{verbatim}\end{quote}
221: for each token.
222: Usually,
223: \verb"dotoken" is a macro which executes some code for each token.
224: An example is provided momentarily.
225:
226: \subsubsection {Initial Token Settings}
227: For each token which is made available during connection negotiation,
228: the choice as to which user initially has the token is left to the discretion
229: of the initiator.
230: The three choices for the initial settings of a token are listed in
231: Table~\ref{SSAPsettings}.
232: \tagtable[tp]{5b-3}{Initial Token Settings}{SSAPsettings}
233:
234: The initial settings for all available tokens are encoded in a single integer
235: (actually, only the low-order 2~octets of an integer).
236: To encode a value:
237: \begin{quote}\small\begin{verbatim}
238: settings &= ~(ST_MASK << ST_yyy_SHIFT);
239: settings |= ST_xxx_VALUE << ST_yyy_SHIFT;
240: \end{verbatim}\end{quote}
241: For example,
242: to indicate that the responder of the connection is to initially have the
243: data token:
244: \begin{quote}\small\begin{verbatim}
245: settings &= ~(ST_MASK << ST_DAT_SHIFT);
246: settings |= ST_RESP_VALUE << ST_DAT_SHIFT;
247: \end{verbatim}\end{quote}
248: The first statement,
249: which clears the field in \verb"settings" by using \verb"ST_MASK",
250: is not required if \verb"settings" is initially \verb"0".
251:
252: If the initiator indicates that the initial setting of a token is left to
253: the responder's choice,
254: then the responder must decide.
255: In Figure~\ref{setINITtokens},
256: an example of the \verb"dotokens" macro is presented.
257: In this example,
258: the responder examines the initial setting for each available token,
259: and:
260: \begin{itemize}
261: \item Notes if the responder initially owns the token
262: (the \verb"ST_RESP_VALUE" case); or,
263: \item Gives ownership of the token to the initiator if the choice is
264: at the responder's discretion
265: (the \verb"ST_CALL_VALUE" case).
266: \end{itemize}
267: \tagrind[tp]{grind5b-2}{Determining the Initial Token Settings}{setINITtokens}
268:
269: \subsection {Server Initialization}
270: The \man tsapd(8c) daemon,
271: upon accepting a connection from an initiating host,
272: consults the ISO services database to determine which program
273: on the local system implements the desired TSAP entity.
274: In the case of the session service,
275: the \pgm{tsapd} program contains the bootstrap for the session provider.
276: The daemon will again consult the ISO services database to determine which
277: program on the system implements the desired SSAP entity.
278:
279: Once the program has been ascertained,
280: the daemon runs the program with any arguments listed in the database.
281: In addition,
282: it appends some {\em magic arguments\/} to the argument vector.
283: Hence,
284: the very first action performed by the responder is to re-capture the SSAP
285: state contained in the magic arguments.
286: This is done by calling the routine \verb"SInit",
287: which on a successful return,
288: is equivalent to a {\sf S-CONNECT.INDICATION\/} from the session service
289: provider.
290: \begin{quote}\index{SInit}\small\begin{verbatim}
291: int SInit (vecp, vec, ss, si)
292: int vecp;
293: char **vec;
294: struct SSAPstart *ss;
295: struct SSAPindication *si;
296: \end{verbatim}\end{quote}
297: The parameters to this procedure are:
298: \begin{describe}
299: \item[\verb"vecp":] the length of the argument vector;
300:
301: \item[\verb"vec":] the argument vector;
302:
303: \item[\verb"ss":] a pointer to a \verb"SSAPstart" structure, which is updated
304: only if the call succeeds;
305: and,
306:
307: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
308: updated only if the call fails.
309: \end{describe}
310: If \verb"SInit" is successful,
311: it returns information in the \verb"ss" parameter,
312: which is a pointer to a \verb"SSAPstart" structure.
313: \begin{quote}\index{SSAPstart}\small\begin{verbatim}
314: struct SSAPstart {
315: int ss_sd;
316:
317: struct SSAPref ss_connect;
318:
319: struct SSAPaddr ss_calling;
320: struct SSAPaddr ss_called;
321:
322: int ss_requirements;
323: int ss_settings;
324: long ss_isn;
325:
326: int ss_ssdusize;
327:
328: struct QOStype ss_qos;
329:
330: #define SS_SIZE 512
331: int ss_cc;
332: char ss_data[SS_SIZE];
333: };
334: \end{verbatim}\end{quote}
335: The elements of this structure are:
336: \begin{describe}
337: \item[\verb"ss\_sd":] the session-descriptor to be used to reference this
338: connection;
339:
340: \item[\verb"ss\_connect":] the connection identifier (a.k.a. SSAP reference)
341: used by the initiator;
342:
343: \item[\verb"ss\_calling":] the address of the peer initiating the connection;
344:
345: \item[\verb"ss\_called":] the address of the peer being asked to respond;
346:
347: \item[\verb"ss\_requirements":] the proposed session requirements;
348:
349: \item[\verb"ss\_settings":] the initial token settings;
350:
351: \item[\verb"ss\_isn":] the initial serial-number;
352:
353: \item[\verb"ss\_ssdusize":] the largest atomic SSDU size that can be used on
354: the connection (see the note on page~\pageref{SSDU:atomic});
355:
356: \item[\verb"ss\_qos":] the quality of service on the connection
357: (see Section~\ref{tsap:qos});
358: and,
359:
360: \item[\verb"ss\_data"/\verb"ss\_cc":] any initial data
361: (and the length of that data).
362: \end{describe}
363:
364: The \verb"ss_connect" element is a \verb"SSAPref" structure,
365: which is passed transparently by the session service.
366: \begin{quote}\index{SSAPref}\small\begin{verbatim}
367: struct SSAPref {
368: #define SREF_USER_SIZE 64
369: u_char sr_ulen;
370: char sr_udata[SREF_USER_SIZE];
371:
372: #define SREF_COMM_SIZE 64
373: u_char sr_clen;
374: char sr_cdata[SREF_COMM_SIZE];
375:
376: #define SREF_ADDT_SIZE 4
377: u_char sr_alen;
378: char sr_adata[SREF_ADDT_SIZE];
379:
380: u_char sr_vlen;
381: char sr_vdata[SREF_USER_SIZE];
382: };
383: \end{verbatim}\end{quote}
384: The elements of this structure are:\label{SSAPref}
385: \begin{describe}
386: \item[\verb"sr\_udata"/\verb"sr\_ulen":] the user reference (and length of
387: that reference, which may not exceed \verb"SREF_USER_SIZE" octets);
388:
389: \item[\verb"sr\_cdata"/\verb"sr\_clen":] the common reference (and length of
390: that reference, which may not exceed \verb"SREF_COMM_SIZE" octets);
391:
392: \item[\verb"sr\_adata"/\verb"sr\_adata":] the additional reference (and length
393: of that reference, which may not exceed \verb"SREF_ADDT_SIZE" octets);
394: and,
395:
396: \item[\verb"sr\_vdata"/\verb"sr\_vlen":] a second user reference (and length
397: of that reference, which may not exceed \verb"SREF_USER_SIZE" octets),
398: which is used only when starting or resuming an activity.
399: \end{describe}
400:
401: If the call to the \verb"SInit" routine is not successful,
402: then a {\sf S-P-ABORT.IN\-DI\-CA\-TION\/} event is simulated,
403: and the relevant information is returned in a \verb"SSAPindication"
404: structure.\label{SSAPindication}
405: \begin{quote}\index{SSAPindication}\small\begin{verbatim}
406: struct SSAPindication {
407: int si_type;
408: #define SI_DATA 0x00
409: #define SI_TOKEN 0x01
410: #define SI_SYNC 0x02
411: #define SI_ACTIVITY 0x03
412: #define SI_REPORT 0x04
413: #define SI_FINISH 0x05
414: #define SI_ABORT 0x06
415:
416: union {
417: struct SSAPdata si_un_data;
418: struct SSAPtoken si_un_token;
419: struct SSAPsync si_un_sync;
420: struct SSAPactivity si_un_activity;
421: struct SSAPreport si_un_report;
422: struct SSAPfinish si_un_finish;
423: struct SSAPabort si_un_abort;
424: } si_un;
425: #define si_data si_un.si_un_data
426: #define si_token si_un.si_un_token
427: #define si_sync si_un.si_un_sync
428: #define si_activity si_un.si_un_activity
429: #define si_report si_un.si_un_report
430: #define si_finish si_un.si_un_finish
431: #define si_abort si_un.si_un_abort
432: };
433: \end{verbatim}\end{quote}
434: As shown, this structure is really a discriminated union
435: (a structure with a tag element followed by a union).
436: Hence, on a failure return,
437: one first coerces a pointer to the \verb"SSAPabort" structure contained
438: therein,
439: and then consults the elements of that structure.
440: \begin{quote}\index{SSAPabort}\small\begin{verbatim}
441: struct SSAPabort {
442: int sa_peer;
443:
444: int sa_reason;
445:
446: #define SA_SIZE 512
447: int sa_cc;
448: char sa_data[SA_SIZE];
449: };
450: \end{verbatim}\end{quote}
451: The elements of a \verb"SSAPabort" structure are:
452: \begin{describe}
453: \item[\verb"sa\_peer":] if set, indicates that a user-initiated abort occurred
454: (a {\sf S-U-ABORT.INDICATION\/} event);
455: if not set, indicates that a provider-initiated abort occurred
456: (a {\sf S-P-ABORT.INDICATION\/} event);
457:
458: \item[\verb"sa\_reason":] the reason for the provider-initiated abort
459: (codes are listed in Table~\ref{SSAPreasons}),
460: meaningless if the abort is user-initiated;
461: and,
462:
463: \item[\verb"sa\_data"/\verb"sa\_cc":] any abort data (and the length of that
464: data) from the peer (if \verb"sa_peer" is set) or
465: a diagnostic string from the provider (if \verb"sa_peer" is not set).
466: \end{describe}
467: \tagtable[tp]{5b-4}{SSAP Failure Codes}{SSAPreasons}
468: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
469: \bf NOTE:& Although both \cite{ISO.SP.Protocol} and
470: \cite{CCITT.SP.Protocol} both require a maximum length
471: of \verb"9" octets for a user-initiated abort, the
472: current implementation permits up to \verb"512" octets to
473: be used. Without this freedom, higher-layer protocols
474: which use presentation encoding mechanisms would be unable
475: to successfully use the session abort facility.
476: \end{tabular}}\]
477:
478: After examining the information returned by \verb"SInit" on a successful call
479: (and possibly after examining the argument vector),
480: the responder should either accept or reject the connection.
481: For either response,
482: the responder should use
483: the \verb"SConnResponse" routine
484: (which corresponds to the {\sf S-CONNECT.RESPONSE\/} action).
485: \begin{quote}\index{SConnResponse}\small\begin{verbatim}
486: int SConnResponse (sd, ref, called, result, requirements,
487: settings, isn, data, cc, si)
488: int sd;
489: struct SSAPref *ref;
490: struct SSAPaddr *called;
491: int result,
492: requirements,
493: settings,
494: cc;
495: long isn;
496: char *data;
497: struct SSAPindication *si;
498: \end{verbatim}\end{quote}
499: The parameters to this procedure are:
500: \begin{describe}
501: \item[\verb"sd":] the session-descriptor;
502:
503: \item[\verb"ref":] the connection identifier used by the responder
504: (consult page~\pageref{SSAPref} for a description of the \verb"SSAPref"
505: structure);
506:
507: \item[\verb"called":] the SSAP address of the responder (defaulting to the
508: called address, if not present);
509:
510: \item[\verb"result":] the acceptance indicator
511: (either \verb"SC_ACCEPT" if the connection is to be accepted,
512: or one of the user-initiated abort error codes listed in
513: Table~\ref{SSAPreasons} on page~\pageref{SSAPreasons});
514:
515: \item[\verb"requirements":] the responder's session requirements
516: (this may not include any requirements not listed in the initiator's session
517: requirements);
518:
519: \item[\verb"settings":] the initial token settings
520: (for each token,
521: if the initiator specified \verb"ST_CALL_VALUE",
522: then the responder should specify either \verb"ST_INIT_VALUE" or
523: \verb"ST_RESP_VALUE";
524: instead,
525: if the initiator specified \verb"ST_INIT_VALUE",
526: and the responder wants the token,
527: it can specify the value \verb"ST_RSVD_VALUE".
528: This is interpreted by the service provider as a ``tokens please'' request;
529:
530: \item[\verb"isn":] the initial serial-number;
531:
532: \item[\verb"data"/\verb"cc":] any initial data (and the length of that data,
533: which may not exceed \verb"SC_SIZE" octets);
534: and,
535:
536: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
537: updated only if the call fails.
538: \end{describe}
539: If the call to \verb"SConnResponse" is successful,
540: and if the \verb"result" parameter is set to \verb"SC_ACCEPT",
541: then connection establishment has completed
542: and the users of the session service now operate as symmetric peers.
543: If the call is successful,
544: but the \verb"result" parameter is not \verb"SC_ACCEPT",
545: then the connection has been rejected and the responder may exit.
546: Otherwise, if the call fails and the reason is not an interface error
547: (see Table~\ref{SSAPreasons} on page~\pageref{SSAPreasons}),
548: then the connection is closed.
549:
550: Note that when the responder rejects the connection,
551: it need not supply meaningful values for the the \verb"requirements",
552: \verb"settings", and \verb"isn" parameters.
553: The \verb"data"/\verb"cc" parameters are also optional,
554: but it is recommended that the responder return some diagnostic information.
555:
556: \subsection {Client Initialization}
557: A program wishing to connect to another user of session services calls the
558: \verb"SConnRequest" routine,
559: which corresponds to the {\sf S-CONNECT.REQUEST\/} action.
560: \begin{quote}\index{SConnRequest}\small\begin{verbatim}
561: int SConnRequest (ref, calling, called, requirements,
562: settings, isn, data, cc, qos, sc, si)
563: struct SSAPref *ref;
564: struct SSAPaddr *calling,
565: *called;
566: int requirements,
567: settings,
568: cc;
569: long isn;
570: char *data;
571: struct QOStype *qos;
572: struct SSAPconnect *sc;
573: struct SSAPindication *si;
574: \end{verbatim}\end{quote}
575: The parameters to this procedure are:
576: \begin{describe}
577: \item[\verb"ref":] the connection identifier used by the initiator
578: (consult page~\pageref{SSAPref} for a description of the \verb"SSAPref"
579: structure);
580:
581: \item[\verb"calling":] the SSAP address of the responder;
582:
583: \item[\verb"called":] the SSAP address of the initiator;
584:
585: \item[\verb"requirements":] the session requirements;
586:
587: \item[\verb"settings":] the initial token settings;
588:
589: \item[\verb"isn":] the initial serial-number;
590:
591: \item[\verb"data"/\verb"cc":] any initial data (and the length of that data,
592: which may not exceed \verb"SS_SIZE" octets);
593:
594: \item[\verb"qos":] the quality of service on the connection
595: (see Section~\ref{tsap:qos});
596:
597: \item[\verb"sc":] a pointer to a \verb"SSAPconnect" structure, which is
598: updated only if the call succeeds;
599: and,
600:
601: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
602: updated only if either:
603: \begin{itemize}
604: \item the call fails;
605: or,
606:
607: \item the call succeeds,
608: but the value of the \verb"sc_result" element of the \verb"sc" parameter
609: is not \verb"SC_ACCEPT" (see below).
610: \end{itemize}
611: \end{describe}
612: If the call to \verb"SConnRequest" is successful
613: (a successful return corresponds to a {\sf S-CONNECT.CONFIRMATION\/} event),
614: then information is returned in the \verb"sc" parameter,
615: which is a pointer to a \verb"SSAPconnect" structure.
616: \begin{quote}\index{SSAPconnect}\small\begin{verbatim}
617: struct SSAPconnect {
618: int sc_sd;
619:
620: struct SSAPref sc_connect;
621:
622: struct SSAPaddr sc_responding;
623:
624: int sc_result;
625:
626: int sc_requirements;
627: int sc_settings;
628: int sc_please;
629: lnog sc_isn;
630:
631: int sc_ssdusize;
632:
633: struct QOStype sc_qos;
634:
635: #define SC_SIZE 512
636: int sc_cc;
637: char sc_data[SC_SIZE];
638: };
639: \end{verbatim}\end{quote}
640: The elements of this structure are:
641: \begin{describe}
642: \item[\verb"sc\_sd":] the session-descriptor to be used to reference this
643: connection;
644:
645: \item[\verb"sc\_connect":] the connection identifier used by the responder
646: (consult page~\pageref{SSAPref} for a description of the \verb"SSAPref"
647: structure);
648:
649: \item[\verb"sc\_responding":] the responding peer's address
650: (which is the same as the \verb"called" parameter given to
651: \verb"SConnRequest");
652:
653: \item[\verb"sc\_result":] the connection response;
654:
655: \item[\verb"sc\_requirements":] the (negotiated) session requirements;
656:
657: \item[\verb"sc\_settings":] the (negotiated) initial token settings;
658:
659: \item[\verb"sc\_please":] the tokens which the responder wants to own
660: (if any);
661:
662: \item[\verb"sc\_isn":] the (negotiated) initial serial-number;
663:
664: \item[\verb"sc\_ssdusize":] the largest atomic SSDU size that can be used on
665: the connection (see the note on page~\pageref{SSDU:atomic});
666:
667: \item[\verb"sc\_qos":] the quality of service on the connection
668: (see Section~\ref{tsap:qos});
669: and,
670:
671: \item[\verb"sc\_data"/\verb"sc\_cc":] any initial data (and the length of
672: that data).
673: \end{describe}
674: If the call to \verb"SConnRequest" is successful,
675: and the \verb"sc_result" element is set to \verb"SC_ACCEPT",
676: then connection establishment has completed and the users of the session
677: service now operate as symmetric peers.
678: If the call is successful,
679: but the \verb"sc_result" element is not \verb"SC_ACCEPT",
680: then the connection has been rejected;
681: consult Table~\ref{SSAPreasons} to determine the reason
682: (further information can be found in the \verb"si" parameter).
683: Otherwise, if the call fails then the connection is not established and the
684: \verb"SSAPabort" structure of the \verb"SSAPindication" discriminated union
685: has been updated.
686:
687: Normally \verb"SConnRequest" returns only after a connection has succeeded or
688: failed.
689: This is termed a {\em synchronous\/} connection initiation.
690: If the user desires, an {\em asynchronous\/} connection may be initiated.
691: The routine \verb"SConnRequest" is really a macro which calls the routine
692: \verb"SAsynConnRequest" with an argument indicating that a connection should
693: be attempted synchronously.
694: \begin{quote}\index{SAsynConnRequest}\small\begin{verbatim}
695: int SAsynConnRequest (ref, calling, called,
696: requirements, settings, isn, data, cc,
697: qos, sc, si, async)
698: struct SSAPref *ref;
699: struct SSAPaddr *calling,
700: *called;
701: int requirements,
702: settings,
703: cc,
704: async;
705: long isn;
706: char *data;
707: struct QOStype *qos;
708: struct SSAPconnect *sc;
709: struct SSAPindication *si;
710: \end{verbatim}\end{quote}
711: The additional parameter to this procedure is:
712: \begin{describe}
713: \item[\verb"async":] whether the connection should be initiated asynchronously.
714: \end{describe}
715: If the \verb"async" parameter is non-zero,
716: then \verb"SAsynConnRequest" returns one of four values:
717: \verb"NOTOK", which indicates that the connection request failed;
718: \verb"DONE", which indicates that the connection request succeeded;
719: or, either of \verb"CONNECTING_1" or \verb"CONNECTING_2", which indicates that
720: the connection request is still in
721: progress.
722: In the first two cases,
723: the usual procedures for handling return values from \verb"SConnRequest" are
724: employed
725: (i.e., a \verb"NOTOK" return from \verb"SAsynConnRequest" is equivalent to a
726: \verb"NOTOK" return from \verb"SConnRequest", and,
727: a \verb"DONE" return from \verb"SAsynConnRequest" is equivalent to a
728: \verb"OK" return from \verb"SConnRequest").
729: In the final case, when either \verb"CONNECTING_1" or
730: \verb"CONNECTING_2" is returned,
731: only the \verb"sc_sd" element of the \verb"sc" parameter has been updated;
732: it reflects the session-descriptor to be used to reference this connection.
733: Note that the \verb"data" parameter is still being referenced by
734: \man libssap(3n) and should not be tampered with until the connection attempt
735: has been completed.
736:
737: To determine when the connection attempt has been completed,
738: the routine \verb"xselect" (consult Section~\ref{acs:select} of \volone/)
739: should be used after calling \verb"SSelectMask".
740: In order to determine if the connection attempt is successful,
741: the \verb"SAsynRetryRequest" routine is called:
742: \begin{quote}\index{SAsynRetryRequest}\small\begin{verbatim}
743: int SAsynRetryRequest (sd, sc, si)
744: int sd;
745: struct SSAPconnect *sc;
746: struct SSAPindication *si;
747: \end{verbatim}\end{quote}
748: The parameters to this procedure are:
749: \begin{describe}
750: \item[\verb"sd":] the session-descriptor;
751:
752: \item[\verb"sc":] a pointer to a \verb"SSAPconnect" structure, which is
753: updated only if the call succeeds;
754: and,
755:
756: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
757: updated only if the call fails.
758: \end{describe}
759: Again, one of three values are returned:
760: \verb"NOTOK", which indicates that the connection request failed;
761: \verb"DONE", which indicates that the connection request succeeded;
762: and, \verb"CONNECTING_1" or \verb"CONNECTING_2" which indicates that
763: the connection request is still in progress.
764:
765: Refer to Section~\ref{tsap:async} on page~\pageref{tsap:async} for information
766: on how to make efficient use of the asynchronous connection facility.
767:
768: \section {Data Transfer}
769: Once the connection has been established,
770: a session-descriptor is used to reference the connection.
771: This is usually the first parameter given to any of the remaining routines in
772: the \man libssap(3n) library.
773: Further,
774: the last parameter is usually a pointer to a \verb"SSAPindication" structure
775: (as described on page~\pageref{SSAPindication}).
776: If a call to one of these routines fails,
777: then the structure is updated.
778: Consult the \verb"SSAPabort" element of the \verb"SSAPindication" structure.
779: If the \verb"sa_reason" element of the \verb"SSAPabort" structure is
780: associated with a fatal error,
781: then the connection is closed.
782: That is, a {\sf S-P-ABORT.INDICATION\/} event has occurred.
783: The \verb"SC_FATAL" macro can be used to determine this.
784: \begin{quote}\index{SC\_FATAL}\small\begin{verbatim}
785: int SC_FATAL (r)
786: int r;
787: \end{verbatim}\end{quote}
788: The most common interface error to occur is \verb"SC_OPERATION" which usually
789: indicates that either the user is lacking ownership of a session token
790: to perform an operation,
791: or that a session requirement required by the operation was not negotiated
792: during connection establishment.
793: For protocol purists,
794: the \verb"SC_OFFICIAL" macro can be used to determine if the error is an
795: ``official'' error as defined by the specification,
796: or an ``unofficial'' error used by the implementation.
797: \begin{quote}\index{SC\_OFFICIAL}\small\begin{verbatim}
798: int SC_OFFICIAL (r)
799: int r;
800: \end{verbatim}\end{quote}
801:
802: \subsection {Sending Data}
803: There are six routines which may be used to send data.
804: A call to the \verb"SDataRequest" routine is equivalent to a
805: {\sf S-DATA.REQUEST\/} action on the part of the user.
806: \begin{quote}\index{SDataRequest}\small\begin{verbatim}
807: int SDataRequest (sd, data, cc, si)
808: int sd;
809: char *data;
810: int cc;
811: struct SSAPindication *si;
812: \end{verbatim}\end{quote}
813: The parameters to this procedure are:
814: \begin{describe}
815: \item[\verb"sd":] the session-descriptor;
816:
817: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
818: data);
819: and,
820:
821: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
822: only if the call fails.
823: \end{describe}
824: If the call to \verb"SDataRequest" is successful,
825: then the data has been queued for sending to the peer.
826: Otherwise the \verb"SSAPabort" structure contained in
827: the \verb"SSAPindication" parameter
828: \verb"si" contains the reason for failure.
829:
830: A call to the \verb"SExpdRequest" routine is equivalent to a
831: {\sf S-EXPEDITED-DATA.REQUEST\/} action on the part of the user.
832: \begin{quote}\index{SExpdRequest}\small\begin{verbatim}
833: int SExpdRequest (sd, data, cc, si)
834: int sd;
835: char *data;
836: int cc;
837: struct SSAPindication *si;
838: \end{verbatim}\end{quote}
839: The parameters to this procedure are:
840: \begin{describe}
841: \item[\verb"sd":] the session-descriptor;
842:
843: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
844: data, which may not exceed \verb"SX_SIZE" octets);
845: and,
846:
847: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
848: only if the call fails.
849: \end{describe}
850: If the call to \verb"SExpdRequest" is successful,
851: then the data has been queued for expedited sending.
852: Otherwise the \verb"SSAPabort" element of the \verb"si" parameter
853: contains the reason for failure.
854:
855: A call to the \verb"STypedRequest" routine is equivalent to a
856: {\sf S-TYP\-ED-DA\-TA.RE\-QUEST\/} action on the part of the user.
857: \begin{quote}\index{STypedRequest}\small\begin{verbatim}
858: int STypedRequest (sd, data, cc, si)
859: int sd;
860: char *data;
861: int cc;
862: struct SSAPindication *si;
863: \end{verbatim}\end{quote}
864: The parameters to this procedure are:
865: \begin{describe}
866: \item[\verb"sd":] the session-descriptor;
867:
868: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
869: data);
870: and,
871:
872: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
873: only if the call fails.
874: \end{describe}
875: If the call to \verb"STypedRequest" is successful,
876: then the data has been queued for sending to the peer.
877: Otherwise the \verb"SSAPabort" structure contained in
878: the \verb"SSAPindication" parameter
879: \verb"si" contains the reason for failure.
880:
881: A call to the \verb"SCapdRequest" routine is equivalent to a {\sf
882: S-CAPABILITY-DATA.REQUEST\/} action on the part of the user.
883: \begin{quote}\index{SCapdRequest}\small\begin{verbatim}
884: int SCapdRequest (sd, data, cc, si)
885: int sd;
886: char *data;
887: int cc;
888: struct SSAPindication *si;
889: \end{verbatim}\end{quote}
890: The parameters to this procedure are:
891: \begin{describe}
892: \item[\verb"sd":] the session-descriptor;
893:
894: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
895: data, which may not exceed \verb"SX_CDSIZE" octets);
896: and,
897:
898: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
899: only if the call fails.
900: \end{describe}
901: If the call to \verb"SCapdRequest" is successful,
902: then the data has been queued for sending.
903: When the {\sf S-CAPABILITY-DATA.CONFIRMATION\/} event is received,
904: the data has been successfully received.
905: Otherwise the \verb"SSAPabort" structure contained in
906: the \verb"SSAPindication" parameter
907: \verb"si" contains the reason for failure.
908:
909: Upon receiving a {\sf S-CAPABILITY-DATA.INDICATION\/} event,
910: the user is required to generate a {\sf S-CAPABILITY-DATA.RESPONSE\/} action
911: using the \verb"SCapdResponse" routine.
912: \begin{quote}\index{SCapdResponse}\small\begin{verbatim}
913: int SCapdResponse (sd, data, cc, si)
914: int sd;
915: char *data;
916: int cc;
917: struct SSAPindication *si;
918: \end{verbatim}\end{quote}
919: The parameters to this procedure are:
920: \begin{describe}
921: \item[\verb"sd":] the session-descriptor;
922:
923: \item[\verb"data"/\verb"cc":] the data to be written (and the length of that
924: data, which may not exceed \verb"SX_CDASIZE" octets);
925: and,
926:
927: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
928: only if the call fails.
929: \end{describe}
930: If the call to \verb"SCapdResponse" is successful,
931: then the data has been queued for sending to the peer.
932: Otherwise the \verb"SSAPabort" structure contained in
933: the \verb"SSAPindication" parameter
934: \verb"si" contains the reason for failure.
935:
936: The \verb"SWriteRequest" routine is similar in nature to the
937: \verb"SDataRequest" and \verb"STypedRequest" routines,
938: but uses a different set of parameters.
939: The invocation is:
940: \begin{quote}\index{SWriteRequest}\small\begin{verbatim}
941: int SWriteRequest (sd, typed, uv, si)
942: int sd;
943: int typed;
944: struct udvec *uv;
945: int cc;
946: \end{verbatim}\end{quote}
947: The parameters to this procedure are:
948: \begin{describe}
949: \item[\verb"sd":] the session-descriptor;
950:
951: \item[\verb"typed":] whether this is typed-data or not;
952:
953: \item[\verb"uv":] the data to be written,
954: described in a null-terimated array of scatter/gather elements;
955: and,
956:
957: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
958: only if the call fails.
959: \end{describe}
960: If the call to \verb"SWriteRequest" is successful,
961: then the data has been queued for sending to the peer.
962: Otherwise the \verb"SSAPabort" structure contained in
963: the \verb"SSAPindication" parameter
964: \verb"si" contains the reason for failure.
965:
966: \subsection {Receiving Data}
967: There is one routine used to read data,
968: \verb"SReadRequest",
969: a call to which is equivalent to waiting for an event
970: (usually an incoming data event) to occur.
971: \begin{quote}\index{SReadRequest}\small\begin{verbatim}
972: int SReadRequest (sd, sx, secs, si)
973: int sd;
974: struct SSAPdata *sx;
975: int secs;
976: struct SSAPindication *si;
977: \end{verbatim}\end{quote}
978: The parameters to this procedure are:
979: \begin{describe}
980: \item[\verb"sd":] the session-descriptor;
981:
982: \item[\verb"sx":] a pointer to the \verb"SSAPdata" structure to be given
983: the data;
984:
985: \item[\verb"secs":] the maximum number of seconds to wait for the data
986: (a value of \verb"NOTOK" indicates that the call should block indefinitely,
987: whereas a value of \verb"OK" indicates that the call should not block at all,
988: e.g., a polling action);
989: and,
990:
991: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
992: only if data is not read.
993: \end{describe}
994: Unlike the other routines in the \man libssap(3n) library,
995: the \verb"SReadRequest" routine returns one of three values:
996: \verb"NOTOK" (on failure),
997: \verb"OK" (on reading data),
998: or
999: \verb"DONE" (otherwise).
1000:
1001: If the call to \verb"SReadRequest" returns the manifest constant \verb"OK",
1002: then the data has been read into the \verb"sx" parameter,
1003: which is a pointer to a \verb"SSAPdata" structure.
1004: \begin{quote}\index{SSAPdata}\small\begin{verbatim}
1005: struct SSAPdata {
1006: int sx_type;
1007: #define SX_NORMAL 0x00
1008: #define SX_EXPEDITED 0x01
1009: #define SX_TYPED 0x02
1010: #define SX_CAPDIND 0x03
1011: #define SX_CAPDCNF 0x04
1012:
1013: int sx_cc;
1014: struct qbuf sx_qbuf;
1015: };
1016: \end{verbatim}\end{quote}
1017: The elements of a \verb"SSAPdata" structure are:
1018: \begin{describe}
1019: \item[\verb"sx\_type":] indicates how the data was received:
1020: \[\begin{tabular}{|l|l|}
1021: \hline
1022: \multicolumn{1}{|c|}{\bf Value}&
1023: \multicolumn{1}{c|}{\bf Event}\\
1024: \hline
1025: \tt SX\_NORMAL& \sf S-DATA.INDICATION\\
1026: \tt SX\_EXPEDITED& \sf S-EXPEDITED-DATA.INDICATION\\
1027: \tt SX\_TYPED& \sf S-TYPED-DATA.INDICATION\\
1028: \tt SX\_CAPDIND& \sf S-CAPABILITY-DATA.INDICATION\\
1029: \tt SX\_CAPDCNF& \sf S-CAPABILITY-DATA.CONFIRMATION\\
1030: \hline
1031: \end{tabular}\]
1032:
1033: \item[\verb"sx\_cc":] the total number of octets that was read;
1034: and,
1035:
1036: \item[\verb"sx\_qbuf":] the data that was read in a buffer-queue form
1037: (see page~\pageref{tsap:qbuf} for a description of this structure).
1038: \end{describe}
1039: Note that the data contained in the structure was allocated via \man malloc(3),
1040: and should be released by using the \verb"SXFREE" macro when no longer
1041: referenced.
1042: The \verb"SXFREE" macro,
1043: behaves as if it was defined as:\label{SXFREE}
1044: \begin{quote}\index{SXFREE}\small\begin{verbatim}
1045: void SXFREE (sx)
1046: struct SSAPdata *sx;
1047: \end{verbatim}\end{quote}
1048: The macro frees only the data allocated by \verb"SReadRequest",
1049: and not the \verb"SSAPdata" structure itself.
1050: Further,
1051: \verb"SXFREE" should be called only if the call to the \verb"SReadRequest"
1052: routine returned \verb"OK".
1053:
1054: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
1055: \bf NOTE:& Because the \verb"SSAPdata" structure contains a
1056: \verb"qbuf" element, care must be taken in initializing
1057: and copying variables of this type.
1058: The routines in \man libssap(3n) library will correctly
1059: initialize these structures when given as parameters.
1060: But, users who otherwise manipulate these structures
1061: should take great care.
1062: \end{tabular}}\]
1063:
1064: Otherwise if the call to \verb"SReadRequest" returns the manifest constant
1065: \verb"NOTOK",
1066: then the \verb"SSAPabort" structure contained in
1067: the \verb"SSAPindication" parameter
1068: \verb"si" contains the reason for failure.
1069:
1070: If the call to \verb"SReadRequest" returns the manifest constant \verb"DONE",
1071: then some event other than data arrival has occurred.
1072: This event is encoded in the \verb"si" parameter,
1073: depending on the value of the \verb"si_type" element.
1074: When \verb"SReadRequest" returns \verb"DONE",
1075: the \verb"si_type" element may be set to one of five values:
1076: \[\begin{tabular}{|l|l|}
1077: \hline
1078: \multicolumn{1}{|c|}{\bf Value}&
1079: \multicolumn{1}{c|}{\bf Event}\\
1080: \hline
1081: \tt SI\_TOKEN& Token management\\
1082: \tt SI\_SYNC& Synchronization management\\
1083: \tt SI\_ACTIVITY& Activity management\\
1084: \tt SI\_REPORT& Exception reporting\\
1085: \tt SI\_FINISH& Connection release\\
1086: \hline
1087: \end{tabular}\]
1088:
1089: \subsubsection {Token Indications}
1090: When an event associated with token management occurs,
1091: the \verb"si_type" field of the \verb"si" parameter contains the value
1092: \verb"SI_TOKEN",
1093: and a \verb"SSAPtoken" structure is contained inside the \verb"si" parameter.
1094: \begin{quote}\index{SSAPtoken}\small\begin{verbatim}
1095: struct SSAPtoken {
1096: int st_type;
1097: #define ST_GIVE 0x00
1098: #define ST_PLEASE 0x01
1099: #define ST_CONTROL 0x02
1100:
1101: u_char st_tokens;
1102: u_char st_owned;
1103:
1104: #define ST_SIZE 512
1105: int st_cc;
1106: char st_data[ST_SIZE];
1107: };
1108: \end{verbatim}\end{quote}
1109: The elements of a \verb"SSAPtoken" structure are:
1110: \begin{describe}
1111: \item[\verb"st\_type":] defines the token management indication which
1112: occurred:
1113: \[\begin{tabular}{|l|l|}
1114: \hline
1115: \multicolumn{1}{|c|}{\bf Value}&
1116: \multicolumn{1}{c|}{\bf Event}\\
1117: \hline
1118: \tt ST\_GIVE& \sf S-TOKEN-GIVE.INDICATION\\
1119: \tt ST\_PLEASE& \sf S-TOKEN-PLEASE.INDICATION\\
1120: \tt ST\_CONTROL& \sf S-GIVE-CONTROL.INDICATION\\
1121: \hline
1122: \end{tabular}\]
1123:
1124: \item[\verb"st\_tokens":] the session tokens requested or given;
1125:
1126: \item[\verb"st\_owned":] all of the session tokens currently owned by the
1127: user;
1128: and,
1129:
1130: \item[\verb"st\_base"/\verb"st\_cc":]
1131: associated data (and the length of that data) if tokens are requested.
1132: \end{describe}
1133: It is entirely at the discretion of the user what actions are to be taken when
1134: an indication event associated with token management occurs.
1135:
1136: \subsubsection {Synchronization Indications}
1137: When an event associated with synchronization occurs,
1138: the \verb"si_type" field of the \verb"si" parameter contains the value
1139: \verb"SI_SYNC",
1140: and a \verb"SSAPsync" structure is contained inside the \verb"si" parameter.
1141: \begin{quote}\index{SSAPsync}\small\begin{verbatim}
1142: struct SSAPsync {
1143: int sn_type;
1144: #define SN_MAJORIND 0x00
1145: #define SN_MAJORCNF 0x01
1146: #define SN_MINORIND 0x02
1147: #define SN_MINORCNF 0x03
1148: #define SN_RESETIND 0x04
1149: #define SN_RESETCNF 0x05
1150:
1151: int sn_options;
1152: #define SYNC_CONFIRM 1
1153: #define SYNC_NOCONFIRM 0
1154:
1155: #define SYNC_RESTART 0
1156: #define SYNC_ABANDON 1
1157: #define SYNC_SET 2
1158:
1159: long sn_ssn;
1160: #define SERIAL_NONE (-1L)
1161: #define SERIAL_MIN 000000L
1162: #define SERIAL_MAX 999998L
1163:
1164: int sn_settings;
1165:
1166: #define SN_SIZE 512
1167: int sn_cc;
1168: char sn_data[SN_SIZE];
1169: };
1170: \end{verbatim}\end{quote}
1171: The elements of a \verb"SSAPsync" structure are:
1172: \begin{describe}
1173: \item[\verb"sn\_type":] defines the synchronization management indication
1174: which occurred:
1175: \[\begin{tabular}{|l|l|}
1176: \hline
1177: \multicolumn{1}{|c|}{\bf Value}&
1178: \multicolumn{1}{c|}{\bf Event}\\
1179: \hline
1180: \tt SN\_MAJORIND& \sf S-MAJOR-SYNC.INDICATION\\
1181: \tt SN\_MAJORCNF& \sf S-MAJOR-SYNC.CONFIRMATION\\
1182: \tt SN\_MINORIND& \sf S-MINOR-SYNC.INDICATION\\
1183: \tt SN\_MINORCNF& \sf S-MINOR-SYNC.CONFIRMATION\\
1184: \tt SN\_RESETIND& \sf S-RESYNCHRONIZE.INDICATION\\
1185: \tt SN\_RESETCNF& \sf S-RESYNCHRONIZE.CONFIRMATION\\
1186: \hline
1187: \end{tabular}\]
1188:
1189: \item[\verb"sn\_options":] various modifiers of the indication.
1190: For the minorsync indication (as described in Section~\ref{sync:mgmt}
1191: on page~\pageref{sync:mgmt}):
1192: \[\begin{tabular}{|l|l|}
1193: \hline
1194: \multicolumn{1}{|c|}{\bf Value}&
1195: \multicolumn{1}{c|}{\bf Modifier}\\
1196: \hline
1197: \tt SYNC\_CONFIRM& peer wants explicit confirmation\\
1198: \tt SYNC\_NOCONFIRM& peer doesn't want explicit confirmation\\
1199: \hline
1200: \end{tabular}\]
1201: For the resync indication (also described in Section~\ref{sync:mgmt}):
1202: \[\begin{tabular}{|l|l|}
1203: \hline
1204: \multicolumn{1}{|c|}{\bf Value}&
1205: \multicolumn{1}{c|}{\bf Modifier}\\
1206: \hline
1207: \tt SYNC\_RESTART& a ``restart'' resynchronization is requested\\
1208: \tt SYNC\_ABANDON& a ``abandon'' resynchronization is requested\\
1209: \tt SYNC\_SET& a ``set'' resynchronization is requested\\
1210: \hline
1211: \end{tabular}\]
1212:
1213: \item[\verb"sn\_ssn":] the serial-number associated with this synchronization
1214: management event;
1215:
1216: \item[\verb"sn\_settings":] for resync events,
1217: the proposed (resync indication) or new (resync confirmation) token settings;
1218: and,
1219:
1220: \item[\verb"sn\_data"/\verb"sn\_cc":] associated data
1221: (and the length of that data).
1222: \end{describe}
1223: Note that for minorsync events,
1224: the user is not obligated to confirm the synchronization point
1225: even if the originator requested it.
1226:
1227: \subsubsection {Activity Indications}
1228: When an event associated with activity management occurs,
1229: the \verb"si_type" field of the \verb"si" parameter contains the value
1230: \verb"SI_ACTIVITY",
1231: and the \verb"si" parameter contains a \verb"SSAPactivity" structure.
1232: \begin{quote}\index{SSAPactivity}\small\begin{verbatim}
1233: struct SSAPactivity {
1234: int sv_type;
1235: #define SV_START 0x00
1236: #define SV_RESUME 0x01
1237: #define SV_INTRIND 0x02
1238: #define SV_INTRCNF 0x03
1239: #define SV_DISCIND 0x04
1240: #define SV_DISCCNF 0x05
1241: #define SV_ENDIND 0x06
1242: #define SV_ENDCNF 0x07
1243:
1244: struct SSAPactid sv_id;
1245:
1246: struct SSAPactid sv_oid;
1247: struct SSAPref sv_connect;
1248:
1249: long sv_ssn;
1250:
1251: int sv_reason;
1252:
1253: #define SV_SIZE 512
1254: int sv_cc;
1255: char sv_data[SV_SIZE];
1256: };
1257: \end{verbatim}\end{quote}
1258: The elements of a \verb"SSAPactivity" structure are:
1259: \begin{describe}
1260: \item[\verb"sv\_type":] defines the activity management indication which
1261: occurred:
1262: \[\begin{tabular}{|l|l|}
1263: \hline
1264: \multicolumn{1}{|c|}{\bf Value}&
1265: \multicolumn{1}{c|}{\bf Event}\\
1266: \hline
1267: \tt SV\_START& \sf S-ACTIVITY-START.INDICATION\\
1268: \tt SV\_RESUME& \sf S-ACTIVITY-RESUME.INDICATION\\
1269: \tt SV\_INTRIND& \sf S-ACTIVITY-INTERRUPT.INDICATION\\
1270: \tt SV\_INTRCNF& \sf S-ACTIVITY-INTERRUPT.CONFIRMATION\\
1271: \tt SV\_DISCIND& \sf S-ACTIVITY-DISCARD.INDICATION\\
1272: \tt SV\_DISCCNF& \sf S-ACTIVITY-DISCARD.CONFIRMATION\\
1273: \tt SV\_ENDIND& \sf S-ACTIVITY-END.INDICATION\\
1274: \tt SV\_ENDCNF& \sf S-ACTIVITY-END.CONFIRMATION\\
1275: \hline
1276: \end{tabular}\]
1277:
1278: \item[\verb"sv\_id":] the activity identifier for an activity start
1279: or resume indication;
1280:
1281: \item[\verb"sv\_oid":] the previous activity identifier for an activity resume
1282: indication (see page~\pageref{SSAPactref});
1283:
1284: \item[\verb"sv\_connect":] the previous connection identifier for an activity
1285: resume indication;
1286:
1287: \item[\verb"sv\_ssn":] the serial-number for an activity resume or end
1288: indication;
1289:
1290: \item[\verb"sv\_reason":] the reason for an activity interrupt or discard
1291: indication (codes are listed in Table~\ref{SSAPexceptions});
1292: and,
1293:
1294: \item[\verb"sv\_data"/\verb"sv\_cc":] associated data (and the length of that
1295: data).
1296: \end{describe}
1297: \tagtable[tp]{5b-5}{SSAP Exception Codes}{SSAPexceptions}
1298:
1299: \subsubsection {Report Indications}
1300: When an event associated with exception reporting occurs,
1301: the \verb"si_type" field of the \verb"si" parameter contains the value
1302: \verb"SI_REPORT",
1303: and a \verb"SSAPreport" structure is contained inside the \verb"si"
1304: parameter.
1305: \begin{quote}\index{SSAPreport}\small\begin{verbatim}
1306: struct SSAPreport {
1307: int sp_peer;
1308:
1309: int sp_reason;
1310:
1311: #define SP_SIZE 512
1312: int sp_cc;
1313: char sp_data[SP_SIZE];
1314: };
1315: \end{verbatim}\end{quote}
1316: The elements of a \verb"SSAPreport" structure are:
1317: \begin{describe}
1318: \item[\verb"sp\_peer":] if set, indicates that a user-initiated
1319: report occurred (a {\sf S-U-EXCEPTION-REPORT.INDICATION\/} event);
1320: if not set,
1321: indicates that a provider-initiated report occurred
1322: (a {\sf S-P-EXCEPTION-REPORT.INDICATION\/} event);
1323:
1324: \item[\verb"sp\_reason":] the reason for the report
1325: (codes are listed in Table~\ref{SSAPexceptions} on
1326: page~\pageref{SSAPexceptions});
1327: and,
1328:
1329: \item[\verb"sp\_data"/\verb"sp\_cc":] any report data
1330: (and the length of that data) from the peer;
1331: meaningless if the report is provider-initiated.
1332: \end{describe}
1333:
1334: \subsubsection {Finish Indication}
1335: When a {\sf S-RELEASE.INDICATION\/} event occurs,
1336: the \verb"si_type" field of the \verb"si" parameter contains the value
1337: \verb"SI_FINISH",
1338: and a \verb"SSAPfinish" structure is contained inside the \verb"si" parameter.
1339: \begin{quote}\index{SSAPfinish}\small\begin{verbatim}
1340: struct SSAPfinish {
1341: #define SF_SIZE 512
1342: int sf_cc;
1343: char sf_data[SF_SIZE];
1344: };
1345: \end{verbatim}\end{quote}
1346: The elements of a \verb"SSAPfinish" structure are:
1347: \begin{describe}
1348: \item[\verb"sf\_data"/\verb"sf\_cc":] any final data (and the length of that
1349: data).
1350: \end{describe}
1351:
1352: \subsection {Token Management}
1353: The fundamental aspect of token management deals with transferring ownership
1354: of the tokens.
1355:
1356: \subsubsection {Sending Tokens}
1357: To transfer ownership of one or more session tokens to the remote
1358: user,
1359: the \verb"SGTokenRequest" routine is called
1360: (which corresponds to the {\sf S-TOKEN-GIVE.REQUEST\/} action).
1361: \begin{quote}\index{SGTokenRequest}\small\begin{verbatim}
1362: int SGTokenRequest (sd, tokens, si)
1363: int sd;
1364: int tokens;
1365: struct SSAPindication *si;
1366: \end{verbatim}\end{quote}
1367: The parameters to this procedure are:
1368: \begin{describe}
1369: \item[\verb"sd":] the session-descriptor;
1370:
1371: \item[\verb"tokens":] the tokens to be transferred;
1372: and,
1373:
1374: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1375: updated only if the call fails.
1376: \end{describe}
1377: If the call to \verb"SGTokenRequest" is successful,
1378: then ownership of the tokens has been transferred to the remote user.
1379:
1380: If activity management has been selected,
1381: then the ownership of all tokens can be transferred using the
1382: \verb"SGControlRequest" routine
1383: (which corresponds to the {\sf S-CONTROL-GIVE.REQUEST\/} action).
1384: \begin{quote}\index{SGControlRequest}\small\begin{verbatim}
1385: int SGControlRequest (sd, si)
1386: int sd;
1387: struct SSAPindication *si;
1388: \end{verbatim}\end{quote}
1389: The parameters to this procedure are:
1390: \begin{describe}
1391: \item[\verb"sd":] the session-descriptor;
1392: and,
1393:
1394: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1395: updated only if the call fails.
1396: \end{describe}
1397: If the call to \verb"SGControlRequest" is successful,
1398: then ownership of all available tokens has been transferred to the remote user.
1399: Until this transfer of ownership is acknowledged,
1400: other token management functions will (non-fatally) fail.
1401:
1402: \subsubsection {Requesting Tokens}
1403: To request ownership of one or more session tokens,
1404: the \verb"SPTokenRequest" routine is called
1405: (which corresponds to the {\sf S-TOKEN-PLEASE.REQUEST\/} action).
1406: \begin{quote}\index{SPTokenRequest}\small\begin{verbatim}
1407: int SPTokenRequest (sd, tokens, data, cc, si)
1408: int sd;
1409: int tokens,
1410: cc;
1411: char *data;
1412: struct SSAPindication *si;
1413: \end{verbatim}\end{quote}
1414: The parameters to this procedure are:
1415: \begin{describe}
1416: \item[\verb"sd":] the session-descriptor;
1417:
1418: \item[\verb"tokens":] the tokens to requested;
1419:
1420: \item[\verb"data"/\verb"cc":] any additional data
1421: (and the length of that data, which may not exceed \verb"ST_SIZE" octets);
1422: and,
1423:
1424: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1425: updated only if the call fails.
1426: \end{describe}
1427: If the call to \verb"SPTokenRequest" is successful,
1428: then the remote user has been notified of the request;
1429: however, the ownership of the tokens is not actually transferred until the
1430: session provider notifies the user with a {\sf S-TOKEN-GIVE-INDICATION\/}
1431: event,
1432: which typically occurs on the next call to \verb"SReadRequest".
1433:
1434: \subsection {Synchronization Management}\label{sync:mgmt}
1435: There are three types of synchronization services:
1436: majorsyncs, minorsyncs, and resyncs.
1437:
1438: \subsubsection {Major Synchronization}
1439: To indicate a major synchronization point,
1440: the \verb"SMajSyncRequest" routine is used
1441: (which corresponds to the {\sf S-MAJOR-SYNC.REQUEST\/} action).
1442: \begin{quote}\index{SMajSyncRequest}\small\begin{verbatim}
1443: int SMajSyncRequest (sd, ssn, data, cc, si)
1444: int sd;
1445: long *ssn;
1446: char *data;
1447: int cc;
1448: struct SSAPindication *si;
1449: \end{verbatim}\end{quote}
1450: The parameters to this procedure are:
1451: \begin{describe}
1452: \item[\verb"sd":] the session-descriptor;
1453:
1454: \item[\verb"ssn":] a pointer to a long integer which,
1455: on a successful return,
1456: will be updated to reflect the current serial-number ($V(M)-1$);
1457:
1458: \item[\verb"data"/\verb"cc":] any additional data
1459: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
1460: and,
1461:
1462: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1463: updated only if the call fails.
1464: \end{describe}
1465: If the call to \verb"SMajSyncRequest" is successful,
1466: then the major synchronization has been queued for the remote user.
1467: When the {\sf S-MAJOR-SYNC.CON\-FIR\-MA\-TION\/} event is received,
1468: the major synchronization is complete.
1469: Otherwise the \verb"SSAPabort" structure contained in
1470: the \verb"SSAPindication" parameter
1471: \verb"si" contains the reason for failure.
1472:
1473: Upon receiving a {\sf S-MAJOR-SYNC.INDICATION\/} event,
1474: the user is required to generate a {\sf S-MAJOR-SYNC.RESPONSE\/} action
1475: by calling the \verb"SMajSyncResponse" routine.
1476: \begin{quote}\index{SMajSyncResponse}\small\begin{verbatim}
1477: int SMajSyncResponse (sd, data, cc, si)
1478: int sd;
1479: char *data;
1480: int cc;
1481: struct SSAPindication *si;
1482: \end{verbatim}\end{quote}
1483: The parameters to this procedure are:
1484: \begin{describe}
1485: \item[\verb"sd":] the session-descriptor;
1486:
1487: \item[\verb"data"/\verb"cc":] any additional data
1488: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
1489: and,
1490:
1491: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1492: updated only if the call fails.
1493: \end{describe}
1494: If the call to \verb"SMajSyncResponse" is successful,
1495: then the major synchronization has been completed.
1496: Otherwise the \verb"SSAPabort" structure contained in
1497: the \verb"SSAPindication" parameter
1498: \verb"si" contains the reason for failure.
1499:
1500: \subsubsection {Minor Synchronization}
1501: To indicate a minor synchronization point,
1502: the \verb"SMinSyncRequest" routine is used
1503: (which corresponds to the {\sf S-MINOR-SYNC.REQUEST\/} action).
1504: \begin{quote}\index{SMinSyncRequest}\small\begin{verbatim}
1505: int SMinSyncRequest (sd, type, ssn, data, cc, si)
1506: int sd;
1507: int type;
1508: long *ssn;
1509: char *data;
1510: int cc;
1511: struct SSAPindication *si;
1512: \end{verbatim}\end{quote}
1513: The parameters to this procedure are:
1514: \begin{describe}
1515: \item[\verb"sd":] the session-descriptor;
1516:
1517: \item[\verb"type":] the type of minor synchronization requested,
1518: one of:
1519: \[\begin{tabular}{|l|l|}
1520: \hline
1521: \multicolumn{1}{|c|}{\bf Value}&
1522: \multicolumn{1}{c|}{\bf Type}\\
1523: \hline
1524: \tt SYNC\_CONFIRM& explicit confirmation requested\\
1525: \tt SYNC\_NOCONFIRM& no confirmation requested\\
1526: \hline
1527: \end{tabular}\]
1528:
1529: \item[\verb"ssn":] a pointer to a long integer which,
1530: on a successful return,
1531: will be updated to reflect the current serial-number ($V(M)-1$);
1532:
1533: \item[\verb"data"/\verb"cc":] any additional data
1534: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
1535: and,
1536:
1537: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1538: updated only if the call fails.
1539: \end{describe}
1540: If the call to \verb"SMinSyncRequest" is successful,
1541: then the minor synchronization has been queued for the remote user.
1542: If a {\sf S-MINOR-SYNC.CONFIRMATION\/} event is received,
1543: the minor synchronization is complete.
1544: However, the remote user is under no obligation to acknowledge the minorsync.
1545: Otherwise the \verb"SSAPabort" structure contained in
1546: the \verb"SSAPindication" parameter
1547: \verb"si" contains the reason for failure.
1548:
1549: Upon receiving a {\sf S-MINOR-SYNC.INDICATION\/} event,
1550: the user may optionally use the \verb"SMinSyncResponse" routine
1551: to generate a {\sf S-MINOR-SYNC.RESPONSE\/} action.
1552: \begin{quote}\index{SMinSyncResponse}\small\begin{verbatim}
1553: int SMinSyncResponse (sd, ssn, data, cc, si)
1554: int sd;
1555: long ssn;
1556: char *data;
1557: int cc;
1558: struct SSAPindication *si;
1559: \end{verbatim}\end{quote}
1560: The parameters to this procedure are:
1561: \begin{describe}
1562: \item[\verb"sd":] the session-descriptor;
1563:
1564: \item[\verb"ssn":] the highest serial-number being confirmed;
1565:
1566: \item[\verb"data"/\verb"cc":] any additional data
1567: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
1568: and,
1569:
1570: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1571: updated only if the call fails.
1572: \end{describe}
1573: If the call to \verb"SMinSyncResponse" is successful,
1574: then the minor synchronization has been completed.
1575: Otherwise the \verb"SSAPabort" structure contained in
1576: the \verb"SSAPindication" parameter
1577: \verb"si" contains the reason for failure.
1578:
1579: \subsubsection {ReSynchronization}
1580: To resynchronize the connection to a known state,
1581: the \verb"SReSyncRequest" is used
1582: (which corresponds to the {\sf S-RESYNCHRONIZE.REQUEST\/} action).
1583: \begin{quote}\index{SReSyncRequest}\small\begin{verbatim}
1584: int SReSyncRequest (sd, type, ssn, settings, data, cc, si)
1585: int sd;
1586: int type,
1587: settings;
1588: long ssn;
1589: char *data;
1590: int cc;
1591: struct SSAPindication *si;
1592: \end{verbatim}\end{quote}
1593: The parameters to this procedure are:
1594: \begin{describe}
1595: \item[\verb"sd":] the session-descriptor;
1596:
1597: \item[\verb"type":] the type of resynchronization requested
1598: (either \verb"SYNC_RESTART", \verb"SYNC_ABANDON",
1599: or \verb"SYNC_SET");
1600:
1601: \item[\verb"ssn":] the serial-number to resynchronize to;
1602:
1603: \item[\verb"settings":] the new token settings;
1604:
1605: \item[\verb"data"/\verb"cc":] any additional data
1606: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
1607: and,
1608:
1609: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1610: updated only if the call fails.
1611: \end{describe}
1612: If the call to \verb"SReSyncRequest" is successful,
1613: then the resynchronization has been queued for the remote user.
1614: When the {\sf S-RESYNCHRONIZE.CON\-FIR\-MA\-TION\/} event is received,
1615: the resynchronization is complete.
1616: Otherwise the \verb"SSAPabort" structure contained in
1617: the \verb"SSAPindication" parameter
1618: \verb"si" contains the reason for failure.
1619:
1620: Upon receiving a {\sf S-RESYNCHRONIZE.INDICATION\/} event,
1621: the user is required to generate a {\sf S-RESYNCHRONIZE.RESPONSE\/} action
1622: using using the \verb"SReSyncResponse" routine.%
1623: \footnote{Actually,
1624: the user has other choices by using the rules of contention resolution.
1625: Consult the ISO session service specification for the gruesome details.}
1626: \begin{quote}\index{SReSyncResponse}\small\begin{verbatim}
1627: int SReSyncResponse (sd, ssn, settings, data, cc, si)
1628: int sd;
1629: int settings;
1630: long ssn;
1631: char *data;
1632: int cc;
1633: struct SSAPindication *si;
1634: \end{verbatim}\end{quote}
1635: The parameters to this procedure are:
1636: \begin{describe}
1637: \item[\verb"sd":] the session-descriptor;
1638:
1639: \item[\verb"ssn":] the serial-number to resynchronize to;
1640:
1641: \item[\verb"settings":] the new token settings;
1642:
1643: \item[\verb"data"/\verb"cc":] any additional data
1644: (and the length of that data, which may not exceed \verb"SN_SIZE" octets);
1645: and,
1646:
1647: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1648: updated only if the call fails.
1649: \end{describe}
1650:
1651: \subsection {Activity Management}
1652: There are several types of activity management services:
1653: activity start and resume,
1654: activity interrupt and discard,
1655: and activity end.
1656:
1657: \subsubsection {Activity Start/Resume}
1658: To initiate a new activity,
1659: the \verb"SActStartRequest" routine is used
1660: (which corresponds to the {\sf S-ACTIVITY-START.REQUEST\/} action).
1661: \begin{quote}\index{SActStartRequest}\small\begin{verbatim}
1662: int SActStartRequest (sd, id, data, cc, si)
1663: int sd;
1664: struct SSAPactid *id;
1665: char *data;
1666: int cc;
1667: struct SSAPindication *si;
1668: \end{verbatim}\end{quote}
1669: The parameters to this procedure are:
1670: \begin{describe}
1671: \item[\verb"sd":] the session-descriptor;
1672:
1673: \item[\verb"id":] the activity-identifier;
1674:
1675: \item[\verb"data"/\verb"cc":] any additional data
1676: (and the length of that data, which may not exceed \verb"SV_SIZE" octets);
1677: and,
1678:
1679: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1680: updated only if the call fails.
1681: \end{describe}
1682:
1683: The \verb"id" parameter is a pointer to a \verb"SSAPactid" structure,
1684: which is passed transparently by the session service.
1685: \begin{quote}\index{SSAPref}\small\begin{verbatim}
1686: struct SSAPactid {
1687: #define SID_DATA_SIZE 6
1688: u_char sd_len;
1689: char sd_data[SID_DATA_SIZE];
1690: };
1691: \end{verbatim}\end{quote}
1692: The elements of this structure are:\label{SSAPactid}
1693: \begin{describe}
1694: \item[\verb"sd\_data"/\verb"sd\_len":] the data
1695: (and length of that data, which may not exceed \verb"SID_DATA_SIZE" octets);
1696: \end{describe}
1697: If the call to the \verb"SActStartRequest" routine is successful,
1698: then the activity is started.
1699: Otherwise the \verb"SSAPabort" structure contained in
1700: the \verb"SSAPindication" parameter
1701: \verb"si" contains the reason for failure.
1702:
1703: To resume a previously interrupted activity,
1704: the \verb"SActResumeRequest" routine is used
1705: (which corresponds to the {\sf S-ACTIVITY-RESUME.REQUEST\/} action).
1706: \begin{quote}\index{SActResumeRequest}\small\begin{verbatim}
1707: int SActResumeRequest (sd, id, oid, ssn, ref, data, cc,
1708: si)
1709: int sd;
1710: struct SSAPactid *id,
1711: *oid;
1712: long ssn;
1713: struct SSAPref *ref;
1714: char *data;
1715: int cc;
1716: struct SSAPindication *si;
1717: \end{verbatim}\end{quote}
1718: The parameters to this procedure are:
1719: \begin{describe}
1720: \item[\verb"sd":] the session-descriptor;
1721:
1722: \item[\verb"id":] the activity-identifier
1723: (consult page~\pageref{SSAPactid} for a description of the \verb"SSAPactid"
1724: structure);
1725:
1726: \item[\verb"oid":] the previous activity-identifier
1727: (again, consult page~\pageref{SSAPactid});
1728:
1729: \item[\verb"ssn":] the serial-number to resume the activity at;
1730:
1731: \item[\verb"ref":] the previous connection identifier;
1732:
1733: \item[\verb"data"/\verb"cc":] any additional data
1734: (and the length of that data, which may not exceed \verb"SV_SIZE" octets);
1735: and,
1736:
1737: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1738: updated only if the call fails.
1739: \end{describe}
1740:
1741: The \verb"ref" parameter is a pointer to a \verb"SSAPref" structure.
1742: Note that unlike the connection identifiers used during connection
1743: establishment (as described on page~\pageref{SSAPref}),
1744: there are four fields:\label{SSAPactref}
1745: \[\begin{tabular}{|l|l|l|}
1746: \hline
1747: \multicolumn{1}{|c|}{\bf Field}&
1748: \multicolumn{1}{c|}{\bf Contents}&
1749: \multicolumn{1}{c|}{\bf Length}\\
1750: \hline
1751: calling SSAP user reference&
1752: \tt sr\_calling& \tt sr\_calling\_len\\
1753: called SSAP user reference&
1754: \tt sr\_called& \tt sr\_called\_len\\
1755: common reference&
1756: \tt sr\_cdata& \tt sr\_clen\\
1757: additional reference&
1758: \tt sr\_adata& \tt sr\_alen\\
1759: \hline
1760: \end{tabular}\]
1761:
1762: If the call to the \verb"SActResumeRequest" routine is successful,
1763: then the activity is resumed.
1764: Otherwise the \verb"SSAPabort" structure contained in
1765: the \verb"SSAPindication" parameter
1766: \verb"si" contains the reason for failure.
1767:
1768: \subsubsection {Activity Interrupt/Discard}
1769: To interrupt an activity in progress,
1770: the \verb"SActIntrRequest" routine is used
1771: (which corresponds to the {\sf S-ACTIVITY-INTERRUPT.REQUEST\/} action).
1772: \begin{quote}\index{SActIntrRequest}\small\begin{verbatim}
1773: int SActIntrRequest (sd, reason, si)
1774: int sd;
1775: int reason;
1776: struct SSAPindication *si;
1777: \end{verbatim}\end{quote}
1778: The parameters to this procedure are:
1779: \begin{describe}
1780: \item[\verb"sd":] the session-descriptor;
1781:
1782: \item[\verb"reason":] the reason for the interrupt
1783: (codes are listed in Table~\ref{SSAPexceptions});
1784: and,
1785:
1786: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1787: updated only if the call fails.
1788: \end{describe}
1789: If the call to \verb"SActIntrRequest" is successful,
1790: then the activity interrupt has been queued for the remote user.
1791: When the {\sf S-ACTIVITY-INTERRUPT.CON\-FIR\-MA\-TION\/} event is received,
1792: the activity interrupt is complete.
1793: Otherwise the \verb"SSAPabort" structure contained in
1794: the \verb"SSAPindication" parameter
1795: \verb"si" contains the reason for failure.
1796:
1797: Upon receiving a {\sf S-ACTIVITY-INTERRUPT.INDICATION\/} event,
1798: the user is required to generate a {\sf S-ACTIVITY-INTERRUPT.RESPONSE\/} action
1799: using the \verb"SActIntrResponse" routine.
1800: \begin{quote}\index{SActIntrResponse}\small\begin{verbatim}
1801: int SActIntrResponse (sd, si)
1802: int sd;
1803: struct SSAPindication *si;
1804: \end{verbatim}\end{quote}
1805: The parameters to this procedure are:
1806: \begin{describe}
1807: \item[\verb"sd":] the session-descriptor;
1808: and,
1809:
1810: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1811: updated only if the call fails.
1812: \end{describe}
1813: If the call to \verb"SActIntrResponse" is successful,
1814: then the activity interrupt has been completed.
1815: Otherwise the \verb"SSAPabort" structure contained in
1816: the \verb"SSAPindication" parameter
1817: \verb"si" contains the reason for failure.
1818:
1819: To discard an activity in progress,
1820: the \verb"SActDiscRequest" routine is used
1821: (which corresponds to the {\sf S-ACTIVITY-DISCARD.REQUEST\/} action).
1822: \begin{quote}\index{SActDiscRequest}\small\begin{verbatim}
1823: int SActDiscRequest (sd, reason, si)
1824: int sd;
1825: int reason;
1826: struct SSAPindication *si;
1827: \end{verbatim}\end{quote}
1828: The parameters to this procedure are:
1829: \begin{describe}
1830: \item[\verb"sd":] the session-descriptor;
1831:
1832: \item[\verb"reason":] the reason for the discard
1833: (codes are listed in Table~\ref{SSAPexceptions});
1834: and,
1835:
1836: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1837: updated only if the call fails.
1838: \end{describe}
1839: If the call to \verb"SActDiscRequest" is successful,
1840: then the activity discard has been queued for the remote user.
1841: When the {\sf S-ACTIVITY-DISCARD.CON\-FIR\-MA\-TION\/} event is received,
1842: the activity discard is complete.
1843: Otherwise the \verb"SSAPabort" structure contained in
1844: the \verb"SSAPindication" parameter
1845: \verb"si" contains the reason for failure.
1846:
1847: Upon receiving a {\sf S-ACTIVITY-DISCARD.INDICATION\/} event,
1848: the user is required to generate a {\sf S-ACTIVITY-DISCARD.RESPONSE\/} action
1849: using the \verb"SActDiscResponse" routine.
1850: \begin{quote}\index{SActDiscResponse}\small\begin{verbatim}
1851: int SActDiscResponse (sd, si)
1852: int sd;
1853: struct SSAPindication *si;
1854: \end{verbatim}\end{quote}
1855: The parameters to this procedure are:
1856: \begin{describe}
1857: \item[\verb"sd":] the session-descriptor;
1858: and,
1859:
1860: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1861: updated only if the call fails.
1862: \end{describe}
1863: If the call to \verb"SActDiscResponse" is successful,
1864: then the activity discard has been completed.
1865: Otherwise the \verb"SSAPabort" structure contained in
1866: the \verb"SSAPindication" parameter
1867: \verb"si" contains the reason for failure.
1868:
1869: \subsubsection {Activity End}
1870: To end an activity in progress,
1871: the \verb"SActEndRequest" routine is used
1872: (which corresponds to the {\sf S-ACTIVITY-END.REQUEST\/} action).
1873: \begin{quote}\index{SActEndRequest}\small\begin{verbatim}
1874: int SActEndRequest (sd, ssn, data, cc, si)
1875: int sd;
1876: long *ssn;
1877: char *data;
1878: int cc;
1879: struct SSAPindication *si;
1880: \end{verbatim}\end{quote}
1881: The parameters to this procedure are:
1882: \begin{describe}
1883: \item[\verb"sd":] the session-descriptor;
1884:
1885: \item[\verb"ssn":] a pointer to a long integer which,
1886: on a successful return,
1887: will be updated to reflect the current serial-number ($V(M)-1$);
1888:
1889: \item[\verb"data"/\verb"cc":] any additional data
1890: (and the length of that data, which may not exceed \verb"SV_SIZE" octets);
1891: and,
1892:
1893: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1894: updated only if the call fails.
1895: \end{describe}
1896: If the call to \verb"SActEndRequest" is successful,
1897: then the activity end has been queued for the remote user.
1898: When the {\sf S-ACTIVITY-END.CONFIRMATION\/} event is received,
1899: the activity end is complete.
1900: Otherwise the \verb"SSAPabort" structure contained in
1901: the \verb"SSAPindication" parameter
1902: \verb"si" contains the reason for failure.
1903:
1904: Upon receiving a {\sf S-ACTIVITY-END.INDICATION\/} event,
1905: the user is required to call the \verb"SActEndResponse" routine
1906: to generate a {\sf S-ACTIVITY-END.RESPONSE\/} action.
1907: \begin{quote}\index{SActEndResponse}\small\begin{verbatim}
1908: int SActEndResponse (sd, data, cc, si)
1909: int sd;
1910: char *data;
1911: int cc;
1912: struct SSAPindication *si;
1913: \end{verbatim}\end{quote}
1914: The parameters to this procedure are:
1915: \begin{describe}
1916: \item[\verb"sd":] the session-descriptor;
1917:
1918: \item[\verb"data"/\verb"cc":] any additional data
1919: (and the length of that data, which may not exceed \verb"SV_SIZE" octets);
1920: and,
1921:
1922: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1923: updated only if the call fails.
1924: \end{describe}
1925: If the call to \verb"SActEndResponse" is successful,
1926: then the activity end has been completed.
1927: Otherwise the \verb"SSAPabort" structure contained in
1928: the \verb"SSAPindication" parameter
1929: \verb"si" contains the reason for failure.
1930:
1931: \subsection {Exception Reporting}
1932: To report an exception and place the connection in a special error-recovery
1933: state,
1934: the \verb"SUReportRequest" routine is called
1935: (which corresponds to the {\sf S-U-EXCEPTION-REPORT.REQUEST\/} action).
1936: \begin{quote}\index{SUReportRequest}\small\begin{verbatim}
1937: int SUReportRequest (sd, reason, data, cc, si)
1938: int sd;
1939: int reason;
1940: char *data;
1941: int cc;
1942: struct SSAPindication *si;
1943: \end{verbatim}\end{quote}
1944: The parameters to this procedure are:
1945: \begin{describe}
1946: \item[\verb"sd":] the session-descriptor;
1947:
1948: \item[\verb"reason":] the reason for the report
1949: (codes are listed in Table~\ref{SSAPexceptions});
1950:
1951: \item[\verb"data"/\verb"cc":] any report data
1952: (and the length of that data, which may not exceed \verb"SP_SIZE" octets);
1953: and,
1954:
1955: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1956: updated only if the call fails.
1957: \end{describe}
1958: If the call to \verb"SUReportRequest" is successful,
1959: then the connection is placed in an error state,
1960: and any data queued for the connection may be lost until recovery is complete.
1961: Otherwise the \verb"SSAPabort" structure contained in
1962: the \verb"SSAPindication" parameter
1963: \verb"si" contains the reason for failure.
1964:
1965: Typically,
1966: error recovery can be achieved by giving away the data token or by aborting
1967: the connection (discussed next).
1968: Error recovery is discussed in greater detail in the ISO session service
1969: specification.
1970:
1971: \subsection {User-initiated Aborts}
1972: To unilaterally initiate an abort of the connection,
1973: the \verb"SUAbortRequest" routine is called
1974: (which corresponds to the {\sf S-U-ABORT.REQUEST\/} action).
1975: \begin{quote}\index{SUAbortRequest}\small\begin{verbatim}
1976: int SUAbortRequest (sd, data, cc, si)
1977: int sd;
1978: char *data;
1979: int cc;
1980: struct SSAPindication *si;
1981: \end{verbatim}\end{quote}
1982: The parameters to this procedure are:
1983: \begin{describe}
1984: \item[\verb"sd":] the session-descriptor;
1985:
1986: \item[\verb"data"/\verb"cc":] any abort data
1987: (and the length of that data, which may not exceed \verb"SA_SIZE" octets);
1988: and,
1989:
1990: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
1991: updated only if the call fails.
1992: \end{describe}
1993: If the call to \verb"SUAbortRequest" is successful,
1994: then the connection is immediately closed,
1995: and any data queued for the connection may be lost.
1996:
1997: \subsection {Asynchronous Event Handling}
1998: The data transfer events discussed thus far have been synchronous in nature.
1999: Some users of the session service may wish an asynchronous interface.
2000: The \verb"SSetIndications" routine is used to change the service associated
2001: with a session-descriptor to or from an asynchronous interface.
2002: \begin{quote}\index{SSetIndications}\small\begin{verbatim}
2003: int SSetIndications (sd, data, tokens, sync, activity,
2004: report, finish, abort, si)
2005: int sd;
2006: int (*data) (),
2007: (*tokens) (),
2008: (*sync) (),
2009: (*activity) (),
2010: (*report) (),
2011: (*finish) (),
2012: (*abort) ();
2013: struct SSAPindication *si;
2014: \end{verbatim}\end{quote}
2015: The parameters to this procedure are:
2016: \begin{describe}
2017: \item[\verb"sd":] the session-descriptor;
2018:
2019: \item[\verb"data":] the address of an event-handler routine to be invoked when
2020: data has arrived;
2021:
2022: \item[\verb"tokens":] the address of an event-handler routine to be invoked
2023: when a token management event occurs;
2024:
2025: \item[\verb"sync":] the address of an event-handler routine to be invoked
2026: when a synchronization management event occurs;
2027:
2028: \item[\verb"activity":] the address of an event-handler routine to be invoked
2029: when an activity management event occurs;
2030:
2031: \item[\verb"report":] the address of an event-handler routine to be invoked
2032: when an exception report event occurs;
2033:
2034: \item[\verb"finish":] the address of an event-handler routine to be invoked
2035: when the connection is ready to be released;
2036:
2037: \item[\verb"abort":] the address of an event-handler routine to be invoked when
2038: a user-initiated abort (a {\sf S-U-ABORT.INDICATION\/} event occurs)
2039: or a provider-initiated abort
2040: (a {\sf S-P-ABORT.INDICATION\/} event occurs);
2041: and,
2042:
2043: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
2044: only if the call fails.
2045: \end{describe}
2046: If the service is to be made asynchronous,
2047: then all event handlers are specified,
2048: otherwise,
2049: if the service is to be made synchronous,
2050: then no event handlers should be specified
2051: (use the manifest constant \verb"NULLIFP").
2052: The most likely reason for the call failing is \verb"SC_WAITING",
2053: which indicates that an event is waiting for the user.
2054:
2055: When an event-handler is invoked,
2056: future invocations of the event-hander are blocked until it returns.
2057: The return value of the event-handler is ignored.
2058: Further,
2059: during the execution of a synchronous call to the library,
2060: the event-handler will be blocked from being invoked.
2061:
2062: When an event associated with data arrival occurs,
2063: the event-handler routine is invoked with two parameters:
2064: \begin{quote}\small\begin{verbatim}
2065: (*data) (sd, sx);
2066: int sd;
2067: struct SSAPdata *sx;
2068: \end{verbatim}\end{quote}
2069: The parameters are:
2070: \begin{describe}
2071: \item[\verb"sd":] the session-descriptor;
2072: and,
2073:
2074: \item[\verb"sx":] a pointer to the \verb"SSAPdata" structure containing
2075: the data.
2076: \end{describe}
2077: Note that the data contained in the structure was allocated via \man malloc(3),
2078: and should be released with the \verb"SXFREE" macro
2079: (described on page~\pageref{SXFREE}) when no longer needed.
2080:
2081: When an event associated with token management arrives
2082: the event-handler routine is invoked with two parameters:
2083: \begin{quote}\small\begin{verbatim}
2084: (*tokens) (sd, st);
2085: int sd;
2086: struct SSAPtoken *st;
2087: \end{verbatim}\end{quote}
2088: The parameters are:
2089: \begin{describe}
2090: \item[\verb"sd":] the session-descriptor;
2091: and,
2092:
2093: \item[\verb"st":] a pointer to the \verb"SSAPtoken" structure containing
2094: the token management information.
2095: \end{describe}
2096:
2097: When an event associated with synchronization management arrives
2098: the event-handler routine is invoked with two parameters:
2099: \begin{quote}\small\begin{verbatim}
2100: (*sync) (sd, sn);
2101: int sd;
2102: struct SSAPsync *sn;
2103: \end{verbatim}\end{quote}
2104: The parameters are:
2105: \begin{describe}
2106: \item[\verb"sd":] the session-descriptor;
2107: and,
2108:
2109: \item[\verb"sn":] a pointer to the \verb"SSAPsync" structure containing
2110: the synchronization management information.
2111: \end{describe}
2112:
2113: When an event associated with activity management arrives
2114: the event-handler routine is invoked with two parameters:
2115: \begin{quote}\small\begin{verbatim}
2116: (*activity) (sd, sv);
2117: int sd;
2118: struct SSAPactivity *sv;
2119: \end{verbatim}\end{quote}
2120: The parameters are:
2121: \begin{describe}
2122: \item[\verb"sd":] the session-descriptor;
2123: and,
2124:
2125: \item[\verb"sv":] a pointer to the \verb"SSAPactivity" structure containing
2126: the activity management information.
2127: \end{describe}
2128:
2129: When an event associated with exception reporting arrives
2130: the event-handler routine is invoked with two parameters:
2131: \begin{quote}\small\begin{verbatim}
2132: (*report) (sd, sp);
2133: int sd;
2134: struct SSAPreport *sp;
2135: \end{verbatim}\end{quote}
2136: The parameters are:
2137: \begin{describe}
2138: \item[\verb"sd":] the session-descriptor;
2139: and,
2140:
2141: \item[\verb"sp":] a pointer to the \verb"SSAPreport" structure containing
2142: the exception report information.
2143: \end{describe}
2144:
2145: When an event associated with connection termination arrives
2146: the event-handler routine is invoked with two parameters:
2147: \begin{quote}\small\begin{verbatim}
2148: (*finish) (sd, sf);
2149: int sd;
2150: struct SSAPfinish *sf;
2151: \end{verbatim}\end{quote}
2152: The parameters are:
2153: \begin{describe}
2154: \item[\verb"sd":] the session-descriptor;
2155: and,
2156:
2157: \item[\verb"sf":] a pointer to the \verb"SSAPfinish" structure containing
2158: information concerning the request to terminate the connection.
2159: \end{describe}
2160:
2161: When an event associated with a user- or provider-initiated abort occurs,
2162: the event-handler is invoked with two parameters:
2163: \begin{quote}\small\begin{verbatim}
2164: (*abort) (sd, sa);
2165: int sd;
2166: struct SSAPabort *sa;
2167: \end{verbatim}\end{quote}
2168: The parameters are:
2169: \begin{describe}
2170: \item[\verb"sd":] the session-descriptor;
2171: and,
2172:
2173: \item[\verb"sa":] a pointer to the \verb"SSAPabort" structure
2174: indicating why the connection was aborted.
2175: \end{describe}
2176: Note that the session-descriptor is no longer valid at the instant the
2177: call is made.
2178:
2179: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
2180: \bf NOTE:& The \man libssap(3n) library uses the SIGEMT signal to provide
2181: these services.
2182: Programs using asynchronous session-descriptors should NOT
2183: use SIGEMT for other purposes.
2184: \end{tabular}}\]
2185:
2186: \subsection {Synchronous Event Multiplexing}
2187: A user of the session service may wish to manage multiple
2188: session-de\-scrip\-tors simultaneously;
2189: the routine \verb"SSelectMask" is provided for this purpose.
2190: This routine updates a file-descriptor mask and associated counter for use
2191: with \verb"xselect".
2192: \begin{quote}\index{SSelectMask}\small\begin{verbatim}
2193: int SSelectMask (sd, mask, nfds, si)
2194: int sd;
2195: fd_set *mask,
2196: int *nfds;
2197: struct SSAPindication *si;
2198: \end{verbatim}\end{quote}
2199: The parameters to this procedure are:
2200: \begin{describe}
2201: \item[\verb"sd":] the session-descriptor;
2202:
2203: \item[\verb"mask":] a pointer to a file-descriptor mask meaningful to
2204: \verb"xselect";
2205:
2206: \item[\verb"nfds":] a pointer to an integer-valued location meaningful to
2207: \verb"xselect";
2208: and,
2209:
2210: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
2211: only if the call fails.
2212: \end{describe}
2213: If the call is successful, then the \verb"mask" and \verb"nfds" parameters can
2214: be used as arguments to \verb"xselect".
2215: The most likely reason for the call failing is \verb"SC_WAITING",
2216: which indicates that an event is waiting for the user.
2217:
2218: If \verb"xselect" indicates that the session-descriptor is ready for reading,
2219: \verb"SReadRequest" should be called with the \verb"secs" parameter equal to
2220: \verb"OK".
2221: If the network activity does not constitute an entire event for the user,
2222: then \verb"SReadRequest" will return \verb"NOTOK" with error code
2223: \verb"SC_TIMER".
2224:
2225: \section {Connection Release}
2226: The \verb"SRelRequest" routine is used to request the release a connection,
2227: and corresponds to a {\sf S-RELEASE.REQUEST\/} action.
2228: The SSAP attempts to gracefully drain any queued data before closing
2229: the connection.
2230: \begin{quote}\index{SRelRequest}\small\begin{verbatim}
2231: int SRelRequest (sd, data, cc, secs, sr, si)
2232: int sd;
2233: char *data;
2234: int cc;
2235: int secs;
2236: struct SSAPrelease *sr;
2237: struct SSAPindication *si;
2238: \end{verbatim}\end{quote}
2239: The parameters to this procedure are:
2240: \begin{describe}
2241: \item[\verb"sd":] the session-descriptor;
2242:
2243: \item[\verb"data"/\verb"cc":] any final data
2244: (and the length of that data,
2245: which may not exceed \verb"SF_SIZE" octets);
2246:
2247: \item[\verb"secs":] the maximum number of seconds to wait for a response
2248: (use the manifest constant \verb"NOTOK" if no time-out is desired);
2249:
2250: \item[\verb"sr":] a pointer to a \verb"SSAPrelease" structure, which is updated
2251: only if the call succeeds;
2252: and,
2253:
2254: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
2255: only if the call fails.
2256: \end{describe}
2257: If the call to \verb"SRelRequest" is successful,
2258: then this corresponds to a {\sf S-RELEASE.CONFIRMATION\/} event,
2259: and it returns information in the \verb"sr" parameter,
2260: which is a pointer to a \verb"SSAPrelease" structure.
2261: \begin{quote}\index{SSAPrelease}\small\begin{verbatim}
2262: struct SSAPrelease {
2263: int sr_affirmative;
2264:
2265: #define SR_SIZE 512
2266: int sr_cc;
2267: char sr_data[SR_SIZE];
2268: };
2269: \end{verbatim}\end{quote}
2270: The elements of this structure are:
2271: \begin{describe}
2272: \item[\verb"sr\_affirmative":] the acceptance indicator;
2273: and,
2274:
2275: \item[\verb"sr\_data"/\verb"sr\_cc":] any final data
2276: (and the length of that data).
2277: \end{describe}
2278: If the call to \verb"SRelRequest" is successful,
2279: and the \verb"sr_affirmative" element is set,
2280: then the connection has been closed.
2281: If the call is successful,
2282: but the \verb"sr_affirmative" element is not set (i.e., zero),
2283: then the request to close the connection has been rejected by the remote user,
2284: and the connection is still open.
2285: Otherwise the \verb"SSAPabort" structure contained in
2286: the \verb"SSAPindication" parameter
2287: \verb"si" contains the reason for failure.
2288:
2289: Note that if a non-negative value is given to the \verb"secs" parameter and a
2290: response is not received within this number of seconds,
2291: then the value contained in the \verb"sa_reason" element is \verb"SC_TIMER".
2292: The user can then call the routine \verb"SRelRetryRequest" to continue waiting
2293: for a response:
2294: \begin{quote}\index{SRelRetryRequest}\small\begin{verbatim}
2295: int SRelRetryRequest (sd, secs, sr, si)
2296: int sd;
2297: int secs;
2298: struct SSAPrelease *sr;
2299: struct SSAPindication *si;
2300: \end{verbatim}\end{quote}
2301: The parameters to this procedure are:
2302: \begin{describe}
2303: \item[\verb"sd":] the session-descriptor;
2304:
2305: \item[\verb"secs":] the maximum number of seconds to wait for a response
2306: (use the manifest constant \verb"NOTOK" if no time-out is desired);
2307:
2308: \item[\verb"sr":] a pointer to a \verb"SSAPrelease" structure, which is updated
2309: only if the call succeeds;
2310: and,
2311:
2312: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is updated
2313: only if the call fails.
2314: \end{describe}
2315: If the call to \verb"SRelRetryRequest" is successful,
2316: and the \verb"sr_affirmative" element is set,
2317: then the connection has been closed.
2318: If the call is successful,
2319: but the \verb"sr_affirmative" element is not set (i.e., zero),
2320: then the request to close the connection has been rejected by the remote user,
2321: and the connection is still open.
2322: Otherwise the \verb"SSAPabort" structure contained in
2323: the \verb"SSAPindication" parameter
2324: \verb"si" contains the reason for failure.
2325: As expected,
2326: the value \verb"SC_TIMER" indicates that no response was received within the
2327: time given by the \verb"secs" parameter.
2328:
2329: Upon receiving a {\sf S-RELEASE.INDICATION\/} event,
2330: the user is required to generate a {\sf S-RELEASE.RESPONSE\/} action
2331: using the \verb"SRelResponse" routine.
2332: \begin{quote}\index{SRelResponse}\small\begin{verbatim}
2333: int SRelResponse (sd, status, data, cc, si)
2334: int sd;
2335: int status,
2336: cc;
2337: char *data;
2338: struct SSAPindication *si;
2339: \end{verbatim}\end{quote}
2340: The parameters to this procedure are:
2341: \begin{describe}
2342: \item[\verb"sd":] the session-descriptor;
2343:
2344: \item[\verb"status":] the acceptance indicator
2345: (either \verb"SC_ACCEPT" if the connection is to be closed,
2346: or \verb"SC_REJECTED" otherwise);
2347:
2348: \item[\verb"data"/\verb"cc":] any final data (and the length of that data,
2349: which may not exceed \verb"SR_SIZE" octets);
2350: and,
2351:
2352: \item[\verb"si":] a pointer to a \verb"SSAPindication" structure, which is
2353: updated only if the call fails.
2354: \end{describe}
2355: If the call to \verb"SRelResponse" is successful,
2356: and if the \verb"result" parameter is set to \verb"SC_ACCEPT",
2357: then the connection has been closed.
2358: If the call is successful,
2359: but the \verb"result" parameter is not \verb"SC_ACCEPT",
2360: then the connection still remains open.
2361: Note that in order to specify a value other tha \verb"SC_ACCEPT" for the
2362: \verb"result" parameter to \verb"SRelResponse",
2363: the release token must exist but must not be owned by the user making the
2364: call to \verb"SRelResponse".%
2365: \footnote{Gentle reader, we don't write the standards;
2366: we just try to implement them.}
2367:
2368: \section {Restrictions on User Data}
2369: The \man libssap(3n) contains partial support for the use of unlimited user
2370: data for session services.
2371: With the exception of the {\sf S-DATA\/} and the {\sf S-TYPED-DATA\/} services,
2372: the initial session service limited the amount of user data that could be
2373: present.
2374: With the introduction of the unlimited user data
2375: addendum\cite{ISO.SS.UserData,ISO.SP.UserData} to the session service and
2376: protocol,
2377: this restriction has been lifted.
2378:
2379: During connection establishment,
2380: the \man libssap(3n) library will attempt to negotate the use of unlimited
2381: user data.
2382: If this negotiation fails,
2383: then session services which permit user data,
2384: other than {\sf S-DATA\/} and {\sf S-TYPED-DATA},
2385: are limited to 512~octets of user data.%
2386: \footnote{Strictly speaking,
2387: the {\sf S-U-ABORT} service permits only 9~octets of user data.
2388: This limitation is unreasonable~---~upto 512~octets will be permitted.}
2389:
2390: If the negotation succeeds,
2391: then session services which permit user data,
2392: other than {\sf S-DATA\/} and {\sf S-TYPED-DATA},
2393: are limited to 65400~octets of user data,
2394: with the exception of the {\sf S-CONNECT.REQUEST\/} primitive,
2395: which is limited to 10240~octets of user data
2396: (the {\sf S-CONNECT.RESPONSE\/} primitive is limited to 65528~octets).%
2397: \footnote{Strictly speaking,
2398: the amount should be unlimited.
2399: However this full generality is not available at this time.}
2400:
2401: There is one further limitation however:
2402: although the initiator of a connection can send upto 10240~octets,
2403: due to limitations in the \unix/ kernel,
2404: if the \man tsapd(8c) is dispatching based on session selector,
2405: then a responder can accept upto approximately 1536~octets.
2406: To avoid this problem,
2407: have \man tsapd(8c) dispatch based on transport selector
2408: (see Section~\ref{service:standard} in \volone/).
2409:
2410: \section {Error Conventions}
2411: All of the routines in this library return the manifest constant \verb"NOTOK"
2412: on error,
2413: and also update the \verb"si" parameter given to the routine.
2414: The \verb"si_abort" element of the \verb"SSAPindication" structure contains a
2415: \verb"SSAPabort" structure detailing the reason for the failure.
2416: The \verb"sa_reason" element of this latter structure can be given as a
2417: parameter to the routine \verb"SErrString" which returns a null-terminated
2418: diagnostic string.
2419: \begin{quote}\index{SErrString}\small\begin{verbatim}
2420: char *SErrString (c)
2421: int c;
2422: \end{verbatim}\end{quote}
2423:
2424: \section {Compiling and Loading}
2425: Programs using the \man libssap(3n) library should include
2426: \verb"<isode/ssap.h>".
2427: The programs should also be loaded with \verb"-lssap" and \verb"-ltsap"
2428: (this latter library contains the routines which implement the transport
2429: services used by the session provider).
2430:
2431: \section {An Example}
2432: Let's consider how one might construct a source entity that resides on the
2433: SSAP.
2434: This entity will use a synchronous interface.
2435:
2436: There are two parts to the program:
2437: initialization and data transfer;
2438: release will occur when the standard input has been exhausted.
2439: In our example,
2440: we assume that the routine \verb"error" results in the process being
2441: terminated after printing a diagnostic.
2442:
2443: In Figure~\ref{initSSsource},
2444: the initialization steps for the source entity,
2445: including the outer {\em C\/} wrapper,
2446: is shown.
2447: First, a lookup is done in the ISO services database,
2448: and the \verb"SSAPaddr" is initialized.
2449: The \verb"SSAPref" is zeroed.
2450: Next, for each token associated with the session requirements,
2451: initial ownership of that token is claimed.
2452: Finally,
2453: the call to \verb"SConnRequest" is made.
2454: If the call is successful,
2455: a check is made to see if the remote user accepted the connection.
2456: If so,
2457: the session-descriptor is captured,
2458: along with the negotiated requirements and initial token settings.
2459:
2460: In Figure~\ref{dataSSsource} on page~\pageref{dataSSsource},
2461: the data transfer loop is realized.
2462: The source entity reads a line from the standard input,
2463: and then queues that line for sending to the remote side.
2464: When an end-of-file occurs on the standard input,
2465: the source entity requests release and then gracefully terminates.
2466: Although no checking is done in this example,
2467: for the calls to \verb"SDataRequest" and \verb"SRelRequest",
2468: on failure
2469: a check for the operational error \verb"SC_OPERATION" should be made.
2470: For \verb"SDataRequest",
2471: this would occur when the data token was not owned by the user;
2472: for \verb"SRelRequest",
2473: this would occur when the release token was not owned by the user.
2474: \clearpage
2475: \tagrind[tp]{grind5b-3a}{Initializing the SSAP source entity}{initSSsource}
2476: \clearpage
2477: \tagrind[tp]{grind5b-3b}{Initializing the SSAP source entity (continued)}\empty
2478: \clearpage
2479: \tagrind[tp]{grind5b-4}{Data Transfer for the SSAP source entity}%
2480: {dataSSsource}.
2481:
2482: \section {For Further Reading}
2483: The ISO specification for session services is defined in
2484: \cite{ISO.SP.Service},
2485: while the complementary CCITT recommendation is defined in
2486: \cite{CCITT.SP.Service}.
2487: The corresponding protocol definitions are \cite{ISO.SP.Protocol} and
2488: \cite{CCITT.SP.Protocol}, respectively.
2489:
2490: %%% \section {Changes Since the Last Release}\label{ssap:changes}
2491: %%% A brief summary of the major changes between v~\ssaprevrsn/ and
2492: %%% v~\ssapvrsn/ are now presented.
2493: %%% These are the user-visible changes only;
2494: %%% changes of a strictly internal nature are not discussed.
2495:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.