HP 3000 Manuals HP 3000 Manuals
Using a Terminal in Full Screen Mode
When you have several fields of data to process using a terminal, you may
find it easier to work in full screen mode rather than line mode. Full
screen (or block) mode lets you read and display entire screens of data
at one time.
There are three software tools that let you use the terminal in full
screen mode; VPLUS, RPG Screen Interface (RSI) and the RSI CONSOLE
facility. VPLUS is a general-purpose forms management system that
interfaces with many programming languages. RSI is an RPG utility that
creates forms similar to those used on IBM S/34 and S/36. RSI CONSOLE
facility lets you use certain RSI functions for processing input files
only (CONSOLE files are ideal for simple data entry applications).
The following list compares the features of VPLUS and RSI:
VPLUS RSI
Uses actions and events to manage Uses standard RPG specifications to manage
input/output input and output
Can be used with other languages and Most easily used with RPG programs
applications
Does not let you use User Message Catalog Lets you use User Message Catalog files for
files for messages messages
Cannot dynamically change screen attributes Can dynamically change screen attributes
(for example, blinking and inverse video)
No automatic conversion to VPLUS Converts IBM S and D Specifications to
RSI-compatible format
No automatic conversion to VPLUS Automatically generates RPG program
specifications from RSI form files
This chapter explains how to use VPLUS, RSI and RSI CONSOLE files in RPG
programs. To help you compare VPLUS and RSI, the same program example is
used for each (the example differs only in how terminal input and output
is handled). The last three section in this chapter, starting with
"Enabling the BREAK Key," describe RPG features that you can use with
both VPLUS and RSI.
NOTE Although you can use most VPLUS features in an RPG program, some
are not available. This chapter and the HP Reference Manual
describe the features that are available when you use the RPG
Interface to VPLUS.
Using VPLUS
When you use VPLUS in an RPG program, follow these procedures:
* Create a VPLUS form
Before using VPLUS to process data full screen mode, use the FORMSPEC
facility of VPLUS to create a screen form. When you create a form,
you determine the layout of fields on the screen and specify the type
of data each field holds. You can also enter titles and field
display characteristics.
* Define a VPLUS form
When you're finished designing the VPLUS form, enter the following
specifications in the RPG program to define the form.
File Description Specifications -
Enter the specifications for a terminal file. This is the forms file
you created with FORMSPEC. Specify that it is a WORKSTN file.
Input Specifications -
Enter input records describing the fields in the VPLUS form. Also
enter one or more records for processing VPLUS event codes. (You use
event codes to identify the type of input the user entered.)
Output Specifications -
Define an output record describing the VPLUS form and one describing
the message window (the message window is used for displaying
one-line messages at the bottom of the screen). You may also need to
define a separate output record for processing VPLUS action codes.
(You use action codes to specify the VPLUS operation to perform.)
* Perform a VPLUS action or return a VPLUS event
Calculation Specifications -
For each VPLUS operation you want to perform, enter Calculation
Specifications to identify and execute it as follows:
1. Enter a MOVE operation to move the VPLUS action code (for the
operation you want to perform) to the first field of the
terminal file's output record.
VPLUS has several action codes that you can use. Here are the
ones that are discussed in this chapter:
Action code: Description:
CHGNXT Changes VPLUS forms.
EDITS Performs the data edits specified in
FORMSPEC. VPLUS returns an edit error
count to the program.
GETDTA Moves data from the VPLUS buffer to the
program's input record.
GETNXT Gets the next form from the VPLUS forms
file.
INIT Initializes form fields according to the
edits specified in FORMSPEC.
PUTDTA Moves data from the terminal output record
to the VPLUS buffer.
RDTERM Reads screen data into the VPLUS buffer.
SHOMSG Displays a message in the message window.
For example, the operation MOVEL "GETDTA" ACTION moves the
GETDTA action code to the output field, ACTION.
2. Once you move the VPLUS action code to the output record,
perform exception output (EXCPT operation) for that record.
VPLUS performs the action and returns control to your program.
3. To complete input actions (for example, GETDTA), enter a READ
operation for the terminal file. VPLUS returns an event code
in the first field of the terminal input record. You use this
event code to identify the type of input received. Here are
some of the codes that may be returned:
Event code: Description:\00\The user entered data and
pressed ENTER .
01-08 The user pressed F1 through F8 .
09 An EDITS action was performed and VPLUS
returned the number of fields that failed
the VPLUS edits.
For example, if you performed a GETDTA action, you follow it
with READ TERMINAL operation.
The VPLUS sections in this chapter explain how to perform the VPLUS
procedures introduced above. They do not cover all of the VPLUS actions
or the ways to use VPLUS, but they should give you a good start. See the
HP RPG Reference Manual for rules on using the RPG interface to VPLUS.
Many of the following VPLUS sections in this manual use examples taken
from the program listed in the section "A Sample Program Using VPLUS."
You may find it helpful to refer to this program to get a clear idea of
how the examples can be used together to form a complete program.
Creating a VPLUS Form. Before you can use VPLUS in a program, you must
create a screen form using the VPLUS facility, FORMSPEC. Although this
section shows a typical screen created by FORMSPEC, it does not explain
how to create it. For instructions on how to use FORMSPEC, see the Data
Entry and Forms Management System VPLUS/3000 manual.
Figure 4-13 shows what a FORMSPEC screen form looks like. Titles,
captions and headings are capitalized. Fields, used for entering data,
are enclosed in brackets.
![[]](../../pic3k/M010422/RPGP4F133c50.gif)
Figure 4-13. Creating a VPLUS Form Using FORMSPEC
Figure 4-14 shows what the screen form (in Figure 4-13) looks like when
displayed from an RPG program. Input fields are highlighted.
The line at the bottom of the screen is the message window. It is used
to display one-line messages.
![[]](../../pic3k/M010422/RPGP4F143c50.gif)
Figure 4-14. Using a VPLUS Form Within an RPG Program
The form shown in Figure 4-14 is used in examples throughout the VPLUS
sections in this chapter. The form is used to update the D-ACCOUNTS data
set (see the schema for the MARKET database in Figure 3-23.
Defining a VPLUS Form. To use a VPLUS form in an RPG program, enter a
File Description Specification for it, defining it as a WORKSTN file.
Also enter Input and Output Specifications that describe the form as well
as the action and event records that let you communicate with VPLUS. Only
define those fields on the form that you're actually using in the
program. You can get the field starting and ending locations from the
event and action record formats described in the HP RPG Reference Manual
and the forms file listing produced by FORMSPEC.
Figure 4-15 shows how to define a VPLUS form. The form used is the one
in Figure 4-14. Notice that there are two input records for the file,
TERMINAL. The first is used for processing event code 09. (To review
events, see the section titled "Using VPLUS.") The second input record
defines the VPLUS form fields used in the program. There are three
output records. The first is used to initiate VPLUS actions other than
reading data from the screen. (To review VPLUS actions, see the section
titled "Using VPLUS.") The second output record is used for displaying
screen data and the third defines the fields in the message window (see
the section "Displaying VPLUS Messages" for information about the message
window).
![[]](../../pic3k/M010422/RPGP4F153c50.gif)
Figure 4-15. Defining a VPLUS Form
![[]](../../pic3k/M010422/RPG4F15A3c50.gif)
Figure 4-15. Defining a VPLUS Form (Continued)
Comments
1 This line defines a WORKSTN (terminal) file.
Column 15 is U to specify update processing.
Column 16 is D to specify that this is a demand file.
Column 19 is V to specify variable length records (you must use
V for terminal files).
Columns 24-27 specify that the record length is 256 characters
(the record length must be at least 20 characters longer than
the longest record in the file).
Columns 40-46 specify that the file is a WORKSTN file.
2 This line identifies the VPLUS forms file used in the program.
Column 53 is K to specify that this is a File Description
Continuation line.
Columns 54-59 specify that this line is a FORMS File Description
Continuation line.
Columns 60-65 contain the name of the forms file, FACCOUNT.
Figure 4-14 shows what this form looks like.
3 This line defines input record type 09. It is used to process
event code 09.
Columns 21-24 specify that the record core in columns 1-2 of
each record is 09.
4 This line defines the field, NUMBER. NUMBER contains the number
of edit errors returned by VPLUS.
Columns 69-70 contain 13 to turn on indicator 13 when there are
no edit errors.
5 This line defines input record type 01. This record describes
the VPLUS screen form and is used to read data from the
terminal.
6 This line defines the field, DATALN, that contains the number of
bytes read from the screen.
7 This line starts the descriptions of the fields in the VPLUS.
form.
8 This line defines the output record that is written when an
EXCPT V$ACTN calculation is executed. This may occur, for
example, when you request VPLUS to edit screen data.
9 This line defines the field, ACTION, which contains the VPLUS
action code.
10 This line defines the output record to be written when an EXCPT
V$DATA calculation is executed. This may occur, for example,
when you want to display a form containing data.
11 This line defines the field, ACTION, which contains the VPLUS
action code.
12 This line defines the field, DATALN, which contains the number
of bytes of data that VPLUS displays on the screen.
13 This line starts the field description for the VPLUS form.
14 This line starts the description of the fields in the message
window. See the section "Displaying VPLUS Messages" for
information about message window fields.
Displaying an Initialized VPLUS Form. This section explains how to load
a form from a VPLUS forms file, initialize it with FORMSPEC values and
display it. You must display an initialized form before a user can enter
data from the terminal.
The discussion in this section assumes that you are familiar with VPLUS
action and event codes. To review these topics, see the third section
titled, "Using VPLUS."
Figure 4-16 shows the steps for displaying an initialized VPLUS form.
(Refer to Figure 4-15 for descriptions of the terminal input and output
records used here.) The first step in displaying an initialized VPLUS
form is to set appropriate values in the message window fields, DATALN
and ENHANC. The second step is to enter the VPLUS action, GETNXT, to
retrieve the form from the VPLUS forms file. The third step is to enter
the VPLUS action, INIT, to place FORMSPEC values in the form fields. The
fourth step is to enter the VPLUS action, SHOMSG, to clear the VPLUS
message window. And the last step is to use the VPLUS action, SHOW, to
display the form with its initial values.
![[]](../../pic3k/M010422/RPGP4F163c50.gif)
Figure 4-16. Displaying a VPLUS Form
Comments
1 This line initializes the DATALN field in the message window
record with the screen length. This operation is done once,
when the form is first displayed.
2 This line initializes the message window field, ENHANC, with the
character J. J is inverse video, half bright. ENHANC is
initialized once, when the form is first displayed.
3 This line enters the VPLUS action, GETNXT, into the ACTION
output field. GETNXT retrieves the form from the forms file and
places it into the VPLUS buffer.
4 This line performs exception output for the record associated
with EXCPT Group V$ACTN.
5 This line enters the VPLUS action, INIT, into the ACTION output
field. INIT initializes the VPLUS buffer fields with FORMSPEC
values.
6 This line performs exception output for the record associated
with EXCPT Group V$ACTN.
7 This line resets the message array pointer, M, to 3. Assuming
that the third element of the message array is a blank line, the
window is cleared.
8 This line enters the VPLUS action, SHOMSG, into the ACTION
output field. SHOMSG displays a message in the VPLUS message
window.
9 This line performs exception output for the record associated
with EXCPT Group V$MESG.
10 This line enters the VPLUS action, SHOW, into the ACTION output
field. SHOW displays the form in the VPLUS buffer.
11 This line performs exception output for the record associated
with EXCPT Group V$ACTN.
Reading a VPLUS Form. Once you display an initialized VPLUS form (see
the previous section), a user can start entering data into it from the
terminal. This section explains how to read that data into an RPG
program.
Reading screen data involves three steps. The first step is to read
screen data into the VPLUS buffer. The second step is to direct VPLUS to
edit the data according to the edit values entered with FORMSPEC. The
last step is to move the screen data from the VPLUS buffer to fields in
the program.
Figure 4-17 shows how to perform these steps. (Refer to Figure 4-15 for
a description of the terminal input record associated with EXCPT Group
V$DATA.) You read screen data into the VPLUS buffer by using the VPLUS
action, RDTERM, followed by a READ operation (READ returns the event code
for the action). To perform the second step, editing the data, enter the
VPLUS action, EDITS, and a READ operation (READ returns the event code
for the action). VPLUS does the editing specified in FORMSPEC. If you do
not want VPLUS to perform the edits or you want to edit the data
yourself, you may omit this step. When VPLUS finishes the edits and
returns to the program, it gives you a count of the number of errors. If
there are errors, you redisplay the VPLUS form so that the user can
correct mistakes (in this figure, the SHOW action in line 3 is executed).
To perform the last step, moving data from the VPLUS buffer to the
program's input record, enter the VPLUS action, GETDTA, followed by a
READ operation (READ returns the event code for the action).
![[]](../../pic3k/M010422/RPGP4F173c50.gif)
Figure 4-17. Reading a VPLUS Form
![[]](../../pic3k/M010422/RPG4F17A3c50.gif)
Figure 4-17. Reading a VPLUS Form (Continued)
Comments
1 This line defines the input record for processing event code 09
(VPLUS edit errors).
2 This line defines the field, NUMBER, which contains a count of
the VPLUS edit errors.
3 This line displays the VPLUS form on the terminal. The SHOW
action is executed after the EDITS action (see line 8). It
redisplays the form so that a user can correct edit errors.
4 This line enters the VPLUS action, RDTERM, into the output
field, ACTION. RDTERM retrieves data from the terminal and saves
it in the VPLUS buffer.
5 This line performs exception output for the record associated
with EXCPT Group V$ACTN.
6 This line returns the event code for the RDTERM action.
Columns 28-32 contain READ to perform a read to the TERMINAL
file.
7 This line directs program execution to RDSCR7 when a user
presses a function key instead of entering data. (when F0 is
turned on, the user entered data and pressed ENTER .)
8 This line enters the VPLUS action, EDITS, into the output field,
ACTION. EDITS performs the field edits specified by FORMSPEC.
Columns 33-42 contain EDITS to specify the VPLUS action.
9 This line performs exception output for the record associated
with EXCPT Group V$ACTN.
10 This line returns the event code for the EDITS action.
11 When event 09 occurs (an edit error), this line directs program
execution to RDSCR1. RDSCR1 redisplays the form so that a user
can enter corrections.
12 This line enters the VPLUS action, GETDTA, into the output
field, ACTION. GETDTA moves data fields from the VPLUS buffer to
the program.
13 This line performs exception output for the record associated
with EXCPT Group V$ACTN.
14 This READ operation moves fields in the VPLUS buffer to the
corresponding fields in the terminal input record.
15 This line defines the output record associated with EXCPT Group
V$ACTN.
16 This line defines the field, ACTION, which contains the VPLUS
action code.
Processing VPLUS Form Data. Once you retrieve screen data from the VPLUS
buffer with a GETDTA action followed by a READ operation, the data is
moved to the appropriate input record in the program. You process the
data fields in the input record as you would normally.
Moving Data to a VPLUS Form and Displaying It. This section explains how
to display data that is calculated in the program or that comes from
sources such as a disc file. For example, you may want to display master
file information in response to a query.
Figure 4-18 shows how to move disc file information to a terminal file
output record then display it using a VPLUS PUTDTA action.
![[]](../../pic3k/M010422/RPGP4F183c50.gif)
Figure 4-18. Moving Data to a VPLUS Form and Displaying It
Comments
1 This line reads the TurboIMAGE data set file, DACCOUNT.
(Information from this data set will be displayed on the
terminal.)
2 This line begins the MOVE operations that move the data set
fields to the terminal output record. (See Figure 4-15 for a
description of the terminal output record associated with
indicator 85.)
3 The line enters the VPLUS action, PUTDTA, into the output field,
ACTION. PUTDTA moves the terminal output record fields to the
VPLUS buffer.
4 This line performs exception output for the record associated
with EXCPT Group V$DATA.
5 This line enters the VPLUS action, SHOW, into the output field,
ACTION. SHOW displays the form in the VPLUS buffer.
6 This line performs exception output for the record associated
with EXCPT Group V$ACTN.
Displaying Messages with VPLUS. When you use VPLUS, you can display
one-line messages in the message window located at the bottom of the
display. VPLUS automatically displays FORMSPEC data field prompts and
edit errors in the window, but occasionally you may need to use the
window for other purposes.
Figure 4-19 shows how to display a message in the message window. The
example assumes that the message, SELECT MODE WITH FUNCTION KEY, is
placed in the first element of the array, MSG. It also assumes that the
message window fields, MSGLEN and ENHANC, are already initialized.
![[]](../../pic3k/M010422/RPGP4F193c50.gif)
Figure 4-19. Displaying Messages in the VPLUS Message Window
Comments
1 This line sets the index of the MSG array tp 1.
Columns 43-58 contain the name of the index field, M.
2 This line places the VPLUS action, SHOMSG, into the first field
of the message window record. SHOWMSG displays messages in the
VPLUS message window.
3 This line performs exception output for the record associated
with EXCPT Group V$MESG. This is the message window record.
4 This line begins the message window record description.
5 This line specifies that the window message is in the array,
MSG. Since the value of M is one, the first element of the array
is displayed in the message window.
Specifying the VPLUS Error Message Display Interval. RPG run-time error
messages related to VPLUS files (except edit errors or messages you
display in the message window) are displayed for 3 seconds in the message
window.
You can change the time interval, if necessary, by using column 51 of the
File Description Specification.
![[]](../../pic3k/M010422/RPGP4F203c50.gif)
Figure 4-20. Specifying the Error Message Display Interval
Comments
1 This line defines the terminal file, TERMINAL.
Column 51 contains the number of seconds (8) to pause when
displaying errors. You can enter a number from 0 to 9. If you
enter 0, all messages are suppressed.
Changing VPLUS Forms. This section tells you how to display a second
VPLUS form in a program.
The number of forms that you can use is limited only by the number of
forms that can be placed in a forms file. The second and successive
forms are retrieved differently from the first. The first form displayed
in a program is retrieved using the GETNXT action. To retrieve
additional forms, use the CHGNXT action instead of GETNXT. Also enter
Input and Output record descriptions for the new form(s).
Figure 4-21 shows how to retrieve a form from the forms file, FORM2.
(The form is only retrieved, not displayed.) For instructions on how to
display the form, see the section "Displaying an Initialized VPLUS Form."
You display a form the same way shown in that section except that you
omit the GETNXT action. You also perform exception output for the new
form rather than the original.
See the HP RPG Reference Manual for details about the fields used in the
TERMINAL action output record.
![[]](../../pic3k/M010422/RPGP4F213c50.gif)
Figure 4-21. Changing a VPLUS Form
Comments
1 This line sets the repeat/append code (RPTAPP) code to 0. Code
0 does not repeat the current form.
2 This line sets the freeze/append code (FRZAPP) code to 0. Code
0 clears the current form before displaying the next one.
3 This line enters the name of the next form (FORM2) in to the
output field, NXTFRM.
4 This line enters the VPLUS action, CHGNXT, into the action
field. CHGNXT directs VPLUS to retrieve another forms file and
place it into the VPLUS buffer.
5 This line performs exception output for the record associated
with EXCPT Group V$ACTN.
6 This line begins the description of the TERMINAL output record
associated with EXCPT Group V$ACTN.
Using Function Keys with VPLUS. This section explains how to use
function keys and function key labels with VPLUS.
You can use function keys to turn on record identification indicators
instead of using event codes to do this. (For each event code returned
by VPLUS, a corresponding function key is turned on also.) For example,
when the user enters data and presses ENTER , VPLUS returns event code
00 and turns on F0. An advantage of using function keys is that they are
automatically reset for each event. Indicators set by event codes are
not reset by READ operations and can cause erroneous results if you do
not use them properly in the program.
Figure 4-22 shows how to enable the function keys and how to use them to
identify the type of data the user enters on the terminal.
![[]](../../pic3k/M010422/RPGP4F223c50.gif)
Figure 4-22. Using Function Keys with VPLUS
Comments
1 This line defines the terminal file, TERMINAL.
Column 50 contains L to enable the function key labels.
2 This line defines the function key label array, LBL. There are 8
labels in array, each label containing 16 characters.
3 This line enables all function keys.
4 This line uses the setting of F1 to direct program execution.
The subroutine, ADD, is executed when F1 is turned on.
5 This line uses the setting of function key F0 to direct program
execution. Program execution goes to RDSCR1 when F0 is turned
on. F0 is turned on when a user enters data into the VPLUS form
and then presses ENTER .
A Sample Program Using VPLUS. This section lists a complete program that
processes screen data using VPLUS forms.
The program in Figure 4-23 updates the D-ACCOUNTS data set. This data
set keeps customer information such as account number, name and address.
The data set is part of the TurboIMAGE MARKET database whose schema is
shown in Figure 3-23. Users access customer records by the customer's
account number and select the type of update operation by pressing one of
the function keys, F1 , F2 , F3 or F5 (add, change, query, delete).
The program uses VPLUS to handle all screen input and output.
![[]](../../pic3k/M010422/RPGP4F233c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS
![[]](../../pic3k/M010422/RPG4F23A3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23B3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23C3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23D3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23E3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23F3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23G3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23H3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23I3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23J3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
![[]](../../pic3k/M010422/RPG4F23K3c50.gif)
Figure 4-23. Program to Update D-ACCOUNTS Using VPLUS (Continued)
Comments
1 This line defines the terminal as a WORKSTN file and enables the
function keys.
2 This line identifies the VPLUS forms file, FACCOUNT, that is
used.
3 This line associates event code 09 with the input record
indicator 09. Event code 09 reports edit errors to the program.
4 This line describes the field, NUMBER, which contains the edit
error count.
5 This line begins the description of the record that handles all
terminal input except edit error counts (line 4).
6 This line executes the ADD subroutine when the user presses F1
.
7 This subroutine checks to see if the user pressed a valid
function key ( F1 , F2 , F3 , F5 or F8 ).
8 This line begins the subroutine that retrieves the form from the
forms file.
9 This subroutine displays the VPLUS form retrieved in the
subroutine, GETSCR.
10 This line begins the operations that check for VPLUS edit
errors.
11 This subroutine displays messages in the VPLUS message window.
12 This is the output record for displaying VPLUS form data.
13 This is the output record for displaying messages in the VPLUS
message window.
14 This is the last line of Output Specifications. Following it
are the values for the MSG and LBL arrays.