The computer program documented here is the copyrighted property of David William Noon, published in 1995. This program may be distributed freely, provided that the copies distributed either are not altered from the original, or any alterations from the original are clearly marked in the source code, and that no charge is levied beyond the price of the medium of distribution. The author does not relinquish the rights of this intellectual property.
DWNVPRX.DLL
This is a working sample of a REXX extension DLL to perform Presentation Manager functions that have not been implemented in Hockware VisPro REXX. With some modification, the functions contained in the DLL might work with Watcom VX-REXX, but your mileage might vary.
The dynamic link library, as shipped, contains 2 functions. One sets the maximum size of the entry field of an entry field control; this function is called DwnSetTextLimit(). The other positions the cursor and, optionally, highlights text within a multi-line edit (or MLE) control; this function is called DwnSetSel.
Registering Entry Points
You need to register the entry points of any REXX extension DLL with the REXX interpreter by calling the REXX built-in function RxFuncAdd. For example, to register DwnSetTextLimit, to be called from a DLL called DWNVPRX.DLL that is located in a directory named in the current LIBPATH, you can use the following code:
Name by which the REXX program will call the function.
Name of the DLL.
Name of the entry point within the DLL. This is often case-sensitive!
Both of the functions in this library require the PM handle of the control to be manipulated. Therefore, you should be familiar with the VisPro REXX method VpItem() using the 'GETHANDLE' parameter. It will be required in each usage of these functions.
Do all your external function registration in the 'When Opened' event of the main form of your VisPro REXX application. Then the functions will be available wherever and whenever you need them.
DwnSetTextLimit
This function adjusts "on the fly" the capacity of an entry field control, by sending the EM_SETTEXTLIMIT message to the control via the PM message queue. This message takes a single additional parameter - an unsigned integer value that specifies the maximum length the entry field is to accept. Thus, the function needs to know the handle of the entry field control and the number of characters it is to accept. The value returned by the function will be a Boolean (0=FALSE, 1=TRUE) if the parameters are valid or an error message character string explaining why the invalid parameter was rejected.
To call this function, you need to have registered it with REXX, and then call it with code similar to the following:
Ok = DwnSetTextLimit(VpItem(window,1004,'GETHANDLE'),60)
SELECT
WHEN Ok = 1 THEN
NOP /* Everything went Ok */
WHEN Ok = 0 THEN
DO /* Too little storage available for buffer, usually */
CALL VpMessageBox window,'Entry field error',,
'Unable to set size of entry field.'
RETURN
OTHERWISE
DO /* Something else was wrong, so display error message */
CALL VpMessageBox window,'Entry field error',Ok
RETURN
The above code sets the maximum size of the entry field text to 60 characters. It assumes that the entry field control is identified to the VisPro REXX run-time by the id. of 1004. If you have assigned a mnemonic name to the control, you may use that instead when calling the VpItem() method.
DwnSetSel
This function moves the cursor around and, optionally, highlights text within a multi-line entry (MLE) control by sending the MLM_SETSEL message to the control. It requires the PM handle of the MLE and two unsigned integer values that represent the anchor point and cursor point, respectively. The value returned by the function will be a Boolean (0=FALSE, 1=TRUE) if the parameters are valid or an error message character string explaining why the invalid parameter was rejected.
Text in a MLE control is considered to be one long string of bytes, starting at offset zero. No account is taken of word wrapping at the end of display lines, and such; it is a one-dimensional view of the text. The anchor point is the offset of the first character to be highlighted and the cursor point is the offset
immediately after
the last character to be highlighted.
If the anchor point and cursor point are equal, no text is highlighted but the cursor is moved to that offset within the MLE, with the display scrolled accordingly. If the MLE is not read-only and insert mode is off, at least 1 character is always highlighted.
Thus, to home the cursor within a MLE, the following code could be used:
Ok = DwnSetSel(VpItem(window,1006,'GETHANDLE'),0,0)
Since even an empty MLE has an offset zero, the control should not reject the message. However, if you specify an anchor point or cursor point outside the current text range within the MLE, your positioning request might be rejected; the control might accept the request instead and place the cursor at the very end of the current text.
To highlight, for example, the 10th through 15th characters - a total of 6 characters - in the MLE, you could call this function as follows:
Ok = DwnSetSel(VpItem(window,1006,'GETHANDLE'),9,15)
SELECT
WHEN Ok = 1 THEN
NOP /* Everything went Ok */
WHEN Ok = 0 THEN
DO /* Maybe we don't have that much text in the MLE */
Note that the offsets are 9 (for the 10th character) and 15 (6 bytes on from there). You need to be very careful when determining these values.
What if it breaks?
Basically, you get to keep all the pieces. However, you may contact me via Compuserve at [72172,431], or on FidoNet by posting a message to David Noon (that's me) in the OS2REXX or OS2PROG echo and I will at least offer sympathy, and maybe some assistance.
Since I have included all the source code, you should be able to fix any problems yourself. I used IBM C Set ++ 2.01 to compile it for my system; using any other compiler is up to you.
(.txt)