Contents

Introduction

Support

Information about Versions and Constants

Locating the DLL file

Version Compatibility

Further Information and Examples

Error Handling

Debugging

Function List

Icons

Cursors

Using with Web Deployed Applications

Known Limitations

Change History

Introduction

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.

Support

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:

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:

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.

Icons

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..

Cursors

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

• When using the WIN_API_SESSION functions ONE_SESSION, FIND_3RDPARTY_APP and FIND_APP_WINDOW on NT you MUST use WINDOW as the match mode.
• Do not call WIN_API_SESSION.TIMEOUT_START_TIMER for a second time in the runtime session without calling DELETE_TIMER first. If you do you may get an access violation.
• If you are calling the Dialog functions, from Reports or Graphics, when runing in the background, set the Modal flag to FALSE. If you set it to true, D2KWUTIL will attempt to find out which window owns it, and as you’re running in the background, this will fail and the dialog will not display.

Change History