Return to libftam.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/libftam.tex, revision 1.1

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.