Title: D2KWUTIL Oracle Developer Add-on
(Windows API Access Functions)
Date: 08-November-2000
Author: Duncan Mills




Information about Versions and Constants

Locating the DLL file

Version Compatibility

Further Information and Examples

Error Handling


Function List



Using with Web Deployed Applications

Known Limitations

Change History


D2KWUTIL.PLL is a comprehensive utility containing many of functions for the Win32 environment that users ask for, which are not included in the Oracle Developer Product set by default The utility itself consists simply of a PL/SQL library (D2KWUTIL.PLL) and a Windows DLL (D2KWUT60.DLL).

The utility uses the ORA_FFI package to interact with it’s DLL and then this DLL calls the various Windows API functions and some internal code to carry out the requested action.

Some of the functions in the library are direct mapping into Windows API calls, where the DLL just acts as a pass-through mechanism, in other functions the DLL takes the arguments provided by PL/SQL and converts them into C structures which then get passed onto the API calls. Finally there is a class of utility functions which are actually just C code within the DLL (for instance the bit operators).

In addition to the functions listed below there are also a large number of Toolbar icons and several mouse cursors compiled into the DLL. This allows applications to simply reference this DLL and dispense with having individual .ICO files. This could be beneficial in a network environment where pulling many icons off a remote drive might be expensive.


D2KWUTIL is supplied "as is" and although we will attempt to fix any problem that may be encountered in the utility, it is unsupported. 

Useful information about Versions and Constants.

The package header of the WIN_API package contains many pre-defined constants. These will mostly map onto constants defined in winuser.h and the other windows header files. These constants map the hexadecimal constants in these windows header files to PL/SQL integers. Many of these constants will have the same name as the Windows equivalents and the Hex value will be in comments by the value.

There are, however, some constants used within the utility alone, of which you should be aware:

Constant Use
D2KWUTIL _VERSION Documents the Version number for the PLL. This should match the Product Version of the DLL (see below) in the first two places.
D2K_WINDOW_CLASS One of the internal functions (win_api_session.one_session) needs to know the internal window class name of the Developer runtime windows. If this name changes, it needs to be altered here and this will be inherited where required.

The DLL for the D2KWUTIL utility also has a version number embedded in it. To view this, choose Properties for the DLL and click the version tab. In Win95 and NT 4.0 the properties of a file can be viewed by right mouse clicking on the file.

You can programmatically obtain the version of both the PLL and DLL by calling the function d2kwutil, which returns a string containing the current version information.

Locating the DLL file

The D2KUTIL utility is fairly intelligent about where to look for it’s DLL. The following places are searched in this order:

  1. The Directory specified in a call to WIN_API_PRELOAD.SET_LOAD_LOC()
  2. The Directory specified in the Registry parameter HKEY_LOCAL_MACHINE\Software\Oracle\D2KWUTIL60_PATH
  3. The Directory specified in the Registry parameter HKEY_LOCAL_MACHINE\Software\Oracle\D2KWUTIL_PATH
  4. Working Directory
  5. O/S Path
  6. A Directory ..\bin relative to the working Directory
  7. %ORACLE_HOME%/bin Directory

The First 3 search locations should only really be used for debugging or when you have to co-exist with older versions of the utility and need to explicitly load a particular DLL.

Version Compatibility

Version 6.0 is fully code compatible with previous versions of the utility. Any code written to use prior versions of D2KWUTIL can just be re-compiled, without change, against the new version of the library with one possible exception (documented below).

One behavioral change has been made to this version of the utility concerning the reading of strings in REG_EXPAND_SZ format from the registry.  D2KWUTIL now automatically expands any environment variables within the registry value for you.  For instance %TEMP%\mydir might be expanded to "c:\documents and settings\fred\temp\mydir". As a result of this expansion the return value from WIN_API_ENVIRONMENT.READ_REGISTRY may be up to 2000 bytes long rather than the previous value of 512.
To restore the old behavior and not expand such values set the value WIN_API.COMPAT_EXPAND_REG_VALUES to FALSE at runtime

This version of the PLL has been compiled using Oracle Developer version 6.0.8 The code can be backported to Developer version 2.1 (and 2.0) by converting the .PLD file supplied to a PLL using f50gen32.exe or the Forms Builder to convert the PLD back to a PLL. You will not be able to backport this version of D2KWUTIL to Developer Release 1.n as it uses PL/SQL version 2.0 constructs which are only available in Developer Release 2.0 and above.

