_______________________________________________________________________________

  rwIni v1.20 - Copyright (C)2018 Richard L Walsh - All Rights Reserved

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

_______________________________________________________________________________
_______________________________________________________________________________

  rwIni is a REXX interface to rwPrf, a library that emulates the PM Profile
  functions. It is only appropriate for use with private INI files and will
  refuse to handle the current System and User INI files.

  Functions
    rwIniLoadFuncs
    rwIniDropFuncs
    rwIniVersion
    rwIniOpen
    rwIniClose
    rwIni

_______________________________________________________________________________

  rwIniLoadFuncs
_______________________________________________________________________________

  rc = rwIniLoadFuncs()

  Loads the 5 other rwIni functions.
  Always returns a null string.

_______________________________________________________________________________

  rwIniDropFuncs
_______________________________________________________________________________

  rc = rwIniDropFuncs()

  Unloads all rwIni functions.
  Always returns a null string.

_______________________________________________________________________________

  rwIniVersion
_______________________________________________________________________________

  version = rwIniVersion()

  Returns the current version in the form "Major.Minor" (e.g. '1.20').

_______________________________________________________________________________

  rwIniOpen
_______________________________________________________________________________

  handle = rwIniOpen(fileName [, option])

  Opens the specified file, creating it if it doesn't exist. After the entire
  INI file is read into memory the physical file is closed. All read and write
  operations occur in memory and are only written to file when rwIniClose()
  is called.

  The only option available is 'N' or 'n' for "no-create". If specified, the
  file will not be created if it does not exist already.

  Returns a handle to the opened file if successful. This handle must be
  passed to rwIni() and rwIniClose(). Returns the string 'ERROR:' if the
  file can not be opened.

  Note: rwIniOpen() will refuse to open the current User and System profiles
  (normally, '\os2\os2.ini' and '\os2\os2sys.ini'). Use the 'REXXUTIL'
  function SysIni() instead.
  
_______________________________________________________________________________

  rwIniClose
_______________________________________________________________________________

  rc = rwIniClose(handle [, option])

  Closes the specified handle by writing any changes back to file then
  freeing the memory it used. After this call the handle is no longer
  valid.

  The only option available is 'N' or 'n' for "no-save". If specified, any
  changes to the file will not be saved. Additionally, if this file was
  just created by your script's call to rwIniOpen(), it will be deleted.

  Returns a null string for success and 'ERROR:' for failure.

_______________________________________________________________________________

  rwIni
_______________________________________________________________________________

  rc = rwIni(handle, arg1[, arg2[, arg3]])

  rwIni()'s operation is identical to SysIni() _except_ that you must pass it
  the handle obtained by a previous call to rwIniOpen().

  * enumerate all applications
    rc = rwIni(handle, 'ALL:', 'stem')

  * enumerate all keys within an application
    rc = rwIni(handle, app, 'ALL:', 'stem')

  * delete an application and all its keys
    rc = rwIni(handle, app, 'DELETE:')

  * delete a key within an application
    rc = rwIni(handle, app, key, 'DELETE:')

  * add/change a key and its value
    rc = rwIni(handle, app, key, value)

  * query a key's value
    value = rwIni(handle, app, key)

  If successful, all calls to rwIni() except queries return a null string;
  queries return the requested value. If unsuccessful, all calls return
  'ERROR:'.

_______________________________________________________________________________
_______________________________________________________________________________

