VX-REXX Programmer's Guide by Watcom International Corporation

Edition	Availability
1 VX-REXX Programmer's Guide 1995, Watcom	aaaa Read Listen Locate

Introduction.........................................................................................................................................................1

What you should know before starting....................................................................................................1

How to use this manual............................................................................................................................1

Organization......................................................................................................................................2

Syntax conventions............................................................................................................................3

Online information...................................................................................................................................4

Online books......................................................................................................................................4

REXX information............................................................................................................................4

Context help at design time...............................................................................................................4

Technical notes........................................................................................................................................5

Other sources of information...................................................................................................................5

Setting up.............................................................................................................................................................7

Before you start........................................................................................................................................7

Check your VX-REXX package.......................................................................................................7

Check your machine..........................................................................................................................7

Installing OS/2 REXX, the Enhanced Editor and the resource compiler..........................................8

Installing VX-REXX...............................................................................................................................9

Send in your registration card................................................................................................................10

Watcom VX-REXX folder contents (Standard Edition).......................................................................10

VX-REXX.......................................................................................................................................10

Read Me First..................................................................................................................................11

VX-REXX Programmer's Guide.....................................................................................................11

VX-REXX Reference......................................................................................................................11

REXX Information..........................................................................................................................11

Samples...........................................................................................................................................11

Projects............................................................................................................................................12

Macros.............................................................................................................................................12

Color Palette....................................................................................................................................12

Font Palette......................................................................................................................................12

Watcom VX-REXX folder contents (Client/Server Edition)................................................................12

Database Administrator...................................................................................................................13

Chart samples..................................................................................................................................13

Database samples............................................................................................................................13

Chart Object Guide..........................................................................................................................13

Database Objects Guide..................................................................................................................13

Watcom VX-REXX directory contents.................................................................................................13

Buildvrx.CMD.................................................................................................................................13

Buildcso.CMD (Client/Server Edition only)...................................................................................13

Bpatch.EXE.....................................................................................................................................14

Recover.EXE...................................................................................................................................14

A simple program.............................................................................................................................................15

Starting VX-REXX................................................................................................................................15

Creating an application..........................................................................................................................16

Creating the user interface.....................................................................................................................16

Customizing object properties...............................................................................................................20

A preliminary run...................................................................................................................................22

A simple program

Attaching code to objects.......................................................................................................................22

A test run................................................................................................................................................27

Improving the application......................................................................................................................28

Running the application.........................................................................................................................32

Saving the application............................................................................................................................33

Stopping VX-REXX..............................................................................................................................33

Creating and running projects........................................................................................................................35

Projects...................................................................................................................................................35

VX-REXX and the Workplace Shell.....................................................................................................36

Creating a project...................................................................................................................................36

Opening an existing project...................................................................................................................36

Saving a project......................................................................................................................................36

Running a project...................................................................................................................................37

Making an executable............................................................................................................................37

Command line options...........................................................................................................................37

Adding objects to a window.............................................................................................................................39

Introduction to objects...........................................................................................................................39

Creating objects.....................................................................................................................................39

Using the tool palette.............................................................................................................................41

Sizing and moving an object..................................................................................................................42

Selecting objects....................................................................................................................................43

Copying and deleting objects.................................................................................................................43

Duplicating an object.............................................................................................................................45

Aligning objects.....................................................................................................................................45

Grouping objects....................................................................................................................................46

Moving objects to the front and back....................................................................................................47

Changing object properties..............................................................................................................................49

Property notebook..................................................................................................................................49

Changing property values......................................................................................................................50

Properties of copied and deleted objects................................................................................................53

Direct editing.........................................................................................................................................53

Adding and modifying routines.......................................................................................................................55

Introduction to routines..........................................................................................................................55

Event routines..................................................................................................................................55

General routines..............................................................................................................................55

Introduction to sections..........................................................................................................................55

Editing sections......................................................................................................................................56