Example Code & Further Documentation

As part of the D2KWUTIL utility a demonstration form WAPIDEMO.FMB is supplied. This form provides a simple way of viewing the Windows API functions embedded into the D2KWUTIL library.
Simply select an API function on the function list, a test-bed window will appear, allowing you to do a test of the API function, supplying your own arguments to see the effects. A secondary window will show you the PL/SQL code that is actually generated by your test, any errors that occurred and a description of the function that you've chosen.

Note: This version of WAPIDEMO cannot be backported to Earlier versions of Developer.

You can run the WAPIDEMO form without connecting to a database..

The demo consists of the following files:

wapidemo.fmb/fmx Demo form to run
wapidemo.mmb/mmx Menu module for the form
d2kcomn.pll PL/SQL library containing resource file routines and other useful common code.
wapidmus.res Resource file containing strings used by the demo
Demo sound files

To install the demo, simply copy all of the files into a directory on your hard disk and create a shortcut to ifrun60.exe with the arguments MODULE=WAPIDEMO and the working directory (Start in Directory) defined as the directory that you installed into.

D2KWUTIL Error handling mechanism

Because, as was mentioned above, the utility is designed for cross product use, the error handling is not in the form of messaging an error out. When an error, or some other information arises (say a return code form a function) then two variables are set by the internal error mechanism. WIN_API.ERROR_ENCOUNTERED (boolean) is set to TRUE and WIN_API. ERROR_STACK holds the text of the error raised. Most errors will be prefixed with the name of the function that raised them.

Additionally, nearly all the function calls have an optional Boolean argument RaiseExceptions. If this is set and there is a problem with the call, then one of several PL/SQL exceptions will be raised (generally this is the NO_DATA_FOUND exception). The programmer can then use a standard exception handler to deal with the error.

The exceptions raised by each package are documented in the package header. There are some public exceptions defined in WIN_API, which may be raised if the API functions can not initialize (say the DLL is not available).

Debugging D2KWUTIL Startup Problems

If you are having problems getting D2KWUTIL functions to work then you can switch an internal debug mechanism on in one of two ways:

  1. Use the Demo utility WAPIDEMO with the command line parameter DEBUG_LOG=<Filename>. Debug information will then be written to the file name that you specify.
  2. To switch on D2KWUTIL debugging within your own application call the function WIN_API_DEBUG.SetDebug(1,’<Filename>’); again output is sent to the filename that you specify.

The debug output shows you where the utility has searched for the DLL and also records all the arguments to and results from each function as it is called.

You can incorporate this debugging mechanism into your own code as well, see the WIN_API_DEBUG packge for more information.

Function List

The functions within the D2KWUTIL.PLL are divided up into several PL/SQL packages, each of which, groups similar functions together. All of these packages have a dependency on the WIN_API package which holds control information, constants and the error handling mechanisms.

Packages may also have other dependencies, these will be listed in the package header. The PLL does not use any product specific calls e.g. the forms Message() built-in, or the GET_WINDOW_PROPERTY() build in. This perhaps make the code a little less "neat" but does mean that all the function calls can be used in Graphics and Reports as well as Forms.

Package "Public" Function Purpose
WIN_API PreLoad This procedure simply pre-loads the DLL file. This would typically be used so that the icons in the DLL can be accessed.
  DLL_Version Returns the internal version number of the DLL
D2KWUTIL (Function) N/A Returns the version number of this PLL
WIN_API_DIALOG Open_File Pops up a standard Windows File Open Dialog
  Open_FileEx Extended version of Open_file that provides better support for Multiple file selection
  Save_File A standard File-Save dialog
  Select_Printer Printer selection dialog
  Choose_Font Font Selection Dialog
  Choose_Color Color Picker
