HP 3000 Manuals

HP RPG/XL Programmer's Guide

Using a Terminal in Line Mode 

Line mode is the easiest way to read or display a small number of fields.
For example, line mode can be the simplest way to read a date from the
terminal.  The "line mode" sections which follow in this chapter explain
how to read and display data and how to use function keys and message
files in line mode.

When using line mode, you normally use the system-defined files $STDIN
for terminal input and $STDLST for terminal output.  $STDIN and $STDLST
are assigned to the devices shown below:

When running in this mode:       $STDIN, $STDLST have these device assignments: 

Session                          User terminal

Job                              Job stream file, job stream list file

When necessary, you can redirect $STDIN and $STDLST to other devices by
using the operating system FILE command.

Reading and Displaying Data 

There are two ways to read and display data on a terminal.  You can use
the Calculation Specification operations READ and EXCPT or you can use
the Calculation Specification operations DSPLY or DSPLM.

The READ/EXCPT method is more flexible but requires more coding.  DSPLY
and DSPLM are simpler to use and they justify numeric input data.  DSPLM
also displays data from message files.

Using READ and EXCPT.  One method of using a terminal to read and display
data is to use the Calculation Specification operations, READ and EXCPT.
You can use one READ operation to read several fields at once.  EXCPT
performs exception output to $STDLST.

If you want to reassign $STDIN and $STDLST to other devices, enter the
appropriate operating system FILE equation(s) before running the program.
For example, the following FILE equation creates the DATES file on disc
and redirects $STDLST to it (see Figure 4-2 for an example of how $STDLST
is used in the program),

:FILE STDLIST=DATES;SAVE;DEV=DISC;REC=-10,25,F,ASCII;DISC=25

Figure 4-2 shows how to use READ and EXCPT to read data from and write
data to a terminal.  The File Description Specifications assign the files
INPUT and OUTPUT to the system-defined files, $STDIN and $STDLST,
respectively.  The READ operation reads a date in the format, MMDDYY,
from the terminal.  The date is converted to a YYMMDD format and this
converted date is displayed using EXCPT (exception output).


          Figure 4-2.  Using READ and EXCPT to Read and Display Terminal Data 

            Comments 

 1       This line defines the input file, INPUT, and assigns it to the
         system-defined file, $STDIN.

 2       This line defines the output file, OUTPUT, and assigns it to the
         system-defined file, $STDLST.

 3       This line begins the input record description for the file,
         INPUT.

 4       This line reads 6 characters from the terminal and saves them in
         the field, MMDDYY.

         Columns 58-59 direct RPG to turn on the LR indicator when the
         user enters an end-of-data signal (:EOD or :).

 5       This line turns on the resulting indicator 80.

 6       This line performs exception output (lines 7 and 8) when the
         user enters a valid date.

 7       This line begins the output record description for the file,
         OUTPUT.

A Sample Program Using READ and EXCPT 

Figure 4-3 lists a program that updates an TurboIMAGE data set using READ
and EXCPT. The data set that is updated is M-SOURCE (see the schema for
this data set in Figure 3-21).  The program prompts a terminal user to
enter a source code (SRCCDO). It then reads the source code record in
M-SOURCE. If the record exists, the source description field is updated.
If the record does not exist, a new record is added for that source code.
The next section, "Running the Sample Program," shows what a typical
display looks like when the program is executed.