Editing event routine sections.........................................................................................................56

Event routine names........................................................................................................................57

General routines..............................................................................................................................57

Using the section list.......................................................................................................................57

Creating a new section....................................................................................................................57

Default section header.....................................................................................................................58

Adding and modifying routines

Editing a section..............................................................................................................................58

Deleting a section............................................................................................................................59

Using the section editor.........................................................................................................................59

Searching.........................................................................................................................................59

Replacing.........................................................................................................................................59

Moving to a line..............................................................................................................................60

Accessing online information..........................................................................................................61

Jumping to another routine..............................................................................................................61

Using an external editor.........................................................................................................................61

Event routines of copied or deleted objects...........................................................................................62

Sharing sections.....................................................................................................................................63

Adding shared sections....................................................................................................................63

Editing shared sections....................................................................................................................63

Deleting shared sections..................................................................................................................63

Search order.....................................................................................................................................63

Programming with objects...............................................................................................................................65

The structure of a VX-REXX project....................................................................................................65

Code files.........................................................................................................................................65

Window files...................................................................................................................................65

Predefined routines..........................................................................................................................66

Multiple files and windows.............................................................................................................67

Interacting with objects from a program................................................................................................67

Referring to an object......................................................................................................................67

Renaming an object.........................................................................................................................68

Implicit and relative naming............................................................................................................69

Responding to events.......................................................................................................................70

Getting and setting properties..........................................................................................................71

Using object methods......................................................................................................................72

Using objects......................................................................................................................................................73

Common operations on objects..............................................................................................................73

Disabling objects.............................................................................................................................73

Hiding objects..................................................................................................................................73

Getting and setting the focus...........................................................................................................73

Input validation................................................................................................................................74

Setting the tab order........................................................................................................................74

Windows................................................................................................................................................74

Setting the border type....................................................................................................................75

Setting the caption...........................................................................................................................75

Adding minimize, hide, and maximize buttons...............................................................................75

Removing the system menu............................................................................................................76

Removing the title bar.....................................................................................................................76

Resizing objects in windows...........................................................................................................76

Getting and setting the window state..............................................................................................76

Setting the OS/2 window list title....................................................................................................76

Hints................................................................................................................................................76

Using objects

Displaying a background picture.....................................................................................................77

Push buttons...........................................................................................................................................77

Setting the caption...........................................................................................................................77

Creating a default button.................................................................................................................77

Creating a cancel button..................................................................................................................77

Using the Click event......................................................................................................................77

Radio buttons.........................................................................................................................................78

Setting the caption...........................................................................................................................78

Setting and getting the button state.................................................................................................78

Using the Click event......................................................................................................................79

Check boxes...........................................................................................................................................79

Setting the caption...........................................................................................................................79

Setting and clearing a check box.....................................................................................................80

Using the Click event......................................................................................................................80

Descriptive text......................................................................................................................................80

Setting the text.................................................................................................................................80

Entry field..............................................................................................................................................80

Setting and getting the value...........................................................................................................81

Masking the value...........................................................................................................................81

Write-protecting an entry field........................................................................................................81

Using cut, copy, and paste and delete.............................................................................................81

Using default and cancel push buttons............................................................................................82

Multi line entry field..............................................................................................................................82

Adding text to an MLE....................................................................................................................82

Using scroll bars and word wrap.....................................................................................................83

Write-protecting an MLE................................................................................................................83

Using cut, copy, and paste and delete.............................................................................................83

Using MLEs with a cancel button...................................................................................................84

Lists........................................................................................................................................................84

Setting the sort order.......................................................................................................................84

Adding items to the list...................................................................................................................85

Selecting and deselecting list items.................................................................................................85

Removing list items.........................................................................................................................86

Write-protecting drop down combo boxes......................................................................................86

Per-item data....................................................................................................................................86

Sizing drop down combo boxes......................................................................................................86

Using the Click event......................................................................................................................86