WIN_API_ENVIRONMENT Read_INI_File Gets a Value from an INI file
  Write_INI_File Sets a Value in an INI file
  Read_Registry Gets a value from the Registry
  Write_Registry Writes a value to the Registry
  Write_RegistryEx Extended version of Write_Registry that allows you to specify the format of the entry.
  Create_Registry_key Create a new key in the Registry
  Delete_Registry_Key Delete an existing key from the Registry
  Get_Windows_Username Windows Logon name
  Get_Windows_Version Which flavour of Win32 are you on?
  Get_Environment_string Gets DOS variable values e.g. PATH
  Get_Windows_Directory Name of directory Windows is installed in
  Get_Temp_Directory The Temporary directory defined for Windows
  Get_Net_Connection Expands the Drive letter of an attached network drive to it’s full path
  Get_Working_Directory The directory that the app was started from.
  Set_Working_Directory Change the Start In directory at runtime
  Get_Computer_Name The name of your machine
  Get_Default_Printer The Printername and port of your default printer.
WIN_API_SESSION One_Session Lets you check to see if an application is already running and Switch to it if required.
  FindAppWindow Returns the top level Window handle for another application
  Find3rdPartyApp Used to check and switch to another application. Unlike One_Session this will find a one or more occurrences of an application, rather than just looking for duplicates
  Find3rdPartyAppEx Extended version of Find3rdPartyAPP that allows you to activate and minimise the application if found.
  Change_MDI_Icon Lets you change the MDI icon for Forms to your own Icon
  TimeOut Lets you detect inactivity in your application
WIN_API_SHELL WinExec Start another application
  StartFile A way of starting an application by just supplying the name of a document. The correct server
  ShellExecute Emulates the right mouse menu options for opening or printing a file, or for opening or exploring a directory
  WinHelp Hook into the Windows Help mechanism
  WinHelpEx Extended version of WinHelp, which offers further control over the Help window size and position.
  MousePosition Get the position of the Mouse at any time.
  SendMessage A hook into the Windows internal messaging System
  SendKeys Allows you to simulate User Keystrokes via a macro language
  ShellExecute Enhanced version of Startfile
WIN_API_UTILITY Delete_File Remove an O/S file
  Move_File Move an O/S file
  Copy_File Copy an O/S file
  Create_Directory Create a new directory
  Delete_Directory Delete an existing Directory
  Generate_Temp_Filename Create and get the name of a temporary file.
  Get_Active_Window Get the window handle of the active window
  Get_Parent_Window Get the parent window of the specified window or the top level window of the app.,
  Play_WAV Play WAV files and System Sounds
  Sleep Put the app to sleep for n milliseconds
  InterruptCheck Allow you to check for the user clicking on a specified button, even when a trigger would not normally fire - e.g. during a Cursor Fetch
  Get_Tick_Count The number of Milliseconds since the PC was last booted.
WIN_API_FILE Created_Date Extract the Creation date of a file.
  Accessed_Date Extract the Last Access date of a file.
  Modified_Date Extract the modification date of a file
  File_Size File size in bytes of a file
  File_Attributes File Attributes such as Read Only
WIN_API_DIRECTORY_LIST FirstFile Starts a listing for all the files and directories matching a search patten in a particular directory
  NextFile Iterator for the search started by FirstFile
  CloseSearch Ends the Search started by FirstFile
WIN_API_BITOP BITWISE_OR "|" bit operator not provided by PL/SQL
  BITWISE_XOR "^" bit operator
  BITWISE_AND "&" bit operator
  BITWISE_SHIFT_RIGHT ">>" bit operator
  BITWISE_SHIFT_LEFT "<<" bit operator
  HiWord High 16 bits from a 32 bit integer
  LoWord Low 16 bits from a 32 bit integer
  HiByte High 8 bits from a 16 bit integer
  LoByte Low 8 Bits from a 16 bit integer
  MakeLong Combine 2 16 bit integers
  MakeWord Combine 2 8 bit integers
  To_BitString Convert number to a string of 1’s and 0’s
  To_HexString Convert number to Hexadecimal string
  BitString_to_Number Convert a binary string to a number
  HexString_To_Number Convert a Hexadecimal sting to a number


The DLL that is used by D2KWUTIL also contains many of the commonly used toolbar icons See the Demo form WAPIDEMO for a display of all the icons. Use the function GetResource to format the icon name correctly for use in Set_ITEM_PROPERTY.

The DLL must be loaded by Forms before the icons can be found. Use the WIN_API.PRELOAD procedure to do this in your When-New-Form-Instance trigger..