The program in Figure 4-6 is identical to that shown in Figure 4-3,
except that Figure 4-6 uses DSPLY instead of READ/EXCPT. Comparing these
programs should help you to understand the differences between READ/EXCPT
and DSPLY/DSPLM.


          Figure 4-3.  Using READ and EXCPT to Update the M-SOURCE Data Set 


          Figure 4-3.  Using READ and EXCPT to Update the M-SOURCE Data Set (Continued) 


          Figure 4-3.  Using READ and EXCPT to Update the M-SOURCE Data Set (Continued) 


          Figure 4-3.  Using READ and EXCPT to Update the M-SOURCE Data Set (Continued) 

            Comments 

 1       This Header Specification enables buffer-checking for all files.

         Column 28 contains X to enable full buffer-checking for the
         files.

 2       This line defines the terminal file, STDIN.

         Columns 20-23 contain 30 to provide for the longest input field.

 3       This line defines the terminal file, STDLIST.

         Columns 20-23 contain 70 to provide enough space for the longest
         display line.  RPG automatically pads with blanks to the end of
         the line.

 4       This line defines the STDIN field, ANSWER.

 5       This line reads data from the terminal.  The user enters either
         a source code or an E to end the program.

         This READ operation does not turn off indicators set by the
         previous READ. Indicator 01 must be turned off by a Calculation
         Specification to prevent last record output when E in column 1
         turns on indicator 09.

 6       This line performs exception output when a record is found in
         M-SOURCE.

 7       This line reads data from the terminal and saves it in the
         field, ANSWR.

 8       This line performs exception output to the terminal.  The
         message contained in the CRT array, ----- RECORD UPDATED -----,
         is displayed.

 9       This line begins the output record description for records that
         are added to M-SOURCE. New records are written when indicators
         01 and 60 are turned on.

 10      This line begins the output record description for records that
         are updated in M-SOURCE. Records are updated when indicator 01
         is turned on and indicator 60 is not turned on.

 11      This line begins the output record description for displaying
         the source description.  This record is displayed when an EXCPT
         CRTMSG calculation is executed and indicator 81 is turned on.

 12      This line begins the output record description for prompting the
         user to enter data.  This record is displayed when an EXCPT
         CRTMSG calculation is executed.

Running the Sample Program 

Figure 4-4 shows what a terminal dialogue might look like when the sample
program in Figure 4-3 is executed.  A user at a terminal is updating
source codes 111A and 112A. Two updates are required for source code 112A
because the user made a mistake on the first try.  The lines that the
user enters are shaded.


          Figure 4-4.  Running the M-SOURCE Update Program 

Using DSPLY and DSPLM.  The Calculation Specification operations, DSPLY
and DSPLM, are alternative ways to read and display data using the
terminal.  They have two advantages over READ/EXCPT (see the section
titled "Using READ and EXCPT").  First, numeric input data is stored
right justified and zero-filled; users do not have to enter leading zeros
for these fields.  Second, one operation (either DSPLY or DSPLM) is used
for both reading and displaying data.

DSPLY and DSPLM are used the same way except for the Factor 1 Field.  For
DSPLY,

Factor 1 contains either a variable or constant.  For DSPLM, Factor 1
contains a message identification.  DSPLM displays messages from a User
Message Catalog (see the section titled "Using Message Files" for more
information on how to display messages from a User Message Catalog file).

Figure 4-5 shows how to use DSPLY. A date in the format, YYMMDD, is read
from the terminal.  This date is converted to MMDDYY format and
displayed.


          Figure 4-5.  Using DSPLY to Read and Display Terminal Data 

            Comments 

 1       This line defines the output file, OUTPUT.

         Columns 40-46 contain the device class name, $STDLST.

 2       This line displays the prompt, YYMMDD. It then reads 6
         characters from the terminal and saves them in the field,
         YYMMDD.

 3       The line converts the date into a MMDDYY format.  For example,
         when 890318

         is multiplied by 100.0001, the result is 89031889.0318.  When
         saved in the result field, this number becomes 031889.

 4       This line displays the converted date field, MMDDYY, on the
         terminal.

A Sample Program Using DSPLY 

Figure 4-6 lists a program that updates an TurboIMAGE data set using
DSPLY. The data set that is updated is M-SOURCE (see the schema for this
data set in Figure 3-21).  The program gets a source code (SRCCDO) from
the terminal user, then reads the corresponding record in M-SOURCE. If
the record exists, the source description field is updated.  If the
record does not exist, a new record is added for that source code.

The update program in Figure 4-6 is the same as that shown for READ/EXCPT
in Figure 4-3.  Comparing these programs should help to clarify the
differences between READ/EXCPT and DSPLY.


          Figure 4-6.  Using DSPLY to Update the M-SOURCE Data Set 


          Figure 4-6.  Using DSPLY to Update the M-SOURCE Data Set (Continued) 


          Figure 4-6.  Using DSPLY to Update the M-SOURCE Data Set (Continued) 

            Comments 

 1       This line prompts the user to enter a source code.  It then
         reads that source code into the field, SRCCDO.

 2       This line displays the third element of the array, CRT. This
         element is a heading line for the source description.

 3       This line displays the source description (SRCDS) retrieved from
         the M-SOURCE data set.

 4       This line displays the second element in the array, CRT. This
         element prompts the user to enter a new description.  Then the
         new description is saved in the field, SRCDSO.

 5       This line displays the fourth element in the array, CRT. This
         element acknowledges that the M-SOURCE record is updated.

