/****************************** Module Header *******************************
*
* Module Name: getnextconfigkey.e
*
* E wrapper routine to access the NEPMD library DLL.
* Include of nepmdlib.e.
*
* Copyright (c) Netlabs EPM Distribution Project 2002
*
* $Id$
*
* ===========================================================================
*
* This file is part of the Netlabs EPM Distribution package and is free
* software.  You can redistribute it and/or modify it under the terms of the
* GNU General Public License as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* Netlabs EPM Distribution.  This library is distributed in the hope that it
* will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
* General Public License for more details.
*
****************************************************************************/

/*
@@NepmdGetNextConfigKey@PROTOTYPE
Flag = NepmdGetNextConfigKey( Handle, RegPath, SearchOpts, NextKey)

@@NepmdGetNextConfigKey@CATEGORY@CONFIG

@@NepmdGetNextConfigKey@SYNTAX
This function queries a container lookup for key containers
in the configuration repository of the [=TITLE].
For that it needs to be
[.IDPNL_EFUNC_NEPMDGETNEXTCONFIGKEY_EXAMPLE called in a loop].

@@NepmdGetNextConfigKey@PARM@Handle
This parameter determines the handle obtained by a previous call
to [.IDPNL_EFUNC_NEPMDOPENCONFIG].

Use *-3* or *HINI__NEPMDPROFILE* to automatically insert the value of the
universal var *nepmd__hini*.
That's the handle returned by the initial opening of NEPMD.INI.

You may pass an *empty string* to
[.IDPNL_REGISTRY_IMPLICITOPEN implicitely open and close]
the configuration repository before and after this call.

@@NepmdGetNextConfigKey@PARM@RegPath
This parameter specifies the pathname of the container.

@@NepmdGetNextConfigKey@PARM@SearchOpts
This parameter specifies the search options in a logical
combination of the following:
.pl compact bold break=none tsize=3
- K
= search keys only
- C
= search containers only
- B
= search entries being either a container or a key or both

Note that a container #may# also have a key value, but does not
necessarily have one.

@@NepmdGetNextConfigKey@PARM@NextKey
This parameter must be a variable. It specifies either
.ul compact
- an empty string to query the first key of the container or
- the previously returned key in order to query the next key.

If a key is specified, it must exist in the key list, otherwise
*NepmdGetNextConfigKey* will return an error.

The next found key is stored in this parameter.

@@NepmdGetNextConfigKey@EXAMPLE
The following code searches both keys and subcontainers within the
container *\NEPMD*:
.fo text
 Handle        = -3
 RegPath       = '\NEPMD'
 SearchOptions = 'B'
 NextKey       = ''

 -- Search all keys
 do while NepmdGetNextConfigKey( Handle, RegPath, SearchOptions, NextKey)
    -- Process key - here as a sample we display a popup
    messagenwait( 'Key found:' NextKey)
 enddo
.fo on

@@NepmdGetNextConfigKey@RETURNS
*NepmdGetNextConfigKey* returns either
.ul compact
- *0* (zero), if no more keys exist or on error
- *1*, if next config key was queried successfully.

The next key returned by the key search is stored in the
[.IDPNL_EFUNC_NEPMDGETNEXTCONFIGKEY_PARM_NEXTKEY NextKey] parameter.

This procedure sets the implicit universal var *rc*. rc is set to an
[inf:cp2 "Errors" OS/2 error code] or to zero for no error.
rc is set to 18 = ERROR__NO__MORE__FILES if key was not found.

@@NepmdGetNextConfigKey@REMARKS
*NepmdGetNextConfigKey* uses [.IDPNL_EFUNC_NEPMDGETNEXTCONFIGKEY_PARM_NEXTKEY NextKey]
for to find the following key. Therefore
[.IDPNL_EFUNC_NEPMDGETNEXTCONFIGKEY_PARM_NEXTKEY NextKey] itself can't be deleted
in a *NepmdGetNextConfigKey* loop. To achieve that,
gather all found keys in a first *NepmdGetNextConfigKey* loop and delete these
keys in a second loop. Note that the length of an E string is limited to 1600
chars.

The following example shows how to delete all mode keys for mode C:
.fo text
 Handle        = -3
 KeyPath       = '\NEPMD\User\Mode\C'
 SearchOptions = 'K'
 NextKey       = ''
 FoundKeys     = ''

 do while NepmdGetNextConfigKey( Handle, KeyPath, SearchOptions, NextKey)
    FoundKeys = FoundKeys''NextKey''\0
 enddo

 RestKeys = FoundKeys
 do while RestKeys
    parse value RestKeys with NextKey \0 RestKeys
    -- Activate the following to remove NextKey:
    --call NepmdDeleteConfigValue( Handle, NextKey)
    'SayError NepmdDeleteConfigValue( 'Handle', 'NextKey') returned rc = 'rc'.'
 enddo
.fo on

@@NepmdGetNextConfigKey@TESTCASE
You can test this function from the *EPM* commandline by
executing:
.sl
- *NepmdGetNextConfigKey*
  - or
- *GetNextConfigKey*

Executing this command will open up a virtual file and
write all keys found for the container *\NEPMD* to it.

@@
*/

; ---------------------------------------------------------------------------
; Allow editor command to call function
; ---------------------------------------------------------------------------
compile if NEPMD_LIB_TEST

defc NepmdGetNextConfigKey, GetNextConfigKey
   Handle        = HINI_NEPMDPROFILE
   RegPath       = '\NEPMD'
   SearchOptions = 'B'
   NextKey       = ''

   -- Create virtual file
   helperNepmdCreateDumpfile( 'NepmdGetNextConfigKey', RegPath)

   -- Search all keys
   do while NepmdGetNextConfigKey( Handle, RegPath, SearchOptions, NextKey)
      insertline( '-' NextKey)
   enddo
   insertline ''
   .modify = 0

compile endif

; ---------------------------------------------------------------------------
; Procedure: NepmdGetNextConfigKey
; ---------------------------------------------------------------------------
; E syntax:
;    Handle  = ''
;    Flag = NepmdGetNextConfigKey( Handle, RegPath, SearchOpts, NextKey)
;
; ---------------------------------------------------------------------------
; C prototype:
;    APIRET EXPENTRY NepmdGetNextConfigKey( HCONFIG hconfig,
;                                           PSZ   pszRegPath,
;                                           PSZ   pszPreviousKey,
;                                           PSZ   pszBuffer,
;                                           ULONG ulBuffLen);
;
; ---------------------------------------------------------------------------

defproc NepmdGetNextConfigKey( Handle, RegPath, SearchOpts, var NextKey)

   -- For -3, use the handle returned by the initial OpenConfig of NEPMD.INI.
   if Handle = HINI_NEPMDPROFILE then
      Handle = helperNepmdGetConfigHandle()
   endif

   -- Prepare parameters for C routine
   -- Don't touch the handle parameter, as we must report
   -- the address of the original var of the caller.
   RegPath      = RegPath\0
   PreviousKey  = NextKey\0
   SearchOpts   = SearchOpts\0
   BuffLen      = NEPMD_MAXLEN_ESTRING + 1
   NextKey      = copies( \0, BuffLen)

   -- Call C routine
   LibFile = helperNepmdGetlibfile()
   rc = dynalink32( LibFile,
                    'NepmdGetNextConfigKey',
                    atol( Handle)                ||
                    address( RegPath)            ||
                    address( PreviousKey)        ||
                    address( SearchOpts)         ||
                    address( NextKey)            ||
                    atol( BuffLen))

   helperNepmdCheckliberror( LibFile, rc)
   if rc then
      Flag = 0
      NextKey = ''
   else
      Flag = 1
      NextKey = makerexxstring( NextKey)
   endif
   return Flag