Title: | D2KWUTIL
Oracle Developer Add-on (Windows API Access Functions) |
Version: | 6.0.6.0 |
Date: | 08-November-2000 |
Author: | Duncan Mills |
Contents
Information about Versions and Constants
Further Information and Examples
Using with Web Deployed Applications
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 its 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.
The D2KUTIL utility is fairly intelligent about where to look for its DLL. The following places are searched in this order:
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 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:
File | |
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 |
d2kwut1.wav d2kwut2.wav |
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:
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.
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 its 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 1s and 0s | |
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 Servers 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.
Date | PLL Version | DLL Version | By | Change |
23-JAN-1997 | 1.4.0.1 | 1.4.0.0 | DRMILLS | Release (1.4) |
29-JAN-1997 | 1.4.0.2 | 1.4.0.0 | 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 | 1.4.0.3 | 1.4.0.0 | DRMILLS | Enable compatibility for Forms 5.0 Beta, by altering all functions to C calling standard from Pascal. |
09-MAY-1997 | 1.4.0.4 | 1.4.1.0 | DRMILLS | Fix One_Session for NT 4.0 use. Add and document FindAppWindow and Find3rdPartyApp. |
05-JUN-1997 | 1.4.0.5 | 1.4.2.0 | 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 | 1.4.2.0 | 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 | 6.0.4.1 | DRMILLS | Added 3 new Icons for Tree control use: FOLDER_OPEN FOLDER_CLOSED TABS |
08-NOV-2000 | 6.0.6 | 6.0.6.0 | 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. WIN_API_ENVIRONMENT.GET_WINDOWS_VERSION now recognizes Windows2000. |