Using the Change event...................................................................................................................86

Using the DoubleClick event..........................................................................................................87

Using lists with default and cancel push buttons............................................................................87

Spin buttons...........................................................................................................................................87

Using spin buttons with numbers....................................................................................................87

Using spin buttons with a list of items............................................................................................87

Using the ReadOnly and NumericOnly properties..........................................................................88

Using default and cancel push buttons............................................................................................88

Pictures...................................................................................................................................................88

Setting the picture path....................................................................................................................89

Using objects

Creating 3-D effects........................................................................................................................89

Groups....................................................................................................................................................89

Setting a group box caption.............................................................................................................90

Adding objects to a group...............................................................................................................90

Removing objects from a group......................................................................................................90

Disabling objects in a group............................................................................................................90

Notebooks..............................................................................................................................................90

Changing the notebook binding......................................................................................................92

Changing the tab shape....................................................................................................................92

Using the MajorTabPos and BackPages properties........................................................................92

Adding pages at design time...........................................................................................................93

Setting the page tab text..................................................................................................................94

Setting the page status text..............................................................................................................94

Turning to a given page...................................................................................................................94

Adding pages at run time.................................................................................................................94

Preloading notebook pages..............................................................................................................95

Loading pages under program control.............................................................................................95

Removing pages at run time............................................................................................................95

Containers..............................................................................................................................................95

Setting the view...............................................................................................................................96

Creating detail view fields...............................................................................................................99

Record emphasis............................................................................................................................100

Adding records..............................................................................................................................101

Removing records..........................................................................................................................102

Selecting records...........................................................................................................................102

Setting detail view information.....................................................................................................102

Making fields invisible..................................................................................................................103

Positioning records........................................................................................................................103

Sorting records..............................................................................................................................103

Searching records..........................................................................................................................104

Sharing records between multiple containers................................................................................104

Moving a record from one container to another............................................................................104

Direct editing of records................................................................................................................105

Checking if a record is in a container............................................................................................105

Using the container ContextMenu event.......................................................................................106

Dragging and dropping records.....................................................................................................106

Interacting with the Workplace Shell............................................................................................110

Programming with the DragStart event.........................................................................................113

Sliders..................................................................................................................................................114

Setting up the slider ticks..............................................................................................................115

Setting and getting the slider value...............................................................................................115

Using a slider as a progress indicator............................................................................................115

Responding to the Track event......................................................................................................115

Value sets.............................................................................................................................................115

Setting the number of rows and columns......................................................................................116

Setting item types..........................................................................................................................116

Setting item values........................................................................................................................116

Using objects Handling the Click event...............................................................................................................116

Timers..................................................................................................................................................116

Setting the delay interval...............................................................................................................116

Starting and stopping timers..........................................................................................................116

Responding to................................................................................................................................117

Dynamic Data Exchange (DDE) Client...............................................................................................117

The VX-REXX console.......................................................................................................................117

Turning off the console.................................................................................................................117

Hiding, moving and clearing the console......................................................................................118

Removing the console from the OS/2 window list........................................................................118

Console input.................................................................................................................................119

Bitmaps, icons, and resources........................................................................................................................121

Loading bitmap and icon files..............................................................................................................121

System icons and pointers....................................................................................................................121

Loading bitmap and icon resources.....................................................................................................122

Adding resources to your project.........................................................................................................123

Using the resource editor...............................................................................................................123

Resource binding...........................................................................................................................124

Editing bitmaps and icons.............................................................................................................124

A note about icon formats.............................................................................................................125

The executable icon.......................................................................................................................125

Drag and drop operations..............................................................................................................................127

Drag and drop definitions....................................................................................................................127

Basic terminology..........................................................................................................................127

Adding drag targets to your project.....................................................................................................127

Files, records and objects..............................................................................................................128

Default and supported operations..................................................................................................128

Other formats.................................................................................................................................128

Passing the drop to the parent object.............................................................................................129

