HP 3000 Manuals HP 3000 Manuals
Communicating with Other RPG Programs
The remaining sections in this chapter explain how to use certain
operating system and RPG facilities to communicate information to other
RPG programs. The sections discuss ways to communicate:
* Switches (user indicators U1-U8)
* System file information (retrieved from the operating system LISTF
command)
* Data (Local Data Area)
Communicating Switches
When the information you want to pass to other programs or receive from
them can be put in the form of yes/no or on/off states, you may want to
use user indicators (U1-U8) in your RPG program. User indicators can be
saved and passed to other RPG programs by either:
* Saving the switches in a USWITCH file, or
* Saving the switches in the System-Defined JCW
Both of these methods are discussed in the following sections.
Using USWITCH Files. A USWITCH file is a standard text file that
contains the settings of the user indicators (U1-U8). This file can be
created, read and updated by RPG programs. If you're running in job
mode, you do not need to enter the indicator settings in a USWITCH file.
You can include them as part of the job file. For more details about
using USWITCH files, see the USWITCH sections in the HP RPG Reference
Manual.
You can read a USWITCH file only, or you can read and update it in a
program. The next two sections show how to do this.
Reading a USWITCH File
Figure 8-5 shows how to read the USWITCH file. In this particular
example, user indicator U1 signals that the program should terminate
immediately. User indicator U2 means that the program can access the
master file, GLMAST. These indicators are set by the update program shown
in Figure 8-6. They are read by each application program to ensure that
they do not execute concurrently with the update program or process the
GLMAST file concurrently.
To read a USWITCH file, enter a Header Specification indicating that the
USWITCH file is being used. Then use the user indicator(s) in File
Description, Input, Calculation and Output Specifications.
![[]](../../pic3k/M010422/RPGP8F53c50.gif)
Figure 8-5. Reading User Indicators
Comments
1 This line enables the USWITCH facility.
Column 16 contains F to specify that a USWITCH file is used.
2 This line defines the GLMAST file. It is opened only when user
indicator U2 is turned on.
3 This line displays a message indicating that the update program
in Figure 8-6 is executing and the program must be run later.
Columns 10-11 contain U1 to display the message only when user
indicator U1 is turned on.
Updating a USWITCH File
Figure 8-6 shows how an update program uses the USWITCH file to prevent
other programs from running at the same time. When the program starts,
it turns on user indicator U1. At the end of the update program, when
the last record (LR) indicator is turned on, U1 is turned off and user
indicator U2 is turned on.
Other programs (as shown in Figure 8-5) test U1 to determine whether to
continue and test U2 to determine whether to process the master file,
GLMAST.
![[]](../../pic3k/M010422/RPGP8F63c50.gif)
Figure 8-6. Setting User Indicators to Prevent Simultaneous Program Execution
Comments
1 This line defines the USWITCH file.
Column 16 specifies that this file is a chained file.
Column 30 indicates that the key field length is 1.
2 This line defines the input USWITCH record.
3 This line (at the beginning of the program) turns on indicator
20. Indicator 20 triggers an update of the USWITCH file (U1 is
turned on).
4 This line reads a USWITCH record whenever indicator 20 or the
last record indicator (LR) are turned on.
5 This line describes the USWITCH output record that is written
when indicator 20 is turned on.
6 This line defines the user indicator settings that are written
to the USWITCH file when indicator 20 is turned on.
Columns 45-63 contain "USWITCH: 10XXXXXX" to specify the
settings for the user indicators. User indicator U1 is turned
on, U2 is turned off and the others remain unchanged.
7 This line defines the USWITCH output record that is written when
the LR indicator is turned on.
8 This line defines the user indicator settings that are written
to the USWITCH file at the end of the program.
Columns 45-63 contain "USWITCH: 01XXXXXX" to specify the
settings for the user indicators. User indicator U1 is turned
off, U2 is turned on and the others remain unchanged.
Using the System-Defined Job Control Word (JCW). The System-Defined Job
Control Word (JCW) is a two-byte data area that is part of the operating
system. It provides a way to pass indicators among operating system
routines. Application programs can use the rightmost byte of the JCW for
indicators. The rightmost byte provides up to eight User Switches, one
switch per bit. When these switches are used in RPG, they are called
user indicators (U1-U8).
The System-Defined JCW is easier to use than a USWITCH file. You do not
enter File Description and Input Specifications for the JCW and it is
updated automatically by RPG. The System-Defined JCW has one
disadvantage. Since the system software also uses it, you cannot always
count on switch values remaining unaltered. For more details on JCWs,
see the MPE XL Intrinsics Reference Manual.
Figure 8-7 shows the structure of the System-Defined JCW.
![[]](../../pic3k/M010422/RPGP8F73c50.gif)
Figure 8-7. The System-Defined Job Control Word (JCW)
User Switches are assigned values depending on their relative bit
positions in the Job Control Word (see Figure 8-8). You can test and
change User Switch settings using decimal or octal notation. For
example, to see if user indicator U1 is turned on, you can test JCW=128
(decimal) or JCW=%200 (octal).
![[]](../../pic3k/M010422/RPGP8F83c50.gif)
Figure 8-8. Setting User Switches in the System-Defined Job Control Word (JCW)
Figure 8-9 shows a UDC that uses a System-Defined JCW. The UDC
initializes the JCW (SETJCW JCW=0), then calls a menu program, RMENU.
RMENU prompts the user to select the reports to print. These selections
are saved in the JCW. When RMENU ends, the UDC executes the report
programs indicated by the User Switches in the JCW.
![[]](../../pic3k/M010422/RPGP8F93c50.gif)
Figure 8-9. Using the System-Defined JCW in a UDC
Portions of the program, RMENU (see Figure 8-9), that set User Switches
are shown in Figure 8-10. RMENU prompts the user for report selections
and saves the selections in the System-Defined JCW.
![[]](../../pic3k/M010422/RPGP8F103c50.gif)
Figure 8-10. Using the System-Defined JCW
Comments
1 This line specifies where the values for the user indicators
originate.
Column 16 contains J to specify that user indicator values come
from the System-Defined JCW.
2 This line turns on user indicator U1 when indicator 01 is turned
on. (Indicator 01 is turned on when the user requests the DAILY
report.)
3 This line turns on user indicator U2 when indicator 02 is turned
on. (Indicator 02 is turned on when the user requests the MONTH
report.)
4 This line turns on user indicator U3 when indicator 03 is turned
on. (Indicator 03 is turned on when the user requests the YEAR
report.)
Communicating File Information
This section explains how to use a User-Defined Job Control Word (JCW) to
pass file information between RPG programs. For example, you may need to
exchange the maximum record count for a file with other programs, so that
they will not write beyond the file's limits. You can use a User-Defined
JCW to exchange any information, not just file information.
A User-Defined JCW is a 16-bit logical word located within the operating
system. You can create and use as many User-Defined JCWs as necessary.
When you create them, you assign identifying names to them (the first
character in each name must be a letter). User-Defined JCWs are used
exclusively by application programs. The operating system software does
not use them. Because of this, you may prefer to use them instead of
System-Defined JCWs (see the section "Using a System-Defined Job Control
Word (JCW)" in this chapter). User-Defined JCWs are discussed in detail
in your MPE XL Intrinsics Reference Manual.
The next three figures illustrate how to use a User-Defined JCW. The
first figure shows a UDC that runs program, SIZER. It then creates a
BATCHOUT file based on the record count of an input BATCHIN file computed
by SIZER. Then the UDC executes the program, UPDATE. UPDATE uses the
maximum record count for BATCHOUT to ensure that it does not write beyond
the file's limits.
Two JCWs are used; JCWEOF and JCWLIM. JCWEOF contains the record count of
the BATCHIN file. JCWLIM contains the maximum number of records that can
be written to the output batch file, BATCHOUT.
![[]](../../pic3k/M010422/RPGP8F113c50.gif)
Figure 8-11. Setting a User-Defined JCW - UDC
Figure 8-12 lists segments of the program, SIZER. SIZER updates the
User-Defined JCWs, JCWEOF and JCWLIM with the values placed in the LIMITS
file (LIMITS is created by the UDC in Figure 8-11.)
![[]](../../pic3k/M010422/RPGP8F123c50.gif)
Figure 8-12. Setting a User-Defined JCW - Program SIZER Comments
Comments
1 This line defines the file, LIMITS, created by the UDC.
2 This line describes the input record in the LIMITS file.
Column 27 contains B to specify the record code.
3 This line defines the first field, IEOF.
4 This line defines the second field, ILIMIT.
5 This line creates a User-Defined JCW, JCWEOF, containing the
IEOF field information.
Columns 18-27 names the field, IEOF, that is written to JCWEOF.
Columns 28-32 contain PUTJW to update the User-Defined JCW (this
operation uses the intrinsic, PUTJCW).
Columns 33-42 name the User-Defined JCW, JCWEOF.
Columns 58-59 contain 20 to turn indicator 20 on when the PUTJW
operation is successful.
6 This line creates a User-Defined JCW, JCWLIM, containing the
ILIMIT field information.
Columns 18-27 names the field, ILIMIT, that is written to
JCWLIM.
Columns 28-32 contain PUTJW to update the User-Defined JCW (this
operation uses the intrinsic, PUTJCW).
Columns 33-42 name the User-Defined JCW, JCWLIM.
Columns 58-59 contain 20 to turn indicator 20 on when the PUTJW
operation is successful.
Segments of the program, UPDATE, are shown below. UPDATE reads the
User-Defined JCWs (JCWEOF and JCWLIM) created in Figure 8-12. UPDATE
increments the record count (from JCWEOF) each time a record is written
to BATCHOUT. This number is tested against the file limit in JCWLIM. If
there is no more room to write records, the program ends.
![[]](../../pic3k/M010422/RPGP8F133c50.gif)
Figure 8-13. Reading a User-Defined JCW - Program UPDATE
Comments
1 This line reads the User-Defined JCW, JCWEOF.
Columns 9-11 contain N99 to perform this Calculation operation
when indicator 99 is turned off (at the start of the program).
Columns 28-32 contain FNDJW to read a User-Defined JCW (this
operation uses the FINDJCW intrinsic).
Columns 33-42 contain the name of the User-Defined JCW, JCWEOF.
Columns 43-48 contain the name of the field, EOF, where the
JCWEOF information is stored.
2 This line reads the User-Defined JCW, JCWLIM.
Columns 9-11 contain N99 to perform this Calculation operation
when indicator 99 is turned off (at the beginning of the
program).
Columns 28-32 contain FNDJW to read a User-Defined JCW (this
operation uses the FINDJCW intrinsic).
Columns 33-42 contain the name of the User-Defined JCW, JCWLIM.
Columns 43-48 contain the name of the field, LIMIT, where the
JCWLIM information is stored.
3 Before writing a record, this line increments the output record
count in EOF.
4 This line compares the number of records in the BATCHOUT file
with the maximum number of records it holds. The maximum is
stored in LIMIT. Indicator 20 is turned on when EOF reaches
LIMIT.
5 This line executes a subroutine that displays a warning message.
6 This line turns on the last record (LR) indicator when the
maximum record limit is reached (indicator 20 is turned on).
Communicating Data
A Local Data Area File (LDAFILE) is a special RPG file that you can use
to pass data to other programs and to receive data from them. You can
use an LDA file in a program without entering a File Description
Specification for it. An LDA is defined in an Input Specification as a
User Data Structure.
RPG loads the LDA data into your program when it starts executing and
that data is available at the first cycle (1P) output. When your program
ends, the LDA data is written back to the LDA file automatically.
You create an LDA using the RPGINIT utility (see the RPG Utilities
Reference Manual).
Chapter 5 discusses LDAs in the context of data structures. Refer to
Figure 5-12 and Figure 5-13 for an example of how to use LDAs.