Using Function Keys 

This section explains how to use function keys ( F1  through  F8 ) in an
RPG program.  It discusses how to sense them when they are pressed on the
keyboard.  If you want to display labels for the function keys, see the
next section titled "Displaying Function Key Labels."

The Calculation Specifications shown in Figure 4-7 use  F8  to end a
program.  This function key is activated at the beginning of the
Calculation Specifications section.  When the user presses it, the LR
indicator is turned on and the program ends.  (See Figure 4-12 for the
listing of an entire program that uses function keys.)


          Figure 4-7.  Using the Function Keys 

            Comments 

 1       This line enables function key  F8  (SET F@ enables all of the
         function keys).

 2       This line turns on the LR indicator when function key  F8  is
         pressed.

 3       This line directs program execution to the END tag when the LR
         indicator is turned on.

Displaying Function Key Labels 

This section explains how to display function key labels.  If you're
using function keys in a program (function keys are discussed in the
previous section) you may want to display labels for them also.  Function
key labels are displayed at the bottom of the screen and are highlighted.

Figure 4-8 shows how to activate function keys 4, 7 and 8 ( F4 ,  F7  and
 F8 ) and how to display their labels.  When these function key labels
are displayed, they look like this:


          Figure 4-8.  Displaying Function Key Labels 

            Comments 

 1       This line defines the array, KEYLBL, that contains the function
         key label text.  There are 8 labels in the array, each label
         containing 16 characters.

 2       This line enables the function keys  F4 ,  F7  and  F8 .  It
         also displays the function key labels saved in the KEYLBL array.

 3       This line is the last line of Output Specifications.  Following
         this line are the contents of the function key labels array
         (KEYLBL).

Using Escape Sequences 

Escape sequences let you perform many terminal-handling functions for
which there is no corresponding RPG language facility.  For example, you
can use escape sequences to set graphics mode, move the cursor and reset
the terminal.

The Calculation Specification operation, DSPLY, can be used to "display"
escape sequences.  You enter an escape sequence literal in the Factor 1
Field of a Calculation Specification.  Figure 4-9 shows how to use escape
sequences to home the cursor, clear the screen and release a memory lock.
Instead of entering the escape sequences as literals in your program, you
can enter them into a message file (see the next section for information
on message files).


          Figure 4-9.  Using Escape Sequences 

            Comments 

 1       This line displays the escape sequences for homing the cursor
         and clearing the screen.  The escape character is indicated here
         by a ^.

 2       This line displays the escape sequence for performing a memory
         lock.  The escape character is indicated here by a ^.

Using Message Files 

A message file is a convenient place to keep the text of messages
displayed in an RPG program.  You can alter the text of these messages
when required without recompiling your program.  Message files in RPG are
called User Message Catalog files.

To use a message file, you must first create a source file containing the
message text.  Then, you use either MAKECAT or GENCAT to convert the
source file to a User Message Catalog file.  The message files created by
MAKECAT and GENCAT are different.  GENCAT message files have a compressed
format, requiring less disc space, and they can be used with the Native
Language Support (NLS) System.  Although MAKECAT and GENCAT generate
message files having different physical formats, you access messages in
them the same way within an RPG program.

Creating a Message File.  This section explains how to create a message
source file and how to convert it into a User Message Catalog file using
GENCAT. For details on using GENCAT, see the Native Language Programmer's 
Guide.  For information on using MAKECAT to convert the file, see the
Message Catalogs Programmer's Guide.

Figure 4-10 gives the terminal dialogue for creating a message source
file using EDITOR and for executing GENCAT. (The lines that are shaded
are the ones that a user enters.)  Although this example uses EDITOR, you
can use any editor that produces a standard text file.  You organize
messages into sets (see the $SET lines).  Normally, sets contain similar
kinds of messages.  Within sets, you enter message text and associated
message numbers.  When a message is long, enter it according to how you
want to display it.  To display the message as a continuous string of
characters, end message text lines with &.  If you want to format the
lines that are displayed, enter each line of text as you want it
displayed, and end each line with a %.

As shown in Figure 4-10, GENCAT converts the message source file, CAT4,
into a User Message Catalog file.  It is saved with the name, CATALOG.
(All User Message Catalog files have the name, CATALOG.)


          Figure 4-10.  Creating a User Message Catalog File 

