![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to libftam.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 libftam.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 {User Library}\label{libftam}
4: The \man libftam(3n) library implements the filestore-independent parts of
5: the International Standard of the OSI file service, FTAM
6: (which stands for File Transfer, Access and Management).
7: Currently supported are:
8: the no-recovery FTAM Quality-of-Service;
9: the transfer, access, management, and transfer and management service classes;
10: the kernel, read, write, access, limited file management,
11: enhanced file management, grouping, and fadu-locking functional units;
12: and, the kernel, storage, security, and private attribute groups.
13:
14: Unlike most OSI services,
15: FTAM distinguishes between the {\em initiator\/} of an FTAM association and
16: the {\em responder}.
17: However,
18: as with most models of OSI services,
19: an asynchronous environment is assumed.
20: That is,
21: the service provider may generate events for the service user without the
22: latter triggering the actions which led to the event.
23: For example,
24: in a synchronous environment,
25: an indication that data has arrived usually occurs only when the service user
26: asks the service provider to read data;
27: in an asynchronous environment,
28: the service provider may interrupt the service user at any time to announce
29: the arrival of data.
30:
31: The \verb"ftam" module in this release initially uses a synchronous interface;
32: however once the connection is established,
33: an asynchronous interface may be selected.
34:
35: All of the routines in the \man libftam(3n) library are integer-valued.
36: They return the manifest constant \verb"OK" on success,
37: or \verb"NOTOK" otherwise.
38:
39: \section {Warning}\label{ftam:note}
40: Please read the following important message.
41: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
42: \bf NOTE:& Readers of this chapter should have an intimate understanding
43: of FTAM.
44: It is not the intent of this
45: chapter to present a tutorial on these services, so novice
46: users will suffer greatly if they choose to read further.
47:
48: As previous versions of this software included an
49: implementation of DIS FTAM, and the release contains an IS
50: implementation, users of the \man libftam(3n) library
51: are urged to re-read this chapter.
52: \end{tabular}}\]
53:
54: \section {Constants}
55: There are several important constants, described below:
56:
57: \subsection {FTAM Quality-of-Service}
58: \[\begin{tabular}{|l|l|}
59: \hline
60: \multicolumn{1}{|c|}{\bf Value}&
61: \multicolumn{1}{c|}{\bf FTAM-QoS}\\
62: \hline
63: \tt FQOS\_NORECOVERY& no recovery\\
64: \tt FQOS\_CLASS1& class 1 recovery\\
65: \tt FQOS\_CLASS2& class 2 recovery\\
66: \tt FQOS\_CLASS3& class 3 recovery\\
67: \hline
68: \end{tabular}\]
69: Currently, only the no-recovery FTAM-QoS is supported.
70:
71: \subsection {Service Classes}
72: \[\begin{tabular}{|l|l|}
73: \hline
74: \multicolumn{1}{|c|}{\bf Value}&
75: \multicolumn{1}{c|}{\bf Service Class}\\
76: \hline
77: \tt FCLASS\_TRANSFER& transfer\\
78: \tt FCLASS\_ACCESS& access\\
79: \tt FCLASS\_MANAGE& management\\
80: \tt FCLASS\_TM& transfer and management\\
81: \tt FCLASS\_UNCONS& unconstrained\\
82: \hline
83: \end{tabular}\]
84: Currently, all service classes other than the unconstrained class are
85: supported.
86:
87: \subsection {Functional Units}
88: \[\begin{tabular}{|l|l|}
89: \hline
90: \multicolumn{1}{|c|}{\bf Value}&
91: \multicolumn{1}{c|}{\bf Functional Unit}\\
92: \hline
93: \tt FUNIT\_READ& read\\
94: \tt FUNIT\_WRITE& write\\
95: \tt FUNIT\_ACCESS& file access\\
96: \tt FUNIT\_LIMITED& limited file management\\
97: \tt FUNIT\_ENHANCED& enhanced file management\\
98: \tt FUNIT\_GROUPING& grouping\\
99: \tt FUNIT\_FADULOCK& fadu locking\\
100: \tt FUNIT\_RECOVERY& recovery\\
101: \tt FUNIT\_RESTART& restart data transfer\\
102: \hline
103: \end{tabular}\]
104: Currently, all functional units other than the
105: recovery and restart units are supported.
106: Further, the grouping unit {\em must\/} be specified.
107:
108: \subsection {Attribute Groups}
109: \[\begin{tabular}{|l|l|}
110: \hline
111: \multicolumn{1}{|c|}{\bf Value}&
112: \multicolumn{1}{c|}{\bf Attribute Group}\\
113: \hline
114: \tt FATTR\_STORAGE& storage\\
115: \tt FATTR\_SECURITY& security\\
116: \tt FATTR\_PRIVATE& private\\
117: \hline
118: \end{tabular}\]
119: Currently, all attribute groups other than the
120: private group are supported.
121:
122: \subsection {State Results}
123: \[\begin{tabular}{|l|l|}
124: \hline
125: \multicolumn{1}{|c|}{\bf Value}&
126: \multicolumn{1}{c|}{\bf State Result}\\
127: \hline
128: \tt FSTATE\_SUCCESS& success\\
129: \tt FSTATE\_FAILURE& failure\\
130: \hline
131: \end{tabular}\]
132:
133: \subsection {Action Results}
134: \[\begin{tabular}{|l|l|}
135: \hline
136: \multicolumn{1}{|c|}{\bf Value}&
137: \multicolumn{1}{c|}{\bf Action Result}\\
138: \hline
139: \tt FACTION\_SUCCESS& success\\
140: \tt FACTION\_TRANS& transient error\\
141: \tt FACTION\_PERM& permanent error\\
142: \hline
143: \end{tabular}\]
144:
145: \section {Data-Structures}
146: There are several important data structures, described below:
147:
148: \subsection {Contents Type}
149: An FTAM document type is represented by the \verb"FTAMcontent" structure.
150: \begin{quote}\index{FTAMcontent}\small\begin{verbatim}
151: struct FTAMcontent {
152: OID fc_dtn;
153:
154: int fc_id;
155: int fc_result;
156: };
157: \end{verbatim}\end{quote}
158: This elements of this structure are:
159: \begin{describe}
160: \item[\verb"fc\_dtn":] the document type name,
161: represented as an object identifier
162: (consult Section~\ref{psap:oid} of \volone/);
163:
164: \item[\verb"fc\_id":] the presentation context identifier
165: (consult Section~\ref{psap:context} of \voltwo/)
166: associated with the document type;
167: and,
168:
169: \item[\verb"fc\_result":] the status indicator for the presentation context
170: (codes are listed in Table~\ref{PSAPreasons} of \voltwo/).
171: \end{describe}
172:
173: A list of FTAM documents types is represented by the \verb"FTAMcontentlist"
174: structure.
175: \begin{quote}\index{FTAMcontentlist}\small\begin{verbatim}
176: struct FTAMcontentlist {
177: int fc_ncontent;
178:
179: #define NFCONT (NPCTX - 2)
180: struct FTAMcontent fc_contents[NFCONT];
181: };
182: \end{verbatim}\end{quote}
183: This elements of this structure are:
184: \begin{describe}
185: \item[\verb"fc\_contents"/\verb"fc\_ncontent":] the contents list
186: (and the number of contents in the list).
187: \end{describe}
188: A limitation of this implementation is that a fixed number of document types
189: may be supported,
190: as denoted by the manifest constant \verb"NFCONT".
191:
192: \subsection {Diagnostics}
193: An FTAM diagnostic is represented by the \verb"FTAMdiagnostic" structure.
194: \begin{quote}\index{FTAMcontent}\small\begin{verbatim}
195: struct FTAMdiagnostic {
196: int ftd_type;
197:
198: int ftd_identifier;
199:
200: int ftd_observer;
201: int ftd_source;
202:
203: int ftd_delay;
204:
205: #define FTD_SIZE 512
206: int ftd_cc;
207: char ftd_data[FTD_SIZE];
208: };
209: \end{verbatim}\end{quote}
210: This elements of this structure are:
211: \begin{describe}
212: \item[\verb"ftd\_type":] the diagnostic type, one of:
213: \[\begin{tabular}{|l|l|}
214: \hline
215: \multicolumn{1}{|c|}{\bf Value}&
216: \multicolumn{1}{c|}{\bf Meaning}\\
217: \hline
218: \tt DIAG\_INFORM& informative\\
219: \tt DIAG\_TRANS& transient\\
220: \tt DIAG\_PERM& permanent\\
221: \hline
222: \end{tabular}\]
223:
224: \item[\verb"ftd\_identifier":] the error-identifier
225: (consult \verb"<isode/ftam.h>" for the list,
226: there are far too many to list here);
227:
228: \item[\verb"ftd\_observer"/\verb"ftd\_source":] the observer and source of
229: the error, one of:
230: \[\begin{tabular}{|l|l|}
231: \hline
232: \multicolumn{1}{|c|}{\bf Value}&
233: \multicolumn{1}{c|}{\bf Meaning}\\
234: \hline
235: \tt EREF\_NONE& no categorization possible\\
236: \tt EREF\_IFSU& initiating file service user\\
237: \tt EREF\_IFPM& initiating file service machine\\
238: \tt EREF\_SERV& service support the file protocol machine\\
239: \tt EREF\_RFPM& responding file protocol machine\\
240: \tt EREF\_RFSU& responding file service user\\
241: \hline
242: \end{tabular}\]
243:
244: \item[\verb"ftd\_delay":] the suggested delay that might be honored prior to
245: retrying the operation (use \verb"DIAG_NODELAY" if a delay is not
246: appropriate);
247: and,
248:
249: \item[\verb"ftd\_data"/\verb"ftd\_cc":] a diagnostic string
250: (and the length of that string).
251: \end{describe}
252: A limitation of this implementation
253: is that the routines and data structures which support diagnostics have a
254: fixed limit as to the number of diagnostics permitted.
255: This is currently denoted by the manifest constant \verb"NFDIAG".
256:
257: \subsection {Charging}
258: A list of FTAM charges is represented by the \verb"FTAMcharging" structure.
259: \begin{quote}\index{FTAMcharging}\small\begin{verbatim}
260: struct FTAMcharging {
261: int fc_ncharge;
262:
263: #define NFCHRG 5
264: struct fc_charge {
265: char *fc_resource;
266: char *fc_unit;
267: int fc_value;
268: } fc_charges[NFCHRG];
269: };
270: \end{verbatim}\end{quote}
271: This elements of this structure are:
272: \begin{describe}
273: \item[\verb"fc\_charges"/\verb"fc\_ncharge":] the charging list
274: (and the number of charges in the list, which may not exceed
275: the manifest constant \verb"NFCHRG").
276: Each charge consists of:
277: \begin{describe}
278: \item[\verb"fc\_resource":] the resource identifier;
279:
280: \item[\verb"fc\_unit":] the charging unit;
281: and,
282:
283: \item[\verb"fc\_value":] the charging value.
284: \end{describe}
285: \end{describe}
286: A limitation of this implementation
287: is that a fixed number of charges may be supported,
288: as denoted by the manifest constant \verb"NFCHRG".
289:
290: \subsection {Passwords}
291: A list of FTAM passwords is represented by the \verb"FTAMpasswords" structure.
292: \begin{quote}\index{FTAMpasswords}\small\begin{verbatim}
293: struct FTAMpasswords {
294: char *fp_read;
295: int fp_readlen;
296:
297: char *fp_insert;
298: int fp_insertlen;
299:
300: char *fp_replace;
301: int fp_replacelen;
302:
303: char *fp_extend;
304: int fp_extendlen;
305:
306: char *fp_erase;
307: int fp_eraselen;
308:
309: char *fp_readattr;
310: int fp_readattrlen;
311:
312: char *fp_chngattr;
313: int fp_chngattrlen;
314:
315: char *fp_delete;
316: int fp_deletelen;
317: };
318: \end{verbatim}\end{quote}
319: This elements of this structure are:
320: \begin{describe}
321: \item[\verb"fp\_read"/\verb"fp\_readlen":] the read password
322: (and the length of the password);
323:
324: \item[\verb"fp\_insert"/\verb"fp\_insertlen":] the insert password
325: (and the length of the password);
326:
327: \item[\verb"fp\_replace"/\verb"fp\_replacelen":] the replace password
328: (and the length of the password);
329:
330: \item[\verb"fp\_extend"/\verb"fp\_extendlen":] the extend password
331: (and the length of the password);
332:
333: \item[\verb"fp\_erase"/\verb"fp\_eraselen":] the erase password
334: (and the length of the password);
335:
336: \item[\verb"fp\_readattr"/\verb"fp\_readattrlen":] the read attribute password
337: (and the length of the password);
338:
339: \item[\verb"fp\_chngattr"/\verb"fp\_chngattrlen":] the change attribute
340: password (and the length of the password);
341: and,
342:
343: \item[\verb"fp\_delete"/\verb"fp\_deletelen":] the delete password
344: (and the length of the password).
345: \end{describe}
346: The \verb"FPFREE" macro can be used to free the storage associated with an
347: \verb"FTAMpasswords" structure (without freeing the structure itself).
348: It behaves as if it was defined as:
349: \begin{quote}\index{FPFREE}\small\begin{verbatim}
350: void FPFREE (fp)
351: struct FTAMpasswords *fp;
352: \end{verbatim}\end{quote}
353:
354: \subsection {Access Control}
355: An FTAM access control element is represented by the \verb"FTAMacelement"
356: structure.
357: \begin{quote}\index{FTAMacelement}\small\begin{verbatim}
358: struct FTAMacelement {
359: int fe_actions;
360:
361: struct FTAMconcurrency fe_concurrency;
362:
363: char *fe_aet;
364:
365: struct FTAMpasswords fe_passwords;
366:
367: AEI fe_aet;
368:
369: struct FTAMacelement *fe_next;
370: };
371: \end{verbatim}\end{quote}
372: The elements of this structure are:
373: \begin{describe}
374: \item[\verb"fe\_actions":] the action list,
375: containing the inclusive-or of any of the values shown in
376: Table~\ref{FTAMaccess};
377:
378: \item[\verb"fe\_concurrency":] any concurrency-control constraints;
379:
380: \item[\verb"fe\_aet":] the user identity;
381:
382: \item[\verb"fe\_passwords"] the passwords;
383:
384: \item[\verb"fe\_aet":] the application-entity title
385: (defined in Section~\ref{acs:aei} on page~\pageref{acs:aei} in \volone/);
386: and,
387:
388: \item[\verb"fe\_next":] the next access element in the linked list.
389: \end{describe}
390: The \verb"FEFREE" macro can be used to free the storage associated with a
391: list of FTAM access elements,
392: including the head element on the list.
393: It behaves as if it was defined as:
394: \begin{quote}\index{FEFREE}\small\begin{verbatim}
395: void FEFREE (fe)
396: struct FTAMacelement *fe;
397: \end{verbatim}\end{quote}
398: \tagtable[tp]{ftam-1}{FTAM Requested Access Values}{FTAMaccess}
399:
400: \subsection {Attributes}
401: An FTAM attribute list is represented by the \verb"FTAMattributes" structure.
402: \begin{quote}\index{FTAMattributes}\small\begin{verbatim}
403: struct FTAMattributes {
404: long fa_present;
405: long fa_novalue;
406:
407: #define NFFILE 5
408: int fa_nfile;
409: char *fa_files[NFFILE];
410:
411: int fa_permitted;
412:
413: OID fa_contents;
414: PE fa_parameter;
415:
416: char *fa_account;
417:
418: struct UTCtime fa_date_create;
419: struct UTCtime fa_date_modify;
420: struct UTCtime fa_date_read;
421: struct UTCtime fa_date_attribute;
422:
423: char *fa_id_create;
424: char *fa_id_modify;
425: char *fa_id_read;
426: char *fa_id_attribute;
427:
428: int fa_availability;
429:
430: int fa_filesize;
431: int fa_futuresize;
432:
433: struct FTAMacelement fa_control;
434: char *fa_legal;
435: };
436: \end{verbatim}\end{quote}
437:
438: \newpage %%% hack
439:
440: The elements of this structure are:
441: \begin{describe}
442: \item[\verb"fa\_present":] the values present,
443: containing the inclusive-or of any of the values shown in
444: Table~\ref{FTAMattributes};
445:
446: \item[\verb"fa\_novalue":] the values which are not available are not available
447: (using the same values listed in Table~\ref{FTAMattributes},
448: the value of this element is a subset of the value of the \verb"fa_present"
449: element);
450:
451: \item[\verb"fa\_files"/\verb"fa\_nfile":] the list of filename components
452: (and the number of components, which may not exceed
453: the manifest constant \verb"NFFILE");
454:
455: \item[\verb"fa\_permitted":] permitted actions,
456: containing the inclusive-or of any of the values shown in
457: Table~\ref{FTAMaccess} on page~\pageref{FTAMaccess},
458: in addition to any of:
459: \[\begin{tabular}{|l|l|}
460: \hline
461: \multicolumn{1}{|c|}{\bf Value}&
462: \multicolumn{1}{c|}{\bf Meaning}\\
463: \hline
464: \tt FA\_PERM\_TRAV& traversal\\
465: \tt FA\_PERM\_RVTRAV& reverse-traversal\\
466: \tt FA\_PERM\_RANDOM& random-order\\
467: \hline
468: \end{tabular}\]
469:
470: \item[\verb"fa\_contents"/\verb"fa\_parameter":] the contents type;
471:
472: \item[\verb"fa\_account":] the account;
473:
474: \item[\verb"fa\_date\_create":] the date and time of creation;
475:
476: \item[\verb"fa\_date\_modify":] the date and time of last modification;
477:
478: \item[\verb"fa\_date\_read":] the date and time of last read access;
479:
480: \item[\verb"fa\_date\_attribute":] the date and time of last attribute
481: modification;
482:
483: \item[\verb"fa\_id\_create":] the identity of creator;
484:
485: \item[\verb"fa\_id\_modify":] the identity of last modifier;
486:
487: \item[\verb"fa\_id\_read":] the identity of last reader;
488:
489: \item[\verb"fa\_id\_attribute":] the identity of last attribute modifier;
490:
491: \item[\verb"fa\_availability":] file availability,
492: one of:
493: \[\begin{tabular}{|l|l|}
494: \hline
495: \multicolumn{1}{|c|}{\bf Value}&
496: \multicolumn{1}{c|}{\bf Meaning}\\
497: \hline
498: \tt FA\_AVAIL\_IMMED& immediate\\
499: \tt FA\_AVAIL\_DEFER& deferred\\
500: \hline
501: \end{tabular}\]
502:
503: \item[\verb"fa\_filesize":] filesize;
504:
505: \item[\verb"fa\_futuresize":] future filesize;
506:
507: \item[\verb"fa\_control":] access control;
508:
509: \item[\verb"fa\_encrypt":] encryption name;
510: and,
511:
512: \item[\verb"fa\_legal":] legal qualification.
513: \end{describe}
514: A limitation of this implementation
515: is that a fixed number of filename components may be supported,
516: as denoted by the manifest constant \verb"NFFILE".
517:
518: The routine \verb"FAFREE" can be used to free the storage associated with an
519: \verb"FTAMattributes" structure (without freeing the structure itself).
520: It is defined as:
521: \begin{quote}\index{FAFREE}\small\begin{verbatim}
522: void FAFREE (fa)
523: struct FTAMattributes *fa;
524: \end{verbatim}\end{quote}
525: \tagtable[tp]{ftam-2}{FTAM Attribute Values}{FTAMattributes}
526:
527: \subsection {Concurrency}
528: An FTAM concurrency list is represented by the \verb"FTAMconcurrency"
529: structure.
530: \begin{quote}\index{FTAMconcurrency}\small\begin{verbatim}
531: struct FTAMconcurrency {
532: #define FLOCK_SHARED 00 /* shared */
533: #define FLOCK_EXCLUSIVE 01 /* exclusive */
534: #define FLOCK_NOTREQD 02 /* not-required */
535: #define FLOCK_NOACCESS 03 /* no-access */
536:
537: char fc_readlock;
538: char fc_insertlock;
539: char fc_replacelock;
540: char fc_extendlock;
541: char fc_eraselock;
542: char fc_readattrlock;
543: char fc_chngattrlock;
544: char fc_deletelock;
545: };
546: \end{verbatim}\end{quote}
547: This elements of this structure are:
548: \begin{describe}
549: \item[\verb"fc\_readlock":] the concurrency constraints for the read operation;
550:
551: \item[\verb"fc\_insertlock":] the concurrency constraints for the insert
552: operation;
553:
554: \item[\verb"fc\_replacelock":] the concurrency constraints for the replace
555: operation;
556:
557: \item[\verb"fc\_extendlock":] the concurrency constraints for the extend
558: operation;
559:
560: \item[\verb"fc\_eraselock":] the concurrency constraints for the erase
561: operation;
562:
563: \item[\verb"fc\_readattrlock":] the concurrency constraints for the read
564: attribute operation;
565:
566: \item[\verb"fc\_chngattrlock":] the concurrency constraints for the change
567: attribute operation;
568: and,
569:
570: \item[\verb"fc\_deletelock":] the concurrency constraints for the delete
571: operation.
572: \end{describe}
573: The \verb"FCINIT" macro can be used to initialize an
574: \verb"FTAMconcurrency" structure.
575: It behaves as if it was defined as:
576: \begin{quote}\index{FCINIT}\small\begin{verbatim}
577: void FCINIT (fc)
578: struct FTAMconcurrency *fc;
579: \end{verbatim}\end{quote}
580:
581: \subsection {FADU Identity}
582: An FADU identity is represented by the \verb"FADUidentity" structure.%
583: \footnote{FADU stands for File Access Data Unit;
584: if you didn't already know this, you shouldn't be reading this chapter.
585: Read Section~\ref{ftam:note} right now.}
586: \begin{quote}\index{FADUidentity}\small\begin{verbatim}
587: struct FADUidentity {
588: int fa_type;
589: #define FA_FIRSTLAST 0 /* first-last */
590: #define FA_RELATIVE 1 /* relative */
591: #define FA_BEGINEND 2 /* begin-end */
592: #define FA_SINGLE 3 /* single-name */
593: #define FA_NAMELIST 4 /* name-list */
594: #define FA_FADUNUMBER 5 /* fadu-number */
595:
596: union {
597: int fa_un_firstlast;
598: #define FA_FIRST 0
599: #define FA_LAST 1
600:
601: int fa_un_relative;
602: #define FA_PREVIOUS 0
603: #define FA_CURRENT 1
604: #define FA_NEXT 2
605:
606: int fa_un_beginend;
607: #define FA_BEGIN 0
608: #define FA_END 1
609:
610: char *fa_un_singlename;
611:
612: #define NANAME 5
613: struct {
614: char *fa_un_names[NANAME];
615: int fa_un_nname;
616: } fa_un_list;
617:
618: int fa_un_fadunumber;
619: } fa_un;
620: #define fa_firstlast fa_un.fa_un_firstlast
621: #define fa_relative fa_un.fa_un_relative
622: #define fa_beginend fa_un.fa_un_beginend
623: #define fa_singlename fa_un.fa_un_singlename
624: #define fa_names fa_un.fa_un_list.fa_un_names
625: #define fa_nname fa_un.fa_un_list.fa_un_nname
626: #define fa_fadunumber fa_un.fa_un_fadunumber
627: };
628: \end{verbatim}\end{quote}
629: As shown, this structure is really a discriminated union
630: (a structure with a tag element followed by a union).
631: The elements are:
632: \begin{describe}
633: \item[\verb"fa\_type":] indicates what type of FADU identity is represented;
634: Depending on this type, one of the following elements is valid:
635: \begin{describe}
636: \item[\verb"fa\_firstlast":] the location, identified as first or last;
637:
638: \item[\verb"fa\_relative":] the location, identified as previous,
639: current, or next;
640:
641: \item[\verb"fa\_beginend":] the location, identified as begin or end;
642:
643: \item[\verb"fa\_singlename":] the location, as identified by name;
644:
645: \item[\verb"fa\_names"/\verb"fa\_nname":] the location,
646: as identified by a list of names (and the length of that list,
647: which may not exceed the manifest constant \verb"NANAME");
648: or,
649:
650: \item[\verb"fa\_fadunumber":] the location, as identified by number.
651: \end{describe}
652: \end{describe}
653: A limitation of this implementation
654: is that a fixed number of FADU names may be supported,
655: as denoted by the manifest constant \verb"NANAME".
656:
657: The \verb"FUFREE" macro can be used to free the storage associated with an
658: \verb"FADUidentity" structure (without freeing the structure itself).
659: It behaves as if it was defined as:
660: \begin{quote}\index{FUFREE}\small\begin{verbatim}
661: void FUFREE (fu)
662: struct FADUidentity *fu;
663: \end{verbatim}\end{quote}
664:
665: \section {Association Establishment}
666: The \man libftam(3n) library distinguishes between the entity which started an
667: association,
668: the {\em initiator},
669: and the entity which was subsequently bound to the association,
670: the {\em responder}.
671: We sometimes term these two entities the {\em client\/} and the {\em server},
672: respectively.
673:
674: Section~\ref{acs:addresses} of \volone/ describes the use of addressing
675: for the application layer.
676: In particular,
677: Figure~\ref{getFTAMentity} on page~\pageref{getFTAMentity} of \volone/
678: presents
679: an example of how one constructs the address for the File Transfer, Access
680: and Management (FTAM) service on host \verb"RemoteHost".
681:
682: \subsection {Responder}
683: The \man tsapd(8c) daemon,
684: upon accepting a connection from an initiating host,
685: consults the ISO services database to determine which program
686: on the local system implements the desired application context.
687:
688: Once the program has been ascertained,
689: the daemon runs the program with any arguments listed in the database.
690: In addition,
691: it appends some {\em magic arguments\/} to the argument vector.
692: Hence,
693: the very first action performed by the responder is to re-capture the FTAM
694: state contained in the magic arguments.
695: This is done by calling the routine \verb"FInit",
696: which on a successful return,
697: is equivalent to an {\sf F-INITIALIZE.INDICATION\/} event.
698: \begin{quote}\index{FInit}\small\begin{verbatim}
699: int FInit (vecp, vec, fts, tracing, fti)
700: int vecp;
701: char **vec;
702: struct FTAMstart *fts;
703: int (*tracing) ();
704: struct FTAMindication *fti;
705: \end{verbatim}\end{quote}
706: The parameters to this procedure are:
707: \begin{describe}
708: \item[\verb"vecp":] the length of the argument vector;
709:
710: \item[\verb"vec":] the argument vector;
711:
712: \item[\verb"fts":] a pointer to an \verb"FTAMstart" structure,
713: which is updated only if the call succeeds;
714:
715: \item[\verb"tracing":] the address of a tracing routine to be invoked when an
716: FTAM event occurs (consult Section~\ref{ftam:tracing});
717: and,
718:
719: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure,
720: which is updated only if the call fails.
721: \end{describe}
722: If \verb"FInit" is successful,
723: it returns information in the \verb"fts" parameter,
724: which is a pointer to an \verb"FTAMstart" structure.
725: \begin{quote}\index{FTAMstart}\small\begin{verbatim}
726: struct FTAMstart {
727: int fts_sd;
728:
729: AEInfo fts_calledtitle;
730: AEInfo fts_callingtitle;
731:
732: struct PSAPaddr fts_calledaddr;
733: struct PSAPaddr fts_callingaddr;
734:
735: OID fts_context;
736:
737: int fts_manage;
738:
739: int fts_class;
740:
741: int fts_units;
742: int fts_attrs;
743:
744: PE fts_sharedASE;
745:
746: int fts_fqos;
747:
748: struct FTAMcontentlist fts_contents;
749:
750: char *fts_initiator;
751: char *fts_account;
752: char *fts_password;
753: int fts_passlen;
754:
755: int fts_ssdusize;
756:
757: struct QOStype fts_qos;
758: };
759: \end{verbatim}\end{quote}
760: The elements of this structure are:
761: \begin{describe}
762: \item[\verb"fts\_sd":] the association-descriptor to be used to reference
763: this association;
764:
765: \item[\verb"fts\_calledtitle":] information on the called application-entity,
766: if any (consult Section~\ref{acs:aei} of \volone/);
767:
768: \item[\verb"fts\_callingtitle":] information on the the calling
769: application-entity, if any;
770:
771: \item[\verb"fts\_calledaddr":] the called presentation address
772: (consult Section~\ref{psap:addresses} of \voltwo/);
773:
774: \item[\verb"fts\_callingaddr":] the calling presentation address;
775:
776: \item[\verb"fts\_context":] the application context name;
777:
778: \item[\verb"fts\_manage":] a flag indicating if presentation context
779: management is available for use (zero if unavailable);
780:
781: \item[\verb"fts\_class":] the inclusive-or of the service classes offered;
782:
783: \item[\verb"fts\_units":] the functional units;
784:
785: \item[\verb"fts\_attrs":] the attribute groups;
786:
787: \item[\verb"fts\_sharedASE":] shared ASE information;
788:
789: \item[\verb"fts\_fqos":] the FTAM Quality-of-Service;
790:
791: \item[\verb"fts\_contents":] the contents type list;
792:
793: \item[\verb"fts\_initiator":] the user-identity of the initiator, if any;
794:
795: \item[\verb"fts\_account":] the account, if any;
796:
797: \item[\verb"fts\_password"/\verb"fts\_passlen":] the password (and its
798: length), if any;
799:
800: \item[\verb"fts\_ssdusize":] the largest atomic SSDU size that can be used
801: on the underlying connection;
802: and,
803:
804: \item[\verb"qos":] the quality of service on the connection
805: (see Section~\ref{tsap:qos} in \voltwo/).
806: \end{describe}
807: Note that the data contained in the structure was allocated via \man malloc(3),
808: and should be released by using the \verb"FTSFREE" macro when no longer
809: referenced.
810: The \verb"FTSFREE" macro,
811: behaves as if it was defined as:
812: \begin{quote}\index{FTSFREE}\small\begin{verbatim}
813: void FTSFREE (fts)
814: struct FTAMstart *fts;
815: \end{verbatim}\end{quote}
816: The macro frees only the data allocated by \verb"FInit",
817: and not the \verb"FTAMstart" structure itself.
818: Further,
819: \verb"FTSFREE" should be called only if the call to the \verb"FInit"
820: routine returned \verb"OK".
821:
822: If the call to \verb"FInit" is not successful,
823: then an {\sf F-P-ABORT.INDICATION\/} event is simulated,
824: and the relevant information is returned in an encoded \verb"FTAMindication"
825: structure.\label{FTAMindication}
826: \begin{quote}\index{FTAMindication}\small\begin{verbatim}
827: struct FTAMindication {
828: int fti_type;
829: #define FTI_FINISH 0x00
830: #define FTI_ABORT 0x01
831: #define FTI_MANAGEMENT 0x02
832: #define FTI_BULKBEGIN 0x03
833: #define FTI_BULKEND 0x04
834: #define FTI_ACCESS 0x05
835: #define FTI_READWRITE 0x06
836: #define FTI_DATA 0x07
837: #define FTI_DATAEND 0x08
838: #define FTI_CANCEL 0x09
839: #define FTI_TRANSEND 0x10
840:
841: union {
842: struct FTAMfinish fti_un_finish;
843: struct FTAMabort fti_un_abort;
844: struct FTAMgroup fti_un_group;
845: struct FTAMaccess fti_un_access;
846: struct FTAMreadwrite fti_un_readwrite;
847: struct PSAPdata fti_un_data;
848: struct FTAMdataend fti_un_dataend;
849: struct FTAMcancel fti_un_cancel;
850: struct FTAMtransend fti_un_transend;
851: } fti_un;
852: #define fti_finish fti_un.fti_un_finish
853: #define fti_abort fti_un.fti_un_abort
854: #define fti_group fti_un.fti_un_group
855: #define fti_access fti_un.fti_un_access
856: #define fti_readwrite fti_un.fti_un_readwrite
857: #define fti_data fti_un.fti_un_data
858: #define fti_dataend fti_un.fti_un_dataend
859: #define fti_cancel fti_un.fti_un_cancel
860: #define fti_transend fti_un.fti_un_transend
861: };
862: \end{verbatim}\end{quote}
863: As shown, this structure is really a discriminated union
864: (a structure with a tag element followed by a union).
865: Hence, on a failure return,
866: one first coerces a pointer to the \verb"FTAMabort" structure contained
867: therein,
868: and then consults the elements of that structure.
869: \begin{quote}\index{FTAMabort}\small\begin{verbatim}
870: struct FTAMabort {
871: int fta_peer;
872:
873: int fta_action;
874:
875: #define NFDIAG 5
876: int fta_ndiag;
877: struct FTAMdiagnostic fta_diags[NFDIAG];
878: };
879: \end{verbatim}\end{quote}
880: The elements of an \verb"FTAMabort" structure are:
881: \begin{describe}
882: \item[\verb"fta\_peer":] if set, indicates that a user-initiated abort occurred
883: (an {\sf F-U-ABORT.INDICATION\/} event);
884: if not set, indicates that a provider-initiated abort occurred
885: (an {\sf F-P-ABORT.INDICATION\/} event);
886:
887: \item[\verb"fta\_action":] an action result;
888: and,
889:
890: \item[\verb"fta\_diags"/\verb"fta\_ndiag":] any diagnostic information
891: (and the number of diagnostics present).
892: \end{describe}
893: For each diagnostic present (typically only one) in the \verb"FTAMabort"
894: structure,
895: information regarding the failure is present.
896: In particular,
897: the error code can be found in the
898: the \verb"ftd_identifier" element of each diagnostic.
899:
900: After examining the information returned by \verb"FInit" on a successful call
901: (and possibly after examining the argument vector),
902: the responder should either accept or reject the association.
903: For either response,
904: the responder should use the \verb"FInitializeResponse" routine
905: (which corresponds to the {\sf F-INITIALIZE.RESPONSE\/} action).
906: \begin{quote}\index{FInitializeResonse}\small\begin{verbatim}
907: int FInitializeResponse (sd, state, action, context,
908: respondtitle, respondaddr, manage, class, units,
909: attrs, sharedASE, fqos, contents, diag, ndiag, fti)
910: int sd;
911: int state,
912: action,
913: manage,
914: class,
915: units,
916: attrs,
917: fqos;
918: OID context;
919: AEI respondtitle;
920: struct PSAPaddr *respondaddr;
921: PE sharedASE;
922: struct FTAMcontentlist *contents;
923: struct FTAMdiagnostic diag[];
924: int ndiag;
925: struct FTAMindication *fti;
926: \end{verbatim}\end{quote}
927: The parameters to this procedure are:
928: \begin{describe}
929: \item[\verb"sd":] the association-descriptor;
930:
931: \item[\verb"state":] a state result;
932:
933: \item[\verb"action":] an action result;
934:
935: \item[\verb"context":] the application context name
936: (use the manifest constant \verb"NULLOID" if the proposed name should be used);
937:
938: \item[\verb"manage":] the negotiated use of presentation context management;
939:
940: \item[\verb"respondtitle":] information on the responding application-entity,
941: if any;
942:
943: \item[\verb"respondaddr":] the responding presentation address, if any;
944:
945: \item[\verb"manage":] the negotiated service class;
946:
947: \item[\verb"units":] the negotiated functional units
948: (specify both mandatory and optional functional units for the service class);
949:
950: \item[\verb"attrs":] the negotiated attribute groups;
951:
952: \item[\verb"sharedASE":] shared ASE information;
953:
954: \item[\verb"fqos":] the negotiated FTAM Quality-of-Service;
955:
956: \item[\verb"contents":] the negotiated contents type list;
957:
958: \item[\verb"diag"/\verb"ndiag":] a list of diagnostics
959: (and the number of diagnostics in the list);
960: and,
961:
962: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure,
963: which is updated only if the call fails.
964: \end{describe}
965: If the call to \verb"FInitializeResponse" is successful,
966: then association establishment has now been completed.
967: Otherwise,
968: if the call failed and the reason is ``fatal'',
969: then the association is lost.
970:
971: \subsection {Initiator}
972: A program wishing to associate itself with a filestore
973: calls the routine \verb"FInitializeRequest",
974: which corresponds to the user taking the {\sf F-INIT\-IAL\-IZE.REQUEST\/}
975: action.
976: \begin{quote}\index{FInitializeRequest}\small\begin{verbatim}
977: int FInitializeRequest (context, callingtitle, calledtitle,
978: callingaddr, calledaddr, manage, class, units, attrs,
979: sharedASE, fqos, contents, initiator, account,
980: password, passlen, qos, tracing, ftc, fti)
981: OID context;
982: AEI calledtitle,
983: callingtitle;
984: struct PSAPaddr *calledaddr,
985: *callingaddr;
986: int manage,
987: class,
988: units,
989: attrs,
990: fqos,
991: passlen;
992: PE sharedASE;
993: struct FTAMcontentlist *contents;
994: char *initiator,
995: *account,
996: *password;
997: struct QOStype *qos;
998: IFP tracing;
999: struct FTAMconnect *ftc;
1000: struct FTAMindication *fti;
1001: \end{verbatim}\end{quote}
1002: The parameters to this procedure are:
1003: \begin{describe}
1004: \item[\verb"context":] the application context name
1005: (use the manifest constant \verb"NULLOID" to invoke the default
1006: file transfer context);
1007:
1008: \item[\verb"callingtitle":] information on the the calling application-entity,
1009: if any (consult Section~\ref{acs:aei} of \volone/);
1010:
1011: \item[\verb"calledtitle":] information on the called application-entity,
1012: if any;
1013:
1014: \item[\verb"callingaddr":] the calling presentation address
1015: (consult Section~\ref{psap:addresses} of \voltwo/);
1016:
1017: \item[\verb"calledaddr":] the called presentation address;
1018:
1019: \item[\verb"manage":] a flag indicating if presentation context management is
1020: available for use (zero if unavailable);
1021:
1022: \item[\verb"class":] the proposed service classes;
1023:
1024: \item[\verb"units":] the proposed functional units
1025: (specify both mandatory and optional functional units for the indicated
1026: service class);
1027:
1028: \item[\verb"attrs":] the proposed attribute groups;
1029:
1030: \item[\verb"sharedASE":] shared ASE information;
1031:
1032: \item[\verb"fqos":] the proposed FTAM Quality-of-Service;
1033:
1034: \item[\verb"contents":] the contents type list;
1035:
1036: \item[\verb"initiator":] the user-identity of the initiator, if any;
1037:
1038: \item[\verb"account":] the account, if any
1039:
1040: \item[\verb"password"/\verb"passlen":] the password (and its length), if any;
1041:
1042: \item[\verb"qos":] the quality of service on the connection
1043: (see Section~\ref{tsap:qos} in \voltwo/);
1044:
1045: \item[\verb"tracing":] the address of a tracing routine to be invoked when an
1046: FTAM event occurs (consult Section~\ref{ftam:tracing});
1047:
1048: \item[\verb"ftc":] a pointer to an \verb"FTAMconnect" structure,
1049: which is updated only if the call succeeds;
1050: and,
1051:
1052: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure,
1053: which is updated only if the call fails.
1054: \end{describe}
1055: If the call to \verb"FInitializeRequest" is successful
1056: (the {\sf F-INITIALIZE.CON\-FIR\-MA\-TION\/} event occurs),
1057: it returns information in the \verb"ftc" parameter
1058: which is a pointer to an \verb"FTAMconnect" structure.
1059: \begin{quote}\index{FTAMconnect}\small\begin{verbatim}
1060: struct FTAMconnect {
1061: int ftc_sd;
1062:
1063: int ftc_state;
1064: int ftc_action;
1065:
1066: AEInfo ftc_respondtitle;
1067:
1068: struct PSAPaddr ftc_respondaddr;
1069:
1070: int ftc_manage;
1071:
1072: int ftc_units;
1073: int ftc_attrs;
1074:
1075: int ftc_rollback;
1076:
1077: struct FTAMcontentlist ftc_contents;
1078:
1079: int ftc_ndiag;
1080: struct FTAMdiagnostic ftc_diags[NFDIAG];
1081:
1082: int ftc_ssdusize;
1083:
1084: struct QOStype ftc_qos;
1085: };
1086: \end{verbatim}\end{quote}
1087: The elements of an \verb"FTAMconnect" structure are:
1088: \begin{describe}
1089: \item[\verb"ftc\_sd":] the association-descriptor to be used to reference
1090: this association;
1091:
1092: \item[\verb"ftc\_state":] a state result
1093:
1094: \item[\verb"ftc\_action":] an action result
1095:
1096: \item[\verb"ftc\_respondtitle":] the responding application-entity title, if
1097: any;
1098:
1099: \item[\verb"ftc\_respondaddr":] the responding presentation address, if any;
1100:
1101: \item[\verb"ftc\_manage":] the negotiated use of presentation context
1102: management;
1103:
1104: \item[\verb"ftc\_units":] the negotiated functional units;
1105:
1106: \item[\verb"ftc\_attrs":] the negotiated attribute groups;
1107:
1108: \item[\verb"ftc\_rollback":] the negotiated rollback availability;
1109:
1110: \item[\verb"ftc\_contents":] the negotiated contents type list;
1111:
1112: \item[\verb"ftc\_diags"/\verb"ftc\_ndiag":] any diagnostic information
1113: (and the number of diagnostics present)
1114:
1115: \item[\verb"ftc\_ssdusize":] the largest atomic SSDU size that can be used
1116: on the underlying connection;
1117: and,
1118:
1119: \item[\verb"ftc\_qos":] the quality of service on the connection
1120: (see Section~\ref{tsap:qos} in \voltwo/).
1121: \end{describe}
1122: If the call to \verb"FInitializeRequest" is successful,
1123: and the \verb"ftc_state" element is set to \verb"FSTATE_SUCCESS",
1124: then association establishment has completed.
1125: If the call is successful,
1126: but the \verb"acc_result" element is not \verb"FSTATE_SUCCESS",
1127: the the association attempt has been rejected
1128: and the diagnostics present indicate the reason for the rejection.
1129: Otherwise, if the call fails then the association is not established and
1130: the \verb"FTAMabort" structure contained in the \verb"FTAMindication"
1131: discriminated union has been updated.
1132:
1133: Note that the data contained in the structure was allocated via \man malloc(3),
1134: and should be released by using the \verb"FTCFREE" macro when no longer
1135: referenced.
1136: The \verb"FTCFREE" macro,
1137: behaves as if it was defined as:
1138: \begin{quote}\index{FTCFREE}\small\begin{verbatim}
1139: void FTCFREE (ftc)
1140: struct FTAMconnect *ftc;
1141: \end{verbatim}\end{quote}
1142: The macro frees only the data allocated by \verb"FInitializeRequest",
1143: and not the \verb"FTAMconnect" structure itself.
1144: Further,
1145: \verb"FTCFREE" should be called only if the call to the
1146: \verb"FInitializeRequest" routine returned \verb"OK".
1147:
1148: \section {Event Handling}
1149: Once the association has been established,
1150: an association-descriptor is used to reference the connection.
1151: This is usually the first parameter given to any of the remaining routines in
1152: the \man libftam(3n) library.
1153: Further,
1154: the last parameter is usually a pointer to an \verb"FTAMindication" structure
1155: (as described on page~\pageref{FTAMindication}).
1156: If a call to one of these routines fails,
1157: then the structure is updated.
1158: Consult the \verb"FTAMabort" element of the \verb"FTAMindication" structure
1159: and look at the diagnostics (typically only one) present.
1160: When a diagnostic is reported by the provider,
1161: the \verb"ftd_type" element indicates if the error is ``fatal'' by having the
1162: value \verb"DIAG_PERM".
1163: Other values, such as \verb"DIAG_TRANS" indicate non-fatal errors
1164: (the association still exists).
1165: The most common non-fatal error to occur is \verb"FS_GEN_WAITING" which
1166: indicates that an indication is waiting to be read.
1167:
1168: The \verb"FWaitRequest" routine is used to wait for an event to occur.
1169: \begin{quote}\index{FWaitRequest}\small\begin{verbatim}
1170: int FWaitRequest (sd, secs, fti)
1171: int sd;
1172: int secs;
1173: struct FTAMindication *fti;
1174: \end{verbatim}\end{quote}
1175: The parameters to this procedure are:
1176: \begin{describe}
1177: \item[\verb"sd":] the association-descriptor;
1178:
1179: \item[\verb"secs":] the maximum number of seconds to wait for the event
1180: (a value of \verb"NOTOK" indicates that the call should block indefinitely,
1181: whereas a value of \verb"OK" indicates that the call should not block at all,
1182: e.g., a polling action);
1183: and,
1184:
1185: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure,
1186: which is always updated.
1187: \end{describe}
1188: If the call to \verb"FWaitRequest" returns the manifest constant \verb"NOTOK",
1189: then the \verb"FTAMabort" structure contained in the \verb"FTAMindication"
1190: parameter \verb"fti" contains the reason for the failure.
1191: Similarly,
1192: if the manifest constant \verb"OK" is returned,
1193: an event is encoded in the \verb"fti" parameter,
1194: depending on the value of the \verb"fti_type" element:
1195: \[\begin{tabular}{|l|l|}
1196: \hline
1197: \multicolumn{1}{|c|}{\bf Value}&
1198: \multicolumn{1}{c|}{\bf Event}\\
1199: \hline
1200: \tt FTI\_FINISH& \sf F-TERMINATE.INDICATION\\
1201: \hline
1202: \tt FTI\_MANAGEMENT& grouped management operation\\
1203: \hline
1204: \tt FTI\_BULKBEGIN& begin of grouped file transfer operation\\
1205: \hline
1206: \tt FTI\_BULKEND& end of grouped file transfer operation\\
1207: \hline
1208: \tt FTI\_ACCESS& \sf F-LOCATE.INDICATION\\
1209: & \sf F-LOCATE.CONFIRMATION\\
1210: & \sf F-ERASE.INDICATION\\
1211: & \sf F-ERASE.CONFIRMATION\\
1212: \hline
1213: \tt FTI\_READWRITE& \sf F-READ.INDICATION\\
1214: & \sf F-WRITE.INDICATION\\
1215: \hline
1216: \tt FTI\_DATA& \sf F-DATA.INDICATION\\
1217: \hline
1218: \tt FTI\_DATAEND& \sf F-DATA-END.INDICATION\\
1219: \hline
1220: \tt FTI\_CANCEL& \sf F-CANCEL.INDICATION\\
1221: & \sf F-CANCEL.CONFIRMATION\\
1222: \hline
1223: \tt FTI\_TRANSEND& \sf F-TRANSFER-END.INDICATION\\
1224: & \sf F-TRANSFER-END.CONFIRMATION\\
1225: \hline
1226: \end{tabular}\]
1227: These are now discussed in turn.
1228:
1229: \subsubsection {Termination Indication}
1230: When an event associated with association release occurs,
1231: the \verb"fti_type" field of the \verb"fti" parameter contains the value
1232: \verb"FTI_FINISH".
1233: Further,
1234: an \verb"FTAMfinish" structure is contained inside the \verb"fti" parameter,
1235: indicating an {\sf F-TERMINATE.INDICATION\/} event.
1236: \begin{quote}\index{FTAMfinish}\small\begin{verbatim}
1237: struct FTAMfinish {
1238: int ftf_sharedASE;
1239: };
1240: \end{verbatim}\end{quote}
1241: The elements of this structure are:
1242: \begin{describe}
1243: \item[\verb"ftf\_sharedASE":] shared ASE information.
1244: \end{describe}
1245: The \verb"FTFFREE" macro can be used to free the storage associated with an
1246: \verb"FTAMdfinish" structure (without freeing the structure itself).
1247: It behaves as if it was defined as:
1248: \begin{quote}\index{FTFFREE}\small\begin{verbatim}
1249: void FTFFREE (ftf)
1250: struct FTAMfinish *ftf;
1251: \end{verbatim}\end{quote}
1252:
1253: \subsubsection {Group Indications}
1254: Use of the grouping function unit is required in the current implementation,
1255: hence
1256: when a transfer or management indication occurs,
1257: the \verb"fti_type" field of the \verb"fti" parameter contains one of three
1258: values:
1259: \[\begin{tabular}{|l|l|}
1260: \hline
1261: \multicolumn{1}{|c|}{\bf Value}&
1262: \multicolumn{1}{c|}{\bf Event}\\
1263: \hline
1264: \tt FTI\_MANAGEMENT& grouped management operation\\
1265: \tt FTI\_BULKBEGIN& begin of grouped file transfer operation\\
1266: \tt FTI\_BULKEND& end of grouped file transfer operation\\
1267: \hline
1268: \end{tabular}\]
1269: and an \verb"FTAMgroup" structure is contained inside the \verb"fti" parameter.
1270: \begin{quote}\index{FTAMgroup}\small\begin{verbatim}
1271: struct FTAMgroup {
1272: int ftg_threshold;
1273:
1274: int ftg_flags;
1275:
1276: union {
1277: struct FTAMselect ftg_un1_select;
1278: struct FTAMcreate ftg_un1_create;
1279: struct FTAMclose ftg_un1_close;
1280: } ftg_un1;
1281: #define ftg_select ftg_un1.ftg_un1_select
1282: #define ftg_create ftg_un1.ftg_un1_create
1283: #define ftg_close ftg_un1.ftg_un1_close
1284:
1285: struct FTAMreadattr ftg_readattr;
1286:
1287: struct FTAMchngattr ftg_chngattr;
1288:
1289: union {
1290: struct FTAMdeselect ftg_un2_deselect;
1291: struct FTAMdelete ftg_un2_delete;
1292: struct FTAMopen ftg_un2_open;
1293: } ftg_un2;
1294: #define ftg_deselect ftg_un2.ftg_un2_deselect
1295: #define ftg_delete ftg_un2.ftg_un2_delete
1296: #define ftg_open ftg_un2.ftg_un2_open
1297: };
1298: \end{verbatim}\end{quote}
1299: The elements of this structure are:\label{FTAMgroup}
1300: \begin{describe}
1301: \item[\verb"ftg\_threshold":] the grouping threshold;
1302:
1303: \item[\verb"ftg\_flags":] the indications which are present,
1304: containing the inclusive-or of any of the values:
1305: \[\begin{tabular}{|l|l|}
1306: \hline
1307: \multicolumn{1}{|c|}{\bf Value}&
1308: \multicolumn{1}{c|}{\bf Meaning}\\
1309: \hline
1310: \tt FTG\_BEGIN& F-BEGIN-GROUP\\
1311: \tt FTG\_SELECT& F-SELECT\\
1312: \tt FTG\_CREATE& F-CREATE\\
1313: \tt FTG\_RDATTR& F-READ-ATTRIB\\
1314: \tt FTG\_CHATTR& F-CHANGE-ATTRIB\\
1315: \tt FTG\_OPEN& F-OPEN\\
1316: \tt FTG\_CLOSE& F-CLOSE\\
1317: \tt FTG\_DESELECT& F-DESELECT\\
1318: \tt FTG\_DELETE& F-DELETE\\
1319: \tt FTG\_END& F-END-GROUP\\
1320: \hline
1321: \end{tabular}\]
1322:
1323: \item[\verb"ftg\_select":] an \verb"FTAMselect" structure;
1324:
1325: \item[\verb"ftg\_create":] an \verb"FTAMcreate" structure;
1326:
1327: \item[\verb"ftg\_close":] an \verb"FTAMclose" structure;
1328:
1329: \item[\verb"ftg\_readattr":] an \verb"FTAMreadattr" structure;
1330:
1331: \item[\verb"ftg\_chngattr":] an \verb"FTAMchngattr" structure;
1332:
1333: \item[\verb"ftg\_deselect":] an \verb"FTAMdeselect" structure;
1334:
1335: \item[\verb"ftg\_delete":] an \verb"FTAMdelete" structure;
1336: and,
1337:
1338: \item[\verb"ftg\_open":] an \verb"FTAMopen" structure.
1339: \end{describe}
1340: The \verb"FTGFREE" macro can be used to free the storage associated with an
1341: \verb"FTAMgroup" structure (without freeing the structure itself).
1342: It behaves as if it was defined as:
1343: \begin{quote}\index{FTGFREE}\small\begin{verbatim}
1344: void FTGFREE (ftg)
1345: struct FTAMgroup *ftg;
1346: \end{verbatim}\end{quote}
1347:
1348: If the flag \verb"FTG_SELECT" is present,
1349: then \verb"ftg_select" element contains an {\sf F-SELECT\/} event encoded in an
1350: \verb"FTAMselect" structure:
1351: \begin{quote}\index{FTAMselect}\small\begin{verbatim}
1352: struct FTAMselect {
1353: int ftse_state;
1354: int ftse_action;
1355:
1356: struct FTAMattributes ftse_attrs;
1357:
1358: int ftse_access;
1359: struct FTAMpasswords ftse_pwds;
1360: struct FTAMconcurrency ftse_conctl;
1361:
1362: PE ftse_sharedASE;
1363:
1364: char *ftse_account;
1365:
1366: int ftse_ndiag;
1367: struct FTAMdiagnostic ftse_diags[NFDIAG];
1368: };
1369: \end{verbatim}\end{quote}
1370: The elements of this structure are:
1371: \begin{describe}
1372: \item[\verb"ftse\_state":] the state result ({\sf .RESPONSE\/} only);
1373:
1374: \item[\verb"ftse\_action":] the action result ({\sf .RESPONSE\/} only);
1375:
1376: \item[\verb"ftse\_attrs":] file attributes;
1377:
1378: \item[\verb"ftse\_access":] requested access,
1379: containing the inclusive-or of any of the values
1380: found in Table~\ref{FTAMaccess} ({\sf .REQUEST\/} only);
1381:
1382: \item[\verb"ftse\_pwds":] access passwords ({\sf .REQUEST\/} only);
1383:
1384: \item[\verb"ftse\_conctl":] concurrency control ({\sf .REQUEST\/} only);
1385:
1386: \item[\verb"ftse\_sharedASE":] shared ASE information ({\sf .REQUEST\/} only);
1387:
1388: \item[\verb"ftse\_account":] account ({\sf .REQUEST\/} only);
1389: and,
1390:
1391: \item[\verb"ftse\_diags"/\verb"ftse\_ndiag":] any diagnostic information
1392: (and the number of diagnostics present, {\sf .RESPONSE\/} only).
1393: \end{describe}
1394: Note that the data contained in the structure was allocated via \man malloc(3),
1395: and should be released with the \verb"FTSEFREE" macro when no longer needed.
1396: The \verb"FTSEFREE" macro
1397: behaves as if it was defined as:
1398: \begin{quote}\index{FTSEFREE}\small\begin{verbatim}
1399: void FTSEFREE (ftse)
1400: struct FTAMselect *ftse;
1401: \end{verbatim}\end{quote}
1402: The macro frees only the data allocated by \verb"FWaitRequest",
1403: and not the \verb"FTAMselect" structure itself.
1404: Note that the macro \verb"FTGFREE" when applied to the group,
1405: will call \verb"FTSEFREE" as appropriate.
1406:
1407: If the flag \verb"FTG_CREATE" is present,
1408: then \verb"ftg_create" element contains an {\sf F-CREATE\/} event encoded in an
1409: \verb"FTAMcreate" structure:
1410: \begin{quote}\index{FTAMcreate}\small\begin{verbatim}
1411: struct FTAMcreate {
1412: int ftce_state;
1413: int ftce_action;
1414:
1415: int ftce_override;
1416: char *ftce_create;
1417: int ftce_crelen;
1418:
1419: struct FTAMattributes ftce_attrs;
1420:
1421: int ftce_access;
1422: struct FTAMpasswords ftce_pwds;
1423: struct FTAMconcurrency ftce_conctl;
1424:
1425: PE ftce_sharedASE;
1426:
1427: char *ftce_account;
1428:
1429: int ftce_ndiag;
1430: struct FTAMdiagnostic ftce_diags[NFDIAG];
1431: };
1432: \end{verbatim}\end{quote}
1433: The elements of this structure are:
1434: \begin{describe}
1435: \item[\verb"ftce\_state":] the state result ({\sf .RESPONSE\/} only);
1436:
1437: \item[\verb"ftce\_action":] the action result ({\sf .RESPONSE\/} only);
1438:
1439: \item[\verb"ftce\_override":] the override setting, one of:
1440: \[\begin{tabular}{|l|l|}
1441: \hline
1442: \multicolumn{1}{|c|}{\bf Value}&
1443: \multicolumn{1}{c|}{\bf Meaning}\\
1444: \hline
1445: \tt FOVER\_FAIL& fail, if already exists\\
1446: \tt FOVER\_SELECT& select, if already exists\\
1447: \tt FOVER\_WRITE& zero-truncate, if already exists\\
1448: \tt FOVER\_DELETE& delete, if already exists\\
1449: \hline
1450: \end{tabular}\]
1451: ({\sf .REQUEST\/} only);
1452:
1453: \item[\verb"ftce\_attrs":] file attributes;
1454:
1455: \item[\verb"ftce\_create"/\verb"ftce\_crelen":] the
1456: create password and its length, if any ({\sf .REQUEST\/} only);
1457:
1458: \item[\verb"ftce\_access":] requested access,
1459: containing the inclusive-or of any of the values
1460: found in Table~\ref{FTAMaccess} ({\sf .REQUEST\/} only);
1461:
1462: \item[\verb"ftce\_pwds":] access passwords ({\sf .REQUEST\/} only);
1463:
1464: \item[\verb"ftce\_conctl":] concurrency control ({\sf .REQUEST\/} only);
1465:
1466: \item[\verb"ftce\_sharedASE":] shared ASE information ({\sf .REQUEST\/} only);
1467:
1468: \item[\verb"ftce\_account":] account ({\sf .REQUEST\/} only);
1469: and,
1470:
1471: \item[\verb"ftce\_diags"/\verb"ftce\_ndiag":] any diagnostic information
1472: (and the number of diagnostics present, {\sf .RESPONSE\/} only).
1473: \end{describe}
1474: Note that the data contained in the structure was allocated via \man malloc(3),
1475: and should be released with the \verb"FTCEFREE" macro when no longer needed.
1476: The \verb"FTCEFREE" macro
1477: behaves as if it was defined as:
1478: \begin{quote}\index{FTCEFREE}\small\begin{verbatim}
1479: void FTCEFREE (ftce)
1480: struct FTAMcreate *ftce;
1481: \end{verbatim}\end{quote}
1482: The macro frees only the data allocated by \verb"FWaitRequest",
1483: and not the \verb"FTAMcreate" structure itself.
1484: Note that the macro \verb"FTGFREE" when applied to the group,
1485: will call \verb"FTCEFREE" as appropriate.
1486:
1487: If the flag \verb"FTG_RDATTR" is present,
1488: then \verb"ftg_readattr" element contains an {\sf F-READ-ATTRIB\/} event encoded in an
1489: \verb"FTAMreadattr" structure:
1490: \begin{quote}\index{FTAMreadattr}\small\begin{verbatim}
1491: struct FTAMreadattr {
1492: int ftra_action;
1493:
1494: int ftra_attrnames;
1495:
1496: struct FTAMattributes ftra_attrs;
1497: int ftra_ndiag;
1498: struct FTAMdiagnostic ftra_diags[NFDIAG];
1499: };
1500: \end{verbatim}\end{quote}
1501: The elements of this structure are:
1502: \begin{describe}
1503: \item[\verb"ftra\_action":] the action result ({\sf .RESPONSE\/} only);
1504:
1505: \item[\verb"ftra\_attrnames":] the attributes to read,
1506: containing the inclusive-or of any of the values shown in
1507: Table~\ref{FTAMattributes} on page~\pageref{FTAMattributes}
1508: ({\sf .REQUEST\/} only);
1509:
1510: \item[\verb"ftra\_attrs":] the attribute values
1511: ({\sf .RESPONSE\/} only);
1512: and,
1513:
1514: \item[\verb"ftra\_diags"/\verb"ftra\_ndiag":] any diagnostic information
1515: (and the number of diagnostics present, {\sf .RESPONSE\/} only).
1516: \end{describe}
1517: Note that the data contained in the structure was allocated via \man malloc(3),
1518: and should be released with the \verb"FTRAFREE" macro when no longer needed.
1519: The \verb"FTRAFREE" macro
1520: behaves as if it was defined as:
1521: \begin{quote}\index{FTRAFREE}\small\begin{verbatim}
1522: void FTRAFREE (ftra)
1523: struct FTAMreadattr *ftra;
1524: \end{verbatim}\end{quote}
1525: The macro frees only the data allocated by \verb"FWaitRequest",
1526: and not the \verb"FTAMreadattr" structure itself.
1527: Note that the macro \verb"FTGFREE" when applied to the group,
1528: will call \verb"FTRAFREE" as appropriate.
1529:
1530: If the flag \verb"FTG_CHNGATTR" is present,
1531: then \verb"ftg_chngattr" element contains an {\sf F-CHANGE-ATTRIB\/} event encoded in
1532: an \verb"FTAMchngattr" structure:
1533: \begin{quote}\index{FTAMchngattr}\small\begin{verbatim}
1534: struct FTAMchngattr {
1535: int ftca_action;
1536:
1537: struct FTAMattributes ftca_attrs;
1538:
1539: int ftca_ndiag;
1540: struct FTAMdiagnostic ftca_diags[NFDIAG];
1541: };
1542: \end{verbatim}\end{quote}
1543: The elements of this structure are:
1544: \begin{describe}
1545: \item[\verb"ftca\_action":] the action result ({\sf .RESPONSE\/} only);
1546:
1547: \item[\verb"ftca\_attrs":] the attribute values to change
1548: (in a {\sf .REQUEST\/}),
1549: and possibly the new values (in a {\sf .RESPONSE\/});
1550: and,
1551:
1552: \item[\verb"ftca\_diags"/\verb"ftca\_ndiag":] any diagnostic information
1553: (and the number of diagnostics present, {\sf .RESPONSE\/} only).
1554: \end{describe}
1555: Note that the data contained in the structure was allocated via \man malloc(3),
1556: and should be released with the \verb"FTCAFREE" macro when no longer needed.
1557: The \verb"FTCAFREE" macro
1558: behaves as if it was defined as:
1559: \begin{quote}\index{FTCAFREE}\small\begin{verbatim}
1560: void FTCAFREE (ftca)
1561: struct FTAMchngattr *ftca;
1562: \end{verbatim}\end{quote}
1563: The macro frees only the data allocated by \verb"FWaitRequest",
1564: and not the \verb"FTAMchngattr" structure itself.
1565: Note that the macro \verb"FTGFREE" when applied to the group,
1566: will call \verb"FTCAFREE" as appropriate.
1567:
1568: If the flag \verb"FTG_OPEN" is present,
1569: then \verb"ftg_open" element contains an {\sf F-OPEN\/} event encoded in an
1570: \verb"FTAMopen" structure:
1571: \begin{quote}\index{FTAMopen}\small\begin{verbatim}
1572: struct FTAMopen {
1573: int ftop_state;
1574: int ftop_action;
1575:
1576: int ftop_mode;
1577:
1578: OID ftop_contents;
1579: PE ftop_parameter;
1580: struct FTAMconcurrency ftop_conctl;
1581: PE ftop_sharedASE;
1582:
1583: int ftop_locking;
1584:
1585: int ftop_ndiag;
1586: struct FTAMdiagnostic ftop_diags[NFDIAG];
1587: };
1588: \end{verbatim}\end{quote}
1589: The elements of this structure are:
1590: \begin{describe}
1591: \item[\verb"ftop\_state":] the state result ({\sf .RESPONSE\/} only);
1592:
1593: \item[\verb"ftop\_action":] the action result ({\sf .RESPONSE\/} only);
1594:
1595: \item[\verb"ftop\_mode":] the processing mode,
1596: containing the inclusive-or of any of the values shown in
1597: Table~\ref{FTAMaccess} on page~\pageref{FTAMaccess}
1598: ({\sf .REQUEST\/} only);
1599:
1600: \item[\verb"ftop\_contents"/\verb"ftop\_parameter":] the contents type;
1601:
1602: \item[\verb"ftop\_conctl":] concurrency control;
1603:
1604: \item[\verb"ftop\_sharedASE":] shared ASE information;
1605:
1606: \item[\verb"ftop\_locking":] enable FADU locking ({\sf .REQUEST\/} only);
1607: and,
1608:
1609: \item[\verb"ftop\_diags"/\verb"ftop\_ndiag":] any diagnostic information
1610: (and the number of diagnostics present, {\sf .RESPONSE\/} only).
1611: \end{describe}
1612: Note that the data contained in the structure was allocated via \man malloc(3),
1613: and should be released with the \verb"FTOPFREE" macro when no longer needed.
1614: The \verb"FTOPFREE" macro
1615: behaves as if it was defined as:
1616: \begin{quote}\index{FTOPFREE}\small\begin{verbatim}
1617: void FTOPFREE (ftop)
1618: struct FTAMopen *ftop;
1619: \end{verbatim}\end{quote}
1620: The macro frees only the data allocated by \verb"FWaitRequest",
1621: and not the \verb"FTAMopen" structure itself.
1622: Note that the macro \verb"FTGFREE" when applied to the group,
1623: will call \verb"FTOPFREE" as appropriate.
1624:
1625: If the flag \verb"FTG_CLOSE" is present,
1626: then \verb"ftg_close" element contains an {\sf F-CLOSE\/} event encoded in an
1627: \verb"FTAMclose" structure:
1628: \begin{quote}\index{FTAMclose}\small\begin{verbatim}
1629: struct FTAMclose {
1630: int ftcl_action;
1631:
1632: PE ftcl_sharedASE;
1633:
1634: int ftcl_ndiag;
1635: struct FTAMdiagnostic ftcl_diags[NFDIAG];
1636: };
1637: \end{verbatim}\end{quote}
1638: The elements of this structure are:
1639: \begin{describe}
1640: \item[\verb"ftcl\_action":] the action result;
1641:
1642: \item[\verb"ftcl\_sharedASE":] shared ASE information;
1643: and,
1644:
1645: \item[\verb"ftcl\_diags"/\verb"ftcl\_ndiag":] any diagnostic information
1646: (and the number of diagnostics present).
1647: \end{describe}
1648: Note that the data contained in the structure was allocated via \man malloc(3),
1649: and should be released with the \verb"FTCLFREE" macro when no longer needed.
1650: The \verb"FTCLFREE" macro
1651: behaves as if it was defined as:
1652: \begin{quote}\index{FTCLFREE}\small\begin{verbatim}
1653: void FTCLFREE (ftcl)
1654: struct FTAMclose *ftcl;
1655: \end{verbatim}\end{quote}
1656: The macro frees only the data allocated by \verb"FWaitRequest",
1657: and not the \verb"FTAMclose" structure itself.
1658: Note that the macro \verb"FTGFREE" when applied to the group,
1659: will call \verb"FTCLFREE" as appropriate.
1660:
1661: If the flag \verb"FTG_DESELECT" is present,
1662: then \verb"ftg_deselect" element contains an {\sf F-DESELECT\/} event encoded in an
1663: \verb"FTAMdeselect" structure:
1664: \begin{quote}\index{FTAMdeselect}\small\begin{verbatim}
1665: struct FTAMdeselect {
1666: int ftde_action;
1667:
1668: PE ftde_sharedASE;
1669:
1670: struct FTAMcharging ftde_charges;
1671: int ftde_ndiag;
1672: struct FTAMdiagnostic ftde_diags[NFDIAG];
1673: };
1674: \end{verbatim}\end{quote}
1675: The elements of this structure are:
1676: \begin{describe}
1677: \item[\verb"ftde\_action":] the action result ({\sf .RESPONSE\/} only);
1678:
1679: \item[\verb"ftde\_sharedASE":] shared ASE information;
1680:
1681: \item[\verb"ftde\_charges":] any charges ({\sf .RESPONSE\/} only);
1682: and,
1683:
1684: \item[\verb"ftde\_diags"/\verb"ftde\_ndiag":] any diagnostic information
1685: (and the number of diagnostics present, {\sf .RESPONSE\/} only).
1686: \end{describe}
1687: Note that the data contained in the structure was allocated via \man malloc(3),
1688: and should be released with the \verb"FTDEFREE" macro when no longer needed.
1689: The \verb"FTDEFREE" macro
1690: behaves as if it was defined as:
1691: \begin{quote}\index{FTDEFREE}\small\begin{verbatim}
1692: void FTDEFREE (ftde)
1693: struct FTAMdeselect *ftde;
1694: \end{verbatim}\end{quote}
1695: The macro frees only the data allocated by \verb"FWaitRequest",
1696: and not the \verb"FTAMdeselect" structure itself.
1697: Note that the macro \verb"FTGFREE" when applied to the group,
1698: will call \verb"FTDEFREE" as appropriate.
1699:
1700: If the flag \verb"FTG_DELETE" is present,
1701: then \verb"ftg_delete" element contains an {\sf F-DELETE\/} event encoded in an
1702: \verb"FTAMdelete" structure:
1703: \begin{quote}\index{FTAMdelete}\small\begin{verbatim}
1704: struct FTAMdelete {
1705: int ftxe_action;
1706:
1707: PE ftxe_sharedASE;
1708:
1709: struct FTAMcharging ftxe_charges;
1710: int ftxe_ndiag;
1711: struct FTAMdiagnostic ftxe_diags[NFDIAG];
1712: };
1713: \end{verbatim}\end{quote}
1714: The elements of this structure are:
1715: \begin{describe}
1716: \item[\verb"ftxe\_action":] the action result ({\sf .RESPONSE\/} only);
1717:
1718: \item[\verb"ftxe\_sharedASE":] shared ASE information;
1719:
1720: \item[\verb"ftxe\_charges":] any charges ({\sf .RESPONSE\/} only);
1721: and,
1722:
1723: \item[\verb"ftxe\_diags"/\verb"ftxe\_ndiag":] any diagnostic information
1724: (and the number of diagnostics present, {\sf .RESPONSE\/} only).
1725: \end{describe}
1726: Note that the data contained in the structure was allocated via \man malloc(3),
1727: and should be released with the \verb"FTXEFREE" macro when no longer needed.
1728: The \verb"FTXEFREE" macro
1729: behaves as if it was defined as:
1730: \begin{quote}\index{FTXEFREE}\small\begin{verbatim}
1731: void FTXEFREE (ftxe)
1732: struct FTAMdeltee *ftxe;
1733: \end{verbatim}\end{quote}
1734: The macro frees only the data allocated by \verb"FWaitRequest",
1735: and not the \verb"FTAMdelete" structure itself.
1736: Note that the macro \verb"FTGFREE" when applied to the group,
1737: will call \verb"FTXEFREE" as appropriate.
1738:
1739: \subsubsection {Access Indications}
1740: When an event associated with file access occurs,
1741: the \verb"fti_type" field of the \verb"fti" parameter contains the value
1742: \verb"FTI_ACCESS".
1743: Further,
1744: an \verb"FTAMaccess" structure is contained inside the \verb"fti" parameter,
1745: indicating an {\sf F-LOCATE\/} or {\sf F-ERASE\/} event.
1746: \begin{quote}\index{FTAMaccess}\small\begin{verbatim}
1747: struct FTAMaccess {
1748: int ftac_operation;
1749:
1750: int ftac_action;
1751:
1752: struct FADUidentity ftac_identity;
1753:
1754: int ftac_locking;
1755:
1756: int ftac_ndiag;
1757: struct FTAMdiagnostic ftac_diags[NFDIAG];
1758: };
1759: \end{verbatim}\end{quote}
1760: The elements of this structure are:
1761: \begin{describe}
1762: \item[\verb"ftac\_operation":] the operation,
1763: one of the values shown in Table~\ref{FTAMaccessops};
1764:
1765: \item[\verb"ftac\_action":] the action result ({\sf .CONFIRMATION\/} only);
1766:
1767: \item[\verb"ftac\_identity":] the FADU identity
1768: (either {\sf .INDICATION\/} and optionally on {\sf F-LOCATE.CONFIRMATION\/});
1769:
1770: \item[\verb"ftac\_locking":] FADU locked ({\sf F-LOCATE.INDICATION\/} only);
1771: and,
1772:
1773: \item[\verb"ftac\_diags"/\verb"ftac\_ndiag":] any diagnostic information
1774: (and the number of diagnostics present, {\sf .CONFIRMATION\/} only).
1775: \end{describe}
1776: Note that the data contained in the structure was allocated via \man malloc(3),
1777: and should be released with the \verb"FTACFREE" macro when no longer needed.
1778: The \verb"FTACFREE" macro
1779: behaves as if it was defined as:
1780: \begin{quote}\index{FTACFREE}\small\begin{verbatim}
1781: void FTACFREE (ftac)
1782: struct FTAMaccess *ftac;
1783: \end{verbatim}\end{quote}
1784: The macro frees only the data allocated by \verb"FWaitRequest",
1785: and not the \verb"FTAMaccess" structure itself.
1786: \tagtable[tp]{ftam-5}{FTAM Access Operations}{FTAMaccessops}
1787:
1788: \subsubsection {Read/Write Indications}
1789: When an event associated with the beginning of bulk data transfer occurs,
1790: the \verb"fti_type" field of the \verb"fti" parameter contains the value
1791: \verb"FTI_READWRITE".
1792: Further,
1793: an \verb"FTAMreadwrite" structure is contained inside the \verb"fti" parameter,
1794: indicating an {\sf F-READ.INDICATION\/} or {\sf F-WRITE.INDICATION\/} event.
1795: \begin{quote}\index{FTAMreadwrite}\small\begin{verbatim}
1796: struct FTAMreadwrite {
1797: int ftrw_operation;
1798:
1799: struct FADUidentity ftrw_identity;
1800:
1801: int ftrw_context;
1802: int ftrw_level;
1803:
1804: int ftrw_locking;
1805: };
1806: \end{verbatim}\end{quote}
1807: The elements of this structure are:
1808: \begin{describe}
1809: \item[\verb"ftrw\_operation":] the operation,
1810: one of the values shown in Table~\ref{FTAMdataops};
1811:
1812: \item[\verb"ftrw\_identity":] the FADU identity;
1813:
1814: \item[\verb"ftrw\_context"/\verb"ftrw\_level":] the access context,
1815: one of the values shown in Table~\ref{FTAMcontexts}
1816: ({\sf F-READ.INDICATION\/} only);
1817: and,
1818:
1819: \item[\verb"ftrw\_locking":] FADU locked.
1820: \end{describe}
1821: Note that the data contained in the structure was allocated via \man malloc(3),
1822: and should be released with the \verb"FTRWFREE" macro when no longer needed.
1823: The \verb"FTRWFREE" macro
1824: behaves as if it was defined as:
1825: \begin{quote}\index{FTRWFREE}\small\begin{verbatim}
1826: void FTRWFREE (ftrw)
1827: struct FTAMreadwrite *ftrw;
1828: \end{verbatim}\end{quote}
1829: The macro frees only the data allocated by \verb"FWaitRequest",
1830: and not the \verb"FTAMreadwrite" structure itself.
1831: \tagtable[tp]{ftam-4}{FTAM Data Operations}{FTAMdataops}
1832: \tagtable[tp]{ftam-3}{FTAM Access Contexts}{FTAMcontexts}
1833:
1834: \subsubsection {Data Indications}\label{ftam:data}
1835: When an event associated with user data occurs,
1836: the \verb"fti_type" field of the \verb"fti" parameter contains the value
1837: \verb"FTI_DATA",
1838: and an \verb"PSAPdata" structure
1839: (described in Chapter~\ref{libpsap2} of \voltwo/)
1840: is contained inside the \verb"fti" parameter,
1841: indicating an {\sf F-DATA.INDICATION\/} event.
1842: To distinguish between structure and contents,
1843: FTAM uses different presentation context identifiers.
1844: If the \verb"pe_context" field of any presentation element contains the value
1845: \verb"PE_DFLT_CONTEXT",
1846: then the element contains structuring information in the FTAM PCI,
1847: and the \verb"pe_id" element should be consulted to determine the particular
1848: structuring information being conveyed:
1849: \[\begin{tabular}{|l|l|}
1850: \hline
1851: \multicolumn{1}{|c|}{\bf Value}&
1852: \multicolumn{1}{c|}{\bf Meaning}\\
1853: \hline
1854: \tt FADU\_NODESCR& node descriptor data element\\
1855: \tt FADU\_ENTERTREE& enter subtree data element\\
1856: \tt FADU\_EXITREE& exit subtree data element\\
1857: \hline
1858: \end{tabular}\]
1859: Otherwise,
1860: the element contains file contents as defined in the PCI for the
1861: document type being transferred.
1862:
1863: \subsubsection {Data End Indication}
1864: When an event associated with the end of bulk data transfer occurs,
1865: the \verb"fti_type" field of the \verb"fti" parameter contains the value
1866: \verb"FTI_DATAEND".
1867: Further,
1868: an \verb"FTAMdataend" structure is contained inside the \verb"fti" parameter,
1869: indicating an {\sf F-DATA-END.INDICATION\/} event.
1870: \begin{quote}\index{FTAMdataend}\small\begin{verbatim}
1871: struct FTAMdataend {
1872: int ftda_action;
1873:
1874: int ftda_ndiag;
1875: struct FTAMdiagnostic ftda_diags[NFDIAG];
1876: };
1877: \end{verbatim}\end{quote}
1878: The elements of this structure are:
1879: \begin{describe}
1880: \item[\verb"ftda\_action":] the action result;
1881: and,
1882:
1883: \item[\verb"ftda\_diags"/\verb"ftda\_ndiag":] any diagnostic information
1884: (and the number of diagnostics present).
1885: \end{describe}
1886:
1887: \subsubsection {Cancel Indications}
1888: When an event associated with the cancellation of bulk data transfer occurs,
1889: the \verb"fti_type" field of the \verb"fti" parameter contains the value
1890: \verb"FTI_CANCEL".
1891: Further,
1892: an \verb"FTAMcancel" structure is contained inside the \verb"fti" parameter,
1893: indicating an {\sf F-CANCEL\/} event.
1894: \begin{quote}\index{FTAMcancel}\small\begin{verbatim}
1895: struct FTAMcancel {
1896: int ftcn_action;
1897:
1898: PE ftcn_sharedASE;
1899:
1900: int ftcn_ndiag;
1901: struct FTAMdiagnostic ftcn_diags[NFDIAG];
1902: };
1903: \end{verbatim}\end{quote}
1904: The elements of this structure are:
1905: \begin{describe}
1906: \item[\verb"ftcn\_action":] the action result;
1907:
1908: \item[\verb"ftcn\_sharedASE":] shared ASE information;
1909: and,
1910:
1911: \item[\verb"ftcn\_diags"/\verb"ftcn\_ndiag":] any diagnostic information
1912: (and the number of diagnostics present).
1913: \end{describe}
1914: Note that the data contained in the structure was allocated via \man malloc(3),
1915: and should be released with the \verb"FTCNFREE" macro when no longer needed.
1916: The \verb"FTCNFREE" macro
1917: behaves as if it was defined as:
1918: \begin{quote}\index{FTCNFREE}\small\begin{verbatim}
1919: void FTCNFREE (ftcn)
1920: struct FTAMcancel *ftcn;
1921: \end{verbatim}\end{quote}
1922: The macro frees only the data allocated by \verb"FWaitRequest",
1923: and not the \verb"FTAMcancel" structure itself.
1924:
1925: \subsubsection {Transfer End Indications}
1926: When an event associated with the termination of bulk data transfer occurs,
1927: the \verb"fti_type" field of the \verb"fti" parameter contains the value
1928: \verb"FTI_TRANSEND".
1929: Further,
1930: an \verb"FTAMtransend" structure is contained inside the \verb"fti" parameter,
1931: indicating an {\sf F-TRANSFER-END\/} event.
1932: \begin{quote}\index{FTAMtransend}\small\begin{verbatim}
1933: struct FTAMtransend {
1934: int ftre_action;
1935:
1936: PE ftre_sharedASE;
1937:
1938: int ftre_ndiag;
1939: struct FTAMdiagnostic ftre_diags[NFDIAG];
1940: };
1941: \end{verbatim}\end{quote}
1942: The elements of this structure are:
1943: \begin{describe}
1944: \item[\verb"ftre\_action":] the action result ({\sf .RESPONSE\/} only);
1945:
1946: \item[\verb"ftre\_sharedASE":] shared ASE information;
1947: and,
1948:
1949: \item[\verb"ftre\_diags"/\verb"ftre\_ndiag":] any diagnostic information
1950: (and the number of diagnostics present, {\sf .RESPONSE\/} only).
1951: \end{describe}
1952: Note that the data contained in the structure was allocated via \man malloc(3),
1953: and should be released with the \verb"FTREFREE" macro when no longer needed.
1954: The \verb"FTREFREE" macro
1955: behaves as if it was defined as:
1956: \begin{quote}\index{FTREFREE}\small\begin{verbatim}
1957: void FTREFREE (ftre)
1958: struct FTAMtransend *ftre;
1959: \end{verbatim}\end{quote}
1960: The macro frees only the data allocated by \verb"FWaitRequest",
1961: and not the \verb"FTAMtransend" structure itself.
1962:
1963: \subsection {Asynchronous Event Handling}
1964: Thus far the discussion on event handling has been synchronous in nature.
1965: Some users of FTAM may wish an asynchronous interface.
1966: The \verb"FSetIndications" routine is used to change the service associated
1967: with an association-descriptor to or from an asynchronous interface.
1968: \begin{quote}\index{FSetIndications}\small\begin{verbatim}
1969: int FSetIndications (sd, indication, fti)
1970: int sd;
1971: int (*indication) ();
1972: struct FTAMindication *fti;
1973: \end{verbatim}\end{quote}
1974: The parameters to this procedure are:
1975: \begin{describe}
1976: \item[\verb"sd":] the association-descriptor;
1977:
1978: \item[\verb"indication":] the address of an event-handler routine to be
1979: invoked when an indication occurs;
1980: and,
1981:
1982: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
1983: updated only if the call fails.
1984: \end{describe}
1985: If the service is to be made asynchronous,
1986: then the event handler is specified,
1987: otherwise,
1988: if the service is to be made synchronous,
1989: then the handler should not be specified
1990: (use the manifest constant \verb"NULLIFP").
1991: The most likely reason for the call failing is \verb"FS_GEN_WAITING",
1992: which indicates that an event is waiting for the user.
1993:
1994: When an event-handler is invoked,
1995: future invocations of the event-hander are blocked until it returns.
1996: The return value of the event-handler is ignored.
1997: Further,
1998: during the execution of a synchronous call to the library,
1999: the event-handler will be blocked from being invoked.
2000:
2001: When an event occurs,
2002: the event-handler routine is invoked with two parameters:
2003: \begin{quote}\small\begin{verbatim}
2004: (*indication) (sd, fti);
2005: int sd;
2006: struct FTAMindication *fti;
2007: \end{verbatim}\end{quote}
2008: The parameters are:
2009: \begin{describe}
2010: \item[\verb"sd":] the association-descriptor;
2011: and,
2012:
2013: \item[\verb"fti":] a pointer to the \verb"FTAMindication" structure containing
2014: the indication.
2015: \end{describe}
2016:
2017: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
2018: \bf NOTE:& The \man libftam(3n) library uses the SIGEMT signal to provide
2019: these services.
2020: Programs using asynchronous association-descriptors should NOT
2021: use SIGEMT for other purposes.
2022: \end{tabular}}\]
2023:
2024: \subsection {Synchronous Event Multiplexing}
2025: A user of FTAM may wish to manage multiple
2026: association-descriptors simultaneously;
2027: the routine \verb"FSelectMask" is provided for this purpose.
2028: This routine updates a file-descriptor mask and associated counter for use
2029: with \verb"xselect".
2030: \begin{quote}\index{FSelectMask}\small\begin{verbatim}
2031: int FSelectMask (sd, mask, nfds, fti)
2032: int sd;
2033: fd_set *mask;
2034: int *nfds;
2035: struct FTAMindication *fti;
2036: \end{verbatim}\end{quote}
2037: The parameters to this procedure are:
2038: \begin{describe}
2039: \item[\verb"sd":] the association-descriptor;
2040:
2041: \item[\verb"mask":] a pointer to a file-descriptor mask meaningful to
2042: \verb"xselect";
2043:
2044: \item[\verb"nfds":] a pointer to an integer-valued location meaningful to
2045: \verb"xselect";
2046: and,
2047:
2048: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is updated
2049: only if the call fails.
2050: \end{describe}
2051: If the call is successful, then the \verb"mask" and \verb"nfds" parameters can
2052: be used as arguments to \verb"xselect".
2053: The most likely reason for the call failing is \verb"FS_GEN_WAITING",
2054: which indicates that an event is waiting for the user.
2055:
2056: If \verb"xselect" indicates that the association-descriptor is ready for
2057: reading,
2058: \verb"FWaitRequest" should be called with the \verb"secs" parameter equal to
2059: \verb"OK".
2060: If the network activity does not constitute an entire event for the user,
2061: then \verb"FWaitRequest" will return \verb"NOTOK" with error code
2062: \verb"FS_PRO_TIMEOUT".
2063:
2064: \subsection {Tracing}\label{ftam:tracing}
2065: Users may wish to trace FTAM events as they are processed.
2066: The routine \verb"FHookRequest" is used to set (or unset) the user-defined
2067: tracing routine.
2068: \begin{quote}\index{FHookRequest}\small\begin{verbatim}
2069: int FHookRequest (sd, tracing, fti)
2070: int sd;
2071: int (*tracing) ();
2072: \end{verbatim}\end{quote}
2073: The parameters to this procedure are:
2074: \begin{describe}
2075: \item[\verb"sd":] the association-descriptor;
2076:
2077: \item[\verb"tracing":] the address of a tracing routine to be invoked when an
2078: FTAM event occurs;
2079: and,
2080:
2081: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is updated
2082: only if the call fails.
2083: \end{describe}
2084: If tracing is to be enabled,
2085: then the tracing routine is specified,
2086: otherwise,
2087: if tracing is to be turned off, the manifest constant \verb"NULLIFP" should
2088: be used.
2089:
2090: When an event occurs,
2091: the tracing routine is invoked with five parameters:
2092: \begin{quote}\small\begin{verbatim}
2093: (*tracing) (sd, event, fpdu, pe, rw)
2094: \end{verbatim}\end{quote}
2095: The parameters are:
2096: \begin{describe}
2097: \item[\verb"sd":] the association-descriptor;
2098:
2099: \item[\verb"event":] the name of the underlying service primitive
2100: (association control or presentation) associated with the FTAM event;
2101:
2102: \item[\verb"fpdu":] the name of the FTAM PDU, if any;
2103:
2104: \item[\verb"pe":] a presentation element containing the FTAM PDU
2105: associated with the FTAM event
2106: (described in Chapter~\ref{libpsap} of \volone/), if any;
2107: and,
2108:
2109: \item[\verb"rw":] a flag saying whether the event is being initiated (zero)
2110: or being received (non-zero).
2111: \end{describe}
2112: The return value of the tracing routine is ignored.
2113:
2114: One pre-defined tracing routine is available, \verb"FTraceHook"
2115: \index{FHookRequest},
2116: which simply appends tracing information to the log determined by
2117: \begin{quote}\index{ftamfile}\small\begin{verbatim}
2118: LLog *ftam_log;
2119: \end{verbatim}\end{quote}
2120: See Chapter~\ref{logging} in \voltwo/ for all the details.
2121:
2122: \section {Grouped Operations: File Transfer}
2123: The \verb"FBulkBeginRequest" routine is used to issue a grouped file transfer
2124: request consisting of:
2125: \begin{itemize}
2126: \item {\sf F-BEGIN-GROUP.REQUEST\/};
2127:
2128: \item {\sf F-SELECT.REQUEST\/} or {\sf F-CREATE.REQUEST\/};
2129:
2130: \item optionally, {\sf F-READ-ATTRIB.REQUEST\/};
2131:
2132: \item optionally, {\sf F-CHANGE-ATTRIB.REQUEST\/};
2133:
2134: \item {\sf F-OPEN.REQUEST\/};
2135: and,
2136:
2137: \item {\sf F-END-GROUP.REQUEST}.
2138: \end{itemize}
2139: The user initializes an \verb"FTAMgroup" structure
2140: (described in tedious detail on page~\pageref{FTAMgroup})
2141: and then invokes \verb"FBulkRequest".
2142: \begin{quote}\index{FBulkRequest}\small\begin{verbatim}
2143: int FBulkRequest (sd, ftg, fti)
2144: int sd;
2145: struct FTAMgroup *ftg;
2146: struct FTAMindication *fti;
2147: \end{verbatim}\end{quote}
2148: The parameters to this procedure are:
2149: \begin{describe}
2150: \item[\verb"sd":] the association-descriptor;
2151:
2152: \item[\verb"ftg":] a pointer to an \verb"FTAMgroup" structure;
2153: and,
2154:
2155: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2156: always updated.
2157: \end{describe}
2158: If the call to \verb"FBulkBeginRequest" is successful,
2159: then this corresponds to the appropriate {\sf .CONFIRMATION\/} events,
2160: the \verb"fti_type" element of the \verb"fti" parameter is set to
2161: \verb"FTI_BULKBEGIN",
2162: and the \verb"fti_group" element contains the results.
2163: Note that the data contained in the structure was allocated via \man malloc(3),
2164: and should be released with the \verb"FTGFREE" macro when no longer needed.
2165:
2166: Otherwise if the call fails,
2167: the \verb"FTAMabort" structure contained in the
2168: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2169:
2170: Upon receiving an \verb"FTI_BULKBEGIN" indication,
2171: containing the appropriate {\sf .INDICATION\/} events,
2172: the responder is required to generate the appropriate {\sf .RESPONSE\/}
2173: events using the \verb"FBulkBeginResponse" routine.
2174: \begin{quote}\index{FBulkResponse}\small\begin{verbatim}
2175: int FBulkBeginResponse (sd, ftg, fti)
2176: int sd;
2177: struct FTAMgroup *ftg;
2178: struct FTAMindication *fti;
2179: \end{verbatim}\end{quote}
2180: The parameters to this procedure are:
2181: \begin{describe}
2182: \item[\verb"sd":] the association-descriptor;
2183:
2184: \item[\verb"ftg":] a pointer to an \verb"FTAMgroup" structure;
2185: and,
2186:
2187: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2188: updated only if the call fails.
2189: \end{describe}
2190: If the call fails,
2191: the \verb"FTAMabort" structure contained in the
2192: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2193:
2194: The \verb"FBulkEndRequest" routine is used to issue a grouped file transfer
2195: request consisting of:
2196: \begin{itemize}
2197: \item {\sf F-BEGIN-GROUP.REQUEST\/};
2198:
2199: \item {\sf F-CLOSE.REQUEST\/};
2200:
2201: \item {\sf F-DESELECT.REQUEST\/} or {\sf F-DELETE.REQUEST\/};
2202: and,
2203:
2204: \item {\sf F-END-GROUP.REQUEST}.
2205: \end{itemize}
2206: The user initializes an \verb"FTAMgroup" structure
2207: (described in tedious detail on page~\pageref{FTAMgroup})
2208: and then invokes \verb"FBulkEndRequest".
2209: \begin{quote}\index{FBulkEndRequest}\small\begin{verbatim}
2210: int FBulkEndRequest (sd, ftg, fti)
2211: int sd;
2212: struct FTAMgroup *ftg;
2213: struct FTAMindication *fti;
2214: \end{verbatim}\end{quote}
2215: The parameters to this procedure are:
2216: \begin{describe}
2217: \item[\verb"sd":] the association-descriptor;
2218:
2219: \item[\verb"ftg":] a pointer to an \verb"FTAMgroup" structure;
2220: and,
2221:
2222: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2223: always updated.
2224: \end{describe}
2225: If the call to \verb"FBulkEndRequest" is successful,
2226: then this corresponds to the appropriate {\sf .CONFIRMATION\/} events,
2227: the \verb"fti_type" element of the \verb"fti" parameter is set to
2228: \verb"FTI_BULKEND",
2229: and the \verb"fti_group" element contains the results.
2230: Note that the data contained in the structure was allocated via \man malloc(3),
2231: and should be released with the \verb"FTGFREE" macro when no longer needed.
2232:
2233: Otherwise if the call fails,
2234: the \verb"FTAMabort" structure contained in the
2235: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2236:
2237: Upon receiving an \verb"FTI_BULKEND" indication,
2238: containing the appropriate {\sf .INDICATION\/} events,
2239: the responder is required to generate the appropriate {\sf .RESPONSE\/}
2240: events using the \verb"FBulkEndResponse" routine.
2241: \begin{quote}\index{FBulkEndResponse}\small\begin{verbatim}
2242: int FBulkEndResponse (sd, ftg, fti)
2243: int sd;
2244: struct FTAMgroup *ftg;
2245: struct FTAMindication *fti;
2246: \end{verbatim}\end{quote}
2247: The parameters to this procedure are:
2248: \begin{describe}
2249: \item[\verb"sd":] the association-descriptor;
2250:
2251: \item[\verb"ftg":] a pointer to an \verb"FTAMgroup" structure;
2252: and,
2253:
2254: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2255: updated only if the call fails.
2256: \end{describe}
2257: If the call fails,
2258: the \verb"FTAMabort" structure contained in the
2259: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2260:
2261: \section {File Access}
2262: The \verb"FAccessRequest" routine is equivalent to an {\sf F-LOCATE.REQUEST\/}
2263: or {\sf F-ERASE.REQUEST\/} action on the part of the user.
2264: \begin{quote}\index{FAccessRequest}\small\begin{verbatim}
2265: int FAccessRequest (sd, operation, identity, fti)
2266: int sd;
2267: int operation;
2268: struct FADUidentity *identity;
2269: struct FTAMindication *fti;
2270: \end{verbatim}\end{quote}
2271: The parameters to this procedure are:
2272: \begin{describe}
2273: \item[\verb"sd":] the association-descriptor;
2274:
2275: \item[\verb"operation":] the operation to be performed,
2276: one of the values shown in Table~\ref{FTAMaccessops};
2277:
2278: \item[\verb"identity":] the identity of the FADU to locate or erase;
2279: and,
2280:
2281: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2282: always updated.
2283: \end{describe}
2284: If the call to \verb"FAccessRequest" is successful,
2285: then this corresponds to the appropriate {\sf .CONFIRMATION\/} event,
2286: the \verb"fti_type" element of the \verb"fti" parameter is set to
2287: \verb"FTI_ACCESS",
2288: and the \verb"fti_access" element contains the results.
2289: Note that the data contained in the structure was allocated via \man malloc(3),
2290: and should be released with the \verb"FTACFREE" macro when no longer needed.
2291:
2292: Otherwise if the call fails,
2293: the \verb"FTAMabort" structure contained in the
2294: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2295:
2296: Upon receiving an {\sf F-LOCATE.INDICATION\/}
2297: or an {\sf F-ERASE.IN\-DI\-CA\-TION\/}
2298: event,
2299: the user is required to generate the appropriate {\sf .RESPONSE\/} action
2300: using the \verb"FAccessResponse" routine.
2301: \begin{quote}\index{FAccessResponse}\small\begin{verbatim}
2302: int FAccessResponse (sd, action, identity, diag, ndiag,
2303: fti)
2304: int sd;
2305: int action;
2306: struct FADUidentity *identity;
2307: struct FTAMdiagnostic diag[];
2308: int ndiag;
2309: struct FTAMindication *fti;
2310: \end{verbatim}\end{quote}
2311: The parameters to this procedure are:
2312: \begin{describe}
2313: \item[\verb"sd":] the association-descriptor;
2314:
2315: \item[\verb"action":] the action result;
2316:
2317: \item[\verb"identity":] the identity of the FADU located
2318: (not present for the {\sf F-ERASE.RESPONSE\/} action);
2319:
2320: \item[\verb"diag"/\verb"ndiag":] a list of diagnostics
2321: (and the number of diagnostics in the list);
2322: and,
2323:
2324: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2325: updated only if the call fails.
2326: \end{describe}
2327: If the call to \verb"AccessResponse" is successful,
2328: then the {\sf .RESPONSE\/} event has been queued for sending to the
2329: initiator.
2330: Otherwise the \verb"FTAMabort" structure contained in the
2331: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2332:
2333: \section {Data Transfer}
2334: Once group file transfer request has been made,
2335: and after any file access requests,
2336: data transfer may occur.
2337: This occurs in three steps:
2338: the initiator requests reading or writing of an FADU,
2339: the source sends the data,
2340: the transfer is then either cancelled (by either side) or terminated by the
2341: initiator.
2342:
2343: \subsection {Read/Write}
2344: The \verb"FReadWriteRequest" routine is equivalent to a {\sf
2345: F-READ.REQUEST\/} or {\sf F-WRITE.REQUEST\/} action on the part of the user.
2346: \begin{quote}\index{FReadWriteRequest}\small\begin{verbatim}
2347: int FReadWriteRequest (sd, operation, identity, context,
2348: level, lock, fti)
2349: int sd;
2350: int operation;
2351: struct FADUidentity *identity;
2352: int context,
2353: level,
2354: lock;
2355: struct FTAMindication *fti;
2356: \end{verbatim}\end{quote}
2357: The parameters to this procedure are:
2358: \begin{describe}
2359: \item[\verb"sd":] the association-descriptor;
2360:
2361: \item[\verb"operation":] the operation to be performed,
2362: one of the values shown in Table~\ref{FTAMdataops} on
2363: page~\pageref{FTAMdataops};
2364:
2365: \item[\verb"identity":] the identity of the FADU to be transferred;
2366:
2367: \item[\verb"context"/\verb"level":] the access context,
2368: one of the values shown in Table~\ref{FTAMcontexts};
2369:
2370: \item[\verb"lock":] lock FADU;
2371: and,
2372:
2373: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2374: updated only if the call fails.
2375: \end{describe}
2376: If the call fails,
2377: the \verb"FTAMabort" structure contained in the
2378: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2379:
2380: \subsection {Sending Data}
2381: The FADU is transmitted as a series of presentation elements.
2382: A group of presentation elements may be sent using the \verb"FDataRequest"
2383: routine,
2384: which corresponds to the {\sf F-DATA.REQUEST\/} action.
2385: \begin{quote}\index{FDataRequest}\small\begin{verbatim}
2386: int FDataRequest (sd, fadus, nfadu, fti)
2387: int sd;
2388: PE fadus[];
2389: int nfadu;
2390: struct FTAMindication *fti;
2391: \end{verbatim}\end{quote}
2392: The parameters to this procedure are:
2393: \begin{describe}
2394: \item[\verb"sd":] the association-descriptor;
2395:
2396: \item[\verb"fadus"/\verb"nfadu":] the list of data elements
2397: (and the number of data elements which may not exceed the manifest constant
2398: \verb"NPDATA" described in Chapter~\ref{libpsap2}),
2399: consult Section~\ref{ftam:data} on page~\pageref{ftam:data} for important
2400: information on the use of presentation context identifiers;
2401: and,
2402:
2403: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2404: updated only if the call fails.
2405: \end{describe}
2406: If the call fails,
2407: the \verb"FTAMabort" structure contained in the
2408: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2409:
2410: When the last data element in the FADU has been sent,
2411: the {\sf F-DATA-END.REQUEST\/} action should be performed
2412: using the \verb"FDataEndRequest" routine.
2413: \begin{quote}\index{FDataEndRequest}\small\begin{verbatim}
2414: int FDataEndRequest (sd, action, diag, ndiag, fti)
2415: int sd;
2416: int action;
2417: struct FTAMdiagnostic diag[];
2418: int ndiag;
2419: struct FTAMindication *fti;
2420: \end{verbatim}\end{quote}
2421: The parameters to this procedure are:
2422: \begin{describe}
2423: \item[\verb"sd":] the association-descriptor;
2424:
2425: \item[\verb"action":] the action result;
2426:
2427: \item[\verb"diag"/\verb"ndiag":] a list of diagnostics
2428: (and the number of diagnostics in the list);
2429: and,
2430:
2431: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2432: updated only if the call fails.
2433: \end{describe}
2434: If the call fails,
2435: the \verb"FTAMabort" structure contained in the
2436: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2437:
2438: \subsection {Canceling Transfer}
2439: Either the initiator or the responder may cancel the transfer prior to
2440: orderly termination of the data transfer.
2441: The \verb"FCancelRequest",
2442: which corresponds to the {\sf F-CANCEL.REQUEST\/} action,
2443: is used to initiate cancellation.
2444: \begin{quote}\index{FCancelRequest}\small\begin{verbatim}
2445: int FCancelRequest (sd, action, sharedASE, diag, ndiag,
2446: fti)
2447: int sd;
2448: int action;
2449: PE sharedASE;
2450: struct FTAMdiagnostic diag[];
2451: int ndiag;
2452: struct FTAMindication *fti;
2453: \end{verbatim}\end{quote}
2454: The parameters to this procedure are:
2455: \begin{describe}
2456: \item[\verb"sd":] the association-descriptor;
2457:
2458: \item[\verb"action":] the action result;
2459:
2460: \item[\verb"sharedASE":] shared ASE information;
2461:
2462: \item[\verb"diag"/\verb"ndiag":] a list of diagnostics
2463: (and the number of diagnostics in the list);
2464: and,
2465:
2466: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2467: always updated.
2468: \end{describe}
2469: If the call to \verb"FCancelRequest" is successful,
2470: then this corresponds to the {\sf F-CANCEL.CONFIRMATION\/} event,
2471: the \verb"fti_type" element of the \verb"fti" parameter is set to
2472: \verb"FTI_CANCEL",
2473: and the \verb"fti_cancel" element contains the results.
2474:
2475: Otherwise if the call fails,
2476: the \verb"FTAMabort" structure contained in the
2477: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2478:
2479: Upon receiving an {\sf F-CANCEL.INDICATION\/} event,
2480: the user is required to generate the {\sf F-CANCEL.RESPONSE\/}
2481: events using the \verb"FCancelResponse" routine.
2482: \begin{quote}\index{FCancelResponse}\small\begin{verbatim}
2483: int FCancelResponse (sd, action, sharedASE, diag, ndiag,
2484: fti)
2485: int sd;
2486: int action;
2487: PE sharedASE;
2488: struct FTAMdiagnostic diag[];
2489: int ndiag;
2490: struct FTAMindication *fti;
2491: \end{verbatim}\end{quote}
2492: The parameters to this procedure are:
2493: \begin{describe}
2494: \item[\verb"sd":] the association-descriptor;
2495:
2496: \item[\verb"action":] the action result;
2497:
2498: \item[\verb"sharedASE":] shared ASE information;
2499:
2500: \item[\verb"diag"/\verb"ndiag":] a list of diagnostics
2501: (and the number of diagnostics in the list);
2502: and,
2503:
2504: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2505: updated only if the call fails.
2506: \end{describe}
2507: If the call fails,
2508: the \verb"FTAMabort" structure contained in the
2509: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2510:
2511: \subsection {Terminating Transfer}
2512: After generating the {\sf F-DATA-END.REQUEST\/}
2513: (or after receiving the {\sf F-DATA-END.RESPONSE\/}) action,
2514: the initiator is required to perform the {\sf F-TRANSFER-END.REQUEST\/}
2515: action using the \verb"FTransEndRequest" routine.
2516: \begin{quote}\index{FTransEndRequest}\small\begin{verbatim}
2517: int FTransEndRequest (sd, sharedASE, fti)
2518: int sd;
2519: PE sharedASE;
2520: struct FTAMindication *fti;
2521: \end{verbatim}\end{quote}
2522: The parameters to this procedure are:
2523: \begin{describe}
2524: \item[\verb"sd":] the association-descriptor;
2525:
2526: \item[\verb"sharedASE":] shared ASE information;
2527: and,
2528:
2529: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2530: always updated.
2531: \end{describe}
2532: If the call to \verb"FTransEndRequest" is successful,
2533: then this corresponds to the {\sf F-TRANSFER-END.CONFIRMATION\/} event,
2534: the \verb"fti_type" element of the \verb"fti" parameter is set to
2535: \verb"FTI_TRANSEND",
2536: and the \verb"fti_transend" element contains the results.
2537:
2538: Otherwise, if the call fails,
2539: the \verb"FTAMabort" structure contained in the
2540: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2541:
2542: Upon receiving an {\sf F-TRANSFER-END.INDICATION\/} event,
2543: the responder is required to generate the {\sf F-TRANSFER-END.RESPONSE\/}
2544: events using the \verb"FTransEndResponse" routine.
2545: \begin{quote}\index{FTransEndResponse}\small\begin{verbatim}
2546: int FTransEndResponse (sd, action, sharedASE, diag, ndiag,
2547: fti)
2548: int sd;
2549: int action;
2550: PE sharedASE;
2551: struct FTAMdiagnostic diag[];
2552: int ndiag;
2553: struct FTAMindication *fti;
2554: \end{verbatim}\end{quote}
2555: The parameters to this procedure are:
2556: \begin{describe}
2557: \item[\verb"sd":] the association-descriptor;
2558:
2559: \item[\verb"action":] the action result;
2560:
2561: \item[\verb"sharedASE":] shared ASE information;
2562:
2563: \item[\verb"diag"/\verb"ndiag":] a list of diagnostics
2564: (and the number of diagnostics in the list);
2565: and,
2566:
2567: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2568: updated only if the call fails.
2569: \end{describe}
2570: If the call fails,
2571: the \verb"FTAMabort" structure contained in the
2572: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2573:
2574: \section {Grouped Operations: File Management}
2575: The \verb"FManageRequest" routine is used to issue a grouped management
2576: request consisting of:
2577: \begin{itemize}
2578: \item {\sf F-BEGIN-GROUP.REQUEST\/};
2579:
2580: \item {\sf F-SELECT.REQUEST\/} or {\sf F-CREATE.REQUEST\/};
2581:
2582: \item optionally, {\sf F-READ-ATTRIB.REQUEST\/};
2583:
2584: \item optionally, {\sf F-CHANGE-ATTRIB.REQUEST\/};
2585:
2586: \item {\sf F-DESELECT.REQUEST\/} or {\sf F-DELETE.REQUEST\/};
2587: and,
2588:
2589: \item {\sf F-END-GROUP.REQUEST}.
2590: \end{itemize}
2591: The user initializes an \verb"FTAMgroup" structure
2592: (described in tedious detail on page~\pageref{FTAMgroup})
2593: and then invokes \verb"FManageRequest".
2594: \begin{quote}\index{FManageRequest}\small\begin{verbatim}
2595: int FManageRequest (sd, ftg, fti)
2596: int sd;
2597: struct FTAMgroup *ftg;
2598: struct FTAMindication *fti;
2599: \end{verbatim}\end{quote}
2600: The parameters to this procedure are:
2601: \begin{describe}
2602: \item[\verb"sd":] the association-descriptor;
2603:
2604: \item[\verb"ftg":] a pointer to an \verb"FTAMgroup" structure;
2605: and,
2606:
2607: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2608: always updated.
2609: \end{describe}
2610: If the call to \verb"FManageRequest" is successful,
2611: then this corresponds to the appropriate {\sf .CONFIRMATION\/} events,
2612: the \verb"fti_type" element of the \verb"fti" parameter is set to
2613: \verb"FTI_MANAGEMENT",
2614: and the \verb"fti_group" element contains the results.
2615: Note that the data contained in the structure was allocated via \man malloc(3),
2616: and should be released with the \verb"FTGFREE" macro when no longer needed.
2617:
2618: Otherwise if the call fails,
2619: the \verb"FTAMabort" structure contained in the
2620: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2621:
2622: Upon receiving an \verb"FTI_MANAGEMENT" indication,
2623: containing the appropriate {\sf .INDICATION\/} events,
2624: the responder is required to generate the appropriate {\sf .RESPONSE\/}
2625: events using the \verb"FManageResponse" routine.
2626: \begin{quote}\index{FManageResponse}\small\begin{verbatim}
2627: int FManageResponse (sd, ftg, fti)
2628: int sd;
2629: struct FTAMgroup *ftg;
2630: struct FTAMindication *fti;
2631: \end{verbatim}\end{quote}
2632: The parameters to this procedure are:
2633: \begin{describe}
2634: \item[\verb"sd":] the association-descriptor;
2635:
2636: \item[\verb"ftg":] a pointer to an \verb"FTAMgroup" structure;
2637: and,
2638:
2639: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2640: updated only if the call fails.
2641: \end{describe}
2642: If the call fails,
2643: the \verb"FTAMabort" structure contained in the
2644: \verb"FTAMindication" parameter \verb"fti" contains the reason for the failure.
2645:
2646: \section {Association Release}
2647: The \verb"FTerminateRequest" routine is used to request the release of an
2648: association,
2649: and corresponds to an {\sf F-TERMINATE.REQUEST\/} action.
2650: \begin{quote}\index{FTerminateRequest}\small\begin{verbatim}
2651: int FTerminateRequest (sd, sharedASE, ftr, fti)
2652: int sd;
2653: PE sharedASE;
2654: struct FTAMrelease *ftr;
2655: struct FTAMindication *fti;
2656: \end{verbatim}\end{quote}
2657: \newpage %%% yikes!
2658: The parameters to this procedure are:
2659: \begin{describe}
2660: \item[\verb"sd":] the association-descriptor;
2661:
2662: \item[\verb"sharedASE":] shared ASE information;
2663:
2664: \item[\verb"ftr":] a pointer to an \verb"FTAMrelease" structure, which is
2665: updated only if the call succeeds;
2666: and,
2667:
2668: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2669: updated only if the call fails.
2670: \end{describe}
2671: If the call to \verb"FTerminateRequest" is successful,
2672: then this corresponds to an {\sf F-TERMINATE.CONFIRMATION\/} event,
2673: and it returns information in the \verb"ftr" parameter,
2674: which is a pointer to an \verb"FTAMrelease" structure.
2675: \begin{quote}\index{FTAMrelease}\small\begin{verbatim}
2676: struct FTAMrelease {
2677: PE ftr_sharedASE;
2678:
2679: struct FTAMcharging ftr_charges;
2680: };
2681: \end{verbatim}\end{quote}
2682: The elements of this structure are:
2683: \begin{describe}
2684: \item[\verb"ftr\_sharedASE":] shared ASE information;
2685: and,
2686:
2687: \item[\verb"ftr\_charges":] any charges.
2688: \end{describe}
2689: Note that the data contained in the structure was allocated via \man malloc(3),
2690: and should be released with the \verb"FTRFREE" macro when no longer needed.
2691: The \verb"FTRFREE" macro
2692: behaves as if it was defined as:
2693: \begin{quote}\index{FTRFREE}\small\begin{verbatim}
2694: void FTRFREE (ftr)
2695: struct FTAMrelease *ftr;
2696: \end{verbatim}\end{quote}
2697: The macro frees only the data allocated by \verb"FTerminateRequest",
2698: and not the \verb"FTAMrelease" structure itself.
2699: Further,
2700: \verb"FTRFREE" should be called only if the call to the
2701: \verb"FTerminateRequest" routine returned \verb"OK".
2702:
2703: If the call to \verb"FTerminateRequest" is successful,
2704: then the association has been released.
2705: Otherwise the \verb"FTAMabort" structure contained in
2706: the \verb"FTAMindication" parameter
2707: \verb"fti" contains the reason for failure.
2708:
2709: Upon receiving an {\sf F-TERMINATE.INDICATION\/} event,
2710: the user is required to generate an {\sf F-TERMINATE.RESPONSE\/} action
2711: using the\\ %%% hack
2712: \verb"FTerminateResponse" routine.
2713: \begin{quote}\index{FTerminateResponse}\small\begin{verbatim}
2714: int FTerminateResponse (sd, sharedASE, charging, fti)
2715: int sd;
2716: PE sharedASE;
2717: struct FTAMcharging *charging;
2718: struct FTAMindication *fti;
2719: \end{verbatim}\end{quote}
2720: The parameters to this procedure are:
2721: \begin{describe}
2722: \item[\verb"sd":] the association-descriptor;
2723:
2724: \item[\verb"sharedASE":] shared ASE information;
2725:
2726: \item[\verb"charging":] charging information (if any);
2727: and,
2728:
2729: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2730: updated only if the call fails.
2731: \end{describe}
2732: If the call to \verb"FTerminateResponse" is successful,
2733: then the association has been released.
2734:
2735: \section {Association Abort}
2736: The \verb"FUAbortRequest" routine is used to request the ungraceful release
2737: of an association,
2738: and corresponds to an {\sf F-U-ABORT.REQUEST\/} action.
2739: \begin{quote}\index{FUAbortRequest}\small\begin{verbatim}
2740: int FUAbortRequest (sd, action, diag, ndiag, fti)
2741: int sd;
2742: int action;
2743: struct FTAMdiagnostic diag[];
2744: int ndiag;
2745: struct FTAMindication *fti;
2746: \end{verbatim}\end{quote}
2747: The parameters to this procedure are:
2748: \begin{describe}
2749: \item[\verb"sd":] the association-descriptor;
2750:
2751: \item[\verb"action":] an action result;
2752:
2753: \item[\verb"diag"/\verb"ndiag":] a list of diagnostics
2754: (and the number of diagnostics in the list);
2755: and,
2756:
2757: \item[\verb"fti":] a pointer to an \verb"FTAMindication" structure, which is
2758: updated only if the call fails.
2759: \end{describe}
2760: If the call to \verb"FUAbortRequest" is successful,
2761: then the connection is immediately closed,
2762: and any data queued for the connection may be lost.
2763:
2764: \section {Error Conventions}
2765: All of the routines in this library return the manifest constant \verb"NOTOK"
2766: on error,
2767: and also update the \verb"fti" parameter given to the routine.
2768: The \verb"fti_abort" element of the \verb"FTAMindication" structure contains a
2769: \verb"FTAMabort" structure detailing the reason for the failure.
2770: For each diagnostic present (typically only one) in the \verb"FTAMabort"
2771: structure,
2772: the \verb"ftd_identifier" element of each diagnostic can be given as a
2773: parameter to the procedure \verb"FErrString" which returns a null-terminated
2774: diagnostic string.
2775: \begin{quote}\index{FErrString}\small\begin{verbatim}
2776: char *FErrString (c)
2777: int c;
2778: \end{verbatim}\end{quote}
2779:
2780: \section {Compiling and Loading}
2781: Programs using the \man libftam(3n) library should include
2782: \verb"<isode/ftam.h>".
2783: These programs should also be loaded with \verb"-lftam" and \verb"-lisode".
2784:
2785: \section {An Example}
2786: Read Section~\ref{unixftam:code} on page~\pageref{unixftam:code}.
2787:
2788: \section {For Further Reading}
2789: The ISO specification for the International Standard on
2790: File Transfer, Access, and Management is found in \cite{ISO.FTAM},
2791: which is a four-part document.
2792:
2793: %%% \section {Changes Since the Last Release}\label{ftam:changes}
2794: %%% A brief summary of the major changes between v~\ftamprevrsn/ and
2795: %%% v~\ftamvrsn/ are now presented.
2796: %%% These are the user-visible changes only;
2797: %%% changes of a strictly internal nature are not discussed.
2798:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.