Container restrictions....................................................................................................................130

Handling drops.....................................................................................................................................130

Programming with the DragDrop event........................................................................................130

Programming with the MoveRecord event...................................................................................131

Adding drag sources to your project....................................................................................................131

The StartDrag method...................................................................................................................131

Dragging objects............................................................................................................................131

Dragging files................................................................................................................................132

Dragging to the shredder and printer.............................................................................................132

Adding menus to a program..........................................................................................................................135

Types of menus....................................................................................................................................135

Menu bar and pull-down menus....................................................................................................135

Pop-up or context menus...............................................................................................................136

Cascaded menus............................................................................................................................136

Menu properties...................................................................................................................................137

Adding menus to a program Menu editor..........................................................................................................................................138

Creating a menu...................................................................................................................................139

Adding code to menu items.................................................................................................................142

Creating a pop-up menu.......................................................................................................................143

Responding to a pop-up menu.............................................................................................................143

Using pop-up menus with containers...................................................................................................144

Creating a conditional cascaded menu.................................................................................................146

Changing menus at run time................................................................................................................146

Checking menu items....................................................................................................................146

Installing accelerators at run time.................................................................................................147

Using built-in dialogs and system functions.................................................................................................149

Predefined dialogs................................................................................................................................149

File selection dialog.......................................................................................................................149

Font selection dialog.....................................................................................................................151

Message dialog..............................................................................................................................152

Multiline message dialog...............................................................................................................153

Prompt dialog................................................................................................................................154

INI files................................................................................................................................................155

File system manipulation.....................................................................................................................155

Creating custom dialogs.................................................................................................................................157

Calling the modal window file.............................................................................................................157

Creating a new window file.................................................................................................................158

Returning a value.................................................................................................................................158

Running the program...........................................................................................................................160

Multiple file considerations.................................................................................................................160

Secondary windows.........................................................................................................................................161

Primary vs. secondary..........................................................................................................................161

Window list window............................................................................................................................161

Creating and editing a secondary window...........................................................................................162

Opening a secondary window at run time............................................................................................163

Closing a secondary window at run time.............................................................................................164

Saving a multiple window file.............................................................................................................164

Deleting a window...............................................................................................................................165

Multiple file projects.......................................................................................................................................167

Overview..............................................................................................................................................167

File list window...................................................................................................................................167

Creating and editing a new file............................................................................................................168

Calling a file.........................................................................................................................................169

Calling a code file..........................................................................................................................169

Calling a window file....................................................................................................................170

Returning a value.................................................................................................................................171

Returning multiple values.............................................................................................................171

Saving files..........................................................................................................................................172

Multiple file projects Saving one file...............................................................................................................................172

Removing or adding a file....................................................................................................................173

Saving a file as text..............................................................................................................................173

Loading a file.......................................................................................................................................173

Adding help to a program..............................................................................................................................175

Using IPF help files.............................................................................................................................175

Setting the file and title.................................................................................................................175

Help tags........................................................................................................................................175

Notes on IPF tags..........................................................................................................................176

Using text files for help........................................................................................................................176

Invoking help directly..........................................................................................................................177

Custom help.........................................................................................................................................178

Debugging a project........................................................................................................................................181

Run time program exceptions..............................................................................................................181

The interactive debugger......................................................................................................................182

Debugger windows........................................................................................................................182

Starting the debugger.....................................................................................................................184

Viewing REXX instructions..........................................................................................................184

Using breakpoints..........................................................................................................................184

Tracing a program.........................................................................................................................186

Displaying and modifying variables..............................................................................................186

Interrupting a program...................................................................................................................187

Executing a REXX instruction......................................................................................................187

Run time exception handling in the debugger...............................................................................188

Quitting the debugger....................................................................................................................188

Debugging with the say and trace instructions....................................................................................188

Extending VX-REXX......................................................................................................................................191

Object libraries.....................................................................................................................................191

Function libraries.................................................................................................................................191