Reading a Message File.  This section explains how to use the Calculation
Specification operation, DSPLM, to read and display messages contained in
a User Message Catalog file (see the previous section for information on
how to create a User Message Catalog file).

Although this section does not show how to use the Calculation
Specification operation, MSG, you can use it also to access messages in a
User Message Catalog file.  Instead of displaying a message, MSG saves it
in a field specified by the program.  MSG is useful when you need to
tailor a message before displaying it.

Figure 4-11 shows how the messages shown in Figure 4-10 are accessed and
displayed using DSPLM. You enter a message identification number with
DSPLM that identifies a message in the User Message Catalog file.  RPG
retrieves that message and displays it.  RPG assumes that the User
Message Catalog name is CATALOG. If the file has another name, enter a
system FILE command before running the program that equates the name to
CATALOG. For instance, to equate the name, CAT4, enter this file
equation,

FILE CATALOG=CAT4


          Figure 4-11.  Using a User Message Catalog File 

            Comments 

 1       This line displays message 1:1 from the User Message Catalog.

         Columns 18-27 identify the message (1:1) in the User Message
         Catalog file (see line 2 in Figure 4-10).  The identification
         number consists of two parts.  The first part is the message
         number (1) within the set and the second part is the set number
         (1).

         Columns 28-32 contain DSPLM to specify that the data to be
         displayed on the terminal comes from a User Message Catalog
         file.

 2       This line displays message 2:1 from the User Message Catalog and
         accepts a date entered by the user.

         Columns 18-27 identify the message (2:1) in the User Message
         Catalog file.  (See line 1 for an explanation of the message
         identification.)

         Columns 28-32 contain DSPLM to specify that the data to be
         displayed on the terminal comes from the User Message Catalog
         file.

         Columns 43-48 contain the name of the field, MMDDYY, where the
         user-entered date is stored.

 3       This line displays message 10:1 from the User Message Catalog.

         Columns 18-27 identify the message (10:1) in the User Message
         Catalog file.  (See line 1 for an explanation of the message
         identification.)

         Columns 28-32 contain DSPLM to specify that the data to be
         displayed on the terminal comes from the User Message Catalog
         file.

A Sample Program Using Message Files.  Figure 4-12 lists a program that
uses the User Message Catalog file created in Figure 4-10.  This message
file contains user prompts and informational messages.

The program updates the TurboIMAGE data set, M-SOURCE. (see the schema
for this data set in Figure 3-21).  The program gets a source code
(SRCCDO) from the terminal user, then reads the corresponding record in
M-SOURCE. If the record exists, the source description field is updated.
If the record does not exist, a new record is added for that source code.
Users delete records by pressing  F2  and end the program by pressing  F8 
.  (After entering data or pressing a function key, users must press  
RETURN .)


          Figure 4-12.  Updating the M-SOURCE Data Set Using a User Message Catalog File and the Function Keys 


          Figure 4-12.  Updating the M-SOURCE Data Set Using a User Message Catalog File and the Function Keys (Continued) 


          Figure 4-12.  Updating the M-SOURCE Data Set Using a User Message Catalog File and the Function Keys (Continued) 

            Comments 

 1       This line suppresses the display of DSPLY literals and causes
         all terminal input to be entered on a separate line on the
         screen.

 2       This line enables function keys  F2  (delete a record) and  F8  
         (end).

 3       This line turns  F2  off.  (You must specifically turn off
         function keys.)

 4       This line displays message 01:3 from the User Message Catalog
         file (see line 9 in Figure 4-10).

 5       This line ends the program when the user presses  F8 .

 6       This line displays message 03:3 from the User Message Catalog
         file (see line 11 in Figure 4-10).

 7       This line displays message 02:3 from the User Message Catalog
         file (see line 10 in Figure 4-10).

 8       This line compares SRCDSO (source description) to blanks when  
         F2  is not turned on.

         Columns 9-11 contain NF2 to perform the compare when  F2  is not
         pressed.  (SRCDSO is blank even when  F2  is pressed.)

 9       This line displays message 04:3 from the User Message Catalog
         file when  F2  is not pressed (see line 12 in Figure 4-10).

 10      This line displays message 05:3 from the User Message Catalog
         file when  F2  is pressed (see line 13 in Figure 4-10).

 11      This line describes the output record format for a delete
         operation.  A record is deleted in M-SOURCE when the user
         presses  F2 .

MPE/iX 5.0 Documentation