INTRODUCTION

RPG is both a position-oriented and free-format language. This means that certain information, such as control codes and field names, must be placed into specific positions of the RPG program statements. Failure to fulfill this obligation results in an error message. The free-format component of RPG IV is supported in the procedure area (known as the calculation specifications) and to a lesser extent in a keyword area of the data definition.

In a free-form procedure language such as COBOL, the value of one variable (or "field") can be copied to another by specifying the following statement:

MOVE FIELDA TO FIELDB

Most high-level languages use the MOVE instruction to copy data. There is no documentation as to how this tradition started, but it's taken for granted now. The preceding COBOL statement copies each character from the memory location of the first field, FIELDA, to the memory location of the second field, FIELDB.

The same program statement written in C or C++ might look like this:

strcpy(fieldbm fielda);

In traditional RPG programs, the same program statement looks like this:

[PROGRAM LISTING NOT REPRODUCIBLE IN ASCII]

Using free-format RPG IV commands, the same program statement could look like this:

[PROGRAM LISTING NOT REPRODUCIBLE IN ASCII]

Or like this:

[PROGRAM LISTING NOT REPRODUCIBLE IN ASCII]

The three forms of RPG IV statements shown above are referred to as fixed format, columnar expression format (sometimes called "hybrid free -format"), and free format. The first two styles of coding are referred to as "Traditional RPG IV" and the third style is often referred to as "/free" or "free -format." This is because the free-format style was added much later in the life of RPG IV. The field being copied (FIELDA) is referred to as the source field. The field that receives the data is referred to as the target or result field.

The MOVE and EVAL instructions appear in positions 26 through 35. These positions contain the program instruction or operation code. The operation code is commonly referred to as operation or opcode.

The letter "C" must appear in position 6 of RPG "Calculation" statements, except when using free-format; in that case position 6 must be blank. Different letters are used to identify the various types of program statements (or specifications). The available specifications are:

* Header specification. * File specifications. * Definition specifications. * Input specifications. * Calculation specifications. * Output specifications. * Procedure specifications.

Ordinarily, an editor is available that provides prompting for "fill-in-the-blank" coding of the different RPG specifications. Consequently, programmers need not be concerned with remembering specific positions. However, a thorough knowledge of the various specification types and their layout will greatly improve programmer efficiency.

Another example of the position-oriented structure of RPG follows. Suppose three account totals need to be accumulated. In a free-format procedure language such as PL/I, the program statements look like the source code shown in Figure 1.1.

In traditional RPG, the equivalent program looks like the code shown in Figure 1.2.

In this example, the IF operation is used to compare the field ACCT to three numbers, and then the value of the field AMOUNT is added to one of three total fields.

RPG requires an associated ENDIF operation for each IF operation. This is because IF operations are treated as an IF-THEN-DO structure. This allows several statements to be conditioned and performed for each IF operation. As a by-product, the program's complexity is reduced. However, when IF statements are nested too deeply (usually more than three levels deep) the program's readability is reduced. Readability can be improved greatly, however, through the use of an in-line case structure. RPG support two forms of in-line case. The first is the SELECT-WHEN operations. The source code shown in Figure 1.2 — rewritten using the SELECT-WHEN operations — is illustrated in Figure 1.3a.

The second form of in-line case is the IF statement itself. However, later versions of RPG include a new ELSEIF operation that eliminates the need for multiple ENDIF statements. The source code shown in Figure 1.2 — rewritten using the SELECT-WHEN operations — is illustrated in Figure 1.3b.

The primary difference between these three examples is readability. The SELECT-WHEN requires only one ENDSL statement for the entire case group. The IF/ELSEIF style also requires only one ENDxx statement. The SELECT-WHEN operations are available on all versions of RPG, whereas the IF/ELSEIF option (Figure 1.3b) is only available on later releases of RPG.

POSITION-ORIENTED PROGRAM SPECIFICATIONS

To simplify writing RPG programs, various preprinted specification forms are available. These forms allow an application program to be written while making certain the correct positions are used. The source statements that make up an application program are transferred to the computer for compilation. This process,known as desk coding, was very popular before the onslaught of desktop personal computers, with their full-screen editors, as well as the full-screen editor available with the OS/400 operating system.

