You’re probably already using OS/2 REXX for utility applications. By exploiting a freely available IBM add-on function set, you can add a sophisticated GUI interface with little effort. Best of all, no programming prowess is required.
Visual REXX for Presentation Manager, VREXX for short, lets you create and control presentation manager windows and dialogs directly from an OS/2 REXX program. (VREXX requires OS/2 version 2.0 or later.) With VREXX, your REXX program can create windows, put text and graphics in them, and display pop-up dialog boxes to display messages or receive user input. In other words, your program can continue to use the standard REXX features, but the drab command line interface used to “say” text and “pull” user input is replaced with contemporary dialog boxes. (Note: VREXX should not be confused with Watcom’s commercial product VX-REXX. For more information on VX-REXX, refer to http://www.watcom.on.ca/vxrexx/vxrexx.html.)
In this article, I will introduce you to the VREXX dialog functions. This article will give you the background and confidence you’ll need to begin exploiting VREXX in your own REXX programs. It will also provide a solid foundation for a future article on VREXX’s windowing and drawing functions and how those functions can be used to express data harvested from the AS/400 using REXX EHLLAPI.
What’s Possible with VREXX
VREXX provides a robust suite of GUI functions to enhance your OS/2 REXX programs. They are classified into three categories: dialog functions, windowing functions, and graphics functions. VREXX dialog functions allow a REXX program to display message boxes, list boxes, check boxes, input boxes, and file boxes. This article will explore VREXX dialog functions, which also give you a good introduction to OS/2 PM
concepts. VREXX windowing functions allow a REXX program to create new windows, clear windows, change their foreground/ background colors, resize them, and tear them down.
VREXX graphics functions allow a REXX program to draw complex lines, arcs, splines, polygons, pixels, and text into a window.
VREXX Availability
VREXX is EWS, IBM employee-written software. It is freely available to any OS/2 licensed user and can be downloaded from IBM’s EWS ftp site: ftp://software.watson.ibm.com/pub/os2/ews/vrexx2.zip. (The REXX code for the examples used in this article is available at my ftp site: ftp://members.aol.com/cmiksanek/xmpvrexx.zip.)
Installing VREXX
Once you unzip VREXX, you’ll see several files. VREXX includes Dynamic Link Libraries (DLLs), executables, documentation, comprehensive sample REXX programs, and help files. You can install them as directed by the included documentation:
1. Copy VREXX.INF to a BOOKSHELF help file directory specified in your CONFIG.SYS file.
2. Copy VREXX.EXE and the sample command files to a utility directory included in your PATH statement.
3. Copy VREXX.DLL and DEVBASE.DLL to a directory specified in your LIBPATH in CONFIG.SYS.
Or you can just unzip all of the VREXX files into a new directory and do all of your REXX development there without worrying about moving files or modifying paths.
Initializing/Housekeeping
Before calling VREXX functions, your REXX program must first load and initialize the functions by using RxFuncAdd and vInit() as illustrated in the sample REXX program. Also, on exit, your program should call the vExit() function to clean up system resources. Because it is important that your program clean up system resources properly, your code should establish error exits so that, in the event of abnormal termination, execution flow is properly routed through the cleanup code. The sample program has an example of error trapping.
Editing and Executing a REXX Program
You don’t need to know much about programming to exploit REXX or the GUI functions introduced here. (REXX is IBM’s SAA procedural language, and it has been implemented on VM, TSO, the AS/400, and OS/2. There are excellent REXX tutorials available; several of them are noted at the end of this article.) At this point, you just need to know how to edit the sample program and execute it.
Using your favorite editor, create a new member named XMPVREXX.CMD (all REXX programs must have the extension .CMD). Type the sample program code and save the file as ASCII text. To execute it, type the command name XMPVREXX in an OS/2 window. Better yet, to fully exploit the GUI concept, create a program object on your desktop (by dragging a program template from your templates folder—refer to your OS/2 reference for more information), attach the REXX command to it, then just double-click the new icon to execute your program. By ticking the
Start minimized and Close window on exit options in the settings notebook of your program object, your REXX code will operate like most native OS/2 applications.
Stem Variables
VREXX makes extensive use of stem variables. A stem variable is analogous to an array. Many REXX programs use stem variables to manage variable-length tables. Typically, STEM.0 contains the total number of elements, and STEM1 through STEMn contain the data. For example, to pass two lines of message text to the vMsgBox function—which requires a stem variable containing the text as a parameter—you can populate the MsgText stem variable as follows:
MsgText.0 = 2
MsgText.1 = ‘This is the
first line of the message text’
MsgText.2 = ‘This is the
second line of the message text’
You would then pass the name of the stem variable, in this case MsgText, to the function vMsgBox. (Refer to the VREXX Dialog Function Reference section of this article and the included sample code for more information on the actual vMsgBox invocation.)
Some of the VREXX functions use stem variables to return information as well. For instance, the vCheckBox functions returns a stem variable indicating the total number of items the user checked and the associated text of those checked items. Your REXX program could then interpret the returned variable stem.0. If it is zero, nothing was selected. If stem.0 was, for example, three, then stem.1, stem.2, and stem.3 would contain the text of the checked items.
Instead of enumerated subscripts, some functions return “named” stem variable subscripts. An example of this operation is vInputBox. When returning user- specified text, vInputBox sets the stem subscript named vstring to the entered text. To interrogate user input, your REXX program would examine the variable stem.vstring.
Some of the dialog functions described here—vCheckBox, vInputBox, vListBox, vMsgBox, and vRadioBox—allow you to specify button options to appear in the pop-up dialog. The button options are OK, Cancel, OK and Cancel, Yes, No, and Yes and No. These button options are specified on the function call as 1, 2, 3, 4, 5, and 6, respectively. (Refer to the VREXX Dialog Function Reference section and included sample code for more information on the actual function call syntax.) The function returns the button the user selected; if the user pressed the OK button, the function returns OK; if the user pressed the cancel button, the function returns CANCEL, and so on.
Note that there are two ways to call a REXX function:
call func parm1, parm2, parm3 or
rc = func(parm1, parm2, parm3)
In order for the function to return a value, you need to specify the latter format so that a variable is set to the result of a function. In the case above, rc would be set to the function result. If the function was one that returned a button value, rc would reflect the button the user selected.
Sample App Ideas
A GUI function set empowers the OS/2 REXX programmer to easily develop sophisticated applications. For example, combined with the REXX EHLLAPI interface,
Buttons
you can graphically express AS/400 resources on your desktop. The opportunities are limitless. Start with the sample REXX program included here, which makes use of the Novell Send command to dispatch a message to any number of users. This sample application makes use of all of the fundamental VREXX dialog functions and is a great launch-point for your GUI REXX experimentation. Also, consider porting many of your OS/2 command-line applications to VREXX GUI applications. Start by replacing the SAY and PULL function calls with vMsgBox and vInputBox, respectively.
VREXX Dialog Function Reference
Here are some of the more common VREXX dialog functions you will need to use when you begin experimenting with VREXX. For a complete description of all of the VREXX functions, refer to the “Visual REXX For Presentation Manager” document included in the VREXX package. (Note: Before invoking VREXX functions, your REXX program must first load and initialize VREXX. Refer to the sample code elsewhere in this article for this procedure.)
vInit—vInit initializes the VREXX environment. vInit is a prerequisite function for all VREXX functions. vInit returns the string ERROR if initialization fails. Sample execution: rc = vInit()
vExit—vExit performs exit housekeeping and should be called on termination for any REXX program that has executed the vInit function. Sample execution: call vExit
vDialogPos—vDialogPos allows your REXX program to specify where the subsequent pop-up will appear on the user’s terminal. vDialogPos accepts two parameters—x and y—which represent screen percentages where the x-coordinate 0 is the left edge of the screen and the y-coordinate 0 is the bottom edge. Thus, an invocation of call VDialogPos 50, 0 will place the pop-up window in left-to-right center (x-coordinate) and bottom (y-coordinate).
To center a dialog pop-up, specify 50,50.
vMsgBox—vMsgBox will probably be the VREXX function you’ll use most. It can display one to 10 lines of message text as well as OK, Cancel, Yes, and No buttons. Below is the code used to generate the vMsgBox. See Figure 1 for a picture of this window.
txt.0 = 6
txt.1 = ‘ This is a popup that can
support from one to 10 lines of’
txt.2 = ‘ message text
as well as several button options.’
txt.3 = ‘’
txt.4 = ‘’
txt.5 = ‘ If you would like to
exit, click the [CANCEL] button
now.’
txt.6 = ‘ If you want to proceed,
click [OK].’
button = vMsgBox(‘Sample vMsgBox’,
txt, 3)
if button = ‘CANCEL’ then signal
Cleanup_and_Exit
/* proceed with processing */
vFileBox—vFileBox is a handy function that displays a standard OS/2 file selection box with an optional file template (e.g., *.txt). The filename and entire path of the selected or specified file—for example, an input file or an output file—is then returned to the REXX program if the OK button is pressed.
Below is the code used to generate vFileBox. See Figure 2 for a picture of
this display.
button = VFileBox(‘Select a
names file to use’, ‘*.nms’,
name)
if button = ‘CANCEL’ then signal
Cleanup_and_Exit
selected_file = name.vstring
/* proceed with processing */
vRadioBox—vRadioBox displays a list of up to 10 items, each with a radio button from which the user may specify only one. The name of the checked item is then returned to the REXX program along with the specification of any button(s) selected.
Below is the code used to generate vRadioBox (see Figure 3).
list.0 = 3
list.1 = ‘a. Use only first 9’
list.2 = ‘b. Review file now’
list.3 = ‘c. Abort operation’
call VRadioBox ‘Names file
limit exceeded!’, list, 1 select
when
substr(list.vstring,1,1) = ‘a’
then do
/* User selected first radio button... */
end
when substr(list.vstring,1,1) = ‘b’
then do
/* User selected second radio button... */
end
otherwise
/* User selected third radio button */
end /* Select */
vListBox—vListBox displays a selection list for a user to review or select from. The name of the selected item is then returned to the REXX program along with the specification of any button(s) selected. Unlike vCheckBox and vRadioBox, vListBox has no display limit.
Below is the code used to generate vListBox (see Figure 4).
/* list names in list_box from
the names_data array populated
earlier */
height = 12
width = 20
list_box.0 = names_data.0
names_data_title = “Charlie’s
Staff contents”
do i = 1 to names_data.0
list_box.i = names_data.i
end i
call VListBox names_data_title,
list_box, width, height, 1
vCheckBox—vCheckBox displays a list of up to 10 items, from which a user may specify one or more by clicking a checkbox. The names of the checked items are returned to the REXX program along with the specification of any button(s) selected. Here is an example of displaying a checkbox. To see what the vCheckBox looks like, refer to Figure 5.
/* list names in check_box from
the names_data array populated
earlier */
recip_list.0 = names_data.0
do i = 1 to names_data.0
recip_list.i = names_data.i
end i
checked.0 = 1
checked.1 = recip_list.1 /*
Default checked is first entry */
button = VCheckBox(‘ Choose
Recipients’, recip_list,
checked, 3)
if button = ‘CANCEL’ then signal
Cleanup_and_Exit
/* the function will set
checked.0 to the total number
of entries
checked and checked.1-n to the
selected entry text.*/
vInputBox—vInputBox displays a pop-up window with an input field for a user to enter data. The entered text is returned to the REXX program along with the specification of any button(s) selected. Figure 6 shows a sample vInputBox. Below is the code used to generate vInputBox.
/* Prompt user for message text */
width = 75
prompt.0 = 0 /* No additional lines
of message text */
prompt.vstring = ‘Fredo’’s been
involved in a terrible fishing
accident!’
button = VInputBox(‘Type message text
and press [ENTER]’, prompt, width, 3)
if button = ‘CANCEL’ then signal
Cleanup_and_Exit
message_text = prompt.vstring
What Lies Ahead
VREXX is simple way to add a sophisticated GUI interface to your OS/2 REXX command line programs. In my final OS/2 REXX article, which will appear in an upcoming issue of Client Access/400 Expert, I’ll combine all of the concepts introduced up to this point, including screen-parsing with EHLLAPI. We’ll also introduce some advanced VREXX functions to create windows and draw into them to create an OS/2 desktop application that continually monitors AS/400 CPU utilization in a graphical manner.
References
IBM’s EWS ftp site: ftp://software.watson.ibm.com/pub/os2/ews/vrexx2.zip ftp://members.aol.com/cmiksanek/xmpvrexx.zip Newsgroup: comp.lang.rexx
“REXX EHLLAPI for Client Access/400 Optimized for OS/2,” Client Access/ 400 Expert, March/April 1996
“Harvesting Data from the AS/400 for Workstation Applications,” Client Access/ 400 Expert, September/October 1996
OS/2 Procedures Language/2 REXX (available on softcopy in the OS/2 Information folder)
The REXX Language, A Practical Approach to Programming, Michael Cowlishaw, Prentice Hall (Cowlishaw is the designer of the REXX language.)
The REXX Language page at IBM Hursley: http://rexx.hursley.ibm.com/rexx/ rexx.htm
Figure 1: The vMsgBox
Figure 2: The vFileBox
Figure 3: The vRadioBox
Figure 4: The vListBox
Figure 5: The vCheckBox
Figure 6: The vInputBox
/*
To use this .cmd, ensure VREXX is correctly installed and the ‘.nam ’
files are available.
For bext effect, create an OS/2 program icon that is minimized on
start-up and attach this .CMD file to it.
*/
diag = 0 /* diagnostic level */
‘ @echo off’
if Rxfuncquery(‘ VInit’) then call RXFUNCADD ‘ VInit’, ‘VREXX’, ‘VINIT’
initcode = VInit()
if initcode = ‘ERROR’ then signal Cleanup_and_Exit
signal on failure name Cleanup_and_Exit
signal on halt name Cleanup_and_Exit
signal on syntax name Cleanup_and_Exit
/* Define Button Aliases */
Button_OK = 1
Button_Cancel = 2
Button_OK_and_Cancel = 3
Button_Yes = 4
Button_No = 5
Button_Yes_and_No = 6
ver = VGetVersion()
/* Welcome popup */
txt.0 = 10
txt.1 = ‘ This is a sample application to familiarize the user with some of’
txt.2 = ‘ the VREXX functions. You’’ll see that VREXX provides a robust’
txt.3 = ‘ assortment of dialog, window, and graphic functions to give any’
txt.4 = ‘ OS/2 REXX application a slick GUI’
txt.5 = ‘’
txt.6 = ‘ This sample application displays a list of names and allows’
txt.7 = ‘ the user to send a message to one or more using the Netware’
txt.8 = ‘ SEND command. If your network does not support this command’
txt.9 = ‘ or you otherwise choose to exit, click the [CANCEL] button now.’
txt.10 = ‘ If you want to proceed, click [OK].’
call VDialogPos 50, 50
button = VMsgBox(‘Welcome to the VREXX Sample Application, VREXX v’||ver, txt, Button_OK_and_Cancel)
if button = ‘CANCEL’ then signal Cleanup_and_Exit
/* Select Names File */
call VDialogPos 50, 50
button = VFileBox(‘Select a names file to use’, ‘*.nms’, name)
if button = ‘CANCEL’ then signal Cleanup_and_Exit
selected_file = name.vstring
rc = lines( selected_file)
if rc <> 1 then do
txt.0 = 2
txt.1 = ‘ ‘ ||selected_file
txt.2 = ‘ is not found or empty. Program aborting.’
call VMsgBox ‘File Error’, txt, Button_OK
signal Cleanup_and_Exit
end
/* Read names file and populate stem variable */
names_data_title = ‘’
names_data.0 = 0
name_maxW = 0
do while lines( selected_file) = 1
line_of_file = linein(selected_file)
if names_data_title = ‘’ then names_data_title = line_of_file
else do
names_data.0 = names_data.0 + 1
x = names_data.0
PARSE VALUE line_of_file with id ‘,’ name
names_data.x = name
id_data.x = id
if length(name) > name_maxW then name_maxW = length(name)
end
end /* while loop */
user_decision_1:
/* Check if file exceeds maximum name limit of 10 (9 choices + “all”) */
if names_data.0 > 9 then do
list.0 = 3
list.1 = ‘a. Use only first 9’
list.2 = ‘b. Review file now’
list.3 = ‘c. Abort operation’
call VRadioBox ‘Names file limit exceeded!’, list, Button_OK
select
when substr(list.vstring,1,1) = ‘a’ then do
names_data.0 = 9
end
when substr(list.vstring,1,1) = ‘b’ then do
list_box.0 = names_data.0
do i = 1 to names_data.0
list_box.i = left(i||’. ‘,4) names_data.i
end i
call VDialogPos 50, 50
call VListBox names_data_title||’ contents’, list_box, name_maxW*1.5, 12, Button_OK
signal user_decision_1
end
otherwise
/* Must be ‘c’ so just exit */
signal Cleanup_and_Exit
end /* Select */
end /* Names > 9 */
/* Select Recipients */
recip_list.0 = names_data.0+1
recip_list.1 = names_data_title||’ (all)’
do i = 1 to names_data.0
x = i + 1
recip_list.x = names_data.i
end i
checked.0 = 1
checked.1 = recip_list.1
user_decision_2:
button = VCheckBox(‘ Choose Recipients’, recip_list, checked, Button_OK_and_Cancel)
if button = ‘CANCEL’ then signal Cleanup_and_Exit
if checked.0 = 0 then do
txt.0 = 1
txt.1 = ‘ Check at least one recipient’
call VDialogPos 50, 50
button = VMsgBox(‘User Error’, txt, Button_OK)
signal user_decision_2
end
/* Prompt user for message text */
prompt.0 = 0
prompt.vstring = ‘Fredo’’s been involved in a terrible fishing
accident!’
call VDialogPos 50, 50
button = VInputBox(‘Type message text and press [ENTER]’, prompt, 75, Button_OK_and_Cancel)
if button = ‘CANCEL’ then signal Cleanup_and_Exit
message_text = prompt.vstring
/* Send specified message text to checked users*/
/* First, check for “all” request */
if checked.1 = recip_list.1 then do
checked.0 = 1 /* ignore any other checks on later redisplay */
do i = 1 to names_data.0
if diag > 0 then say “SEND to “ id_data.i
/* Build Novell SEND command string */
parm = ‘“‘||message_text||’” to ‘||id_data.i
“x:send.exe” parm
end i
end
/* loop through and send to all checked */
else do
/* Loop through names_data for a match for checked.x */
/* When found “ i” will then be the index into id_data */
do i = 1 to checked.0
do k = 1 to names_data.0
if checked.i <> names_data.k then iterate
if diag > 0 then say “Checked.i:” checked.i
if diag > 0 then say “SEND to “ id_data.k
/* Build Novell SEND command string */
parm = ‘“‘||message_text||’” to ‘||id_data.k
“x:send.exe” parm
leave
end k
end i
end
call VDialogPos 50, 50
button = VMsgBox(‘Message sent to:’, checked, Button_OK_and_Cancel)
if button = ‘CANCEL’ then signal Cleanup_and_Exit
signal user_decision_2
Cleanup_and_Exit:
call VExit/* VREXX Cleanup */
Just_Exit:
exit 0
Figure 7: Sample VREXX Dialog Function Application
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online