05
Thu, Dec
6 New Articles

A Visual OS/2 REXX Primer: Advanced Functions

General
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

In the last few months, I have written a series of articles introducing you to OS/2 REXX, EHLLAPI, and emulator screen parsing concepts, as well as OS/2 VREXX dialog functions. This article will combine all of those topics and also introduce another set of GUI functions to describe how a sophisticated desktop application—an AS/400 monitor, for example—can easily be created. By combining the simplicity of OS/2 REXX and the power of VREXX and EHLLAPI, you can create a desktop application (like the one shown in Figure 1) to continually monitor the CPU utilization of your AS/400. Before introducing the advanced VREXX windowing and draw functions, a review of requisite knowledge is in order.

OS/2 REXX

REXX has been included with OS/2 as far back as V1.2 and has fast gained popularity with users as a quick and easy method of creating programs. Its syntax is very intuitive, and most users can pick it up simply by reviewing existing programs. Further, with a little effort and some help from one of the online references available with OS/2, you can become REXX-proficient in a matter of days.

You may already be familiar with REXX because it’s one of the languages available on the AS/400. In fact, implementations of REXX are available on most of the IBM platforms, including MVS and OS/2. In 1987, IBM declared REXX the procedures language for its Systems Application Architecture (SAA), solidifying its future in programming circles.

EHLLAPI allows a workstation program to interface directly with an emulator session in much the same way as a user would. The emulator session makes no distinction between keystrokes entered by the keyboard and those entered programmatically via a


EHLLAPI

program that makes EHLLAPI function calls. Further, data presented on an emulation screen with which a user interacts is equally available to the workstation program to copy, parse, or search. By performing programmatic interactions with the emulator session window minimized, the emulator interaction can be masked from the user. OS/2 supports EHLLAPI calls made from a simple REXX program which makes programmatically accessing your emulator data a breeze.

Screen Parsing

A workstation screen-parsing program types the keystrokes necessary to produce a terminal display, then actually “reads” the resulting display. This “program operator,” as it’s called in EHLLAPI circles, functions exactly as a user would—it types keystrokes and reviews the output. A user can exploit this concept to create a workstation application that interacts with an emulator session to query system statistics or perform automated operations, for example.

VREXX for OS/2 REXX

Visual REXX for Presentation Manager, or VREXX for short, provides a robust suite of easily accessible GUI functions. With VREXX, your program can create windows, draw 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 standard REXX features, but the drab command line interface used to “say” text and “pull” user input is replaced with contemporary dialog boxes.

VREXX for OS/2 was introduced in the article “A Visual OS/2 REXX Primer,” which appeared in the January/February 1997 issue of Client Access/400 Expert. In that article, common dialog functions to invoke simple pop-up message and input boxes, as well as list and file boxes, were presented. In this article, advanced concepts such as windowing will be introduced, along with a new function set to support windowing and drawing. All of these features are available to a simple OS/2 REXX program.

VREXX lets a user create windows on an OS/2 workstation display by specifying the percentage of screen real estate a window will occupy, with the bottom left corner of the display being 0 percent and the top right corner being 100 percent. For example, to display a window occupying the center 50 percent of a display, the window create function call would specify 75 percent for the top, 25 percent for the bottom, 25 percent for the left, and 75 percent for the right. Figure 2 shows several windows. Window 1, for example, can be created specifying left and right values of 0 and 10, respectively. This tells VREXX that you want the window to occupy the 10 percent of the left-most side of the screen. Window 1 would have bottom and top values of 0 and 50, which positions it on the bottom half of the screen. Window 2 can be created by specifying left and right values of 25 and 75 and bottom and top values of 40 and 60. Window 3 requires left and right values of 40 and 100, and bottom and top values of 90 and 100.

Perhaps one of the most difficult concepts to grasp in VREXX drawing is window coordinates. A VREXX window is actually 1,000,000 separately addressable pixels. Lines have starting and ending addresses, polygons have corner coordinates, and so on. All points in a window are addressed using x,y coordinates, where the bottom-left point of the window has coordinates of 0,0, and the top-right corner has coordinates of 1000,1000.