Very little desk coding is done any longer. Programmers usually write pseudocode (a free-format, English-like, logic-based language that is not compiled). The pseudocode is translated, by hand, into a high-level language. Pseudocode strongly resembles PL/I. When translating pseudocode into a high-level language, such as RPG, a full-screen editor or integrated development environment (IDE) is used to provide a more productive environment with fewer typing errors. This can result in fewer errors being placed into the source program.

Several full-screen editors are available to the RPG programmer, including CodeStudio, a GUI Microsoft Windows-based IDE for RPG and DDS; SEU, the source editor that comes with OS/400; and the GUI-based IDE offered by IBM. These source-code editors provide prompts that allow RPG program statements to be written easily. The editors correctly format the program statement to match the RPG specification.

A programmer with experience writing RPG programs using 80-position cards on an IBM 029 or 129 keypunch machine will appreciate using an online, full-screen editor or IDE that checks the syntax of statements as they are entered. A novice programmer typically makes a few mistakes anyway and will benefit from the assistance these RPG editors offer.

A BRIEF LANGUAGE

One of the first things anyone should learn about RPG is that it is a brief language. Only a few statements are needed to read a record, change the data in that record,and then update the record. With other languages, such as COBOL, dozens of lines of code are required to perform this process.

Languages such as the C language are often thought to be brief. Actually, RPG is the briefest of all higher-level languages. For example, to read a file containing orders, multiply the quantity ordered by the price, and update the file with the new information, only four RPG statements are required. See Figure 1.4.

On line 10 of the example shown in Figure 1.4, the file ORDERS is defined as the primary file (indicated with the letter "P" in position 18). The file is declared as an update file (indicated with the letter "U" in position 17). The records that are read are modified on line 20 by multiplying the quantity ordered by the price, giving the amount due. Each record is automatically updated (i.e., rewritten with the new value) on lines 30 and 40 by the RPG cycle. (Line 30 contains the name of the record format for the file ORDERS; line 40 contains the name of the fields that are updated.)

As demonstrated in Figure 1.4, RPG can be one of the fastest programming languages with which to write. Once a programmer has learned the essentials, and adding in the benefit of prompting source code using an IDE or editor, the RPG language can be the easiest language to use and the most productive for general -purpose business applications.

SPECIFICATION TYPES

RPG programs consist of statement specifications. Specifications provide the layout of each area of the RPG program. For example, the calculation specification defines where each component of a calculation statement belongs. The most common specifications include those listed in Table 1.1.

Although no single specification is required by every program, when more than one type is used (as is normally the case in RPG programs), the specifications must appear in a specific sequence. The exception is the procedure specification. The procedure specification defines the beginning and end of a subprocedure — a kind of subroutine or subprogram in RPG. Table 1.2 lists all the RPG specifications and the correct sequence.

The calculation specification and the alternate calculation specification can be intermixed without regard for one another. The RPG compiler determines which calculation specification is being used by inspecting the operation code. Table 1.3 lists descriptions of each RPG IV specification. For more information on each specification form, see chapter 2.

RPG COMPONENTS

Every RPG program is made up of components. Each component is defined through one or more RPG specification. A description of some of the components follows.

* Files. The names of files that will be accessed by the RPG program.

* Input. The information read and processed by the program.

* Fields, Arrays, Data Structures, and Named Constants. The names of the variables — referred to as "fields" in the RPG language — and constants that are used to store, compare, and process information within the program.

* Labels. The names assigned with BEGSR, ENDSR, KLIST, PLIST, EXCEPT, and TAG identifiers. They are used to label subroutines, access data files, declare parameter and key lists, control output, and act as the target of a GOTO, respectively.

* Calculations. The computations (e.g., math, field manipulation, decisions, and array searching) performed on the information within the program.

* Output. The results of the program. The processed data is written to a printer, written or rewritten (updated) to a data file, or presented to a user through a workstation device.

* Procedures. The portions of code that are called to perform a specific task and often to return a value to the caller.

RPG LIMITATIONS

Like all high-level languages, RPG has a set of restrictions. RPG IV has fewer limitations than previous versions of RPG. The features listed in Table 1.4 document any significant RPG language restrictions, along with several previous limitations that have been removed in RPG IV. These are marked "No limit."

NAMING CONVENTIONS

As with other computer languages, RPG has standard naming conventions. Table 1.5 lists the criteria for each named component of an RPG program. Unless otherwise noted, all names must be unique. For example, the name of a data structure cannot be the same as that of an array.

DATA TYPES

