OS2::PrfDB - Perl extension for access to OS/2 setting database.

- NAME
- SYNOPSIS
- DESCRIPTION

- High level access
- Low-level access
- Integer handles
- Exports

- AUTHOR
- SEE ALSO

# NAME

OS2::PrfDB - Perl extension for access to OS/2 setting database.

# SYNOPSIS

      use OS2::PrfDB;
      tie %settings, OS2::PrfDB, 'my.ini';
      tie %subsettings, OS2::PrfDB::Sub, 'my.ini', 'mykey';

      print "$settings{firstkey}{subkey}\n";
      print "$subsettings{subkey}\n";

      tie %system, OS2::PrfDB, SystemIni;
      $system{myapp}{mykey} = "myvalue";

# DESCRIPTION

The extension provides both high-level and low-level access to .ini files.

## High level access

High-level access is the tie-hash access via two packages: `OS2::PrfDB` and `OS2::PrfDB::Sub`. First one supports one argument, the name of the file to open, the second one the name of the file to open and so called Application name, or the primary key of the database.

      tie %settings, OS2::PrfDB, 'my.ini';
      tie %subsettings, OS2::PrfDB::Sub, 'my.ini', 'mykey';

One may substitute a handle for already opened ini-file instead of the file name (obtained via low-level access functions). In particular, 3 functions SystemIni(), UserIni(), and `AnyIni()` provide handles to the ``systemish'' databases. AniIni will read from both, and write into User database.

## Low-level access

Low-level access functions reside in the package `OS2::Prf`. They are

`Open(file)`

  Opens the database, returns an integer handle.

`Close(hndl)`

  Closes the database given an integer handle.

`Get(hndl, appname, key)`

  Retrieves data from the database given 2-part-key `appname` `key`. If `key` is `undef`, return the ``\0'' delimited list of `key`s, terminated by \0. If `appname` is `undef`, returns the list of possible `appname`s in the same form.

`GetLength(hndl, appname, key)`

  Same as above, but returns the length of the value.

`Set(hndl, appname, key, value [ , length ])`

  Sets the value. If the `value` is not defined, removes the `key`. If the `key` is not defined, removes the `appname`.

`System(val)`

  Return an integer handle associated with the system database. If `val` is 1, it is User database, if 2, System database, if 0, handle for ``both'' of them: the handle works for read from any one, and for write into User one.

`Profiles()`

  returns a reference to a list of two strings, giving names of the User and System databases.

`SetUser(file)`

  (Not tested.) Sets the profile name of the User database. The application should have a message queue to use this function!

## Integer handles

To convert a name or an integer handle into an object acceptable as argument to `tie()` interface, one may use the following functions from the package `OS2::Prf::Hini`:

`new(package, file)`
`new_from_int(package, int_hndl [ , filename ])`

## Exports

SystemIni(), UserIni(), and AnyIni().

# AUTHOR

Ilya Zakharevich, ilya@math.ohio-state.edu

# SEE ALSO

perl(1).

OS2::PrfDB - Perl extension for access to OS/2 setting database.