To specify a line, polyline, or polygon, VREXX requires that the coordinates be bundled in a REXX stem variable and passed into the appropriate function. (For more information on stem variables, see “A Visual OS/2 REXX Primer” in the January/February 1997 issue of Client Access/400 Expert.) Figure 3 illustrates a polyline and the coordinates involved. In this example, four sets of coordinates are needed: 1,1; 3,7; 5,3; and 11,8.


The opportunities to exploit VREXX are endless. By combining dialog functions and windowing functions, a comprehensive application can be developed. One way to exploit this powerful functionality is to chart data in a window on a real-time basis. Consider the AS/400 pulse application illustrated in the OS/2 monitor sample program code in Figure 7. It continuously monitors an AS/400 and displays the results shown in Figure
1. It accomplishes this by combining VREXX and EHLLAPI functions to parse WRKSYSACT CPU screen output and continuously plot 100 samples on a dynamic graph. The routine invoked in this sample program is a slightly modified version of the code introduced in “Harvesting Data from the AS/400 for Workstation Applications” in the September/October 1996 issue of Client Access/400 Expert. Instead of writing the current CPU utilization to a log file, that code has been modified to return it to the calling program using an exit function like this:

exit Current_CPU * 10

You’ll note that the CPU value is multiplied by 10 because our window charts 1,000 pixels. A point at the very top of the screen, where y=1000, would have a CPU value of 100 percent.

VREXX Window and Draw Function Reference

I’ll describe some of the more useful VREXX windowing and draw functions. For a complete description of all of the VREXX functions, refer to the document titled “Visual REXX for Presentation Manager” included in the VREXX package. Before invoking VREXX functions, your REXX program must load and initialize VREXX. Refer to the VREXX sample code in Figure 7 for this procedure.

VREXX Windowing Functions

vOpenWindow—vOpenWindow creates a new window and returns a window ID, which is used in subsequent functions that perform an action on the window. When a window is created, title and background colors are specified. The colors can later be changed with the vSetTitle and vBackColor and functions, respectively. The window dimensions are specified by a stem variable representing screen percentages, as illustrated in Figure 2. The code in the VREXX sample program code shows how to create a window in the top-right portion of the workstation screen. vResize—vResize resizes and/or repositions a window on a workstation screen. It requires the window ID of the target window and a stem variable containing the new screen percentages. vCloseWindow—vCloseWindow closes a window created with vOpenWindow. It requires the target window ID. vSetTitle—vSetTitle changes the text in a window’s title bar. The sample code in Figure 7 illustrates how to change title bar text. vColorBox—vColorBox allows a user to select window background and foreground colors from a selection dialog. Lines, arcs, fill patterns, and text use the foreground color for display. Figure 4 illustrates a color selection box. vColorBox sets the color stem variable to the user’s selection, where color.fore is the selected foreground color and color.back is the selected background color. Subsequent calls to vBackColor and vForeColor are necessary to actually make the colors change. A user can select and view a sample of various combinations of background and foreground colors. If OK is selected, the function returns the selected colors. vBackColor—vBackColor sets a window’s background color to either black, white, red, green, blue, cyan, yellow, or pink. A sample invocation would be: call vBackColor win_id, ‘PINK’


vForeColor—vForeColor sets a window’s foreground color (the color used to display lines, text, etc.) to either black, white, red, green, blue, cyan, yellow, or pink. A sample invocation would be:

call vForeColor win_id, ‘BLACK’

VREXX Draw Functions

vSay—vSay draws a text string in the target window. The function requires three parameters: the target window ID; the x,y coordinate pair for the text starting point; and the text string. To draw a portion of the text displayed in Figure 5, the following code was used:

call VSay win_id, 50, 750, “Line and Markers”

vFontBox—vFontBox displays a dialog in which the user selects a font for subsequent vSay operations. vFontBox sets a stem variable to the user’s selection, where stem_name.type is the selected font type and stem_name.size is the selected font size. A call to vSetFont to pass in the selected font is necessary before the font will actually change. Figure 6 depicts a font selection box. A user can select and view various combinations of font types and sizes. If OK is selected, the function returns the selected font. vSetFont—vSetFont changes the font the vSay function uses to display text. vSetFont requires three parameters: the target window ID, the font type, and the font size. The font type can be either SYSTEM, SYMBOL, COUR (Courier), HELV (Helvetica), or TIME (Times Roman). Fonts can be made bold and italic, as well. Using HELVI will produce Helvetica italics, HELVB creates Helvetica bold, and HELVBI produces Helvetica bold italics. The font size must be a positive integer greater than 0. A sample invocation is this:

call vSetFont win_id, ‘HELV’, 12

vDraw—The vDraw function draws pixels, lines, and polygons using the current marker, line, and fill values. vDraw requires four parameters: the target window ID; the function type (i.e., PIXEL, LINE, or POLYGON); the x,y coordinate pair stem names; and the number of coordinate pairs specified. For example, to create a box similar to the one illustrated in Figure 5, the function call would need to specify the four coordinate pairs representing the box’s corners. That function call might look like this:

x.1 = 650; y.1 = 900 /* top left */

x.2 = 900; y.2 = 900 /* top right */

x.3 = 900; y.3 = 350 /* bottom right */

x.4 = 650; y.4 = 350 /* bottom left */

call VDraw win_id, ‘POLYGON’, x, y, 4

To create a multi-coordinate line similar to the one illustrated in Figure 5, the function call would need to specify the four coordinate pairs representing the various points. That function call might look like this:

x.1 = 100; y.1 = 100

x.2 = 500; y.2 = 400

x.3 = 500; y.3 = 200

x.4 = 600; y.4 = 700

call VDraw win_id, ‘LINE’, x, y, 4

The sample program to chart CPU utilization in the VREXX sample program code actually plots 100 points on the window and connects them all to describe current and historical CPU utilization. vDrawParms—vDrawParms sets the current marker type, line type, and fill type that will be used for subsequent vDraw operations. For example, if vDrawParms specifies a line type of dashes, all subsequent lines drawn will be dashed and not solid. Coordinate marker types (the diamonds delimiting the line in Figure 5 are examples of markers) may be a cross, circle, plus sign, square, diamond, as well as a few other shapes.

Polygons and circles inherit fill patterns. The shapes in Figure 5 inherited a fill type of solid. Some other fill types that may be specified are no fill and horizontal lines.


For polygons and enclosed arcs (circles), a fill type can be specified. End points for lines can be highlighted by specifying a marker type. Refer to “Visual REXX For Presentation Manager” in the VREXX package for information on the enumerated values vDrawParms requires for its parameters. vArc—vArc draws an arc or a complete circle using the radius; x,y center coordinates; and arc angles. To create the circle displayed in Figure 5, a call to vArc was made specifying the center x,y coordinates of 775,150 and a radius of 150. To accomplish a full circle, angle 1 and angle 2 were specified as 0 and 360 respectively. That function call looks like this:

call VArc win_id, 775, 150, 125, 0, 360

vClearWindow—vClearWindow erases the contents of the specified window. The sample program to chart CPU utilization in the VREXX sample program code uses vClearWindow on each refresh cycle prior to drawing a new 100-point line.

Building Sophisticated GUIs with VREXX

As you can see, VREXX is a simple way to add a sophisticated GUI interface to your OS/2 REXX command line programs making simple function calls to add powerful graphics to any REXX program. With a little imagination, I’m sure you can think of many ways you could use these tools in your shop.

References

IBM’s EWS ftp site: ftp://software. watson.ibm.com/pub/os2/ews/vrexx2.zip ftp://members.aol.com/cmiksanek/ xmpvrex2.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

“A Visual OS/2 REXX Primer,” Client Access/400 Expert, January/February 1997 OS/2 Procedures Language/2 REXX (available on softcopy in the OS/2 Information The REXX Language: A Practical Approach to Programming by 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: AS/400 Pulse Monitor Window


folder)

A_Visual_OS-_2_REXX_Primer-_Advanced_Functions05-00.jpg 450x190

A_Visual_OS-_2_REXX_Primer-_Advanced_Functions06-00.jpg 225x155

Figure 2: Defining a VREXX Window Figure 3: Plotting Line Points via a VREXX Stem Variable


A_Visual_OS-_2_REXX_Primer-_Advanced_Functions06-01.jpg 450x320

A_Visual_OS-_2_REXX_Primer-_Advanced_Functions07-00.jpg 450x347

Figure 4: The vColorBox Dialog Figure 5: A VREXX Window and Simple Draw Object Types