Using databases with VX-REXX...................................................................................................................193

Overview..............................................................................................................................................193

Registering routines.............................................................................................................................194

Starting the database manager.............................................................................................................195

Connecting to the database..................................................................................................................195

Database API return codes...................................................................................................................196

Preparing the SELECT statement........................................................................................................196

Declaring a cursor................................................................................................................................197

Retrieving the data...............................................................................................................................197

Displaying results................................................................................................................................198

Closing the cursor................................................................................................................................198

Stopping the database manager............................................................................................................199

Where to go from here.........................................................................................................................199

Writing multithreaded applications..............................................................................................................201

Planning your application....................................................................................................................201

Starting a code file thread....................................................................................................................201

Starting a window file as a thread........................................................................................................202

Communicating with a thread..............................................................................................................202

Getting information about running threads..........................................................................................204

Halting a thread....................................................................................................................................204

Controlling other programs...........................................................................................................................205

Running programs and executing OS/2 commands.............................................................................205

The address instruction..................................................................................................................205

SysCreateObject and SysSetObjectData.......................................................................................205

Running commands that require OS/2 session VIO support.........................................................206

Redirecting standard input, output and error.................................................................................206

Manipulating windows........................................................................................................................207

Finding a window..........................................................................................................................207

Setting window properties.............................................................................................................207

Getting window properties............................................................................................................208

Window methods...........................................................................................................................209

Example programs.........................................................................................................................209

Sending keystrokes..............................................................................................................................209

Keystroke syntax...........................................................................................................................210

Controlling other applications.......................................................................................................211

Controlling a MultiLineEntryField...............................................................................................211

DOS and OS/2 Windows...............................................................................................................212

Dynamic Data Exchange (DDE) client................................................................................................214

Creating a DDE client...................................................................................................................214

Initiating a conversation................................................................................................................214

Executing server commands..........................................................................................................215

Requesting data.............................................................................................................................215

Sending data..................................................................................................................................216

Getting the status of a conversation..............................................................................................216

Terminating a conversation...........................................................................................................216

Application macros..............................................................................................................................216

Creating application macros with VX-REXX...............................................................................217

Using application macro examples................................................................................................217

Creating objects at run time..........................................................................................................................221

Using VRCreate and VRCreateStem...................................................................................................221

Setting properties at creation time.......................................................................................................222

Attaching events to an object...............................................................................................................222

Events and event queues......................................................................................................................222

Destroying objects...............................................................................................................................223

VX-REXX design time macros......................................................................................................................225

The PROFILE.VRM file......................................................................................................................225

Search order.........................................................................................................................................225

Installing macros..................................................................................................................................225

VX-REXX design time macros

Macro arguments.................................................................................................................................226

Functions and methods........................................................................................................................226

Distributing your projects..............................................................................................................................227

Run time library...................................................................................................................................227

Additional redistribution rights............................................................................................................227

Samples............................................................................................................................................................229

Bounce.................................................................................................................................................229

Button...................................................................................................................................................229

Calculator.............................................................................................................................................229

DDE Explorer......................................................................................................................................230

DragDrop.............................................................................................................................................230

Employee database...............................................................................................................................230

File browser.........................................................................................................................................230

Hint and Help.......................................................................................................................................230

Mind Game..........................................................................................................................................231

MMW...................................................................................................................................................231

Movies.................................................................................................................................................231

Notebook..............................................................................................................................................232

Popup...................................................................................................................................................232

Printing.................................................................................................................................................232

RGB.....................................................................................................................................................232

Scan......................................................................................................................................................232

Threads.................................................................................................................................................233

Window Controller..............................................................................................................................234

July 26, 2019	Edited by Martin Iturbide	Edited without comment.
January 24, 2016	Edited by freslocoke	Edited without comment.
January 24, 2016	Created by freslocoke	Added new book.

VX-REXX Programmer's Guide

by Watcom International Corporation