HP 3000 Manuals

Using a Terminal in Full Screen Mode (Continued) [ HP RPG/XL Programmer's Guide ] MPE/iX 5.0 Documentation

HP RPG/XL Programmer's Guide

Using a Terminal in Full Screen Mode (Continued)

Using the RPG Screen Interface (RSI)

RSI is a unique forms handling facility designed to work exclusively with
RPG. In many cases, you can have RSI perform screen handling
automatically during normal logic cycle processing. If you're using the
RSI file for a simple input application, you may prefer to use RSI
CONSOLE files instead of the regular RSI files that use the full
capabilities of RSI (for information on RSI CONSOLE files, see "Using RSI
CONSOLE Files").

To use RSI in an RPG program, perform the following steps (the steps are
discussed in detail in the following sections in this chapter):

* Create the RSI form

Before using RSI to process data in full screen mode, use SIGEDITOR
(see the RPG Utilities Reference Manual) to create a screen form.
When creating the form, you specify headings and titles, where the
data fields are located on the screen, the type of data each field
holds and which function and command keys are used.

* Define an RSI form

When you use SIGEDITOR to define an RSI form, you can have SIGEDITOR
generate the RPG specifications for the form. You then include those
specifications in the RPG program, modifying them when necessary.
Whether or not you or SIGEDITOR creates the specifications, they must
be entered as described below:

File Description Specifications -

These specifications define the file as an RSI WORKSTNR file and,
optionally, the name of the forms file.

Input Specifications -

These specifications define the fields that are used for input.

Output Specifications -

These specifications name the RSI form (in the forms file) to be used
and the data for the fields to be displayed. You can also include a
field for errors and other messages.

* Display and Read the RSI form

Calculation Specifications -

You can display and read the form in one of two ways. If you define
the file as a primary file, RSI performs input and output
automatically during the normal logic cycle. If you define the file
as a demand file, you control input and output by entering the
Calculation Specification operations EXCPT and READ.

In addition, to determine which command keys the user presses at run
time, enter Calculation Specifications to test the command key
indicators. If you need to know which function keys the user
presses, enter one or more Calculation Specifications to test the
values in the RSI STATUS array.

Creating an RSI Form. Figure 4-24 shows how a form is defined using
SIGEDITOR. This form is used in the following sections to illustrate how
RSI is used. The form is used to update the D-ACCOUNTS data set (see the
schema for the MARKET database in Figure 3-23).

Figure 4-24. Creating an RSI Form Using SIGEDITOR

In addition to defining the layout of the form, you must also assign a
name to the forms file and define certain processing requirements. For
example, you may want to process the form using exception output rather
than letting the processing be handled automatically by the RPG logic
cycle.

Figure 4-25 shows the SIGEDITOR Forms Specification screen that lets you
define these requirements.

Figure 4-25. Using the SIGEDITOR Forms Specification Screen

The lower part of the SIGEDITOR Forms Specification screen lets you
enable one or more of the function keys ( F2 - F7 ). To enable a
function key, enter an asterisk for it on this screen.

The function keys F3 - F8 let you simulate the function keys of the
same name on IBM 3x systems. To use them in an RPG program, you must
enable them in on this screen. The function keys are:

Function Key Description

PRNT (PRINT SCREEN) ( F2 ) When enabled, the function key label PRINT SCREEN
appears and lets you simulate the print screen key on
IBM3X systems. When not enabled, the label *PRINT
SCREEN appears at run time and the screen contents are
written to RSIPRINT (DEV=LP).

ROLL UP ( F3 ) Lets you simulate the ROLL UP key on IBM 3x systems.

ROLL DOWN ( F4 ) Lets you simulate the ROLL DOWN key on IBM 3x systems.

CLEAR ( F5 ) Lets you simulate the CLEAR key on IBM 3x systems.

HELP ( F6 ) When enabled, the function key label HELP appears and
lets you simulate the HELP key on IBM 3x systems. When
not enabled, the label *HELP appears and the application
hep facility is activated when the key is pressed.

REC BKSPC (RECORD BACKSPACE) ( Lets you simulate the REC BKSPC key on IBM 3x systems.
F7 )

The last part of the SIGEDITOR Forms Specification screen lets you enable
one or more command keys. You must enable the command keys before using
the corresponding command key indicators in an RPG program. Figure 4-25
shows that all of the command keys are disabled except for command keys
1, 2, 3, 5 and 8 (which correspond to command key indicators KA, KB, KC,
KE and KH).

At run time, the form defined in Figure 4-24 and Figure 4-25 appears as
shown in Figure 4-26. Data is entered in the form to show how the fields
are used.

Figure 4-26. Using an RSI Form Within an RPG Program

Defining an RSI Form. Figure 4-27 shows the specifications generated by
SIGEDITOR for the screen in Figure 4-24. You can create the
specifications yourself, if you prefer or you can modify the ones
generated by SIGEDITOR.

Figure 4-27. RPG Specifications Generated by SIGEDITOR

Figure 4-27. RPG Specifications Generated by SIGEDITOR (Continued)

Comments

1 This line defines the file WRKSTN as a WORKSTNR (RSI) file.

Column 15 is U to specify update file 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 246 characters.

2 This line names the RSI forms file, FACCTFM, to be used in the
program.

3 This line begins the definition of the fields that are used for
input.

4 This line begins the definition of the fields that are used for
output.

Displaying and Reading an RSI Form. You can enter the Calculation
Specifications operations EXCPT and READ to display, then read and RSI
form. You do not need to enter Calculation Specifications to display and
read an RSI form if you entered "N" for Exception Output in SIGEDITOR
because the form is processed automatically during normal logic cycle
processing.

Figure 4-28 shows how to display and read an RSI form using Calculation
Specifications.

Figure 4-28. Displaying and Reading an RSI Form Using Calculation Specifications

Comments

1 This line begins the definition of the input fields in the RSI
form.

2 This line displays the form SCN01 whose definition starts in
line 4.

3 This line reads the data entered into the form by the user and
stores it in the Input Specification fields. When this line is
executed, all of the data entered by the user is available for
processing by the program.

4 This line defines the fields that are displayed in form SCN01.
Field values can be specified as defaults in SIGEDITOR or you
can move the values into the output fields using Calculation
Specifications operations.

Displaying Messages with RSI. There are no special areas of the screen
or special fields for messages. If you want to display a message (for
example, an error message), you must define a field for it. Once
defined, there are several ways you can use the field to display
messages. You can place a message in the field yourself or, if the
message is contained in a User Message Catalog, you can specify the
message number in SIGEDITOR. In that case, the message is read and placed
into the field automatically. Also, you can associate an indicator with
the field in SIGEDITOR, then display the field by turning the indicator
ON at run time.

You cannot use the Calculation Specification DSPLM operation with RSI to
display messages.

Figure 4-29 shows how to display a message contained in the compile-time
array MSG.

Figure 4-29. Displaying Messages in an RSI Form

Comments

1 This line sets the index (M#) to the array MSG to the value 2.

2 This line turns ON indicator 82 which is defined in the "Output
Field" attribute for this field in SIGEDITOR.

3 This line displays the RSI form SCN01.

4 This line defines the message field as part of the form SCN01.
It consists of a single element of the array MSG.

5 This is the second element of the array MSG and is displayed in
line 3.

Using Function Keys with RSI. When you enable any or all of the function
keys F3 - F8 in SIGEDITOR, their labels (as shown below) appear. If
you do not enable them, the labels F3-F8 appear. Even though the
function keys are enabled, RSI does not perform any action when the user
presses them. You must perform the processing yourself by entering
Calculation Specifications.

The function keys are:

Function Key Description

F1 (COMMAND) Used in conjunction with one of the keys on the
top row of the keyboard to turn on the
corresponding command key indicator.

F2 (PRINT SCREEN) If enabled, the function key label PRINT SCREEN
appears though no printing takes place. You
must enter Calculation Specifications to
perform this function. If not enabled, the
label *PRINT SCREEN appears and the contents of
the screen are written to RSIPRINT (DEV=LP).

F3 (ROLL UP) If enabled, you must enter the Calculation
Specifications to perform this function.

F4 (ROLL DOWN) If enabled, you must enter the Calculation
Specifications to perform this function.

F5 (CLEAR) If enabled, you must enter the Calculation
Specifications to perform this function.

F6 (HELP) If enabled, the function lable HELP appears.
You must enter the Calculation Specifications
to perform this function. If not enabled, the
label *HELP appears and the application help
facility is activated when the key is pressed.

F7 (RECORD BACKSPACE) If enabled, you must enter the Calculation
Specifications to perform this function.

F8 (DUPLICATION) If enabled in the Attribute Specification
screen of SIGEDITOR, this key fills the field
(from the cursor position to the end of the
field) with the hexadecimal character 1C (^)
and moves the cursor to the next field. You
can check for these characters and take
appropriate action. For example, you may want
to reuse the field's previous value.

If the user presses a function key that is not enabled, the message
"FUNCTION KEY NOT ENABLED AT THIS TIME" is displayed momentarily.

To determine which function key was pressed, check the value in the first
element of the RSI STATUS array. (Refer to the HP RPG Reference Manual
for these values.) Figure 4-30 shows how to test the array STAT to
determine if the user pressed F4 (ROLL DOWN).

Figure 4-30. Using Function Keys with RSI

Comments

1 This line reads the RSI form and the settings of the function
keys.

2 This line tests the first element of STAT for the value 1123
(which indicates that F4 was pressed).

Using Command Key Indicators with RSI. If you enabled a command key when
you defined the form using SIGEDITOR, you can use the associated command
key indicator in the program to set indicators and to condition
operations. See "Creating an RSI Form" at the beginning of this chapter
for information on enabling the command keys.

If the user presses a command key that you did not enable, the message
"COMMAND KEY NOT ENABLED AT THIS TIME", is displayed momentarily.

Figure 4-31 shows how to use command key 3 (command key indicator KC) to
condition an EXSR operation.

Figure 4-31. Using the RSI Command Keys

Changing Field Attributes with RSI. From time to time, you may need to
define a field's attributes one way in SIGEDITOR, but change them
dynamically at run time. You can change video and protection attributes.
To do this, you must associate an indicator with the attribute in
SIGEDITOR, then turn the indicator ON before the form is displayed.

Figure 4-32 shows how to associate an indicator (41) with the "High
Intense" attribute of a field in SIGEDITOR.

Figure 4-32. Assigning an Indicator to a Field's Attribute

Assuming that the field shown in Figure 4-32 is a field in the output
record R$DATA, Figure 4-33 shows how to display it in high intensity.

Figure 4-33. Changing a Field's High Intense Attribute

Comments

1 This line turns ON indicator 41.

2 This line displays the RSI form. All fields having indicator 41
associated with them in SIGEDITOR are highlighted when the form
is displayed.

A Sample Program Using RSI. This section lists a complete program that
processes data using RSI forms.

The program updates the D-ACCOUNTS data set. This data set keeps
customer information such as account numbers, names and addresses. The
data set is part of the TurboIMAGE MARKET database whose schema is shown
in Figure 3-23. The RSI form is the one shown in Figure 4-24.

Customer records are accessed by the customer's account number. To add a
record, the user presses command key 1 then enters an account number.
"CMD-1 Add" is highlighted and the user can then proceed to add data for
the new customer. When input is complete, the user presses ENTER .
Similarly, to modify an existing record, the user presses command key 2
then enters an account number. "CMD-2 Change" is highlighted and the
customer information in the D-ACCOUNTS data set is displayed. The user
can then change that information, pressing ENTER when input is
complete. To display existing account information for a customer, the
user presses command key 3 then enters the customer's account number. To
delete a customer record, the user presses command key 5 then enters an
account number. The user is asked to confirm the delete, then the record
is purged from the data set.

Figure 4-34. Program to Update D-ACCOUNTS Using RSI

Figure 4-34. Program to Update D-ACCOUNTS Using RSI (Continued)

Comments

1 This line begins the definition of the RSI WORKSTN file WORKSTN.
The forms file for WORKSTN is FACCTFM and the STATUS array is
STAT. (STAT is used to determine if the user pressed ENTER .)

2 This line begins the description of the record used for all
terminal input. (The lines were generated by SIGEDITOR, then
modified.)

3 This line begins the mainline portion of the program. The
subroutine ONETIM is executed only at the beginning of the first
logic cycle. The other subroutines are executed when the user
presses the associated command key (for example, CMD-2 Change).

4 This line begins the subroutine that adds records to the
D-ACCOUNTS data set. The subroutine first resets (in the RESET
subroutine) all indicators used in the previous cycle. Next,
indicators 41 and 80 are turned ON. Indicator 41 is used to
change the video attribute for the constant "CMD-1 Add" so that
the user knows what the current mode is. Indicator 80 is the
"erase input fields" indicator. It causes all input fields to
be cleared before the form is displayed. (This saves having to
initialize each field yourself before displaying the form.)

The form is displayed by the EXCPT R$DATA operation. Then, the
RDSCRN subroutine reads the form and checks to see if the user
pressed the ENTER key or some other enabled command key.
Control remains in the subroutine until the user presses another
command key. When this happens, control proceeds to the end of
the subroutine. (The mainline portion of the program processes
the command key request during the next logic cycle.)

The RECINP subroutine checks to see if the data record already
exists in D-ACCOUNTS. If it does, the account number field is
cleared, and the form is redisplayed with the error message
"EXISTING ACCOUNT NUMBER" (override is in effect so that the
user can enter the correct account number). If there are no
errors (indicator 40 is OFF), a record is added to the data set
by the EXCPT $ADD operation and control goes back to the
beginning of this step.

5 This line begins the subroutine that updates D-ACCOUNTS data set
records. The RESET subroutine turns OFF indicators that were
turned ON during the previous logic cycle, then indicators 42
and 80 are turned ON. The RSI form is displayed, then read. If
the user pressed another command key (indicator 49 is OFF)
control skips to the end of the subroutine.

The RECINP subroutine reads the record from the D-ACCOUNTS data
set. If the record exists, indicator 40 is turned ON and the
form containing account information is displayed. Control skips
to CNGMSG where changes are read. If the record does not exist,
indicator 80 is turned OFF so that the "Erase input fields"
attribute will not be in effect. The error message "INVALID
ACCOUNT NUMBER" is displayed and control skips back to CNGMSG to
accept

the new account information.

After the new information is read, the record in D-ACCOUNTS is
updated by the EXCPT $UPD operation. Control remains in the
subroutine until the user changes modes (presses a different
command key).

6 This line begins the subroutine that locates records in the
D-ACCOUNTS data set and prepares error messages for display.
The CHAIN operation reads D-ACCOUNTS using ACTNO as its key
field. If the record is not found, indicator 60 is turned ON.

If add mode is in effect and the record is found, or if other
modes are in effect and the record is not found, an error
results. The index of the appropriate error message in MSG is
placed in the variable M# and indicator 82 is turned ON.
Indicator 81 is turned ON to allow override and to sound the
alarm (beep). When override is in effect, data on the screen
remains unaltered except for attributes conditioned by
indicators and output fields conditioned by indicators that are
ON.

7 This line begins the subroutine that reads the form and checks
to see if the user pressed a function key. Indicator H0 is
turned ON by the READ WORKSTN operation when a terminal read
error occurs.

When READ is executed, a code that identifies which function key
(if any) was pressed, is placed in the first element of the STAT
array. If the ENTER key was pressed this element equals 0 and
indicator 49 is turned ON. Since none of the function keys were
enabled on the form, the only other possible value is 2 (which
indicates that a command key was pressed).

8 This line begins the output record description for the RSI form.
The specifications were generated by SIGEDITOR, then modified.
The form name is entered as a constant in the first line. It
has a length of 8 and the prefix "K". The field used for
messages, MSG, is indexed by M# (M# contains the number of the
message). MSG is conditioned by indicator 82 and the SIGEDITOR
"Output Data" attribute for MSG also contains 82.

Using RSI CONSOLE Files

RSI CONSOLE files are RSI files that are used for input only and whose
forms file is generated automatically during compilation. RSI handles
all file input and output during run time.

To use an RSI CONSOLE file in an RPG program, perform the following steps
(the steps are discussed in detail in the following sections in this
chapter):

* Define the RSI CONSOLE form

Enter the File Description and Input Specifications that describe the
form, then compile the program. The forms file is generated
automatically. If you wish, you can use SIGEDITOR to modify the
form.

File Description Specifications -

These specifications define the file as an RSI WORKSTNC file.

Input Specifications -

These specifications define the fields that are used for input.

* Process data entered in the form

Calculation Specifications -

Since RSI handles all of the input and output for the CONSOLE form,
you do not enter Calculation Specification operations to do this.
However, you must enter the usual operations to process the data once
it is read.

Defining an RSI CONSOLE File. Figure 4-35 shows the File Description and
Input Specifications that define the RSI CONSOLE file SCRNFILE. SCRNFILE
is defined as a WORKSTNC file (line 1) which consists of three different
forms. The first form is FORM01 and is defined starting with line 2.
(The form name is "FORM" suffixed by the record-identifying indicator for
the record type.) Lines 3 and 4 start the definitions for the second and
third forms, respectively.

Figure 4-35. Defining an RSI CONSOLE Form

When the forms FORM01, FORM02 and FORM03 are displayed at run time, they
appear as shown in Figure 4-36, Figure 4-37 and Figure 4-38.

Figure 4-36. FORM01 Displayed at Run Time

Figure 4-37. FORM02 Displayed at Run Time

Figure 4-38. FORM03 Displayed at Run Time

You can modify the forms generated by RSI yourself or by using SIGEDITOR.
However, do not change the top (status) line, the data type and length of
the fields or the order of the fields.

Figure 4-39 shows how you can modify FORM01 in Figure 4-35 to make it
easier to understand and use.

Figure 4-39. Modifying an RSI CONSOLE Forms File

Displaying and Reading an RSI CONSOLE File. You do not need to enter
Calculation Specifications to display and read an RSI form, the input and
output are handles automatically by RSI during normal logic cycle
processing. Once the data is read, you may enter Calculation
Specifications to process the data the same way you do other file data.

Displaying Messages with an RSI CONSOLE File. You cannot display
messages when using RSI CONSOLE files, since CONSOLE forms are used for
input only. Simple input editing is handled by RSI based on each field's
data type. If the user enters invalid data, RSI displays an error
message and allows the user to correct the data.

Using Function Keys with an RSI CONSOLE File. There are just two
function keys that are used with RSI CONSOLE files and they are described
below. You cannot change the actions that they perform.

Function Key Description

F1 (COMMAND) Used in conjunction with one of the keys on the
top row of the keyboard to select a command key
(see the next section).

F2 (PRINT SCREEN) Copies the contents of the screen to the print
file RSIPRINT (DEV=LP).

If the user presses another function key, the message "FUNCTION KEY NOT
ENABLED AT THIS TIME" is displayed momentarily.

Using Command Keys with an RSI CONSOLE File. If you defined more than
one record type in the CONSOLE file, the user must press a command key at
run time to select the type. For example, to select record type 3
(SUMMARY RECORD) in Figure 4-35, the user presses command key 3. The
command keys do not turn on the command key indicators, as they do with
regular RSI files. Therefore, you cannot use the indicators in the
normal way to condition Calculation Specification operations.

If the user presses a command key not associated with any record type,
the message "FORM CHANGE OR EXIT NOT ACCEPTABLE" is displayed
momentarily.

A Sample Program Using an RSI CONSOLE File. This section lists a
complete program that uses RSI CONSOLE files to read and balance
invoices. Each invoice can have three or more records, where each record
belongs to a different record type (the record types are sequenced).
Each invoice must have a header record that gives the customer name and
address, one or more detail records that list individual items on the
invoice and a summary record that gives the total invoice amount. The
user enters data for the header, detail an summary records in that order.
Each group of invoice records are written to disc along with any errors.

When the program is executed, the first form (FORM01) is displayed. When
the user finishes entering data on the form and presses ENTER , the
second form (FORM02) is displayed. When ENTER is pressed again, the
second form is redisplayed because it can occur more than once in a
group. The user can continue entering detail records or can select the
third form by pressing command key 3 (the record-identifying indicator
for the last record type). When input is complete for FORM03, the user
presses ENTER and the first form is displayed again, starting the
sequence over. The user presses command key 12 to end the program.

Figure 4-40. Invoice-Balancing Program that Uses an RSI CONSOLE File

Figure 4-40. Invoice-Balancing Program that Uses an RSI CONSOLE File (Continued)

Comments

1 This line begins the definition of the RSI WORKSTNC file
SCRNFILE. The forms file for SCRNFILE is INV36SFM which is the
program name in the $CONTROL subsystem command suffixed by "FM".

2 This line begins the description of the invoice header records.

Columns 15-16 contain the record sequence (01) in the group.

Column 17 is 1 to indicate that there is only one header record
per invoice.

Column 18 is blank to indicate that this header record is
required.

Columns 19-20 contain the record-identifying indicator (01) for
the form. The indicator is appended to "FORM" to create the
form name FORM01.

Columns 21-41 contain the record identification code (HD) for
the record. (The code can be one or two characters but must
begin in the first position of the record.)

3 This line begins the description of the record used for
detail invoice records. The form name is FORM02, the
record-identifying indicator is 02 and the record identification
code is DE.

Column 17 is N to specify that there can be more than one detail
record per invoice.

4 This line begins the description of the record that summarizes
each invoice. The form name is FORM03, the record-identifying
indicator is 03 and the record identification code is SU.

5 This line begins the Calculation Specification operations that
do invoice-balancing. It also flags invoices that are
out-of-balance.

Enabling the BREAK Key

On 264X terminals, the BREAK key is physically positioned near ENTER .
As a result, it is easy to press BREAK accidentally. Since it is
difficult to recover from a break, this key is disabled automatically
whenever you use a WORKSTN file.

If you want to use the BREAK key, indicate this in column 52 of the
terminal's File Description Specification as shown below.

Figure 4-41. Enabling the BREAK Key

Comments

1 This line defines the terminal file, TERMINAL.

Column 52 contains B to enable the BREAK key.

Handling Run-Time Errors

When you run a program that uses VPLUS or RSI, run-time errors are
handled differently from programs that do not use them. When using
VPLUS, an error message is displayed in the message window and for RSI,
it is displayed on a separate screen. VPLUS and RSI then reset the
function keys so that the user can select an error response. The
function keys and their responses are:

Function Key: Response

F1 Continue execution

F2 Skip the input record containing the error and
continue execution

F3 Terminate the program by executing the normal
termination code

F4 Terminate the program immediately

F5 Terminate normally and print an error dump

F6 Terminate immediately and print an error dump

You can specify the function key responses within your program instead of
letting the user select them. Use the Header Specification to do this.
For each error you anticipate, enter the response in columns 56-71.
Figure 4-42 shows how to suppress the error message for arithmetic
overflow and to continue program execution when arithmetic overflow
occurs.

Figure 4-42. Specifying a Run-Time Error Response

Comments

1 This line specifies special error handling for arithmetic
overflow errors.

Column 55 contains N to suppress the display of arithmetic
overflow error messages.

Column 65 contains 0 to suppress arithmetic overflow messages
and to continue program execution.