RPG supports a wide variety of data types such as character, numeric, packed decimal, pointer, date, and time. Data types are used to declare field and array element attributes. This attribute is specified in the data-type position of the definition specification or it is inferred by the compiler when a variable is defined on the calculation specification. Table 1.6 lists the available data types supported by RPG.

INDICATORS

Indicators are logical variables or switches that are either on or off; that is, they contain a value of 1 or 0. Indicators are used to control program logic, program termination, output, signal conditions, and to communicate with device files.

For example, when an indicator is used to condition the ADD operation, the indicator is tested before the ADD operation is performed. If the indicator test is true, the ADD operation is performed. If the indicator test is false, the ADD operation is bypassed, and the program goes to the next statement. Figure 1.5 shows an example.

Logically, this program is illustrated as shown in Figure 1.6.

In early versions of RPG (RPG and RPG II), structured programming constructs did not exist. Consequently, the indicator usage proliferated. However, the modern RPG programmer avoids the use of indicators except where it is impossible to ignore them (such as in accessing files). In place of indicators, structured operations are used to control program logic. Today, the use of the numeric indicators is all but eliminated.

Indicatorless RPG Code

The example code shown in Figure 1.5, if rewritten with structured RPG operations, would appear as shown in Figure 1.7.

In pseudocode, the program (Figure 1.7) is illustrated by Figure 1.8.

Notice how concise and readable the program becomes when structured operations are used properly. A side effect of the use of structured operations is that programs tend to run more efficiently than they do when indicators control the logic. This is a by-product of the OS/400 RPG compilers and not inherent of compilers in general. Table 1.7 lists definitions of the various types of indicators supported by RPG.

INDICATOR USAGE

Indicators were used extensively in early RPG programming to control program logic, identify input, condition output, detect errors, and signal certain "events." Due to support for structured programming constructs, extensive use of indicators is no longer an endorsed programming practice. However, many hundreds of thousands, or perhaps even millions, of RPG application programs have been written. This represents nearly 1 billion lines of RPG code. A large percentage of that code was written prior to structured constructs being added to RPG. These programs have to be maintained. When maintaining these applications, try to convert as much of the application as possible to structured programming. Often, this can be accomplished without affecting the program's overall design.

Nowadays, a typical application program uses fewer than four indicators, unless communicating with a device file necessitates using more. The recommendations for each of the four indicators follow:

* "Trash" Indicator. The "trash" indicator is used for just about anything. For example, it can be used to condition the ENDDO statement of a DO ... ENDDO loop construct or to indicate the result of various operations such as LOOKUP, COMP, SCAN, TEST, MULT, and DIV.

* Error Indicator. The error indicator is used to signal error conditions such as record locking, device file time-out, or other errors.

* File Status Indicator. The file status indicator is used to signal various file conditions such as record not found, end of file, or beginning of file. In some cases, such as with small programs, the indicator used as the file indicator also can be used as the error indicator.

* Program Termination Indicator. Normally, the last record indicator (LR) or the return indicator (RT) is used as the program termination indicator. LR signals that the program should terminate upon reaching the end of calculation specifications or when the return (RETURN) operation is performed. RT, when used independently, signals that the program should end, but remain active in memory at the completion of the calculation specifications.

When communicating with a workstation, printer, or telecommunications device file, the number of indicators being used can increase. This is primarily due to limitations in the technology being used for device-file definition. Also, each function key (i.e., special keys on every keyboard that normally cause an immediate reaction by the program) can result in the use of an additional indicator.

FUNCTION KEY ATTENTION IDENTIFICATION BYTE

An alternative to assigning function-key response indicators is being used more frequently in RPG applications. This method avoids indicator assignment and uses the function key attention identification byte (located in position 369 of the workstation information data structure) to identify which function key has been pressed. Table 1.8 illustrates how this byte can be interpreted.

INDICATOR CLASSIFICATION

Depending on the type of RPG specifications being used, indicators have various definitions. A list of the indicator classifications and definitions follows.

Overflow Indicator. An indicator that is specified as an overflow indicator (i.e., the OFLIND keyword on the file specification for a printer device file) is set on automatically when the overflow line for a printer file is printed. The overflow line is identified by the FORMOFL keyword on the file specification.

Record-Identifying Indicator. The record-identifying indicator is an indicator specified for the record identification position of the input record specification. RPG automatically sets on a record-identifying indicator when a record is read that matches the record type for the record-identifying indicator.