VisualAge Programming
VisualAge Programming
SC09-2449-07
iSeries
SC09-2449-07
Note!
Before using this information and the product it supports, be sure to read the general information under Notices on page
455.
Contents
About this Book . . . . . . . . . . . ix
Who Should Use This Book . . . .
Prerequisite and Related Information .
How to Use This Book . . . . . .
The VisualAge RPG Library . . . .
How to Send Your Comments . . .
Accessing Online Information . . .
Using Online Books . . . . . .
Publications in PDF Format . . .
Using Online Help . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. ix
. ix
. ix
. x
. xi
. xi
. xi
. xi
. xii
Client
. . . xiii
Client
. . . xiv
Client
. . . xiv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
3
5
5
5
6
6
6
6
6
7
7
7
8
11
11
12
12
12
15
15
15
16
17
19
.
.
.
.
.
.
.
.
19
19
19
20
Number of Windows . .
Content of Each Window .
Plan Your Code Effectively .
Keep the User Informed . .
Use a Consistent Style . . .
Anticipate Translation Issues
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
20
20
21
21
21
22
. .
. .
. .
. .
. .
. .
. .
. .
with
. .
.
.
.
.
.
.
.
.
25
25
26
27
27
28
28
29
. 30
. . .
. . .
. . .
Server .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
34
34
34
34
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
35
35
35
37
37
37
38
38
39
39
39
39
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
41
41
41
42
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
46
47
47
48
50
iii
Animation Control . . . . . . . . . . . .
Calendar . . . . . . . . . . . . . . .
Determining Which Date the User Selected . . .
Using Date Index Attributes . . . . . . . .
Canvas . . . . . . . . . . . . . . . .
Check Box . . . . . . . . . . . . . . .
Setting the State of a Check Box Part . . . . .
Setting a Mnemonic . . . . . . . . . .
Signaling Events . . . . . . . . . . . .
Combination Box . . . . . . . . . . . .
Selecting the Type of Combination Box . . . .
Adding and Setting the Initial Sequence of Items
Adding Items at Run Time . . . . . . . .
Updating Items in a List . . . . . . . . .
Setting the Top of the List . . . . . . . .
Removing Items . . . . . . . . . . . .
Selecting and Deselecting Items. . . . . . .
Retrieving a User-Selected Item . . . . . . .
Using Keys . . . . . . . . . . . . .
Setting the Entry Field Text . . . . . . . .
Signaling Events . . . . . . . . . . . .
Component Reference . . . . . . . . . . .
Referencing Part Attributes in Other Components
Monitoring for Events in Another Component . .
Container . . . . . . . . . . . . . . .
Adding Columns to a Container . . . . . .
Adding Records to a Container . . . . . . .
Updating Container Columns . . . . . . .
Removing Records from a Container . . . . .
Changing the Container View . . . . . . .
DDE Client . . . . . . . . . . . . . .
Entry Field . . . . . . . . . . . . . .
Using the InsertMode Attribute . . . . . . .
Using the Text Attribute . . . . . . . . .
Getting and Setting Information for a Window .
Validity Checking . . . . . . . . . . .
Preventing User Input . . . . . . . . . .
Masking Sensitive Data . . . . . . . . .
Graph . . . . . . . . . . . . . . . .
Sending data to the Graph . . . . . . . .
Graphic Push Button . . . . . . . . . . .
Setting the Image . . . . . . . . . . .
Assigning Command Keys . . . . . . . .
Signaling Events . . . . . . . . . . . .
Group Box. . . . . . . . . . . . . . .
Labeling a Group Box . . . . . . . . . .
Grouping Radio Buttons . . . . . . . . .
Horizontal Scroll Bar . . . . . . . . . . .
Image . . . . . . . . . . . . . . . .
Creating the Image Part . . . . . . . . .
Setting the File Name . . . . . . . . . .
Controlling the Magnification Panel . . . . .
Image Example . . . . . . . . . . . .
Java Bean . . . . . . . . . . . . . . .
Adding Beans to your Project . . . . . . .
Location of Bean JAR Files . . . . . . . .
Setting the JAR Classpath . . . . . . . .
Setting/Getting JavaBean Properties and
Invoking Methods . . . . . . . . . . .
List Box . . . . . . . . . . . . . . .
Adding and Setting the Sequence of Items . . .
iv
53
54
54
55
56
58
59
59
59
60
61
61
61
61
62
62
62
62
63
64
64
65
65
66
67
67
68
69
70
70
74
75
76
76
76
76
77
77
78
78
80
81
81
81
82
82
82
83
84
85
85
85
85
89
89
90
90
91
92
92
124
137
137
138
139
139
140
140
140
141
141
142
142
142
144
144
145
145
145
146
151
151
151
152
152
155
155
155
155
156
157
157
158
159
159
159
159
159
159
160
160
161
161
161
161
170
171
172
172
172
173
173
173
173
179
180
181
181
183
185
185
Terminating a Program . . .
Clearing Fields on a Window .
Example of a Window Part . .
*Component . . . . . . . .
Using the *component part . .
Displaying a File Open/Save As
Selecting a printer . . . . .
Using Plugins . . . . . .
. . .
. . .
. . .
. . .
. . .
dialog.
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
186
187
187
188
188
188
189
190
191
193
193
194
194
194
195
196
199
199
199
200
200
200
201
201
203
205
208
208
209
209
210
.
.
.
.
213
217
218
222
222
. 223
. 224
. 224
. . .
. . .
. . .
. . .
. . .
. . .
Debug
. . .
.
.
.
.
.
.
.
.
.
.
.
.
. 231
Contents
227
228
228
229
229
231
. 232
.
.
.
.
.
.
.
233
234
234
234
234
236
237
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 239
. 240
. 241
.
.
. 244
. 244
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
245
245
245
245
246
246
246
246
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
249
250
252
252
252
252
a HelpSet File
the Map File
the TOC File
the JAR File .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
vi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
254
255
255
256
259
259
260
261
261
261
262
262
263
263
. 265
.
.
.
.
.
.
.
.
.
.
.
.
.
.
266
266
266
266
267
267
267
267
267
269
270
272
273
273
.
.
.
.
.
274
274
275
277
277
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
279
280
281
283
283
286
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
287
287
287
288
290
291
291
. . . . .
. . . . .
. . . . .
from Another
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
293
295
296
297
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
299
301
301
323
339
340
.
.
.
.
342
344
345
346
348
. 348
349
. 349
Programs .
. . . .
. . . .
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
375
376
379
379
379
Data Types
. . . .
. . . .
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
381
382
382
383
383
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 389
. 389
. 389
391
391
397
399
412
412
412
. 423
. 423
. 423
423
. 424
. 424
.
.
.
.
.
.
.
.
431
432
433
434
436
437
441
443
443
. 448
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
449
449
450
452
Notices . . . . . . . . . . . . . . 455
Programming Interface Information .
Trademarks and Service Marks . .
.
.
.
.
.
.
.
.
. 456
. 456
Glossary . . . . . . . . . . . . . 457
Bibliography . . . . . . . . . . . . 469
Index . . . . . . . . . . . . . . . 471
Contents
vii
viii
ix
xi
xii
If Use Separate Folder is unchecked(default), all users will share the same
security file.
Part changes:
v Container: Allow setting of READONLY for the entire container. If the record
number is set to 0, READONLY applies to the whole container.
v Line Graph: Allow clicking a point on a line graph to set group & point values.
Previously, this operation was allowed on Bar or Pie graphs only. When clicked
on, the group & point value is set and the point is highlighted with a circle.
This publication includes updates from the Readme files of previous releases and
other technical corrections.
Changes are noted by a vertical bar (|).
Part changes:
Copyright IBM Corp. 1994, 2005
xiii
v *component:
Attributes SelFolder, DlgPrompt, and FolderName can be used to select a
folder.
Attribute FocusPart returns the name of the part that has the focus.
v Subfile: Attribute ByteComp can be set when sorting a subfile column. When
this value is set to 1, the sorting algorithm does a byte-by-byte comparison of
the two strings (the default is still to do a language sensitive comparison).
v Media: This part now works on Windows XP.
xiv
v
v
v
v
v
v
xv
xvi
c: is the drive where you installed the product and HOSTNAME is the
name of the iSeries server where you created the save file. (You can use
your servers TCP/IP address, instead.)
c. Enter your user ID when prompted for it.
d. Enter your password when prompted for it.
e. After you are signed on, make the USER library your current library. Enter:
Copyright IBM Corp. 1994, 2005
ftp>cd user
After installing the J2SDK, set the PATH environment variable to point to the
location of both the Java compiler and the Java Runtime Environment (JRE).
For example, if your home directory for the J2SDK is c:\jdk1.2, add the
following path statement: c:\jdk1.2\bin
Selecting Help Catalog displays the Get Help on using theCatalog window. If they
press one of the other push buttons, another window is displayed from which they
can perform other actions, such as view lists, preview clips, or submit a purchase
order.
Browsing by Category
Selecting Browe by Category displays the Video Catalog Categories window.
This window presents a list of video categories to choose from:
Action/Adventure
Children
Science Fiction
Comedy
Horror
Western
Romance
Classics
To select a category, the customer presses its associated push button. This displays
the Video Titles window, which lists the items for that category. Customers can
preview some of the titles, add a title to their order, delete it from their order if
they change their mind, and submit their order to the cashier.
Previewing Titles
Customers can preview a video that is on a list by reading a review of it or, if they
have the appropriate hardware and software, by viewing a clip of it with
associated audio.
Submitting Orders
When customers submit their orders, they must provide their name, address, and
phone number on the Video Catalog Order Reference window. This information
is stored in a database on the iSeries 400 server.
If you want to see the design for the sample application, select Edit from the
pop-up menu of the Video Store Catalog project folder in the VisualAge RPG
Sample Applications folder. This displays the applications project window and the
parts palette. The project window shows all the windows defined for the
application. Double-click on an entry to see its design window with the associated
parts. To view the projects VARPG source code, select Project>Edit source code
from the project window.
The Comedy window displays the list of comedy videos that customers can
purchase. This section describes how you can create a window similar to this one.
Setting Attributes
After a part is placed and positioned on the window, you can modify the default
settings for the part attributes using its properties notebook. To do this, right-click
on the part and select Properties from the parts pop-up menu.
Some of the part attributes you can modify are described below.
Chapter 1. Creating a Client/Server Application
Window attributes
You can select the items you want to appear on the window (such as system menu,
title bar, and minimize and maximize buttons), and configure the border of the
window. By default, the window uses the system font and has a white
background. You can change the font and color.
Canvas attributes
By default, the canvas part uses the system font, and is the same color as the
folder background. You can change the font and background color of the canvas
part. You can also place a graphic on the canvas part.
Subfile attributes
By default, the subfile part is created with no columns. If you know the database
field names, you can create subfile entry fields using the GUI Designer. Otherwise,
you can reference the existing fields in the database by following these steps:
1. Select Define reference fields from the Server menu. The Define Reference
Fields window appears.
2. Specify the iSeries 400 server and library information to view the database field
information.
3. Select the appropriate fields from the Fields list box with the right mouse
button, move the pointer icon onto the subfile part in the design window, and
right-click again.
The new subfile entry field inherits the attributes from the original field:
Length is set to the column width, and Type is set to the data type.
Set the style and data type for a subfile entry field using the appropriate properties
notebook. For example, you can set the length, or the type of data.
1. Write an action subroutine to handle the Press event for the Comedy push
button.
We wrote the COMEDYGPB action subroutine (shown in Figure 2) to handle
this event. When the user presses the push button, the COMEDYGPB
subroutine calls the brComedy user subroutine. This subroutine reads the
database and calls another user subroutine, dspbrowse, to check if the database
is empty. If it is, a message is displayed. If it is not empty, control returns to the
brComedy user subroutine, the title of the window is changed, and the results
of the database search are displayed.
*********************************************************************
**
**
** Categories window action-link subroutines
**
**
**
**
**
*********************************************************************
*
* This routine is executed when the Comedy graphic push button in the
* Categories window is pressed.
*
C
COMEDYGPB
BEGACT
PRESS
CATW
C
z-add
0
srchdir
C
z-add
0
srchact
C
exsr
brComedy
C
ENDACT
2. Write program logic to read the Comedy video titles from the database and
populate the subfile part with the list of titles. Call the dspbrowse subroutine to
check whether the database is empty. If the database is not empty, set the title
for the browse window to display the found comedy titles. Otherwise, display
message number MSG0001 to inform the user that no match was found in the
database. See Figure 3 on page 10.
*********************************************************************
*
*
* User Subroutine: brComedy
*
* Description
: Show browse window with comedy videos
*
*
*
*********************************************************************
C
C
brComedy
BEGSR
clear
browsesf
* Get records from vil0004, the logical file on the AS/400
* for comedy type videos.
C
*start
setll
vil0004
C
read
vil0004
61
C
*IN61
doweq
0
C
exsr
ckcriteria
C
read
vil0004
61
C
end
C
exsr
dspbrowse
* The next three lines set the browse windows title bar text.
C
movel
*blanks
vdocatstl
C
movel
stlcmdy
vdocatstl
C
eval
%setatr(browsew:browsew:Label) =
C
vdocatttl
C
ENDSR
.
.
.
*********************************************************************
*
*
* User Subroutine: dspbrowse
*
* Description
: Check if the browse subfile is empty. If so,
*
*
display message MSG0001 saying match not found.
*
*
*
*********************************************************************
C
C
C
C
C
C
C
C
C
dspbrowse
items
*MSG0001
BEGSR
eval
ifeq
dsply
else
eval
eval
endif
ENDSR
items=%getatr(BROWSEW:BROWSESF:Count)
0
msgrsp
9 0
%setatr(BROWSEW: BROWSEW: VISIBLE)=1
%setatr(BROWSEW: BROWSEW: FOCUS)=1
Figure 3. Reading the iSeries Database and showing the results window
10
*********************************************************************
* When the preview button in the browse window is pressed, the common
* component is started. The common component displays the preview
* window of a video.
*
*
C
PREVIEWPB
BEGACT
PRESS
BROWSEW
C
READS
BROWSESF
55
C
*IN55
ifeq
0
C
start
common
C
parm
brsfpart
C
endif
C
ENDACT
The Preview window uses the multimedia capabilities of the operating system to
give customers a glimpse of a video clip. This section describes how you can create
a window that resembles the above.
Note: To run the audio in the preview, you must have a sound card on your
system. To run the video clip, you must have a Media Player installed. Java
applications require the Java Media Framework (JMF) API.
11
Pause
Play
Record
Stop
12
*********************************************************************
*
Fvideo
if
e
k disk
remote BLOCK(*YES)
*
DFlg
s
1
inz(*OFF)
DFldx
s
12
*
*********************************************************************
*
C
*entry
PLIST
C
parm
partno
5 0
*
*********************************************************************
* Action link subroutines for PREVIEWW
*
*********************************************************************
*
C
PREVIEWW
BEGACT
CREATE
PREVIEWW
C
partno
setll
video
50
C N50*msg0001
DSPLY
msgrsp
9 0
C
read
video
51
C
*IN51
IFEQ
0
C
TITLEST
SETATR
vititle
label
C
DIRST
SETATR
vidirect
label
*
C
viactr1
CAT
viactr2:1
actors
41
C
ACTST
SETATR
actors
label
*
C
ABSTMLE
SETATR
vireview
text
*
* If its for Java, use .mov file
/If defined(COMPILE_JAVA)
*
C
vibitmap
CAT
.mov:0
videofil
13
* If its not for Java, then use .avi file
/else
C
vibitmap
CAT
.avi:0
videofil
13
/EndIf
C
endif
*signify videofil is not yet loaded to Audio part
C
move
N
loaded
*
C
ENDACT
*
*
13
*********************************************************************
*
C
PBPLAY
BEGACT
PRESS
PREVIEWW
*
C
if
loaded=N
C
eval
%setatr(previeww:audo:FileName)
C
=videofil
C
move
Y
loaded
1
C
endif
*
C
eval
%setatr(previeww:audo:audioMode)=2
*
C
ENDACT
*
*
*********************************************************************
*
C
PBPAUSE
BEGACT
PRESS
PREVIEWW
*
C
eval
%setatr(previeww:audo:audioMode)=1
C
ENDACT
*
*
*********************************************************************
*
C
PBRECORD
BEGACT
PRESS
PREVIEWW
*
C
eval
%setatr(previeww:audo:audioMode)=3
C
ENDACT
*
*
*********************************************************************
*
C
PBSTOP
BEGACT
PRESS
PREVIEWW
*
C
eval
%setatr(previeww:audo:audioMode)=4
C
ENDACT
*
*
Figure 6. The Preview Component (Part 2 of 3)
*********************************************************************
*
C
CANCELPB
BEGACT
PRESS
PREVIEWW
*
C
move
*on
Flg
C
STOP
C
ENDACT
*
*
*********************************************************************
*
C
PREVIEWW
BEGACT
CLOSE
PREVIEWW
*
C
if
Flg=*ON
C
eval
Fldx=*DEFAULT
C
else
C
eval
Fldx=*NODEFAULT
C
endif
C
ENDACT
Fldx
*
14
Creating Messages
To add messages, select Project>Define messages from the GUI Designer. The
Define Messages window appears. Select Create, and then select the type of
message you want to create (for example, information or warning). Type the actual
text for the message, and any additional information or second-level help, in the
spaces provided.
VisualAge RPG automatically generates a message ID for the message you create.
Reference that message ID in your code. For example, in Figure 3 on page 10,
MSG0001 is used by the DSPLY operation code.
Context-sensitive help
Add context-sensitive help to the Browse by Category graphic push button part by
selecting Help text from the parts pop-up menu. This starts an edit session that
already contains information similar to that shown in Figure 7.
:h1 res=01.PSB0000C
:p.Help
The :h1 res=01. is a heading tag containing a resource identifier. The resource
identifier is automatically generated do not edit this text. The heading appears
directly after this tag; it is used on the help panel and listed in the help index at
run time. By default, the name of the part for which you are adding text is used as
the heading. You should replace that with a heading that identifies the purpose of
the help panel and is more meaningful to users. Type the actual help text after the
:p. tag. By default, the word Help appears in the edit session.
An example of help text from the Video Store Catalog application is shown in
Figure 8. The help panel that is generated from that source and displayed at run
time is shown in Figure 9 on page 16.
:h1 res=12.Browse by Category
:p.Select this to browse videos by categories.
15
16
Figure 11. Example of help for a window that contains a hypertext link
For more information about creating online help for your application, see the
following topics:
v Chapter 13, Tips for Creating Online Help with IPF, on page 245
v Chapter 14, Tips for Creating and Using Windows Help, on page 249
v Chapter 15, Tips for Creating JavaHelp, on page 253
17
You respond to events in your program by coding the BEGACT (begin action)
and ENDACT (end action) operation codes. The code between these operation
codes, called an action subroutine, is executed for a particular event. If you do
not code an action subroutine, no action is taken when the event occurs.
5. Adding Messages and Online Help
In addition to creating the GUI and writing some program logic to make it run,
you can add messages and online help to your application.
18
19
Other ways to help your users are to give them all the information they need to
complete a task, and to provide meaningful prompts and labels on GUI parts. You
can use an ellipsis (...) to indicate that more information is needed before a
particular action can be performed. (For example, use Display... to tell users that
they will be prompted for more information before the display action is carried
out.) Do not use an ellipsis on a label if the action will be performed immediately
after the button is pressed. For example, a Help button does not need an ellipsis
because the help information is displayed as soon as the button is pressed. You can
also provide help in the form of a static text field that is updated when the mouse
pointer moves over different parts of your interface.
You can minimize the amount of information that your users have to provide by
setting default values. For example, you can use a combination box part to give
users the option of selecting from a list of commonly used choices. This prevents
key-in errors at run time.
Number of Windows
It is a good idea to have one main window from which the user can initiate all of
the main tasks. Provide secondary windows for additional information that users
must specify to complete a task.
Avoid a lot of nested windows because too many layers make a simple task look
complex. Also remember that too many windows will clutter the screen, especially
if the user has more than one application running. Users can also get lost if they
have many windows on their screen.
Try to minimize the number of parts in each window. This will increase
performance when windows are displayed. An application with many windows
and few parts per window will perform better than the same application with
fewer windows and more parts per window.
20
21
22
23
24
25
Responding to Events
Each part responds to a set of predefined events. You can use one of the following
methods to obtain a list of predefined events:
1. Refer to the VisualAge RPG Parts Reference for a complete list.
2. Press F1 when focus is on the part in the palette or catalog to get a general
description of the part and a list of the attributes and events associated with it.
3. In the GUI Designer, invoke the pop-up menu for the part, and select the
Events item.
Events are typically generated as the result of some interaction with the user
interface. For example, pressing a push button signals a Press event. Events can
also be generated by your program. For example, the DDE Client part generates a
Timeout event if it is unable to start a conversation with a server program within a
predetermined time period. If your program changes the text value of an entry
field part, a Change event is signaled by the entry field.
You respond to events in your program by coding the BEGACT (begin action) and
ENDACT (end action) operation codes. The code between these operation codes,
called an action subroutine, is executed for a particular event. When you create an
action subroutine for a specific event, an action link is defined. If you did not code
an action subroutine for a particular event, no action is taken when the event
occurs. The code in an action subroutine is executed until the ENDACT operation
code is reached. Therefore, if you coded EXSR operation codes within an action
subroutine, these subroutines (called user subroutines) are also executed.
You cannot invoke an action subroutine using the EXSR operation code. You can,
however, invoke a particular action subroutine by more than one action. For
example, you can have code that is executed when a push button is pressed or
when a menu item is selected. You can review which events have action
subroutines and modify link events to action subroutines in the Action Subroutines
window. To display the Action Subroutines window:
1. Select Edit source code from the Project menu in the GUI Designer. This starts
an edit session.
2. From the edit session, select Edit>Action subroutines. The Action Subroutines
window appears.
Event attributes contain data that is relevant to an event. For example, the
MouseMove event stores the X and Y coordinates to indicate where the mouse was
located when the event occurred. Before you can use event attributes in your
program, they must be defined on definition specifications. The name of the event
attribute is the name of the entity on the definition specification. Because the
compiler does not verify the length of the variable and some attributes have
varying lengths, be sure to specify a length large enough to contain the expected
value.
Note: Event attributes cannot be changed by your program. Therefore, they cannot
appear in a result field or as the target field for an EVAL operation.
The VisualAge RPG Parts Reference describes all the event attributes.
The following example illustrates how the %MouseX and %MouseY event
attributes can be defined and used in a program.
26
*
* Define mouse x and y coordinate event attributes
*
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++++++++++++++++++
D%MouseX
S
4P 0
D%MouseY
S
4P 0
*
* Check if Mouse coordinates in range:
*
CSRN01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq...
CSRN01Factor1+++++++Opcode(E)+Extended-factor2++++++++++++++++++++++++++
C
%MouseX
ifgt
100
C
%MouseY
andgt
100
C
..
C
endif
*
***** End of Source
System Attributes
System attributes pertain to your application rather than to a specific part.
As with event attributes, system attributes must be defined on a definition
specification. They cannot be modified by your program.
VisualAge RPG supports the following system attributes:
Table 1. System Attributes
Attribute
Description
Type
Length
%DspHeight
Numeric
%DspWidth
Numeric
27
28
When a READ is performed, where does VisualAge RPG store the retrieved value?
When a WRITE is performed, what value does VisualAge RPG use to set the
value?
For each entry field part, VisualAge RPG creates a field with the same name as the
part. This field is defined to match the definition of the Text attribute (or the Label
attribute for static text parts). For example, if there is an entry field part called
ENT00012, and the Text attribute is defined as character 20, then VRPG
automatically defines a 20-character field called ENT00012. You can use this field in
your program.
You can override the definition of the field on a definition specification by defining
a field of the same name. However, the definition of the field must comply with
the rules of VisualAge RPG concerning type and length compatibility. For example,
the field must be the same length as the attribute definition. For numeric fields, the
field does not have to be the same type as the attribute definition.
When you run your application, the value of an entry field is initialized by the
value that you supplied in the GUI Designer. However, you can overwrite this
value by setting the INZ keyword in your definition specification, or by moving a
value into the program field. In these cases, the value stored in each of these fields
does not necessarily match the value that you see on the screen for the
corresponding part.
If you store a different value in a field in a user or action subroutine, VisualAge
RPG does not reflect that new value on the screen. Therefore, the value stored in
the field is different from what is displayed on the screen. To reflect the stored
value on the screen, you must use a WRITE operation or a SETATR operation.
The same holds true for SHOWWIN. When a window is first opened, the values
that appear on the screen correspond to the values supplied for the parts in the
GUI Designer. If you change the stored value for a corresponding VisualAge RPG
field before you show the window, then the value in the field does not match what
is seen on the screen. To make the two values identical, you have to perform a
WRITE operation or a set attribute operation in an action subroutine that is linked
to the Create event for the window. This synchronizes the value stored in the field
with the value on the screen, and the user sees only the new value when the
window is shown.
In general, it is a good idea to use an action subroutine that is linked to the Create
event to set values that should appear on the screen when a window is opened.
29
RESET
Sets static text and entry field parts back to their initial values.
The window operation codes use these attributes:
Text
Label
Attribute of static text parts that is used to perform READ, WRITE, and
RESET operations.
Example
The following example shows what can happen when you set the value of one of
the parts to a value of another part when the parts share a field.
1. Define the fields: The Entry field A01 in window W1 is defined as character
10, and the Entry field A01 in window W2 is defined as character 10. The value on
the screen for W1 is 78893, and the value on the screen for W2 is 885364. Field A01
contains the value 0000000000. These are the initial values.
W1
A01
30
78893
W2
A01
885364
Program Field
A01
0000000000
2. Perform a READ on W1: Field A01 now contains 78893. This matches entry
field A01 in W1.
W1
A01
78893
W2
A01
885364
Program Field
A01
78893
3. Perform a WRITE on W2: The screen value of entry field A01 in W2 is now
78893.
W1
A01
78893
W2
A01
78893
Program Field
A01
78893
4. Perform a CLEAR on W2: Field A01 now contains blanks. This matches entry
field A01 in W2. The Entry field A01 in W1 - value on screen is 78893. The Entry
field A01 in W2 - value on screen is blank.
W1
A01
78893
W2
A01
Program Field
A01
5. Perform a GETATR on entry field A01 in W1 with target field A01: Field A01
now contains 78893. This matches entry field A01 in W1.
W1
A01
78893
W2
A01
Program Field
A01
78893
If you want all the parts that share a field to display the same value, then you
have to perform SETATR operations on all the parts using the field as the source
value, or perform WRITE operations on all the windows that contain one of these
parts.
It is recommended that you give unique names to all entry field parts in your
component to avoid accidentally setting the value of one of the parts to the value
of another.
31
32
Description
Animation
ActiveX
Bean
Calendar
Container
Customer Maintenance*
DDE Client
DDE Hotlink
Graph
Image*
Listbox
Message Subfile
Multiline Edit
Notebook
Odbcceld
Popup Menu
Progress
Resize
Resize example
Runtime_control_of_server_connections
Scroll
Slider**
Spin Button
Subfile*
Timer
VARPG Plug-in
Welcome
Welcome example
33
Notes:
1. * This example requires data on an iSeries 400 server.
2. ** Also shows how to use the BackMix and ForeMix attributes
After installing the J2SDK, set the PATH environment variable to point to the
location of both the Java compiler and the Java Runtime Environment (JRE). For
example, if your home directory for the J2SDK is c:\jdk1.2, add the following path
statement: c:\jdk1.2\bin
If you plan to run VisualAge RPG applets inside a browser, the international
version of the JRE must be installed on the client workstation.
34
PartName Attribute
All parts have a name. VisualAge RPG automatically generates this name when the
part is created. You can change the name of the part in its properties notebook or
by editing it directly in the tree view of the GUI Designers project window. The
*component part name cannot be edited.
Note: You cannot change the part name at run time.
Each window must have a unique name, and all parts on a given window must
have unique names. Parts on different windows can have the same name, except
for subfile part names, which must be unique across your component.
The compiler implicitly defines a field name for entry field and static text parts
using the PartName attribute. You can use that name in your program if you want
to refer to the value of these parts. For more information, see Chapter 3,
Programming with Parts, on page 25.
If you change the name of a part, you must change all references to that part in
your program source. If you attempt to reference the old name of a part that has
been renamed, you will get either compile errors, or a runtime error indicating that
the part could not be found.
ParentName Attribute
The ParentName attribute returns the name of the parent part. The parent is the
window on which a part is placed. For a window part, the parent is the window
itself.
PartType Attribute
You can use the PartType attribute to determine the type of a part in your
program. PartType returns the type of the part as defined by VisualAge RPG. The
value returned for VisualAge RPG parts consists of the string FVDES followed by
the part type. For example, for an entry field part, the part type would be
FVDESEntryField. One exception to this rule is the component reference part; it
has a prefix of FVDESV.
Table 3 summarizes the PartType attribute value for each VisualAge RPG part.
Table 3. The PartType attribute for VisualAge RPG parts
PartType attribute
FVDESOCX
ActiveX
FVDESAnimationControl
Animation control
FVDESCalendar
Calendar
FVDESCanvas
Canvas
35
36
PartType attribute
FVDESCheckBox
Check box
FVDESComboBox
Combination box
FVDESContainerControl
Container
FVDESVComponentReference
Component reference
FVDESDDEClient
DDE client
FVDESEntryField
Entry field
FVDESGraph
Graph
FVDESGraphicPushButton
FVDESGroupBox
Group box
FVDESHScrollBar
FVDESImage
Image
FVDESJavaBean
Java Bean
FVDESListBox
List box
FVDESAudio
Media
FVDESMediaPanel
Media panel
FVDESMenuItem
Menu item
FVDESMessageSubfile
Message subfile
FVDESMultiLineEdit
Multiline edit
FVDESNotebook
Notebook
FVDESNotebookPage
Notebook page
FVDESODBCInterface
ODBC/JDBC Interface
FVDESOutlineBox
Outline box
FVDESPopUpMenu
Pop-up menu
FVDESProgressBar
Progress bar
FVDESPushButton
Push button
FVDESRadioButton
Radio button
FVDESSlider
Slider
FVDESSpinButton
Spin button
FVDESStaticText
Static text
FVDESStatusBar
Status bar
FVDESSubfile
Subfile
FVDESSubmenu
Submenu
FVDESTimer
Timer
FVDESVScrollBar
FVDESFrameWindow
Window
Color Attributes
You can change the color of most parts by using the BackColor and ForeColor
attributes. The attribute values are numbers that represent specific colors. The
compiler provides a set of figurative constants, such as *RED and *GREEN, that
you can use to set the colors. Refer to the VisualAge RPG Language Reference for
these names.
You can specify a color mix for the part by using the ForeMix and BackMix
attributes. The value of these attributes represents a mixture of the primary colors
of red, green, and blue. This is often referred to as the RGB color value. This RGB
value is a string consisting of three values separated by colons (:). Each value
represents the intensity of red, green, and blue, in that order. The value of each
color is between 0 and 255.
In the following code example, the background color mix of a static text part is set
to a medium shade of blue:
CSRN01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq..
*
C
ST1
setatr
000:000:128 BackMix
For a more detailed example on how to specify the ForeMix and BackMix
attributes, see Slider on page 145.
Enabled Attribute
When a part is enabled, it can respond to user interaction and generate events. For
example, when an enabled push button is pressed, it generates a Press event that
may then be handled by your program.
You may not want a part to be enabled until a certain condition exists. In the case
of the push button, you may want the user to be able to press it only when an
item has been selected in a list box.
When a part is not enabled, it does not respond to user interaction, and its label is
dimmed.
To enable a part, set its Enabled attribute value to 1. If you do not want it to be
enabled, set this value to 0.
37
If your application runs on systems that use monitors with different resolutions,
you can use the %DspWidth and %DspHeight system attributes to ensure that
the windows are visible regardless of the screen resolution. You may want to
position the window in the center of the screen, or at some other coordinate.
Heres a calculation that can be done in the Create event for a window. This
example calculates the appropriate coordinates to center a window called Window1;
then moves the window to a new coordinate before displaying it on the screen.
*
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++
*
* Declare the display size system attributes
D%DspHeight
S
4P0
D%DspWidth
S
4P0
*
CSRN01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq
*
* Handle create event for Window1.
* Gets screen size and calculates pixel coordinates to
* position the window in the center of the screen.
*
C
WINDOW1
BEGACT
CREATE
WINDOW1
*
* Get the windows dimensions:
C
Window1
GETATR
Width
winWidth
4 0
C
Window1
GETATR
Height
winHeight
4 0
*
* Calculate new coordinates to center window
C
%DspWidth
SUB
winWidth
newLeft
4 0
C
%DspHeight
SUB
winHeight
newBottom
4 0
C
newLeft
DIV
2
newLeft
C
newBottom
DIV
2
newBottom
*
* Center the window and make it visible
C
Window1
SETATR
newLeft
Left
C
Window1
SETATR
newBottom
Bottom
C
Window1
SETATR
1
Visible
C
ENDACT
*
Visible Attribute
You can use the Visible attribute to specify when you want a part or a window to
be displayed. For example, you may want a push button to appear on the screen
only at run time. To do this, when you create the push button in the GUI Designer,
go to the properties notebook for the part and set the visible flag off. Then, at run
time, set the Visible attribute value to 1 when you want the push button to appear.
Focus Attribute
The area of a window where a user can interact with the interface has input focus.
The part that has input focus must be enabled to respond to user actions, such as
the pressing of a key or a button.
There are times when you want to focus on a part in your program so that the
user can use it immediately. For example, if you are checking several entry fields
and require the user to re-enter information in a particular entry field, you would
set the Focus attribute value to 1 for that entry field. When you set the attribute,
the cursor appears where the user can begin typing data into the entry field.
38
In addition to giving focus to a particular part, you can determine if a part has
gained focus. A part gains focus when the user selects it by either tabbing to it or
by selecting it with the mouse. When this happens, a GotFocus event is generated
for the part. Conversely, a LostFocus event is generated when a part loses focus.
UserData Attribute
All parts support the UserData attribute. Use this attribute to assign any text string
to a part. This string has no effect on the value of any other attribute of the part,
and it is not displayed. The UserData attribute can contain a maximum of 65,535
characters.
Label Attribute
Several parts have a Label attribute. This is descriptive text that explains the
purpose of the part. The text that appears on a push button is an example of this
attribute.
The following parts have a Label attribute:
v Check box
v Container
v Group box
v Menu item
v Push button
v Radio button
v Static text
v Window
v Window with canvas
Label Substitution
You can substitute the text of a label by using a symbol when you set the Label,
TabLabel, or InfoLabel attributes. This is particularly useful if you are developing
applications for use with other languages, because it allows you to translate labels
and messages that you defined in the GUI Designer.
When you specify label substitution for a part, an entry is made in the
components message file. Multiple parts can use the same label substitution (for
example, ^OK.). The same message file entry is used for all references.
You define a substitution label for a part in its properties notebook by specifying a
string, with no imbedded blanks, preceded by the caret (^) symbol. This adds a
message to the message file. Select Project>Define Messages... to invoke the
message editor and add the message text you want to replace the Label attribute
when the application is run.
Translation Tips
When sizing a part in the GUI Designer that will have a substitution label, keep in
mind that translated text may be longer than the original.
If you use mnemonics, remember that the mnemonic character may be different for
other languages.
You can have more than one translated message file in the runtime subdirectories
by assigning different file extensions to each. For example, an English version of
the compiled message file could be named SAMPLE.ENG and a German version
Chapter 5. Common Attributes
39
named SAMPLE.GER. You can instruct the user to copy the appropriate message
file to SAMPLE.MSG before running the application.
40
Data Transferred
Combination box
Entry field
List box
Message subfile
Multiline edit
Static text
41
42
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : EF2
*
*
*
* Event . . : DROP
*
*
*
* Description: This action subroutine will get control when a
*
*
value has been dropped onto the entry field EF2
*
*
By checking the %Data event attribute, it will
*
*
determine if the dropped value is allowed for the
*
*
entry field and add a message to the message
*
*
subfile part accordingly.
*
*
*
*********************************************************************
*
C
EF2
BEGACT
DROP
MAIN
*
* Clear the message subfile
C
Msg1
setatr
0
RemoveMsg
*
* Check that dropped value is allowed
*
C
if
%Data <> Yes and
C
%Data <> No
and
C
%Data <> Maybe
*
C
Msg1
setatr
1
AddMsgID
C
endif
*
C
ENDACT
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : EF2
*
*
*
* Event . . : CHANGE
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
EF2
BEGACT
CHANGE
MAIN
*
C
ENDACT
43
44
45
For more information about part attributes, events, and event attributes, see the
VisualAge RPG Parts Reference. For additional programming tips, see Chapter 3,
Programming with Parts, on page 25.
ActiveX
46
Part Attributes
Activate
HasPrpPage
OCXProp
paramindex
refresh
Top
AddEvent
Height
OCXPropIdx
parentname
ReturnVal
UserData
Bottom
Left
OCXValue
partname
RmvEvent
Visible
Destroy
OCXEvent
DeActivate
Method
Parameter
parttype
ShowProp
Width
Applicable Events
Create
Setting Properties
You can set the properties of an ActiveX control at build or run time. To set
properties during build time, open the ActiveX Part Properties notebook from the
design window. Right-click on the ActiveX icon in the design window and select
Properties. If a properties editor is available for the ActiveX control, it will be
displayed, as well. You can then directly edit the property values.
The properties, methods, and events of the ActiveX control appear on the
Information page of the ActiveX Part Properties notebook. Select the appropriate
radio button to view what is available.
Setting or getting a property during run time requires two steps. First, set the
ActiveX parts OCXProp attribute to the property name of the ActiveX control you
are using. Use the OCXValue attribute to set or get the property.
The following example sets the Depth property for an ActiveX pie chart control:
C
C
PieChart
PieChart
Setatr
Setatr
Depth
DepthValue
OCXProp
OCXValue
Note: The OCXValue attribute takes a string value. The VisualAge RPG run time
will handle the appropriate conversions before forwarding the value to your
ActiveX control.
The OCXPropIdx attribute sets or retrieves the index for an ActiveX string array
property type. You can use this attribute together with the OCXProp and
OCXValue attributes to manipulate string array property types.
For example, the following code sets the first element of the property DataFiles to
c:\temp\Sample.mdb, that is, DataFiles[0]=c:\temp\Sample.mdb.
Chapter 7. Using Parts
47
C
C
C
C
C
EVAL
EVAL
EVAL
%SETATR(WINNEWJOB:ocxname:OCXPROP)=
DataFiles
%SETATR(WINNEWJOB:ocxname:OCXPROPIDX)=0
%SETATR(WINNEWJOB:ocxname:OCXVALUE)
=C:\temp\Sample.mdb
To set an element of a multi-dimensional array property, pass the index value for
each element in a string as n1 n2 n3, where n1 is the index for element 1 and so
on. For example, the following code sets 3DImageData[2][4][7] to 200:
C
C
C
C
C
C
EVAL
EVAL
EVAL
%SETATR(WINNEWJOB:ocxname:OCXPROP)=
3DImageData
%SETATR(WINNEWJOB:ocxname:OCXPROPIDX)
= 2 4 7
%SETATR(WINNEWJOB:ocxname:OCXVALUE)
= 200
Each time the OCXProp attribute is set, the internal index value for an array at run
time is reset to NULL. So, to set or get the array properties, first set OCXProp to
the property name. Then, set OCXPropIdx to the index value in the array. Lastly,
set or get the OCXValue attribute.
The ActiveX part properties notebook shows the property types in the Information
tab. If the type of a property is a string array, the Information tab displays
String[][]...[], where the number of [] pairs indicates the dimension of the
array. For a numeric array, Numeric[][]...[] is displayed. For a non-array
property, either Numeric or String is displayed. In the following example, the
properties are all string arrays:
Calling Methods
The VisualAge RPG IDE attempts to compile a listing of available methods for
your ActiveX control. This list is available on the Information page of the ActiveX
Part Properties notebook. For each method, the parameters are shown with brace
brackets containing IN for an input parameter, OUT for an output parameter, or
nothing if no information is available.
Note: It may not be possible for the builder to discover all available methods for
your ActiveX control. Consult the controls documentation for a complete
listing.
48
The following example calls the AboutBox method of an ActiveX pie chart control.
The method takes no parameters.
C
PieChart
Setatr
AboutBox
Method
The next example calls the AddData method of an ActiveX pie chart control. This
method takes two parameters: a string label and a float value.
D datax
C
PieChart
datax
Method
49
Responding to Events
VisualAge RPG can respond to any events generated by the ActiveX control you
are using. ActiveX control events are accepted by VisualAge RPG as an OCXEvent.
You can use the %RealName event to retrieve the actual name of the event.
To receive an event from an ActiveX control, you must first register the event with
the VisualAge RPG run time. Set the ActiveX parts AddEvent attribute to the
string name of the event to be received. You can also set the AddEvent attribute to
*ALL to receive all events generated by the ActiveX control. To unregister an event,
set the RmvEvent attribute to the string name of the event.
* Declare the event attribute
D %RealName
s
20a
C
OCXEVENT
FRA000000B
%RealName = Click
When an ActiveX part fires an event, the event may contain some parameters.
Prior to WDSC V5.1, these parameters were ignored. They were not available to
the application. Now, with the introduction of these two attributes in V5.1, the
event parameters are available to the application.
To access a parameter, these are the steps:
1.When an OCXEVENT fires, in its event action-subroutine, the parameter index
should be set first:
C
ocx
setatr
PARAMINDEX
ocx
getatr
Parameter
param
The above info shows that the event has 2 parameters. The first one, number, is a
pointer to a Variant structure which contains a bstrVal member, and this bstrVal
may contain a value from one to six, the number of dots on a dice. The value
of vstrVal can be retrieved and be changed to a different number in the action
subroutine. The second one, useNumber, is a pointer to a Boolean value. If this
value is set to be true, the Dice control will roll to the number set here (e.g.,
suppose number=Four; if it is set to five, the dice will display 5 dots. If there is
no change, the dice will display 4 dots).
Please note that in order to pass a parameter back to the control, the control must
define the parameter as a pointer (to desired types), and allow the pointer to be
50
passed back (some pointer parameters are for read only, applications can not
change their value. This is controled by the ActiveX control developer.).
How to access and change the BOOL parameter of the event:
d BoolVal
s
1b 0 based(pBool)
d Bool
DS
d pBool
1
4*
d PB_Value
1
4b 0
d*param is used to receive the pointer parameter. Then
d*move it into PB_Value to get the numeric value.
d param
s
8A
Pointer
pointer, char
To access and change the first parameter of the event, it is helpful to look at the
VARIANT structure first:
struct VARIANT {
VARTYPE vt; //Indicate data
unsigned short wReserved1;
unsigned short wReserved2;
unsigned short wReserved3;
union {
unsigned char bVal;
short
iVal;
long
lVal;
float
fltVal;
double
dblVal;
VARIANT_BOOL xbool;
DATE
date;
BSTR
bstrVal;
short
FAR* piVal;
long
FAR* plVal;
... ...
}
//
//
//
//
//
//
//
//
VT_UI1
VT_I2
VT_I4
VT_R4
// VT_R8
// VT_BOOL
VT_DATE
VT_BSTR
VT_BYREF|VT_I2
VT_BYREF|VT_I4
pointer, char
Pointer
8=VT_BSTR
51
d typeStrParam
1
2b 0
d reserved1Param
3
4b 0
d reserved2Param
6b 0
d reserved3Param
7
8b 0
d bstrValParam
*
d B0
9
12B 0
d padding2Param
13
16b 0
d
d*Change the bstrValParam member of the structure.
d NewBSTRVal
s
20A
based(bstrValParam)
d
C
OCX2
BEGACT
OCXEVENT
MAIN
C
IF
%REALNAME=BeforeRollToVariant
C*Get the pointer (char string), and transform it into a pointer.
C*The first parameter is a pointer to a VARIANT structure.
C
ocx2
setatr
1
PARAMINDEX
C*Please note that the length of the returned "PARAMETER" string
C*varies. E.g., the length of the first parameter here is 8, while
C*the second one is 7. So, a long-enough variable need to be
C*defined to receive the string, and its need to be processed so
C*that theres no SPACE characters in it before it is converted
C*to a numeric value.
C
ocx2
getatr
Parameter
param
C
EVAL
PTR_Value = 0
C
MOVE
PARAM
PTR_Value
C*Change the value of bstrValParam member of the structure.
C
eval
strFour=four+x00
C
eval
NewBSTRVal=strFour
This way, the contents of the structure pointed to by the first parameter can be
changed. The above code will make the Dice display 4 dots.
52
String
Animation Control
In Windows applications, the animation control part plays video files with the AVI
extension. This part differs from the media part in that the video is actually played
independently of the program logic. One typical use of this part is to display an
AVI file that shows some progress, such as a file being moved from one folder to
another.
The animation control part plays video files with no sound. The AVI file cannot be
in compressed format, unless it was compressed with the Running-Length Encoded
(RLE) method.
In Java applications, the animation control part is used to play back an animated
GIF file sequence using the NbrOfImage attribute.
Part Attributes
FileName
Mode
PartType
FrameRate
NbrOfImage
Top
Handle*
ParentName
UserData
Left
PartName
Visible
Destroy
53
Calendar
The calendar part represents a monthly calendar. By clicking on one of the month
arrows, the user can navigate the calendar by going to the next or previous month.
You also have complete program control over the calendar such as going to a
specific date, determining which date the user has selected, and adding short text
comments to individual days in the calendar.
Part Attributes
Border
ClearMonth
ColorMix
DateUnder
DayNumPos
FontArea
FontSize
Handle*
Month
OutlineRcl
Refresh
Top
WeekDay
YearIdx
Bottom
ClearYear
Date
Day
DayNumRect
FontBold
FontStrike*
Height
MonthArrow
ParentName
ShowRects
UserData
WeekDayIdx
YearLen
ClearAll
Color
DateIdx
DayIdx
DayStart
FontItalic
FontUnder*
HRule
MonthIdx
PartName
ShowText
Visible
Width
ClearDate
ColorArea
DateText
DayLen
Enabled
FontName
FrmtString
Left
MonthLen
PartType
TipText
VRule
Year
Create
MouseEnter
MthChange
Destroy
MouseExit
YearChange
DblClick
MouseMove
54
C
*
Cal1
Getatr
DateUnder
YYYYMMDDA
8 0
*
* Set index to date to reference
C
Cal1
Setatr
19971210
*
* Set comment for the day
C
Cal1
Setatr
Vacation
*
DateIdx
DateText
55
Canvas
Use the canvas part with a window or a notebook page if you want to place more
than one part on your window or notebook page. You can point and click various
parts onto the canvas, position them, and organize them to produce a graphical
user interface.
The canvas part occupies the client area of either a window or a notebook page. If
there is no canvas in your window or notebook page, then you can put only one
part on the client area, unless the parts are extensions to the window, such as
menu bars and message subfiles.
More often than not, you will be creating windows and notebook pages with more
than one part on them. In that case, you should use the notebook page with canvas
part and the window with canvas part. They save you a step because they already
contain the canvas part.
At build time, you can also include a bitmap image as the canvas background by
specifying the FileName attribute. This image can be tiled by setting the Tile
attribute. For Java applications, you can include GIF or JPG images as the
background.
Notes:
1. The canvas part, the window (without canvas) part, and the notebook page
(without canvas) part are located on the parts catalog, not the parts palette. If
you want to use them frequently, you can add them to the parts palette.
2. If parts located on a canvas part have the default font setting specified (Default
System Font), they will inherit the font definition specified for the canvas part.
To apply a certain font to the majority of parts on a canvas, specify that font for
the canvas part rather than for each individual part.
For related information, see:
v Window on page 180
v Window with Canvas on page 181
v Notebook Page on page 118
v Notebook Page with Canvas on page 119.
56
Part Attributes
BackColor
FileName
FontSize
Height
PartType
Top*
BackMix
FontBold
FontStrike*
Left
ReadOnly
UserData
Bottom*
FontItalic
FontUnder*
ParentName
Refresh
Width
Enabled
FontName
Handle*
PartName
Tile
Create
MouseMove
DblClick
MouseUp
Destroy
Popup
57
Check Box
Use the check box part if you want the user to choose between two clearly
distinguishable states; for example, on and off.
A label associated with the check box describes what its setting is when it is
selected.
Typically, you use a group of check boxes to provide a list of options. The user can
select one or more check boxes, or not select any. The options are not mutually
exclusive; therefore, selecting one check box has no effect on others on the window.
If you want the user to be able to select only one option from two or more, use
radio buttons instead. See Radio Button on page 142 for more information.
To set the state of a check box, the user can either click on it with the mouse, press
the space bar on the keyboard when the check box is in focus, or (if you have
assigned one) press the mnemonic key.
Part Attributes
AddLink*
Bottom
FontBold
FontStrike*
Handle*
Left
Refresh
Top
AllowLink*
Checked
FontItalic
FontUnder*
Height
ParentName
RemoveLink*
UserData
BackColor
Enabled
FontName
ForeColor
Highlight*
PartName
ShowTips
Visible
BackMix
Focus
FontSize
ForeMix
Label
PartType
TipText
Width
58
Destroy
Popup
MouseEnter
Select
MouseExit
The check box is not set and the state is turned off.
The check box contains a check mark when its state is on.
Setting a Mnemonic
Note: Mnemonics are not supported in Java applications.
To specify a mnemonic key for the check box, place the mnemonic identifier in
front of a character in the check box label. For Windows, use an ampersand (&).
This character is the mnemonic key and will be displayed on your interface with
an underscore (for example, Visible). The underscore informs users that they can
select the check box by pressing the underlined character on the keyboard.
Signaling Events
When the user selects a check box to turn the state either on or off, a Select event
is signaled.
59
Combination Box
A combination box provides the user with the option of entering specific
information, or selecting from a list of commonly used choices.
It consists of an entry field with an attached list box that presents a list of values
which the user can scroll through. If the user selects one of these values, it will
appear in the entry field and replace any existing text. Alternatively, the user can
type a value, that does not have to match any of the listed ones, directly into the
entry field.
Combination boxes come in different styles. You can select the style you want from
the parts properties notebook
For related information, see:
v List Box on page 92
v Entry Field on page 75
Part Attributes
AddItemEnd
Bottom
DeSelect*
FieldExit
FontItalic
FontUnder*
Handle*
ItemKey
PartType
Search*
Sequence*
SizeToFit*
UseDelim
AutoScroll*
Case*
DragEnable*
FirstSel
FontName
ForeColor
Height
Left
ReadOnly
SearchType*
SetItem
Text
UserData
BackColor
Count
DropEnable*
Focus
FontSize
ForeMix
Index
ParentName
Refresh
Selected
SetTop*
TipText
Visible
60
BackMix
DelimChar
Enabled
FontBold
FontStrike*
GetItem
InsertItem*
PartName
RemoveItem
SelectItem
Showtips
Top
Width
Applicable Events
Change
DropDown*
LostFocus
Popup
Create
Enter
MouseEnter
Select
Destroy
GotFocus
MouseExit
VKeyPress
Drop*
KeyPress
MouseMove
61
you had set the Sequence attribute to ascending order before the
combination box was filled, the items appear in the combination box in
ascending sequence; however, if you then retrieve an item, change its value,
and use the SetItem attribute to replace it in the combination box, the item
is inserted in the same position it was in before. Therefore, the list may or
may not be in ascending sequence after the change.
Removing Items
Use the RemoveItem attribute and the Index value of the item you want to
remove. Index values start at 1. When an item is removed from the list, all items
following the removed item are moved up one position in the list.
To remove all items in the list, specify an Index value of 0.
62
The user may also type a value into the entry field portion of the combination box.
This value does not have to be one of those in the list. If you want the user to be
able to select only items that are in the list, set the ReadOnly attribute value to 0.
You can use the Count attribute to determine if there are items to retrieve.
Using Keys
Both the list box and the combination box allow you to add items to the list that
consist of a key portion and a data portion. When items are added to the list,
only the data portion of the item is displayed. When the user selects an item you
can programatically retrieve the key portion of the item.
To enable keys in a list, you must check the Use separator check box on the
Separator page of the parts settings notebook and specify a separator character.
The default separator character is the semicolon (;). The items in the list consist of
the key portion, followed by the separator, followed by the data portion. For
example:
01;Shipping
Combo1
Combo1
Combo1
Getatr
Setatr
Getatr
FirstSel
X
ItemKey
X
Index
Key
2 0
63
Signaling Events
The Select event is signaled when:
v The user selects an item that is in a combination box.
v You select an item in the list in your program.
v The user selects an item that is already selected.
The Enter event is signaled when:
v The user double-clicks on an item that is in the combination box
v The Enter key is pressed when the list box has focus and an item has been
selected.
In your action subroutine for these events, you can use the Selected attribute to
determine which item was selected.
64
Component Reference
AttrValue
NotSrcEvt
PartName
RefPart
Bottom
NotSrcPart
PartType
RmvSrcEvt
Destroy
Notify
CompName
NotSrcWin
RefAttr
UserData
Applicable Events
Create
CompName
RefParent
RefPart
RefAttr
AttrValue
65
66
Container
Use the container part to store related records. The records can be shown in an
icon view, tree view, text tree view, or details view.
Part Attributes
AddRcd
BlankChar
Collapsed
DeSelect
FirstSel
FontName
ForeColor
GetRcdIcon
InUse*
ParentId
PartType
RemoveRcd
SetRcdIcon
SortAsc
UserData
VisTitlSep
Arrange
Bottom
ColNumber
EditItem
Focus
FontSize
ForeMix
GetRcdText
Label
ParentList
ReadOnly
Selected
SetRcdText
SortDesc
View*
Width
BackColor
ChildCount
Count
Enabled
FontBold
FontStrike*
GetNewID
Handle*
Left
ParentName
RecordID
SelectRcd
SetTop*
TipText
Visible
BackMix
ChildList
DeleteRcd
ExtSelect*
FontItalic
FontUnder*
GetRcdFld
Height
MiniIcon
PartName
Refresh
SetRcdFld
ShowTips
Top
VisTitle
Collapsed
Destroy
KeyPress
MouseExit
Select
ColSelect
Enter
LostFocus
MouseMove
VKeyPress
Create
Expanded
MouseDown
MouseUp
67
Object icon
An object icon column displays the icon file that is specified when the
record is created. You can change the icon file name at run time using the
SetRcdIcon attribute.
Text
Icon
A unique numeric value you give to a record. This number must be greater
than zero. To ensure that you assign a unique ID to each record you create,
use the GetNewID attribute.
Text
The text that is displayed with the object icon. The text can be changed at
run time by using the SetRcdText attribute.
FileName
The name of a file containing the icon image for an object icon column.
This icon is displayed in the containers Icon and Tree views. You can
change the icon file name at run time using the SetRcdIcon attribute.
ParentID
The unique ID of the record under which this record will appear. If this
record does not have a parent record, put a 0 in this field.
Field_data
Additional information for a record that is displayed in a text or icon
column. Each field_data value updates a corresponding column in the
container part. If you want to have an empty text column or icon container
column, you must specify an underscore ( _ ) in the corresponding
field_data parameter.
The following code fragment shows the parameters that are specified to add a
sample record to a container. No column data is added in this example.
68
*
* This is not a child record
C
Eval
Parent = 0
*
* Use the icon text specified in the GUI designer
C
Eval
IconText = _
*
* Set the icon file name to be used for this record
C
Eval
IconFile = .\\TOM.ICO
*
* Get a new container record ID and make it character
C
CT1
Getatr
GetNewId
NextIDN
C
Move
NextIDN
NextID
*
* Create the container record structure
C
Eval
NextRcd = NextID + +
C
IconText + +
C
IconFile + +
C
Parent
*
* Add the record to the container
C
CT1
Setatr
NextRcd
AddRcd
*
6 0
6
Use the Count attribute to determine how many records are in a container.
If you want the new column value to contain imbedded blanks, use the underscore
character to represent each blank. The underscore characters are replaced by blanks
when the column is updated. For example:
*
* New data is set in the column
C
CT1
Setatr
New_data
*
SetRcdFld
69
Use the GetRcdFld attribute to retrieve the contents of a record field. Set the
RecordID attribute to the unique ID of the record, and the ColNumber attribute to
the desired column number.
selected record
Getatr
FirstSel
TmpID
6 0
Icon view
An icon view has each record represented by an icon, with text beneath it. Child
records are not displayed in icon view. You specify the icon file name and the
descriptive text in the record structure when you add the record to the container.
You can change the icon and icon text at run time by using the SetRcdIcon and
SetRcdText attributes.
To have the icons displayed in rows in the container, set the Arrange attribute to 1.
To use mini icons, set the MiniIcon attribute to 1 or check the Mini Icon box on
the properties notebooks Style page.
70
Tree view
In a tree view, records are presented in a hierarchy. The tree icon view displays
each record with its icon and icon text beside it. If a record has child records, a
plus sign is displayed next to its icon. Selecting the plus sign shows all the records
related to this record. The tree text view displays records in the same way as the
tree icon view, except in text-only mode, without icons.
Connecting lines are drawn between related records to show their relationship.
71
Details View
In a details view, records are shown one after the other with each column
displayed (similar to a subfile). Child records are not displayed in this type of
view.
72
If the container is not large enough to display all records at once, scroll bars are
automatically added.
To change the view, use the View attribute.
Mini Icons
This option allows the programmer to specify whether the icons contained in the
container part will be shown as regular icons, or as mini icons. This will only affect
the icon view, and will leave the tree and details views unchanged.
73
DDE Client
Bottom
Execute
ParentName
Request
UserData
DDEAddLink
Format
PartName
TimeOut
Visible
DDEMode
Item
PartType
Top
Data
Terminate
Destroy
TimeOut
ExecuteAck
Applicable Events
Create
PokeAck
74
Entry Field
Use the entry field part if you want the user to input something that you cannot
predict the value of. An entry field is an area into which the user can type or place
text. Its boundaries are usually indicated. The user can scroll through the text in
the entry field if more information is available than is currently visible.
You can configure the entry field part to accept character, numeric, or double-byte
character set (DBCS) data.
You can also make the entry field read-only, so that it contains information that
cannot be directly altered by the user.
You can point and click on an entry field part in the parts palette and then click it
onto the subfile part to create a subfile entry field.
Part Attributes
AddLink*
AutoSelect
CapsLock
DataType
Enabled
FontItalic
FontUnder*
Height
ParentName
ReadOnly
Text
TextStart
Visible
Alignment
BackColor
Copy
Delete
FieldExit
FontName
ForeColor
InsertMode*
PartName
Refresh
TextEnd
TipText
Width
AllowLink*
BackMix
CsrAtEnd
DragEnable*
Focus
FontSize
ForeMix
Left
PartType
RemoveLink*
TextLength
Top
AutoScroll*
Bottom
Cut
DropEnable*
FontBold
FontStrike*
Handle*
Masked
Paste
ShowTips
TextSelect
UserData
75
Applicable Events
Change
Destroy
Link*
MouseExit
VKeyPress
Click
Drop
LostFocus
MouseMove
Create
GotFocus
MouseDown
MouseUp
DblClick
KeyPress
MouseEnter
Popup
Validity Checking
You can use the properties notebook to specify that an entry field should accept
only data that meets criteria you specify. To ensure that the data matches certain
values, set the Compare values. To ensure that the data falls within a range of
predefined values, set the Range values.
Note: VisualAge RPG uses the ASCII collating sequence for validity checking. This
differs from the server, which uses the EBCDIC collating sequence.
Therefore, results may vary between systems.
To have validity checking performed, you must have at least one push button or
graphic push button on the window that has the Validate attribute set. When the
push button is pressed, validity checking is performed for each entry field that has
validity checking criteria defined. If any of the entry fields fail this validity check,
a message window is displayed and no press event is signaled to your program.
You can also use the field at the top of the properties notebook to set the message
that is displayed if the validity check fails. Either enter the text of the message to
be diplayed or the named message file (such as *MSG0001) to have the
corresponding message appear. If this field is left blank, the default system
message is displayed whenever there is a validity check failure.
Note: There is a 15 character limit on this field.
76
77
Graph
The graph part allows you to create and design a graph in your project. At
runtime, you can send data to the graph and change graph attributes and the
graph type. The graph part supports Pie, Line, Bar, and Line and Bar graph types.
The Bar and Line graph types support the ToolTip text control. When enabled,
moving the mouse over a data point displays the tooltip text control. To use this
support in your program logic, set the value for the point into the TipText attribute
and set the ShowTips attribute on for the window that contains the graph part.
Part Attributes
AutoInc
ColorArea
DataValue
FontBold
FontStrike*
GraphType
Height
Left
PartType
Title
UseData
XAxisLabel
BarLabel
ColorMix
Enabled
FontItalic
FontUnder*
GroupLabel
HitItem*
LegendType
Refresh
TitlePlace
UserData
YAxisLabel
Bottom
DataGroup
FillStyle*
FontName
GnEqGrpCol
GrphHiLite
HlitPoints*
ParentName
StartNew
Top
Visible
YInc
Color
DataPoint
FontArea
FontSize
GnEqPntCol
Handle*
LabelPlace
PartName
TipText
UnderPoint*
Width
Create
MouseEnter
Popup
DblClick
MouseExit
Destroy
MouseMove
78
Sending data to the graph does not update the graph. You must set the UseData
attribute to display the data.
The following code fragment shows how this may be done:
*
C
C
Do
Setatr
2
Group
Group
DataGroup
2 0
Graph1
Do
Setatr
12
Point
Point
DataPoint
2 0
Graph1
Graph1
If
Setatr
Group = 1
Low(Point)
DataValue
Else
Setatr
Endif
High(Point)
DataValue
UseData
*
C
C
*
C
C
*
C
C
C
Graph1
*
EndDo
*
EndDo
*
Graph1
Setatr
79
Use graphic push buttons to provide convenient access to frequently used actions.
A graphic push button provides the same function as a push button. It indicates an
action that will be initiated when the user selects it, but instead of displaying a
label to describe its function, it displays an image. The FileName attribute specifies
the name of the image to use.
Valid Windows image formats include:
v Windows and OS/2 Bitmaps (BMP, VGA, BGA, RLE, DIB, RL4, RL8)
v Icon (ICO )
v Microsoft/Aldus Tagged Image File Format (TIF, TIFF)
v CompuServe Graphics Interchange Format (GIF)
v ZSoft PC Paintbrush Image File Format (PCX)
v Truevision Targa/Vista Bitmap (TGA, VST, AFI)
v Amiga Interleaved Bitmap Format (IFF, ILBM)
v X Windows Bitmap (XBM)
v IBM Printer Page Segment (PSE, PSEG, PSEG38PP, PSEG3820)
v Joint Photographic Experts Group format (JPG, JPEG)
Note: This products support for the JPG/JPEG format is based in part on the
work of the Independent JPEG Group.
Valid Java image formats include:
v CompuServe Graphics Interchange Format (GIF)
v Joint Photographic Experts Group format (JPG, JPEG)
For related information, see Push Button on page 140.
80
Part Attributes
Bottom
Handle*
Left
Refresh
UserData
Enabled
Height
ParentName
ShowTips
Validate
FileName
HelpEnable
PartName
TipText
Visible
Focus
HighLight
PartType
Top
Width
Destroy
MouseExit
GotFocus
MouseMove
LostFocus
Popup
Signaling Events
When the push button is pressed, a Press event is signaled to your program.
81
Group Box
Enabled
FontSize
ForeMix
Left
Refresh
Width
FontBold
FontStrike*
Handle*
ParentName
Top
FontItalic
FontUnder*
Height
PartName
UserData
Destroy
82
Use the horizontal scroll bar part to allow users to scroll through a pane of
information from left-to-right, or right-to-left. The information can be a list of files,
records in a database, columns in a document, and so on. You can use the Range
attribute to represent the total number of objects to be scrolled through and the
PageSize attribute to determine the number of objects that can be displayed on a
page.
Part Attributes
Bottom
Height
PageSize
Position
Top
Enabled
Left
ParentName
PrevLine
UserData
Focus
NextLine
PartName
PrevPage
Visible
Handle*
NextPage
PartType
Range
Width
Destroy
Scroll
83
Image
Use the image part to display a picture. The FileName attribute specifies the name
of the image to use.
Valid Windows image formats include:
v Windows and OS/2 Bitmaps (BMP, VGA, BGA, RLE, DIB, RL4, RL8)
v Icon (ICO )
v Microsoft/Aldus Tagged Image File Format (TIF, TIFF)
v CompuServe Graphics Interchange Format (GIF)
v ZSoft PC Paintbrush Image File Format (PCX)
v Truevision Targa/Vista Bitmap (TGA, VST, AFI)
v Amiga Interleaved Bitmap Format (IFF, ILBM)
v X Windows Bitmap (XBM)
v IBM Printer Page Segment (PSE, PSEG, PSEG38PP, PSEG3820)
v Joint Photographic Experts Group format (JPG, JPEG)
Note: This products support for the JPG/JPEG format is based in part on the
work of the Independent JPEG Group.
Valid Java image formats include:
v CompuServe Graphics Interchange Format (GIF)
v Joint Photographic Experts Group format (JPG, JPEG)
These files reside on the programmable workstation (PWS), not on the host. You
should store system-specific bitmap and icon files in the appropriate runtime
directory (RT_JAVA, or RT_WIN32) so that the packaging utility includes them
when you package your application.
Note: The image part can only be dropped on a notebook page with canvas or
window with canvas.
84
Part Attributes
AddLink*
Border
Handle*
Panel
Print
ShowTips
Visible
AllowLink*
Bottom
Height
ParentName
PrintAsIs
TipText
Width
BackColor
Enabled
Left
PartName
Refresh
Top
BackMix
FileName
Magnify
PartType
RemoveLink*
UserData
Create
MouseEnter
DblClick
MouseExit
Destroy
MouseMove
Image Example
In this example, a file is read from the iSeries 400 server. Each record in the file
contains a part number field, which is inserted into the list box as each record is
Chapter 7. Using Parts
85
read. When the user selects a part number in the list box and presses the View
push button, the part number is concatenated with the string .BMP to form a file
name. That file name is then used to set the FileName attribute of the image part
to display the picture. The Label attribute of the PINFO static text part is updated
to indicate the result of setting the file name attribute. Press the Close push button
to terminate the program.
*********************************************************************
*
*
* Program ID . . : IMAGE
*
*
*
* Description . : Example of the Image Part
*
*
*
*
This sample program illustrates how the image
*
*
part can be implemented in VARPG Client.
*
*
*
*
The example assumes there is file on the host
*
*
AS/400 system called PARTS. That file format
*
*
consists of a field called PARTNO.
*
*
*
*
When the application is started, the Create
*
*
event for window WIN1 is invoked which reads all *
*
records from the file and inserts the PARTNO
*
*
field value into list box LB1.
*
*
*
*
When the user presses the View push button,
*
*
the image file name is constructed and used to
*
*
set the FILENAME attribute of the image part
*
*
IMG1.
*
*
*
*********************************************************************
*
H
* Define the PARTS file
*
FPARTS
IF
E
*
DPath
C
dnopic
C
*
DISK
REMOTE
86
*********************************************************************
*
*
* Window . . : WIN1
*
*
*
* Part . . . : Close
*
*
*
* Event . . : Press
*
*
*
* Description: Terminate the program
*
*
*
*********************************************************************
*
C
CLOSE
BEGACT
PRESS
WIN1
*
C
move
*on
*inlr
*
C
ENDACT
*********************************************************************
*
*
* Window . . : WIN1
*
*
*
* Part . . . : WIN1
*
*
*
* Event . . : Create
*
*
*
* Description: This action subroutine is executed when window WIN1 *
*
is created.
*
*
It will fill the list box with the part number values*
*
from the PARTS file.
*
*
*
*********************************************************************
*
C
WIN1
BEGACT
CREATE
WIN1
*
* Fill the listbox part with items from the database
C
read
produc1
9999
*
C
*in99
doweq
*off
C
LB1
setatr
partno
InsertItem
C
read
produc1
9999
C
enddo
*
C
ENDACT
*
87
*********************************************************************
*
*
* Window . . : WIN1
*
*
*
* Part . . . : VIEW
*
*
*
* Event . . : PRESS
*
*
*
* Description: Display the image for the selected part
*
*
*
*********************************************************************
*
C
VIEW
BEGACT
PRESS
WIN1
*
* Get index of selected item
C
LB1
getatr
FirstSel
x
4 0
*
* If an item was selected, build the bitmap file name
C
x
ifgt
*zero
C
LB1
setatr
x
Index
C
LB1
getatr
GETITEM
tmp20
20
C
movel
tmp20
part
5
C
endif
*
C
move
*blanks
fullpath
64
C
move
*blanks
tmp64
64
C
path
cat
part:0
tmp64
C
tmp64
cat
.gif:0
fullpath
*
* Set the file name in the image FILENAME attribute
* to display the image
C
IMG1
setatr
fullpath
FILENAME
80
*
* If indicator 80 is on, the set the image file name
* failed. i.e. the file was not found.
* Set the Label attribute for the static text part PINFO to
* indicate status
C
*in80
ifeq
*on
C
PINFO
setatr
nopic
Label
*
C
else
C
PINFO
setatr
*BLANKS
Label
C
endif
*
C
ENDACT
*
88
Java Bean
After installing the J2SDK, set the PATH environment variable to point to the
location of the Java compiler. For example, if your home directory for the J2SDK is
x:\jdk1.2, add the following path statement:
x:\jdk1.2\bin
Also, set the JVM_DIR environment variable to point to the location of the jvm.dll,
which is part of the J2SDK and JRE (Java Runtime Environment). For example, if
your home directory for the J2SDK is x:\jdk1.2, set JVM_DIR to the following
statements:
x:\jdk1.2\jre\bin\classic
Part Attributes
AddEvent
Left
RmvEvent
Visible
Bottom
ParentName
ShowProp
Width
Enabled
PartName
Top
Destroy
BeanEvent
Height
PartType
UserData
Applicable Events
Create
89
the design window and select Properties. The properties, methods, and events of a
bean are on the Information page. Select the appropriate radio button to view what
is available.
Not all bean events are supported. VARPG-supported events are prefixed with an
asterisk(*) in the Events list.
90
91
List Box
Use the list box part to provide the user with a list of items from which one or
more items can be selected. A list box consists of read-only items. An item in a list
box is a string of characters.
Horizontal and vertical scroll bars allow the user to view sections of the list that
are not currently displayed. You can configure the list box so that the user can
select either just one item or multiple items. You can use the Search, SearchType,
and Case attributes to easily search for a particular item in the list.
Part Attributes
AddItemEnd
BackMix
DelimChar
Enabled
FontBold
FontStrike*
GetItem
InsertItem*
NbrOfSel
Refresh
SearchType*
Sequence*
SizeToFit
UseDelim
AddLink*
Bottom
DeSelect
ExtSelect*
FontItalic
FontUnder*
Handle*
ItemKey
ParentName
RemoveItem
Selected
SetItem
TipText
UserData
AllowLink*
Case*
DragEnable*
FirstSel
FontName
ForeColor
Height
Left
PartName
RemoveLink*
SelectItem
SetTop
Top
Visible
BackColor
Count
DropEnable*
Focus
FontSize
ForeMix
Index
MultSelect
PartType
Search*
SelectList
ShowTips
TopItem
Width
Destroy
KeyPress
MouseMove
Drop*
LostFocus
Popup
Enter*
MouseEnter
Select
92
Removing Items
Use the RemoveItem attribute to remove items from the list. Use the index value
to specify the item that is to be removed. Index values start at 1. When an item is
removed from the list, all items following the removed item are moved up one
position in the list.
To remove all items in the list, specify an index value of 0.
Types of Selection
You can use attributes to specify how items are selected in a list box. Single,
multiple, and extended selection are available.
Single selection
Single selection (the default) permits only one item in a list to be selected
at one time. If an item is currently selected, it will be deselected when
another item is selected.
Multiple selection
The user can select any number of objects, or not select any.
Extended selection
This type of selection is optimized for the selection of a single object, but
the user can extend selection to more than one object, if required.
93
Using Keys
Both the list box and the combination box allow you to add items to the list that
consist of a key portion and a data portion. When items are added to the list,
only the data portion of the item is displayed. When the user selects an item you
can programatically retrieve the key portion of the item.
See the Using Keys section in the combination box part description for more
information.
Signaling Events
The Select event is signaled when:
v The user selects an item that is in a list box.
v You select an item in the list in your program.
v The user selects an item that is already selected.
The Enter event is signaled when:
v The user double-clicks over an item that is in the list box
v The user presses the Enter key when the list box has focus and an item has been
selected.
In your action subroutine for these events, you can use the Selected or FirstSel
attribute to determine which item was selected.
94
95
*********************************************************************
*
*
* Program ID . . : LISTBOX
*
*
*
* Description . : Sample program to demonstrate the Listbox part. *
*
*
*********************************************************************
*
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : CLEAR
*
*
*
* Event . . : PRESS
*
*
*
* Description: Clear the listbox and the entry field. Give focus
*
*
to the entry field part.
*
*
*
*********************************************************************
*
C
CLEAR
BEGACT
PRESS
MAIN
*
C
LB1
setatr
0
RemoveItem
C
EF1
setatr
*blanks
Text
C
EF1
setatr
1
Focus
*
C
ENDACT
*********************************************************************
*
*
* Window . . : FRA0000B
*
*
*
* Part . . . : CLOSE
*
*
*
* Event . . : PRESS
*
*
*
* Description: Terminate the program
*
*
*
*********************************************************************
*
C
CLOSE
BEGACT
PRESS
MAIN
*
C
move
*on
*INLR
*
C
ENDACT
Figure 20. Coding Example Using the List Box Part (Part 1 of 3)
96
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : REMOVE
*
*
*
* Event . . : PRESS
*
*
*
* Description: Remove the selected item from the list box.
*
*
The FirstSel attribute is used to determine the
*
*
index of the first selected item.
*
*
*
*********************************************************************
*
C
REMOVE
BEGACT
PRESS
MAIN
*
C
LB1
getatr
FirstSel
Index
3 0
*
C
Index
ifgt
*zero
C
LB1
setatr
Index
RemoveItem
C
endif
*
C
ENDACT
*********************************************************************
*
*
* Window . . : FRA0000B
*
*
*
* Part . . . : ADD
*
*
*
* Event . . : PRESS
*
*
*
* Description: Adds the value in the entry field part as a new item *
*
to the list box part.
*
*
*
*********************************************************************
*
C
ADD
BEGACT
PRESS
MAIN
*
C
EF1
getatr
TEXT
tmp
30
*
C
tmp
ifne
*blanks
C
LB1
setatr
tmp
InsertItem
C
EF1
setatr
*blanks
Text
C
EF1
setatr
1
Focus
C
endif
*
C
ENDACT
Figure 20. Coding Example Using the List Box Part (Part 2 of 3)
97
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : SELECT
*
*
*
* Event . . : PRESS
*
*
*
* Description: Retrieves the selected item from the list box and
*
*
copies it to the entry field.
*
*
*
*********************************************************************
*
C
SELECT
BEGACT
PRESS
MAIN
*
C
LB1
getatr
FirstSel
x
3 0
*
C
x
ifgt
*zero
C
LB1
setatr
x
Index
C
LB1
getatr
GetItem
temp
20
C
EF1
setatr
temp
Text
C
endif
*
C
ENDACT
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : EF1
*
*
*
* Event . . : CHANGE
*
*
*
* Description: For CRP samples notify event purpose
*
*
*
*********************************************************************
*
C
EF1
BEGACT
CHANGE
MAIN
*
C
ENDACT
*
Figure 20. Coding Example Using the List Box Part (Part 3 of 3)
Search Example
You can use the Search, SearchType, and Case attributes to search for a particular
item in the list. Using them is faster than reading each item in your program and
comparing for specific values.
The following example shows how to locate a customer name in a list box as the
user types a name in the entry field. The window is named MAIN, the list box is
LB1, and the entry field is EF1. The user interface follows:
98
In the windows Create event, we set the Case attribute of the list box to 0 to
indicate that the search is not case sensitive. The SearchType attribute is set to 1
indicating we only want to compare the number of characters in the search string
with the first characters of the list item. The rest of the code is filling the list box
with records from the iSeries database.
C
MAIN
BEGACT
CREATE
MAIN
LB1
LB1
Setatr
Setatr
0
1
Case
SearchType
Read
Custom01
DoW
Setatr
Read
EndDo
NOT *in99
CustNa
Custom01
AddItemEnd
Setatr
SelectItem
*
C
C
*
C
99
*
C
C
C
C
LB1
99
*
C
LB1
*
ENDACT
The following code is the action subroutine for the Change event of the entry field
EF1. Each time a character is typed in the entry field, this action subroutine is
invoked.
The value of the Text attribute of the entry field is retrieved, and if it is not blank,
that value is used as the search string for the Search attribute of the list box. If a
match is found (Index attribute is greater than 0), the found item is selected and
then moved to the top of the list box with the Settop attribute.
C
EF1
BEGACT
CHANGE
MAIN
EF1
Getatr
Text
Search
LB1
If
Setatr
If
%Getatr(Main:LB1:Index)<>0
*
C
40
*
C
C
*
C
99
C
C
C
C
C
Eval
Eval
%Setatr(Main:LB1:SelectItem)=
%Getatr(Main:LB1:Index)
%Setatr(Main:LB1:SetTop)=
%Getatr(Main:LB1:Index)
EndIf
*
C
C
C
C
LB1
LB1
LB1
Else
Setatr
Setatr
Setatr
1
1
1
SetTop
SelectItem
Index
*
C
EndIf
*
ENDACT
If the entry field is blank, the first item in the list box is moved to the top, and is
selected. The INDEX attribute is set to 1 so that subsequent searches begin at the
top of the list.
100
Media
Use the media part to play or record audio information or to play video files.
The media part gives your programs the ability to process wave (.WAV), MIDI
(.MID), and QuickTime Movie (.MOV) files. If you want to use audio files, the
computer must be equipped with a sound card capable of processing these files. To
record a sound file, you will need a microphone or some other supported input
device for the sound card. MIDI files cannot be recorded with the media part.
Java applications require the Java Media Framework (JMF) API. The media part
only supports the playback of audio and video files in the Java environment.
The video file formats that can be processed are: MPEG (*.mpg) files, QUICKTIME
Movie (*.mov) files, *.dat files, Microsoft Video for Windows *.avi files are
supported for Windows. To play these video files, the computer must have the
appropriate drivers.
Part Attributes
AddLink*
Bottom
Left
PartName
ShowPlyBar*
Visible
AllowLink*
FileName
Length
PartType
Top
Volume
AudioMode
Handle*
Panel
Position
Treble*
Bass*
InPlace
ParentName
RemoveLink*
UserData
Create
Destroy
Link*
Setting AudioMode
To process a file, set the AudioMode attribute to one of the following values:
Value Description
1
101
Signaling Events
When the media part has completely processed a file, a Complete event is
signaled.
102
Media Panel
AllowLink
Enabled
PanelItem
PartType
UserData
BackColor
Handle
PanelMode
Position
Visible
BackMix
Height
ParentName
RemoveLink
Volume
Create
MouseExit
Destroy
MouseMove
Link
Popup
Applicable Events
Change
MouseEnter
Press
103
Signaling Events
When the volume slider or the position slider is moved, a Change event is
signaled. Use the PanelItem attribute to determine which slider was changed. Use
the Volume attribute to determine the value of the volume slider, and the Position
attribute to determine the value of the position slider.
When a push button on the media panel is pressed, a Press event is signaled. Use
the numeric value returned by the PanelItem attribute to determine which button
caused the Press event. Refer to VisualAge RPG Parts Reference, SC09-2450-05for a
list of possible values.
104
Menu Bar
Use the menu bar part to give users access to pull-down menus. You can add
submenu parts and menu item parts to the menu bar.
A menu bar appears near the top of the window frame, just below the title bar.
When the user selects a menu item from it, a pull-down menu appears, showing
the items on that menu. Selecting a menu item immediately initiates the action it
describes.
Note: You can manipulate this parts properties, events, and so on, only from its
pop-up menu in the project tree view.
For related information, see:
v Menu Item on page 106
v Submenu on page 171
v Pop-up Menu on page 138
Part Attributes
PartType
PartName
ParentName
UserData
Applicable Events
Create
Destroy
105
Menu Item
Enabled
PartName
FileName
PartType
Destroy
MenuSelect
Label
UserData
Applicable Events
Create
Setting a Mnemonic
Note: Mnemonics are not supported in Java applications.
To specify a mnemonic key for the menu item, place the mnemonic identifier in
front of a character in the text of the Label attribute. For Windows, use an
ampersand (&). The designated character is displayed on the interface with an
underscore, for example, Display. The underscore informs users that they can
select the menu item by pressing the underlined character on the keyboard.
106
Signaling Events
When the user selects a menu item, a MenuSelect event is signaled.
Note: Only menu items signal a MenuSelect event. Submenus (such as cascaded
menus), which are attached to other menu items do not.
107
Message Subfile
Use the message subfile part to display predefined messages or to display text that
you supply in your program logic: for example, error or status information.
This part is always positioned at the bottom of the window frame and runs the
width of the window. You cannot resize its width; you can, however, resize its
height so that it shows more messages. At run time, users can use scroll bars to
view all of the messages.
Part Attributes
AddMsgID
DropEnable*
FontItalic
FontUnder*
Handle*
NbrOfSel
RemoveMsg
UserData
AddMsgText
Enabled
FontName
ForeColor
Height
ParentName
Selected
Visible
Count
FirstSel
FontSize
ForeMix
Index
PartName
ShowTips
DragEnable*
FontBold
FontStrike*
GetItem
MsgSubText
PartType
TipText
Destroy
MouseExit
Drop
MouseMove
Enter
Popup
108
message is added to the message subfile part. To set the message substitution data,
use the MsgSubText attribute before you set the AddMsgID attribute.
Note: The substitution data remains in effect until another MsgSubText attribute is
used.
Removing Messages
Use the RemoveMsg attribute to remove a message from the message subfile part.
Specify the index number of the message to be removed. To remove all messages,
use an index value of 0.
109
*********************************************************************
*
*
* Program ID . . : MESSAGE
*
*
*
* Description . : Sample program to demonstrate the Message
*
*
subfile part.
*
*
*
*********************************************************************
*
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : PB_CLOSE
*
*
*
* Event . . : PRESS
*
*
*
* Description: Terminate the program
*
*
*
*********************************************************************
*
C
PB_CLOSE
BEGACT
PRESS
MAIN
*
C
move
*on
*inlr
*
C
ENDACT
Figure 21. Coding Example Using the Message Subfile Part (Part 1 of 2)
110
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : PB_OK
*
*
*
* Event . . : PRESS
*
*
*
* Description: Check that the value entered is allowed. If not,
*
*
add a message to Message subfile part.
*
*
*
*
The value entered is used as substitution text in
*
*
the message.
*
*
*
*********************************************************************
*
C
PB_OK
BEGACT
PRESS
MAIN
*
* Clear the message subfile
*
C
Msg1
setatr
0
RemoveMsg
*
* Get the part number
*
C
PartNum
getatr
Text
tmp4
4 0
*
* If part number is not valid, add a message to the
* Message part. The partnumber entered by the user is
* used as the substition text.
* Since substitution text must be a string, we move the
* numeric part number value to a character field, and use
* it as the substitution text.
C
tmp4
ifle
*zero
C
tmp4
orgt
1999
C
move
tmp4
char4
4
C
Msg1
setatr
char4
MsgSubText
C
Msg1
setatr
1
AddMsgID
*
* Give the PartNum entry field FOCUS, so the cursor will
* return to it.
C
PartNum
setatr
1
Focus
*
* Part number is OK, continue processing
C
else
*
...
*
...
*
...
Figure 21. Coding Example Using the Message Subfile Part (Part 2 of 2)
111
Multiline Edit
Use the multiline edit part if you want the user to be able to type in several lines
of text.
The multiline edit part has defined boundaries. Sometimes not all of its text is
visible. The user can scroll up, down, left, or right to view text that is currently not
visible.
Part Attributes
AddLineEnd
Bottom
CsrLine
DragEnable*
FontBold
FontStrike*
Handle*
Left
ParentName
ReadOnly
TextEnd
TextString
Undo
WordWrap
AddOffset
CanUndo
CsrPos
DropEnable*
FontItalic
FontUnder*
Height
LineNumber
PartName
Refresh
TextLength
TipText
UserData
BackColor
CharOffset
Cut
Enabled
FontName
ForeColor
InsertLine
LineText
PartType
ShowTips
TextSelect
Top
Visible
BackMix
Copy
Delete
Focus
FontSize
ForeMix
InsertText
NbrOfLines
Paste
Text
TextStart
TopLine
Width
Click
Drop
MouseDown
MouseUp
Create
GotFocus
MouseEnter
Popup
DblClick
KeyPress
MouseExit
VKeyPress
112
Changing Color
If a multiline edit part exists on a canvas part whose background color is set to the
system default, changes to the background color of the canvas will be inherited by
the multiline edit part. Additional multiline edit parts added to the canvas will not
inherit this color. To correct this, defer setting the background color of the canvas
until you have placed all multiline edit parts on it. Alternatively, you can make the
multiline edit parts inherit the color by setting the color of the canvas to the
system default and then back to your predefined RGB color setting.
If you drag and drop a color onto the scroll bar of a multiline edit part, that color
is not saved. The multiline edit part will be changed to the new color, but when
you close and reopen the window, the color will be changed back to the original.
Choosing Fonts
Not all fonts are supported by the multiline edit part. After you select a font for
this part, it will adjust to display the closest match for the selected font.
113
114
*********************************************************************
*
*
* Program ID . . : MLE
*
*
*
* Description . : Sample program to demonstrate the Multiline Edit *
*
part.
*
*
*
*********************************************************************
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : PB_CLOSE
*
*
*
* Event . . : PRESS
*
*
*
* Description: Terminate the program
*
*
*
*********************************************************************
*
C
PB_CLOSE
BEGACT
PRESS
MAIN
*
C
move
*on
*inlr
*
C
ENDACT
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : PB_COPY
*
*
*
* Event . . : PRESS
*
*
*
* Description: Copy the selected text in the MLE to the entry field *
*
part.
*
*
*
*********************************************************************
*
C
PB_COPY
BEGACT
PRESS
MAIN
*
C
EF1
setatr
*blanks
Text
C
MLE1
getatr
TextStart
start
5 0
C
MLE1
getatr
TextSelect selected
128
*
C
start
ifgt
*zero
C
ef1
setatr
selected
Text
C
endif
*
C
ENDACT
Figure 22. Coding Example Using the Multiline Edit Part (Part 1 of 2)
115
*********************************************************************
*
*
* Window . . : Main
*
*
*
* Part . . . : Top
*
*
*
* Event . . : Press
*
*
*
* Description: Set the 5th line in the MLE part as top line.
*
*
*
* Change activity:
*
*
*
*********************************************************************
*
C
TOP
BEGACT
PRESS
MAIN
*
C
eval
%setatr(MAIN:MLE1:TOPLINE) = 5
C
ENDACT
*********************************************************************
*
*
* Window . . : Main
*
*
*
* Part . . . : Bottom
*
*
*
* Event . . : Press
*
*
*
* Description: Set bottom
*
*
*
*********************************************************************
*
C
BOTTOM
BEGACT
PRESS
MAIN
*
C
eval
%setatr(MAIN:MLE1:TOPLINE) = 0
C
ENDACT
Figure 22. Coding Example Using the Multiline Edit Part (Part 2 of 2)
116
Notebook
Use the notebook part to present data that can be logically grouped by topic: for
example, customer information divided into categories such as Name, Shipping
Address, Orders, and Credits.
A notebook part is a graphical representation of a bound notebook. (In Windows
applications, this is known as a tab control.) You can add pages to the notebook,
and you can group the pages into sections separated by tabbed dividers. If the
notebook page has a canvas, you can add more than one part to it. If it does not
have a canvas, you can add only one part to it.
The user can turn the pages of the notebook to move from one page to the next, or
go straight to a section by clicking on its divider tab.
You can add notebook pages by:
v Using the properties notebook for the notebook part
v Pointing-and-clicking (or dragging-and-dropping) a properties tab or notebook
page with canvas onto the notebook part
For related information, see:
v Notebook Page on page 118
v Notebook Page with Canvas on page 119
Part Attributes
BackColor
Enabled
FontName
ForeColor
Left
PartType
UserData
BackMix
Focus
FontSize
ForeMix
PageNumber
Refresh
Visible
Bottom
FontBold
FontStrike*
Handle*
ParentName
ShowTabs*
Width
Count
FontItalic
FontUnder*
Height
PartName
Top
Destroy
117
Notebook Page
OnTop
Refresh
Visible
ParentName
TabImage
PartName
TabLabel
Destroy
PageSelect
SelPending*
Applicable Events
Create
Setting a Mnemonic
To specify a mnemonic key for the notebook page, place the mnemonic identifier
in front of a character in the text of the Label attribute. This designated character is
displayed on the interface with an underscore (for example, Display). Note that for
Windows, mnemonics are displayed, but do not function on notebook pages.
Note: Mnemonics are not supported in Java applications
118
Use the notebook page with canvas to add pages to a notebook part.
The canvas part occupies the client area of a notebook page part. By adding parts
to the canvas part, you can create a graphical user interface.
If you want to add only one part to the page, you can use the notebook page part
instead of the notebook page with canvas part. Because the notebook page part
does not have a canvas on it, the part you add will be sized automatically.
For related information, see:
v Notebook on page 117
v Notebook Page on page 118
Part Attributes
Enabled
PartType
UserData
OnTop
Refresh
Visible
ParentName
TabImage
PartName
TabLabel
Destroy
PageSelect
SelPending
Applicable Events
Create
119
ODBC/JDBC Interface
The ODBC/JDBC Interface part provides the ability to process database files that
support the Windows ODBC API or Sun Microsystems JDBC API. Examples of
these database file types include Foxpro, Access, and Paradox.
To develop applications that can use the ODBC/JDBC Interface part, you must be
familiar with SQL and have either the Windows ODBC SDK or Sun Microsystems
Java 2 Software Development Kit (J2SDK), Standard Edition, installed on your
workstation.
If you do not have the ODBC SDK, you can download it from Microsoft at the
following URL:
http://www.microsoft.com/odbc/download.htm
The JDBC support is part of the Java 2 Software Development Kit (J2SDK)
Version 1.2 for Windows. If you do not have the J2SDK, you can download it from
Sun Microsystems at the following URL:
http://java.sun.com/products/
Applications that access and manipulate data in a JDBC database require the
appropriate JDBC 2.0 compliance driver. You can find JDBC driver and other
information at the following URL:
http://java.sun.com/products/jdbc/
120
BindPart
BufferPtr*
Bottom
BufferType*
BufferDec*
CharData
Column
Columns
ConnectStr
Fetch
Handle*
Left
Refresh
SQLQuery
UserData
ColumnDec
ColumnType
CurrentRow
FetchNext
Height
ParentName
Rows*
Top
Visible
ColumnLen
Connect
DeleteRow
FetchPrior
InsertRow
PartName
SQLError
UnBind
Width
ColumnName
Connected
ExecuteSQL
GetTables
IsData
PartType
SQLMsgBox
UpdateRow
Destroy
ODBC
ODBC
Setatr
Setatr
If
...
Else
...
EndIf
*Blanks
ConnectStr
1
Connect
%Getatr(Main:ODBC:Connected)=1
121
D SelAll
*
C
ODBC
C
ODBC
SelAll
1
SQLQuery
ExecuteSQL
S
S
20
30
S
S
*
*
INZ(%Addr(first))
INZ(%Addr(last))
Setatr
Setatr
Setatr
Setatr
1
20
fptr
1
Column
BufferLen
BufferPtr
BufferType
Setatr
Setatr
Setatr
Setatr
2
30
lptr
1
Column
BufferLen
BufferPtr
BufferType
You can also use the %ADDR built-in directly on the C specifications to avoid
coding the D specifications to define the pointers:
C
Eval
%Setatr(`Main:ODBC1:BufferPtr)=%Addr(first)
Data Types
Use the BufferType attribute to indicate the data type of the program field
referenced by the BufferPtr attribute. The ODBC/JDBC Interface part uses the
BufferType attribute to perform the correct data translation when moving data
122
between the program field and table column. It is important to set this attribute
correctly, as there is no checking for proper field types.
Set the Column attribute before using the BufferType attribute. If the program field
is associated with a part on the interface, you can use the DataType attribute to get
the buffer type.
Use the following chart to set the VARPG data type for the corresponding,
supported SQL data type. Specify the BufferLen and BufferDec attributes only as
listed in the chart.
For character, decimal, integer, or small integer data types, specify only the
BufferLen attribute.
Note that Double, Float, and Real data types can be defined, in VARPG, as either
Float(F) or Zoned. If you define these as Zoned, the VARPG run time will only use
the number of decimal places specified by the BufferDec attribute when moving
data from the column. This can result in a loss of precision if the data source has
more decimal places than is specified by the BufferDec attribute. If you define
these fields as Float(F), do NOT specify the BufferLen or BufferDec attribute.
X
X
X
SelAll
1
SQLQuery
ExecuteSQL
123
To determine the number of rows that were returned as the result of an SQLQuery,
you can check the value of the Rows attribute.
Once a record set has been returned, you can process each row using the
FetchNext and FetchPrior attributes. Set the FetchNext attribute to 1 to return the
next row in the record set. Set the FetchPrior attribute to 1 to return the previous
row in the record set. To determine if a FetchNext or FetchPrior successfully
returned a row, check the value of the IsData attribute. A value of 1 indicates that
data was returned. Otherwise, the IsData value is set to 0.
In the following example, all of the records in a record set are read and the value
of column 1 (field first) is added to list box LB1.
C
C
ODBC1
ODBC1
Setatr
Getatr
1
IsData
FetchNext
Temp
LB1
ODBC1
DoW
Setatr
Getatr
EndDo
Temp = 1
first
IsData
AddItemEnd
Temp
1 0
*
C
C
C
C
PB_Update
BEGACT
PRESS
Main
ODBC1
ODBC1
Read
Getatr
Setatr
Main
CurrentRow
Row
Row
UpdateRow
*
C
C
C
1 0
*
C
ENDACT
Deleting a Row
Deleting a row is similar to updating one. (See Updating Row Data.) Use the
DeleteRow attribute to specify the row to be deleted. As with the UpdateRow
attribute, DeleteRow will cause any row in the row set to be deleted. It is not
necessary to fetch the row first.
In the following example, the user has pressed the Delete push button to delete a
record that has just been fetched and is currently being displayed on a window.
C
PB_Delete
BEGACT
PRESS
Main
ODBC1
ODBC1
Getatr
Setatr
CurrentRow
Row
Row
DeleteRow
*
C
C
1 0
*
C
ENDACT
124
a window containing details about a customer. Push buttons are provided that
allow the user to go to the next and previous records, and to update and delete the
current record.
The following figure shows the inquiry window:
125
*********************************************************************
* Define connect string
*
D ConnectStr
C
DSN=MS Access 97 Database;DBQ=D
CelDial.mdb;D
DriverId=25;FIL=D
MS Access;MaxBufferSiz
* Working variables
DClr
S
2 0
DCol
S
10
DSQL
S
255A
D%ColNumber
S
2 0
D%Part
S
10
D%Character
S
2
D AppStart
C
HourGlas.ANI
*
DDel
M
MsgNbr(*MSG0003)
D
MsgData(CustNo:CustNa)
D J
S
4 0
D I
S
4 0
*
D CSENDINFO
S
1S 0
*
* Define pointers to field buffers
*
DCBalance
S
18S 3
DP_001
S
*
DP_002
S
*
DP_003
S
*
DP_004
S
*
DP_005
S
*
DP_006
S
*
DP_007
S
*
DP_008
S
*
DP_009
S
*
DP_010
S
*
DP_011
S
*
DP_012
S
*
DP_013
S
*
*
* Select ALL records
*
DSelAll
C
Select * From "Customers"
126
Balance (Numeric-Double)
Number
Name
Rep number
Contact
Phone
Fax
Address
City
Country
Zip Postal Code
Zip location
Balance
Send Market Info to?
*********************************************************************
*
*
* Window/Part/Event:
*
*
*
* Description: Bind program fields to columns and connect to the
*
*
database table CUSTOMERS
*
*
*
*********************************************************************
*
C
Main
BEGACT
CREATE
Main
*
C
Main
Setatr
appstart
MouseIcon
C
ODBC
Setatr
0
Visible
C
MoveL
ASC
Seq
4
C
Eval
CLR = *White
C
Move
255:255:255 Mix
C
SFL1
Setatr
1
SizeToFit
C
SFL1
Getatr
BackColor
RowClr
2 0
* Bind fields to columns
*
* Bind column: Number
C
ODBC
SetAtr
1
Column
C
ODBC
SetAtr
7
BufferLen
C
ODBC
SetAtr
1
BufferType
C
Eval
P_001=%Addr(CUSTNO)
C
ODBC
SetAtr
P_001
BufferPtr
*
* Bind column: Name
C
ODBC
SetAtr
2
Column
C
ODBC
SetAtr
40
BufferLen
C
ODBC
SetAtr
1
BufferType
C
Eval
P_002=%Addr(CUSTNA)
C
ODBC
SetAtr
P_002
BufferPtr
*
* Bind column: Rep number
C
ODBC
SetAtr
3
Column
C
ODBC
SetAtr
5
BufferLen
C
ODBC
SetAtr
1
BufferType
C
Eval
P_003=%Addr(Repno)
C
ODBC
SetAtr
P_003
BufferPtr
*
* Bind column: Contact
C
ODBC
SetAtr
4
Column
C
ODBC
SetAtr
30
BufferLen
C
ODBC
SetAtr
1
BufferType
C
Eval
P_004=%Addr(Contac)
C
ODBC
SetAtr
P_004
BufferPtr
*
127
128
129
*********************************************************************
*
*
* Window/Part/Event: Main/PB_OK/Press
*
*
*
* Description: Close the Detail window
*
*
*
*********************************************************************
*
C
PB_OK
BEGACT
PRESS
DETAIL
*
C
ClsWin
Detail
*
C
ENDACT
*********************************************************************
*
*
* Window/Part/Event: Main/SFL1/Enter
*
*
*
* Description: Show detail on selected customer
*
*
*
*********************************************************************
*
C
SFL1
BEGACT
ENTER
MAIN
*
C
ReadS
SFL1
C
Eval
SQL=SELECT * FROM CUSTOMER WHERE CUSTNO=+
C
Custno
C
ShowWin
Detail
80
C
Write
Detail
C
Eval
%Setatr(Detail:Detail:Focus)=1
*
C
ENDACT
*********************************************************************
*
*
* Window/Part/Event: Main/PB_Columns/Press
*
*
*
* Description: Show the options window
*
*
*
*********************************************************************
*
C
PB_COLUMNS
BEGACT
PRESS
MAIN
*
C
ShowWin
Columns
88
C
Eval
%Setatr(Columns:Columns:Focus)=1
*
C
ENDACT
130
*********************************************************************
*
*
* Window/Part/Event: Columns/PB_Cancel/Press
*
*
*
* Description: Close the options window
*
*
*
*********************************************************************
*
C
PB_CANCEL
BEGACT
PRESS
COLUMNS
*
C
ClsWin
Columns
*
C
ENDACT
*********************************************************************
*
*
* Window/Part/Event: Main/SFL1/ColSelect
*
*
*
* Description: Sort columns by selected column
*
*
*
*********************************************************************
*
C
SFL1
BEGACT
COLSELECT
MAIN
*
C
Eval
SQL=SELECT * FROM CUSTOMERS ORDER BY +
c
%EditC(%ColNumber:1) + + Seq
C
ODBC
Setatr
SQL
SQLQuery
C
ODBC
Setatr
1
ExecuteSQL
C
Exsr
Fill
*
C
ENDACT
*********************************************************************
*
*
* Window/Part/Event: Main/PB_Update/Press
*
*
*
* Description: Updated changed record
*
*
*
*********************************************************************
*
C
PB_UPDATE
BEGACT
PRESS
MAIN
*
C
ReadC
SFL1
99
*
C
If
NOT *IN99
C
SFL1
Getatr
FirstSel
Sel
4 0
C
ODBC
Setatr
Sel
UpdateRow
*
C
Else
C
*MSG0002
Dsply
mRC
9 0
C
EndIf
*
C
ENDACT
131
*********************************************************************
*
*
* Window/Part/Event: Main/PB_Delete/Press
*
*
*
* Description: Delete selected record
*
*
*
*********************************************************************
*
C
PB_DELETE
BEGACT
PRESS
MAIN
*
C
ReadS
SFL1
99
*
C
If
NOT *in99
C
Del
Dsply
mRC
*
C
If
mRC=*YESButton
C
SFL1
Getatr
FirstSel
Sel
4 0
C
ODBC
Setatr
Sel
DeleteRow
C
EndIf
*
C
EndIf
*
C
ENDACT
*********************************************************************
*
*
* Window/Part/Event: Main/PB_Opt/Press
*
*
*
* Description: Show the options window
*
*
*
*********************************************************************
*
C
PB_Opt
BEGACT
PRESS
MAIN
*
C
ShowWin
Columns
88
*
C
ENDACT
*********************************************************************
*
*
* Window/Part/Event: Columns/CB_Hrule/Select
*
*
*
* Description: Toggle horizontal rule
*
*
*
*********************************************************************
*
C
CB_HRULE
BEGACT
SELECT
COLUMNS
*
C
Eval
%Setatr(Main:SFL1:HRule)=
C
%Getatr(Columns:CB_HRule:Checked)
*
C
ENDACT
132
*********************************************************************
*
*
* Window/Part/Event: Columns/CB_VRule/Select
*
*
*
* Description: Toggle vertical rule
*
*
*
*********************************************************************
*
C
CB_VRULE
BEGACT
SELECT
COLUMNS
*
C
Eval
%Setatr(Main:SFL1:VRule)=
C
%Getatr(Columns:CB_VRule:Checked)
*
C
ENDACT
*********************************************************************
*
*
* Subroutine: Fill
*
*
*
* Description: Fill the subfile from the database
*
*
*
*********************************************************************
C
Fill
Begsr
*
C
Main
Setatr
99
MouseShape
C
Z-Add
0
Count
C
Eval
*IN01 = *OFF
C
Clear
SFL1
C
SQL
Setatr
SQL
Text
C
ODBC
Setatr
1
FetchNext
C
ODBC
Getatr
IsData
Temp
1 0
*
* Do while there is data
C
DoW
Temp = 1
C
Write
SFL1
*
C
Eval
*IN01 = NOT *IN01
*
C
If
*IN01
C
Eval
%Setatr(Main:SFL1:RowBGMix)=Mix
C
EndIf
*
* Move the progress bar
C
Add
1
Count
C
Main
Setatr
1
PBStep
* Check if there is another row
C
ODBC
Setatr
1
FetchNext
C
ODBC
Getatr
IsData
Temp
1 0
C
EndDo
*
133
C
C
C
C
C
C
Main
Count
SFL1
Setatr
Setatr
Setatr
Eval
Main
Setatr
0
PBSetPos
Count
Label
1
SelectItem
%Setatr(Main:SQL:Text)=
%Getatr(Main:ODBC:SQLQuery)
1
MouseShape
*
C
EndSr
*********************************************************************
*
*
* Window/Part/Event: Columns/ST06/Click
*
*
*
* Description: Change list colour
*
*
*
*********************************************************************
*
C
ST06
BEGACT
CLICK
COLUMNS
*
C
Eval
*IN01 = *OFF
C
Eval
I=%Getatr(Main:SFL1:Count)
C
%Part
Getatr
BackMix
Mix
11
*
C
Do
I
J
C
Eval
*IN01 = NOT *IN01
*
C
If
*IN01
C
Eval
%Setatr(Main:SFL1:Index)=J
C
Eval
%Setatr(Main:SFL1:RowBGMix)=Mix
C
EndIf
*
C
EndDo
*
C
ENDACT
*********************************************************************
*
*
* Window/Part/Event: Main/PB_Sql/Press
*
*
*
* Description: Process SQL statement
*
*
*
*********************************************************************
*
C
PB_SQL
BEGACT
Press
MAIN
*
C
SQL
Getatr
Text
SQL
C
Eval
%Setatr(Main:ODBC:SQLQuery)=SQL
C
Eval
%Setatr(Main:ODBC:ExecuteSQL)=1
C
Exsr
Fill
*
C
ENDACT
134
*********************************************************************
*
*
* Window/Part/Event: Columns/CB01/Select
*
*
*
* Description: Hide/Show columns
*
*
*
*********************************************************************
*
C
CB01
BEGACT
SELECT
COLUMNS
*
C
MoveL
%Part
TempName
4
C
Move
TempName
Num2
2 0
C
Eval
%Setatr(Main:SFL1:ColNumber)=Num2
C
%Part
Getatr
Checked
State
1 0
*
C
If
State = 1
C
Eval
State = 0
*
C
Else
C
Eval
State=1
C
EndIf
*
C
Eval
%Setatr(Main:SFL1:Hidden)=State
*
C
ENDACT
*********************************************************************
*
*
* Window/Part/Event: Columns/CB_Sort/Select
*
*
*
* Description: Set sort sequence
*
*
*
*********************************************************************
*
C
CB_SORT
BEGACT
SELECT
COLUMNS
*
C
If
%Getatr(Columns:CB_Sort:Checked)=1
C
Eval
SEQ = ASC
*
C
Else
C
Eval
SEQ = DESC
C
EndIf
*
C
ENDACT
135
*********************************************************************
*
*
* Window/Part/Event: Detail/Detail/Create
*
*
*
* Description: Set all fields to read only
*
*
*
*********************************************************************
*
C
DETAIL
BEGACT
CREATE
DETAIL
*
C
CAN0000037 Setatr
1
ReadOnly
*
C
ENDACT
*********************************************************************
*
*
* Window/Part/Event: Main/MI_Tips/MenuSelect
*
*
*
* Description: Toggle display of tip text
*
*
*
*********************************************************************
*
C
MI_TIPS
BEGACT
MENUSELECT
MAIN
*
C
If
%Getatr(Main:MI_Tips:Checked)=0
C
Eval
%Setatr(Main:MI_Tips:Checked)=1
*
C
Else
C
Eval
%Setatr(Main:MI_Tips:Checked)=0
C
EndIf
C
Eval
%Setatr(Main:Main:ShowTips)=
C
%Getatr(Main:MI_Tips:Checked)
*
C
ENDACT
136
Outline Box
Use an outline box around a group of parts to indicate that they are related.
An outline box is a rectangular, unlabeled box. If you need a label on the box, use
the group box part instead.
For related information, see Group Box on page 82.
Part Attributes
Bottom
ParentName
Top
Handle*
PartName
UserData
Height
PartType
Visible
Left
Refresh
Width
Destroy
137
Pop-up Menu
Use the pop-up menu part to display a number of choices that pertain to a
particular part on your interface. You can add menu item parts and submenu parts
to the pop-up menu part.
The menu is called a pop-up because it appears when the user presses the
appropriate key or mouse button.
Note: You can manipulate this parts properties, events, and so on, only from its
pop-up menu in the project tree view.
For related information, see:
v Menu Bar on page 105
v Menu Item on page 106
v Submenu on page 171
Part Attributes
Handle*
PartName
X
InvName
PartType
Y
InvPName
UserData
138
ParentName
Visible*
Progress Bar
Use the progress bar part to indicate graphically the progress of a process, such as
copying files, loading a database, and so on.
For example, to show the progress of copying 100 files, you could set the PBRange
attribute to 100 and the PBStepSize attribute to 10. Your code could then monitor
the copyfile process and move the progress bar indicator forward in steps for every
ten files copied.
In Java applications, if the progress bars width is smaller than its height, the
progress bar will have a vertical orientation.
Part Attributes
Bottom
ParentName
PBSetPos
UserData
Handle*
PartName
PBStep
Visible
Height
PartType
PBStepSize
Width
Left
PBRange
Top
Destroy
139
Push Button
BackMix
Focus
FontSize
ForeMix
HighLight
PartName
TipText
Visible
Border*
FontBold
FontStrike*
Handle*
Label
PartType
Top
Width
Bottom
FontItalic
FontUnder*
Height
Left
Refresh
UserData
Destroy
MouseExit
GotFocus
MouseMove
LostFocus
Popup
Setting a Mnemonic
Note: Mnemonics are not supported in Java applications.
For each push button, use the Label attribute to associate text with a specific push
button. That text appears on the button.
To specify a mnemonic key for the push button, place the mnemonic identifier in
front of a character in the text of the Label attribute. For Windows, use an
ampersand (&). This designated character is displayed on the interface with an
140
underscore (for example, Cancel). The underscore informs users that they can
select the push button by pressing the Alt key and the underlined character on the
keyboard.
Signaling Events
A Press event is signaled to your program when:
v the user selects a push button.
v the user presses the Enter key if a default push button is defined.
v the user presses a command key that is assigned to a push button.
141
Radio Button
Use radio buttons if you want the user to select only one of a group of related but
mutually exclusive choices. When the user makes a selection, the previously
selected choice in the group is deselected.
A radio button appears as a raised circular button that is labeled with text beside
it. When selected, the circular button displays a dot.
Do not use radio buttons if you want the user to be able to select more than one
choice at a time. In that case, see Check Box on page 58.
Part Attributes
BackColor
Enabled
FontName
ForeColor
HighLight*
PartName
ShowTips
Visible
BackMix
Focus
FontSize
ForeMix
Label
PartType
TipText
Width
Bottom
FontBold
FontStrike*
Handle*
Left
Refresh
Top
Checked
FontItalic
FontUnder*
Height
ParentName
SelectIdx
UserData
Destroy
MouseMove
Enter
Popup
MouseEnter
Select
Setting a Mnemonic
To specify a mnemonic key for the radio button, place the mnemonic identifier in
front of a character in the text of the Label attribute. For Windows, use an
ampersand (&). This designated character is displayed on the interface with an
underscore (for example, Blue). The underscore informs users that they can select
the radio button by pressing the underlined character on the keyboard.
Note: Mnemonics are not supported in Java applications.
142
143
Note: Tab stops and group marks can also be set for individual parts from within
a parts properties notebook.
Signaling Events
When the user selects a radio button, a Select event is signaled.
144
Slider
Use the slider part if you want the user to be able to display, set, or modify a
value by moving a slider arm along a slider shaft.
Sliders are typically used for values that have familiar increments, such as seconds
or degrees, or to show the percentage of a task that has been completed.
By default, a slider is placed horizontally in the center of a box with the slider
shaft on the left side. A scale can be displayed to show the units of measure for the
shaft.
Use the properties notebook for the slider part to:
v Set the range of values that a slider can return
v Position the slider vertically or horizontally in a window
v Provide a scale to indicate the units of measure represented by the slider
Part Attributes
AddLink*
Bottom
FontItalic
FontUnder*
Height
ParentName
RemoveLink*
TipText
Visible
AllowLink*
Enabled
FontName
ForeColor
Left
PartName
ShowTips
Top
Width
BackColor
Focus
FontSize
ForeMix
Maximum
PartType
TickLabel
UserData
BackMix
FontBold
FontStrike*
Handle*
Minimum
Refresh
TickNumber
Value
Create
LostFocus
Popup
Destroy
MouseEnter
GotFocus
MouseExit
Signaling Events
The Change event is signaled when the position of the slider arm changes.
145
If you use increment buttons to move the slider arm, the Change event is signaled
continuously as long as the buttons are pressed.
If you use the mouse to move the slider arm, the Change event occurs when the
mouse button is released.
Slider Example
This example illustrates how the slider part can be used to control the color of
other parts by using the BackMix attribute. As each slider is moved, its value is
used to determine the background color mix of its corresponding static text part to
show the intensity of that color. The background color of the static text labeled
Sample is updated to show the combined color mix of all three colors.
146
*********************************************************************
*
*
* Program ID . . : Slider
*
*
*
* Description . : Sample program to illustrate the slider part.
*
*
*
*
As each slider arm is moved, a CHANGE event is
*
*
signalled for that slider.
*
*
The CHANGE action subroutine retrieves the value *
*
of the slider, and updates the background colour *
*
mix of its corresponding static text part to
*
*
show the intensity of that colour.
*
*
*
*
The background colour mix of static text part
*
*
SAMPLE is also updated to show the result of
*
*
mixing all the colour values.
*
*
*
*********************************************************************
*
H
*
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : PB_EXIT
*
*
*
* Event . . : PRESS
*
*
*
* Description: Terminate the program.
*
*
*
*********************************************************************
*
C
PB_EXIT
BEGACT
PRESS
MAIN
*
C
move
*on
*inlr
*
C
ENDACT
Figure 24. Coding Example Using the Slider Part (Part 1 of 4)
147
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : GREEN
*
*
*
* Event . . : CHANGE
*
*
*
* Description: Update the Green colour value.
*
*
*
*********************************************************************
*
C
GREEN
BEGACT
CHANGE
MAIN
*
C
green
getatr
Value
val
3 0
C
move
val
grnmix
3
C
move
*blanks
mix
11
C
movel
000:
mix
C
mix
cat
grnmix:0
mix
C
mix
cat
:000:0
mix
C
STGreen
setatr
mix
BackMix
C
exsr
update
*
C
ENDACT
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : BLUE
*
*
*
* Event . . : CHANGE
*
*
*
* Description: Update the Blue colour value.
*
*
*
*********************************************************************
*
C
BLUE
BEGACT
CHANGE
MAIN
*
C
blue
getatr
Value
val
C
move
val
blumix
3
C
move
*blanks
mix
C
movel
000:000:
mix
C
mix
cat
blumix:0
mix
C
STBlue
setatr
mix
BackMix
C
exsr
update
*
C
ENDACT
148
*********************************************************************
*
*
* Subroutine . . : UPDATE
*
*
*
* Description . : Updates the background colour mix of the static *
*
text part Sample to show the results of
*
*
combining the colour values from the three
*
*
sliders.
*
*
*
*********************************************************************
*
C
UPDATE
BEGSR
*
C
move
*blanks
smpmix
11
C
movel
redmix
smpmix
C
smpmix
cat
::0
smpmix
C
smpmix
cat
grnmix:0
smpmix
C
smpmix
cat
::0
smpmix
C
smpmix
cat
blumix:0
smpmix
C
Sample
setatr
smpmix
BackMix
*
C
ENDSR
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : RED
*
*
*
* Event . . : CHANGE
*
*
*
* Description: Update Red colour value.
*
*
*
*********************************************************************
*
C
RED
BEGACT
CHANGE
FRA0000B
*
C
red
getatr
Value
val
C
move
val
redmix
3
C
move
*blanks
mix
C
movel
redmix
mix
C
mix
cat
:000:000:0 mix
C
STRed
setatr
mix
BackMix
C
exsr
update
*
C
ENDACT
149
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : MAIN
*
*
*
* Event . . : CREATE
*
*
*
* Description: Initialize the color mix
*
*
*
*********************************************************************
*
C
MAIN
BEGACT
CREATE
MAIN
*
C
move
000
grnmix
C
move
000
blumix
C
move
000
redmix
*
C
ENDACT
150
Spin Button
Use the spin button part to display, in sequence, a group of related but mutually
exclusive choices that have a logical consecutive order; for example, months of the
year. The choices are displayed as though they were arranged in a ring. The user
can move (or spin) through the choices by pressing the up arrow to go to the
next higher value, or the down arrow to go to the next lower one. Alternatively,
one of the choices can be typed directly into the entry field for the spin button.
Part Attributes
AddItemEnd
Bottom
FontItalic
FontUnder*
Height
ParentName
Refresh
TipText
Visible
Alignment*
Enabled
FontName
ForeColor
Left
PartName
RemoveItem
Top
Width
BackColor
Focus
FontSize
ForeMix
Maximum
PartType
ShowTips
UserData
BackMix
FontBold
FontStrike*
Handle*
Minimum
ReadOnly
Text
Value
Create
LostFocus
Popup
Destroy
MouseEnter
SpinDown
GotFocus
MouseExit
SpinEnd
151
v For numeric spin buttons, use the Value attribute. This attribute returns a value
ranging from the minimum to the maximum value specified for the spin button.
152
*********************************************************************
*
*
* Program ID . . : SPIN
*
*
*
* Description . : Sample program to demonstrate the Spin button
*
*
part.
*
*
*
*
A Character, and Numeric spin button are used
*
*
to show how they are initialized, and how their *
*
values are retrieved.
*
*
*
*********************************************************************
*
H
*
DDAY
S
10A
DIM(7) PERRCD(1) CTDATA
*
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : PB_COPY
*
*
*
* Event . . : PRESS
*
*
*
* Description: Copy the value from each Spin button to its
*
*
corresponding entry field part.
*
*
*
*********************************************************************
*
C
PB_COPY
BEGACT
PRESS
MAIN
*
C
SPB1
Getatr
Value
tmp2N
2 0
C
EF1
Setatr
tmp2N
Text
*
C
SPB2
Getatr
Text
tmp
10
C
EF2
Setatr
tmp
Text
*
C
ENDACT
Figure 25. Coding Example Using the Spin Button Part (Part 1 of 2)
153
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : MAIN
*
*
*
* Event . . : CREATE
*
*
*
* Description: Center the window on the display, and
*
*
initialize the spin buttons.
*
*
*
*********************************************************************
*
C
MAIN
BEGACT
CREATE
MAIN
*
* Initialize the Character spin button with the days of the
* week from the array DAY
C
Do
7
I
2 0
C
SPB2
Setatr
day(i)
AddItemEnd
C
EndDo
*
* Initialize the numeric spin button
C
SPB1
Setatr
1
Minimum
C
SPB1
Setatr
10
Maximum
*
C
ENDACT
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : PB_EXIT
*
*
*
* Event . . : PRESS
*
*
*
* Description: Terminate the program.
*
*
*
*********************************************************************
*
C
PB_EXIT
BEGACT
PRESS
MAIN
*
C
Move
*On
*INLR
*
C
ENDACT
**CTDATA DAY
Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Figure 25. Coding Example Using the Spin Button Part (Part 2 of 2)
154
Static Text
Use the static text part as a label for other parts, such as a prompt for an entry
field part. Static text parts do not accept end user input. In Java applications, static
text can be displayed only on a single line.
Part Attributes
Alignment
DataType
Enabled
FontSize
ForeMix
Left
Refresh
UserData
BackColor
DragEnable*
FontBold
FontStrike*
Handle*
ParentName
ShowTips
Visible
BackMix
DropEnable*
FontItalic
FontUnder*
Height
PartName
TipText
Width
Bottom
DropValue*
FontName
ForeColor
Label
PartType
Top
Create
Link*
MouseMove
DblClick
MouseDown
MouseUp
Destroy
MouseEnter
Popup
155
The READ and WRITE operation codes are most useful if you have many static
text parts in your user interface because you do not have to execute a series of get
and set attributes.
See Chapter 3, Programming with Parts, on page 25 for more information.
Editing Output
You can edit the contents of a static text part if the data type is numeric. See
Chapter 11, Editing Output, on page 239 for a description of editing.
156
Status Bar
Use the status bar part to provide additional information about a process or action
for your window. You can create up to five panes for the status bar. The status bar
part provides more flexibility than the StatusBar attribute for the window part.
By default, a status bar is created at the bottom of the window. However, you can
use the properties notebook to reposition it to the top. You can also set the border
style, number of panes, and text alignment.
Part Attributes
Handle*
SBIndex
Visible
ParentName
SBLabel
PartName
SBPanes
PartType
UserData
Destroy
157
Subfile
Use the subfile part to display a list of records, each consisting of one or more
fields.
The subfile part has similar function to an iSeries subfile. The user can scroll
horizontally or vertically through the list using the subfiles scroll bars.
To create a subfile entry field, point-and-click on a field from the Define Reference
Fields window or the parts palette and click it onto the subfile part. You can also
add fields using the properties notebook.
Note: The subfile part can only be point-and-clicked onto a notebook page with
canvas or window with canvas.
Part Attributes
AddItemEnd
BackMix
ButtonTip
CellBGMix
ColBGMix
ColWidth
EditColumn
Enabled
FontArea
FontSize
ForeMix
HdgFGClr
Height
ItemCount
NbrOfSel
PartName
RowBGMix
Selected
SflNxtChg
SortDesc
TopRecord
Visible
AllowEdit
Bottom
ByteComp
CellFGClr
ColFGClr
Count
EditIndex
ExtSelect*
FontBold
FontStrike*
Handle*
HdgFGMix
Hidden
Left
OpenEdit
PartType
RowFGClr
SelectItem
ShowTips
StartAt
UserData
VRule
AutoSelect
ButtonIdx
CapsLock
CellFGMix
ColFGMix
DColFRVCol
EditText
FirstSel
FontItalic
FontUnder*
HdgBGClr
HdgIdx
HRule
MapViewCol
PageSize
RemoveItem
RowFGMix
SelectList
SizeToFit
TipText
VColFRDCol
Width
BackColor
Buttons
CellBGClr
ColBGClr
ColNumber
DeSelect
EnableBtn
Focus
FontName
ForeColor
HdgBGMix
HdgText
Index
MultSelect
ParentName
RowBGClr
Scale
SetTop
SortAsc
Top
ViewColumn
158
ColSelect
FirstRec
LostFocus
NextRec
PageUp
VKeyPress
Create
GotFocus
MouseEnter
PageDown
Popup
Destroy
KeyPress
MouseExit
PageEnd
PrevRec
Operation
CHAIN
Reads a record from a subfile by specifying an index.
CLEAR
Clears all records from the subfile.
DELETE
Deletes a record from the subfile. All records following the deleted record
are moved up one position.
READC
Reads a record if the value of any of the entry fields in the record has
changed.
READS
Reads a selected record from the subfile. Users can select a record with
either the mouse or the keyboard. After the record has been read, it is
deselected.
UPDATE
Updates an existing subfile record. A record must have been read before
this operation code can be used.
WRITE
Adds a new record to the subfile.
Loading a Subfile
To display information in a subfile part, the information is written one record at a
time to the subfile part. Subfile fields that were defined in the GUI Designer for
the subfile part are set to the desired values, and the WRITE operation is
performed on the subfile record format.
159
REPORT
BEGACT
PRESS
READS
SUBF1
DOWEQ
*OFF
WIN1
*
C
99
*
C
*IN99
*
*
*
*
*
(Reported)
UPDATE
SUBF1
READS
END
SUBF1
SF1NAME
*
C
*
C
C
99
*
C
ENDACT
160
Use the READC operation to determine if the user has changed any field in the
subfile.
Hidden Fields
In the subfile parts properties notebook, you can set subfile fields to be Hidden so
that they are not displayed. For example, a subfile record can contain record key
information in a hidden field. You cannot see the hidden field, but the field is
returned to the program with the subfile record.
Enabling Tabbing
Use the Customize Tabs and Groups dialog to enable tabbing to a subfile part.
Right-click on the canvas part of the window containing the subfile part. Select
Tabs and Groups from the pop-up menu. The Customize Tabs and Groups dialog
appars. To set or clear the Tab stop setting, right-click on the part name and select
the Tab stop menu item.
Subfile Example
In the following example, a subfile part is used to display records from a database
file on an iSeries 400 server. Rather than filling the subfile with all records from the
database, navigation push buttons (FirstRec, LastRec, PageTop, PageUp,
PageDown, PrevPage, NextPage) are provided to control scrolling through the
records in the subfile.
When you press the Select push button, the READS operation code is used to
determine which record was selected, and the value of the CUSTNO field is
displayed in the static text part. Also, the first field in the record is opened for
editing.
Select the Exit menu item to end the program.
161
*********************************************************************
*
*
* Program ID . . : SUBFILE
*
*
*
* Description . : Sample program to demonstrate the subfile part. *
*
*
*
This sample program requires a physical database *
*
file on the AS/400 called CUSTOMER.
*
*
*
*********************************************************************
*
H
FCUSTOMER IF
E
DISK
REMOTE INFDS(INFDS) BLOCK(*Yes)
*
* INFDS for database file. FileSize will contain the number
* of records in the file when the file is opened.
DINFDS
DS
DFileSize
156
159B 0
*
*********************************************************************
*
*
* Subroutine . . : *INZSR
*
*
*
* Description . : Initialize working variables.
*
*
*
*********************************************************************
*
C
*INZSR
BEGSR
*
C
Z-Add
10
PageSize
2 0
C
Z-Add
1
CurRec
6 0
C
FileSize
Sub
PageSize
LastPage
6 0
C
Add
1
LastPage
*
C
ENDSR
*
*
Figure 27. Coding Example Using the Subfile Part (Part 1 of 10)
*********************************************************************
*
*
* Subroutine . . : NEXTPAGE
*
*
*
* Description . : Get the next page of records from the database. *
*
*
*********************************************************************
*
C
NEXTPAGE
BEGSR
*
C
add
PageSize
CurRec
*
C
CurRec
IfGt
FileSize
C
Sub
PageSize
CurRec
*
C
Else
C
Exsr
FillPage
C
SFl1
setatr
2
BUTTONIDX
C
SFL1
setatr
1
ENABLEBTN
C
EndIf
*
C
ENDSR
Figure 27. Coding Example Using the Subfile Part (Part 2 of 10)
162
*********************************************************************
*
*
* Subroutine . . : PREVPAGE
*
*
*
* Description . : Return the previous page of records from the
*
*
database.
*
*
*
*********************************************************************
*
C
PREVPAGE
BEGSR
*
C
Sub
PageSize
CurRec
*
C
CurRec
IfLe
*zero
C
Add
PageSize
CurRec
*
C
Else
C
Exsr
FillPage
C
SFl1
setatr
5
BUTTONIDX
C
SFL1
setatr
1
ENABLEBTN
C
EndIf
*
C
ENDSR
*********************************************************************
*
*
* Subroutine . . : FILLPAGE
*
*
*
* Description . : Fill the subfile part with a page of records
*
*
from the database.
*
*
*
*********************************************************************
*
C
FILLPAGE
BEGSR
*
C
Clear
Sfl1
C
CurRec
Setll
customer
C
Z-Add
1
count
2 0
C
Read
customer
9999
*
C
*in99
DoWeq
*off
C
count
AndLE
PageSize
C
Write
Sfl1
*
C
If
%Getatr(Main:HILITE:Checked)=1
C
SFL1
Setatr
Count
Index
C
SFL1
Setatr
1
ColNumber
C
SFL1
Setatr
*DarkGreen
CellFGClr
C
SFL1
Setatr
2
ColNumber
C
SFL1
Setatr
*DarkPink
CellFGClr
C
SFL1
Setatr
3
ColNumber
C
SFL1
Setatr
*DarkBlue
CellFGClr
C
EndIf
Figure 27. Coding Example Using the Subfile Part (Part 3 of 10)
163
*
C
C
C
Add
Read
EndDo
1
customer
count
Read
customer
CurRec
SFl1
SFL1
SFl1
SFL1
SFl1
SFL1
SFl1
SFL1
ifeq
setatr
setatr
setatr
setatr
setatr
setatr
setatr
setatr
endif
1
1
0
2
0
5
1
6
1
BUTTONIDX
ENABLEBTN
BUTTONIDX
ENABLEBTN
BUTTONIDX
ENABLEBTN
BUTTONIDX
ENABLEBTN
*in99
CurRec
SFl1
SFL1
SFl1
SFL1
SFl1
SFL1
SFl1
SFL1
ifeq
oreq
setatr
setatr
setatr
setatr
setatr
setatr
setatr
setatr
endif
ENDSR
*on
LastPage
1
1
2
1
5
0
6
0
BUTTONIDX
ENABLEBTN
BUTTONIDX
ENABLEBTN
BUTTONIDX
ENABLEBTN
BUTTONIDX
ENABLEBTN
9999
*
C
9999
*
C
C
C
C
C
C
C
C
C
C
*
C
C
C
C
C
C
C
C
C
C
C
C
*
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : MAIN
*
*
*
* Event . . : CREATE
*
*
*
* Description: Get the first page of records.
*
*
*
*********************************************************************
*
C
MAIN
BEGACT
CREATE
MAIN
*
C
Exsr
FillPage
*
C
SFL1
Setatr
*Green
HdgBGClr
C
SFL1
Setatr
*Black
HdgFGClr
C
SFL1
Setatr
1
ColNumber
Figure 27. Coding Example Using the Subfile Part (Part 4 of 10)
164
*
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
MAIN
SFL1
SFL1
SFL1
SFL1
SFL1
SFL1
SFL1
SFL1
SFL1
SFL1
SFL1
SFL1
SFL1
SFL1
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
Setatr
1
1
*MSG0001
0
2
*MSG0002
0
3
0
4
0
5
*MSG0004
6
*MSG0005
Visible
BUTTONIDX
BUTTONTIP
ENABLEBTN
BUTTONIDX
BUTTONTIP
ENABLEBTN
BUTTONIDX
ENABLEBTN
BUTTONIDX
ENABLEBTN
BUTTONIDX
BUTTONTIP
BUTTONIDX
BUTTONTIP
*
C
ENDACT
*
*
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : PB_SELECT
*
*
*
* Event . . : PRESS
*
*
*
* Description: Read the selected subfile record.
*
*
The static text part Selected is updated to show
*
*
the selected customer number.
*
*
The first field in the subfile is opened for editing.*
*
*
*********************************************************************
*
C
PB_SELECT
BEGACT
PRESS
MAIN
*
C
Reads
sfl1
27
*
C
*in27
IfEq
*off
C
Selected
Setatr
custno
Label
C
SFL1
Setatr
1
ColNumber
C
SFL1
Setatr
1
OpenEdit
C
EndIf
*
C
ENDACT
Figure 27. Coding Example Using the Subfile Part (Part 5 of 10)
165
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : HRULE
*
*
*
* Event . . : MENUSELECT
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
HRULE
BEGACT
MENUSELECT
MAIN
*
C
If
%Getatr(Main:HRULE:Checked)=1
C
SFL1
Setatr
0
HRule
C
HRULE
Setatr
0
Checked
*
C
Else
C
SFL1
Setatr
1
HRule
C
HRULE
Setatr
1
Checked
C
EndIf
*
C
ENDACT
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : VRULE
*
*
*
* Event . . : MENUSELECT
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
VRULE
BEGACT
MENUSELECT
MAIN
*
C
If
%Getatr(Main:VRULE:Checked)=1
C
SFL1
Setatr
0
VRule
C
VRULE
Setatr
0
Checked
*
C
Else
C
SFL1
Setatr
1
VRule
C
VRULE
Setatr
1
Checked
C
EndIf
*
C
Exsr
FillPage
*
C
ENDACT
Figure 27. Coding Example Using the Subfile Part (Part 6 of 10)
166
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : HILITE
*
*
*
* Event . . : MENUSELECT
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
HILITE
BEGACT
MENUSELECT
MAIN
*
C
If
%Getatr(Main:HILITE:Checked)=1
C
Eval
%Setatr(Main:HILITE:Checked)=0
*
C
Else
C
Eval
%Setatr(Main:HILITE:Checked)=1
C
EndIf
*
C
Exsr
FillPage
*
C
ENDACT
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : SFL1
*
*
*
* Event . . : PAGETOP
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
SFL1
BEGACT
PAGETOP
MAIN
*
C
Z-Add
1
CurRec
C
Exsr
FillPage
*
C
ENDACT
Figure 27. Coding Example Using the Subfile Part (Part 7 of 10)
167
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : SFL1
*
*
*
* Event . . : PAGEUP
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
SFL1
BEGACT
PAGEUP
MAIN
*
C
exsr
PrevPage
*
C
ENDACT
*
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : SFL1
*
*
*
* Event . . : LASTREC
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
SFL1
BEGACT
LASTREC
MAIN
*
C
FileSize
Sub
PageSize
CurRec
C
Add
1
CurRec
*
C
CurRec
IfLt
1
C
Z-Add
1
CurRec
C
EndIf
*
C
Exsr
FillPage
*
C
SFL1
setatr
1
BUTTONIDX
C
SFL1
setatr
1
ENABLEBTN
C
SFL1
setatr
2
BUTTONIDX
C
SFL1
setatr
1
ENABLEBTN
C
SFL1
setatr
5
BUTTONIDX
C
SFL1
setatr
0
ENABLEBTN
C
SFL1
setatr
6
BUTTONIDX
C
SFL1
setatr
0
ENABLEBTN
C
ENDACT
Figure 27. Coding Example Using the Subfile Part (Part 8 of 10)
168
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : SFL1
*
*
*
* Event . . : PAGEDOWN
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
SFL1
BEGACT
PAGEDOWN
MAIN
*
C
Exsr
NextPage
*
C
ENDACT
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : SFL1
*
*
*
* Event . . : FIRSTREC
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
SFL1
BEGACT
FIRSTREC
MAIN
*
C
Z-Add
1
CurRec
C
Exsr
FillPage
*
C
SFL1
setatr
1
BUTTONIDX
C
SFL1
setatr
0
ENABLEBTN
C
SFL1
setatr
2
BUTTONIDX
C
SFL1
setatr
0
ENABLEBTN
C
SFL1
setatr
5
BUTTONIDX
C
SFL1
setatr
1
ENABLEBTN
C
SFL1
setatr
6
BUTTONIDX
C
SFL1
setatr
1
ENABLEBTN
C
ENDACT
Figure 27. Coding Example Using the Subfile Part (Part 9 of 10)
169
*********************************************************************
*
*
* Window . . : MAIN
*
*
*
* Part . . . : EXIT
*
*
*
* Event . . : MENUSELECT
*
*
*
* Description:
*
*
*
*********************************************************************
*
C
EXIT
BEGACT
MENUSELECT
MAIN
*
C
Move
*on
*inlr
*
C
ENDACT
Figure 27. Coding Example Using the Subfile Part (Part 10 of 10)
Signaling Events
The Select event is signaled when:
v The user selects an item that is in a subfile
v You select an item in the list in your program
v The user selects an item that is already selected
The Enter event is signaled when:
v The user double-clicks over an item that is in the subfile
v The user presses the Enter key when the subfile has focus, and an item has been
selected
In your action subroutine for these events, you can use the READS operation code
to determine which item was selected.
170
Submenu
PartName
PartType
UserData
Applicable Events
Create
Destroy
171
Timer
Use the timer part if your program must perform certain operations at preset time
intervals. For example, you can use it to close a window, or perhaps end an
application, after a certain period of inactivity.
A timer part counts units of time and tracks the preset time interval between two
events, triggering the second event once the interval has passed.
When you create a timer part in the GUI builder, the part is represented as an icon
on the design window. However, in the properties notebook for a timer part, you
can specify that you do not want the icon displayed while the program is
executing.
Note: Do not use the timer part when precise timing is required. Due to other
programs running on your system, the Tick event may not necessarily occur
at the exact interval you specify.
Part Attributes
AddLink*
Left
PartType
Top
AllowLink*
Multiplier
RemoveLink*
UserData
Bottom
ParentName
TimerMode
Visible
Interval
PartName
TimerTicks
Destroy
Link*
Tick
172
Timer Example
In this example, a static text part is moved in the window for each timer Tick
event.
When you press the Start push button, the timer mode is set to 1. This starts the
timer and generates Tick events. During the processing of the Tick event, new
coordinates are calculated for the static text part, and the part is set to the new
location.
When you press the Stop push button, the TimerMode is set to 2. This stops the
timer.
Press the Close push button to terminate the program.
173
*********************************************************************
*
*
* Program ID . . : TIMER
*
*
*
* Description . : Sample program to demonstrate the timer part
*
*
by moving a static text part in a window each
*
*
time the timer Ticks.
*
*
*
*********************************************************************
*
H
*
* Declare display size System attributes
D%DspHeight
S
4 0
D%DspWidth
S
4 0
*
* Declare new size event attributes
D%NewHeight
S
4 0
D%NewWidth
S
4 0
*
* Define working variables
DminX
S
4 0 INZ(0)
DmaxX
S
4 0
DminY
S
4 0
DmaxY
S
4 0
DxChange
S
4 0 INZ(5)
DyChange
S
4 0 INZ(5)
*
174
*********************************************************************
*
*
* Window . . : FRA0000B
*
*
*
* Part . . . : FRA0000B
*
*
*
* Event . . : CREATE
*
*
*
* Description: Center the window on the display.
*
*
*
*
Calculate starting values.
*
*
Since the height attribute of the window part
*
*
includes the title bar, we subtract the height of
*
*
the title bar so the static text part remains within *
*
the window frame.
*
*
*
*
For SVGA, this value is about 20 pixels. It could
*
*
be adjusted for other resolutions.
*
*
*
*********************************************************************
*
C
FRA0000B
BEGACT
CREATE
FRA0000B
*
* Get beginning window height and width
C
FRA0000B
getatr
Height
winHeight
4 0
C
FRA0000B
getatr
Width
winWidth
4 0
*
* Center the window on the display
C
eval
%setatr(FRA0000B:
C
FRA0000B:
C
Left)=(%DspWidth-winWidth)/2
*
C
eval
%setatr(FRA0000B:
C
FRA0000B:
C
Bottom)=(%DspHeight-winHeight)/2
*
* Get beginning coordinates of static text part
C
ST1
getatr
Left
picX
4 0
C
ST1
getatr
Bottom
picY
4 0
*
* Get dimensions of static text part
C
ST1
getatr
Height
picHeight
4 0
C
ST1
getatr
Width
picWidth
4 0
*
* Calculate minimum and maximum Y coordinates
C
Start
getatr
Height
startH
4 0
C
Start
getatr
Bottom
startB
4 0
C
eval
minY = startB + startH
C
eval
maxY = winHeight - picHeight - 20
*
175
176
*********************************************************************
*
*
* Window . . : FRA0000B
*
*
*
* Part . . . : CLOSE
*
*
*
* Event . . : PRESS
*
*
*
* Description: Terminate the program.
*
*
*
*********************************************************************
*
C
CLOSE
BEGACT
PRESS
FRA0000B
*
C
eval
*inlr = *on
*
C
ENDACT
*********************************************************************
*
*
* Window . . : FRA0000B
*
*
*
* Part . . . : TIMER1
*
*
*
* Event . . : TICK
*
*
*
* Description: Respond to timer tick events by moving the static
*
*
text part in the window.
*
*
*
*
If the static text part moves outside the window
*
*
frame, its xChange or yChange values are multiplied *
*
by -1 to reverse the direction.
*
*
*
*********************************************************************
Figure 28. Coding Example Using the Timer Part (Part 4 of 6)
177
*
C
TIMER1
BEGACT
TICK
FRA0000B
*
* Calculate new static text coordinates
C
eval
picX = picX + xChange
C
eval
picY = picY + yChange
*
* Check static text remains in window boundaries
C
select
*
C
picX
whenlt
0
C
eval
xChange = xChange * -1
C
eval
picX = minX + xChange
*
C
picX
whengt
maxX
C
eval
xChange = xChange * -1
C
eval
picX = maxX + xChange
*
C
picY
whenlt
minY
C
eval
yChange = yChange * -1
C
eval
picY = minY + yChange
*
C
picY
whengt
maxY
C
eval
yChange = yChange * -1
C
eval
picY = maxY + yChange
*
C
endsl
*
* Move static text to new coordinates
C
ST1
setatr
picX
Left
C
ST1
setatr
picY
Bottom
*
*
C
ENDACT
Figure 28. Coding Example Using the Timer Part (Part 5 of 6)
*********************************************************************
*
*
* Window . . : FRA0000B
*
*
*
* Part . . . : FRA0000B
*
*
*
* Event . . : RESIZE
*
*
*
* Description: Get the size of the window after it has been resized *
*
so static part uses entire window.
*
*
*
*********************************************************************
*
C
FRA0000B
BEGACT
RESIZE
FRA0000B
*
C
eval
maxY = %NewHeight - picHeight - 20
C
eval
maxX = %NewWidth - picWidth
*
C
ENDACT
178
Use the vertical scroll bar part to allow users to scroll through a pane of
information vertically. The information can be a list of files, records in a database,
columns in a document, and so on. You can use the Range attribute to represent
the total number of objects to be scrolled through and the PageSize attribute to
determine the number of objects that can be displayed on a page.
Part Attributes
Bottom
Height
PageSize
Position
Top
Enabled
Left
ParentName
PrevLine
UserData
Focus
NextLine
PartName
PrevPage
Visible
Handle*
NextPage
PartType
Range
Width
Destroy
Scroll
179
Window
Windows are the users primary means of interacting with your program. Your
application must contain at least one window.
You can add only one part to the client area of a window, except for parts that are
extensions to the window frame, such as menu bars, pop-up menus and message
subfiles. The part you add is automatically sized to fit the client area.
If you want a window to contain more than one part, you must add a canvas part
to it. Or, use the window with canvas part to save a step.
Note: The window part is located in the Frames section of the parts catalog, not
on the parts palette.
For related information, see:
v Canvas on page 56
v Window with Canvas on page 181
Part Attributes
Bottom
Focus*
FontSize*
Height
MouseIcon*
PartType
PBStepSize
Refresh
ShowTips
Visible
Center
FontBold*
FontStrike*
IconHandle*
MouseShape*
PBRange
Print
SBLabel
StatusBar
Width
Enabled
FontItalic*
FontUnder*
Label
ParentName
PBSetPos
PrintAsIs
SBPosition
Top
WindowMode*
FileName*
FontName*
Handle*
Left
PartName
PBStep
ProgresBar
SBStyle
UserData
180
Close
LClickTray
ShutDown
Create
Moved
DeActivate
RClickTray
Windows are the end users primary means of interacting with your program. The
canvas, on a window with canvas part, allows you to add many parts to the
window.
You can point and click various parts onto the canvas portion, position them, and
organize them to produce a graphical user interface. You can also add parts that
are extensions of the windows frame, such as menu bars, pop-up menus and
message subfiles.
If you need to put only one part on the client area of the window, you do not need
the window with canvas part: you should use the window part instead (found in
the Frames section of the parts catalog). Without a canvas, the part you add will be
automatically sized to fit the client area.
For related information, see:
v Canvas on page 56
v Window on page 180
Part Attributes
Bottom
Focus*
FontSize*
Height
MouseIcon*
PartType
PBStepSize
Refresh
ShowTips
Visible
Center
FontBold*
FontStrike*
IconHandle*
MouseShape*
PBRange
Print
SBLabel
StatusBar
Width
Enabled
FontItalic*
FontUnder*
Label
ParentName
PBSetPos
PrintAsIs
SBPosition
Top
WindowMode*
FileName*
FontName*
Handle*
Left
PartName
PBStep
ProgresBar
SBStyle
UserData
Close
LClickTray
ShutDown
Create
Moved
DeActivate
RClickTray
Displaying a Window
By default, all windows are marked as Visible and Open Immediately when they
are created in the GUI Designer.
Decide which window you want the user to see first. That window is called the
main or primary window and you must set the Visible and Open Immediately
attributes accordingly for it. If you do not change the default settings, all the
windows will appear when the user starts your application.
Chapter 7. Using Parts
181
Referencing
The parts on a window are created when the window is created. Therefore, if you
attempt to reference any part on a window that has not been loaded, or to
reference a window attribute before the window is created, you will receive a Part
not found message.
Hint
If a window is displayed and you cannot click on its title bar, use this
method to move the window:
1. Position the mouse cursor somewhere on the visible portion of the
window.
2. Click and release mouse button 1.
3. Press the Alt-space key combination. Then press M.
4. Use the arrow keys to reposition the window.
5. When the window is in the desired position, press Enter.
182
Resizing a Window
There are two things you can do to create your application so that the user has one
or more ways to resize a window:
v In the GUI Designer, set the border of a window as Sizeable. This setting allows
the user to select the window border with the mouse button, and resize the
border while keeping the mouse button pressed. When the mouse button is
released, the ReSize event is signaled.
v Add a Maximize and a Minimize button to the window. The user can then
change the size of the window by selecting one of these buttons.
You can position parts on the window so that they maintain their relative position
and size within the windows boundaries after the window is resized. To do this,
use the ReSize event with the %NewHeight and %NewWidth event attributes.
In the following coding example, a push button part labeled PB1 is located in the
upper right corner of a window. When the window is resized, the ReSize action
subroutine calculates new Left and Bottom attribute values to ensure that the push
button remains within the windows boundaries.
*********************************************************************
*
*
* Program ID . . : ReSize
*
*
*
* Description . : Sample program to demonstrate how to ensure
*
*
parts remain within a window after it has been
*
*
resized.
*
*
*
*
A push button is located in the upper right
*
*
corner of the window. If the window is resized
*
*
to a smaller size, the push button will no
*
*
longer be visible, since all parts maintain
*
*
their relation with the lower-left corner of the *
*
window.
*
*
The RESIZE event is used to ensure the push
*
*
button also maintains its position relative to
*
*
the upper right corner of the window.
*
*
*
*********************************************************************
*
H
*
* Declare display size System attributes
D%DspHeight
S
4 0
D%DspWidth
S
4 0
*
Figure 29. Ensuring parts are displayed correctly after a window is resized (Part 1 of 3)
183
Figure 29. Ensuring parts are displayed correctly after a window is resized (Part 2 of 3)
184
*********************************************************************
*
*
* Window . . : FRA0000B
*
*
*
* Part . . . : FRA0000B
*
*
*
* Event . . : CREATE
*
*
*
* Description: Center the window on the display.
*
*
Get current coordinate of push button PB1 and its
*
*
offset from the upper right corner of the window.
*
*
*
*********************************************************************
*
C
FRA0000B
BEGACT
CREATE
FRA0000B
*
C
FRA0000B
getatr
Height
winHeight
4 0
C
FRA0000B
getatr
Width
winWidth
4 0
C
%DspWidth
sub
winWidth
diffWidth
4 0
C
%DspHeight
sub
winHeight
diffHeight
4 0
*
C
eval
%setatr(FRA0000B:
C
FRA0000B:
C
Left) = diffWidth / 2
*
C
eval
%setatr(FRA0000B:
C
FRA0000B:
C
Bottom) = diffHeight / 2
*
* Calculate the offsets of the push button part PB1 from
* the upper right corner of the window. These values are used
* to maintain this offset if the window is resized.
C
PB1
getatr
Left
PBLeft
4 0
C
PB1
getatr
Bottom
PBBottom
4 0
C
FRA0000B
getatr
Width
WinWidth
4 0
C
FRA0000B
getatr
Height
WinHeight
4 0
C
WinWidth
sub
PBLeft
HOffset
4 0
C
WinHeight
sub
PBBottom
VOffset
4 0
*
C
ENDACT
Figure 29. Ensuring parts are displayed correctly after a window is resized (Part 3 of 3)
Window List
In the properties notebook for a window part, you can indicate if the window
should appear in the window list. This list appears when you press the
Ctrl+Alt+Delete in Windows. By default, window parts do not appear in the
window list. You should set at least the main window to appear in the window
list. You can use the task list to redisplay the window.
185
Terminating a Program
If the user selects the Close option from the system menu on a window, the
operating system closes the window but does not necessarily terminate your
program. To prevent this from happening, you can do one of the following:
v Select the Terminate on close check box in the second Style page in the
windows properties notebook. This will terminate your program when the user
closes the window.
v In the first Style page of the windows properties notebook, deselect the System
Menu check box so that your windows are created without a System Menu. (By
default, all windows are created with a system menu.)
v Use the Close event. This event is signaled when the user selects Close from the
system menu. In the Close event action subroutine, you could set the LR
indicator on, or prompt the user to confirm that this window should be closed,
and set the ENDACT return point accordingly. For example, by setting the
return value to *NODEFAULT the close request is ignored and the window is not
closed.
*
* Define message box variables
Dstyle
M
button(*yesbutton: *nobutton)
D
style(*WARN)
Dmsg
M
msgtext(Are sure you want to exit?)
*
*********************************************************************
*
*
* Window . . : FRA0000B
*
*
*
* Part . . . : FRA0000B
*
*
*
* Event . . : CLOSE
*
*
*
* Description: Handle Close event from system menu to verify user
*
*
wants to close this window.
*
*
*
*********************************************************************
*
C
FRA0000B
BEGACT
CLOSE
FRA0000B
*
* Prompt for close
C
msg
dsply
style
rc
9 0
*
* If Yes, terminate program, allow close to occur
C
rc
ifeq
*YESBUTTON
C
move
*on
*inlr
C
movel
*DEFAULT
return
12
*
* Else, do not close this window
C
else
C
movel
*NODEFAULT return
C
endif
*
C
ENDACT
return
186
187
*Component
The *component part allows programmers to access and use component- and
system-wide attributes.
A *component part is the part representation of the component. One *component
part is created for each component automatically; it is invisible and not on the
palette.
Part Attributes
Active*
ClipBoard
DlgOwner
DspWidth
HelpWindow
MsgFile*
OS
Platform
PlugRC*
SelFolder*
ShDataName
WrkStnName*
Alarm
CurrentDir
DlgPrompt*
FileName
HostName*
MsgID
Parent
PlugCmd*
PlugResult*
SelPrinter*
ShDataPos
AppData
Dialog
DoEvents*
FocusPart*
LookNFeel*
MsgText
PartCount
PlugDLL*
Printer*
ShData
ShowMsgID
Button
DIRName*
DspHeight
FolderName*
MsgData
Name
PartList
PlugID*
PrtDevmode
ShDataLen
SwitchTo*
188
*
* Display File Open dialog
C
*Component Setatr
*
* This window is the owner
C
*Component Setatr
*
* Show only .DAT files
C
*Component Setatr
*
* Get the button pressed
C
*Component Getatr
*
* Handle the OK button
C
If
*
* User canceled
C
Else
*
C
EndIf
Dialog
Main Main
DlgOwner
*.DAT
Filename
Button
Button
1 0
Button = 1
The following example shows how to use a File Open dialog to select multiple
files.
*
C
eval
%setatr(*Component:*Component
C
:MulSel) = 1
C
eval
%setatr(*Component:*Component
C
:Dialog) = 1
C
eval
%setatr(*Component:*Component
C
:Filename)=*.jpg
C*Get the number of selected files.
C
z-add
0
num
c
*component getatr
NumOfSel
num
C*Get the path of the selected files.
C
eval
str=
C
%getatr(*Component:*Component:
C
folderName)
C*Retrieve the name of the selected files.
C
1
do
num
idx
4 0
C
eval
%setatr(*Component:*Component
C
:FileIndex) = idx
C
eval
str=
C
%getatr(*Component:*Component:
C
filename)
C
enddo
Figure 31. Use a File Open dialog to select multiple files
Selecting a printer
If your application prints to a printer attached to the workstation you can use the
SelPrinter and Printer attributes to allow the user to select to which printer the
output is to be sent. Setting the SelPrinter attribute to 1 displays the Windows
Print dialog to be displayed. When the user selects a printer from that dialog, the
printed output from your application will be sent to that printer.
Initial settings shown in the dialog can be set by the PrtDevmode attribute.
189
Using Plugins
The PlugDLL, PlugID, PlugCmd, PlugRC, and PlugResult attributes give you the
ability to extend the functionality of the GUI Designer. You provide the additional
functionality in a program that you have developed. Once your application is
registered to the GUI Builder by using the Vendor menu, your application can
interact with the GUI Designer. See chapter 20 for more details on creating plugins.
190
191
192
Notebook Considerations
If the Define iSeries Information properties notebook pages do not contain the
override name for the program, the data area, or the database file, then the
following occurs:
1. The name of the program, data area, or database file in the program is used.
2. If the program name, data area, or database file is library-qualified in the
program, then this library is used.
3. If the program name or database file is not library-qualified in the program, the
library list (*LIBL) on the iSeries server is searched.
4. The first server listed on the server page is used.
193
Note: The first server listed in the server page of the Define iSeries Information
notebook is known as the default server. At least one server is required for
every program that makes use of an iSeries server.
Setting Up a Server
You must set up a server when you are developing your application, so that you
can access it while you edit, compile, and debug your application. When you
package and distribute your application to other workstations, you also have to set
up a server if the running application accesses a different server than the one used
during design time.
Whenever you set up a server, ensure that the library list of the service job
contains the remote resource that you want to work with.
194
QCMDDDM can be used to change the library list of the DDM service job to
ensure that the library containing the database files is present in the DDM jobs
library list.
REMDTAARA
SERVER01
Be sure the data area has been initialized before you attempt to use it. A runtime
exception is issued if a data area on the server does not contain a valid packed
decimal value when attempting to retrieve it into a data area data structure with a
packed decimal subfield in a VisualAge RPG program.
*********************************************************************
*
*
* Program ID . . : dtaaraex.vpg
*
*
*
* Description . : Code segment to get the contents of an AS/400
*
*
data area.
*
*********************************************************************
*
D dtaara
S
6P 0 DTAARA
*********************************************************************
*
*
* Window . . : WIN1
*
*
*
* Part . . . : PSB0000C
*
*
*
* Event . . : PRESS
*
*
*
* Description: Get the contents of the AS/400 data area.
*
*********************************************************************
*
C
PSB0000C
BEGACT
PRESS
WIN1
C
IN
dtaara
C
ENDACT
195
196
*********************************************************************
*
*
* Program ID . . : ioex.vpg
*
*
*
* Description . : Create Database records using data from window. *
*
*
* Files . . . . : FILE1
*
*
*
*********************************************************************
*
FFILE1
UF A E
DISK
REMOTE USROPN
*********************************************************************
*
*
* Window . . : WIN1
*
*
*
* Part . . . : *INZSR
*
*
*
* Event . . : Initialization routine
*
*
*
* Description: Open Database file (FILE1).
*
*
*
*********************************************************************
*
C
*INZSR
BEGSR
C
OPEN
FILE1
C
ENDSR
*********************************************************************
*
*
* Window . . : WIN1
*
*
*
* Part . . . : PSB0000D
*
*
*
* Event . . : PRESS
*
*
*
* Description: User is finished creating records. End Application. *
*
*
*********************************************************************
*
C
PSB0000D
BEGACT
PRESS
WIN1
C
SETON
LR
C
ENDACT
Figure 33. Database file example (Part 1 of 2)
197
*********************************************************************
*
*
* Window . . : WIN1
*
*
*
* Part . . . : PSB0000C
*
*
*
* Event . . : PRESS
*
*
*
* Description: Read field information from screen and add record
*
*
to AS/400 Database file.
*
*
*
*
*
*********************************************************************
*
C
PSB0000C
BEGACT
PRESS
WIN1
C
READ
WIN1
C
WRITE
FORMAT1
C
ENDACT
FILE1 in the file specification is used as a file alias, since an entry exists in the File
page of the associated Define iSeriesInformation notebook.
The first member of FILE1 in library LIB1 on server TORAS180 is used during file
open. FILE1 in the remote name does not have to match the override name in the
file entry. The override name represents a link between the file entry in the File
page and the file name used in the VisualAge RPG program.
The part names of the two entry fields are NAME and ADDRESS. The VisualAge
RPG creates fields with the same names and the same attributes. In this example,
NAME and ADDRESS are 20-character fields. The database file also contains two
fields named NAME and ADDRESS, both 20 characters. The following is the DDS
for these fields:
A
A
R RECORD100
NAME
ADDRESS
20A
20A
When field names and their attributes match, only one field is created. This
example reads the data from the window.
C* N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq..
C
READ
WIN1
When this READ is performed, data is moved automatically from the screen into
the two fields NAME and ADDRESS. Since the data is now in the appropriate
fields, it can be written directly to the database without any further field
movement.
C* N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq..
C
WRITE
FORMAT1
In this example, the data in the two fields NAME and ADDRESS is moved to the
output buffer automatically before the write command is issued to the iSeries 400
database.
198
Level Checking
The VisualAge RPG supports level checking between a VisualAge RPG program
and the iSeries 400 database files being used.
The compiler always provides the information required by level checking. Level
checking occurs on a record-format basis when the file is opened, unless you
specify LVLCHK(*NO) when creating or changing the database file.
Note: If a level check occurs, it is handled as an I/O error. For more information,
see VisualAge RPG Language Reference.
QCMDDDM Linkage(*Server)
BEGSR
C
Eval
C
TOFILE(SYSLIBT/MENUFL) +
C
MBR( + MemberName + ) +
C
OVRSCOPE(*JOB) +
C
OPNSCOPE(*JOB)
C
Exsr
C
C
CallExecDDM
ENDSR
CallExecDDM
BEGSR
C
C
C
C
EVAL
Call
Parm
Parm
ENDSR
QCMDDDM_Parm2 = %LEN(QCMDDDM_Parm1)
QCMDDDM
QCMDDDM_Parm1
QCMDDDM_Parm2
199
IF
K DISK
BLOCK(*YES)
REMOTE
.
.
.
C
FLD2
SETLL
REC1
READ
REC1
.
.
.
C
10
200
These servers are required when you develop your applications. In addition, when
you run your applications, you should have the TCP/IP DDM server active as
well. Use the STRTCPSRV command to start this server.
201
APIs supplied in VARPG. These APIs will set the connection environment, they
will not establish a connection. The connection can then be established by
accessing the server (opening a file or invoking a remote program) or by using the
Connect APIs described in the second half of this chapter.
VARPG provides these two Set server APIs:
v The Set Server API allows the programmer to set a server to a new Remote
Location name regardless of which remote server a current session is already
connected to. In the case an active connection is already established this
connection will be terminated.
v The Change Server API allows a programmer to specify a new Remote Location
name for a specific remote server connection already in use. It will stop the
communications session already in place and will set the connection to the new
Remote Location name so a subsequent request to connect to the server alias
will result in establishing a session with this new server.
The only difference to the Set server API is the fact that the programmer can
qualify the server name to be terminated and changed. The parameters for new
remote location name and keep job are the same as in the Set Server function.
These two APIs allow the VARPG programmer to easily write VARPG programs
that can dynamically change the target server, and allow the application to connect
to different servers without ending the VARPG application.
For the user controlled connection startup, the programmer uses the APIs to pass
the existing server name, new server name, and information how to deal with jobs
on an existing connection. The functions whose interface is described by these APIs
are located in the FVDCWVC9.DLL. This DLL is part of the VARPG run time and
is located in the path; there is no need to rearrange the path environment for
applications using this API.
The Set remote location function, VARPG_Set_Remote_Location, accepts the
following parameters and provides a numeric return code indicating the success or
failure of the change server process:
v New Remote Location name
v Keep job
The parameters are null terminated character variables passed by reference. The
following example shows the C signature and the RPG IV prototype for the API:
* Set server prototype
* extern "C" VARPG_ENTRY int VARPG_Set_Remote_Location( char *
*
newRmtLocation, char * keepServerJob );
*
D setsrv
pr
5i 0 dll(FVDCWVC9) extproc
D
(VARPG_Set_Remote_Location)
D newrmtl
*
value options(*string)
D keepjob
*
value options(*string)
If you need to set the remote location name back to the default, specify (an
empty string) in the new remote location name parameter.
When terminating an existing connection, if the programmer wants to end the
active VARPG jobs running on the iSeries server for this session, he needs to
specify the literal OFF for the keepServerJob parameter. Only if the jobs are
supposed to continue running, after the VARPG communications session
terminated, specify ON. The programmer has to manage non terminated VARPG
202
jobs himself, and has to make sure they get terminated eventually. The VARPG
runtime doesnt have access to these jobs after a server has been switched.
The Change remote location function, VARPG_Chg_Remote_Location, accepts the
following parameters and provides a numeric return code indicating success or
failure of the change server process:
v Old Remote location name
v New Remote Location name
v Keep job
The parameters are null terminated character variables passed by reference.
The following example shows the C signature and the RPG IV prototype for the
API:
* Change server prototype
* extern "C" VARPG_ENTRY int VARPG_Chg_Remote_Location( char *
*
oldRmtLocation, char * newRmtLocation,
*
char * keepServerJob );
*
Dchangesrv
pr
5i 0 dll(FVDCWVC9) extproc
D
(VARPG_Chg_Remote_Location)
D oldrmtl
*
value options(*string)
D newrmtl
*
value options(*string)
D keepjob
*
value options(*string)
The return codes for these APIs are listed in Figure 35 on page 205.
203
signon
pr
system
userid
password
5I 0 dll(FVDCWVC9)
extproc(VARPG_Set_Signon_Info)
*
VALUE options(*string)
*
VALUE options(*string)
*
VALUE options(*string)
newpassw
system
userid
oldpassword
newpassword
pr
5I 0 dll(FVDCWVC9)
extproc(VARPG_Change_Password)
*
value options(*string)
*
VALUE options(*string)
*
VALUE options(*string)
*
VALUE options(*string)
There are many different ways to gather the server/user Id information. The
sample program provided in VARPG uses its own signon dialog written in
VARPG. Remember that the connection is established for the VARPG application
and its components. If you start another VARPG application, by default the
VARPG run time will use its usual connection startup mechanism again the same
way it does for the first VARPG application. The programmer has two options to
change this behavior.
1. Use the control specification option INHERITSIGNON in the application to
re-use the previously specified authentication information
2. Use these Connect APIs to control how to deal with server authentication
When using the Signon API in a VARPG application with remote server files, make
sure to specify the USROPN keyword in the file specifications for the remote files.
If USROPN is not specified, the server connection will be established at application
204
startup before you have a chance to invoke the SIGNON function. In components
started after the communication session has been established, you can use the RPG
implicit opening of files by not specifying the USROPN keyword in these
components. The components will reuse the existing connection of the application.
The return codes for these Connection and Signon APIs are:
OK
INVALID_PARAMETER
INTERNAL_ERROR
FUNCTION_NOT_SUPPORTED
COMMUNICATIONS_ERROR
SERVER_INVALID
USER_ID_UNKNOWN
USER_ID_REVOKED
NEW_PWD_LENGTH_LONGER_THAN_MAX
NEW_PWD_LENGTH_SHORTER_THAN_MIN
NEW_PWD_CONTAINS_CHAR_USED_THAN_ONCE
NEW_PWD_CONTAINS_ADJACENT_DIGIT
NEW_PWD_CONTAINS_REPEATED_CONSECUTIVELY
NEW_PWD_PREVIOUSLY_USED
NEW_PWD_MUST_CONTAIN_ONE_NUMERIC
NEW_PWD_CONTAINS_INVALID_CHAR
NEW_PWD_CONATINS_DISALLOWED_WORD
NEW_PWD_CONTAINS_USERID
PASSWORD_INCORRECT
PASSWORD_DISABLED_NEXT_INVALID_ATTEMPT
PASSWORD_EXPIRED
NEW_PWD_CONTAINS_CHAR_SAME_POSITION_AS_LAST
0
1
2
3
4
101
201
202
301
302
303
304
305
306
307
308
309
310
311
312
313
315
Figure 35. Return codes for the Connection and Signon APIs
205
Files have been specified with the USROPN keyword, so no connection request is
made by the VARPG run time. Pressing Sign on to server will start the
component.
206
The user can now specify the server and userID/password information. The
component will use this data to start the signon API and establish the connection
to the server. When the initial window gets notified that a connection has been
established successfully, the program accesses the customer database on the iSeries
server.
207
The program uses this dialog to get the new password and then send it to the
VARPG communications layer by invoking the VARPG_Change_Password
function. The code for all of these functions is included in the
Runtime_control_of_server_connections sample program.
208
uf
k disk
open
customl3
remote usropn
90
C
*IN90
ifeq
C* error openning the file.
C
else
C* open ok.
C
endif
*ON
209
C
*PSSR
BEGSR
C* Do error handling here...
C
ENDSR
*CANCL
where xxxx is the URL and directory that contains the applet that is to be
given permission to the security file.
c. Click the Add Permission button. Complete the Permissions dialog as
follows:
v From the Permissions combination box, choose RuntimePermission.
v From the Target combination box, choose loadLibrary.<library name>.
v In the entry field immediately to the right of the Target combination box,
change loadLibrary.<library name> to loadLibrary.fvdcjava.
v Press OK to return to the Policy Entry dialog.
d. From the Policy Entry dialog, again click the Add Permission button.
Complete the Permissions dialog as follows:
v From the Permissions combination box, choose FilePermission.
v In the entry field immediately to the right of the Target combination box,
type the name of the security file. This file is located in the ibmcom
subdirectory of your Windows directory. For example:
c:\windows\ibmcom\fvdcsec.txt
210
211
212
Reuse Scenario
You can use VisualAge RPG to modify applications that run on the server so that
they run on a PWS, access data on the host, and have a graphical user interface.
This section provides an overview of the steps involved.
Importing display files: The Import utility converts existing display files to a
graphical user interface on a PWS. After you import a display file, the record
formats are converted to user-defined parts and stored on the Imported page of the
parts catalog. You can move the parts to the parts palette as you work on the
application, and then store them in the parts catalog when you finish working on
the application until you need them again.
For example, importing the 5250 screen shown in Figure 37 results in the GUI
shown in Figure 38 on page 214. Records are converted to a group of parts, fields
are converted to entry field parts, and constants are converted to static text parts.
All command keys are converted to push button parts, and the push button labels
reflect the original command key keyword.
OOO OO OOOO
OOOOOOOOOOOOOOOOOOOOOOOOOOOOOO
Status: OOOOOOO
OOOOOOOOOOOOOOOOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOOOOOOOOOOOOOOOO
Print : B (Y,N)
Ship Via: BBBBBBBBBB
Date Entered: OOO OO OOOO
F.O.B.: BBBBBBBBBBBBBBB
Date Revised: OOO OO OOOO
Terms Code : BBBB OOOOOOOOOOOOOOO
OOO OO OOOO
Password :
Originator : OOOOOOOOOOOOOOO
Prep./Collect/Chg : B (P,C,X)
Confirm./Orig. : B (C,O)
Warehouse: BB OOOOOOOOOOOOOOOOOOOOOOOOOOOOOO
Requested by: BBBBBBBBBBBBBBB
Work Order #: 9999999
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
Cmd1 Exit Cmd3 PO Notes Cmd4 Lookup Cmd5 Material Status Cmd9 Vendor Maint.
Cmd11 Delete
Cmd15 Vendor Notes Cmd16 Vendor Quotes
213
Note: The new parts inherit the original field names, but you can rename them if
you like. Retaining the same field name improves productivity when
manipulating program logic for reuse.
You may want to customize the imported parts to take advantage of the basic
design issues discussed in Chapter 2, Planning Your Application, on page 19.
Customizing the GUI:
214
Figure 39 shows how the imported window would look if you made the following
changes to the interface:
v Replace the command keys with a menu bar and associated menu items. For
example, a Vendor menu contains actions that were originally converted to push
buttons. This gives users easy access to frequently performed actions, and
launches related windows.
v Group related information, using group box parts to provide a visual cue for
users. For example, a group box labeled Shipment Information contains entry
fields that pertain to shipment information.
v Use grouped radio buttons for information that requires a user to select from a
number of known choices. For example, only three methods of payment are
possible (prepaid, collect, charge); therefore users need to select only one radio
button to indicate the method being used. The radio buttons are in a group box
labeled Payment.
These changes take advantage of the graphical capabilities that VisualAge RPG
offers.
Reusing online help: When you reuse an application, you may want to reuse the
existing User Interface Manager (UIM) help, too. You will have to modify it
somewhat to reflect the look of the new GUI; however, it could save you the effort
required to create help from scratch.
You can customize the converted UIM help and add new types of help using the
Information Presentation Facility (IPF). You can write help for each window and
context-sensitive help for each part, and you can link the help information by
215
creating hypertext links in the help source. See Reusing UIM Help on page 222,
and Chapter 13, Tips for Creating Online Help with IPF, on page 245 for more
information.
Writing program logic: You can reuse logic written in RPG IV because the compiler
is based on that language. Simply cut-and-paste existing code for reuse.
You also have to write some additional program logic, using event-driven
programming. For every event associated with a part, there is an action subroutine
which describes how the program responds to an event. Procedural operation
codes for program control are not required; program control is implicit. Some of
the VisualAge RPG operation codes unique to VisualAge RPG applications are:
BEGACT
Begins an action subroutine
ENDACT
Ends an action subroutine
SETATR
Sets the value of a part attribute
GETATR
Retrieves the value of a part attribute
SHOWWIN
Displays a window
CLSWIN
Closes a window
Figure 40 on page 217 contains an action subroutine from a sample purchase order
application. When SHOWWIN is called from a particular window to display the
PUR570R2 window, an action subroutine is coded for the Create event to prepare
the window for the users next action.
If this is a new purchase order (#PONUM = 0), the menu items change, delete,
print, and fax are set to not respond to the MENUSELECT event. For each of the
menu items, the %setatr function is used to set the enabled attribute to 0. The
BEGACT operation code indicates the beginning of the action subroutine, and
ENDACT indicates the end of it.
216
*********************************************************************
*********************************************************************
*
* Window . . : PUR570R2 PO Header Maintenance
*
*
*
*********************************************************************
**********************************************************************
C
PUR570R2
BEGACT
CREATE
PUR570R2
c*
c*
C
if
#PONUM = 0
C
eval
%setatr(pur570r2:m2_change:enabled)=0
C
eval
%setatr(pur570r2:m2_delete:enabled)=0
C
eval
%setatr(pur570r2:m2_print:enabled)=0
C
eval
%setatr(pur570r2:m2_fax:enabled)=0
c
end
c
exsr
POCHECK
c
write
PUR570R2
C
ENDACT
*********************************************************************-
Connecting to the Host: If your application uses iSeries 400 database fields or
imports iSeries 400 display files when you are building your application, you must
define the iSeries 400 server it uses. You can communicate with the host at any
time, as long as the server logon information is appropriately defined. See the
online help for more information about defining server information.
217
Catalog only
The part is added to the Imported page in the catalog.
Catalog and palette
The part is added to the Imported page in the catalog, and the icon for
the imported part appears on the palette.
7. Choose Import.
Record Formats
The following list describes how display record formats are converted to parts.
MNUBAR
The MNUBAR record format is converted to a menu bar part that you can
drop onto a window with canvas.
PULLDOWN
The PULLDOWN record format is used with the MNUBAR record format
to create a submenu part. The PULLDOWN record format is converted to
menu item parts for the MNUBAR record format that it references.
RECORD
The RECORD record format is converted to a group of parts that you can
drop onto a window with canvas.
SFL, SFLCTL
These record formats are converted to a subfile part that you can drop onto
a window with canvas.
Constants in the SFL records are not converted.
WINDOW
The WINDOW definition record format is converted to a window with
canvas part. The WINDOW reference record format is converted to a group
of parts that you can drop onto a window with canvas.
These record formats are not converted: ERRSFL, SFLMSG, and USRDFN. The
PULLDOWN and WINDOW keywords within a subfile are not converted.
Positional Entries
The following table describes how positional entries in the DDS used to create a
display file determine how formats and fields are converted.
218
Meaning
8-16
Indicators
17
Record type
19-28
Name
29
Reference
30-34
Length
35
Keyboard shift
Converted as described in
Record Formats
Not converted
If a named field, used as the
name of the part
Not converted
Sets the data length
Converted to character
Read-only, Disabled
DFMNSWXY
Not converted
36-37
Decimals
38
Usage
39-41
Location
45-80
Keywords
Enabled
MP
Not converted
Read-only, Enabled
Constant
Creates a static text part
219
CNTFLD
The CNTFLD keyword is converted to a multiline edit part.
COLOR
The COLOR keyword determines the foreground color attribute of the
part. If there is more than one COLOR keyword, the last one is used.
COMP
The COMP keyword is used to set the comparison attributes in the parts
properties notebook.
DATE The DATE keyword is converted to a static text part.
DFT
The text associated with DFT becomes the label for the part.
v If the field that is being converted is a constant field, the DFT value is
used on the label.
v If the field that is being converted is specified on a named field, the DFT
keyword value is converted to the default text of the part.
DFTVAL
The DFTVAL keyword value is converted to the default value of the part.
DSPATR
If
v
v
v
220
RANGE
The RANGE keyword is converted to the range attribute for the part.
SFL, SFLCTL
These record formats are converted to a subfile part.
SFLPAG
Influences the initial height of the subfile part.
SNGCHCFLD
If the SNGCHCFLD keyword is used inside a PULLDOWN record, each
CHOICE keyword associated with it is converted to a menu item part on a
submenu part.
If the SNGCHCFLD keyword is used outside a PULLDOWN record, each
CHOICE keyword associated with it is converted to a radio button part.
The radio buttons are arranged horizontally with the same default space
between them. They are not grouped.
SYSNAME
The SYSNAME keyword is converted to a static text part.
TIME The TIME keyword is converted to a static text part.
USER The USER keyword is converted to a static text part.
VALUES
The VALUES keyword causes the field to be converted to a drop-down
combination box part. The values associated with the VALUES keyword
are used on the drop-down list.
WDWTITLE
The WDWTITLE keyword is used to determine the label and attributes for
a window with canvas part.
v If the title text is assigned to a program-to-system field, it is not
converted.
v If the title text is assigned to a literal field, the label for the window with
canvas part is set to this text.
WINDOW
The WINDOW definition record format is converted to a window with
canvas part. The WINDOW reference record format is converted to a group
of parts that you can drop onto a window with canvas.
No other keywords are converted.
Converting Color
Character-based computer screen entry fields are converted to entry field parts that
are color-coded.
Note: Not all displays support these colors. On VGA displays, for example, the
converted entry fields will be white.
The color of each converted entry field depends on the type and attributes defined
in the display file:
Table 7. Original and Converted Field Attributes
Field Type
I/O*
Field Attributes
GUI Attributes
ReadOnly: Off
Enabled: On
Color:
Light Yellow
Chapter 9. Reusing iSeries Applications
221
ReadOnly: On
Enabled: On
Color:
Light Green
Input
ReadOnly: Off
Enabled: On
Color:
Light Blue
Input or I/O
Protected
ReadOnly: Off
Enabled: Off
Color:
Light Red
Input or I/O
Inhibited keyboard
ReadOnly: On
Enabled: On
Color:
Medium Red
Input or I/O
ReadOnly: On
Enabled: Off
Color:
Deep Pink
222
UIM Tag
Tag Function
IPF Tag
:DL.
Definition List
:dl.
:FIG.
Figure
:fig.
:HP1.
Highlighted Phrase
:hp1.
:HP2.
Highlighted Phrase
:hp2.
Tag Function
IPF Tag
:HP3.
Highlighted Phrase
:hp3.
:HP4.
Highlighted Phrase
:hp4.
:HP5.
Highlighted Phrase
:hp5.
:HP6.
Highlighted Phrase
:hp6.
:HP7.
Highlighted Phrase
:hp7.
:HP8.
Highlighted Phrase
:hp8.
:HP9.
Highlighted Phrase
:hp9.
:LINES.
Lines
:lines.
:LI.
List Item
:li.
:LP.
List Part
:lp.
:NT.
Note
:nt.
:OL.
Ordered List
:ol.
:P.
Paragraph
:p.
:PARML.
Parameter List
:parml.
:P
Parameter Description
:pd.
:PT.
Parameter Term
:pt.
:SL.
Simple List
:sl.
:UL.
Unordered List
:ul.
:XMP.
Example
:xmp.
&.
Ampersand (&)
&.
&COLON.
Colon (:)
&colon.
&period.
Period (.)
&period.
&SLR.
&slr.
Function
IPF Tag
:CIT.
Citation
:hp5.
:H1.
Heading
:h2.
:H2.
Heading
:h3.
:H3.
Heading
:h4.
:H4.
Heading
:h5.
:HELP.
Heading
:help.
:ISCH.
Index item
:i1.
:ISCHSYN.
Index synonym
:isyn.
:PK.
Programming keyword
:hp2.
Default programming
keyword
:hp7.
223
Function
IPF Tag
:PV.
Programming variable
:hp5.
Function
:HP0.
No highlighting
:PC.
Paragraph continuation
:RT.
Reverse text
:XH1.
:XH2.
:XH3.
:XH4.
224
225
226
Figure 41. The VisualAge RPG Source and Debug Session Control Windows
When the debugger starts, it searches for the VisualAge RPG source member and
then displays it in the Source window. Once the source is displayed, you can
perform debugging tasks.
Note: The current position of the executing program is indicated by a highlighted
line number. Here, the first line of the source member is highlighted.
227
To correct this problem, make sure that the VisualAge RPG source code (.VPG file)
resides on your workstation.
This returns you to the debug session. When the assembly source view is
displayed again, press the R key to resume execution of the program. When the
DLL is loaded, the system displays a message and the name of your application is
displayed in the control window. You can now click on the application to get the
source to display. If the source does not display this means you have lost or
deleted the source.
228
If your application uses the START opcode to start another component, you will
have to use this procedure to load the other component DLL. This will allow you
to set breakpoints within the other components.
Setting a Breakpoint
You can control how your program executes by setting breakpoints. A breakpoint
stops the execution of your program at a specific location or when a specific event
occurs. To set a breakpoint, move the cursor to the line number that you would
like to break at and double-click mouse button 1. The debugger highlights the line
number with a red mark. You can repeat this process as many times to mark all
the necessary lines that you would like to break at. Figure 45 on page 230
illustrates the way the screen looks with several breakpoints set. You can view all
of your breakpoints in the Breakpoints List window.
229
230
231
You can also resume execution of the program in different ways. Do any of the
following:
v Press the letter R
v Move the mouse to the Run pull-down menu, then select Run
v Move the mouse to the run icon on the tool bar and single-click mouse button 1
Icon
Function
Step over
Executes the current (highlighted) line in the program, but does not enter
any called function.
Step into
Executes the current (highlighted) line in the program and enters any
called program or function.
Step debug
Executes the current (highlighted) line in the program. The debugger steps
over any function for which debug information is not available, and steps
into any function for which debugging information is available.
Step return
Automatically executes the lines of code up to, and including, the return
statement of the current function.
Run
232
Halt
After you press Enter, the VisualAge RPG field or structure is displayed in the
Program Monitor window, as shown in Figure 51 on page 234.
233
234
235
236
Setting Fonts
There are many options available in the debugger that allow you to customize
your debug session. For example, you can set your fonts. Figure 54 displays the
font window. To display the font window, select Options>Window settings>Fonts.
In the font window, select the desired font, style, and size, then select OK. The font
changes display in your debugging session.
237
238
Edit Codes
Several edit codes are supported to format the data into predefined formats. These
formats insert the proper thousand and decimal separators, and determine how a
negative number is displayed by providing a fixed or floating minus sign or the
CR (Credit) symbol.
You can optionally specify asterisk protection or floating currency symbol with the
edit codes. If you specify asterisk protection, an asterisk is displayed with each
zero that is suppressed. If you specify floating currency symbol, the symbol
appears to the left of the first significant digit. The symbol does not display on a
zero balance when an edit code is used that suppresses the zero balance.
The actual characters to be used for the thousand and decimal separators and
currency symbol are determined by the operating system when the application is
run.
239
The following table summarizes the supported edit codes and the editing they
provide, and provides examples.
Note: The compiler does not support user-defined edit codes. User-defined edit
codes are defined and stored on the AS/400 system, and are not available to
VisualAge RPG programs.
Table 11. VisualAge RPG Edit Codes
Edit ComCode mas
Decimal
Point
Sign for
Positive Number Negative
Zero
Negative Balance Example
Number Example balance
none No
Yes
Yes
0123456789
0123456789-
Yes
Yes
No Sign
124,567.89
124,567.89
Yes
Yes
No Sign
124,567.89
124,567.89
No
Yes
No Sign
124567.89
124567.89
No
Yes
No Sign
124567.89
124567.89
Yes
Yes
CR
124,567.89
124,567.89CR
Yes
Yes
CR
124,567.89
124,567.89CR
No
Yes
CR
124567.89
124567.89CR
No
Yes
CR
124567.89
124567.89CR
Yes
Yes
-(minus)
124,567.89
124,567.89-
Yes
Yes
-(minus)
124,567.89
124,567.89-
No
Yes
-(minus)
124567.89
124567.89-
No
Yes
-(minus)
124567.89
124567.89-
Yes
Yes
-(floating minus)
124,567.89
-124,567.89
Yes
Yes
-(floating minus)
124,567.89
-124,567.89
No
Yes
-(floating minus)
124567.89
-124567.89
No
Yes
-(floating minus)
124567.89
-124567.89
Y (2.)
Z (3.) No
.00
.00
.00
.00
.00
.00
.00
.00
1984-12-25
No
No Sign
1234567
1234567
Notes:
1. All edit codes suppress leading zeros
2. The Y edit code is used to date fields. The date field should be defined as a
numeric field. The output of this edit code is in the form nnnn-nn-nn. This
format cannot be changed. The date separator character is determined by the
operating system when the application is run.
3. The Z edit code removes the + or sign.
Edit Words
You can use edit words if none of the supplied edit codes meets your editing
requirements. An edit word is a template that is applied to your data before it is
placed in the part. With edit words you can specify:
v Suppression of leading zeros
v Leading asterisks
v The fixed/floating currency symbol
v The position of thousands and decimal separators.
240
Note: When you use edit words, make sure that you specify the currency, decimal,
and thousands symbols correctly. If the symbols do not match the edit word,
you will get improperly formatted output but no runtime error. These
symbols are replaced by the runtime operating system values when the
application is run.
=
=
=
=
x
$
,
.
A zero stops zero suppression. The zero is itself a digit position. Any zeros
in the data field to the right of the stop-zero-suppression character are
displayed. Each zero that is suppressed is replaced by a blank.
Asterisk
An asterisk instead of a zero can be used as a stop-zero-suppression
character. This is called asterisk protection, and each zero that is
suppressed is replaced by an asterisk. Any asterisks or zeros to the right of
the stop-zero-suppression character are constants, and will be displayed
as-is.
Currency Symbol
If you code a currency symbol immediately to the left of the
stop-zero-suppression character, a currency symbol is inserted in the
position to the left of the first significant digit. It is called a floating
currency symbol when it is used in this manner. If you code a currency
symbol in the farthest left position of the edit word, it is fixed and is
displayed in the same location. It is called a fixed currency symbol.
Thousand Separator and Decimal Separators
Thousand and decimal separators are displayed in the same relative
positions in which they are coded in the edit word. All other characters are
displayed if they are to the right of significant digits in the edit word. If
they are to the left of the high-order significant digit in the edit word, they
are blanked out or replaced by an asterisk if asterisk protection is being
used.
Chapter 11. Editing Output
241
242
243
To be sure that these files are found at run time, use the Current directory string
(.\): a dot and a backslash followed by the file name. At run time, the file is found
in the current directory from which the application is run.
For example, in the properties notebook for a graphic push button, specify the
following as the file name for an icon named EXIT.ICO, so that it will be found at
run time in the current directory.
.\\EXIT.ICO
244
Using IPF
The source for VisualAge RPG application help modules is in IPF format. IPF
enables you to create online information, specify how it will appear on the screen,
connect various parts of the information, and provide help information that can be
requested by the user. IPF features include:
v A tagging language that formats text, provides ways to connect information
units, and customizes windows
v A compiler that creates online documents and help windows
v A viewing program that displays formatted online documents
245
246
247
248
There are many tools on the market available, commercially and as shareware, that
provide complete help authoring environments.In addition, there a several books
available that describe how to use the Help Compiler workshop. Many of these
books include a CD-ROM with the help compiler workshop, such as the Microsoft
Windows 95 Help Authoring Kit ISBN1-55615-892-0.
Steps to creating Windows help
The basic steps to follow to use Windows help in your application are:
1. Establish the resource id for each part that will have help.
2. Write the help text.
3. Create the help project file.
4. Compile the help file.
249
During the build process, VisualAge RPG generates a resource ID table entry for
each part that you have created help for using the Help text menu item from the
parts popup menu. The Windows help engine uses this table to determine the
resource ID for a part so it can display the correct help. You must create the help
text for each part in this way for the part to have Windows help. Currently,
VisualAge RPG does not create this table entry automatically for you. If you do
follow this process, no help is displayed and no error message is generated.
250
You can have several topics in a single topic file. Each topic must begin on a new
page. Once you complete typing the help text, save your topic file in RTF format.
251
252
253
Where:
<title> Names the HelpSet. This corresponds to the title of the help window.
<homeID>
Specifies the name of the (default) ID that is displayed when the help is
called if an ID is not explicitly specified.
<data>
Specifies the path to the data used by the navigator. In our example, this is
the TOC view. The TOC file name is uppercase and the xml extension is
lowercase. The TOC file must exist in your help directory.
254
url="help/welcome.htm" />
url="help/catalog.htm" />
url="help/browse.htm" />
url="help/new.htm" />
url="help/top10.htm" />
url="help/search.htm" />
target Specifies the part ID for the VARPG part. The part ID is automatically
assigned to the part by the GUI Designer. You can retrieve it from the
parts properties notebook.
Specifies the path to the HTML topic file containing the help text. The path
can be relative or absolute.
url
text="Welcome" target="11"/>
text="Help" target="22"/>
text="Browse" target="14"/>
text="New" target="19"/>
text="Top 10" target="20"/>
text="Search" target="21"/>
</tocitem>
</toc>
Where:
tocitem
The first TOC entry specifies the title for your table of contents. (You can
nest TOC entries within a higher-level entry.)
text
255
target Specifies the ID of the HTML topic to display when the user chooses this
entry in the TOC. The ID corresponds to the part ID identified in the map
file.
Where the SOURCE_FILE_NAME part is the name specified in the Source file field
on the Save as Application - VisualAge RPG window. The file name must end with
HS and be in uppercase. The jar extension is lowercase.
256
Issue the command from the top most directory containing your help hierarchy.
For example, if your help directory structure is as follows:
javahelp (directory)
Map.jhm
CATALOG.hs
VIDCTOC.xml
help (subdirectory)
browse.htm
catalog.htm
new.htm
search.htm
top10.htm
welcome.htm
Copy the resultant jar file into the RT_JAVA subdirectory for your project. Build
and run the project with the Java option (Build>Java or Run>Java, respectively.).
257
258
259
5.
6.
7.
8.
Warning
Use this type of message when the user can continue the original
request without modification, but should be aware of the existence of
some situation.
Type the message text in the Message field.
If you want to provide help for the message, type it in the Message Help
field.
When you create message help and use the DSPLY operation code to display
the message, a Help push button will appear at the bottom of the message
window. When the user clicks on this push button, the help text will be
displayed as additional information.
Select the Moveable check box if you want the user to be able to move the
message to the background and continue with other tasks before taking action
with the message.
From the Buttons drop-down box, select what combination of push buttons
you want to appear at the bottom of the message window:
Choice Buttons That Will Appear
abortRetryIgnoreButton
Abort, Retry and Ignore
okButton
OK
okCancelButton
OK and Cancel
retryCancelButton
Retry and Cancel
260
yesNoButton
Yes and No
yesNoCancelButton
Yes, No and Cancel
9. Select a default push button by selecting the Button 1, Button 2, or Button 3
radio button. When the message window is displayed and the user presses the
Enter key, the action associated with the default push button is performed.
For example, if you selected enterCancelButton from the Buttons drop-down
and you want the default push button to be Cancel, you would select the
Button 2 radio button.
10. Select Save to keep the message, or Cancel to discard it.
Note: Message identifiers (message IDs) range from MSG0001 to MSG9999, and
are assigned by VisualAge RPG. When all message IDs in the range are
used, VisualAge RPG posts an error when you try to create a new message,
and no new message can be created until you delete one. After you delete a
message, you can create a new message that uses the ID of the deleted one.
Editing a Message
To edit a message:
1. Select ProjectDefine messages from the GUI Designer. The Define Messages
window appears.
2. Select a message from the list that is displayed. If you cannot find the message
you want, follow the instructions in Finding a Message.
3. Choose Edit from the Define Messages window. The Edit Message window
opens, displaying the message you selected.
4. Change the message alias, type, text, help or message window information.
5. Select Save to keep your changes, or Cancel to discard them.
Deleting a Message
To delete a message:
1. Choose ProjectDefine messages from the GUI Designer. The Define Messages
window opens.
2. Select a message from the list that is displayed. If you cannot find the message
you want, follow the instructions in Finding a Message.
3. Choose the Delete push button.
Finding a Message
Here are some tips for finding a message:
v If you know what the exact message ID is, use the Sort by Message ID feature
of the Define Messages window. The messages appear in ascending order of
message ID.
v If you know what type of message you are looking for, use the Sort by Type
feature of the Define Messages window. The messages are sorted in ascending
order of message ID within the following groups:
1. Messages you can set at run time:
a. Information
b. Warning
c. Action
d. Critical
Chapter 16. Working with Messages
261
The fields CUSNO and FILE are defined elsewhere in the program. Assume that
the message text for message *MSG0001 is:
Customer number %1 was not found in file %2.
To display the message with the DSPLY operation and have substitution done,
code the following on the C specification:
CSRN01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq
C
notFound
DSPLY
rc
9 0
For more information on the DSPLY operation code, see the VisualAge RPG
Language Reference, SC09-2451-04.
262
Make sure that you edit only the text that appears after the colon ( : ) in the record
layout.
The first record identifies the message prefix, and the following records each
represent a message in the application.
Each message has a message prefix, MSG; a four-digit identifier or ID number; and
a letter describing the type of message. In our example, message number 1 is an
information message, and message number 2 is a warning message.
Do not do any of the following:
v Modify the message ID. Changing message IDs will cause unpredictable results.
Without a message ID, your message cannot be displayed.
v Add a message. The message style will not be defined, and the message will
never display in the Define Messages window.
v Delete a message. The Define Messages window will still display everything
about the message except its message text.
PB1
SETATR
*MSG0001
Label
If the message number cannot be found in the component message file, then the
application searches the message file indicated by the *component MsgFile
attribute for the message number. If the message number does not exist in either
message file, then the message identifier (in this example, MSG0001) appears as the
label text.
263
264
Linking Parts
The following parts can be linked using VisualAge RPG:
v Check box
v Entry field
v Image
v List box
v Media
v Media panel
v Slider
v Timer
A part that notifies another part when it changes is called the source part, and the
part that is notified of this change is called the target part.
One way to set up communication between a source part and a target part is to
use the Link page of the source parts properties notebook. In the fields provided,
type the name of the target part and the name of the window in which it resides.
If you want the target to issue a Link event when it is notified by the source part,
select the Enable notify target check box.
Alternatively, you can set up the communication link by setting the AddLink
attribute and the target in the form WindowName|PartName. If you want the target
to issue a Link event, set the AllowLink attribute to 1. Figure 59 on page 266
265
shows sample code used to link a media panel part, MMP1, to a media part,
AUDIO1.
*
C
C
MMP1
MMP1
SETATR
SETATR
WIN2|AUDIO1 AddLink
1
AllowLink
Note: You can set only one link for a source part in the GUI Designer, but you can
set multiple links in your code.
AppName
This is the name of the server application: SERVER.EXE.
Topic
This is the name of the server component, followed by a vertical bar, followed by
the component instance name. For VisualAge RPG, in most cases the component
name is the same as the component instance name, and also the same as the
executable name. For this example, the component name is SERVER|SERVER.
Item
This is the name of the server part. For VisualAge RPG programs, this is the
window name, followed by a vertical bar, followed by the part name. In this
example, the item attribute value is WINDOW_S|ENTRY_S.
266
DDEAddLink
This is the name of the client part. It consists of the window name, followed by a
vertical bar, followed by the part name. In this example, the DDEAddLink
attribute is WINDOW_C|STTEXT_C.
DDEMode
Set DDEMode to 1 to begin the conversation and initiate the hot link between the
server and the client. To terminate the conversation, set DDEMode to 2. This
signals the Terminate event to the client application.
267
#include <stdio.h>
*
/*The following two lines are required only if you compile
/*the OBJ with the IBM C/C++ compiler. These lines */
/*are not required if the function is exported from a DLL.
int _CRT_init(void);
void _CRT_term(void);
*
/* print the str and age parameters to a file */
void MYFUNC(char *str, int *age) {
FILE *fp;
int j;
*
/*The following line is required only if you compile
/*the OBJ with the IBM C/C++ compiler. This line
*/
/*is not required if the function is exported from a DLL.
_CRT_init();
*
fp=fopen("myfunc.log", "a");
*
/* print the character data to a file*/
for (j=0; j<10; ++j) {
fprintf(fp, "%c", str[j]);
}
*
/* if an age is given, print the age */
if ( age == NULL ) {
fprintf(fp, "no age is given\n");
} else {
fprintf(fp, "num = %d\n", *age);
}
*
fclose(fp);
*
/*The following line is required only if you compile
/*the OBJ with the IBM C/C++ compiler. This line
*/
/*is not required if the function is exported from a DLL.
_CRT_term();
}
*/
*/
*/
*/
*/
*/
268
*
Dwilma
Dage
C
*inzsr
C
C
C
C
C
s
s
80a
inz(mydata)
9b 0 inz(32)
begsr
callb
parm
parm
seton
endsr
MYFUNC
wilma
age
lr
s
s
s
*
procptr inz(%paddr(MYFUNC))
80a
inz(mydata)
9b 0 inz(32)
begsr
callb
parm
parm
seton
endsr
p2
wilma
age
lr
s
s
s
*
procptr inz(%paddr(MYFUNC))
80a
inz(mydata)
9b 0 inz(32)
begsr
callb
parm
parm
seton
endsr
p2
wilma
*OMIT
lr
269
Columns
Description
6
7-21
24-25
PR
44-80
keyword
Use the CLTPGM keyword with the system name of the program as a parameter.
If the program expects parameters, use one definition specification for each
parameter immediately after the PR definition specification. These definition
specifications should consist of the name, length, and type of parameter. Specify
the precision of numeric parameters. Always specify the VALUE keyword. You can
also specify the ASC, DATFMT, DESC, DIM, LIKE, NOOPT, OPTIONS, and
TIMFMT keywords on your parameter definitions.
Figure 65 defines pgm1 to VisualAge RPG. One parameter can be passed to the
program.
D pgm1
D parm1
PR
20A
CLTPGM(testprog)
VALUE
Figure 65. Specifying definition specification parameters when calling local programs
In Figure 66, the CALLP operation code calls pgm1 with parameters f1d1 and 22.4.
C
CALLP
pgml(f1d1:22.4)
270
D test1
C
D test2
C
*
*To start a component:
C
START
*
*To start a component:
C
START
*
*Starts local program testprog.exe:
C
START
component
testprog
LINKAGE(*CLIENT)
xxx
test1
test2
S
S
START
START
20A
20A
LINKAGE(*CLIENT)
name1
name2
Figure 68. Defining variable names for the START operation code
START can still have a PLIST specified in the result field, or it can be followed by
a list of PARMS. These PARMS are passed to the component or local program.
271
Starting a Component
The START operation code starts a new component in the application. When the
operation is performed, both the starting and the started components, together
with any other active components in the application, are ready to receive user
actions on all the parts currently enabled by all the components.
The START operation code is similar to the CALL operation code in the following
ways:
v Parameters can be passed to a component.
v Parameters are mapped to the parameters in the *ENTRY PLIST of the target
component.
v In the source component, factor 2 of the PARM operation code is copied to the
result field of the same PARM operation code. When control returns to the
source component, the result field is copied to factor 1.
v In the target component, the result field is copied to factor 1. When control
returns to the source component, factor 2 is copied to the result field if the target
component completes a successful startup.
v No checks or conversions are performed on the parameters.
The START operation code is different from the CALL operation code in the
following ways:
v The terms called and calling are used with the CALL operation code. A called
program is a program whose execution is requested by another program. A
calling program is a program that requests the execution of another program.
With the START operation code, the terms target (called) and source (calling) are
used.
v CALL invokes a program, executes it, then returns back to the calling program
with factor 1, factor 2, and the result field copied as described above. START
initializes a component, executes its *INZSR, and returns to the source
component with factor 1, factor 2, and the result field copied as described above.
The difference is that with the START operation code, factor 2 in the target
program is copied to the result field at the end of the *INZSR (if *INZSR is
successful), not at the end of the program.
v Once the START operation has finished initializing the target component, the
action subroutine in the source component continues executing, and the target
component remains active with its action subroutines enabled to receive events.
v Since parameters are passed by address, any parameters that are passed can be
accessed by both the source and target components after the initial START has
ended. This means that both the source and target components can continue to
share information using the parameter fields.
Terminating a Component
The STOP operation code terminates the execution of a component. If you do not
specify the component name in factor 2, the component that is currently running is
terminated. When a component is terminated, any child components that it may
have started are terminated first.
272
REMPGM
MYLIB/LOOKUP
SERVER01
273
*********************************************************************
*
*
* Program ID . . : rcallex.vpg
*
*
*
* Description . : Code segment to call a remote program on the
*
*
AS/400.
*
*
*
*********************************************************************
*
* REMPGM is the remote program alias name
D as400pgm
S
6A
INZ(REMPGM) LINKAGE(*SERVER)
* The following variables are parameters that are passed to the
* remote program
*
student_id
- input
*
name
- output
D student_id
S
6S 0 INZ(32533)
D name
S
20A
*********************************************************************
*
*
* Window . . : WIN1
*
*
*
* Part . . . : PSB0000C
*
*
*
* Event . . : PRESS
*
*
*
* Description: Call a remote program on the AS/400 to get the name *
*
of the person associated with a student id.
*
*
*
*********************************************************************
*
C
PSB0000C
BEGACT
PRESS
WIN1
C
CALL
as400pgm
C
PARM
student_id
C
PARM
name
C
ENDACT
Note: If the program on the iSeries server contains a workstation file, it will fail
when the system attempts to open it. Since the remote call command is done
through the DDM server, the display device is unknown to workstation data
management. A technique you can use is to create the workstation file on
the iSeries server with the Display Device value set to the name of the
session (OMXxxxx) and set the Maximum Number of Devices parameter to
a value greater than 1. This will allow parameters to be passed to the iSeries
server program. Do not try to explicitly acquire the session with an ACQ
statement. This will cause a conflict to occur which results in an error. You
still cannot acquire any 5250 emulator display device on your workstation,
because it will result in a deadlock that can only be ended by rebooting the
workstation.
274
Prototyped Calls
To call a subprocedure, you must use a prototyped call. You can also call any
program or procedure that is written in any language by using a prototyped call. A
prototyped call is one where the call interface is checked at compile time through
the use of a prototype. A prototype is a definition of the call interface. It includes
the following information:
v Whether the call is bound (procedure) or dynamic (program)
v How to find the program or procedure (the external name)
v The number and nature of the parameters
v Which parameters must be passed, and which are optionally passed
v The data type of the return value, if any (for a procedure)
The prototype is used by the compiler to call the program or procedure correctly,
and to ensure that the caller passes the correct parameters. Figure 70 shows a
prototype for a procedure FmtCust, which formats various fields of a record into
readable form. It has two output parameters.
* Prototype for procedure FmtCust (Note the PR on definition
* specification.) It has two parameters.
D FmtCust
PR
D Name
100A
D Address
100A
275
CALLP
FmtCust(RPTNAME : RPTADDR)
Using prototyped calls you can call (with the same syntax):
v Programs that are on the system at run time
v Exported procedures in other modules
v Subprocedures in the same module
In order to format the name and address properly, FmtCust calls NumToChar to
convert the customer number to a character field. Because FmtCust wants to use
the return value, the call to NumToChar is made within an expression. Figure 73
shows the call.
*-------------------------------------------------------------* CUSTNAME and CUSTNUM are formatted to look like this:
*
A&P Electronics
(Customer number 157)
*-------------------------------------------------------------C
EVAL
Name = CUSTNAME +
C
+ (Customer number
C
+ %trimr(NumToChar(CUSTNUM)) + )
The use of procedures to return values, as in the above figure, allows you to write
any user-defined function you require. In addition, the use of a prototyped call
interface opens up a number of options for parameter passing.
v Prototyped parameters can be passed in several ways: by reference, by value (for
procedures only), or by read-only reference. The default method for RPG is to
pass by reference. However, passing by value or by read-only reference gives
you more options for passing parameters.
v If the prototype indicates that it is allowed for a given parameter, you may be
able to do one or more of the following:
Pass *OMIT
Leave out a parameter entirely
Pass a shorter parameter than is specified (for character and graphic
parameters, and for array parameters)
276
Procedure Considerations
v You cannot define return values for a main procedure. Parameters must be
passed by value.
v A main procedure is only contained within an EXE. you specify that its
parameters be passed by value.
v Any of the calculation operations may be coded in a subprocedure. However, all
files must be defined globally, so all input and output specifications must be
defined in the main source section. Similarly, all data areas must be defined in
the main procedure, although they can be used in a subprocedure.
v The control specification can only be coded in the main source section since it
controls the entire module.
v A subprocedure can be called recursively. Each recursive call causes a new
invocation of the procedure to be placed on the call stack. The new invocation
has new storage for all data items in automatic storage, and that storage is
unavailable to other invocations because it is local. (A data item that is defined
in a subprocedure uses automatic storage unless the STATIC keyword is
specified for the definition.)
The automatic storage that is associated with earlier invocations is unaffected by
later invocations. All invocations share the same static storage, so later
invocations can affect the value held by a variable in static storage.
v Exception handling within a subprocedure differs from that in a main procedure
primarily because there is no default exception handler for subprocedures.
Situations where the default handler would be called for a main procedure result
in the abnormal end of the subprocedure.
v VisualAge RPG procedure names are in uppercase. When calling these
procedures, make sure that the case matches that of the procedure.
Procedure Implications
As a programmer, you have the have the option of producing three possible target
objects:
v A VisualAge RPG DLL (contains GUI operation codes)
v A utility DLL which contains only RPG subprocedures that do not include any
GUI operation codes
v An RPG EXE which does not contain any GUI operation codes.
277
EXE Considerations
v An EXE is built when the keyword EXE is provided on the control specification.
v The EXE consists of procedures only.
All subroutines (BEGSR) must be local to a procedure. The EXE must contain a
procedure whose name matches the name of the source file. This will be the
main entry point for the EXE (i.e. the main procedure).
v There are no GUI operation codes allowed in the source.
This includes START, STOP, SETATR, GETATR, %SETATR, %GETATR,
SHOWWIN, CLSWIN and READS. DSPLY can be used.
v *inzsr and *termsr are not permitted.
v *ENTRY parms are not permitted.
If there are entry parameters, they are specified on the parameter definition for
the main procedure, and they must be passed in by VALUE (the VALUE
keyword must be specified for each parameter).
v The EXPORT keyword is not allowed on the Begin P specification.
v Exception handling differs from the VRPG DLL. The default exception handler is
never invoked from an EXE. If an exception occurs in the EXE, and there is no
error indicator or *PSSR, an exit() is performed and information about the
exception is written to the FVDCERRS.LOG file.
278
*JAVA identifies the object as a Java object. Class_name specifies the class of the
object. It must be a character literal, and the class name must be fully qualified.
The class name is case sensitive.
For example, to declare a field that will hold an object of type BigDecimal:
D bdnum
CLASS(*JAVA:java.math.BigDecimal)
CLASS(*JAVA:java.lang.String)
Note that both class names are fully qualified and that their case exactly matches
that of the java class.
Fields of type O cannot be defined as subfields of data structures. It is possible to
have arrays of type O fields, but tables of type O are not allowed because they
have to be preloaded at run time.
The following keywords cannot be used with the CLASS keyword:
279
280
char[]
graphic or unicode
boolean
indicator (N)
byte[]
byte
integer (3I)
int
integer (10I)
short
integer (5I)
long
integer (20I)
float
float (4F)
double
float (8F)
any object
object (O)
Zoned, Packed, Binary, and Unsigned data types are not available in Java. If you
pass a Zoned, Packed, Binary, or Unsigned field as a parameter, the compiler will
do the appropriate conversion, but this will most likely result in truncation and/or
loss of precision.
If the method you are calling is a VARPG-generated method, meaning that
*JAVARPG has been specified as the first parameter of the EXTPROC keyword,
then Packed, Zoned, Binary, and Unsigned data types can be specified as the data
type of parameters and returned values. Methods generated from code originally
written in Java cannot use Packed, Zoned, Binary, and Unsigned data types on the
prototype for parameters or return values.
When calling a method, the compiler will accept arrays as parameters if the
parameter is prototyped using the DIM keyword. Otherwise, only scalar fields,
data structures, and tables will be accepted.
Currently, you cannot call methods which expect the following Java data types or
which return values of these types: byte, char, and long
If the return value of a method is an object, then you must provide the class of the
object by coding the CLASS keyword on the prototype. The class name specified
will be that of the object being returned. Use the EXTPROC keyword to specify the
class of the method being called.
If the method being called is a static method, then you must be specify the STATIC
keyword on the prototype.
In Java, the following data types can only be passed by value:
byte
int
short
long
float
double
Parameters of these types must have the VALUE keyword specified for them on
the prototype.
If the method you are calling is a VARPG-generated method, meaning that
*JAVARPG has been specified as the first parameter of the EXTPROC keyword,
then these data types can be passed by reference and the VALUE keyword is not
required.
Note that objects can only be passed by reference. The VALUE keyword cannot be
specified with type O. Since arrays are seen by Java as objects, parameters
mapping to arrays must also be passed by reference. This includes byte arrays.
Example 1
The Java Integer class contains a static method called toString, which accepts an int
parameter, and returns a String object. It is declared in Java as follows:
String
Integer.toString(int)
281
D tostring
D
D
D
D
D
num
PR
EXTPROC(*JAVA:
java.lang.Integer:
toString)
CLASS(*JAVA:java.lang.String)
STATIC
10I 0 VALUE
Example 2
The Java Integer class contains a static method called getInteger, which accepts
String and Integer objects as parameters, and returns an Integer object. Is is
declared in Java as follows:
Integer Integer.getInteger(String, Integer)
PR
O
O
EXTPROC(*JAVA:
java.lang.Integer:
getInteger)
CLASS(*JAVA:java.lang.Integer)
STATIC
CLASS(*JAVA:java.lang.String)
CLASS(*JAVA:java.lang.Integer)
Example 3
The Java Integer class contains a method called shortValue, which returns the short
representation of the Integer object used to invoke the method. It is declared in
Java as follows:
short shortValue()
PR
5I 0 EXTPROC(*JAVA:
java.lang.Integer:
shortValue)
The STATIC keyword is not specified because the method is not a static method.
The method takes no parameters, so none are coded.
The returned value is specified as 5I, which maps to the Java short data type.
282
Example 4
The Java Integer class contains a method called equals, which accepts an Object as
parameter and returns a boolean. It is declared in Java as follows:
boolean equals(Object)
PR
N
O
EXTPROC(*JAVA:
java.lang.Integer:
equals)
CLASS(*JAVA:java.lang.Object)
The returned value is specified as N, which maps to the Java boolean data type.
Creating Objects
In order to call a non-static method, an object is required. The class of the object
must be the same as the class containing the method. Objects are instantiated, or
created, by calling the class constructor. The class constructor is not a static
method, but it does not require an object to call it. The special method name
*CONSTRUCTOR is used when prototyping a constructor.
For example, in order to construct a BigDecimal object from a float value, the
constructor that expects a float parameter must be called as follows:
BigDecimal(float)
PR
4F
EXTPROC(*JAVA:
java.math.BigDecimal:
*CONSTRUCTOR)
CLASS(*JAVA:java.math.BigDecimal)
VALUE
Note that the parameter must be passed by value because it maps to the Java float
data type.
283
*
*
*
*
D bdcreate1
PR
O
EXTPROC(*JAVA:
D
java.math.BigDecimal:
D
*CONSTRUCTOR)
D
CLASS(*JAVA:java.math.BigDecimal)
D
str
O
CLASS(*JAVA:java.lang.String)
*
*
Prototype the BigDecimal constructor that accepts a double
*
parameter. 8F maps to the Java double data type and so must
*
be passed by VALUE. It returns a BigDecimal object.
*
D bdcreate2
PR
O
EXTPROC(*JAVA:
D
java.math.BigDecimal:
D
*CONSTRUCTOR)
D
CLASS(*JAVA:java.math.BigDecimal)
D
double
8F
VALUE
*
*
Define fields to store the BigDecimal objects.
*
D bdnum1
S
O
CLASS(*JAVA:java.math.BigDecimal)
D bdnum2
S
O
CLASS(*JAVA:java.math.BigDecimal)
*
*
*
*
*
*
*
D makestring
PR
O
EXTPROC(*JAVA:
D
java.lang.String:
D
*CONSTRUCTOR)
D
CLASS(*JAVA:java.lang.String)
D
bytes
10A
*
* Define a field to store the String object.
*
D string
S
O
CLASS(*JAVA:java.lang.String)
*
* Prototype the BigDecimal add method. It accepts a BigDecimal object
* as a parameter, and returns a BigDecimal object (the sum of the parameter
* and of the BigDecimal object used to make the call).
*
D add
PR
O
EXTPROC(*JAVA:
D
java.lang.BigDecimal:
D
add)
D
CLASS(*JAVA:java.math.BigDecimal)
D
bd1
O
CLASS(*JAVA:java.math.BigDecimal)
*
* Define a field to store the sum.
*
D sum
S
O
CLASS(*JAVA:java.math.BigDecimal)
D
D double
S
8F
INZ(1.1)
D fld1
S
10A
284
MOVEL
mystring
fld1
10
C*
C*
C
C*
C*
C*
C*
C
C*
C*
C*
C*
C
C*
C*
C*
C*
C*
C*
C*
C*
C*
C
C*
C*
string = makestring(fld1)
bdnum1 = bdcreate1(string)
bdnum2 = bdcreate2(double)
Example 2
This example shows how to perform a TRIM in Java by using the trim() method as
an alternative to the VARPG %TRIM built-in function. The trim() method in the
String class is not a static method, so a String object is needed in order to call it.
*
* Define a field to store the String object we wish to trim
*
D str
S
O
CLASS(*JAVA:java.lang.String)
*
* Prototype the constructor for the String class. The
* constructor expects a byte array.
*
D makestring
PR
O
EXTPROC(*JAVA:
D
java.lang.String:
D
*CONSTRUCTOR)
D
CLASS(*JAVA:java.lang.String)
D
parm
10A
D
*
* Prototype the String method getBytes which converts a String to a byte
* array. We can then store this byte array in an alpha field.
*
D makealpha
PR
10A
EXTPROC(*JAVA:
D
java.lang.String:
D
getBytes)
*
* Prototype the String method trim. It doesnt take any parameters,
* but since it is not a static method, must be called using a String
* object.
*
D trimstring
PR
O
EXTPROC(*JAVA:
D
java.lang.String:
D
trim)
*
D fld
S
10A
INZ(
hello
)
285
str = makestring(fld)
str = trimstring(str)
fld = makealpha(str)
Static methods are called in the same way, except that an object is not required to
make a call. If the makealpha() method above was static, the call would look like:
C
EVAL
fld = makealpha()
If the method does not return a value, use the CALLP operation code.
Additional Considerations
The compiler will not attempt to resolve classes at compile time. If a class cannot
be located at run time, a runtime error will occur. It will indicate that an
UnresolvedLinkException object was received from the Java environment.
The compiler does no type checking of parameters at compile time. If there is a
conflict between the prototype and the method being called, an error will be
received at run time.
It is very important that *JAVARPG be specified as the first parameter of
EXTPROC if the method being called is a non VARPG-generated method. If this is
not done, it is likely that one of the above two error situations will occur.
286
287
IF
...
RETURN
ELSE
...
RETURN
ENDIF
x = 1
1
0
IF
...
RETURN
ELSE
...
ENDIF
RETURN
x = 1
1
288
%mousex
%mousey
IFEQ
ANDEQ
...
ENDIF
x
y
IF
%mousex = x AND
%mousey = y
...
ENDIF
x
x
SELECT
WHENEQ
RETURN
WHENEQ
RETURN
OTHER
RETURN
ENDSL
y
1
z
2
0
289
C
C
C
C
C
C
C
x
x
SELECT
WHENEQ
RETURN
WHENEQ
RETURN
ENDSL
RETURN
y
1
z
2
0
In general, a RETURN operation should be coded for all possible code paths
of a subprocedure, otherwise the Java compiler may report errors.
19. Arrays cannot be passed by value to subprocedures.
Runtime Differences
Because of differences between the Windows and Java environments, an
application may run differently under Java than it does under Windows. The
following areas are affected:
1. The %SCAN builtin function will return an integer result. In Windows, it
returns an unsigned result.
2. The truncate numeric build option is unreliable and should not be depended
upon.
3. When an I/O exception occurs, the user will not be given the option to retry
the operation.
4. Data structures are not treated as one large character field when the Java
application is running. This may cause unexpected results if they are used as
such.
5. The format of binary, integer, and unsigned datatypes is handled differently
for local files. When reading and writing local files, the Java format is
assumed, which means that the high order bytes are leftmost, whereas when
running as a Windows application, they are rightmost.
6. Exception handling for subprocedures will behave the same as for action
subroutines. The default error handler will be called if there is no local *PSSR
or INFSR and no error indicator on the operation.
7. If an invalid date, time, or timestamp value is encountered when reading or
writing a field to/from a file, the field will be set to the default value
(*LOVAL). No error is reported.
8. Java can only handle a 3 digit millisecond portion in timestamps. When doing
calculations with timestamps that use all 6 digits of the millisecond portion
(meaning they do not have milliseconds in the form 000xxx), the results might
not be as expected.
9. Intermediate results in expressions are not limited to 30 digits. In fact, when
running in the VARPG environment, no attention is paid to the precision of
intermediate results.
10. Memory cannot be shared between components. If a component is started by
another component via START, changes made to passed parameters are not
reflected across components.
11. Integer overflow or underflow will not be reported. Float overflow or
underflow will be reported as status 9999.
12. If an error occurs while a subprocedure in a NOMAIN or EXE application is
being executed, and there is no error indicator or *PSSR, then the error will be
reported back to the caller and handled by the caller. When running under
Windows, the application would terminate.
13. A status 50 error will never be issued when running Java applications. Java
gives no diagnostic messages for character conversions it cannot handle. Java
may issue a status 100 for an unsuccessful conversion or an
ArrayIndexOutOfBoundsException when the converted string is used.
14. Positioning a host file to Null-Valued Records when ALWNULL(*NO) has
been specified results in CPF5035.
290
Applet Restrictions
The following language elements are not supported when running a VARPG applet
and will result in Java errors at run time:
v Printer files
v Local files
v Calling C functions, external subprocedures, EXEs.
v NOMAIN and EXE applications cannot be run as applets.
However, the printed text may not appear as expected. This problem will be
resolved when the existing problem with J2SDK 1.2 is fixed, without requiring a
VARPG update.
291
292
Creating Applets
Note: In order to build the Java version of a project, the Java 2 Software
Development Kit (J2SDK), version 1.2 or greater, must be installed on the
workstation. The J2SDK is available from Sun Microsystems at URL
http://java.sun.com/products/
293
You can control your applets build options on the Java: Build options notebook.
Select Project>Build Options>Java from the VisualAge RPG design window to
display the Java Build Options for your project:
The majority of the settings are simliar to those used for building a Windows
application, with the following exceptions:
SSL
Select SSL if you want all TCP/IP connections between your iSeries server
and Java applet or application to be encrypted using Secure Sockets Layer
technology. (See Appendix D, Secure Sockets Layer (SSL) Setup, on page
449 for information on SLL setup.)
Java Compiler
VisualAge RPG generates a Java source file (.java) from your project and
relies on an external Java compiler to create the class file (.class) from the
source. If you are not using the IBM or Sun Microsystems Java 2 SDK,
then you will need to specify the Java compiler you are using here.
Options
Pass any command line options you want to the Java compiler.
Applet - Embedded
Determines if your applet is run when the HTML page it is embedded in is
displayed in a Web browser, or if your applet starts in an external window.
Applet - Directory for HTML and JAR files
You can specify a directory where you want all of the required runtime
files for your applet to be placed. These files are generated when you build
your project for Java. By default, these files are placed in the projects
source directory on your workstation.
Hint: Map a network drive to your iSeries server and enter the IFS
directory where you would like to deploy the applet from.
Now that you have configured the options for your applet, you are ready to build
the project. From the projects design window, select Project>Build>Java. Upon a
294
successful build, the runtime files for the applet are created in the projects source
directory or the directory specified in the Directory for HTML and JAR files Java
build option.
For example, if you build the Listbox sample to create a Java application and
specify c:\applet\Listbox as the directory to contain the applets runtime files,
you should see the following files in this directory:
listbox.htm
listbox_applet.htm
LISTBOX.jar
vapplet.jar
These files are used to deploy your applet from the Web server, as follows:
listbox.htm
Launches your applet using the Java Plug-in.
listbox_applet.htm
Checks the users workstation for the required VisualAge RPG Java
runtime (varpg.jar) file. If the workstation has the correct version of the
run time, then the browser opens the listbox.htm page. Otherwise, the user
is prompted to download and install the correct runtime file.
LISTBOX.jar
Contains the LISTBOX.class, LISTBOXApplet.class, LISTBOX.ODX,
LISTBOX.RST and any *Resources.properties (if you defined messages for
the application) files used by your project.
vapplet.jar
Contains a small subset of the VisualAge RPG Java run time that is
required on the Web server.
295
Hint: Map a network drive to your iSeries server and enter the IFS directory in
the Directory for HTML and JAR files Java build option before you create your
applet.
4. Set up the iSeries HTTP server to allow access to the directory containing your
applet.
You will need to start and configure the IBM HTTP Server if you have not
already done so. See HTTP Server for iSeries Webmasters Guide for information
on configuring the HTTP server.
Add a PASS statement to your iSeries HTTP configuration file that allows
access to the IFS directory where you placed the applet runtime files. For this
example the applet files are in the IFS directory /applets. So, add the following
PASS statement:
Pass /applets/* /applets/*
5. Run the applet from your Web browser. For example, open your Web browser
with the following URL:
http://Toras14m:999/Listbox.htm
where Toras14m is your iSeries server name, 999 is your HTTP port number,
and Listbox.htm is the Web page containing your applet.
Here is the Listbox applet running inside the Windows browser:
Troubleshooting
The following is a list of common configuration problems that can cause applets
not to run:
v The proper J2RE is not installed. Ensure that the Java 2 SDK or international
version of the J2RE is installed along with the Java Plug-in.
296
v The applets required runtime files are not in the correct directory on the server.
The files AppName.htm, AppName_applet.htm, vapplet.jar, and APPNAME.jar
need to be in the directory referenced in the second parameter to the HTTP
servers Pass statement.
v Java file names are case sensitive. This causes the majority of configuration
issues. Make sure that all .jar files are in the correct case. Windows Explorer
does not always show file names in their actual case. Use the OS/400 wrklnk
command to check the case of the file names stored in the IFS.
If your applet is still not running, try enabling the Java Plug-in console to see if
any error messages are being displayed. Start the Plug-in control pannel by
selecting Start>Programs>Java Plug-in Control Panel. From the basic tab, select
Show Java Console and click Apply. Close all open Web browser windows and
restart the Web browser for the changes to take affect. The next time you run the
applet, the Java Console window appears with messages.
v Insert , APPLETB.jar between the varpg.jar and closing quotes so the VALUE
and archive values are now:
<PARAM NAME = "archive" VALUE = "APPLETA.jar , varpg.jar , APPLETB.jar">
...
archive = "APPLETA.jar , varpg.jar , APPLETB.jar"
Be sure to include a blank character before and after the comma delimiter.
When you display the AppletA.htm page in your Web browser, it should now run
AppletB, too.
If the called applet (AppletB, in this example), also accesses data on the server, you
need to give each applet permission to read the security file that resides on the
workstation. Otherwise, the user will be prompted to enter a valid user Id and
password each time that AppletB is run. SeeUsing the Security File for Applets
on page 210 for more information.
In this example, you need to modify the local policy file by adding the following
lines:
permission java.lang.RuntimePermission "modifyThreadGroup";
permission java.lang.RuntimePermission "modifyThread";
The policy file (java.policy) is located in the Java run time lib\security
subdirectory.
For socket permission, you may need to add a line like the following:
permission java.net.SocketPermission
"server_name:port_number", "connect,resolve";
Chapter 20. Creating and Running VisualAge RPG Applets
297
If you need to change the name or location of this policy file, modify the
java.security file in the same directory.
298
A Simple Call
The first code example shows a simple call to an external procedure with no
parameters and no return value. The simple VisualAge RPG application calls an
external procedure in a sample dynamic link library. The JNI specification dictates
the function name and interface to the native function being called. A function will
be coded and compiled into a new DLL to be the target of the call. The following
samples will only demonstrate native functions coded in the C language, but the
illustrated coding principles apply equally to other language implementations.
Once the native function has control, it is free to call other native functions, such
as system APIs.
Code a procedure prototype for the procedure in VisualAge RPG, specifying the
DLL keyword to provide the name of the DLL which will contain the native
function being called. The EXTPROC keyword may optionally be coded to specify
a function name different from the procedure name within the VisualAge RPG
program.
Note: The value of the EXTPROC keyword is case sensitive. Code a call to the
procedure in the VisualAge RPG source.
299
**********************************************************************
* Source File: VCOMP1.VPG
*
* Demonstrate calling an external procedure thru JNI.
*
**********************************************************************
* This declares a procedure named sub1 which refers to
* a function named proc1 in a Dynamic Link Library VSUB.DLL
d sub1
pr
dll(VSUB) extproc(proc1)
*INZSR
dll(VSUB)
BEGSR
C
C
callp
callp
seton
ENDSR
sub1
sub2
lr
CREATE1
BEGACT
seton
ENDACT
LR
For the Windows platform, the native function is coded to use the StdCall program
linkage. The function is coded as an exported function in the DLL. The exported
function name must match the name dictated by the JNI specification. The format
of the JNI Specification is:
Java_VARPGComponentName_ExternalProcedureName_OverloadedNativeMethods
300
// Source File:
VSUB.C
// Add
(d:\jdk12\include;d:\jdk12\include\win32) to the INCLUDE setting
//
in order to find jni.h when compiling.
// Compiled with: IBM VisualAge(TM) for C++ for Windows(R), Version 3.5
// Compile command: icc /q /ss /ge- /fe vsub.dll vsub.c
#include <stdio.h>
#include <string.h>
#include <jni.h>
//--------------------------------------------------------------void _Export __stdcall
{
printf(" proc1 called successfully.\n");
}
//--------------------------------------------------------------void _Export __stdcall
{
Parameter Types
Character
VisualAge RPG implements character fields as byte arrays in Java including a
character field of length one. The JNI interface function GetByteArrayElements
returns the value of the byte array parameter. The value can be changed and
returned to the calling function through the ReleaseByteArrayElements interface
function.
Note: The value should not be used in the native function after calling the release
function.
The first parameter for the native function in the C language source has been
changed from a void pointer to a JNIEnv pointer. It points to a table of function
pointers for JNI interface functions. The prototyped parameters for the external
301
procedure are added to the native functions parameters, after the two standard
JNI pointers. The character parameters are declared as jbyteArray types in the
native function.
The GetByteArrayElements interface function is used to obtain the value of the
Java byte array for the VARPG character field.
The obtained value can be changed and returned to the Java caller with the
ReleaseByteArrayElements interface function.
The obtained value should not be accessed after releasing it.
Note: It is possible the value obtained is the actual value in the Java object, and
not a copy in memory. The changes made to it might be reflected in the Java
caller even without calling the release function. Refer to the
GetByteArrayElements function in the JNI documentation for more
information.
302
**********************************************************************
* Source File: VCOMP1.VPG
*
* Demonstrate calling an external procedure thru JNI.
*
**********************************************************************
* This declares a procedure named sub1c which refers to
* a function named proc1c in a dynamic Load Library VSUBC.DLL
* With 1 character parameter
d sub1c
pr
d
dll(VSUBC) extproc(proc1c)
1
dll(VSUBC)
d c1
d c4
d c10
s
s
s
inz(J)
inz(blue)
inz(abcdefghij)
d mb1
d rc
*INZSR
C
C
1
4
10
style(*info) button(*OK)
9
BEGSR
callp
callp
sub1c(c1)
sub2c(c4:c10)
c
c
c
C
seton
ENDSR
lr
CREATE1
BEGACT
seton
ENDACT
LR
303
Java_VCOMPC_proc1c(
{
char
*c1;
{
char
char
*c4;
*c10;
304
Zoned Numeric
**********************************************************************
* Source File: VCOMPN.VPG
*
* Demonstrate calling an external procedure thru JNI.
*
**********************************************************************
* With a Zoned(4,0)
d subz
pr
d
parameter
dll(VSUBN)
4S 0
dll(VSUBN)
9P 2
* With
d subb
d
d
d
d
d
d
z4
p92
b4
b9
s
s
s
s
4S
9P
4B
9B
0
2
0
0
inz(1234)
inz(1234567.89)
inz(1234)
inz(123456789)
d mb1
d rc
C
m
s
*INZSR
style(*info) button(*OK)
9
BEGSR
C
C
C
callp
callp
callp
* Display the changed values
c
z4
dsply
c
p92
dsply
subz(z4)
subp(p92)
subb(b4:b9)
from the calls
mb1
rc
mb1
rc
c
c
mb1
mb1
b4
b9
c
C
dsply
dsply
rc
rc
seton
ENDSR
lr
CREATE1
BEGACT
seton
LR
ENDACT
305
// Source File:
VSUBN.C
//
// Add
(d:\jdk12\include;d:\jdk12\include\win32) to the INCLUDE setting
//
in order to find jni.h when compiling.
// Compiled with: IBM VisualAge(TM) for C++ for Windows(R), Version 3.5
// Compile command: icc /q /ss /ge- /fe vsubn.dll vsubn.c
#include <stdio.h>
#include <string.h>
#include <jni.h>
static void SwapBin2( short *b2);
static void SwapBin4( int *b4);
//--------------------------------------------------------------void _Export __stdcall
Java_VCOMPN_SUBZ(
{
jclass
jmethodID
jobject
char
cls;
mid;
aryobj;
*zd;
306
Re-use value
307
Packed Numeric
void _Export __stdcall
{
jclass
jmethodID
jobject
char
cls;
mid;
aryobj;
*packednum;
308
Re-use value
The packed decimal parameter case is similar to the zoned decimal. Only the
appropriate methods for converting an RpgPacked object to and from a byte array
value are used.
The RpgPacked::packedValue method is used to obtain a byte array containing the
numeric value of the RpgPacked parameter object in native packed decimal format,
and then the JNI interface functions are invoked to make the Java byte array
accessible from the native side of the interface.
After altering the byte array on the native side and invoking the
ReleaseByteArrayElements interface function to return the byte array to the Java
side, the assignFromNative method is once again invoked to set the RpgPacked
objects value from the Java byte array.
309
Binary
void _Export __stdcall
{
jclass
jmethodID
jobject
jobject
cls;
mid;
aryobj;
aryobj2;
char
char
*binarynum;
*b9;
short
int
binary2;
binary4;
Binary 4,0
310
311
Re-use value
312
Re-use value
313
This case is similar to the zoned decimal. Only the appropriate methods for
RpgBinary objects are used. The only added complication is that the native Intel
architecture platform stores binary integers in a low-order-bytes-leftmost format,
but the Java side works with them in a low-order-bytes-rightmost format. The
SwapBin2 and SwapBin4 functions are employed to reverse the byte order when
converting between the two sides for two- and four-byte binary integers.
The RpgBinary::binaryValue method is used to obtain a byte array containing the
numeric value of the RpgBinary parameter object in native binary format. Then the
JNI interface functions are invoked to make the Java byte array accessible from the
native side of the interface. After altering the byte array on the native side and
invoking the ReleaseByteArrayElements interface function to return the byte array
to the Java side, the assignFromNative method is once again invoked to set the
RpgBinary objects value from the Java byte array.
314
Integer, Unsigned
315
if ( mid == NULL)
{
printf(" ERROR: GetMethod.\n");
return;
}
i4 = (*je)->CallIntMethod( je, p2, mid);
printf(" i4 = %d\n", (short) i4);
// p3: Unsigned 2-byte.
// Call the method to get the double value
cls = (*je)->GetObjectClass(je, p3);
mid = (*je)->GetMethodID( je, cls, "unsignedValue", "()[B");
if ( mid == NULL)
{
printf(" ERROR: GetMethod.\n");
return;
}
aryobj3 = (*je)->CallObjectMethod( je, p3, mid);
u2 = (unsigned short *) (*je)->GetByteArrayElements( je, aryobj3, NULL);
// Must reverse the byte order of the value received
SwapBin2( (char *) u2);
printf(" u2 = %hu\n", *u2 );
316
317
//
//
//
//
318
//
//
Obtain the method ID so it can be invoked.
cls = (*je)->GetObjectClass(je, p3);
mid = (*je)->GetMethodID( je, cls, "assignFromNative", "([BII)V");
if ( mid == NULL)
{
printf(" ERROR 7: GetMethod.\n");
return;
}
// Pass (aryobj3) as first parameter to method because the
// method expects a Java byte array object
(*je)->CallVoidMethod( je, p3, mid,
aryobj3,
(int) 5,
(int) 0);
// = Component.UNSIGNED_TYPE
// 0 decimal places
//
319
Float (4/8)
320
Java_VJNIO_SUBF(
{
jclass
jmethodID
jfloat
jdouble
cls, cls2;
mid;
f4;
f8;
// p1: Float
// Call the method to get the float value
cls = (*je)->GetObjectClass(je, p1);
mid = (*je)->GetMethodID( je, cls, "getValue", "()F");
if ( mid == NULL)
{
printf(" ERROR: GetMethod.\n");
return;
}
f4 = (*je)->CallFloatMethod( je, p1, mid);
printf(" f4 = %f\n", (float) f4);
// p2: Double
// Call the method to get the double value
cls2 = (*je)->GetObjectClass(je, p2);
mid = (*je)->GetMethodID( je, cls2, "getValue", "()D");
if ( mid == NULL)
{
printf(" ERROR: GetMethod.\n");
return;
}
f8 = (*je)->CallDoubleMethod( je, p2, mid);
printf(" f8 = %lf\n", (double) f8);
Figure 87. Sample VSUBO.C (Part 1 of 2)
321
//
//
The float and double parameter cases are similar to the previous data types. Only
the methods to access the parameter values work with Java primitive data types,
which map to corresponding native primitives, instead of the usual byte arrays.
JNI interface functions dealing with these specific primitives are used to invoke the
methods to access the parameter values.
The RpgFloatRef::getValue, setValue, RpgDoubleRef::getValue, and setValue
methods are used.
322
s
s
s
10d
8t
26z
callp
inz(D1999-12-31)
inz(T09.00.00)
inz(Z2001-01-01-08.01.01)
subdtz(fd:ft:fts)
Date, time, and timestamp parameters work the same as character parameters,
since they are implemented on the Java side as byte arrays.
Passing Arrays
Handling arrayed parameters is done one of two ways depending on the datatype.
Invoke the GetObjectArrayElement interface function to get an address to an
individual object element in the array, then process it like the scalar parameter
methods. Or in the case of an array of Java primitives, there are specific interface
functions to access them as an array of native primitives, and then release them
back to Java.
Chapter 21. Calling System Functions when Compiling for Java
323
d subca
d
d
pr
d c1
d c4
d c10
s
s
s
d subz
d
pr
dll(VSUBA)
4S 0 dim(4)
d subp
pr
dll(VSUBA)
dll(VSUBA)
4
10
dim(4)
1
4
10
inz(J)
inz(blue)
inz(abcdefghij) dim(4)
9P 2 dim(4)
d subb
d
d
pr
dll(VSUBA)
4B 0 dim(4)
9B 0 dim(4)
d
d
d
d
z4
p92
b4
b9
s
s
s
s
4S
9P
4B
9B
d subf
pr
d
d
dim(4)
dim(4)
dim(4)
dim(4)
dll(VSUBA)
4f
8f
324
0
2
0
0
dim(4)
dim(4)
d subdtz
d
d
d
pr
d subiu
d
d
pr
10d
8t
26z
dll(VSUBA)
5i 0 dim(4)
10i 0 dim(4)
d
d
d
d
d
d
d
dll(VSUBA)
dim(4)
dim(4)
dim(4)
5u 0 dim(4)
10u 0 dim(4)
f4
f8
fd
ft
fts
s
s
s
s
s
d fi2
5i 0 dim(4) inz(1)
d fi4
d fu2
d fu4
s
s
s
*INZSR
4f
8f
10d
8t
26z
dim(4)
dim(4)
dim(4)
dim(4)
dim(4)
inz(1234.56)
inz(1111.2222)
inz(D1999-12-31)
inz(T09.00.00)
inz(Z2001-01-01-08.01.01)
BEGSR
C
C
C
C
C
C
callp
callp
callp
callp
callp
callp
subca(c4:c10)
subz(z4)
subp(p92)
subb(b4:b9)
subf(f4:f8)
subdtz(fd:ft:fts)
C
c
C
callp
seton
ENDSR
subiu(fi2:fi4:fu2:fu4)
lr
325
{
char *c4;
char *c10;
jobject p2e;
// Resolve to 2nd element of array parameter
p2e = (*je)->GetObjectArrayElement( je, p2,
1); /* Array index, first element = 0.
c4 = (char *) (*je)->GetByteArrayElements( je, p1, NULL);
c10 = (char *) (*je)->GetByteArrayElements( je, p2e, NULL);
printf(" c4
= %.4s.\n",
c4);
Java_VJNIA_SUBZ(
326
*/
{
jclass
jmethodID
jobject
char
jobject
cls;
mid;
aryobj;
*zd;
pe;
*/
// p1: Zoned
// Call the method to get the zoned value
cls = (*je)->GetObjectClass(je, pe);
mid = (*je)->GetMethodID( je, cls, "zonedValue", "()[B");
aryobj = (*je)->CallObjectMethod( je, pe, mid);
zd = (char *) (*je)->GetByteArrayElements( je, aryobj, NULL);
printf(" zd = %.4s.\n", zd);
// Now change the values
memcpy( zd, "9876", 4);
// Returning the Zoned parameter
// 1. Update the Byte array object with the changed value.
(*je)->ReleaseByteArrayElements( je, aryobj, (signed char *) zd, 0);
Figure 91. Sample VSUBA.C (Part 2 of 14)
327
takes a byte array object and assigns its value into the
RpgNumeric object. Obtain the method ID.
Re-use value
{
jclass
jmethodID
jobject
char
char
jobject
cls;
mid;
aryobj;
*packednum;
tmp[80];
pe;
// For tracing
328
*/
RpgNumeric object.
Re-use value
329
{
jclass
jmethodID
jobject
jobject
char
char
cls;
mid;
aryobj;
aryobj2;
*binarynum;
*b9;
short
int
jobject
binary2;
binary4;
pe,p2e;
*/
Binary 4,0
330
*/
331
Re-use value
332
RpgNumeric object.
Re-use value
333
Java_VJNIA_SUBF(
{
jclass
jmethodID
jfloat
jdouble
jobject
cls, cls2;
mid;
*f4;
*f8;
p1e,p2e;
f8
334
p2,
/* Array index, first element = 0.
p3,
/* Array index, first element = 0.
*/
*/
*/
335
=
=
336
337
//
Obtain the method ID so it can be invoked.
cls = (*je)->GetObjectClass(je, p3e);
mid = (*je)->GetMethodID( je, cls, "assignFromNative", "([BII)V");
// Pass (aryobj3) as first parameter to method because the
// method expects a Java byte array object
(*je)->CallVoidMethod( je, p3e, mid,
aryobj3,
(int) 5,
(int) 0);
338
// = Component.UNSIGNED_TYPE
// 0 decimal places
//
tmp;
tmp = p[0];
p[0] = p[3];
p[3] = tmp;
tmp = p[1];
p[1] = p[2];
p[2] = tmp;
}
pr
10
dll(VSUBR)
d fc
10
inz(ibm varpg )
eval
fc = subrc
339
Java_VJNIR_SUBRC(
",10);
Returning a value from the function involves obtaining the appropriate Java object
and then returning it. In this sample, a new object (matching a Character(10) field)
was created, then its value was assigned. Since the RPG character fields are
implemented as Java byte arrays, a Java byte array object of length ten was
created, then the GetByteArrayElements interface function was used to access the
byte array elements on the native side, then released back to Java, and finally used
to return from the function.
If the appropriate Java byte array object was already available from one of the
input parameters, then it could have been used instead of creating a new object.
pr
s
eval
340
5s 0 dll(VSUBR)
5s 0
fc = subrc
jbyteArray ba;
char
*p;
printf(" SUBRS called successfully.\n");
// Create a new RpgZoned object.
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgZoned");
mid = (*je)->GetMethodID( je, cls, "<init>", "(II)V");
rzo = (*je)->NewObject( je, cls, mid,
(int) 5, /* # of digits */
(int) 0
/* # of decimal places */
);
//
//
//
//
To set the zoned object value, we need a Java byte array to use
as an input parameter to the method for setting the zoned object.
Could constuct a new byte array object, or get one by retrieving
the zoned value from the object.
341
//
//
takes a byte array object and assigns its value into the
RpgNumeric object. Obtain the method ID.
Re-use value
pr
s
eval
342
5p 0 dll(VSUBR)
5p 0
fp = subrp
jbyteArray ba;
char
*p;
printf(" SUBRP called successfully.\n");
// Create a new RpgPacked object.
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgPacked");
mid = (*je)->GetMethodID( je, cls, "<init>", "(II)V");
ro = (*je)->NewObject( je, cls, mid,
(int) 5, /* # of digits */
(int) 0
/* # of decimal places */
);
//
//
//
//
To set the packed object value, we need a Java byte array to use
as an input parameter to the method for setting the packed object.
Could constuct a new byte array object, or get one by retrieving
the packed value from the object.
// Pin the byte array element memory so native side can access it.
p
343
d subrb
d fb
C
pr
s
5b 0 dll(VSUBR)
5b 0
eval
fb = subrb
jbyteArray ba;
char
*p;
printf(" SUBRB called successfully.\n");
// Create a new RpgPacked object.
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgBinary");
mid = (*je)->GetMethodID( je, cls, "<init>", "(II)V");
ro = (*je)->NewObject( je, cls, mid,
(int) 5, /* # of digits */
(int) 0 /* # of decimal places */
);
Figure 99. Sample VSUBR.C (Part 1 of 2)
344
// 55555 = 0xD903
Returning a binary value is similar to the zoned or packed cases above, only an
RpgBinary object is returned.
pr
pr
5i 0 dll(VSUBR)
10i 0 dll(VSUBR)
d fi2
d fi4
s
s
5i 0
10i 0
C
C
eval
eval
fi2= subri2
fi4= subri4
345
jint
_Export __stdcall
{
return -55555;
}
Returning a two-byte or four-byte binary integer value is simple. This is due to the
types supported as Java primitives.
d subru
d fu
C
pr
s
eval
346
10u 0 dll(VSUBR)
10u 0
fu = subru
jbyteArray ba;
char
*p;
printf(" SUBRU called successfully.\n");
// Create a new RpgUnsigned object.
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgUnsigned");
mid = (*je)->GetMethodID( je, cls, "<init>", "(II)V");
ro = (*je)->NewObject( je, cls, mid,
(int) 5, /* # of digits */
(int) 0
/* # of decimal places */
);
// To set the object value, we need a Java byte array to use
// as an input parameter to the method for setting the object.
// Create a new byte array object
ba = (*je)->NewByteArray( je, 4 /* = byte array length */ );
// Pin the byte array element memory so native side can access it.
p
// 55555 = 0xD903
347
pr
s
eval
10d
dll(VSUBR)
10d
fd = subrd
Java_VJNIR_SUBRD(
memcpy( p, "2000-01-01",10);
// Update the values back to the Java Caller
(*je)->ReleaseByteArrayElements( je, ba, (signed char *) p, 0);
return ba;
}
Date, time, and timestamp values are returned as Java byte arrays of the expected
length. This is similar to the character data type.
subrf
subrf8
ff
ff8
C
C
pr
pr
s
s
eval
eval
348
4f
8f
4f
8f
dll(VSUBR)
dll(VSUBR)
ff = subrf
ff8= subrf8
jfloat
_Export __stdcall
{
jfloat rc;
rc = -4444.4444;
return rc;
}
jdouble
_Export __stdcall
{
return -7777777.55555;
}
Returning a float or double (eight-byte float) value is done directly. This is due to
the types supported as Java primitives.
pr
s
eval
10
dll(VSUBR)
10
varying
fcv= subrcv
varying
memcpy( p, "abcd",4);
// Update the values back to the Java Caller
(*je)->ReleaseByteArrayElements( je, ba, (signed char *) p, 0);
return ba;
}
A varying-length character value is returned through a Java byte array, where the
array length matches the current value length.
349
also allocate the elements of the array. Then it is only a matter of calling the
interface function to map the array elements to native memory and they can be set,
relased back to Java, and then returned from the function.
If it is not the case of a Java primitive data type for the array elements, then a Java
object must be allocated for each element of the array, its value set as desired , and
then finally the object is assigned to the specific element of the array. Allocating
the individual objects for the elements is similar to the scalar return value case for
that datatype.
* Source File:
VJNIRA.VPG
d
d
d
d
d
d
d
subrca
subrsa
subrpa
subrba
subri2a
subri4a
subrua
pr
pr
pr
pr
pr
pr
pr
10
5s
5p
5b
5i
10i
10u
d
d
d
d
subrda
subrfa
subrf8a
subrcva
pr
pr
pr
pr
10d
4f
8f
10
d
d
d
d
fc
fs
fp
fb
s
s
s
s
10
dim(4)
5s 0 dim(4)
5p 0 dim(4)
5b 0 dim(4)
d
d
d
d
d
d
d
fi2
fi4
fu
fd
ff
ff8
fcv
s
s
s
s
s
s
s
5i 0 dim(4)
10i 0 dim(4)
10u 0 dim(4)
10d
dim(4)
4f
dim(4)
8f
dim(4)
10
varying dim(4)
d mb1
d rc
m
s
0
0
0
0
0
0
dll(VSUBRA)
dll(VSUBRA)
dll(VSUBRA)
dll(VSUBRA)
dll(VSUBRA)
dll(VSUBRA)
dll(VSUBRA)
dll(VSUBRA) dim(4)
dll(VSUBRA) dim(4)
dll(VSUBRA) dim(4)
dll(VSUBRA) varying dim(4)
style(*info) button(*OK)
9
350
dim(4)
dim(4)
dim(4)
dim(4)
dim(4)
dim(4)
dim(4)
C
C
c
C
c
*INZSR
BEGSR
fs(2)
eval
dsply
eval
dsply
fc = subrca
mb1
fs = subrsa
mb1
C
c
fp(2)
eval
dsply
fp = subrpa
mb1
rc
C
c
fb(2)
eval
dsply
fb = subrba
mb1
rc
C
c
fi2(2)
eval
dsply
fi2= subri2a
mb1
rc
C
c
fi4(2)
eval
dsply
fi4= subri4a
mb1
rc
C
c
fu(2)
eval
dsply
fu = subrua
mb1
rc
C
c
fd(2)
eval
dsply
fd = subrda
mb1
rc
eval
ff = subrfa
fc(2)
rc
rc
ff(2)
dsply
mb1
rc
C
c
ff8(2)
eval
dsply
ff8= subrf8a
mb1
rc
eval
dsply
eval
dsply
seton
ENDSR
fcv= subrcva
mb1
rc
rc = %len(fcv(2))
mb1
rc
C
c
C
c
c
C
fcv(2)
rc
lr
351
// Source File:
VSUBRA.C
//
// Add
(d:\jdk12\include;d:\jdk12\include\win32) to the INCLUDE setting
//
in order to find jni.h when compiling.
// Compiled with: IBM VisualAge(TM) for C++ for Windows(R), Version 3.5
// Compile command: icc /q /ss /ge- /fe vsubra.dll vsubra.c
#include <stdio.h>
#include <string.h>
#include <jni.h>
static void SwapBin2( char *);
static void SwapBin4( char *);
//--------------------------------------------------------------jobjectArray _Export __stdcall
{
jobjectArray oa;
jclass
cls;
jbyteArray ba;
char
*p;
int
i;
Java_VJNIRA_SUBRCA(
352
memcpy( p, "Success
",10);
353
jbyteArray ba;
char
*p;
printf(" SUBRSA called successfully.\n");
// Create the object array
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgZoned");
if ( cls == NULL)
{
printf(" ERROR 1: FindClass.\n");
return NULL;
}
oa = (*je)->NewObjectArray( je, 4 /* array length */, cls, NULL );
if ( oa == NULL)
{
printf(" ERROR 2: Newobj\n");
return NULL;
}
// Populate the array
for (i=0; i<4; i++)
{
// Create a new RpgZoned object.
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgZoned");
if ( cls == NULL)
{
printf(" ERROR 1: FindClass.\n");
return NULL;
}
354
/* # of decimal places */
);
if ( rzo == NULL)
{
printf(" ERROR3: \n");
return NULL;
}
// Set value of 2nd element
if ( 1 == i)
{
// To set the zoned object value, we need a Java byte array to use
// as an input parameter to the method for setting the zoned object.
// Could constuct a new byte array object, or get one by retrieving
// the zoned value from the object.
// Will construct a byte array.
// Create a new byte array object
ba = (*je)->NewByteArray( je, 5 /* = byte array length */ );
if ( ba == NULL)
{
printf(" ERROR4: \n");
return NULL;
}
Figure 111. Sample VSUBRA.C (Part 4 of 22)
355
// Pin the byte array element memory so native side can access it.
p
//
//
//
Re-use value
356
jbyteArray ba;
char
*p;
printf(" SUBRPA called successfully.\n");
// Create the object array
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgPacked");
if ( cls == NULL)
{
printf(" ERROR 1: FindClass.\n");
return NULL;
}
oa = (*je)->NewObjectArray( je, 4 /* array length */, cls, NULL );
if ( oa == NULL)
{
printf(" ERROR 2: Newobj\n");
return NULL;
}
// Populate the array
for (i=0; i<4; i++)
{
357
358
//
//
//
Re-use value
359
// decimal places
);
}
(*je)->SetObjectArrayElement( je, oa, i /* array element, starting at 0 */
, ro);
} // for i
return oa;
}
//--------------------------------------------------------------jobjectArray _Export __stdcall
{
jobjectArray oa;
int
i;
jclass
cls;
jmethodID
jobject
mid;
ro;
jbyteArray ba;
char
*p;
printf(" SUBRBA called successfully.\n");
// Create the object array
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgBinary");
if ( cls == NULL)
{
printf(" ERROR 1: FindClass.\n");
return NULL;
}
360
361
if ( ro == NULL)
{
printf(" ERROR3: \n");
return NULL;
}
// Set value of 2nd element
if ( 1 == i)
{
// To set the packed object value, we need a Java byte array to use
// as an input parameter to the method for setting the packed object.
// Could constuct a new byte array object, or get one by retrieving
// the packed value from the object.
// Will construct a byte array.
// Create a new byte array object
ba = (*je)->NewByteArray( je, 4 /* = byte array length */ );
if ( ba == NULL)
{
printf(" ERROR4: \n");
return NULL;
}
// Pin the byte array element memory so native side can access it.
p
// 55555 = 0xD903
362
//
//
//
RpgNumeric object.
Re-use value
// decimal places
);
}
(*je)->SetObjectArrayElement( je, oa, i /* array element, starting at 0 */
, ro);
} // for i
return oa;
}
363
//--------------------------------------------------------------jshortArray
_Export __stdcall
{
jshortArray rc;
jshort
*n;
n[1] = -5555;
// Update the values back to the Java Caller
(*je)->ReleaseShortArrayElements( je, rc, n, 0);
return rc;
}
//--------------------------------------------------------------jintArray
_Export __stdcall Java_VJNIRA_SUBRI4A( JNIEnv *je , void *jc)
{
jintArray rc;
jint
*n;
printf(" SUBRI4A called successfully.\n");
rc = (*je)->NewIntArray( je, 4 /* = array length */ );
// Pin the array element memory so native side can access it.
n
n[1] = -5555;
// Update the values back to the Java Caller
(*je)->ReleaseIntArrayElements( je, rc, n, 0);
return rc;
}
364
jbyteArray ba;
char
*p;
printf(" SUBRUA called successfully.\n");
// Create the object array
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgUnsigned");
if ( cls == NULL)
{
printf(" ERROR 1: FindClass.\n");
return NULL;
}
oa = (*je)->NewObjectArray( je, 4 /* array length */, cls, NULL );
if ( oa == NULL)
{
printf(" ERROR 2: Newobj\n");
return NULL;
}
// Populate the array
for (i=0; i<4; i++)
{
// Create a new RpgPacked object.
#if 0
cls = (*je)->FindClass( je, "com/ibm/varpg/rpgruntime/RpgUnsigned");
if ( cls == NULL)
{
printf(" ERROR 1: FindClass.\n");
return NULL;
}
#endif
365
To set the packed object value, we need a Java byte array to use
as an input parameter to the method for setting the packed object.
Could constuct a new byte array object, or get one by retrieving
the packed value from the object.
366
// 55555 = 0xD903
367
//
//
//
Re-use value
// for i
return oa;
}
//--------------------------------------------------------------Figure 111. Sample VSUBRA.C (Part 17 of 22)
368
Java_VJNIRA_SUBRDA(
369
n[1] = -4444.4444;
// Update the values back to the Java Caller
(*je)->ReleaseFloatArrayElements( je, rc, n, 0);
return rc;
}
370
//--------------------------------------------------------------jdoubleArray
_Export __stdcall
{
jdoubleArray rc;
jdouble
*n;
printf(" SUBRF8 called successfully.\n");
rc = (*je)->NewDoubleArray( je, 4 /* = array length */ );
// Pin the array element memory so native side can access it.
n
n[1] = -7777777.55555;
// Update the values back to the Java Caller
(*je)->ReleaseDoubleArrayElements( je, rc, n, 0);
return rc;
}
//--------------------------------------------------------------jobjectArray _Export __stdcall Java_VJNIRA_SUBRCVA( JNIEnv *je , void *jc)
{
// This is similar to fixed length character, only the individual
// array elemnts can be created as byte arrays of different lengths
// to reflect the current length of the varying length values.
371
jobjectArray oa;
jclass
cls;
jbyteArray ba;
char
*p;
int
i;
printf(" SUBRCVA called successfully.\n");
// Create the object array
cls = (*je)->FindClass( je, "java/lang/Object");
if ( cls == NULL)
{
printf(" ERROR 1: FindClass.\n");
return NULL;
}
oa = (*je)->NewObjectArray( je, 4 /* array length */, cls, NULL );
if ( oa == NULL)
{
printf(" ERROR 2: Newobj\n");
return NULL;
}
Figure 111. Sample VSUBRA.C (Part 21 of 22)
372
memcpy( p, "abcd",4);
// Update the values back to the Java Caller
// Fourth Parameter = 0 also causes the variables storage to be freed,
// so can not access the variables after this function call.
(*je)->ReleaseByteArrayElements( je, ba, (signed char *) p, 0);
}
373
374
EXE
The program source must contain a procedure whose name matches the name of
the source file. This will be the main entry point for the program. If there are
parameters to be passed to the program, they must be specified on the parameter
definition for the main procedure, and they must be passed in by value. That is,
the VALUE keyword must be specified for each parameter. When calling an
application from the command line, separate parameters by spaces. If more
parameters or fewer are passed than are specified, no error message is displayed.
To create a standalone program in the GUI Designer, select Project > New > Non
GUI project from the project window. The editor opens a new source file that has
an H control specification template. Uncomment the H * EXE specification and code
your program. When completed, save your project and build the application. You
can set any needed build options from the project window, as well.
375
Creating DLLs
A DLL is created when the keyword NOMAIN is specified on the control
specification:
H NOMAIN
To create a DLL in the GUI Designer, select Project > New > Non GUI project
from the project window. The editor opens a new source file that has an H control
specification template. Uncomment the H * NOMAIN specification and code your
program. When completed, save your project and build the DLL. You can set any
needed build options from the project window, as well.
When you build a DLL, the compiler produces the DLL and a LIB file. The LIB file
is used to link the DLL to other applications. The LIB file will be in the same
directory as the source and it will have the same name as the DLL. The LIB file
contains all the procedures that have the EXPORT keyword on their Begin
P-specification.
The following example shows how to code the part of program MyPGM that
translates the lowercase string to uppercase as a procedure in a DLL. The source
for the DLL has one procedure named ToUpper in it. Add the Export keyword to
the procedure defintion so that this procedure can be called from other programs.
* Sample VARPG DLL
H NOMAIN
*
* Prototype ToUpper procedure
D ToUpper
PR
64A
D
64A
*
376
Value
Export
64A
64A
Value
64A
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
InString
OutString
OutString
When you create and build a DLL, you can give it any name. For this example, we
use MyFunc. A successful build will create the following files in the source
directory:
v MyFunc.VPG - program source
v MyFunc.DLL - the DLL
v MyFunc.LST - the compiler listing
v MyFunc.LIB - the library file
v MyFunc.EVT - the event file (used by the GUI designer to display the error
feedback window; not required to run the program)
Edit and modify the MyPGM source so it calls the ToUpper procedure in the
MyFunc.DLL that was just created. The modified source follows:
0000 * Calling a procedure in a VARPG DLL
0001 H EXE
0002 *
0003 D ToUpper
0004 D
0006 D
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
*
D MyMain
D
*
PMyMain
*
D MyMain
D InString
*
D Upper
*
PR
64A
64A
DLL(MyFunc)
ExtProc(TOUPPER)
Value
64A
Value
64A
Value
PR
B
PI
S
64A
0018 C
Eval
0019 C
Upper
0010 *
0011 PMyMain
Dsply
Upper=ToUpper(Instring)
I
Line
Description of Change
0003
Define the prototype for the ToUpper procedure and specify that the
procedure returns a parameter that is an alpha field, 64 bytes long. The
DLL keyword specifies that the procedure is in the DLL named
MyFunc.DLL.
Chapter 22. Creating Non-GUI VisualAge RPG Programs
377
0004
0006
0018
If the procedure you are calling does not return a value, then you must use the
CALLP operation code to invoke it:
C
378
CALLP
SomeFunc(parm1:parm2)
Exception Handling
Exception handling differs from GUI VARPG applications in the following ways:
v No information about the exception is communicated back to the caller if the
caller does not reside in the utility DLL.
v The default exception handler is never invoked from a DLL, since the default
exception handler is not invoked when an exception occurs in a procedure. If an
exception occurs in the DLL and there is no error indicator or *PSSR, the DLL
ends. Information about the exception is written to the FVDCERRS.LOG file.
v The recommended way to handle exceptions in a utility DLL is to have an error
indicator or a local *PSSR for each routine which returns an appropriate return
code to the caller.
Debugging Applications
To debug VARPG programs, be sure to use the debug compiler option when
building the application. If the debug option is not set, you can still start the
debugger on the program, but you will have to work with the assembler view of
your program.
To run the debugger against your source, you must first build your application.
From the project view, choose Project > Build > Windows NT/95/98. To start the
debugger, select the Debug menu item from the Project menu. See Chapter 10,
Debugging Your Application, on page 227 for more information on debugging.
Debugging Procedures
If you want to debug code in your DLL, you need to follow some extra steps:
1. Start the debugger for your main application- in our example, MyMain.
2. On the Debugger - Session Control dialog, choose Breakpoints-Set load
occurrence....
3. When the Load Occurrence Breakpoint dialog is displayed, type the name of
the DLL, MyFunc, in the DLL File Name entry and press OK.
4. Run your program.
When the procedure is called in the DLL, a debugger message dialog is displayed
indicating that the DLL is being loaded. Press OK and do the following:
1. Locate the Debug - Session Control dialog and note that there is a new entry in
the right side panel with the name of the DLL.
379
2. Click on the + sign next to the DLL name. It will expand to show the name of
the object module, MyFunc.obj.
3. Double-click on the object module name.
4. The source view of the debugger will now show the source for procedure
ToUpper in DLL MYFUNC.
You can now add breakpoints and display program variables in the DLL. Also, if
you are currently STARTing other VARPG components, or if you are calling your
own C functions, you can also use the above procedures to debug them.
380
381
used to insert the SO and SI characters before the field is transferred to the server.
Assume that the field contains the following data before being transferred to the
server:
DBDBDBDBblbl
Where DB = 1 Double byte character.
bl = 1 Single byte blank character.
Before the field is transferred to the server, it is converted so that the DBCS data is
bracketed by the SO and SI characters. The single-byte blanks are treated as being
insignificant, and they are replaced with the appropriate SO and SI characters.
Therefore, the field would appear as follows before being transferred to the server:
SODBDBDBDBSI
If the same data is retrieved from the server, then the SO and SI characters are
stripped and the field is padded with two single byte blanks:
DBDBDBDBblbl
Where DB = 1 Double byte character
bl = 1 Single byte blank character
Note: The character fields representing the DBCS ONLY, DBCS Mixed, or DBCS
Either data types must be padded with the appropriate number of
single-byte blanks in order for the field to be transferred to the server and in
order for the data within the field to be displayed in the window correctly.
VisualAge RPG ensures that enough single-byte blanks are present. When setting
DBCS fields or retrieving information from DBCS fields using the SETATR and
GETATR operation codes, respectively, you must ensure that the length of the field
in the SETATR and GETATR operations is the same length as the field in the
window. If it is not, it may not be transferred between the server and the
workstation.
382
VisualAge RPG enforces the following rules when the first two bytes of the field
represent a DBCS character, regardless of whether the data is added via the field
on the window or entered using the SETATR operation code:
v The minimum field length is 2. This ensures that there is enough room for the
SO and SI characters that are added when the data is transferred to the server.
v The field contains only valid DBCS characters. Each double-byte pair is checked
to ensure that a valid DBCS character is used.
v The field is appropriately padded with blank characters. If a smaller value is
entered than the field will allow, then the field is padded to the maximum
length of 2 with double-byte blanks. The last two bytes of the field are padded
with single-byte blanks.
This is the maximum length of the field, since the field is converted to the
following before being transferred to the server.
SODBSIsbSODBSIsbSODBSIsbSODBSIsb.
where SO = 1 shift out character.
sb = 1 shift in character.
383
384
This window shows two views, the one on the left contains the tree view of the
project that you selected to merge from, and the one on the right contains all of the
children of the part that is selected in the tree-view on the left. You can select
multiple parts in the right side of the window much like you can in the Windows
Explorer. This view may be used as an additional parts pallette because you can
select items from here (either the left or the right pane), and then point-and-click
them onto the current projects tree view or onto the design window. This works in
the same way as the parts pallette in that you can only place parts into a
frame-based part, and frame-based parts can only be placed into the root of your
project tree. When you merge the GUI and the associated code, the builder will
force a save of the current project that you are working on, in order to provide you
with a backup of your work in the event that you are not satisfied with the merge
results.
385
In addition to the GUI layout, the merge will copy linked action subroutines, help
panels, technical descriptions, references to media files, referenced user subroutines
and user messages. There are a few rules to keep in mind about merging code in
these specific cases.
v All linked action subroutines will be copied.
v Referenced media files are not copied along with the references. It is your
responsibility to do this.
v File description specifications and definition specifications are not copied to the
current project. Again, it is your responibility to do this.
v User subroutines, RPG procedures and User messages referenced by the action
subroutine being copied will also be copied. This includes all references to user
subroutines used by an EXSR or a CASxx operation code, RPG procedures
referenced on a CALLP operation code, and user messages referenced with the
DSPLY operation code.
v For parts which have been renamed, all action subroutines that refer to the part,
and which have names that conform to the standard format will be renamed.
For example, the following source code would be renamed as it follows the
standard format. The requirement for this format is that the partname and
windowname directly correspond to the location in which the part can be found.
*...1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
CSRN01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq---C
PSB000000C
BEGACT
PRESS
FRA000000B
.
.
.
C
ENDACT
v User messages which are copied are renamed consecutively begining with the
first message copied. All merged user messages are numbered sequentially
starting immediately after the last message in the current project. The message
IDs are changed on DSPLY operation codes that reference them.
v If a name conflict is detected for a user subroutine, it will not be renamed and it
will be added to a list contained in the merge log file. The log will also be
displayed on the Code Merge Results window. The merge log file will be placed
in the project directory, with a filename of projectname.mrg where projectname
is the name of your project. This file will be overwritten if more than one merge
is performed for the same project. The file is not automatically appended. The
following example contains a listing of a sample merge file.
The following parts were copied to the target project:
386
Source Name
Target Name
SEARCHW:CAN00023
SEARCHW:SEARCHW
SEARCHW:SEARCHGB
SEARCHW:STX00071
SEARCHW:TITLECB
SEARCHW:STX00073
SEARCHW:STX00074
SEARCHW:STX00075
SEARCHW:CATCB
SEARCHW:DIRCB
SEARCHW:ACTORCB
SEARCHW:SEARCHPB
SEARCHW:CANCELSEPB
SEARCHW:HELPPB
SEARCHW:STX00082
SEARCHW:CAN00023
SEARCHW:SEARCHW
SEARCHW:SEARCHGB
SEARCHW:STX00071
SEARCHW:TITLECB
SEARCHW:STX00073
SEARCHW:STX00074
SEARCHW:STX00075
SEARCHW:CATCB
SEARCHW:DIRCB
SEARCHW:ACTORCB
SEARCHW:SEARCHPB
SEARCHW:CANCELSEPB
SEARCHW:HELPPB
SEARCHW:STX00082
Target Name
24.SEARCHW
79.SEARCHPB
80.CANCELSEPB
81.HELPPB
88.SEARCHW
99.SEARCHPB
100.CANCELSEPB
101.HELPPB
CATW+CLOSE+CATW
SEARCHW+CLOSE+SEARCHW
TITLECB+CREATE+SEARCHW
DIRCB+CREATE+SEARCHW
ACTORCB+CREATE+SEARCHW
CATCB+CREATE+SEARCHW
TITLECB+ENTER+SEARCHW
CATCB+SELECT+SEARCHW
DIRCB+SELECT+SEARCHW
ACTORCB+SELECT+SEARCHW
CANCELSEPB+PRESS+SEARCHW
SEARCHPB+PRESS+SEARCHW
*MSG0001 -> *MSG0003
*MSG0001 -> *MSG0003
*MSG0001 -> *MSG0003
*MSG0001 -> *MSG0003
WRTBRSFSR
CASECAT
CKCRITERIA
DSPBROWSE
*MSG0001 -> *MSG0003
BRACTION
BRCHILDREN
BRSCIFI
BRCOMEDY
BRHORROR
BRWESTERN
BRROMANCE
BRCLASSIC
Target Message
Target Name
SEARCHW:SEARCHPB
SEARCHW:CANCELSEPB
SEARCHW:HELPPB
SEARCHW:SEARCHPB
SEARCHW:CANCELSEPB
SEARCHW:HELPPB
387
388
389
390
Alternate_Paths
This is a string that indicates what relative paths should be used when loading the
plugin DLL described below. This field is optional.
The string takes the form:
"&1\relativePath1;&1relativePath2;...;&1\relativePathN;"
where &1\ will be converted to the full path to the .plg file. This means that if you
have a suite of plugins that get installed in a directory such as c:\myplugins, and
they all link to a common DLL: c:\myplugins\plugutil\plugutil.dll, then if each
individual plugin was located in c:\myplugins\plugN\plugN.plg, you could specify
the alternate path: &1\..\util;, which would be converted to:
c:\myplugins\plugN\..\util; and be appended to the PATH before your DLL is
loaded. The quotation marks are required if you choose to use this keyword.
391
Instead of a string, you may also use a resource id to point to a path specified in
an external source.
DLL_Names
The value for this field is a string that defines the name of the required DLL files
for this plugin. This is an optional field, but if used, there must be a DLL named
that is used by the plugin. Additionally, an mri.dll may be named. The mri.dll
name is optional, but cannot be included without a plugin.dll. If both are included,
they are delimited by a space. The name of the DLL files can include the path
relative to the location of the plugin files.
plugin.dll
This is the name of the DLL containing the code for the plugin. If the
plugin is not a function call within a DLL, then this may be omitted.
mri.dll
If mri (translatable strings) is in a separate DLL, name that dll here. The
DLLS are specified first so that any strings to follow can be contained in
the DLLs.
Whenever a string is required further on in the .plg file, if a string enclosed in
quotation marks is not specified, then the value given is assumed to be a string
resource id in either mri.dll or plugin.dll
Vendor_Name
This is either the name of the vendor enclosed in double quotation marks, or the
resource id of a string. This field is optional, but recommended. An example of this
string would be:
Vendor_Name:
"Plug-Me-In Inc."
Plugin_Name
This is either the name of the plugin enclosed in quotation marks, the resource id
of a string. This field is optional, but recommended. An example of this field using
a string is:
Plugin_Name:
"Who Am I?"
Help_File
This field is optional, and identifies the Windows .hlp file used for displaying help
for the menu items. It is a string, not enclosed in quotation marks, which includes
the relative path to the help file.
Unloading_Function
This field is optional. The Unloading_Function field cannot be used in conjunction
with the Unloading_Command_Line field. This field is only used if there is
information or a display element that needs to be modified or removed after the
plugin is finished or removed. This string, enclosed in quotation marks, designates
the function which will be used. This function must be contained in the DLL that
accompanies the plugin.
The Unloading_Function is the name of the function to be called when the plugin
is about to be unloaded. It has the following signature:
392
unsigned long
unloadFunctionName(
const char*
const char*
const char*
const char*
int
ppluginPath_,
ppluginStub_,
pdllPath_,
builderId_,
remove_)
Return value
0
success
failure, or refusal
If the plugin returns a 1 from this function, the builder may prompt the
user with the option to forcibly remove the plugin by unloading its DLL. If
this occurs, it is possible that the plugin may then crash the designer. If
this occurs, restart the designer.
Unloading_Command_Line
As mentioned above, this field cannot be used at the same time as the
Unloading_Function field.
When this option is used, you provide a string to be executed as though it were
being run from the command line. For example, you could start Netscape by
specifying the string: netscape.exe
This method allows you to obtain the same set of parameters that would be
available to a function in a DLL. This is accomplished through the definition of
substitution variables. Whenever a &0, &1, &2, &3, &4 or &5 is found in
the string specified, it is replaced with the following:
&0
ppluginPath_
&1
ppluginStub_
&2
pdllPath_
&3
builderId_
&4
remove_
Chapter 26. Creating Plugins
393
&5
IBM_PluginInterface | PluginInterface
This is an advanced feature that is not required. This field allows you to expose
your plugin as a programmable component. You cannot use these two options in
the same .plg file. If you do not have a reason to specify either of these interfaces,
do not do so.
When either one or the other of these options is used, the function name specified
is used when other plugins interact with this plugin through a
target/command/parameters interface.
The signature of the function should be:
unsigned long __stdcall IBMtargetCommandFunction(
const IString& pluginPath_,
const IString& dllPath_,
const IString& builderId_,
const IString& target_,
const IString& command_,
IString&
arguments_);
for the IBM_ style function, where arguments_ is used for input and output.
For the non-IBM style function, the signature should be:
unsigned long __stdcall targetCommandFunction(
const char*
ppluginPath_,
const char*
pdllPath_,
const char*
pbuilderId_,
const char*
ptarget_,
const char*
pcommand_,
const char*
parguments_,
char**
ppreturnString_);
394
Function_Name
This is the name of the function that should be called in the plugin.dll when the
menu item is triggered. You can either use this field or the Command_Line field.
You may not use both. It should have the following signature:
unsigned long
pluginFunctionName(
const char*
const char*
const char*
unsigned long
const char*
ppluginPath_,
pdllPath_,
builderId_,
menuContextId_,
partsIds_);
The plugin was invoked from the menu bar, (that is, this is a
project-scoped plugin) and partsIds_ is an empty string.
The plugin was invoked for a single selected part, (that is, this is a
single-selection-scoped plugin) and partsIds_ contains the identifier
of the selected part.
partsIds_
This is a string representing the part or parts, to which the function call
should apply as indicated by the menuContextId_. Within partsIds_, each
individual part identifier is a sequence of dot-separated unsigned long
values (eg. 432.5632.612) which represent the child-parent hierarchy of the
given part. In the stated example, 612 is the ID of the part, 5632 is the ID
of its parent, and 432 is the ID of the parents parent.
Command_Line
When this option is used, you provide a string to be executed as though it was
being run from the command line. For example, you could start Netscape by
specifying the string: netscape.exe.
This method allows you to obtain the same set of parameters that would be
available to a function in a DLL. This is accomplished through the definition of
substitution variables. Whenever a &0, &1, &2, &3, &4 or &5 is found in
the string you specify, it is replaced with the following:
&0
ppluginPath_
Chapter 26. Creating Plugins
395
&1
pdllPath_
&2
builderId_
&3
menuContextId_
&4
partsIds_
&5
Using the Netscape example above, suppose the vendor provided an HTML file
with its plugin, and this particular menu item is intended to display that HTML
file. Assume also that the plugin file is located in d:\vendor\plugins, and the
HTML file is d:\vendor\plugins\htmlsrc\plugpage.html. To have the plugin
display this web page, the definition of the command line might be as follows:
netscape &0htmlsrc\plugpage.html
Menu_Name
This is either a string or a string resource id that indicates what the menu item
should be. These strings have the format:
submenu1/submenu2/.../submenuN/menuitem
where Plug-Me-In Inc. is the submenu and Who am I? is the menu item.
Menu_Info_Strings
This is a list of strings or string ids that are associated with the corresponding
submenus/menuitem as specified in Menu_Name. The association works
backwards.
For example, if you specify one submenu and one menu item in Menu_Name, but
only specify one string in Menu_Info_Strings, then the string you specify in
Menu_Info_Strings will be associated with the menu item, and the submenu will
be ignored. (It is possible that a previous menu item addition defined an info-area
string for the given menu item.)
Supported_Menus
As mentioned in Function_Name, the menuContextId_ indicates a type of menu.
Supported_Menus indicates the menus to which this particular entry should be
added.
Help_Id
If a help file has been specified, and there is help associated with this command,
provide the help id here in the ulong_panel parameter of Help_Id. If the
optional_force_window_parameter is provided and is a non-zero value, then the
help will be displayed in a full help window rather than in the default context
popup. This field takes the form of:
Help_Id:
396
ulong_panel optional_force_window_parameter
1000 1
Accelerator
This optional field specifies the accelerator to be associated with the item. It
consists of one of F1 through F12, followed by one or more modifiers (SHIFT, ALT,
CONTROL)
Note: <F1/10>, <Alt-F5/7/8/9/10>, and <Shift-F9/10> are already reserved by
the designer, and if specified will be ignored.
To use this function, provide the following information:
Accelerator:
This field, when used will look like the following sample:
Accelerator:
F8 Shift
End_of_Definition
This indicates to the parser that a function definition has ended and that a new
one may begin.
397
string_or_resId
plugin.dll mri.dll
string_or_resId
string_or_resId
helpfile.hlp
"unloadingFunction"
"command line invocation with substitution symbols &0, &1, &2, &3, &4, &5"
"IBMtargetCommandFunction"
"targetCommandFunction"
Begin_Details:
.
.
Optional text outlining the function of the plugin.
.
.
End_Details:
Function_Name:
(or)
Command_Line:
Menu_Name:
Menu_Info_Strings:
Supported_Menus:
Help_Id:
Accelerator:
End_of_definition:
"functionName1"
"command line invocation1 with substitution symbols &0, &1, &2, &3, &4"
string_or_resId
string_or_resId string_or_resId ...
menuContextId1 menuContextId2 ...
ulong_panel optional_force_window_parameter
[F1 | F2 | F3 | ... | F12] [SHIFT] [CONTROL] [ALT]
Note:
v All filenames are given relative to the location of the .plg file.
v The unloaders are optional, but if you choose to have one, you can only
have one or the other.
v Either the Function Name or Command Line may be specified.
The following is a specific example of a simple .plg file. There are some plugin
samples provided with VisualAge RPG. The files can be found in the
X:\...\WDSC\samples\vndplugs\ directory on the workstation where VisualAge
RPG is installed (where X corresponds to the drive letter).
398
"Plug-Me-In Inc."
"Who Am I?"
Who Am I?
This plugin will display information about the current
project including its directory name and file name.
End_Details:
Command_Line:
Menu_Name:
Supported_Menus:
Accelerator:
End_of_Definition
399
Return Code
Meaning
0
Some unknown error occurred and the results of the command can not be
trusted.
400
Command
Parameter(s)
Meaning/Return Value
Build
[win32|java]
Default: win32
BuildOptions
[win32|java]
Default: win32
CursoredPart
none
ExpandAll
[1]
ForceOpen
[projectName]
ProjectDir
ProjectFileName
ProjectTargetName
ProjectTitle
ProjectFileStub
IsSaveRequired
none
IsTemporary
none
MostRecentlyUsed
Open
projectName
PartId
partName [windowName
|[0|1|2]]
PromptedSave
none
401
none
Run
none
Save
none
SaveAs
projectName
SelectedParts
none
Parameter(s)
Meaning/Return Value
AllAttributes
ClassName
AllClasses
none
AllEvents
ClassName
IBMClasses
none
IconDll
ClassName
IconId
ClassName
IsType
TypeName
VendorClasses
none
Parameter(s)
Meaning/Return Value
402
partId eventName
ActionSubroutines
partId
AllEvents
partId
Children
[partId]
ClassName
partId
CreateChild
partId className
CreateFrame
ClassName
DataInfo
dataType dataLength
decimalPlaces
where:
dataType is 0=Numeric or
1=Character
dataLength is the data length
decimalPlaces is the number of
decimal places
ExtraColorAreas
see Note below
partId
FileName
partId
GetColor
partId [x]
where x corresponds to the
colorArea of the part indicated.
403
partId [x]
where x corresponds to the
fontArea of the part indicated.
404
GetRect
partId
HasFile
partId
IsColorArea
see Note below
partId [x]
where x corresponds to the
colorArea of the part indicated.
IsFontArea
partId [x]
where x represents a fontArea of
the part indicated.
Label
partId
LinkedEvents
partId
Name
partId
OpenPart
partId
OpenSettings
partId
partId
colorArea
useDefault
redMix
greenMix
blueMix
SetCursored
partId
SetDataInfo
where:
partId is the parts id
dataType is 0=Numeric or
1=Character
dataLength is the data length
decimalPlaces is the number of
decimal places
SetFileName
partId newFileName
SetFont
SetLabel
partId newLabel
SetName
partId newName
SetRect
405
SetStyles
Styles
partId [0|1]
Zoom
partId [0|1]
Note: A part will have a Foreground (1) color area, a Background (0) color area or
no color area, or it will have Extra color areas. The window part, for
example has no color areas. The Checkbox has foreground and background
color areas. The graph has Extra color areas. Therefore, 0 and 1 only
necessarily indicate background and foreground color if the part has no
Extra colors.
The following require that the source file be open in LPEX.
Table 16. Target: Subroutine
406
Command
Parameter(s)
Meaning/Return Value
DeleteActionSub
routineName
DeleteUserSub
routineName
routineName
UserSubroutines
none
Command
Parameter(s)
Meaning/Return Value
IsOn
none
TurnOn
[0|1]
Command
Parameter(s)
Meaning/Return Value
DoIt
Any_LPEX_command
IsSourceFileOpen
none
OpenSourceFile
none
Query
Any_LPEX_query
Parameter(s)
Meaning/Return Value
AddPlugin
filename
get
PluginCount
Plugin oneBasedIndex
Plugins
InvokePlugin
Parameter(s)
Meaning/Return Value
DeleteKey
key
407
key [defaultValue]
GetRect
Set
key value
SetRect
(Note that case was eliminated from the path portion of the key, and that the colon
and back-slashes were converted to underscores.) The keys and values specified
must be enclosed in quotes, since the keys can contain spaces. Thus, if you were
trying to set a string value you would use:
Set( "c__plugins_my_plugins_myplug.plg\Some relevant keyname" "The new value.")
408
There are some other commands which apply to (some of) the GUI Designers own
constituant windows. (For example, the parts catalog)
Applicable Targets:
MainWindow
This is the main Gui Designer window.
Catalog
The parts catalog.
DBRefDlg
The Define Reference Fields window.
ImportDlg
The Import Display File window.
LPEX The editor window.
Note that these only apply when the indicated window is open.
Table 21. Target: GUI Designer constituent windows
Command
Parameter(s)
Meaning/Return Value
GetHandle
none
GetIWindowPointer
none
MoveSizeTo
X Y Width Height
MoveTo
XY
Position
none
Rect
none
SetFocus
none
SetSize
Width Height
ShowSetFocus
none
Size
none
NotifyOnClose
Window handle
409
*********************************************************************
*
*
* Program ID . . : WhoAmi
*
*
*
* Description . : Sample program to illustrate the Vendor plugin
*
*
interface of VARPG.
*
*
*
*
When invoked from the Vendor menu item on the
*
*
GUI Designer this program will use the plugin
*
*
interface to gather information about the
*
*
current project and display it on a window
*
*
named MAIN.
*
*
*
* The following plugin file, WHOAMI.PLG, was specified when adding *
* this plugin to the GUI designer
*
*
*
* // WhoAmi.plg plug in file
*
* Vendor_Name:
"Plug-Me-In Inc."
*
* Plugin_Name:
"Who Am I?"
*
* Begin_Details:
*
*
Who Am I?
*
*
This plug-in will display information about the current
*
*
project including its directory name and file name.
*
* End_Details:
*
* Command_Line:
"d:\myproj\whoami\rt_win32\whoami.exe &1 &2"*
* Menu_Name:
"Plug-Me-In Inc./Who am I?"
*
* Supported_Menus:
1
*
* Accelerator:
F7 Shift
*
* End_of_Definition
*
*
*
*********************************************************************
*
D Cmd
S
255A
*
C
*Entry
Plist
C
Parm
PlugDLL
64
C
Parm
PlugID
64
410
*********************************************************************
*
*
* Window . . : Main
*
*
*
* Part . . . : PB_Cancel
*
*
*
* Event . . : Press
*
*
*
* Description: Terminate the program
*
*
*
*********************************************************************
*
C
PB_CANCEL
BEGACT
PRESS
MAIN
*
C
Move
*on
*inlr
*
C
ENDACT
*
*********************************************************************
*
*
* Window . . : Main
*
*
*
* Part . . . : Main
*
*
*
* Event . . : Create
*
*
*
* Description: Set up the PLUGDLL and PLUGID values of the
*
*
*COMPONENT part to establish communication with the *
*
GUI builder.
*
*
*
*
Execute PLUGCMD attributes to collect information
*
*
about the current project
*
*
*
*********************************************************************
*
C
MAIN
BEGACT
CREATE
MAIN
*
C
*Component Setatr
PlugDll
PlugDLL
C
*Component Setatr
PlugID
PlugID
*
C
Eval
Cmd=Project Get ProjectDir
C
*Component Setatr
Cmd
PlugCmd
C
*Component Getatr
PlugResult DirName
*
C
Eval
Cmd=Project Get ProjectFileStub
C
*Component Setatr
Cmd
PlugCmd
C
*Component Getatr
PlugResult File
*
C
Eval
Cmd=Project Get ProjectTargetName
C
*Component Setatr
Cmd
PlugCmd
C
*Component Getatr
PlugResult TAR
*
C
C
C
*Component
*Component
Eval
Setatr
Getatr
*Component
*Component
Eval
Setatr
Getatr
Write
Main
*
C
C
C
*
C
*
C
ENDACT
411
412
413
414
415
416
417
Version
The version of the application.
Title
418
Here you can use the Change server button to display a list of servers (remote
locations) used by your application. You can modify the list so that the package
will use the new names.
Select Package to begin the packaging. A progress indicator window appears.
Messages are displayed to tell you what labels to put on the various diskettes as
you create them. When packaging is completed, a completion message is
displayed.
If you package to a diskette, the target directory can only be the root directory of
the diskette; there can be no subdirectory. If you package to a directory, that
directory must not contain other files.
Select Package to begin the packaging. A progress indicator window appears. A
completion message indicates when packaging is completed.
419
420
Specify the target directory. You can specify Jar options, as well. If you select
Inlcude HTML file, the default HTML page for the application will be copied to
the target diretory. If you select Export to iSeries, the Smart Guide to export files
to the server will be displayed.
Note: If your application has multiple components, each component will have its
own jar file. Also, any GIF image files will just be copied and not included
in the jar file.
421
Specify the jar file name and the target directory. If you select Export to iSeries,
the Smart Guide to export files to the server will be displayed.
422
command in the package and follow the steps given in the dialog boxes.
The Define Server Logon, the Define AS/400 Information utility and the Define
TCP/IP Server List are installed with the runtime code. Use these utilities to
maintain and update the names and location of AS/400 resources at run time. See
Chapter 8, iSeries Connectivity, on page 193 for more information.
Installing an Application
Install the application by calling the
setup.exe
in the package and follow the steps given in the dialog boxes.
The Define AS/400 Information utility is installed optionally with the application.
Use this utility to maintain and update the names and location of AS/400
resources at run time. See Chapter 8, iSeries Connectivity, on page 193 for more
information.
423
The r parameter enables the system to record your keystrokes during the
installation process. This information is stored in the setup.iss file created in
your Windows directory. Your keystrokes will be used for silent installation.
3. Copy the setup.iss file from your Windows directory to the LAN directory
where you packaged the run time or application. For example, if c:\winnt is
your Windows directory, the setup.iss file can be found under c:\winnt.
Note: Make sure you copy the runtime setup.iss file before you install the
application to its LAN directory with the r option. Otherwise the
setup.iss file from the application install will overwrite the setup.iss file
created by the runtime install step.
4. Modify the copy of the setup.iss file in the LAN directory where you packaged
the run time or application. Change the szDir entry to point to the target drive
and directory where the run time or application package will be installed to.
5. From the client workstation, go to the LAN directory where the run time or
application was packaged. Run the following command:
setup -s
After installing the run time, shut down and restart your operating system.
424
Part 6. Appendixes
425
426
Format
Description
filename.CLASS
Binary
filename.DLL
Binary
filename.EVT
ASCII
filename.EXE
Binary
filename.HLP
Binary
filename.HTM
ASCII
filename_applet.HTM
ASCII
filename.IPF
ASCII
427
428
File name
Format
Description
filename.IPM
ASCII
filename.JAVA
ASCII
filename.LIB
Binary
filename.LST
ASCII
filename.ODF
Binary or
ASCII
filename.ODX
ASCII
filenameResources.properties
ASCII
filename.RST
ASCII
Format
Description
filename.TXC
ASCII
filename.TXM
ASCII
filename.VCX
Binary
filename.VPF
ASCII
filename.VPG
ASCII
429
430
431
The interface consists of a window with canvas, a subfile, and a push button to
load one More page of records into the subfile. The subfile size for this particular
example is 10 records. It can be changed by increasing the height of the subfile
part.
The following names are used in this example:
Part
Name
Window
WIN1
Subfile
SUB1
Push button
PSBMORE
432
The client program gets requests from the user interface. It calls a server program
that reads records from a database program and passes this data back to the client
through parameters. The subfile gets filled with the returned data.
e ds
s
extname(customer)
occurs(10)
inz
inz
Appendix B. Writing Thin Client Applications
433
D
D
D
D
D
D
nrecords
fileend
getrec
s
s
c
counter
custelem
s
s
2 0
n
inz
linkage(*server)
const(GETREC)
2 0
2 0 inz(%elem(cust))
PSBmore
counter
C
C
C
C
C
begact
call
parm
parm
parm
parm
eval
dow
occur
write
eval
enddo
eval
if
eval
eval
endif
PRESS
GETREC
win1
cust
custelem
eof
nrecords
counter=1
counter<=nrecords and not fileend
cust
sub1
counter=counter+1
%setatr(win1:
sub1:settop)=%getatr(win1
sub1:count)
eof
%setatr(win1:
psbmore:enabled)=0
fileend=*on
*
C
endact
As you can see, the client end of this code is straight forward and minimizes the
processing on the workstation.
434
invoked by the Call in the VARPG client program and ends after each request. The
Return operation code is used to end the program and keep the invocation
environment. This will benefit performance in subsequent calls, since no
initialization is needed. This also requires the program to be created to run in a
named activation group, since *NEW would destroy the invocation environment
and free storage immediately.
At the top of the calculation specifications, the PLIST operation code defines the
parameters being passed to this program. The DO loop reads from the database
file and puts the data into data structure CUST, which will be passed back as a
parameter to the client program. The other two parameters just indicate the status
of the database access:
v EOF will be set to ON if indicator 99 gets set by the READ statement.
v Count contains the number of records being passed back to the client in data
structure CUST.
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
*entry
count
count
plist
parm
parm
parm
parm
eval
occur
read
dow
eval
occur
read
enddo
if
eval
eval
endif
return
cust
custelem
eof
count
count=1
cust
customer
count<custelem and not *in99
count=count+1
cust
customer
9999
9999
*IN99
count=count-1
eof=*on
When compiling the server program, be sure not to specify *NEW for Activation
Group. If *NEW is specified (the default), any storage allocated by this program is
freed when RETURN is executed. One of the benefits of this thin client example is
the reusability of the server application by different applications. Even traditional
5250 applications can use the server modules for database access. This approach
certainly makes it easier to maintain applications since changes in a server module
are reflected in all applications that use it.
435
The next state is entered when a GUI event requests more data. (See Figure 114 on
page 432 for the client interface.) The three events that trigger the action
subroutine are:
v Create event from the window
v Press event from the More... push button
v Pageend event from the subfile
The client program then waits on data queue I for data. The server program
accesses the database file and gets the data.
436
In the third state, the server program fills data queue I. The client program
becomes active and puts the data into the subfile. After this, the program returns
to its initial state and the process starts again.
437
After creating the data queues, the client program calls the server program and
passes it the 2 data queue names. The server program waits on data queue O for
commands from the client program.
The client program gets activated by GUI events and then sends requests to data
queue O. It then waits on data queue I until this data queue is filled by the
server job.
When the client program gets a termination request, the *TERMSR subroutine is
invoked to signal the server program to end and the 2 data queues will be deleted.
438
D*
D* Parameters for data queue APIs
D msg_sz
s
5 0
D Name_of_Q
s
10
D Name_of_Lb
s
10
D count
s
2 0
D maxlen
s
10 0
D wait_time
s
5 0
inz(%size(custds:*all))
WIN1
BEGACT
CREATE
WIN1
Get client IP address to build unique data queue names.
entipadd will contain the clients full host name and IP address.
eval
entipadd =
%GetAtr(*component:
*component:hostname)
hostname returns the string hostname IPAddress.
We only use the IPAddress portion of the returned string.
Substring the second part of the returned string:
eval
entipadd = %subst(entipadd: %scan( :
entipadd)+1)
Create the names for the I and O data queues.
Use the last 5 characters of IPAddress and add I or O.
eval
qnameI= qname1 +
%subst(entipadd:%len
(%trim(entipadd))-4:5) + I
eval
qnameO= qname1 +
%subst(entipadd:%len
(%trim(entipadd))-4:
5) + O
Set up command parameters to create data queues.
eval
cmd=%trim(%trimr(cmd1) +
qnamei + cmd2 +
%editc(%size(
CustDS:*all):Z) + ))
Create the data queues.
call
QCMDEXC
98
parm
cmd
parm
cmdlen
eval
eval
call
parm
parm
cmd=*blank
cmd=%trim(%trimr(cmd1) +
qnameo + cmd2 +
%editc(%size(
CustDS:*all):Z) + ))
QCMDEXC
cmd
cmdlen
98
98
439
C*
C
C
C*
exsr
endact
callhost
440
NAME_OF_LB
10
parm
23
MSG_SZ
5 0
parm
rinfo
Wait on data queue I for data.
Expecting processing data here in DS rinfo.
eval
wait_time=-1
eval
MSG_sz=23
call
QRCVDTAQ
parm
qnamei
parm
QGPL
NAME_OF_LB
parm
MSG_SZ
parm
rinfo
parm
WAIT_TIME
Expecting data from database here.
eval
Msg_sz=%size(custds:*all)
call
QRCVDTAQ
parm
QNAMEi
parm
QGPL
NAME_OF_LB
parm
MSG_SZ
parm
CustDS
parm
WAIT_TIME
For as many records as the server has read, fill the subfile.
eval
count=1
dow
count<=nrecords and not fileend
count
occur
CustDS
write
sub1
eval
count=count+1
enddo
eval
%setatr(win1:
C
sub1:settop)=
C
%getatr(win1:
C
sub1:count)
C* If end-of-file was signaled, disable the push button.
C
if
eof
C
eval
%setatr(win1:
C
psbmore:enabled)=0
C
eval
fileend=*on
C
endif
C
endif
C* End of user subroutine
C
endsr
Terminate subroutine
A termination request is sent to server program DATAQ and the 2 data queues are
deleted.
C*
C*
C
C*
C
C
C
C
C
C
C*
C
C
C
C
C
C
C
C
C
C
C
C
C*
C
NAME_OF_LB
10
parm
23
MSG_SZ
5 0
parm
rinfo
Delete both data queues
eval
cmd=*blank
eval
cmd=%trim(%trimr(cmde) +
qnamei + ))
call
QCMDEXC
98
parm
cmd
parm
cmdlen
eval
cmd=*blank
eval
cmd=%trim(%trimr(cmde) +
qnameo + ))
call
QCMDEXC
98
parm
cmd
parm
cmdlen
Application ends
endsr
441
When the server program gets signaled that a termination is requested, the LR
indicator will be set on and the DO loop will end. This will end the program. Any
other cleanup will be managed by the client program.
442
Beginning of mainline
*entry
plist
parm
parm
DO loop runs forever until
terminates
dow
Wait for client program to
eval
eval
call
parm
parm
parm
parm
parm
qnamei
qnameo
client program signals that it
not *inlr
signal that it needs data
wait_time=-1
MSG_sz=23
QRCVDTAQ
qnameo
NAME_OF_LB
MSG_SZ
rinfo
WAIT_TIME
9999
9999
C*
C*
C*
C*
C
C
C
C
C
C*
C
C
C
C
C
C
C*
C*
C
C
C*
C
C
C*
C*
98
98
end
enddo
End of MAINLINE
443
This subfile only fits 8 records on the screen because each record occupies 2 rows
on the subfile. The program source for this application follows:
H* Program to list customer records
F* Workstn file containing DSPF
Fgetrecs
cf
e
workstn sfile(sub1:recnum)
D* Data structure to pass data from server program to the subfile
Dcust
e ds
extname(customer) occurs(8)
D
inz
Deof
s
1
inz(*off)
Dnrecords
s
2 0
Dfileend
s
1
inz(*off)
Dcount
s
2 0
Dcustelem
s
2 0 inz(%elem(cust))
Drecnum
s
5 0 inz(1)
* Main program to invoke subfile sub routine and end the program
* In91 indicates that database file has not reached the end
C
EVAL
*IN91=*ON
C
exsr
more
C
eval
*inlr=*on
c
C
more
BEGsr
* LOOP to fetch more data and display in subfile
C
dow
not *in03
* Call server program to get data first time and when page down
* is used.
C
if
*in91
C
call
GETREC
C
parm
cust
C
parm
custelem
C
parm
eof
C
parm
nrecords
C
eval
count=1
* recnum1 is sbfrcdnbr in subfile control record, to position top record
* to be shown on screen
C
EVAL
RECNUM1=RECNUM
* Loop to fill subfile with new records
C
dow
count<=nrecords
C
count
occur
cust
444
C
C
C
C
*
*
C
C
C
*
C
C
C
C
*
*
C
C
C
C
*
C
write
sub1
eval
count=count+1
eval
recnum=recnum+1
enddo
After the set of records is added to subfile, display it, plus header
and footer record formats
write
record1
write
footer
exfmt
sub1ctl
Handle none pagedown keys
else
read
sub1ctl
99
endif
if
eof=*on
IN90 enables PAGEDOWN key for additional records to be read.
At file end it gets disabled.
eval
*in90=*on
eval
recnum=recnum1
endif
enddo
Leave the LOOP when Exit requested
ENDSR
445
446
Be sure to include the .VPG extension in the filename so you can benefit from the
editors tokenizing and syntax checking of your source.
To run the FVDFNFE compiler, issue the compiler command from an MS-DOS
command prompt. The syntax of the command is:
fvdfnfe filename.VPG [/compiler_option1 ... /compiler_optionn]
Note: You must include the .VPG extension in the source file name; it is not
assumed.
The compiler options, which you can type in upper- or lowercase, are optional.
They are as follows:
Option Description
/BL name
Link library name. If more than one, enclose in double quotes.
/D
/GL 1-99
Generation severity level
/L
/LI
Indentation
/LX
/LV
/LD
/LC
/LE
/LM2
/LS
/LP 10-99
Lines per page (listing)
/HCU Host cache enabled
/HCR
/RF
Fix numeric
447
/RN
Allow null
Truncate numeric
/TI
/SB Name
SQL bind file name
/SF XX
SQL format for date/time columns
/SI XX (RR RS CS UR) SQL isolation level
/SN Name
SQL database name
/SP Name
SQL package file name
/SR
/SU
Database user id
/SUP
Database password
/SVC
/SVG
DEFINE_FILE
SERVER_ALIAS_NAME(MYAS400)
REMOTE_LOCATION_NAME(TORAS40Z)
NETWORK_PROTOCOL(*TCP)
TEXT(Development - RST)
FILE_ALIAS_NAME(CUSTOMER)
REMOTE_FILE_NAME(PRODUCT/CUSTMAST)
SERVER_ALIAS_NAME(MYAS400)
TEXT()
448
SSL Considerations
v A good knowledge of SSL is required for setup. You should know how to use
the Digital Certificate Manager (DCM) program on the iSeries 400 server to
perform SSL-related tasks, such as generating system certificates. For
information on the DCM program, invoke its online help or go to the
Information Center at URL http://www.ibm.com/eserver/iseries/infocenter.
v Ensure that you adhere to import and export regulations. IBM iSeries Client
Encryption products provide SSL version 3.0 encryption support using
non-exportable 128-bit for U.S. and Canada use only and exportable 56bit for
international use. In customer configurations where Client Encryption products
might be downloaded across national boundaries, the customer is responsible for
ensuring that the non exportable products are not made available outside the
U.S. and Canada. Both the non-exportable and exportable Client Encryption
products can be used in combination to allow the appropriate Client Encryption
product to be downloaded on different Web sites.
Prerequisites
The following prerequisites must be met before setting up SSL:
v Software:
Crytographic Access Provider licensed program (5769-AC1, 5769-AC2, or
5769-AC3)
IBM iSeries Client Encryption program (5722-CE2 or 5722-CE3) where
5722-CE2 (56-bit) is for use in countries other than the U.S. or Canada, and
5722-CE3 (128-bit) is for use only in the U.S. and Canada.
v Hardware:
IBM HTTP Server for iSeries (5722-DG1)
Base operating system option 34 Digital Certificate Manager (DCM)
v Authorization:
Provide proper authorizations for users to access the SSL files. Follow these
steps to change the authority:
1. Enter the command:
wrklnk /QIBM/ProdData/HTTP/Public/jt400/*
449
2. Access the iSeries 400 Administration server by typing in your servers URL
address and port number. For example:
http://your.server.name:2001/
The proper security officer authority, plus *secadm and *allobj authorities are
needed.
3. Enter your iSeries 400 user ID and password.
4. From the AS/400 Tasks page, access DCM by selecting the DCM link.
Obtain a system certificate for your iSeries 400 server from the Digital Certificate
Manager program:
Click on the ? icon for instructions on obtaining a system certificate. You can either
obtain the system certificate from a trusted Certificate Authority (CA) or build
your own.
v To obtain a system certificate from a trusted CA:
Note: This is what you should use if your application is an internet application
and you need to distribute your run time.
Select a CA. You can get a certificate from one of the following companies:
VeriSign, Inc.
Integration Financial Network
Thawte Consulting
RSA Data Security
Obtain request data for submission to the trusted CA from DCM. Refer to the
DCM help for the exact steps you need to follow.Your CA will process your
request form and provide you with the certificate. To install it onto your system,
use the Receive a System Certificate option.
v To obtain your own system certificate:
Note: This should only be used for an intranet because the run time created can
only be used for your specific iSeries 400 server.
1. Create your CA on the iSeries 400 server.
2. Generate the system certificate from your own CA.
For information on creating a CA, on the DCM page click on Certificate
Authority.
Apply the system certificate to the following server applications:
QIBM_OS400_QZBS_SVR_CENTRAL
QIBM_OS400_QZBS_SVR_DATABASE
QIBM_OS400_QZBS_SVR_DTAQ
QIBM_OS400_QZBS_SVR_NETPRT
QIBM_OS400_QZBS_SVR_RMTCMD
QIBM_OS400_QZBS_SVR_SIGNON
QIBM_OS400_QZBS_SVR_FILE
QIBM_OS400_QRW_SVR_DDM_DRDA
450
451
File to Download
sslightx.zip
sslightu.zip
If you built your own certificate, perform the following steps to download the CA
certificate:
1. Download SSLTools.jar from the directory in which you downloaded the SSL
Client Encryption.
2. Add SSLTools.jar and sslightu.zip to your CLASSPATH statement.
3. Create a temporary directory. For example, c:\tempkey.
4. Create the following subdirectory under c:\tempkey:
com\ibm\as400\access
5. From the tempkey directory, run the following command in one line:
java com.ibm.sslight.nlstools.keyrng com.ibm.as400.access.KeyRing
connect <systemname>:<port>
Where <systemname> is the name of your iSeries 400 server and <port> is
your port number.
Note: The server port can be any of the host servers to which you have access.
For example, you can use 9476, which is the default port for the secure
sign-on server on the iSeries 400 server. When you are prompted to enter
a password, enter toolbox. This is the only password that works. The
SSL tool then connects to the iSeries 400 server and lists the certificates it
finds.
6. Enter the CA certificate number. Be sure to use the CA certificate and not the
site certificate. A message will be issued stating that the certificate is being
added to com.ibm.as400.access.KeyRing.class.
7. Delete the file SSLTools.jar.
A KeyRing.class file has been created in the directory.
Create a customized varpg.jar file by following the instructions below:
1. Create a temporary directory. For example, c:\tempjar.
2. Copy the file sslightu.zip to c:\tempjar.
452
You will find the meta-inf and com\ibm\sslight subdirectories created for you
in c:\tempjar.
4. If you built your own certificate:
a. Under subdirectory c:\tempjar\com\ibm add subdirectory \as400\access.
b. Copy the KeyRing.class file in c:\tempkey\com\ibm\as400\access
subdirectory to the c:\tempjar\com\ibm\as400\access subdirectory.
5. Copy the varpg.jar file into c:\tempjar.
6. From c:\tempjar, run the following command:
jar uvf varpg.jar -C ./ com
Note: C is in uppercase.
Running this command updates the varpg.jar file so that it can be used with
your SSL-enabled VARPG applications. This will also work for regular, non
SSL-enabled applications.
Enable your application to use SSL:
1. Rename the varpg.jar in your VARPG install directory \WDSC\JAVA .
2. Compile your application with the /SSL user-defined option in the Build
options dialog.
3. Run the application with the customized file varpg.jar.
453
454
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the users responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
Lab Director
IBM Canada Ltd. Laboratory
B3/KB7/8200/MKM
Copyright IBM Corp. 1994, 2005
455
AS/400
CUA
DB2 Connect
OS/400
WebSphere
AS/400e
DATABASE 2
DB2 Universal Database
SQL/DS
400
Java and all Java-based trademarks are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States and/or other countries.
Lotus is a trademark of Lotus Development Corporation in the United States, or
other countries, or both.
ActiveX, Microsoft, Windows, and Windows NT are trademarks or registered
trademarks of Microsoft Corporation in the United States, or other countries, or
both.
Other company, product, and service names may be trademarks or service marks
of others.
456
Glossary
This glossary includes terms and definitions from:
v The American National Dictionary for Information Systems ANSI X3.172-1990,
copyright 1990 by the American National Standards Institute (ANSI). Copies
may be purchased from the American National Standards Institute, 1430
Broadway, New York, New York, 10018. Definitions are defined by the symbol
(A) after the definition.
v The Information Technology Vocabulary developed by Subcommittee 1, Joint
Technical Committee 1, of the International Organization for Standardization and
the International Electrotechnical Committee (ISO/IEC JTC1/SC1). Definitions of
published parts of this vocabulary are identified by the symbol (|) after the
definition; definitions taken from draft international standards, committee drafts,
and working papers being developed by ISO/IEC JTC1/SC1 are identified by
the symbol (T) after the definition indicating that the final agreement has not yet
been reached among participating National Bodies of SC1.
v IBM Dictionary of Computing , New York: McGraw-Hill, 1994.
v Object-Oriented Interface Design IBM Common User Interface Guidelines,
SC34-4399-00, Carmel, IN: Que Corporation, 1992.
A
action. (1) Synonym for action subroutine. (2) An executable program or command file used to manipulate a projects
parts or participate in a build.
action subroutine. Logic that you write to respond to a specific event.
active window. The window with which a user is currently interacting. This is the window that receives keyboard
input.
activeX part. A part that adds ActiveX control objects to the project. VARPG applications can then access their
attributes and monitor for events.
anchor. Any part that you use as a reference point for aligning, sizing, and spacing other parts.
animation control part. A part that allows the playback of video files, with the AVI extension, in Windows, or the
playback of animated GIF sequences in Java applications.
API. Application programming interface.
applet. A program that is written in Java and runs inside of a Java-compatible browser or AppletViewer.
application. A collection of software components used to perform specific user tasks on a computer.
application programming interface (API). A functional interface supplied by the operating system or a separately
orderable licensed program that allows an application program written in a high-level language to use specific data
or functions of the operating system or the licensed program.
ASCII (American National Standard Code for Information Interchange). The standard code, using a coded
character set consisting of 7-bit coded characters (8 bits including parity check), that is used for information
interchange among data processing systems, data communication systems, and associated equipment. The ASCII set
consists of control characters and graphic characters. (A)
B
BMP. The file extension of a bitmap file.
457
build. The process by which the various pieces of source code that make up components of a VARPG application
are compiled and linked to produce an executable version of the application.
button. (1) A mechanism on a pointing device, such as a mouse, used to request or start an action. (2) A graphical
mechanism in a window that, when selected, results in an action. An example of a button is an OK push button that,
when selected, initiates an action.
C
calendar part. A part that adds a calendar that can be modified by the user to include text, color and other
attributes.
canvas part. A part onto which you can point and click various other parts, position them, and organize them to
produce a graphical user interface. A canvas part occupies the client area of either a window part or a notebook page
part. See also notebook page with canvas part and window with canvas part.
check box part. A square box with associated text that represents a choice. When a user selects a choice, an
indicator appears in the check box to indicate that the choice is selected. The user can clear the check box by
selecting the choice again. In VisualAge RPG, you point and click on a check box part in the parts palette or parts
catalog and click it onto a design window.
click. To press and release a mouse button without moving the pointer off of the choice or object. See also
double-click.
client. (1) A system that is dependent on a server to provide it with data. (2) The PWS on which the VARPG
applications run. See also DDE client.
client area. The portion of the window that is the users workspace, where a user types information and selects
choices from selection fields. In primary windows, the area where an application programmer presents the objects
that a user works on.
client/server. The model of interaction in distributed data processing in which a program at one site sends a request
to a program at another site and awaits a response. The requesting program is called a client; the answering program
is called a server. See also client, server, DDE client, DDE server.
clipboard. An area of storage provided by the system to hold data temporarily. Data in the clipboard is available to
other applications.
cold-link conversation. In DDE, an explicit request made from a client program to a server program. The server
program responds to the request. Contrast with hot-link conversation.
color palette. A set of colors that can be used to change the color of any part in your applications GUI.
combination box. A control that combines the functions of an entry field and a list box. A combination box contains
a list of objects that a user can scroll through and select from to complete the entry field. Alternatively, a user can
type text directly into the entry field. In VisualAge RPG, you can point and click on a combination box part in the
parts palette or parts catalog and click it onto a design window.
Common User Access architecture (CUA architecture). Guidelines for the dialog between a human and a
workstation or terminal.
compile. To translate a source program into an executable program (an object program).
component. A functional grouping of related files within a project. A component is created when the NOMAIN and
EXE keywords are not present on the control specifications.
component reference part. A part that enables one component to communicate with another component in a
VARPG application.
*component part. A part that is the part representation of the component. One *component part is created for
each component automatically, and it is invisible.
CONFIG.SYS. The configuration file, located in the root directory of the boot drive, for the DOS, OS/2, or Windows
operating systems. It contains information required to install and run hardware and software.
458
configuration. The manner in which the hardware and software of an information processing system are organized
and interconnected (T).
container part. A part that stores related records and displays them in a details, icon, or tree view.
CUA architecture. Common User Access architecture.
cursor. The visible indication of the position where user interaction with the keyboard will appear.
D
database. (1) A collection of data with a given structure for accepting, storing, and providing, on demand, data for
multiple users. (T) (2) All the data files stored in the system.
data object. An object that conveys information, such as text, graphics, audio, or video.
DBCS. Double-byte character set.
DDE. Dynamic data exchange.
DDE client. An application that initiates a DDE conversation. Contrast with DDE server. See also DDE client part,
DDE conversation.
DDE client part. A part used to exchange data with other applications, such as spreadsheet applications, that
support the dynamic data exchange (DDE) protocol.
DDE conversation. The exchange of data between a DDE client and a DDE server. See also cold-link conversation and
hot-link conversation.
DDE server. An application that provides data to another DDE-enabled application. Contrast with DDE client. See
also DDE conversation.
default. A value that is automatically supplied or assumed by the system or program when no value is specified by
the user. The default value can be assigned to a push button or graphic push button.
default action. An action that will be performed when some action is taken, such a pressing the Enter key.
dereferencing. The action of removing the association between a part and an AS/400 database field.
design window. The window in the GUI designer on which parts are placed to create a user interface.
details view. A standard contents view in which a small icon is combined with text to provide descriptive
information about an object.
dimmed. Pertaining to the reduced contrast indicating that a part can not be selected or directly manipulated by the
user.
direct editing. The use of techniques that allow a user to work with an object by dragging it with a mouse or
interacting with its pop-up menu.
DLL. Dynamic link library.
double-byte character set (DBCS). A set of characters in which each character is represented by 2 bytes. Languages
such as Japanese, Chinese, and Korean, which contain more symbols than can be represented by 256 code points,
require double-byte character sets. Because each character requires 2 bytes, the typing, displaying, and printing of
DBCS characters requires hardware and programs that support DBCS. Four double-byte character sets are supported
by the system: Japanese, Korean, Simplified Chinese, and Traditional Chinese. Contrast with single-byte character set
(SBCS).
double-click. To quickly press a mouse button twice.
drag. To use a mouse to move or to copy an object. For example, a user can drag a window border to make it larger
by holding a button while moving the mouse. See also drag and drop.
drag and drop. To directly manipulate an object by moving it and placing it somewhere else using a mouse.
Glossary
459
drop-down combination box. A variation of a combination box in which a list box is hidden until a user takes
explicit acts to make it visible.
drop-down list. A single selection field in which only the current choice is visible. Other choices are hidden until
the user explicitly acts to display the list box that contains the other choices.
dynamic data exchange (DDE). The exchange of data between programs or between a program and a datafile
object. Any change made to information in one program or session is applied to the identical data created by the
other program. See also DDE conversation, DDE client, DDE server.
Dynamic link library (DLL). A file containing executable code and data bound to a program at load time or run
time, rather than during linking. The code and data in a dynamic link library can be shared by several applications
simultaneously.
E
EBCDIC. Extended binary-coded decimal interchange code. A coded character set of 256 8-bit characters.
emphasis. Highlighting, color change, or other visible indication of conditions relative to an object or choice that
affects a users ability to interact with that object or choice. Emphasis can also give a user additional information
about the state of a choice or an object.
entry field part. An area on a display where a user can enter information, unless the field is read-only. The
boundaries of an entry field are usually indicated. In VisualAge RPG, you point and click on an entry field part in
the parts palette or parts catalog and click it onto a design window.
error logging. Keeps track of errors in an error log. The editor takes you to the place in the source where the error
occurred.
event. A signal generated as a result of a change to the state of a part. For example, pressing a button generates a
Press event.
exception. (1) In programming languages, an abnormal situation that may arise during execution, that may cause a
deviation from the normal execution sequence, and for which facilities exist in a programming language to define,
raise, recognize, ignore, and handle it. (I) (2) In VisualAge RPG, an event or situation that prevents, or could prevent,
an action requested by a user from being completed in a manner that the user would expect. Exceptions occur when
a product is unable to interpret a users input.
EXE. The extension of an executable file.
EXE module. An EXE module consists of a main procedure and subprocedures. It is created when the EXE keyword
is present on the control specification. All subroutines (BEGSR) must be local to a procedure. The EXE must contain a
procedure whose name matches the name of the source file. This will be the main entry point for the EXE, that is, the
main procedure.
export. A function that converts an internal file to some standard file format for use outside of an application.
Contrast with import.
F
field. (1) An identifiable area in a window, such as an entry field where a user types text. (2) A group of related
bytes, such as a name or amount, that is treated as a unit in a record.
file. A collection of related data that is stored and retrieved by an assigned name. A file can include information
that starts a program (program-file object), contains text or graphics (data-file object), or processes a series of
commands (batch file).
focus. Synonym for input focus.
font palette. A set of fonts that can be used to change the font of a part in your applications GUI.
460
G
graph part. A part that allows the user to add a graph to the GUI. The graph styles available are line, bar, line and
bar, or pie chart.
graphical user interface (GUI). A type of user interface that takes advantage of high-resolution graphics. A
graphical user interface includes a combination of graphics, the object-action paradigm, the use of pointing devices,
menu bars and other menus, overlapping windows, and icons.
graphic push button part. A push button, labeled with a graphic, that represents an action that will be initiated
when a user selects it. Contrast with push button part.
group box part. A rectangular frame around a group of controls to indicate that they are related and to provide an
optional label for the group. In VisualAge RPG, you point and click on a group box part in the parts palette or parts
catalog and click it onto a design window.
group marker. A mark that identifies a part as being the first one in a group. When a user moves the cursor
through a group of parts and reaches the last part, the cursor returns to the first part in the group.
GUI designer. A suite of tools used to create interfaces by dragging and dropping parts from the parts palette to the
design window.
H
hide button. A button on a title bar that a user clicks on to remove a window from the workplace without closing
the window. When the window is hidden, the state of the window, as represented in the window list, changes.
Contrast with maximize button and minimize button.
horizontal scroll bar part. A part that adds a horizontal scroll bar to a window. This part allows users to scroll
through a pane of information, from left-to-right or right-to-left.
hot-link conversation. In DDE, an automatic update of a client program by a server program when data changes on
the server. Contrast with cold-link conversation.
I
ICO. The file extension of an icon file.
icon. A graphical representation of an object, consisting of an image, image background, and a label.
icon view. A standard contents view in which each object contained in a container is displayed as an icon.
image part. A part used to display a picture, from a BMP or ICO file, on a window.
import. A function that converts AS/400 display file objects to the appropriate VARPG part. Contrast with export.
inactive window. A window that can not receive keyboard input at a given moment.
index. The identifier of an entry in VARPG parts such as list boxes or combination boxes.
information area. A part of a window in which information about the object or choice that the cursor is on is
displayed. The information area can also contain a message about the normal completion of a process. See also status
bar.
Information Presentation Facility (IPF). A tool used to create online help on a programmable workstation.
Information Presentation Facility (IPF) file. A file in which the applications help source is stored.
INI. The file extension for a file in the OS/2 or Windows operating system containing application-specific
information that needs to be preserved from one call of an application to another.
input focus. The area of a window where user interaction is possible from either the keyboard or the mouse.
Glossary
461
input/output (I/O). Data provided to the computer or data resulting from computer processing.
IPF. Information Presentation Facility
item. In dynamic data exchange, a unit of data. For example, the top left cell position in a spreadsheet is row 1,
column 1. This cell position may be referred to as item R1C1.
J
JAR files (.jar). In Java, abbreviation for Java ARchive. A file format that is used for aggregating many files into
one.
Java. An object-oriented programming language for portable interpretive code that supports interaction among
remote objects. Java was developed and specified by Sun Microsystems, Incorporated.
java bean part. A part that allows VARPG applications to access Sun Microsystems JavaBeans.
JavaBeans. In Java, a portable, platform-independent reusable component model.
Java Database Connectivity (JDBC). An industry standard for database-independent connectivity between Java and
a wide range of databases. The JDBC provides a call-level application programming interface (API) for SQL-based
database access.
Java 2 Software Development Kit (J2SDK). Software that Sun Microsystems distributes for Java developers. This
software includes the Java interpreter, Java classes, and Java development tools. The development tools include a
compiler, debugger, dissassembler, AppletViewer, stub file generator, and documentation generator.
Java Native Interface (JNI). A programming interface that allows Java code that runs inside of a Java Virtual
Machine (JVM) to interoperate with functions that are written in other programming languages.
Java Runtime Environment (JRE). A subset of the Java Developer Kit for end users and developers who want to
redistribute the JRE. The JRE consists of the Java Virtual Machine, the Java Core Classes, and supporting files.
Java Virtual Machine (JVM). The part of the Java Runtime Environment (JRE) that is responsible for interpreting
Java bytecodes.
L
link event. An event that a target part receives whenever the state of a source part changes.
list box part. A control that contains scrollable choices that a user can select. In VisualAge RPG, you can point and
click on a list box part in the parts palette or parts catalog and click it onto a design window.
M
main procedure. A main procedure is a subprocedure that can be specified as the program entry procedure and
receives control when it is first called. A main procedure is only produced when creating an EXE. See EXE module
main source section. In a VARPG program, the main source section contains all the global dedfinitions for a
module. For a component, this section also includes the action and user subroutines.
main window. See primary window.
manipulation button. See mouse button 2.
maximize button. A button on the rightmost part of a title bar that a user clicks on to enlarge the window to its
largest possible size. Contrast with minimize button, hide button.
media panel part. A part used to give the user control over other parts. For example, a media panel part can be
used to control the volume of a media part.
media part. A part that gives a program the ability to process sound files and video files.
462
menu. A list of choices that can be applied to an object. A menu can contain choices that are not available for
selection in certain contexts. Those choices are dimmed.
menu bar part. The area near the top of a window, below the title bar and above the rest of the window, that
contains choices that provide access to other menus. In VisualAge RPG, you can point and click on a menu bar part
in the parts palette or parts catalog and click it onto a design window.
menu item part. A part that is a graphical or textual item on a menu. A user selects a menu item to work with an
object in some way.
message. (1) Information not requested by a user but displayed by a product in response to an unexpected event or
when something undesirable could occur. (2) A communication sent from a person or program to another person or
program.
message file. A file containing application messages. The file is created from the message source file during the
build process. See also build.
message subfile part. A part that can display predefined messages or text supplied in program logic.
migrate. (1) To move to a changed operating environment, usually to a new release or version of a system. (2) To
move data from one hierarchy of storage to another.
MID. The file extension of a MIDI file.
MIDI file. Musical Instrument Digital Interface file.
minimize button. A button, located next to the rightmost button in a title bar, that reduces the window to its
smallest possible size. Contrast with maximize button and hide button.
mnemonic. A single character, within the text of a choice, identified by an underscore beneath the character. See also
mnemonic selection.
mnemonic selection. A selection technique whereby a user selects a choice by typing the mnemonic for that choice.
mouse. A device with one or more push buttons used to position a pointer on the display without using the
keyboard. Used to select a choice or function to be performed or to perform operations on the display, such as
dragging or drawing lines from one position to another.
mouse button. A mechanism on a mouse used to select choices, initiate actions, or manipulate objects with the
pointer. See also mouse button 1 and mouse button 2.
mouse button 1. By default, the left button on a mouse used for selection.
mouse button 2. By default, the right button on a mouse used for manipulation.
mouse pointer. Synonym for cursor.
multiline edit (MLE) part. A part representing an entry field that allows the user to enter multiple lines of text.
N
navigation panel. A group of buttons that can be used to control the visible selection of records in a subfile.
NOMAIN module. A module that contains only subprocedures. There are no action or standalone user subroutines
in it. A NOMAIN module is created when the NOMAIN keyword is present on the control specification.
notebook part. A graphical representation of a notebook. You can add notebook pages to the notebook part and
then group the pages into sections separated by tabbed dividers. In Windows, a notebook is sometimes referred to as
a Windows tab control. See also notebook page part, notebook page with canvas part.
notebook page part. A part used to add pages to a notebook part. See also notebook.
notebook page with canvas part. A combination of a notebook page part and a canvas page part. See also notebook,
canvas part.
Glossary
463
O
object. (1) A named storage space that consists of a set of characteristics that describe itself and, in some situations,
data. An object is anything that exists in and occupies space in storage and on which operations can be performed.
Some examples of objects are programs, files, libraries, and folders. (2) A visual component of a user interface that a
user can work with to perform a task. An object can appear as text or an icon.
object-action paradigm. A pattern for interaction in which a user selects an object and then selects an action to
apply to that object.
object-oriented programming. A method for structuring programs as hierarchically organized classes describing the
data and operations of objects that may interact with other objects. (T)
object program. A target program suitable for execution. An object program may or may not require linking. (T)
odbc/jdbc part. A part that allows VAPRG applications to access and process database files that support the
Windows ODBC API or Sun Microsystems JDBC API.
operating system. A collection of system programs that control the overall operation of a computer system.
outline box part. A part that is a rectangular box positioned around a group of parts to indicate that all the parts
are related.
P
package. A function used to collect all the parts of a VARPG application together for distribution.
parts. Objects that make up the GUI of a VARPG application.
parts catalog. A storage space for all of the parts used to create graphical user interfaces for VARPG applications.
parts palette. A collection of parts that are most appropriate for building the current graphical user interface for an
application. When you finish one GUI, you can wipe the palette clean and add parts from the parts catalog that you
require for the next application.
plugin. A function created by the user or an outside vendor that can be used in VARPG programs.
point and click. (1) A selection method which is used to copy a part from the parts palette or catalog to the GUI
design window, the icon view, or the tree view. (2) To place a part in any of the desired views, point to and click on
the part, then move the cursor to the chosen window and point the cursor and click where you want the part to
appear. In the icon and tree views, the part will be placed on the parent part, and you will then have to move it
where you would like it to appear in the design window.
pop-up menu. A menu that, when requested, appears next to the object with which it is associated. It contains
choices appropriate for the object in its current context.
pop-up menu part. A part that, when added to an object on your interface, appears next to the object with which it
is associated when requested. You can point and click on a pop-up menu part in the parts palette or parts catalog
and click it onto a design window.
pop-up window. A movable window, fixed in size, in which a user provides information required by an application
so that it can continue to process a user request. Synonymous with secondary window.
primary window. The window in which the main interaction between the user and the application takes place.
Synonymous with main window.
procedure. A procedure is any piece of code that can be called with the CALLP operation code.
procedure interface definition. A procedure interface definition is a repetition of the prototype information within
the definition of a procedure. It is used to declare the entry parameters for the procedure and to ensure that the
internal definition of the procedure is consistent with the external definition (the prototype)
464
programmable workstation (PWS). A workstation that has some degree of processing capability and that allows a
user to change its functions.
progress bar part. A part that can be used to indicate graphically the progress of a process, such as copying files,
loading a database, and so on.
progress indicator. One or more controls used to inform a user about the progress of a process.
project. The complete set of data and actions needed to build a single target, such as dynamic link library (DLL) or
an executable file (EXE).
prompt. (1) A visual or audible message sent by a program to request the users response. (T) (2) A displayed
symbol or message that requests input from the user or gives operational information. The user must respond to the
prompt in order to proceed.
properties notebook. A graphical representation that resembles a bound notebook containing pages separated into
sections by tabbed divider pages. Select the tabs of a notebook to move from one section to another.
prototype. A prototype is a definition of the call interface. It includes information such as: whether the call is bound
(procedure) or dynamic (program); the external name; the number and nature of the parameters; which parameters
must be passed; the data type of any return value (for a procedure)
pull-down menu. A menu that extends from a selected choice on a menu bar or from a system-menu symbol. The
choices in a pull-down menu are related to one another in some manner.
push button part. A button labeled with text that represents an action that starts when a user selects the push
button. You can point and click on a push button part in the parts palette or parts catalog and click it onto a design
window. See also graphic push button part.
PWS. Programmable workstation.
R
radio button part. A circle with text beside it. Radio buttons are combined to show a user a fixed set of choices from
which only one can be selected. The circle is partially filled when a choice is selected. You can point and click on a
radio button part in the parts palette or parts catalog and click it onto a design window.
reference field. An AS/400 database field from which an entry field part can inherit its characteristics.
restore button. A button that appears in the rightmost corner of the title bar after a window has been maximized.
When the restore button is selected, the window returns to the size and position it was in before it was maximized.
See also maximize button.
S
SBCS. Single-byte character set.
scroll bar. A part that shows a user that more information is available in a particular direction and can be moved
into view by using a mouse or the page keys.
secondary window. A window that contains information that is dependent on information in a primary window,
and is used to supplement the interaction in the primary window. See also primary window. Synonym for pop-up
window.
secure sockets layer (SSL). A popular security scheme that was developed by Netscape Communications Corp. and
RSA Data Security, Inc. SSL allows the client to authenticate the server and all data and requests to be encrypted. The
URL of a secure server that is protected by SSL begins with https rather than http.
selection border. The visual border that appears around a VARPG part or a custom-made part, allowing the part to
be moved with the mouse or keyboard.
selection button. See mouse button 1.
Glossary
465
server. A system in a network that handles the requests of another system, called a client.
server alias. A name you define that can be used instead of the server name.
shared component. A component that can be accessed by more than one project.
single-byte character set (SBCS). A character set in which each character is represented by a one-byte code.
Contrast with double-byte character set (DBCS).
sizing border. The border or frame around a part (or set of parts) that you select to resize the part (or set of parts)
using the mouse or the keyboard.
slider part. A visual component of a user interface that represents a quantity and its relationship to the range of
possible values for that quantity. A user can also change the value of the quantity. You can point and click on a slider
part in the parts palette or parts catalog and click it onto a design window.
slider arm. The visual indicator in the slider that a user can move to change the numerical value.
source directory. The directory in which all source files for a VARPG application are stored.
source part. A part that can notify target parts whenever the state of the source part changes. A source part can
have multiple targets.
spin button part. A type of entry field that shows a ring of related but mutually exclusive choices through which a
user can scroll and select one choice. A user can also type a valid choice in the entry field. You can point and click on
a spin button part in the parts palette or parts catalog and click it onto a design window.
SSL. Secure sockets layer.
static text part. A part used as a label for other parts, such as a prompt for an entry field part.
status bar. A part of a window that displays information indicating the state of the current view or object. See also
information area.
status bar part. A part on a window that can display additional information about a process or action for the
window.
subfile field. A field used to define fields in a subfile part. See also subfile part.
subfile part. A part used to display a list of records, each consisting of a number of fields. This part is similar to an
AS/400 subfile. See also subfile field.
submenu. A menu that appears from, and contains choices related to, a cascading choice in another menu.
Submenus are used to reduce the length of a pull-down menu or a pop-up menu. See also submenu part.
submenu part. A part used to start a submenu from a menu item or existing menu, or to start a pull-down menu
from a menu item on a menu bar. See also submenu and menu item part.
subprocedure. A subprocedure is a procedure specified after the main source section. It must have a corresponding
prototype in the definition specifications of the main source section
syntax checking. Verifies that the syntax of each line is correct while you are editing the source. By doing so, it can
avoid compile errors. You can set this option on or off. You can view only certain specification types, such as C specs,
or a line with a specific string.
T
tab stop. An attribute used to set a tab stop for a part so that users can focus on it when they use the Tab key to
move through the interface.
target part. A part that receives a link event from a source part whenever the state of the source part changes.
target directory. The directory in which the compiled VARPG application is stored after a build. Contrast with target
folder.
466
target folder. The object in which the icon representing a VARPG application is placed.
target program. The object to be built by the project, such as a dynamic link library (DLL).
thread. The smallest unit of operation to be performed within a process.
timer part. A part used to track the interval of time between two events and trigger the second event when the
interval has passed.
title bar. The area at the top of each window that contains the system-menu symbol.
token highlighting. Enhances the readability of the code. You can configure highlighting of different language
constructs with different colors or fonts to identify the program structures. You can turn token highlighting on or off.
tool bar. A menu that contains one or more graphical choices representing actions a user can perform using a
mouse.
topic. In dynamic data exchange (DDE), the set of data that is the subject of a DDE conversation.
tree view. A way of displaying the contents of an object in a hierarchical fashion.
U
user-defined part. A part, consisting of one or more parts you have customized, that you save to the parts palette or
parts catalog for reuse. When in the palette or catalog, you can point and click this part onto the design window as
you would any other VARPG part.
utility DLL. See NOMAIN module
V
vertical scroll bar part. A part that adds a vertical scroll bar to a window. This part allows users to scroll through a
pane of information vertically.
W
WAV. The file extension of a wave file.
wave file. A file used for audio sounds on a waveform device.
window part. An area with visible boundaries that represents a view of an object or with which a user conducts a
dialog with a computer system. You can point and click on a window part from the parts palette or parts catalog and
click it onto the project window.
window with canvas part. A combination of the window part and the canvas part. See also window part and canvas
part.
work area. An area used to organize objects according to a users tasks. When a user closes a work area, all
windows opened from objects contained in the work area are removed from the workplace.
workplace. An area that fills the entire display and holds all of the objects that make up the user interface.
workstation. A device that allows a user to do work. See also programmable workstation.
Glossary
467
468
Bibliography
For additional information about topics related to WebSphere Development Studio
Client, refer to the following IBM publications:
WebSphere Development Studio Client manuals:
v Getting Started with WebSphere Development Studio Client for iSeries, SC09-2625-06,
provides information about WebSphere Development Studio Client for iSeries,
giving an overview of the various components, how they work together, and the
business advantages of using them.
VisualAge RPG manuals:
v Programming with VisualAge RPG, SC09-2449-05, contains specific information
about creating applications with VisualAge RPG. It describes the steps you have
to follow at every stage of the application development cycle, from design to
packaging and distribution. Programming examples are included to clarify the
concepts and the process of developing VARPG applications.
v VisualAge RPG Parts Reference, SC09-2450-05, provides a description of each
VARPG part, part attribute, part event, part attribute, and event attribute. It is a
reference for anyone who is developing applications using VisualAge RPG.
v VisualAge RPG Language Reference, SC09-2451-04, provides reference information
about the VARPG language and compiler.
v Java for RPG Programmers introduces you to the Java language (and RPG IV) by
comparing it to the RPG language. It is a good first step in your Java journey. It
also includes an interactive CD tutorial on Java and VisualAge for Java, by
MINDQ.
v Experience RPG IV Tutorial is an interactive CD tutorial that teaches you RPG IV
and ILE, in a fun and step-by-step approach. The book is a handbook with
questions and exercises to help you get hands-on experience with this exciting
new version of RPG.
v Another non-IBM book of interest to VisualAge RPG users is VisualAge for RPG
by Example.
If you have internet access, you can obtain current iSeries and AS/400e
information and publications from the following Web site:
http://www.ibm.com/eserver/iseries/infocenter
For the PDF version of iSeries publications, refer to the CD ROM iSeries Information
Center: Supplemental Manuals, SK3T-4092-00.
Application Development Manager manuals:
v ADTS/400: Application Development Manager Introduction and Planning Guide,
GC09-1807-00, describes the basic concepts and the planning needed to make
effective use of the Application Development Manager feature.
v ADTS: Application Development Manager Users Guide, SC09-2133-02, describes
how to create and manage projects defined to the Application Development
Manager feature.
v ADTS/400: Application Development Manager Self-Study Guide, SC09-2138-00,
provides practical hands-on experience using the Application Development
Manager feature. The guide illustrates how to use the Application Development
Manager feature by leading you through a series of step-by-step exercises.
469
470
Index
Special characters
.BMP file
using 84, 243
.DLL file
calling functions 268
description 427
loading the DLL occurrence while
debugging 228
.EVT file, description 427
.EXE file
calling .EXEs 269
description 427
.HLP file, description 427
.ICO file
using 84, 243
.IPF file, description 427
.IPM file, description 427
.LIB file, description 427
.LST file, description 427
.MID file
processing by media parts 101
.ODF file, description 427
.ODX file, description 427
.RST file, description 427
.TXC file, description 427
.TXM file, description 427
.VPF file, description 427
.VPG file, description 427
.WAV file
processing by media parts 101
*component part
attributes 188
events 188
purpose of 188
*INZSR 272
*TERMSR 273
%DspHeight system attribute 27, 38
%DspWidth system attribute 27, 38
%GETATR, using 25
%SETATR, using 25
A
accessing picture files at build time 244
action subroutine
modifying link events 26
action subroutine, invoking 26
ActiveX part
attributes 47
creating 47
events 47, 50, 89
methods 48
properties 47
purpose of 46
AddItemEnd attribute 151
AddLink attribute
controlling media part with 102
for media panel parts 103
AddMsgId attribute 108
AddMstTxt attribute 108
Copyright IBM Corp. 1994, 2005
attributes (continued)
Arrange 70
AudioMode 101
BackColor 37
BackMix 37, 146
Bottom 37
CharOffSet 113
Checked 58, 106
checking event and system
attributes 27
ColNumber 69, 160
Count 69, 94, 159
DDEMode 267
DeSelect 62, 93, 94
DragEnable 41
DropEnable 41
Enabled 37, 77, 107, 113
FileName 81, 85, 101, 243
FirstSel 62
Focus 38
FontName 155
FontSize 155
for ActiveX parts 47
for animation control parts 53
for canvas parts 57
for check box parts 58
for combination box parts 60, 61
for component reference parts 65
for container parts 67
for DDE client parts 74
for entry field parts 75
for graphic push button parts 81
for group box parts 82
for horizontal scroll bar parts 83
for image parts 85
for Java Bean parts 89
for list box parts 78, 92
for media panel parts 103
for menu item parts 106
for message subfile parts 108
for multiline edit parts 112
for notebook canvas parts 119
for notebook page parts 118
for notebook parts 117
for ODBC/JDBC interface parts 120
for outline box parts 137
for pop-up menu parts 138
for positioning parts 37
for progress bar parts 139
for push buttonparts 140
for radio button parts 142
for slider parts 145
for static text parts 155
for status bar parts 157
for subfile parts 158
for submenu parts 171
for timer parts 172
for vertical scroll bar parts 179
for window with canvas parts 181
for window without canvas
parts 180
471
attributes (continued)
ForeColor 37
ForeMix 37
GetItem 94
GetNewID 68
GetRcdText 67
getting and setting 25
Height 37, 137
Index 61, 62, 94, 160
InfoLabel 39
InsertItem 61, 93
InsertLine 112
InsertMode 76
Interval 172
Label 39, 82, 106, 140, 155
Left 37
LineNumber 112
Masked 77
Maximum 151
Minimum 151
MsgSubText 109
Multiplier 172
OpenEdit 160
OpenImmediately 181, 182
Panel 85
PanelItem 104
ParentName 35
PartName 35
PartType 35
Position 102, 104
ReadOnly 62, 77, 113, 152
RecordID 69
RemoveItem 62, 93
RemoveMsg 109
RemoveRcd 70
Selected 62, 93, 94
SelectItem 64
Sequence 61, 92
SetItem 61, 93
SetRcdIcon 70
SetRcdText 67
SetTop 62, 93
TabLabel 39
Terminate on close 186
Text 62, 76, 112, 151
TextEnd 113
TextSelect 113
TextStart 113
TimerMode 173
UserData 39
Validate 76
Value 145, 151, 173
View 73
Visible 38, 172, 181
Volume 102, 104
Width 37, 137
AudioMode attribute 101
B
BackColor attribute, common uses of 37
backmatter
common uses of 37
for slider parts 146
BEGACT operation code, responding to
events with 26
bibliography 469
472
C
calendar 54
purpose of 54
CALL operation code, example of 273
CALLB operation code
calling local functions 267, 268
calling local programs
calling local programs 267
functions using named constants 268
functions using procedure
pointer 269
functions without required
parameters 269
local functions 268
local programs 267
remote programs 272
canvas part
attributes 57
events 57
purpose of 56
CHAIN (random retrieval from file)
operation code 159
Change event
and multiline edit parts 113
for media panel parts 104
for slider parts 145
changing
a pointer value while debugging 236
debugger views 236
the contents of a field while
debugging 234
the representation while
debugging 234
variables, arrays, and structures while
debugging 233
changing position of parts 182
CharOffset attribute 113
check box part
attributes 58
events 58, 59
getting and setting states 58
purpose of 58
Checked attribute
for check box parts 58
for menu item parts 106
CLEAR operation code
for subfile parts 159
purpose of 29
Close event 186
ColNumber attribute 69, 160
color of converted parts after
import 221
combination box part
adding and changing items 61
and data transfer 41
attributes 60
events 61
order of items 61
purpose of 60
removing items 62
retrieving a user-selected item 62
D
data area overrides 195
data transfer
example 42
parts that support 41
using 41
DDE client
attributes 74
determining if programs support 74
events 74
purpose of 74
DDEAddLink attribute
using 267
DDEMode attribute 267
debugger
breakpoints 228
changing debugger views 236
changing the contents of a field 234
changing the representation 234
debugger (continued)
changing the view 233
displaying registers 233
displaying the debug session control
window 233
displaying the program monitor 233
displaying the stack 233
displaying the storage 233
displaying variables 233
Load occurrence 228
overview 227
running a program while
debugging 232
running the program 232
setting breakpoints 229, 231
starting 227
step return 232
stepping 232
stepping into 232
stepping over 232
tool bar selections 232
default settings
due to CLEAR operation code 187
focus 185
open immediately 181
order of items in a combination
box 61
system menu settings 186
visible 181
window list contents 185
Define AS/400 Information utility
and packaging your application 415
setting a server at run time 194
DELETE (delete record) operation
code 159
DeSelect attribute
for list box parts 93, 94
designing
messages 21
number of windows 20
online help 19
program logic 21
Video Store Catalog application 5
window content 20
directly editing messages 263
display files
color of converted parts 221
display file keywords 219
display record formats 218
reusing 217, 218
displaying variables
debug assembly source code 228
debug load occurrence
breakpoint 228
pointer value while debugging 234
variables while debugging 233
variables, arrays, and structures while
debugging 233
Double Byte Character Set
application development
considerations 381
DBCS Either data type 381, 382
DBCS Mixed data type 381, 383
DBCS Only data type 381, 382
GETATR operation code 382, 383
graphic data type 383
Pure DBCS 383
E
edit codes
formatting data into predefined
formats 239
purpose of 239
user-defined 240
edit words
body of 241
correcting improperly formatted
output 241
expansion positions of 242
parts of 241
purpose of 239, 240
status of 242
editing
data in entry fields and static text
parts 239, 240
help files 222
messages 261
RPG source 224
Enabled attribute
common uses of 37
for entry field parts 77
for menu item parts 107
for multiline edit parts 113
ENDACT operation code, responding to
events with 26
Enter event
for combination box parts 64
for list box parts 94, 170
entry field part
and data transfer 41
attributes 75
clearing 187
events 76
overriding defined values 29
purpose of 75
starting components 272
storing read values 29
error messages
error referencing parts 182
improperly formatted output 241
Event attributes
defining event and system
attributes 27
purpose of 26
event attributes, using 26
events
Change 104, 113, 145
checking for event attribute errors 27
Close 186
coding BEGACT and ENDACT 26
Complete 102
description of attributes 26
Enter 94, 170
for ActiveX parts 47
for animation control parts 53
for check box parts 59
for combination box parts 64
for DDE client parts 74
events (continued)
for entry field parts 76
for graphic push button parts 81
for group box parts 82
for horizontal scroll bar parts 83
for image parts 85
for Java Bean parts 89
for list box parts 92
for media panel parts 103
for media parts 101
for menu bar parts 105
for menu item parts 106
for message subfile parts 108
for multiline edit parts 112
for notebook page parts 118
for notebook parts 117
for ODBC/JDBC Interface parts 121
for outline box parts 137
for progress bar parts 139
for push button parts 140
for radio button parts 142
for slider parts 145
for spin button parts 151
for static text parts 155
for status bar parts 157
for subfile parts 158
for submenu parts 171
for timer parts 172
for vertical scroll bar parts 179
for window with canvas parts 181
for window without canvas
parts 180
GotFocus 38, 113
invoking action subroutines 26
listing events for a part 26
LostFocus 38
MenuSelect 107
Notify 66
Press 81, 141
responding to events in your
program 26
Select 59, 94, 144, 170
Tick 172
examples
adding records to a container part 69
getting and setting values for spin
button parts 152
grouping radio buttons 142
of data transfer 42
of parts sharing a program field 30
reading and modifying subfile
records 160
removing records from container
parts 70
resizing a window 183
updating container parts 69
using component reference part 65
using Create event for a window 38
using subfile part to display database
records 161
using subfiles to display server
data 161
using the image part 86
using the list box part 94
using the message subfile part 110
using the multiline edit part 113
using the slider part 146
Index
473
examples (continued)
using the timer part 173
Video Store Catalog application 3
window part 187
exchanging information with other PWS
applications 265
execute subroutine
invoking action subroutines with 26
F
field parts
unique names 30
file aliases (overrides) 196
FileName attribute
for graphic push button parts 81
for image parts 85
for media parts 101, 243
finding a message
a message 261
FirstSel attribute 62
Focus attribute, common uses of 38
FontName attribute 155
FontSize attribute 155
ForeColor attribute, common uses of 37
ForeMix attribute, common uses of 37
G
GETATR
using 25
GetItem attribute 94
GetNewID attribute 68
GetRcdText attribute 67
getting the record count
count of records in a subfile 159
part attributes 25
state of check box parts 58
state of radio button parts 144
text attribute for multiline parts 112
value for slider parts 145
values for spin button parts 151
glossary 457
GotFocus event
and multiline edit parts 113
common uses of 38
graph 78
purpose of 78
graphic data type 383
graphic push button part
attributes 81
events 81
purpose of 80
group box
attributes 82
events 82
purpose of 82
grouping radio buttons, example 142
H
Height attribute
common uses of 37
for outline box parts 137
help
adding graphics to 245
474
help (continued)
creating a help push button 246
creating for Windows 249
creating hypertext links 246
editing 222
filename.IPM 427
filename.VPF 427
for Java applications 253
planning your application 19
reusing UIM 222
translating 245
types of 246
help push button, creating 246
hidden subfile fields 161
horizontal scroll bar
attributes 83
events 83
purpose of 83
hypertext links, creating 246
I
icons, using 243
image part
accessing picture and sound files at
build time 244
attributes 85
events 85
purpose of 84
specifying the FileName
attribute 243
importing 217
and color of converted parts 221
display file keywords 219
display files 217, 218
display record formats 218
positional entries and conversion 218
scenario 213
Index attribute
for combination box parts 61, 62
for list box parts 94
for subfile parts 160
InfoLabel attribute 39
Information Presentation Facility
(IPF) 245
InsertItem
for list box parts 93
InsertItem attribute
for combination box parts 61
for list box parts 93
InsertLine attribute 112
InsertMode attribute 76
installing
applications (for Windows NT) 423
code for examples in this book 33
DBCS considerations 381
runtime code (for Windows NT) 423
Video Store Catalog example 3
Interval attribute 172
IPF (Information Presentation
Facility) 245
J
Java applications
SSL setup 449
L
Label attribute
common uses of 39
for group box parts 82
for menu item parts 106
for push button parts 140
for static text parts 155
purpose of 30
labels
description 39
substitution 259
Left attribute, common uses of 37
level checking 199
library lists
Define iSeriesInformation notebook
considerations 196
job description 194
QCMDDDM 194
QCMDEXC 194
setting up a server 194
LineNumber attribute 112
for multiline edit parts 112
linking parts 265
list box part
and data transfer 41
attributes 78, 92
events 92
purpose of 92
locking database files 199
LostFocus event, common uses of 38
M
Make Message File utility 262
Masked attribute 77
Maximize button 183
Maximum attribute 151
media panel part
attributes 103
controlling media part with 102
events 103
purpose of 103
media part
attributes 101
controlling with media panel
part 102
events 101
purpose of 101
signaling events 102
menu bar
attributes 105
events 105
purpose of 105
menu item part
attributes 106
events 105, 106
purpose of 106
menubar
purpose of 105
MenuSelect event
for menu item parts 107
message subfile part
and data transfer 41
attributes 108
events 108
example of 110
purpose of 108
messages
choosing type of 260
compiling for translation 262
creating 259, 260
deleting 261
designing 21
editing 261
editing for translation 263
filename.TXM 427
finding 261
types of 259
using as labels 263
using with logic 262
Minimize button 183
Minimum attribute 151
mnemonics
for check box parts 59
for menu items 106
for notebook pages 118
for push buttons 140
for radio buttons 142
translating 22
modifying
link events to action subroutines 26
resource IDs 427
MsgSubText attribute 109
multiline edit part
and data transfer 41
attributes 112
events 112
example of 113
purpose of 112
multiple procedures
prototyped call 275
Multiplier attribute 172
MultSelect attribute
for list box parts 78, 92
for subfile parts 158
N
non-GUI programs 375
non-GUI programs from DOS 447
notebook page part
attributes 118
events 118
purpose of 118
notebook page with canvas part
attributes 119
O
ODBC/JDBC interface part
access table data 122
attributes 120, 139
connect to a database 121
create a record set 121
data types 122
events 121, 139
purpose of 120
retrieve table rows 123
Open Immediately attribute 181
OpenEdit attribute 160
operation codes
CALLB 268
CHAIN 159
CLEAR 159, 187
DELETE 159
READ 76
READC 159
READS 159
SETATR 85
SHOWWIN 182
START 65, 272
STOP 272
UPDATE 159
WRITE 76, 159
Outline Box part
attributes 137
events 137
purpose of 137
overrides
accessing data areas 195
accessing database files 196
calling iSeries server programs 273
P
packaging
application 415
prerequisites 415
runtime code 415
Packaging utility 415
Panel attribute 85
PanelItem attribute 104
ParentName attribute, common uses
of 35
part colors
common uses of 37
slider part example 146
part type
description 275
PartName attribute, common uses of
parts
*component 188
ActiveX 46
35
parts (continued)
animation control 53
canvas 56
changing colors of 37
check box 58
combination box 60
Combination box 60
component reference 65
Component Reference 65
container 67
Container 67
DDE client 74
enabling parts 37
entry field 75
graph 78
graphic push button 80
group box 82
horizontal scroll bar 83
image 84
Java Bean 89
linking 265
list box 86, 92
listing events for a part 26
media 101
media panel 103
menu bar 105
menu item 106
message subfile 108
multiline edit 112
notebook 117
notebook page 118
notebook page with canvas 119
ODBC/JDBC interface 120
outline box 137
placement on various monitor
resolutions 38
pop-up menu 138
positioning 37
progress bar 139
push button 140
radio button 142
referencing 25
slider 145
spin button 151
static text 155
status bar 157
subfile 158
submenu 171
support data transfer 41
timer 172
vertical scroll bar 179
window 180, 181
window frame 180
PartType attribute, common uses of 35
Picture file
for image parts 84
using 243
pictures, adding 243
planning your application 19
pointer
changing the value while
debugging 236
displaying while debugging 234
pop-up menu part
attributes 138
events 138
purpose of 138
Index
475
Position attribute
for media panel parts 104
setting 102
position of parts, changing 182
positional entries, and conversion during
import 218
Press event
for graphic push button parts 81
for push button parts 141
programs, non-GUI 375
progress bar part
purpose of 139
prototyped call
prototyped call 275
prototyping, Java methods 280
publications, list of 469
push button part
attributes 140
events 140
purpose of 140
Q
QCMDDDM
changing the library list 194
QCMDDDM, changing the library
list 194
QCMDEXC
changing the library list 194
QCMDEXC, changing the library
list 194
R
radio button part
attributes 142
events 142
example showing how to group 142
purpose of 142
re-packaging 423
READ (read a record) operation code
database files 198
purpose of 29
READC (read next modified record)
operation code 159
ReadOnly attribute
for combination box parts 62
for entry field parts 77
for multiline edit parts 113
for spin button parts 152
READS (read selected record from
subfile) operation code 159
RecordID attribute 69
recursion
recursive calls 277
referencing
parts on different windows 25
parts on the same windows 25
RemoveItem attribute 62, 93
RemoveMsg attribute 109
RemoveRcd attribute 70
removing
an application 423
the runtime code 423
RESET
purpose of 29
476
S
sample programs
building 34
installing 33
running 34
special instructions for samples
requiring iSeries server data 34
secure sockets layer setup 449
Select event
for combination box parts 64
for list box parts 94
for radio button parts 144
for subfile parts 170
signaling 59
Selected attribute
for combination box parts 62
for list box parts 93, 94
selecting items in combination boxes 62
SelectItem attribute 64
Sequence attribute
for combination box parts 61
for list box parts 92
server connections, runtime control 201
servers
accessing data areas 195
accessing database files 196
calling iSeries 400 programs with
workstation files 274
calling server programs 273
database considerations 200
defining iSeries Information 193
issuing CL commands 194
level checking 199
library list considerations 194
locking database files 199
notebook considerations 193
overriding database files 199
setting up for developing/running
applications 194
servers (continued)
using your application as a DDE
Server 266
SETATR
using 25
SETATR (set attribute) operation code
for image parts 85
reflecting stored values on the
screen 29
SetItem attribute
for combination box parts 61
for list box parts 93
SetRcdIcon attribute 70
SetRcdText attribute 67, 70
setting
debug breakpoints 229
debug fonts 237
SetTop attribute
for combination box parts 62
for list box parts 93
sharing program fields, example of
parts 30
SHOWWIN operation code
loading window into memory 182
Signon API, sample program 205
Signon API,using 201
slider part
attributes 145
events 145
purpose of 145
sound files, using 243
sound, adding 243
source code
editing 224
filename.VPG 427
spin button part
events 151
example of 152
purpose of 151
SSL setup 449
standalone programs 375
START (start a component) operation
code
and component reference parts 65
calling local programs using 270
description 272
restrictions when calling local
programs with 271
starting
debug window 227
the debugger 227
starting a component 272
starting components
starting components 272
static text part
and data transfer 41
attributes 155
events 155
overriding defined values 29
purpose of 155
storing read values 29
unique names 30
status bar part
attributes 157
events 157
purpose of 157
stepping over
while debugging 232
STOP (stop a component) operation code
description 272
subfile part
attributes 158
events 158
example displaying server data 161
example of reading and updating
records 160
hidden fields 161
purpose of 158
submenu part
attributes 171
events 171
purpose of 171
substitution labels
defining text for 259
description 39
system attributes
%DspHeight 27, 38
%DspWidth 27, 38
System attributes
checking for system attribute
errors 27
T
TabLabel attribute 39
Terminate on close 186
terminating a program 186
text
for combination box parts 62
for entry field parts 76
for spin button parts 151
purpose of 30
Text attribute 112
TextEnd attribute 113
TextSelect attribute 113
TextStart attribute 113
thin clients 431
Tick event 172
TickLabel attribute
for slider parts 145
timer part
events 172
purpose of 172
TimerMode attribute 173
translating
compiling messages for 262
editing messages for 263
messages 22
mnemonics 22
tips for 22, 39
U
update subfiel record
for subfile parts 159
User Interface Manager, reusing
files 222
UserData attribute, common uses of 39
utilities
Define iSeries Information 194, 415
Make Message File 262
Packaging 415
V
Validate attribute 76
Value attribute
for slider parts 145
for spin button parts 151
for timer parts 173
Vendor Plugins
adding 389
creating 391
invoking 389
managing 389
vertical scroll bar
attributes 179
events 179
purpose of 179
Video Catalog application
adding messages 15
adding online help 15
creating the Comedy window 7
creating the Preview window 11
description of 3
designing 5
installing 3
running 4
View attribute 73
views, changing 70
Visible attribute
common uses of 38
for timer parts 172
for window parts 181
visual RPG
breakpoints list 230
changing a pointer value 236
changing variables, arrays, and
structures 233
debug startup information 229
debug tool bar 232
debug window 227
displaying a pointer value 234
displaying the assembly source
code 228
displaying the load occurrence
breakpoint 228
displaying variables, arrays, and
structures 233
running breakpoints 231
setting breakpoints 229
setting debug fonts 237
Volume attribute
for media panel parts 104
for media parts 102
windows
attributes 180, 181
attributes for operation codes 30
creating at startup 182
default settings 181
designing content of 20
displaying 181
displaying pictures on 243
events 180, 181
giving input focus 38
loading into memory 182
method for moving 182
OpenImmediately attribute 181
operation codes for 29
positioning without use of title
bar 182
purpose of 180, 181
referencing 182
resizing 183
setting focus 185
setting window list contents 185
specifying when to display 38
style considerations 21
system menu settings 186
terminating on Close 186
unique names for entry field and
static text parts 30
using sound 243
Visible attribute 181
when you can set attributes 182
Windows help, creating 249
WRITE (create new records) operation
code
database files 198
for subfile parts 159
purpose of 29
reflecting stored values on the
screen 29
W
Width attribute
common uses of 37
for outline box parts 137
window part
attributes 180
events 180
purpose of 180
window with canvas part
attributes 181
events 181
purpose of 181
Index
477
478
Printed in U.S.A.
SC09-2449-07