home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / DevCon / Atlanta_1990 / Atlanta-Devcon.2 / Libraries / IFFParse / Docs / iffparse.doc next >
Encoding:
Text File  |  1992-08-26  |  37.7 KB  |  1,349 lines
  1.     NAME
  2.     AllocIFF -- create a new IFFHandle structure.
  3.  
  4.     SYNOPSIS
  5.     iff = AllocIFF ()
  6.     d0
  7.  
  8.     struct IFFHandle *iff;
  9.  
  10.     FUNCTION
  11.     Allocates a new IFFHandle structure and initializes the basic values.
  12.     This function is the only supported way to create an IFFHandle
  13.     structure since there are private fields that need to be initialized.
  14.  
  15.     RESULTS
  16.     iff    - pointer to IFFHandle structure or NULL if the allocation
  17.           failed.
  18.  
  19.     SEE ALSO
  20.     FreeIFF
  21.  
  22.     NAME
  23.     AllocLocalItem -- create a local context item structure.
  24.  
  25.     SYNOPSIS
  26.     item = AllocLocalItem (type, id, ident, usize)
  27.      d0                     d0   d1   d2     d3
  28.  
  29.     struct LocalContextItem *item;
  30.     LONG type, id, ident, usize;
  31.  
  32.     FUNCTION
  33.     Allocates and initializes a LocalContextItem structure with "usize"
  34.     bytes of associated user data.  This is the only supported way to
  35.     create such an item.  The user data can be accessed with the
  36.     LocalItemData function.  An item created with this function
  37.     automatically has its purge vectors set up correctly to dispose of
  38.     itself and its associated user data area.  Any additional cleanup
  39.     should be done with a user-supplied purge vector.
  40.  
  41.     INPUTS
  42.     type,id    - additional longword identification values.
  43.     ident    - longword identifier for class of context item.
  44.     usize    - number of bytes of user data to allocate for this item.
  45.  
  46.     RESULTS
  47.     item    - pointer to initialized LocalContextItem or NULL if the
  48.           allocation failed.
  49.  
  50.     SEE ALSO
  51.     FreeLocalItem, LocalItemData, StoreLocalItem, StoreItemInContext,
  52.     SetLocalItemPurge
  53.  
  54.     NAME
  55.     CloseClipboard -- close and free an open ClipboardHandle.
  56.  
  57.     SYNOPSIS
  58.     CloseClipboard (clip)
  59.                      a0
  60.  
  61.     struct ClipboardHandle *clip;
  62.  
  63.     FUNCTION
  64.     Closes the clipboard.device and frees the ClipboardHandle structure.
  65.  
  66.     INPUTS
  67.     clip    - pointer to ClipboardHandle struct created with
  68.           OpenClipboard. 
  69.  
  70.     SEE ALSO
  71.     OpenClipboard, InitIFFasClip
  72.  
  73.     NAME
  74.     CloseIFF -- close an IFF context.
  75.  
  76.     SYNOPSIS
  77.     CloseIFF (iff)
  78.               a0
  79.  
  80.     struct IFFHandle *iff;
  81.  
  82.     FUNCTION
  83.     Completes an IFF read or write operation by closing the IFF context
  84.     established for this IFFHandle struct.  The IFFHandle struct itself
  85.     is left ready for re-use and a new context can be opened with
  86.     OpenIFF().  This function can be used for cleanup if a read or write
  87.     fails partway through.
  88.  
  89.     As part of its cleanup operation, CloseIFF() calls the client-
  90.     supplied stream hook vector.  This operation is not allowed to fail;
  91.     any error code returned will be ignored (best to return 0, though).
  92.     The IFFStreamCmd packet will be set as follows:
  93.  
  94.         sc_Command:    IFFCMD_CLEANUP
  95.         sc_Buf:        (Not applicable)
  96.         sc_NBytes:    (Not applicable)
  97.  
  98.     This operation is NOT permitted to fail;  any error code returned
  99.     will be ignored.  DO NOT write to this structure.
  100.  
  101.     INPUTS
  102.     iff    - pointer to IFFHandle struct previously opened with
  103.           OpenIFF().
  104.  
  105.     SEE ALSO
  106.     OpenIFF, InitIFF
  107.  
  108.     NAME
  109.     CollectionChunk -- declare a chunk type for collection.
  110.  
  111.     SYNOPSIS
  112.     error = CollectionChunk (iff, type, id)
  113.      d0                      a0    d0   d1
  114.  
  115.     LONG error;
  116.     struct IFFHandle *iff;
  117.     LONG type;
  118.     LONG id;
  119.  
  120.     FUNCTION
  121.     Installs an entry handler for chunks with the given type and id so
  122.     that the contents of those chunks will be stored as they are
  123.     encountered.  This is like PropChunk() except that more than one
  124.     chunk of this type can be stored in lists which can be returned by
  125.     FindCollection().  The storage of these chunks still follows the
  126.     property chunk scoping rules for IFF files so that at any given
  127.     point, stored collection chunks will be valid in the current context.
  128.  
  129.     INPUTS
  130.     iff    - pointer to IFFHandle struct (does not need to be open).
  131.     type    - type code for the chunk to declare (ex. "ILBM").
  132.     id    - identifier for the chunk to declare (ex. "CRNG").
  133.  
  134.     RESULTS
  135.     error    - 0 if successful or an IFFERR_#? error code if not
  136.           successful.
  137.  
  138.     SEE ALSO
  139.     CollectionChunks, FindCollection, PropChunk
  140.  
  141.     NAME
  142.     CollectionChunks -- declare many collection chunks at once.
  143.  
  144.     SYNOPSIS
  145.     error = CollectionChunks (iff, list, n)
  146.      d0                       a0    a1  d0
  147.  
  148.     LONG error;
  149.     struct IFFHandle *iff;
  150.     LONG *list;
  151.     LONG n;
  152.  
  153.     FUNCTION
  154.     Declares multiple collection chunks from a list.  The list argument
  155.     is a pointer to an array of long words arranged in pairs.  The format
  156.     for the list is as follows:
  157.  
  158.         TYPE1, ID1, TYPE2, ID2, ..., TYPEn, IDn
  159.  
  160.     The argument n is the number of pairs.  CollectionChunks() just calls
  161.     CollectionChunk() n times.
  162.  
  163.     INPUTS
  164.     iff    - pointer to IFFHandle struct.
  165.     list    - pointer to array of longword chunk types and identifiers.
  166.     n    - number of chunks to declare.
  167.  
  168.     RESULTS
  169.     error    - 0 if successful or an IFFERR_#? error code if not
  170.           successful.
  171.  
  172.     SEE ALSO
  173.     CollectionChunk
  174.  
  175.     NAME
  176.     CurrentChunk -- get context node for current chunk.
  177.  
  178.     SYNOPSIS
  179.     top = CurrentChunk (iff)
  180.     d0                  a0
  181.  
  182.     struct ContextNode *top;
  183.     struct IFFHandle *iff;
  184.  
  185.     FUNCTION
  186.     Returns top context node for the given IFFHandle struct.  The top
  187.     context node corresponds to the chunk most recently pushed on the
  188.     stack, which is the chunk where the stream is currently positioned.
  189.     The ContextNode structure contains information on the type of chunk
  190.     currently being parsed (or written), its size and the current
  191.     position within the chunk.
  192.  
  193.     INPUTS
  194.     iff    - pointer to IFFHandle struct.
  195.  
  196.     RESULTS
  197.     top    - pointer to top context node or NULL if none.
  198.  
  199.     SEE ALSO
  200.     PushChunk, PopChunk, ParseIFF, ParentChunk
  201.  
  202.     NAME
  203.     EntryHandler -- add an entry handler to the IFFHandle context.
  204.  
  205.     SYNOPSIS
  206.     error = EntryHandler (iff, type, id, position, hook, object)
  207.      d0                   a0    d0   d1    d2       a1     a2
  208.  
  209.     LONG         error;
  210.     struct IFFHandle *iff;
  211.     LONG         type, id, position;
  212.     struct Hook     *hook;
  213.     APTR         object;
  214.  
  215.     FUNCTION
  216.     Installs an entry handler vector for a specific type of chunk into
  217.     the context for the given IFFHandle struct.  Type and id are the
  218.     longword identifiers for the chunk to handle.  The hook is a client-
  219.     supplied standard 2.0 Hook structure, properly initialized.  Position
  220.     tells where to put the handler in the context.  The handler will be
  221.     called whenever the parser enters a chunk of the given type, so the
  222.     IFF stream will be positioned to read the first data byte in the
  223.     chunk.  The handler will execute in the same context as whoever
  224.     called ParseIFF().  The handler will be called (through the hook)
  225.     with the following arguments: 
  226.  
  227.         A0:    the Hook pointer you passed.
  228.         A2:    the 'object' pointer you passed.
  229.         A1:    pointer to a LONG containing the value
  230.             IFFCMD_ENTRY.
  231.  
  232.     The error code your call-back routine returns will affect the parser
  233.     in three different ways:
  234.  
  235.     Return value        Result
  236.     ------------        ------
  237.     0:            Normal success;  ParseIFF() will continue
  238.                 through the file.
  239.     IFF_RETURN2CLIENT:    ParseIFF() will stop and return the value 0.
  240.                 (StopChunk() is internally implemented using
  241.                 this return value.)
  242.     Any other value:    ParseIFF() will stop and return the value
  243.                 you supplied.  This is how errors should be
  244.                 returned.
  245.  
  246.     INPUTS
  247.     iff    - pointer to IFFHandle struct.
  248.     type    - type code for chunk to handle (ex. "ILBM").
  249.     id    - ID code for chunk to handle (ex. "CMAP").
  250.     position- Local context item position.  One of the IFFSLI_#? codes.
  251.     hook    - pointer to Hook structure.
  252.     object    - a client-defined pointer which is passed in A2 during call-
  253.           back.
  254.  
  255.     RESULTS
  256.     error    - 0 if successful or an IFFERR_#? error code if not
  257.           successful.
  258.  
  259.     BUGS
  260.     Returning the values IFFERR_EOF or IFFERR_EOC from the call-back
  261.     routine *may* confuse the parser.
  262.  
  263.     There is no way to explicitly remove a handler once installed.
  264.     However, by installing a do-nothing handler using IFFSLI_TOP,
  265.     previous handlers will be overridden until the context expires.
  266.  
  267.     SEE ALSO
  268.     ExitHandler, StoreLocalItem, StoreItemInContext, utility/hooks.h
  269.  
  270.     NAME
  271.     ExitHandler -- add an exit handler to the IFFHandle context.
  272.  
  273.     SYNOPSIS
  274.     error = ExitHandler (iff, type, id, position, hook, object)
  275.      d0                  a0    d0   d1    d2       a1     a2
  276.  
  277.     LONG         error;
  278.     struct IFFHandle *iff;
  279.     LONG         type, id, position;
  280.     struct Hook     *hook;
  281.     APTR         object;
  282.  
  283.     FUNCTION
  284.     Installs an exit handler vector for a specific type of chunk into the
  285.     context for the given IFFHandle struct.  Type and id are the longword
  286.     identifiers for the chunk to handle.  The hook is a client-supplied
  287.     standard 2.0 Hook structure, properly initialized.  Position tells
  288.     where to put the handler in the context.  The handler will be called
  289.     just before the parser exits the given chunk in the "pause" parse
  290.     state.  The IFF stream may not be positioned predictably within the
  291.     chunk.  The handler will execute in the same context as whoever
  292.     called ParseIFF().  The handler will be called (through the hook)
  293.     with the following arguments:
  294.  
  295.         A0:    the Hook pointer you passed.
  296.         A2:    the 'object' pointer you passed.
  297.         A1:    pointer to a LONG containing the value
  298.             IFFCMD_EXIT.
  299.  
  300.     The error code your call-back routine returns will affect the parser
  301.     in three different ways:
  302.  
  303.     Return value        Result
  304.     ------------        ------
  305.     0:            Normal success;  ParseIFF() will continue
  306.                 through the file.
  307.     IFF_RETURN2CLIENT:    ParseIFF() will stop and return the value 0.
  308.                 (StopChunk() is internally implemented using
  309.                 this return value.)
  310.     Any other value:    ParseIFF() will stop and return the value
  311.                 you supplied.  This is how errors should be
  312.                 returned.
  313.  
  314.     INPUTS
  315.     iff    - pointer to IFFHandle struct.
  316.     type    - type code for chunk to handle (ex. "ILBM").
  317.     id    - identifier code for chunk to handle (ex. "CMAP").
  318.     position- local context item position.  One of the IFFSLI_#? codes.
  319.     hook    - pointer to Hook structure.
  320.     object    - a client-defined pointer which is passed in A2 during call-
  321.           back.
  322.  
  323.     RESULTS
  324.     error    - 0 if successful or an IFFERR_#? error code if not
  325.           successful.
  326.  
  327.     BUGS
  328.     Returning the values IFFERR_EOF or IFFERR_EOC from the call-back
  329.     routine *may* confuse the parser.
  330.  
  331.     There is no way to explicitly remove a handler once installed.
  332.     However, by installing a do-nothing handler using IFFSLI_TOP,
  333.     previous handlers will be overridden until the context expires.
  334.  
  335.     SEE ALSO
  336.     EntryHandler, StoreLocalItem, StoreItemInContext, utility/hooks.h
  337.  
  338.     NAME
  339.     FindCollection -- get a pointer to the current list of collection
  340.               items.
  341.  
  342.     SYNOPSIS
  343.     ci = FindCollection (iff, type, id)
  344.     d0                   a0    d0   d1
  345.  
  346.     struct CollectionItem *ci;
  347.     struct IFFHandle *iff;
  348.     LONG type, id;
  349.  
  350.     FUNCTION
  351.     Returns a pointer to a list of CollectionItem structures for each of
  352.     the collection chunks of the given type encountered so far in the
  353.     course of parsing this IFF file.  The items earlier in the list will
  354.     be the ones encountered most recently.
  355.  
  356.     INPUTS
  357.     iff    - pointer to IFFHandle struct.
  358.     type    - type code to search for.
  359.     id    - identifier code to search for.
  360.  
  361.     RESULTS
  362.     ci    - pointer to last collection chunk encountered with 
  363.           links to previous ones.
  364.  
  365.     SEE ALSO
  366.     CollectionChunk, CollectionChunks
  367.  
  368.     NAME
  369.     FindLocalItem -- return a local context item from the context stack.
  370.  
  371.     SYNOPSIS
  372.     lci = FindLocalItem (iff, type, id, ident)
  373.     d0                   a0    d0   d1   d2
  374.  
  375.     struct LocalContextItem *lci;
  376.     struct IFFHandle *iff;
  377.     LONG ident, type, id;
  378.  
  379.     FUNCTION
  380.     Searches the context stack of the given IFFHandle struct for a local
  381.     context item which matches the given ident, type and id.  This
  382.     function searches the stack from the most current context backwards,
  383.     so that the item found (if any) will be the one with greatest
  384.     precedence in the context stack.
  385.  
  386.     INPUTS
  387.     iff    - pointer to IFFHandle struct.
  388.     type    - type code to search for.
  389.     id    - ID code to search for.
  390.     ident    - ident code for the class of context item to search for
  391.           (ex. "exhd" -- exit handler).
  392.  
  393.     RESULTS
  394.     lci    - pointer local context item if found, or NULL if nothing
  395.           matched.
  396.  
  397.     BUGS
  398.     It really should have some sort of wildcarding capability.
  399.  
  400.     SEE ALSO
  401.     StoreLocalItem
  402.  
  403.     NAME
  404.     FindProp -- search for a stored property chunk.
  405.  
  406.     SYNOPSIS
  407.     sp = FindProp (iff, type, id)
  408.     d0             a0    d0   d1
  409.  
  410.     struct StoredProperty *sp;
  411.     struct IFFHandle *iff;
  412.     LONG type, id;
  413.  
  414.     FUNCTION
  415.     Searches for the stored property which is valid in the given context.
  416.     Property chunks are automatically stored by ParseIFF() when
  417.     pre-declared by PropChunk() or PropChunks().  The StoredProperty
  418.     struct, if found, contains a pointer to a data buffer containing the
  419.     contents of the stored property.
  420.  
  421.     INPUTS
  422.     iff    - pointer to IFFHandle struct.
  423.     type    - type code for chunk to search for (ex. "ILBM").
  424.     id    - identifier code for chunk to search for (ex. "CMAP").
  425.  
  426.     RESULTS
  427.     sp    - pointer to stored property, if found, or NULL if none
  428.           found.
  429.  
  430.     SEE ALSO
  431.     PropChunk, PropChunks
  432.  
  433.     NAME
  434.     FindPropContext -- get the property context for the current state.
  435.  
  436.     SYNOPSIS
  437.     cn = FindPropContext (iff)
  438.     d0                    a0
  439.  
  440.     struct ContextNode *cn;
  441.     struct IFFHandle *iff;
  442.  
  443.     FUNCTION
  444.     Locates the context node which would be the scoping chunk for
  445.     properties in the current parsing state.  (Huh?)  This is used for
  446.     locating the proper scoping context for property chunks i.e. the
  447.     scope from which a property would apply.
  448.  
  449.     If you don't understand this, read the IFF spec a couple more times.
  450.  
  451.     INPUTS
  452.     iff    - pointer to IFFHandle struct.
  453.  
  454.     RESULTS
  455.     cn    - ContextNode of property scoping chunk.
  456.  
  457.     SEE ALSO
  458.     CurrentChunk, ParentChunk, StoreItemInContext
  459.  
  460.     NAME
  461.     FreeIFF -- deallocate an IFFHandle struct.
  462.  
  463.     SYNOPSIS
  464.     FreeIFF (iff)
  465.              a0
  466.  
  467.     struct IFFHandle *iff;
  468.  
  469.     FUNCTION
  470.     Deallocates all resources associated with this IFFHandle struct.  The
  471.     struct MUST have already been closed with CloseIFF().
  472.  
  473.     INPUTS
  474.     iff    - pointer to IFFHandle struct to free.
  475.  
  476.     SEE ALSO
  477.     AllocIFF, CloseIFF
  478.  
  479.     NAME
  480.     FreeLocalItem -- deallocate a local context item structure.
  481.  
  482.     SYNOPSIS
  483.     FreeLocalItem (lci)
  484.                    a0
  485.  
  486.     struct LocalContextItem *lci;
  487.  
  488.     FUNCTION
  489.     Frees the memory for the local context item and any associated user
  490.     memory as allocated with AllocLocalItem.  User purge vectors should
  491.     call this function after they have freed any other resources
  492.     associated with this item.
  493.  
  494.     Note that FreeLocalItem() does *not* call the purge vector set up
  495.     through SetLocalItemPurge().  (This description seems muddy; how to
  496.     clear it up?)
  497.  
  498.     INPUTS
  499.     lci    - pointer to LocalContextItem created with AllocLocalItem.
  500.  
  501.     SEE ALSO
  502.     AllocLocalItem
  503.  
  504.     NAME
  505.     GoodID -- test if an identifier follows the IFF 85 specification.
  506.  
  507.     SYNOPSIS
  508.     isok = GoodID (id)
  509.      d0            d0
  510.  
  511.     LONG isok, id;
  512.  
  513.     FUNCTION
  514.     Tests the given longword identifier to see if it meets all the EA IFF
  515.     85 specifications for a chunk ID.  If so, it returns 1, otherwise 0.
  516.  
  517.     INPUTS
  518.     id    - potential 32 bit identifier.
  519.  
  520.     RESULTS
  521.     isok    - 1 if this is a valid ID, 0 otherwise.
  522.  
  523.     SEE ALSO
  524.     GoodType
  525.  
  526.     NAME
  527.     GoodType -- test if a type follows the IFF 85 specification.
  528.  
  529.     SYNOPSIS
  530.     isok = GoodType (type)
  531.      d0               d0
  532.  
  533.     LONG isok, type;
  534.  
  535.     FUNCTION
  536.     Tests the given longword type identifier to see if it meets all the
  537.     EA IFF 85 specifications for a FORM type (requirements for a FORM
  538.     type are more stringent than those for a simple chunk ID).  If it
  539.     complies, GoodType() returns 1, otherwise 0.
  540.  
  541.     INPUTS
  542.     type    - potential 32 bit format type identifier.
  543.  
  544.     RESULTS
  545.     isok    - 1 if this is a valid type id, 0 otherwise.
  546.  
  547.     SEE ALSO
  548.     GoodID
  549.  
  550.     NAME
  551.     HookEntry -- call-back stub vector (LANGUAGE SPECIFIC LINK ROUTINE)
  552.  
  553.     SYNOPSIS
  554.     This function is never called directly by the client.
  555.  
  556.     FUNCTION
  557.     HookEntry's purpose is to do language-specific setup and conversion
  558.     of parameters passed from a library to a client call-back routine.
  559.     Under Kickstart 2.0, a standard for call-backs has been established.
  560.     The registers will contain the following items:
  561.  
  562.         A0:    pointer to hook that enabled us to get here.
  563.         A2:    pointer to "object."
  564.         A1:    pointer to "message packet."
  565.  
  566.     In iffparse, the "object" will vary from routine to routine.  The
  567.     "message packet" is also specific to the operation involved (RTFM!).
  568.  
  569.     THIS ROUTINE IS NOT PART OF IFFPARSE.  It, or something similar, is
  570.     part of the compiler vendor's link library.  (If it's not there,
  571.     cobbling up your own isn't too hard.)
  572.  
  573.     SEE ALSO
  574.     EntryHandler, ExitHandler, InitIFF, SetLocalItemPurge,
  575.     utility/hooks.h    (A must-read;  LOTS of details in there)
  576.  
  577.     NAME
  578.     IDtoStr -- convert a longword identifier to a null-terminated string.
  579.  
  580.     SYNOPSIS
  581.     str = IDtoStr (id, buf)
  582.                    d0  a0
  583.  
  584.     char    *str;
  585.     LONG    id;
  586.     char    *buf;
  587.  
  588.     FUNCTION
  589.     Writes the ASCII equivalent of the given longword ID into buf as a
  590.     null-terminated string.
  591.  
  592.     INPUTS
  593.     id    - longword ID.
  594.     buf    - character buffer to accept string (at least 5 chars).
  595.  
  596.     RESULTS
  597.     str    - the value of 'buf'.
  598.  
  599.     SEE ALSO
  600.  
  601.     NAME
  602.     InitIFF -- initialize an IFFHandle struct as a user stream.
  603.  
  604.     SYNOPSIS
  605.     InitIFF (iff, flags, streamhook)
  606.              a0    d0        a1
  607.  
  608.     struct IFFHandle *iff;
  609.     LONG flags;
  610.     struct Hook *streamhook;
  611.  
  612.     FUNCTION
  613.     Initializes an IFFHandle as a general user-defined stream by
  614.     allowing the user to declare a hook that the library will call to
  615.     accomplish the low-level reading, writing, and seeking of the stream.
  616.     Flags are the stream I/O flags for the specified stream; typically a
  617.     combination of the IFFF_?SEEK flags.
  618.  
  619.     The stream vector is called with the following arguments:
  620.  
  621.         A0:    pointer to streamhook.
  622.         A2:    pointer to IFFHandle struct.
  623.         A1:    pointer to IFFStreamCmd struct.
  624.  
  625.     The IFFStreamCmd packet appears as follows:
  626.  
  627.         sc_Command:    Contains an IFFCMD_#? value
  628.         sc_Buf:        Pointer to memory buffer
  629.         sc_NBytes:    Number of bytes involved in operation
  630.  
  631.     The values taken on by sc_Command, and their meaning, are as follows:
  632.  
  633.     IFFCMD_INIT:
  634.         Prepare your stream for reading.  This is used for certain
  635.         streams that can't be read immediately upon opening, and need
  636.         further preparation.  (The clipboard.device is an example of
  637.         such a stream.)  This operation is allowed to fail;  any
  638.         error code will be returned directly to the client.  sc_Buf
  639.         and sc_NBytes have no meaning here.
  640.     IFFCMD_CLEANUP:
  641.         Terminate the transaction with the associated stream.  This
  642.         is used with streams that can't simply be closed.  (Again,
  643.         the clipboard is an example of such a stream.)  This
  644.         operation is not permitted to fail;  any error returned will
  645.         be ignored.  sc_Buf and sc_NBytes have no meaning here.
  646.     IFFCMD_READ:
  647.         Read from the stream.  You are to read sc_NBytes from the
  648.         stream and place them in the buffer pointed to by sc_Buf.
  649.         Any (non-zero) error returned will be remapped by the parser
  650.         into IFFERR_READ.
  651.     IFFCMD_WRITE:
  652.         Write to the stream.  You are to write sc_NBytes to the
  653.         stream from the buffer pointed to by sc_Buf.  Any (non-zero)
  654.         error returned will be remapped by the parser into
  655.         IFFERR_WRITE.
  656.     IFFCMD_SEEK:
  657.         Seek on the stream.  You are to perform a seek on the stream
  658.         relative to the current position.  sc_NBytes is signed;
  659.         negative values mean seek backward, positive values mean seek
  660.         forward.  sc_Buf has no meaning here.  Any (non-zero) error
  661.         returned will be remapped by the parser into IFFERR_SEEK.
  662.  
  663.     All errors are returned in D0.  A return of 0 indicates success.
  664.     UNDER NO CIRCUMSTANCES are you permitted to write to the IFFStreamCmd
  665.     structure.
  666.  
  667.     INPUTS
  668.     iff    - pointer to IFFHandle structure to initialize.
  669.     flags    - stream I/O flags for the IFFHandle.
  670.     hook    - pointer to Hook structure.
  671.  
  672.     SEE ALSO
  673.     utility/hooks.h
  674.  
  675.     NAME
  676.     InitIFFasClip -- initialize an IFFHandle as a clipboard stream.
  677.  
  678.     SYNOPSIS
  679.     InitIFFasClip (iff)
  680.                    a0
  681.  
  682.     struct IFFHandle *iff;
  683.  
  684.     FUNCTION
  685.     Initializes the given IFFHandle to be a clipboard stream.  The
  686.     function initializes the stream processing vectors to operate on
  687.     streams of the ClipboardHandle type.  The iff_Stream field will still
  688.     need to be initialized to point to a ClipboardHandle as returned from
  689.     OpenClipboard().
  690.  
  691.     INPUTS
  692.     iff    - pointer to IFFHandle struct.
  693.  
  694.     SEE ALSO
  695.     OpenClipboard
  696.  
  697.     NAME
  698.     InitIFFasDOS -- initialize an IFFHandle as a DOS stream.
  699.  
  700.     SYNOPSIS
  701.     InitIFFasDOS (iff)
  702.                   a0
  703.  
  704.     struct IFFHandle *iff;
  705.  
  706.     FUNCTION
  707.     The function initializes the given IFFHandle to operate on DOS
  708.     streams.  The iff_Stream field will need to be initialized as a BPTR
  709.     returned from the DOS function Open().
  710.  
  711.     INPUTS
  712.     iff    - pointer to IFFHandle struct.
  713.  
  714.     SEE ALSO
  715.  
  716.     NAME
  717.     LocalItemData -- get pointer to user data for local context item.
  718.  
  719.     SYNOPSIS
  720.     data = LocalItemData (lci)
  721.      d0                   a0
  722.  
  723.     UBYTE *data;
  724.     struct LocalContextItem *lci;
  725.  
  726.     FUNCTION
  727.     Returns pointer to the user data associated with the given local
  728.     context item.  The size of the data area depends on the "usize"
  729.     argument used when allocating this item.  If the pointer to the item
  730.     given (lci) is NULL, the function also returns NULL. 
  731.  
  732.     INPUTS
  733.     lci    - pointer to local context item or NULL.
  734.  
  735.     RESULTS
  736.     data    - pointer to user data area or NULL if lci is NULL.
  737.  
  738.     BUGS
  739.     Currently, there is no way to determine the size of the user data
  740.     area; you have to 'know'.
  741.  
  742.     SEE ALSO
  743.     AllocLocalItem, FreeLocalItem
  744.  
  745.     NAME
  746.     OpenClipboard -- create a handle on a clipboard unit.
  747.  
  748.     SYNOPSIS
  749.     ch = OpenClipboard (unit)
  750.     d0                   d0
  751.  
  752.     struct ClipboardHandle *ch;
  753.     LONG unit;
  754.  
  755.     FUNCTION
  756.     Opens the clipboard.device and opens a stream for the specified unit
  757.     (usually PRIMARY_CLIP).  This handle structure will be used as the
  758.     clipboard stream for IFFHandles initialized as clipboard streams by
  759.     InitIFFasClip().
  760.  
  761.     INPUTS
  762.     unit    - clipboard unit number (usually PRIMARY_CLIP).
  763.  
  764.     RESULTS
  765.     ch    - pointer to ClipboardHandle structure or NULL if
  766.           unsuccessful.
  767.  
  768.     SEE ALSO
  769.     InitIFFasClip, CloseClipboard
  770.  
  771.     NAME
  772.     OpenIFF -- prepare an IFFHandle to read or write a new IFF stream.
  773.  
  774.     SYNOPSIS
  775.     error = OpenIFF (iff, rwmode)
  776.      d0              a0     d0
  777.  
  778.     LONG error;
  779.     struct IFFHandle *iff;
  780.     LONG rwmode;
  781.  
  782.     FUNCTION
  783.     Initializes an IFFHandle struct for a new read or write.  The
  784.     direction of the I/O is given by the value of rwmode, which can be
  785.     either IFFF_READ or IFFF_WRITE.
  786.  
  787.     As part of its initialization procedure, OpenIFF() calls the client-
  788.     supplied stream hook vector.  The IFFStreamCmd packet will contain
  789.     the following:
  790.  
  791.         sc_Command:    IFFCMD_INIT
  792.         sc_Buf:        (Not applicable)
  793.         sc_NBytes:    (Not applicable)
  794.  
  795.     This operation is permitted to fail.  DO NOT write to this structure.
  796.  
  797.     INPUTS
  798.     iff    - pointer to IFFHandle struct.
  799.     rwmode    - IFFF_READ or IFFF_WRITE
  800.  
  801.     RESULTS
  802.     error    - contains an error code or 0 if successful.
  803.  
  804.     SEE ALSO
  805.     CloseIFF, InitIFF
  806.  
  807.     NAME
  808.     ParentChunk -- get the nesting context node for the given chunk.
  809.  
  810.     SYNOPSIS
  811.     parent = ParentChunk (cn)
  812.       d0                  a0
  813.  
  814.     struct ContextNode *parent, *cn;
  815.  
  816.     FUNCTION
  817.     Returns a context node for the chunk containing the chunk for the
  818.     given context node.  This function effectively moves down the context
  819.     stack into previously pushed contexts.  For example, to get a
  820.     ContextNode pointer for the enclosing FORM chunk while reading a data
  821.     chunk, use: ParentChunk (CurrentChunk (iff)) to find this pointer.
  822.     The ContextNode structure contains information on the type of chunk
  823.     and its size.
  824.  
  825.     INPUTS
  826.     cn    - pointer to a context node.
  827.  
  828.     RESULTS
  829.     parent    - pointer to the enclosing context node or NULL if none.
  830.  
  831.     SEE ALSO
  832.     CurrentChunk
  833.  
  834.     NAME
  835.     ParseIFF -- parse an IFF file from an IFFHandle struct stream.
  836.  
  837.     SYNOPSIS
  838.     error = ParseIFF (iff, control)
  839.      d0               a0     d0
  840.  
  841.     LONG error;
  842.     struct IFFHandle *iff;
  843.     LONG control;
  844.  
  845.     FUNCTION
  846.     This is the biggie.
  847.  
  848.     Traverses a file opened for read by pushing chunks onto the context
  849.     stack and popping them off directed by the generic syntax of IFF
  850.     files.  As it pushes each new chunk, it searches the local context
  851.     for handlers to apply to chunks of that type.  If it finds an entry
  852.     handler it will invoke it just after entering the chunk.  If it finds
  853.     an exit handler it will invoke it just before leaving the chunk.
  854.     Standard handlers include entry handlers for pre-declared
  855.     property chunks and collection chunks and entry and exit handlers for
  856.     for stop chunks - that is, chunks which will cause the ParseIFF()
  857.     function to return control to the client.  Client programs can also
  858.     provide their own custom handlers.
  859.  
  860.     The control flag can have three values:
  861.  
  862.     IFFPARSE_SCAN:
  863.         In this normal mode, ParseIFF() will only return control to
  864.         the caller when either:
  865.             1) an error is encountered,
  866.             2) a stop chunk is encountered, or a user handler
  867.                returns the special IFF_RETURN2CLIENT code, or
  868.             3) the end of the logical file is reached, in which
  869.                case IFFERR_EOF is returned.
  870.         
  871.         ParseIFF() will continue pushing and popping chunks until one
  872.         of these conditions occurs.  If ParseIFF() is called again
  873.         after returning, it will continue to parse the file where it
  874.         left off. 
  875.  
  876.     IFFPARSE_STEP and _RAWSTEP:
  877.         In these two modes, ParseIFF() will return control to the
  878.         caller after every step in the parse, specifically, after
  879.         each push of a context node and just before each pop.  If
  880.         returning just before a pop, ParseIFF() will return
  881.         IFFERR_EOC, which is not an error, per se, but is just an
  882.         indication that the most recent context is ending.  In STEP
  883.         mode, ParseIFF() will invoke the handlers for chunks, if
  884.         any, before returning.  In RAWSTEP mode, ParseIFF() will not
  885.         invoke any handlers and will return right away.  In both
  886.         cases the function can be called multiple times to step
  887.         through the parsing of the IFF file.
  888.  
  889.     INPUTS
  890.     iff    - pointer to IFFHandle struct.
  891.     control    - control code (IFFPARSE_SCAN, _STEP or _RAWSTEP).
  892.  
  893.     RESULTS
  894.     error    - 0 or IFFERR_#? value or return value from user handler.
  895.  
  896.     SEE ALSO
  897.     PushChunk, PopChunk, EntryHandler, ExitHandler, PropChunk(s),
  898.     CollectionChunk(s), StopChunk, StopOnExit
  899.  
  900.     NAME
  901.     PopChunk -- pop top context node off context stack.
  902.  
  903.     SYNOPSIS
  904.     error = PopChunk (iff)
  905.      d0               a0
  906.  
  907.     LONG error;
  908.     struct IFFHandle *iff;
  909.  
  910.     FUNCTION
  911.     Pops top context chunk and frees all associated local context items.
  912.     The functions is normally called only for writing files and signals
  913.     the end of a chunk.
  914.  
  915.     INPUTS
  916.     iff    - pointer to IFFHandle struct.
  917.  
  918.     RESULTS
  919.     error    - 0 if successful or an IFFERR_#? error code if not
  920.           successful.
  921.  
  922.     SEE ALSO
  923.     PushChunk
  924.  
  925.     NAME
  926.     PropChunk -- specify a property chunk to store.
  927.  
  928.     SYNOPSIS
  929.     error = PropChunk (iff, type, id)
  930.      d0                a0    d0   d1
  931.  
  932.     LONG error;
  933.     struct IFFHandle *iff;
  934.     LONG type;
  935.     LONG id;
  936.  
  937.     FUNCTION
  938.     Installs an entry handler for chunks with the given type and ID so
  939.     that the contents of those chunks will be stored as they are
  940.     encountered.  The storage of these chunks follows the property chunk
  941.     scoping rules for IFF files so that at any given point, a stored
  942.     property chunk returned by FindProp() will be the valid property for
  943.     the current context.
  944.  
  945.     INPUTS
  946.     iff    - pointer to IFFHandle struct (does not need to be open).
  947.     type    - type code for the chunk to declare (ex. "ILBM").
  948.     id    - identifier for the chunk to declare (ex. "CMAP").
  949.  
  950.     RESULTS
  951.     error    - 0 if successful or an IFFERR_#? error code if not
  952.           successful.
  953.  
  954.     SEE ALSO
  955.     PropChunks, FindProp, CollectionChunk
  956.  
  957.     NAME
  958.     PropChunks -- declare many property chunks at once.
  959.  
  960.     SYNOPSIS
  961.     error = PropChunks (iff, list, n)
  962.      d0                 a0    a1  d0
  963.  
  964.     LONG error;
  965.     struct IFFHandle *iff;
  966.     LONG *list;
  967.     LONG n;
  968.  
  969.     FUNCTION
  970.     Declares multiple property chunks from a list.  The list argument is
  971.     a pointer to an array of long words arranged in pairs, and has the
  972.     following format:
  973.  
  974.         TYPE1, ID1, TYPE2, ID2, ..., TYPEn, IDn
  975.  
  976.     The argument n is the number of pairs.  PropChunks() just calls
  977.     PropChunk() n times.
  978.  
  979.     INPUTS
  980.     iff    - pointer to IFFHandle struct.
  981.     list    - pointer to array of longword chunk types and identifiers.
  982.     n    - number of chunks to declare.
  983.  
  984.     RESULTS
  985.     error    - 0 if successful or an IFFERR_#? error code if not
  986.           successful.
  987.  
  988.     SEE ALSO
  989.     PropChunk
  990.  
  991.     NAME
  992.     PushChunk -- push a new context node on the context stack.
  993.  
  994.     SYNOPSIS
  995.     error = PushChunk (iff, type, id, size)
  996.      d0                a0    d0   d1   d2
  997.  
  998.     LONG error;
  999.     struct IFFHandle *iff;
  1000.     LONG type, id, size;
  1001.  
  1002.     FUNCTION
  1003.     Pushes a new context node on the context stack by reading it from the
  1004.     stream if this is a read file, or by creating it from the passed
  1005.     parameters if this is a write file.  Normally this function is only
  1006.     called in write mode, where the type and id codes specify the new
  1007.     chunk to create.  If this is a leaf chunk, i.e. a local chunk inside
  1008.     a FORM or PROP chunk, then the type argument is ignored.  If the size
  1009.     is specified then the chunk writing functions will enforce this size.
  1010.     If the size is given as IFFSIZE_UNKNOWN, the chunk will expand to
  1011.     accommodate whatever is written into it.
  1012.  
  1013.     INPUTS
  1014.     iff    - pointer to IFFHandle struct.
  1015.     type    - chunk type specifier (ex. ILBM) (ignored for read mode or
  1016.           leaf chunks).
  1017.     id    - chunk id specifier (ex. CMAP) (ignored for read mode).
  1018.     size    - size of the chunk to create or IFFSIZE_UNKNOWN (ignored for
  1019.           read mode).
  1020.  
  1021.     RESULTS
  1022.     error    - 0 if successful or an IFFERR_#? error code if not
  1023.           successful.
  1024.  
  1025.     SEE ALSO
  1026.     PopChunk, WriteChunkRecords, WriteChunkBytes
  1027.  
  1028.     NAME
  1029.     ReadChunkBytes -- read bytes from the current chunk into a buffer.
  1030.  
  1031.     SYNOPSIS
  1032.     error = ReadChunkBytes (iff, buf, size)
  1033.      d0                     a0   a1    d0
  1034.  
  1035.     LONG error;
  1036.     struct IFFHandle *iff;
  1037.     UBYTE *buf;
  1038.     LONG size;
  1039.  
  1040.     FUNCTION
  1041.     Reads the IFFHandle stream into the buffer for the specified number
  1042.     of bytes.  Reads are limited to the size of the current chunk and
  1043.     attempts to read past the end of the chunk will truncate.  Function
  1044.     returns positive number of bytes read or a negative error code.
  1045.  
  1046.     INPUTS
  1047.     iff    - pointer to IFFHandle struct.
  1048.     buf    - pointer to buffer area to receive data.
  1049.     size    - number of bytes to read.
  1050.  
  1051.     RESULTS
  1052.     error    - number of bytes read if successful or an IFFERR_#? error
  1053.           code if not successful.
  1054.  
  1055.     SEE ALSO
  1056.     ReadChunkRecords, ParseIFF, WriteChunkBytes
  1057.  
  1058.     NAME
  1059.     ReadChunkRecords -- read record elements from the current chunk into
  1060.                 a buffer.
  1061.  
  1062.     SYNOPSIS
  1063.     error = ReadChunkRecords (iff, buf, recsize, numrec)
  1064.      d0                       a0   a1     d0       d1
  1065.  
  1066.     LONG error;
  1067.     struct IFFHandle *iff;
  1068.     UBYTE *buf;
  1069.     LONG recsize, numrec;
  1070.  
  1071.     FUNCTION
  1072.     Reads records from the current chunk into buffer.  Truncates attempts
  1073.     to read past end of chunk (only whole records are read; remaining
  1074.     bytes that are not of a whole record size are left unread and
  1075.     available for ReadChunkBytes()).
  1076.  
  1077.     INPUTS
  1078.     iff    - pointer to IFFHandle struct.
  1079.     buf    - pointer to buffer area to receive data.
  1080.     recsize    - size of data records to read.
  1081.     numrec    - number of data records to read.
  1082.  
  1083.     RESULTS
  1084.     error    - number of whole records read if successful or an IFFERR_#?
  1085.           error code if not successful.
  1086.  
  1087.     SEE ALSO
  1088.     ReadChunkBytes, ParseIFF, WriteChunkRecords
  1089.  
  1090.     NAME
  1091.     SetLocalItemPurge -- set purge vector for a local context item.
  1092.  
  1093.     SYNOPSIS
  1094.     SetLocalItemPurge (item, purgehook)
  1095.                         a0      a1
  1096.  
  1097.     struct LocalContextItem *item;
  1098.     struct Hook *purgehook;
  1099.  
  1100.     FUNCTION
  1101.     Sets a local context item to use a client-supplied cleanup (purge)
  1102.     vector for disposal when its context is popped.  The purge vector
  1103.     will be called when the ContextNode containing this local item is
  1104.     popped off the context stack and is about to be deleted itself.  If
  1105.     the purge vector has not been set, the parser will use FreeLocalItem
  1106.     to delete the item, but if this function is used to set the purge
  1107.     vector, the supplied vector will be called with the following
  1108.     arguments:
  1109.  
  1110.         A0:    pointer to purgehook.
  1111.         A2:    pointer to LocalContextItem to be freed.
  1112.         A1:    pointer to a LONG containing the value
  1113.             IFFCMD_PURGELCI.
  1114.  
  1115.     The user purge vector is then responsible for calling FreeLocalItem
  1116.     as part of its own cleanup.  Although the purge vector can return a
  1117.     value, it will be ignored -- purge vectors must always work.
  1118.  
  1119.     INPUTS
  1120.     item      - pointer to local context item.
  1121.     purgehook - pointer to a Hook structure.
  1122.  
  1123.     SEE ALSO
  1124.     AllocLocalItem, FreeLocalItem, utility/hooks.h
  1125.  
  1126.     NAME
  1127.     StopChunk -- declare a chunk which should cause ParseIFF to return.
  1128.  
  1129.     SYNOPSIS
  1130.     error = StopChunk (iff, type, id)
  1131.      d0                a0    d0   d1
  1132.  
  1133.     LONG error;
  1134.     struct IFFHandle *iff;
  1135.     LONG type;
  1136.     LONG id;
  1137.  
  1138.     FUNCTION
  1139.     Installs an entry handler for the specified chunk which will cause
  1140.     the ParseIFF() function to return control to the caller when this
  1141.     chunk is encountered.  This is only of value when ParseIFF() is
  1142.     called with the IFFPARSE_SCAN control code.
  1143.  
  1144.     INPUTS
  1145.     iff    - pointer to IFFHandle struct (need not be open).
  1146.     type    - type code for chunk to declare (ex. "ILBM").
  1147.     id    - identifier for chunk to declare (ex. "BODY").
  1148.  
  1149.     RESULTS
  1150.     error    - 0 if successful or an IFFERR_#? error code if not
  1151.           successful.
  1152.  
  1153.     SEE ALSO
  1154.     StopChunks, ParseIFF
  1155.  
  1156.     NAME
  1157.     StopChunks -- declare many stop chunks at once.
  1158.  
  1159.     SYNOPSIS
  1160.     error = StopChunks (iff, list, n)
  1161.      d0                 a0    a1  d0
  1162.  
  1163.     LONG error;
  1164.     struct IFFHandle *iff;
  1165.     LONG *list;
  1166.     LONG n;
  1167.  
  1168.     FUNCTION
  1169.     (is to StopChunk() as PropChunks() is to PropChunk().)
  1170.  
  1171.     INPUTS
  1172.     iff    - pointer to IFFHandle struct.
  1173.     list    - pointer to array of longword chunk types and identifiers.
  1174.     n    - number of chunks to declare.
  1175.  
  1176.     RESULTS
  1177.     error    - 0 if successful or an IFFERR_#? error code if not
  1178.           successful.
  1179.  
  1180.     SEE ALSO
  1181.     StopChunk
  1182.  
  1183.     NAME
  1184.     StopOnExit -- declare a stop condition for exiting a chunk.
  1185.  
  1186.     SYNOPSIS
  1187.     error = StopOnExit (iff, type, id)
  1188.      d0                 a0    d0   d1
  1189.  
  1190.     LONG error;
  1191.     struct IFFHandle *iff;
  1192.     LONG type;
  1193.     LONG id;
  1194.  
  1195.     FUNCTION
  1196.     Installs an exit handler for the specified chunk which will cause the
  1197.     ParseIFF() function to return control to the caller when this chunk
  1198.     is exhausted.  ParseIFF() will return IFFERR_EOC when the declared
  1199.     chunk is about to be popped.  This is only of value when ParseIFF()
  1200.     is called with the IFFPARSE_SCAN control code.
  1201.  
  1202.     INPUTS
  1203.     iff    - pointer to IFFHandle struct (need not be open).
  1204.     type    - type code for chunk to declare (ex. "ILBM").
  1205.     id    - identifier for chunk to declare (ex. "BODY").
  1206.  
  1207.     RESULTS
  1208.     error    - 0 if successful or an IFFERR_#? error code if not
  1209.           successful.
  1210.  
  1211.     SEE ALSO
  1212.     ParseIFF
  1213.  
  1214.     NAME
  1215.     StoreItemInContext -- store local context item in given context node.
  1216.  
  1217.     SYNOPSIS
  1218.     StoreItemInContext (iff, item, cn)
  1219.                         a0    a1   a2
  1220.  
  1221.     struct IFFHandle *iff;
  1222.     struct LocalContextItem *item;
  1223.     struct ContextNode *cn;
  1224.  
  1225.     FUNCTION
  1226.     Adds the LocalContextItem to the list of items for the given context
  1227.     node.  If an LCI with the same Type, ID, and Ident is already
  1228.     present in the ContextNode, it will be purged.  This is a raw form
  1229.     of StoreLocalItem.
  1230.  
  1231.     INPUTS
  1232.     iff    - pointer to IFFHandle struct for this context.
  1233.     item    - pointer to a local context item to be stored.
  1234.     cn    - pointer to context node for context in which to store item.
  1235.  
  1236.     SEE ALSO
  1237.     StoreLocalItem
  1238.  
  1239.     NAME
  1240.     StoreLocalItem -- insert a local context item into the context stack.
  1241.  
  1242.     SYNOPSIS
  1243.     error = StoreLocalItem (iff, item, position)
  1244.      d0                     a0    a1      d0
  1245.  
  1246.     LONG error;
  1247.     struct IFFHandle *iff;
  1248.     struct LocalContextItem *item;
  1249.     LONG position;
  1250.  
  1251.     FUNCTION
  1252.     Adds the local context item to the list of items for one of the
  1253.     context nodes on the context stack and purges any other item in the
  1254.     same context with the same ident, type and id.  The position argument
  1255.     determines where in the stack to add the item:
  1256.  
  1257.     IFFSLI_ROOT:
  1258.         Add item to list at root (default) stack position.
  1259.     IFFSLI_TOP:
  1260.         Add item to the top (current) context node.
  1261.     IFFSLI_PROP:
  1262.         Add element in top property context.  Top property context is
  1263.         either the top FORM chunk, or the top LIST chunk, whichever
  1264.         is closer to the top of the stack.
  1265.  
  1266.     Items added to the root context, or added to the top context before
  1267.     the IFFHandle has been opened or after it has been closed, are put in
  1268.     the default context.  That is, they will be the local items found
  1269.     only after all other context nodes have been searched.  Items in the
  1270.     default context are also immune to being purged until the IFFHandle
  1271.     struct itself is deleted with FreeIFF().  This means that handlers
  1272.     installed in the root context will still be there after an IFFHandle
  1273.     struct has been opened and closed.  (Note that this implies that
  1274.     items stored in a higher context will be deleted when that context
  1275.     ends.)
  1276.  
  1277.     INPUTS
  1278.     iff    - pointer to IFFHandle struct.
  1279.     item    - pointer to LocalContextItem struct to insert.
  1280.     position- where to store the item (IFFSLI_ROOT, _TOP or _PROP).
  1281.  
  1282.     RESULTS
  1283.     error    - 0 if successful or an IFFERR_#? error code if not
  1284.           successful.
  1285.  
  1286.     SEE ALSO
  1287.     FindLocalItem, StoreItemInContext, EntryHandler, ExitHandler
  1288.  
  1289.     NAME
  1290.     WriteChunkBytes -- write data from a buffer into the current chunk.
  1291.  
  1292.     SYNOPSIS
  1293.     error = WriteChunkBytes (iff, buf, size)
  1294.      d0                      a0   a1    d0
  1295.  
  1296.     LONG error;
  1297.     struct IFFHandle *iff;
  1298.     UBYTE *buf;
  1299.     LONG size;
  1300.  
  1301.     FUNCTION
  1302.     Writes "size" bytes from the specified buffer into the current chunk.
  1303.     If the current chunk was pushed with IFFSIZE_UNKNOWN, the size of the
  1304.     chunk gets increased by the size of the buffer written.  If the size
  1305.     was specified for this chunk, attempts to write past the end of the
  1306.     chunk will be truncated.
  1307.  
  1308.     INPUTS
  1309.     iff    - pointer to IFFHandle struct.
  1310.     buf    - pointer to buffer area with bytes to be written.
  1311.     size    - number of bytes to write.
  1312.  
  1313.     RESULTS
  1314.     error    - positive number of bytes written if successful or a
  1315.           negative IFFERR_#? error code if not successful.
  1316.  
  1317.     SEE ALSO
  1318.     PushChunk, PopChunk, WriteChunkRecords
  1319.  
  1320.     NAME
  1321.     WriteChunkRecords -- write records from a buffer to the current
  1322.                 chunk.
  1323.  
  1324.     SYNOPSIS
  1325.     error = WriteChunkRecords (iff, buf, recsize, numrec)
  1326.      d0                        a0   a1     d0      d1
  1327.  
  1328.     LONG error;
  1329.     struct IFFHandle *iff;
  1330.     UBYTE *buf;
  1331.     LONG recsize, numrec;
  1332.  
  1333.     FUNCTION
  1334.     Writes record elements from the buffer into the top chunk.  This
  1335.     function operates much like ReadChunkBytes().
  1336.  
  1337.     INPUTS
  1338.     iff    - pointer to IFFHandle struct.
  1339.     buf    - pointer to buffer area containing data.
  1340.     recsize    - size of data records to write.
  1341.     numrec    - number of data records to write.
  1342.  
  1343.     RESULTS
  1344.     error    - number of records read if successful or an IFFERR_#?
  1345.           error code if not successful.
  1346.  
  1347.     SEE ALSO
  1348.     WriteChunkBytes
  1349.