A_Visual_OS-_2_REXX_Primer-_Advanced_Functions07-01.jpg 450x338

A_Visual_OS-_2_REXX_Primer-_Advanced_Functions08-00.jpg 450x383

Figure 6: The vFontBox Dialog

/* REXX */
/*

This REXX program assumes VX_REAL.CMD is the

EHLLAPI routine which returns the current CPU

utilization.

To use this .cmd, ensure VREXX is correctly

installed.

For best effect, create an OS/2 program icon

that is minimized on start-up and attach this

.CMD file to it.

Sample invocations:

VX_PULSE DEMO

VX_PULSE REAL OzMoeSYS C

| | |

| | +-> Emulator

| | Session ID

| +-> AS/400 System ID

| displayed in the

| pulse window

| title bar

+-> Operating mode: Real or

Demo

*/

signal on failure name Failure_Exit

signal on halt name Halt_Exit

signal on syntax name Syntax_Exit

/* Get line input/parms */

parse arg Mode AS_400_ID Emulator_Session

call Process_Parms

call load_VREXX

call Create_Main_Window

call Initialize_Display_Matrix

Samples_Taken = 0

do FOREVER /* Only CNTL-C can stop :-) */

call Redraw_Display

call Shift_Display_Matrix

if mode = ‘DEMO’ then do

samples.100 = RANDOM(1,1000)

do _pause = 1 to 99999; end _pause

end

else do

call vx_real Emulator_Session

samples.100 = result

if result < 0 then signal Halt_exit

end

Samples_Taken = Samples_Taken + 1

new_text = ‘ Cur: ‘||Samples.100/10||’%’


call VSetTitle win_id, Win_Title||new_text

end /* Do forever */
/************************************************/

/* Exit Routines */
/************************************************/

Cleanup_and_Exit:

call VExit

exit
Halt_exit:

say ‘Halt exit’

signal Cleanup_and_Exit
Syntax_exit:

say ‘Syntax exit’

signal Cleanup_and_Exit
Failure_exit:

say ‘Failure exit’

signal Cleanup_and_Exit
/************************************************/

/* Subroutines */
/************************************************/

Load_VREXX:

call RxFuncAdd ‘VInit’, ‘VREXX’, ‘VINIT’

initcode = VInit()

if initcode = ‘ERROR’ then signal Cleanup_and_Exit

return
Create_Main_Window: win.left = 60; win.right = 100

win.top = 100; win.bottom = 80

win_title = ‘AS/400 Pulse [Demo Mode]’

if mode <> ‘DEMO’ then

win_title = ‘AS/400 Pulse for ‘||AS_400_ID

win_id = VOpenWindow(win_title, ‘WHITE’, win)

return
Process_Parms:

if Emulator_Session = ‘’ then Emulator_Session = ‘A’

if Mode <> ‘REAL’ then Mode = ‘DEMO’

if AS_400_ID = ‘’ then AS_400_ID = ‘[no AS/400 ID]’

return
Initialize_Display_Matrix: samples.0 = 100

do i = 1 to samples.0

samples.i = 1

end i

return
Shift_Display_Matrix:
/* shift entries left, dropping samples.1 and prepping samples.100 for new sample */

do i = 1 to 99

z = i+1

samples.i = samples.z

end i

return
Redraw_Display:
/*

Horizontally, the 1000-”pixel” window grid is

broken down into 100 reference points: 1, 10,

20, 30, etc.... The first point plotted is x=0

y=samples.1. The next point plotted is x=10

y=samples.2, etc...

*/

do i = 1 to 100

if i <> 1 then do

if i = 100 then l = 1000

else l = ( i-1 ) * 10

end /* i <> 1 */

else l = 1

x.i = l

y.i = samples.i

end

call VClearWindow win_id

call VDraw win_id, ‘LINE’, x, y, 100

return

This sample code plots and refreshes 100 points on a VREXX window. By calling another OS/2 REXX application, in this example an EHLLAPI emulator session parser, this application can dynamically chart AS/400 CPU utilization.

Figure 7: The OS/2 Pulse Monitor VREXX Program Code


BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More 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.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY 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.

  • SB HelpSystems ROBOT GenericForms 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.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA 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:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

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

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra 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: