home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / CD32 / CD32_Support / examples / SA_Examples / nonvolatile / NVLib.doc < prev    next >
Encoding:
Text File  |  1993-08-31  |  7.0 KB  |  191 lines

  1.  
  2.                       NonVolatile.library Test Programs
  3.                                  Release 1.3
  4.                                  20 Apr 1993
  5.                                 J.W. Lockhart
  6.  
  7.   Program           Version
  8. =============       =======
  9.    StoreNV            1.7
  10.    DeleteNV           1.3
  11.    GetNVList          1.21
  12.    GetCopyNV          1.3
  13.    GetNVInfo          1.4
  14.    SetNVProtection    1.6
  15.    StuffNV            1.3
  16.    WipeNV             1.2
  17.  
  18.  
  19. Usages
  20. ===========================================================================
  21.  WipeNV
  22.  
  23.     Purpose
  24.         Delete all items in NV-storage.  No error checking
  25.         or args; be certain before you use it!
  26.     Inputs
  27.         None
  28.     Notes
  29.         Reports each item just before it tries to nuke it.
  30.         Will un-protect any protected items.
  31.     Example
  32.         WipeNV
  33.             *poof!*
  34.  
  35.  
  36. ===========================================================================
  37.  StuffNV NAME/K, ITEMS/K/N, BYTES=BYTESPERITEM/K/N, NOPROTECT/S, OVERRUN/S
  38.  
  39.     Purpose
  40.         Fill up (or overflow) NV-storage
  41.  
  42.     Inputs
  43.         NAME      - Application name to use; default is AppName(1|2).
  44.         ITEMS     - How many items to use.  Default: as many as possible.
  45.         BYTES     - How many bytes per item.  Default: 10.
  46.         NOPROTECT - Don't protect each item after creating it
  47.         OVERRRUN  - Intentionally try to create one more item than should fit.
  48.  
  49.     Notes
  50.       - Always tries to use two application names.
  51.       - Defaults should be sufficient for most purposes.
  52.       - Doesn't currently take into account the amount of space
  53.         needed to store the appname.
  54.       - Items are full of binary gibberish (buffer is filled with
  55.         item number...not ascii value of item number, either).
  56.  
  57.     Example
  58.         StuffNV
  59.  
  60. ===========================================================================
  61.  
  62.  StoreNV NAME=APPNAME/K, ITEM=ITEMNAME/K, DATA/K, FILE=DATAFILE/K,
  63.          BUFSIZE/K/N, BUFFILL/N, NULL=NULLTEST/S, ZERO=ZEROTEST/S, KILLREQ/S,
  64.          BETRUE/S, NOLIE/S
  65.  
  66.    Purpose
  67.       Save data into nonvolatile area.
  68.  
  69.    Inputs
  70.       NAME    - name of application which is storing the info.  Default: NVTest.
  71.       ITEM    - name of item being stored.  Default: Test01.
  72.          ** only one of the following three may be selected:  **
  73.       DATA    - a string which will be used as the data to be stored
  74.       FILE    - an existing file which will be used as the data to be stored
  75.       BUFSIZE - the size of a buffer which will be allocated and used for
  76.                 data to be stored.
  77.       BUFFILL - a number to fill the buffer with.  Only works if BUFSIZE
  78.                 specified.
  79.       NULL    - pass NULL for data to be stored
  80.       ZERO    - pass 0 for size of data to be stored.  All other sizes are
  81.                 calculated automagically.
  82.       KILLREQ - turns off requesters
  83.       BETRUE  - Do not round memory allocations up to the nearest number
  84.                 evenly divisible by 10; use actual needed size instead.
  85.                 (I.e., use "true allocations".)
  86.       NOLIE   - Feed StoreNV() the actual bytecount, not 10's of bytes as
  87.                 required by the autodoc.
  88.  
  89.    Notes
  90.       You must specify one of the following:
  91.         NULL, DATA, FILE, BUFSIZE
  92.       You may only specify one of the following three:
  93.         DATA, FILE, BUFSIZE
  94.  
  95.       One of the quirks of this function is that it asks you to provide a size
  96.       to the nearest 10 bytes, rounded up, for your data.  StoreNV will
  97.       (by default) provide a size and allocation larger than the actual data,
  98.       if necessary.  [A quirk?  Well, 10 is a strange number.  Also, most
  99.       system functions (eg, AllocMem()) will do roundoffs for you, so it's
  100.       not a consideration.]
  101.  
  102.       StoreNV expects its buffersize in real numbers.  That is, if you
  103.       want a 1000-byte buffer, say "BufSize=1000".
  104.  
  105.    Examples
  106.       storenv data "This is a test"
  107.       storenv file s:startup-sequence
  108.       storenv name "Foo" item "Bar" bufsize 107 buffill 65 killreq
  109.  
  110. =============================================================================
  111.  DeleteNV  NAME=APPNAME/K, ITEM=ITEMNAME/K, KILLREQ/S
  112.  
  113.    Purpose
  114.       Delete data from nonvolatile area.
  115.  
  116.    Inputs
  117.       NAME    - name of application which owns the info.  Default: NVTest.
  118.       ITEM    - name of item being deleted.  Default: Test01.
  119.       KILLREQ - turns off requesters
  120.  
  121. =============================================================================
  122.  GetNVList NAME=APPNAME/K,NULL=NULLTEST/S,NOBREAK/S, KILLREQ/S
  123.  
  124.     Purpose
  125.         Get list of stored nonvolatile items owned by an application,
  126.         with info on each entry.
  127.  
  128.     Inputs
  129.         NAME     - application name to search for.
  130.         NULL     - pass NULL for application name
  131.         NOBREAK  - stop only when NVEntry->nve_Node.mln_Succ is NULL.
  132.         KILLREQ  - turns off requesters
  133.  
  134.     History
  135.         Many revisions to make a pretty and succinct output format.
  136.  
  137. =============================================================================
  138.  GetCopyNV LENGTH/A/N, NAME=APPNAME/K, ITEM=ITEMNAME/K, NN=NULLNAME/S,
  139.            NI=NULLITEM/S, HEX=HEXDUMP/S, KILLREQ/S
  140.  
  141.     Purpose
  142.         Get a copy of data stored in nonvolatile area.  Use GetNVList to
  143.         determine the length of this data.
  144.  
  145.     Inputs
  146.  
  147.        LENGTH    - length of data to obtain
  148.        NAME      - name of application which owns the data
  149.        ITEM      - name of item to fetch
  150.        NULLNAME  - use NULL application name
  151.        NULLITEM  - use NULL data item
  152.        HEX       - do hex dump rather than ascii dump on any returned data
  153.        KILLREQ   - turns off requesters
  154.  
  155.     Notes
  156.        Length means the real length:  if you want 1000 bytes, ask for
  157.        1000 bytes.  Any size values returned from GetNVList must be
  158.        multiplied by 10.  (Of course, if GetNVList says there are 5
  159.        storage units, and there are only 47 meaningful bytes, you'll get
  160.        3 garbage bytes if you ask for 50 bytes...)
  161.  
  162. =============================================================================
  163.  GetNVInfo  KILLREQ/S
  164.  
  165.     Show information about nonvolatile area.
  166.  
  167.       KILLREQ - turns off requesters
  168.  
  169. =============================================================================
  170.  SetNVProtection NAME=APPNAME/K, ITEM=ITEMNAME/K, FLAGS=HEXFLAGS/K, DELETE/S,
  171.                  NN=NULLNAME/S, NI=NULLITEM/S, KILLREQ/S
  172.  
  173.     Purpose
  174.         Set protection on previously saved nonvolatile data
  175.  
  176.     Inputs
  177.        NAME     - name of application which owns the data
  178.        ITEM     - name of data item to be affected.
  179.        FLAGS    - raw hex flags to set
  180.        DELETE   - the only legitimate flag to set (NVEF_DELETE)
  181.        NULLNAME - use NULL for application name
  182.        NULLITEM - use NULL for name of data item
  183.        KILLREQ  - turns off requesters
  184.  
  185.     Notes
  186.         Flags=0x01 means to write-protect the data
  187.         Flags=0x00 means to write-enable the data.
  188.         Flags=anything_else should make the function fail, but it should
  189.               no longer crash.  (Nonvolatile.library was intentionally 
  190.               doing a divide-by-zero in this case.)
  191.