The DLL used by D2KWUTIL also has several Mouse cursors coded into it. You can access these using the SET_APPLICATION_PROPERTY() built-in and the GetResource() function.

The DLL must be Pre-Loaded (as for Icons), and also must be in the O/S Path.

Using D2KWUTIL in Web Deployed Applications

The use of this library is not supported with Web deployed applications.

In a web deployment scenario not all functions within D2KWUTIL will work. Any function that interacts with the User Interface (such as those in the WIN_API_DIALOG package) will fail.

Any interaction with the O/S by other functions will all be executed on the NT server and will act within, or return information pertinant to, the environment on that machine. For instance GET_COMPUTER_NAME will return the Server’s name, not the name of the computer that the Client browser is running on. Likewise COPY_FILE will copy files in the Forms Server not on the Client.

Functions such as those in WIN_API_BITOP will continue to work without change.

Known Limitations

Change History

Date PLL Version DLL Version By Change
23-JAN-1997 DRMILLS Release (1.4)
29-JAN-1997 DRMILLS Check for Null in Package Body of win_api_shell.SendKeys If a NULL value is specified for the keystrokes (Keys parameter) then add an error to the stack, and Raise NO_DATA_FOUND if RaiseExceptions is TRUE.
05-FEB-1997 DRMILLS Enable compatibility for Forms 5.0 Beta, by altering all functions to C calling standard from Pascal.
09-MAY-1997 DRMILLS Fix One_Session for NT 4.0 use. Add and document FindAppWindow and Find3rdPartyApp.
05-JUN-1997 DRMILLS Add File information functions(enhancement req 497358): File_Size, File_Attributes, Created_Date, Accessed_date and Modified_Date.

Add package constants to WIN_API for the window classes of various common 3rd party applications. Such constants prefixed with WINCLASS_

Various Fixes to One_Session, Find3rdPartyApp and FindAppWindow.

Added Correct Window classes for Both Developer/2000 1.3.2 and Developer/2000 release 2.0.

Corrected documentation for File dialog functions.

Fixed bug 493668 for WIN_API_ENVIRONMENT.Read_Registry, allow non-administrators on NT access to any Registry Keys that they can read, not just those they can write.

Fixed HELP_CONTEXTPOPUP type help for WinHelp, and supplied new procedure SetHelpPos to define where popup help should appear.

26-JUN-1997 2.0.5 DRMILLS Final upgrade for Developer/2000 Release 2.0. Added new d2kwutil function to return the version number of the PLL for use in About dialogs.
24-FEB-1999 6.0.1 6.0.0 DRMILLS Release 6.0. Many new features added and PLL reworked
02-AUG-1999 6.0.2 6.0.2 DRMILLS Fixed Bug 937756 caused by large window handles greater than the precision of PLS_INTEGER.
Corrected Example for InterruptCheck
Added new cursor "ARROW" to the DLL and Demo.
Few cosmetic changes to WAPIDEMO
29-SEP-1999 6.0.3 6.0.3 (Testing) DRMILLS Added support for HKEY_CURRENT_CONFIG to the Registry Read and Write functions (but not the Create and Delete functions as it is a dynamic key). Updated WAPIDEMO in line.
Fixed Bug 983425 - Unable to find D2KWUT60.DLL in OS Search Path
11-NOV-1999 6.0.4 6.0.4 DRMILLS Productised changes made in 6.0.3 testing version.
Created a new version of Find3rdPartyApp called Find3rdPartyAppEx which includes a "Mimized" parameter to provide a W/A for Bug 675079.
Added Package Win_API_PRELOAD to allow the specification of an explicit location for the DLL.
Added ShellExecute function to WIN_API_SHELL
Improved Initial Load options.
13-NOV-1999 6.0.4 DRMILLS Added 3 new Icons for Tree control use:
08-NOV-2000 6.0.6 DRMILLS Added Color Picker function, directory listing capabilities and ShellExecute.
Fixed a Bug In WRITE_REGISTRY which caused a crash when writing NULL.
Added automatic expansion of REG_EXPAND_SZ values read using READ_REGISTRY.
Fixed a couple of behavior bugs in the WAPIDEMO form.
Exposed the location that the DLL is loaded from in WIN_API.DLL_PATH and made this information available in the WAPIDEMO about box.