RPG books, sample code, etc.
From the book RPG/400 User's Guide (RPG III)
CONTENTS Table of Contents
Of Special Interest:
8.6.4 Sample Program 4-WORKSTN Subfile Processing
see the enhanced Subfile program
in this table of contents, the numbered chapters are links to the chapters.
CONTENTS Table of Contents
FRONT_1 Notices
FRONT_1.1 Programming Interface Information
FRONT_1.2 Trademarks and Service Marks
FRONT_2 About This Manual
FRONT_2.1 Who Should Use This Manual
FRONT_2.2 How to Interpret Syntax Diagrams
1.0 Chapter 1. An Introduction to the RPG/400
1.1 The OS/400 System
1.2 The AS/400 Control Language
1.2.1 Commonly Used Control Language Commands
1.3 System/38 Environment on the AS/400 System
1.4 AS/400 Utilities and Languages
1.4.1 The Source Entry Utility
1.4.2 The Screen Design Aid
1.4.3 The Structured Query Language
1.4.3.1 Restrictions
1.5 Designing Your RPG/400 Program
1.5.1 Designing the Output
1.5.2 Designing the Processing
1.5.3 Designing the Input
1.6 Structured Programming in the RPG/400 Programming Language
1.6.1 Sequential Operation
1.6.2 Conditional Branching
1.6.2.1 If Else Structure
1.6.2.2 SELEC Structure
1.6.2.3 Other Conditional Branching Structures
1.6.3 Repeating an Operation
1.6.3.1 Do Operation
1.6.3.2 Do While Operation
1.6.3.3 Do Until Operation
1.6.4 Summary of Structured Programming Operation Codes
1.7 Designing Applications
1.7.1 Single Program Design
1.7.2 Modular Program Design
1.7.3 Examples of Application Design
2.0 Chapter 2. Entering RPG/400 Specifications
2.1 The RPG/400 Specifications
2.1.1 The Control Specification
2.1.2 File Description Specifications
2.1.3 Extension Specifications
2.1.4 Line Counter Specifications
2.1.5 Input Specifications
2.1.6 Calculation Specifications
2.1.7 Output Specifications
2.2 Entering Your Program
3.0 Chapter 3. Compiling an RPG/400 Program
3.1 Create RPG400 Program (CRTRPGPGM) Command
3.1.1 Using the CRTRPGPGM Command
3.1.1.1 Elements of the CRTRPGPGM Command Lines
3.1.1.2 Entering Elements from the CRTRPGPGM Command Display
3.1.1.3 Entering Only Certain Parameters
3.1.1.4 Entering Only the Parameter Values
3.2 CRTRPGPGM Command
3.3 Compiling under the System/38 Environment
4.0 Chapter 4. Error Messages, Testing, and Debugging
4.1 Using, Displaying, and Printing Messages
4.1.1 Using Messages
4.1.2 Systems Application Architecture Flagging Messages
4.1.3 Displaying and Printing Messages
4.2 How to Run an RPG/400 Program
4.2.1 Save-While-Active Support
4.3 Using a Test Library
4.4 Using Breakpoints
4.4.1 Example of Using Breakpoints
4.4.2 Considerations for Using Breakpoints
4.5 Using a Trace
4.5.1 Example of Using a Trace
4.5.2 Considerations for Using a Trace
4.6 Using the DEBUG Operation Codes
4.7 Using the RPG/400 Formatted Dump
4.8 Exception/Error Handling
5.0 Chapter 5. General File Considerations
5.1 Device Independence/Device Dependence
5.2 Spooling
5.2.1 Output Spool
5.3 Externally Described and Program-Described Files
5.4 Level Checking
5.5 File Locking by an RPG/400 Program
5.6 Record Locking by an RPG/400 Program
5.7 Unblocking Input Records and Blocking Output Records
5.8 Sharing an Open Data Path
5.9 Using the Control Language Command RCLRSC
5.10 Specifications for Externally Described Files
5.10.1 File Description Specifications
5.10.2 Renaming Record-Format Names
5.10.3 Ignoring Record Formats
5.10.4 Floating-Point Fields
5.10.5 Overriding or Adding RPG/400 Functions to an External Description
5.10.6 Output Specifications
5.11 Program-Described Files
5.12 Printer Files
5.12.1 Page Overflow
5.12.2 Overflow Indicators
5.12.3 Fetch-Overflow Logic
5.12.4 PRTCTL (Printer Control) Option
5.13 Sequential File
5.14 Special File
6.0 Chapter 6. Commitment Control
6.1 Using Commitment Control
6.1.1 Starting and Ending Commitment Control
6.1.2 Specifying Files for Commitment Control
6.1.3 Commitment Control Operations
6.1.4 Commitment Control Locks
6.1.5 Commitment Control in the Program Cycle
6.1.6 Example of Using Commitment Control
7.0 Chapter 7. Using DISK Files
7.1 Externally Described Disk Files
7.1.1 Record Format Specifications
7.1.2 Access Path
7.1.3 Valid Keys for a Record or File
7.1.3.1 Valid Search Arguments
7.1.3.2 Referring to a Partial Key
7.1.4 Processing Methods for Externally Described DISK Files
7.2 Program-Described Disk Files
7.2.1 Indexed File
7.2.1.1 Valid Search Arguments
7.2.2 Sequential Files
7.2.3 Record Address File
7.2.3.1 Limits Records
7.2.3.2 Relative Record Numbers
7.2.4 Externally Described File as Program Described
7.3 Methods for Processing Disk Files
7.3.1 Relative-Record-Number Processing
7.3.2 Consecutive Processing
7.3.3 Sequential-by-Key Processing
7.3.4 Sequential-within-Limits Processing
7.3.5 Keyed Processing Examples
7.4 Valid File Operations
8.0 Chapter 8. Using WORKSTN Files
8.1 Intersystem Communications Function
8.2 Externally Described WORKSTN Files
8.2.1 Processing an Externally Described WORKSTN File
8.2.2 Function Key Indicators on Display Device Files
8.2.3 Command Keys on Display Device Files
8.3 Processing WORKSTN Files
8.3.1 EXFMT Operation
8.3.2 READ Operation
8.3.3 WRITE Operation
8.3.4 WORKSTN file
8.3.5 Subfiles
8.3.5.1 Use of Subfiles
8.4 Program-Described WORKSTN File
8.4.1 Program-Described WORKSTN File with a Format Name
8.4.1.1 Output Specifications
8.4.1.2 Input Specifications
8.4.1.3 Calculation Specifications
8.4.1.4 Additional Considerations
8.4.2 Program-Described WORKSTN File without a Format Name
8.4.2.1 Input File
8.4.2.2 Output File
8.4.2.3 Combined File
8.5 Multiple-Device Files
8.6 WORKSTN File Examples
8.6.1 Sample Program 1-Inquiry
8.6.2 Sample Program 2-Data Entry with Master Update
8.6.3 Sample Program 3-Maintenance
8.6.4 Sample Program 4-WORKSTN Subfile Processing
8.6.5 Sample Program 5-Inquiry by Zip Code and Search on Name
FRONT_1
FRONT_1 Notices
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility.IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give | you any license to these patents. You can send license inquiries, in | writing, to the IBM Director of Licensing, IBM Corporation, 208 Harbor | Drive, Stamford, Conecticut, USA 06904-2501.
Changes or addition to the text are indicated by a vertical line (|) to the left of the change or addition.
This publication contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
Subtopics:
FRONT_1.1
FRONT_1.1 Programming Interface Information
This RPG/400 User's Guide is intended to help you create RPG/400 programs. This RPG/400 User's Guide documents general-use programming interfaces and associated guidance information provided by the RPG/400 compiler.
General-use programming interfaces allow the customer to write programs that request or receive services of the RPG/400 compiler.
FRONT_1.2 Trademarks and Service Marks
The following terms, denoted by an asterisk (*), used in this publication, are trademarks of the IBM Corporation in the United States or other countries:
____________________________________ ___________________________________ | Application System/400 | AS/400 | |____________________________________|___________________________________| | IBM | Operating System/2 | |____________________________________|___________________________________| | Operating System/400 | OS/2 | |____________________________________|___________________________________| | OS/400 | RPG/400 | |____________________________________|___________________________________| | SAA | Systems Application Architecture | |____________________________________|___________________________________| | SQL/400 | 400 | |____________________________________|___________________________________|
FRONT_2 About This Manual
This manual is a guide for the RPG/400* programming language on the AS/400 system using the Operating System/400* (OS/400*) system. The RPG/400 compiler is a Systems Application Architecture* (SAA*) compiler that adheres to SAA conventions.The topics covered in this manual include:
° Designing RPG/400 programs ° Coding RPG/400 programs ° Entering and compiling RPG/400 programs ° Testing and debugging RPG/400 programs ° Studying coded RPG/400 examples and sample programs.
This manual may refer to products that are announced but are not yet available.
You may need to refer to other IBM* manuals for more specific information about a particular topic. The Information Directory, provides information on all of the manuals in the AS/400* library. For a list of related publications, see the "Bibliography" in topic BACK_1.
Subtopics:
FRONT_2.1 Who Should Use This Manual
This manual is intended for people who have a basic understanding of data processing concepts and of the RPG/400 programming language. It is also designed to guide the programmer in the use of RPG/400 programs and compilers on the AS/400 system. RPG/400 specifications and operations are frequently mentioned. For a detailed description of RPG/400 specifications and operation codes, see the RPG/400 Reference, SC09-1817.
Before you use this manual, you should be familiar with certain information:
° You should know how to use data management support to work with files, display stations, printers, tapes, and diskettes, as well as spooling support. This information is contained in the Data Management Guide.
° You should be familiar with your display station (also known as a work station) and its controls. Some elements of its display and certain keys on the keyboard are standard regardless of the software system currently running at the display station or the hardware system the display station is connected to. Some of these keys are:
- Cursor movement keys - Command keys - Field exit keys - Insert and delete keys - The Error Reset key.
This information is contained in the System Operations: Display Station User's Guide.
° You should know how to operate your display station when it is connected to the IBM AS/400 system and running AS/400 software. This means knowing about the OS/400 system and the Control Language (CL) to perform the tasks of:
- Sign on and sign off of the AS/400 system - Interact with displays - Use Help - Enter control commands - Call utilities - Respond to messages.
To find out more about control language, refer to these IBM AS/400 publications:
- CL Programmer's Guide - Control Language Reference
° You should be familiar with the RPG/400 program cycle, how indicators affect the program cycle, and how to code entries on the RPG/400 specification sheets.
The sample application programs contained in this manual are scaled in such a way that you can use the RPG Debugging Template, GX21-9129 to check the coding in the programs.
These general items about the RPG/400 programming language are taught in an RPG/400 coding class. Detailed information on the RPG/400 programming language can be found in the RPG/400 Reference.
FRONT_2.2 How to Interpret Syntax Diagrams
The syntax diagrams in this book use the following conventions:
__________________________________________________________________________________________________ | | | | | | | >>__PARAMETER__(__ __________________ __user-defined-value__)_________________________________>< | | |_PREDEFINED-VALUE_| | | | | | |__________________________________________________________________________________________________| |
Read the syntax diagram from left to right, from top to bottom, following the path of the line.
Two right arrow heads followed by a solid line indicates the beginning of the syntax diagram.
A solid line ending in a right arrow head and a left arrow head indicates the end of the syntax diagram.
A solid line leading into a right arrow head indicates that the statement syntax is continued on the next line.
A right arrow head leading into a solid line indicates that a statement is continued from the previous line.
A parameter or value between left and right parentheses indicates that the parameter or value must be entered in parentheses.
Required parameters appear on the base line and must be entered. Optional parameters appear below the base line and do not have to be entered. In the following sample, you must enter REQUIRED-PARAMETER and a value for it, but you do not have to enter OPTIONAL-PARAMETER or a value for it.
__________________________________________________________________________________________________ | | | | | | | >>__REQUIRED-PARAMETER__(__ _PREDEFINED-VALUE___ __)___________________________________________> | | |_user-defined-value_| | | | | >__ __________________________________________________ _______________________________________>< | | |_OPTIONAL-PARAMETER__(__ _PREDEFINED-VALUE___ __)_| | | |_user-defined-value_| | | | | | |__________________________________________________________________________________________________| Default values appear above the base line and do not have to be entered. They are used when you do not specify a parameter. In the following sample, you can enter DEFAULT-VALUE, OTHER-PREDEFINED-VALUE, or nothing. If you enter nothing, DEFAULT-VALUE is assumed. |
1.0 Chapter 1. An Introduction to the RPG/400
Programming Language and the AS/400 SystemThe RPG/400 programming language is designed to make it easier for you to create business software applications.
RPG is a language under evolution. A slightly different version of RPG is available on each machine that supports it. The AS/400 system is the most recent of these computing systems. You should know that, as well as offering a new enhanced version of RPG, the AS/400 system also supports the previous versions of RPG available on System/38 and System/36. For more information, see Appendix B, "RPG/400 and AS/400 RPG II System/36-Compatible Functions," and Appendix E, "System/38 Environment Option of the RPG Compiler."
This chapter provides an overview of the following subjects:
° The OS/400 system and Control Language (CL) ° RPG/400 functions on the AS/400 system ° The System/38 Environment on the AS/400 system ° Available languages and utilities ° The RPG/400 programming cycle ° RPG/400 program design ° Structured programming in RPG/400 programs ° Application design.
1.1 The OS/400 System
The operating system that controls all of your interactions with the AS/400 system is called the Operating System/400 (OS/400) system. From your work station, the OS/400 system allows you to:
° Sign on and sign off ° Interact with the displays ° Use the online help information ° Enter control commands and procedures ° Respond to messages ° Manage files ° Run utilities and programs.
Refer to the Publications Guide for a complete list of publications that discuss the OS/400 system.
1.2 The AS/400 Control Language
You can manipulate the OS/400 system with the CL. You interact with the system by entering or selecting CL commands. The AS/400 system often displays a series of CL commands or command parameters appropriate to the situation on the screen. You then select the desired command or parameters.
1.2.1 Commonly Used Control Language Commands
The following table lists some of the most commonly used CL commands, their function, and the reasons you might want to use them.
________________________________________________________________________ | Table 1. RPG/400 Functions and Associated CL Commands | |_______________________ ________________________________________________| | RPG/400 Function | Associated Control Language Commands and their | | | Uses | |_______________________|________________________________________________| | Calling | CALL program-name Run an RPG/400 program | | | CALL QCL Access the System/38 | | | environment | |_______________________|________________________________________________| | Commitment Control | CRTJRN Prepare to use commitment | | | control. | | | CRTJRNRCV Prepare to use commitment | | | control. | | | ENDCMTCTL Notify the system you want | | | to end commitment control. | | | JRNPF Prepare to use commitment | | | control. | | | STRCMTCTL Notify the system you want | | | to begin commitment control. | |_______________________|________________________________________________| | Communications | CRTICFDEVE Create ICF Device | | | OVRICFDEVE Override ICF Device | |_______________________|________________________________________________| | Compiling | CRTRPGPGM Create RPG Program | | | CRTRPTPGM Create Auto Report Program | |_______________________|________________________________________________| | Consecutive | OVRDBF Override with Database file | | Processing | | |_______________________|________________________________________________| | Control Specification | CRTDTAARA Create Data Area | | Data Area | DSPDTAARA Display Data Area | |_______________________|________________________________________________| | Debugging | ADDBKP Add Breakpoint | | | ADDTRC Add Trace | | | DSPBKP Display Breakpoint | | | STRDBG Start Debug | |_______________________|________________________________________________| | Edit Codes | CRTEDTD Create Edit Description (For | | | User Defined Edit Code) | | | DSPDTAARA Display Data Area | |_______________________|________________________________________________| | Printer Files | CRTPRTF Create Print File | | | OVRPRTF Override Print File | |_______________________|________________________________________________| | System Editor | STRSEU Start Source Entry Utility | |_______________________|________________________________________________|The Control Language and all of its commands are described in detail in the CL Reference manual.
1.3 System/38 Environment on the AS/400 System
The AS/400 system offers increased function over System/38. Because many RPG/400 language programs are written for the System/38, and because many programmers are already familiar with System/38, the AS/400 system also supports these programs under the System/38 Environment. The CL command CALL QCL changes the AS/400 system display to appear to the user as a System/38 display. This is known as the System/38 Environment. When you are in this environment, you can enter and compile RPG/400 programs as if you were using a System/38. The file naming conventions are the same as in System/38. You can also enter AS/400 CL commands in the System/38 Environment. You can enter System/38 Environment commands from the AS/400 system by library qualifying commands. The QSYS38/CRTRPGPGM command calls the System/38 Environment RPG III compiler. For more information on the System/38 Environment, see the System/38 Environment Programmer's Guide/Reference.
You can use the Source Entry Utility (SEU) to enter your RPG/400 source program interactively. Enter the CL command STRSEU to call SEU. If you specify the TYPE(RPG) parameter on this command, the RPG/400 syntax checker is called and detects RPG/400 syntax errors, statement by statement, while the source program is entered. Alternatively, you can enter a source program on diskettes and upload the program into a source file.
___ Note _______________________________________________________________ | | | To find out how to use RPG III in the System/38 Environment, refer to | | the following: | | | | ° Appendix E, "System/38 Environment Option of the RPG Compiler" in | | topic E.0 | | | | ° the System/38 RPG III Reference Manual and Programmer's Guide | | SC21-7725. | | | | For information on System/38 devices and commands, refer to the | | appropriate manuals in the System/38 library. | | | |________________________________________________________________________|
1.4 AS/400 Utilities and Languages
The AS/400 system offers two utilities and a language that you may find useful for programming. They are the Screen Design Aid (SDA) utility, the Source Entry Utility (SEU), and the Structured Query Language (SQL).
Subtopics:
1.4.1 The Source Entry Utility
You use the SEU to enter your code into the system. SEU also provides extensive syntax checking. For more information about SEU, refer to the SEU User's Guide and Reference.
1.4.2 The Screen Design Aid
The SDA utility makes it easier for you to create the displays your program requires. For more information about SDA, refer to the SDA User's Guide and Reference.
1.4.3 The Structured Query Language
The AS/400 system allows you to insert SQL/400 statements into RPG/400 programs. You enter SQL/400 statements on a calculation specification. The syntax is shown in Figure 2. You must observe the following rules:
° The starting delimiter /EXEC SQL must be entered into columns 7-15, with the slash in column 7.
° SQL/400 statements can be started on the same line as the starting delimiter.
° SQL/400 statements can be continued on any number of subsequent continuation lines. The continuation line delimiter is the + in column 7.
° SQL/400 statements cannot go past column 74.
° The ending delimiter /END-EXEC must be entered in columns 7-15, with the slash in column 7, on a separate line. This signals the end of the SQL/400 statements. It must be entered by itself, with no SQL/400 statements following it.
C C | C | C/EXEC SQL (the starting delimiter) C+ C+ (continuation lines containing SQL statements) C+ . . . C/END-EXEC (the ending delimiter) C | C | C |
Figure 2. Syntax for Entering SQL/400 Statements into an RPG/400 Program
You must enter a separate command to process the SQL/400 statements.
Refer to the SQL/400* Programmer's Guide and the SQL/400* Reference for the descriptions of how to code SQL/400 statements.
Subtopics:
1.4.3.1 Restrictions
In the RPG/400 programming language, SQL/400 statements cannot be specified in the referred source member of a /COPY statement.
You should not use SQL/400 statements in an RPG automatic report program. Instead, you should use the CRTRPTPGM command to process your RPG automatic report programs and to save the generated RPG/400 source. Automatic report will generate RPG/400 source, to which you can add SQL/400 statements. To process your SQL/400 statements and generate an RPG object program, you should use the SQL/400 preprocessor. If SQL/400 statements are processed by the RPG/400 automatic report preprocessor, unpredictable results may occur.
Refer to the SEU User's Guide and Reference for information on how the SEU handles SQL/400 statement syntax checking, and to the SQL/400* Programmer's Guide and the SQL/400* Reference for more information on the SQL/400 preprocessor.
1.5 Designing Your RPG/400 Program
Designing a program includes:
° Deciding what output you need from your program ° Deciding what processing will produce the output you need ° Deciding what input is required by and available to your program.
This sequence may seem backwards because it starts at the results (the output) and ends at the beginning (the input). Designing the output first is like knowing where you are going before you set out on a trip: it helps you decide the best way to get there.
Subtopics:
1.5.1 Designing the Output
Your program produces output records. You must decide what to do with those records. In general, you have three choices (or any combination of the three choices):
° You can display them. ° You can print them. ° You can store them.
If you want to display the output records at your display station, you have to decide what information you want displayed and how you want it laid out. To define how you want your displays laid out, you use the display layout sheet. You can then use the SDA utility to create your own displays. For more information about SDA, refer to the SDA User's Guide and Reference.
If you want to print the output records, you have to decide what information you want printed (which fields from which records) and how you want that information laid out on the printed report. To indicate how you want the printed report laid out, use the printer layout sheet.
If you want to keep the output records in storage, you have to decide what information you want to keep and how you want to organize the fields in the output records.
After you design all your output records, you code those records on the RPG/400 file description specifications and output specifications.
1.5.2 Designing the Processing
Designing the processing means planning the calculations that produce the necessary output. When you design the processing, you must be aware of how the RPG/400 program cycle works. The RPG/400 program cycle controls certain read and write operations done on each record. As a result, the program cycle partly determines how you can process your data.
1.5.3 Designing the Input
After you decide what output you need and the calculations that produce the output, the next step is to determine where the input data for your program will come from. It might come from one or more files already on the system, from one or more display stations on your system, from one or more other systems, or from a combination of these sources. You have to know the names used for input files, the location of fields in the input records, the sequence of record types, the formats of numeric data, and the indicators used. When you know all these kinds of information, you can describe your input records on the RPG/400 input specifications.
1.6 Structured Programming in the RPG/400 Programming Language
Structured programming is an approach to design and coding that makes programs easy to understand, debug, and modify.
Three structures used in every computer program are:
° Sequential operation ° Conditional branching ° Repeating an operation based on a certain condition.
Ideally, a structured program is a hierarchy of modules that can have a single entry point and a single exit point. Control is passed downward through the structure without unconditional branches to higher levels of the structure.
The following discuss how the three structures can be accomplished in the RPG/400 programming language.
Subtopics:
- 1.6.1 Sequential Operation
- 1.6.2 Conditional Branching
- 1.6.3 Repeating an Operation
- 1.6.4 Summary of Structured Programming Operation Codes
1.6.1 Sequential Operation
Sequential operation means any series of instructions that is processed one instruction after another, without transferring control to another part of the program.
1.6.2 Conditional Branching
Subtopics:
1.6.2.1 If Else Structure
An example of an If-Then-Else conditional branching structure in simple English is: IF the weather is cold, THEN I will wear my coat; ELSE, I will leave my coat at home. In the RPG/400 programming language, the If-Then-Else structure is carried out through the operation codes IFxx, ELSE, and END. Figure 4 shows a design for a conditional branch using the IFxx, ELSE, and END operation codes. *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* In this example, if CENTR equals Y or if CENTR equals N, then C* indicator 52 is set off by moving '0' to *IN52. If CENTR equals C* neither Y nor N, then indicator 52 is set on by moving '1' to C* *IN52. The END statement ends the IF/THEN/ELSE group. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C CENTR IFEQ 'Y' C CENTR OREQ 'N' C MOVE '0' *IN52 C ELSE C MOVE '1' *IN52 C END Figure 4. Design for a Conditional Branch Using the IF/ELSE/END Operations
1.6.2.2 SELEC Structure
An example of a SELEC-WHEN-OTHER conditional branching structure in simple
english is:
SELEC
WHEN the weather is warm
I will wear my sunhat
I will go to the beach
WHEN the weather is cool
I will not go outside
OTHERwise, I will go to the mall
In the RPG/400 programming language, the SELEC-WHEN-OTHER structure is
carried out through the operation codes of SELEC, WHxx, and OTHER.
Figure 6 shows conditional branching using the SELEC, WHxx, and OTHER
operation codes.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..*
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++*
C*
C* If X equals 1 then do the operations in sequence 1; if
C* X does not equal 1, then if Y=2 and X<10 do the operations
C* in sequence 2. If neither condition is true, then do the
C* operations in sequence 3.
C*
C SELEC
C X WHEQ 1
C : seq 1
C Y WHEQ 2
C X ANDLT10
C : seq 2
C OTHER
C : seq 3
C ENDSL
C*
Figure 6. Conditional Branching Using the SELEC/WHxx/OTHER Operations
1.6.2.3 Other Conditional Branching Structures
There are three other ways you can create conditional branches:
° The CASxx operation ° The GOTO operation and conditioning indicators ° The CABxx operation.
You can also create a branch to a subroutine with the EXSR operation and conditioning indicators.
1.6.3 Repeating an Operation
The RPG/400 programming language implements three repeat structures-Do, Do While, and Do Until-by means of the DOWxx, DOUxx, and DO operation codes and the END operation code.
Subtopics:
1.6.3.1 Do Operation
This is how the Do operation works:
1. Set the index field (result field) to the starting value (factor 1).
2. Test if the index field value is greater than the ending value (factor
2).
If the index field value is greater than the ending value, control
passes to the statement following the END statement.
3. If the index field value is not greater than the ending value, the
operations between the DO statement and the END statement are
processed.
4. At END, the index field value is increased by the increment value
specified in factor 2 on the END statement, or by 1 if the increment
is not specified.
5. Control passes to step 2 above.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..*
C*
C* The following example illustrates a Do operation. Because factor
C* 1 of the DO statement is blank, the starting value of Y is 1, and
C* because factor 2 of the END statement is blank, the increment
C* value of Y is 1. Factor 2 of the DO statement contains the value
C* 10, which is the ending value for the DO routine.
C*
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++*
C Z-ADD1 X 20
C DO 10 Y 30
C X LOKUPTABA TABR 50
C 50 TABR MULT 1.04 RATE 72
C MOVE '1' *IN90
C EXCPT
C MOVE '0' *IN90
C ADD 1 X
C END
Figure 8. Design for a Do Operation Using the DO and END Operation Codes
1.6.3.2 Do While Operation
If you test the condition first and then process the operations, the
structure is called a Do While. An example of a Do While operation is:
1. Compare a sum with 5.
2. If the sum is less than 5, add 1 to the sum.
3. Repeat steps 1 and 2 until the sum is equal to or greater than 5.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..*
C*
C* The following code determines if the subfile has been filled.
C* If indicator 32 is off (*IN32 equal 0), the DOWEQ operation
C* processes until the remainder of the subfile is filled with
C* blank records.
C*
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++*
C *IN32 DOWEQ'0'
C MOVE *BLANKS STATUS
C MOVE *BLANKS PRCDEX
C MOVE *BLANKS RSCDEX
C Z-ADD0 EHWRKX
C Z-ADD0 ACDATX
C Z-ADD0 TFRRN
C ADD 1 RECNO
C WRITEEMPFIL 32
C END
C* The preceding END denotes the end of the Do While operation.
Figure 10. Design for a Do While Operation Using the DOWxx Operation Code
Notice in Figure 10 (the Do While above) that the program first tests if the
condition is true. If it is true, the code between the DOW and the END
operations is processed. The program then goes back to test again if the
condition is still true, and the entire cycle is repeated. If the
condition is no longer true, control passes to the instruction immediately
following the END operation.
1.6.3.3 Do Until Operation
If you process the operations first and then test the condition, the structure is called a Do Until operation. An example of a Do Until operation is: 1. Add 1 to a sum. 2. Compare the sum with 5. 3. If the sum is less than 5, repeat steps 1 and 2 . a Do Until Operation *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C* C* The following lines of code perform a Do Until condition. The C* program loops between the DOUEQ statement and the END statement C* until end of file (*IN50 equal 1) is reached. C EMPSR BEGSR C* C *IN50 DOUEQ'1' C READ RCEMP 50 C* The following lines of code add current month hours to the year- C* to-date hours for the employee master file. Since factor 1 is C* not specified in the statements, factor 2 is added to the result C* field and the result is placed in the result field. If *INU4 C* is on, this session is being run for year end, and the current C* year hours are moved to the prior year hours. C ADD EPHRC EPHRY C ADD EPNRC EPNRY C U4 MOVE EPHRY EPHRP C U4 MOVE EPNRY EPNRP C* The following code clears the current month hours fields by C* zeroing them and adding 0 to them. If *INU4 is on, this session C* is being run for year end, and the current year hours must be C* zeroed as well. C Z-ADD0 EPHRC C Z-ADD0 EPNRC C U4 Z-ADD0 EPHRY C U4 Z-ADD0 EPNRY C* The following code updates the employee master file using the C* RCEMP format. C UPDATRCEMP C END C* The preceding END statement is associated with the DOUEQ C* statement.
Figure 12. Design for a Do Until Operation Using the DOUxx Operation Code
1.6.4 Summary of Structured Programming Operation Codes
The structured programming operation codes are:
° IFxx (If/Then) ° ELSE (Else Do) ° ENDyy (End) ° DO (Do) ° DOWxx (Do While) ° DOUxx (Do Until) ° ANDxx (And) ° ORxx (Or) ° CASxx (Conditional Invoke Subroutine) ° SELEC (Select a module) ° WHxx (When) ° OTHER (Otherwise).
where xx can be:
GT Factor 1 is greater than factor 2. LT Factor 1 is less than factor 2. EQ Factor 1 is equal to factor 2. NE Factor 1 is not equal to factor 2. GE Factor 1 is greater than or equal to factor 2. LE Factor 1 is less than or equal to factor 2. Blanks Factor 1 is not compared to factor 2 (unconditional processing). This is valid for CASxx operation only.
and where yy can be:
CS End a CAS group. DO End a DO, DO UNTIL, or DO WHILE group. IF End an IF group. SL End a SELEC group.
1.7 Designing Applications
Application design involves determining whether to create one program to do all of the required functions, or to create multiple programs to make up an application.
Subtopics:
1.7.1 Single Program Design
In a single program design, all functions are done within one program. Single program design applies to both batch and interactive programs. It is best used when there are few, relatively simple functions. For example, an interactive inquiry program that accepts a customer number from an operator, finds the corresponding record in a customer master file, and displays the record as a simple program that could have a single program design. A slightly more complex program that might also have a single program design is a file maintenance program that allows an operator to: ° Inquire into a record ° Change a record ° Delete a record ° Add a record. An example of a batch program that could have a single program design is a program that prints a list of orders that each operator entered during the day.
1.7.2 Modular Program Design
Modular program design includes using multiple programs to do multiple functions, one function per program. Modular program design can be applied to both batch and interactive programs. For example, the order entry application shown in Figure 13 is designed to have four programs:
° An RPG/400 or CL mainline program
° An RPG/400 program that prompts for the customer number and shows customer information on the display
° An RPG/400 program that accepts input of line items from the order
° An RPG/400 program that calculates totals for the order.
Mainline Program ________________ Program | | Call ________________ ____ÿ| |________ÿ| _____________ |_____ Prompt for | | | | _____________ | Customer | | | | _____________ | Number | | |________| _____________ | | | | |________________| | | | | | | Program | | | Call ________________ | | |________ÿ| _____________ |_____ Line Item | | | | _____________ | Input | | | | _____________ | | | |________| _____________ | | | | |________________| | | | | | | Program | | | Call ________________ | | |________ÿ| _____________ |_____ Totals | | | | _____________ | | | | | _____________ | |_____| |________| _____________ | |________________| |________________|
Figure 13. Modular Design for an Order Entry Application
A modular program design has several potential advantages:
° Designing, coding, testing, and maintaining several small programs can be easier than designing, coding, testing, and maintaining one large, complex program. This choice is a matter of personal preference, but it is often beneficial to keep your programs small and as simple as possible.
° CL functions can be requested from RPG/400 programs because the AS/400 system allows RPG/400 programs and CL programs to call one another.
A single, long-running program might have sections of code that run infrequently. A modular design could arrange to have the seldom-used code called only when needed.
A potential disadvantage of modular program design is the additional calling of programs that is required. These calls take time to code and might require additional system overhead for program processing.
1.7.3 Examples of Application Design
2.0Following are descriptions of modular programs that illustrate some design approaches.
The order entry function shown in Figure 14 has three sub-functions:
° Accepting heading information about an order ° Accepting line item input from the order ° Calculating totals for the order.
One way to design this application is to have a CL mainline program call RPG/400 programs to do the functions.
Control Language Mainline Program ____________________ HEADER Program | | Call ________________ ____ÿ| |________ÿ| Open files | | | | | Put prompt | | | | | Get header | | | | | Process header | | | | | Close Files | | | |________| Return | | | | |________________| | | | | | | ITEM Program | | | Call ________________ | | |________ÿ| Open files | | | | | Put prompt | | | | | Get item | | | | | Process item | | | | | Close Files | | | |________| Return | | | | |________________| | | | | | | TOTALS Program | | | Call ________________ | | |________ÿ| Open files | | | | | Put prompt | | | | | Get total | | | | | information | | | | | Calculate | | | | | Close files | |_____| |________| Return | |____________________| |________________|
Figure 14. Example of Application Design for an Order Entry Function
Each of the RPG/400 programs:
° Opens files ° Displays a prompt for user information and input ° Accepts input from the user ° Processes the information ° Closes the files ° Returns to the mainline program.
The following events occur after a user enters input:
1. The input is processed. 2. Files are closed. 3. Control returns to the mainline program. 4. The mainline program calls the next program. 5. That program prompts for user input.
All processing of input and output from work stations and all opening and closing of files occurs in the RPG/400 programs. Therefore, the user might have to wait for a while after entering a display before seeing the next display.
A change in the previous design that might shorten response times and make more efficient use of system resources is shown in Figure 15.
Control Language Mainline Program ____________________ HPROMPT Program | | ________________________ ____ÿ| Call HPROMPT |________ÿ| Open files | | | | | Put prompt for header | | | | | Close files | | | |________| Return | | | | |________________________| | | | 1 | | | HEADER Program | | | ________________________ | | Call HEADER |________ÿ| Open files | | | | | Get header input | | | | | Process header | | | | | Put prompt for | | | | | line item | | | | | Close Files | | | |________| Return | | | | |________________________| | | | 2 | | | ITEM Program (see Note) | | | ________________________ | | Call ITEM |________ÿ| Open files | | | | | Get line item input | | | | | Process line item | | | | | Put prompt for next | | | | | line item or put | | | | | totals prompt | | | | | Close Files | | | |________| Return | | | | |________________________| | | | 3 | | | TOTALS Program | | | ________________________ |_____| Call TOTALS |________ÿ| Open files | | | | Get totals input | | | | Calculate totals | | | | Close Files | | |________| Return | |____________________| |________________________|
Figure 15. Example of Changed Application Design for an Order Entry Function
Note: Rather than returning unconditionally to the mainline program, the ITEM program could be designed to loop within itself as long as line items are being entered.
This modification allows user data entry to occur while programs are started and files are opened and closed. The overlap of data entry and AS/400 system processing occurs at points 1 , 2 , and 3 .
For the previous two examples of modular program design, all input from and output to work stations occurs in the programs. For the example in Figure 16, a series of operations occur in an RPG/400 mainline program.
RPG RPG Programs Mainline Program ________________________ ____ÿ| Put header prompt | HEADER Program | __ÿ| Get input from display | ____________________ | | | Call HEADER |_______ÿ| Open files | | |__| Put item prompt | " | (first time only) | | | | | | | Process header | | | | | |____| Return | | | | | |____________________| | | | | | | | | ITEM Program | | | | ____________________ | |___| Call ITEM |_______ÿ| Open files | | | | " | (first time only) | | | | | | Process line item | | | | |____| Return | | | | |____________________| | | | | | | TOTALS Program | | | ____________________ |_____| Call TOTALS |_______ÿ| Open files | | | " | (first time only) | | | | | Process Totals | | | |____| Return | |________________________| |____________________|
Figure 16. Example of Application Design with Input and Output in Mainline Program
The input from the display determines the program to call. If a header is read, HEADER is called and the header record is passed as a parameter. If a line item is read, ITEM is called and a line item record is passed as a parameter. If total information is read, TOTALS is called and a total record is passed as a parameter.
The programs leave files open until the job ends, thereby eliminating open and close processing time for the files. The programs do not end when they return to the mainline program.
2.0 Chapter 2. Entering RPG/400 Specifications
After designing your program, you must write the individual statements that you will combine into a source program. These statements are coded on RPG/400 specification sheets. Each line coded on a specification sheet represents a statement in the source program. Each specification sheet contains 80 columns. Column headings indicate the kind of information to code in particular columns.
This chapter describes the kinds of specifications you can enter when creating an RPG/400 source program. This chapter also describes how to use a text editor, such as SEU, to enter this information directly into the system and thus begin creating your source program online.
Subtopics:
2.1 The RPG/400 Specifications
There are seven kinds of RPG/400 specifications. When your source program is compiled, these specifications must be in the following sequence:
1. Control specifications 2. File description specifications 3. Extension specifications 4. Line counter specifications 5. Input specifications 6. Calculation specifications 7. Output specifications.
Each of these specifications is described briefly in this chapter. The RPG/400 Reference provides detailed descriptions for these specifications.
RPG/400 programs do not have to use all specifications. A typical program may use file description, input, calculation, and output specifications.
Subtopics:
- 2.1.1 The Control Specification
- 2.1.2 File Description Specifications
- 2.1.3 Extension Specifications
- 2.1.4 Line Counter Specifications
- 2.1.5 Input Specifications
- 2.1.6 Calculation Specifications
- 2.1.7 Output Specifications
2.1.1 The Control Specification
The control specification provides the RPG/400 compiler with information about your program and your system. This includes:
° Name of the program ° Date format for the program ° If an alternative collating sequence or file translation is used.
Note: The control specification is optional.
2.1.2 File Description Specifications
File description specifications describe all the files that your program uses. The information for each file includes:
° Name of the file ° How the file is used ° Size of records in the file ° Input or output device used for the file ° If the file is conditioned by an external indicator.
2.1.3 Extension Specifications
Extension specifications describe all record address files, table files, and array files used in the program. The information includes:
° Name of the file, table, or array ° Number of entries in a table or array input record ° Number of entries in a table or array ° Length of the table or array entry.
2.1.4 Line Counter Specifications
Line counter specifications describe the page or form on which output is printed. The information includes:
° Number of lines per page ° Line of the page where overflow occurs.
2.1.5 Input Specifications
Input specifications describe the records, fields, data structures and named constants used by the program. The information in the input specifications includes:
° Name of the file ° Sequence of record types ° Whether record-identifying indicators, control-level indicators, field-record-relation indicators, or field indicators are used ° Whether data structures, lookahead fields, record identification codes, or match fields are used ° Type of each field (alphanumeric or numeric; packed-decimal, zoned-decimal, or binary format) ° Location of each field in the record ° Name of each field in the record ° Named constants.
2.1.6 Calculation Specifications
Calculation specifications describe the calculations to be done on the data and the order of the calculations. Calculation specifications can also be used to control certain input and output operations. The information includes:
° Control-level and conditioning indicators for the operation specified ° Fields or constants to be used in the operation ° The operation to be processed ° Whether resulting indicators are set after the operation is processed.
2.1.7 Output Specifications
Output specifications describe the records and fields in the output files and the conditions under which output operations are processed. The information includes:
° Name of the file ° Type of record to be written ° Spacing and skipping instructions for PRINTER files ° Output indicators that condition when the record is to be written ° Name of each field in the output record ° Location of each field in the output record ° Edit codes and edit words ° Constants to be written ° Format name for a WORKSTN file.
2.2 Entering Your Program
3.0After you have written your RPG/400 program on the specifications forms, you must enter it into source files in the system. You can enter the source program in two ways: ° Interactively by using SEU: The SEU User's Guide and Reference provides a complete description of how to enter or update an RPG/400 source program using SEU. ° In a batch manner (that is, from diskette) by using either the OS/400 system copy or spooling functions: The Data Management Guide provides more information on how to use the copy or spooling function for batch entry of the source program.
Note: Whichever method of source entry you use, you can use lowercase letters only in literals, constants, comments, array data, and table data. All other information must be in uppercase letters.
3.0 Chapter 3. Compiling an RPG/400 Program
There are two environments that you can compile source programs from: the AS/400 system environment, and the System/38 Environment. Consequently, there are two ways of compiling source programs. This chapter describes:
° Using the CL command CRTRPGPGM to compile an RPG/400 source program in AS/400 system environment
° Using the CL commands CALL QCL and CRTRPGPGM to compile an RPG/400 source program in the System/38 Environment.
This chapter also contains information on interpreting a compiler listing.
To compile a program, you must ensure that the library QTEMP is in the library list. The CL command CRTRPGPGM calls the compiler to create an RPG/400 program object and a listing. (If externally described files are used in the program, the OS/400 system provides information about the files to the program during compilation.) The following figure shows an overview of the compilation process:
Figure 17. Overview of the Compilation Process
The compiler checks the syntax of the RPG/400 source program line by line and the interrelationships between the lines. For example, it checks that all field names are defined and, if a field is multiply defined, that each definition has the same attributes.
The RPG/400 compiler supports a source file record length of 102. In addition to the usual fields of sequence number (6 characters), last-changed date (6 characters), and the data (80 characters), a field of 10 characters that can contain additional information is placed at the end of the record (positions 93-102). This information is not used by the RPG/400 compiler but is placed on the extreme right of the compiler listing. You, the programmer, place information into this field. If you want to use the additional field, create a source file with a record length of 102. The AS/400 system has an IBM-supplied RPG/400 source file called QRPGSRC, which has a record length of 92.
Subtopics:
- 3.1 Create RPG400 Program (CRTRPGPGM) Command
- 3.2 CRTRPGPGM Command
- 3.3 Compiling under the System/38 Environment
3.1 Create RPG400 Program (CRTRPGPGM) Command
To compile an RPG/400 source program into a program object, you must enter the CL command CRTRPGPGM (Create RPG/400 Program) to call the RPG/400 compiler. RPG/400 program objects are created with the public authority of *LIBCRTAUT. You may want to change this authority to maintain greater security on your system.
If the RPG/400 compiler stops because of errors, the escape message QRG9001 is issued. A CL program can monitor for this exception by using the CL command MONMSG (Monitor Message). See Chapter 4, "Error Messages, Testing, and Debugging."
The compiler creates and updates a data area with the status of the last compilation. This data area is named RETURNCODE, is 400 characters long, and is placed into library QTEMP. You can access the RETURNCODE data area by specifying RETURNCODE in factor 2 of an *NAMVAR DEFN statement. The data area RETURNCODE has the following format:
_________________________________________________________ | Table 2. Contents of the Data Area RETURNCODE | |_________ _______________________________________________| | Byte | Content and Meaning | |_________|_______________________________________________| | 1 | Character 1 means a program was created. | |_________|_______________________________________________| | 2 | Character 1 means the compilation failed | | | because of compiler errors. | |_________|_______________________________________________| | 3 | Character 1 means the compilation failed | | | because of source errors. | |_________|_______________________________________________| | 4 | Character 1 means compiled from source | | | generated by automatic report. | |_________|_______________________________________________| | 5 | Character 1 means program resolution monitor | | | was not called because *NOGEN option was | | | selected on CRTRPGPGM command. | |_________|_______________________________________________| | 6-10 | Number of source statements. | |_________|_______________________________________________| | 11-12 | Severity level from command. | |_________|_______________________________________________| | 13-14 | Highest severity on message diagnostic. | |_________|_______________________________________________| | 15-20 | Number of errors found in program. | |_________|_______________________________________________| | 21-26 | Compile date. | |_________|_______________________________________________| | 27-32 | Compile time. | |_________|_______________________________________________| | 33-100 | Not set. | |_________|_______________________________________________| | 101-110 | Program name. | |_________|_______________________________________________| | 111-120 | Program library name. | |_________|_______________________________________________| | 121-130 | Source file name. | |_________|_______________________________________________| | 131-140 | Source file library name. | |_________|_______________________________________________| | 141-150 | Source file member name. | |_________|_______________________________________________| | 151-160 | Compiler listing file name. | |_________|_______________________________________________| | 161-170 | Compiler listing library name. | |_________|_______________________________________________| | 171-180 | Compiler listing member name. | |_________|_______________________________________________| | 181-190 | Automatic report source file name. | |_________|_______________________________________________| | 191-200 | Automatic report library name. | |_________|_______________________________________________| | 201-210 | Automatic report member name. | |_________|_______________________________________________| | 211-370 | Not set. | |_________|_______________________________________________| | 371-378 | Size of intermediate representation of | | | program passed to program resolution monitor. | |_________|_______________________________________________| | 379 | Not set. | |_________|_______________________________________________| | 380-384 | Total compile time. | |_________|_______________________________________________| | 385 | Not set. | |_________|_______________________________________________| | 386-390 | Time used by compiler. | |_________|_______________________________________________| | 391-395 | Time used by program resolution monitor. | |_________|_______________________________________________| | 396-400 | Time used by translator. | |_________|_______________________________________________|
All object names specified on the CRTRPGPGM command must be composed of alphanumeric characters, the first of which must be alphabetic. The full OS/400 system naming convention is allowed. The length of the names cannot exceed 10 characters. See the CL Programmer's Guide for a detailed description of OS/400 object naming rules and for a complete description of OS/400 command syntax.
It is unlikely that the system internal size limits for a program will be exceeded. However, if these limits are exceeded, the program must be rewritten, usually as multiple programs.
Subtopics:
3.1.1 Using the CRTRPGPGM Command
You can call the RPG/400 compiler in one of three ways:
° Interactively from the CRTRPGPGM command display screen using prompts. You start the display, illustrated in Figure 19 in topic 3.2 and Figure 20 in topic 3.2, by typing the CL command CRTRPGPGM and then pressing F4.
° Entering CRTRPGPGM followed by only those parameters by keyword that override the default settings. This statement is entered on the command line interactively or as part of a batch input stream.
° Entering CRTRPGPGM followed only by the parameter values, in the proper sequence. This method is most often used when you are submitting the compiling request as part of a batch input stream, or if you are including the compiling request as part of a CL program. This method can also be used interactively, but you are limited by CL to entering only the first three parameter values.
Note: Any default on the CRTRPGPGM command or any other CL command can be changed using the CL command CHGCMDDFT (Change Command Default). Refer to the CL Reference for more information.
Subtopics:
- 3.1.1.1 Elements of the CRTRPGPGM Command Lines
- 3.1.1.2 Entering Elements from the CRTRPGPGM Command Display
- 3.1.1.3 Entering Only Certain Parameters
- 3.1.1.4 Entering Only the Parameter Values
3.1.1.1 Elements of the CRTRPGPGM Command Lines
The descriptions that follow refer to the three elements of the compiler command line:
° The CL compiler command word CRTRPGPGM.
° The parameter, which is referred to by a keyword such as PGM, SRCFILE, GENOPT, and so on.
° The value for the parameter. This can be a predefined value or an object name.
All object names specified must consist of alphanumeric characters. The first character must be alphabetic, and the length of the name cannot exceed 10 characters. You can use the full OS/400 system naming convention.
3.1.1.2 Entering Elements from the CRTRPGPGM Command Display
Type CRTRPGPGM, and press F4. The CRTRPGPGM prompt screens appear. Press F10 to get additional parameters. These screens, and the values you can enter on them, are described later in this chapter.
Each parameter on the screen displays a default value. Move the cursor past items where you want the default value to apply. Type over any items where you want to set a different value or option. If you are not sure about what to set a particular parameter to, type a question mark (?) as the first character in that field and press Enter to receive more detailed information. The question mark must be followed by a blank.
When you have set all values to your satisfaction, press Enter.
3.1.1.3 Entering Only Certain Parameters
All of the CRTRPGPGM parameters have default values. Simply type CRTRPGPGM, followed only by those parameters (specified by keyword) whose default settings you want to override. Separate parameters by spaces; enter values for each parameter by enclosing the value or values in parentheses.
For example, to change the program and library name, and accept default values for all other parameters, enter:
CRTRPGPGM PGM(newlibrary/newname)
3.1.1.4 Entering Only the Parameter Values
You have the choice of entering only the parameter values without specifying the parameter keywords. Because there is no keyword to tell the system which value belongs to which parameter, you must enter all the values in the sequence shown below. You need not enter the entire set of options, but you must enter the options for all the parameters up to the one you want. The system uses the default values for the remaining parameters.
For example, to compile a source program in member ABC in file QRPGSRC in library SRCLIB, enter:
CRTRPGPGM QTEMP/ABC SRCLIB/QRPGSRC *PGM
Notice that you also had to enter names for the program and library for the compiled program. The system recognizes which option belongs to which parameter by the position of the value on the compiler command line. You can enter a maximum of three parameter values positionally.
For more information on AS/400 system commands, see the CL Reference.
3.2 CRTRPGPGM Command
The entire syntax diagram for the CRTRPGPGM command is shown in Figure 18 in topic 3.2.
Read the syntax diagram from left to right, from top to bottom, following the path of the line.
Control Language (CL) commands, parameters, and keywords can be entered in either uppercase or lowercase characters. In this manual they are shown in uppercase (for example, PARAMETER, PREDEFINED-VALUE). Variables appear in lowercase italic letters (for example, user-defined-value). Variables are user-defined names or values.
For information on how to read syntax diagrams, see "How to Interpret Syntax Diagrams" in topic FRONT_2.2.
______________________________________________________________________________________________________________________ | | | | | Job: B,I Pgm: B,I REXX: B,I Exec | | | | | | | | >>__CRTRPGPGM__ ________________________________________________ __________________________________________________> | | | _*CURLIB/______ _*CTLSPEC_____ | | | |_PGM__(__|_______________|__|______________|__)_| | | |_library-name/_| |_program-name_| | | | | >__ ________________________________________________________ ______________________________________________________> | | | _*LIBL/________ _QRPGSRC__________ | | | |_SRCFILE__(__|_______________|__|__________________|__)_| | | |_*CURLIB/______| |_source-file-name_| | | |_library-name/_| | | | | (P) | | >__ ___________________________________________ ______ __________________________________ _________________________> | | | _*PGM____________________ | |_OPTION__(__| OPTION Details |__)_| | | |_SRCMBR__(__|_source-file-member-name_|__)_| | | | | >__ __________________________________ __ ___________________________________ _____________________________________> | | |_GENOPT__(__| GENOPT Details |__)_| | _*NONE___________ | | | |_INDENT__(__|_character-value_|__)_| | | | | >__ ______________________________________ __ ____________________________ ________________________________________> | | | _*NONE______________ | | _*NOFLAG_ | | | |_CVTOPT__(__|_| CVTOPT Details |_|__)_| |_SAAFLAG__(__|_*FLAG___|__)_| | | | | >__ ________________________________________ __ _________________________________________________ _________________> | | | _9____________________ | | _*LIBL/________ _QSYSPRT___ | | | |_GENLVL__(__|_severity-level-value_|__)_| |_PRTFILE__(__|_______________|__|___________|__)_| | | |_*CURLIB/______| |_file-name_| | | |_library-name/_| | | | | >__ _________________________ __ _________________________________ __ __________________________ __________________> | | | _*YES_ | | _*CURRENT______ | | _*USER__ | | | |_REPLACE__(__|_*NO__|__)_| |_TGTRLS__(__|_*PRV__________|__)_| |_USRPRF__(__|_*OWNER_|__)_| | | |_release-level_| | | | | >__ ________________________________________ __ _______________________________ __ ________________________ _______> | | | _*LIBCRTAUT______________ | | _*SRCMBRTXT____ | | _*NO__ | | | |_AUT__(__|_*CHANGE_________________|__)_| |_TEXT__(__|_*BLANK________|__)_| |_PHSTRC__(__|_*YES_|__)_| | | |_*USE____________________| |_'description'_| | | |_*ALL____________________| | | |_*EXCLUDE________________| | | |_authorization-list-name_| | | | | >__ ______________________________________ __ _______________________________________ _____________________________> | | | _*NONE______________ | | _*NONE______________ | | | | | <____________ (1) | | | | <____________ (1) | | | | |_ITDUMP__(__|___phase-name_|_____|__)_| |_SNPDUMP__(__|___phase-name_|_____|__)_| | | | | >__ ________________________________________ __ ___________________________ __ _________________________ _________>< | | | _*NONE______________ | | _*NO__ | | _*NO__ | | | |_CODELIST__(__|_*ALL_______________|__)_| |_IGNDECERR__(__|_*YES_|__)_| |_ALWNULL__(__|_*YES_|__)_| | | | <____________ (1) | | | |___phase-name_|_____| | | | | Notes: | | | | (1) A maximum of 25 repetitions | | | | (P) All parameters preceding this point can be specified by position. | | | | | | | | | | | | OPTION Details: | | _*SRC______ | | |_*SOURCE___| _*XREF___ _*GEN___ _*NODUMP_ _*NOSECLVL_ _*NOSRCDBG_ _*NOLSTDBG_ | | |__|___________|__|_________|__|________|__|_________|__|___________|__|___________|__|___________|________________| | | |_*NOSRC____| |_*NOXREF_| |_*NOGEN_| |_*DUMP___| |_*SECLVL___| |_*SRCDBG___| |_*LSTDBG___| | | |_*NOSOURCE_| | | | | GENOPT Details: | | _*NOLIST_ _*NOXREF_ _*NOATR_ _*NODUMP_ _*NOPATCH_ _*NOOPTIMZE_ | | |__|_________|__|_________|__|________|__|_________|__|__________|__|____________|_________________________________| | | |_*LIST___| |_*XREF___| |_*ATR___| |_*DUMP___| |_*PATCH___| |_*OPTIMIZE__| | | | | CVTOPT Details: | | |__ ___________ __ __________ __ __________ _______________________________________________________________________| | | |_*DATETIME_| |_*VARCHAR_| |_*GRAPHIC_| | | | | | |______________________________________________________________________________________________________________________| Figure 18. Syntax of the CRTRPGPGM Command |
PGM Specifies the library and program name by which the compiled RPG/400 program is to be known. If no library is specified, the created program is stored in the current library.
*CTLSPEC The program name specified in positions 75 through 80 of the control specification is used.
If the program name is not specified on the control specification, but the source program is from a database file, the member name, specified by the SRCMBR parameter, is used as the program name. If the source is not from a database file, the program name defaults to RPGOBJ.
program-name Enter the name by which the program is to be known.
*CURLIB The compiled program is stored in the current library. If you have not specified a current library, QGPL is used.
library-name Enter the name of the library where the compiled program is to be stored.
SRCFILE Specifies the name of the source file that contains the RPG/400 source program to be compiled and the library where the source file is located.
QRPGSRC The default source file QRPGSRC contains the RPG/400 source program to be compiled.
source-file-name Enter the name of the source file that contains the RPG/400 source program to be compiled.
*LIBL The system searches the library list to find the library where the source file is located.
*CURLIB The current library is used to find the source file. If you have not specified a current library, QGPL is used.
library-name Enter the name of the library where the source file is stored.
SRCMBR Specifies the name of the member of the source file that contains the RPG/400 source program to be compiled. This parameter can be specified only if the source file named in the SRCFILE parameter is a database file.
*PGM Use the name specified by the *PGM parameter as the source file member name. The compiled program will have the same name as the source file member. If no program name is specified by the *PGM parameter, the command uses the first member created in or added to the source file as the source member name.
source-file-member-name Enter the name of the member that contains the RPG/400 source program.
GENLVL Specifies whether or not a program object is generated, depending on the severity of the errors encountered. A severity-level value corresponding to the severity level of the messages produced during compilation can be specified with this parameter. If errors occur in a program with a severity value less than 30, and if a severity-level greater than that of the program is specified for this parameter the program is compiled; however, the program may contain errors that cause unpredictable results when the program is run. For program errors equal to or greater than severity 30, the compilation of the program may be ended or the program object may not be generated, regardless of the value of this parameter. Specifying a value greater than 30 is not recommended for this parameter.
9 A program object will not be generated if you have messages with a severity-level greater than or equal to 9.
severity-level-value: Enter a number, 0 through 99.
Note: The severity-level value of RPG/400 compile messages does not exceed 50.
TEXT Lets the user enter text that briefly describes the program and its function. The text appears whenever program information is displayed.
*SRCMBRTXT The text of the source member is used.
*BLANK No text appears.
'description' Enter the text that briefly describes the program and its function. The text can be a maximum of 50 characters and must be enclosed in apostrophes. The apostrophes are not part of the 50-character string. Apostrophes are not required if you are entering the text on the prompt screen.
OPTION Specifies the options to use when the source program is compiled. You can specify any or all of the options in any order. Separate the options with a blank space.
*SOURCE Produces a source listing, consisting of the RPG/400 program input and all compile-time errors.
*NOSOURCE A source listing is not produced. If *NOSOURCE is specified, the system assumes that you also don't want a cross-reference listing and *NOXREF is also specified.
The acceptable abbreviation for *SOURCE is *SRC, and for *NOSOURCE is *NOSRC.
*XREF Produces a cross-reference listing and key-field-information table (when appropriate) for the source program.
Note: If you also want to specify *NOSOURCE or *NOSRC, you must explicitly specify *XREF or else *NOXREF is assumed.
*NOXREF A cross-reference listing is not produced.
Note: If either *NOSOURCE or *NOSRC is also specified, the usual default (*XREF) is overridden and *NOXREF is the default.
*GEN Creates a program object that can be run after the program is compiled.
*NOGEN Do not create a program object.
*NODUMP Do not dump major data areas when an error occurs during compilation.
*DUMP Dump major data areas when an error occurs during compilation.
*NOSECLVL Do not print second-level message text on the line following the first-level message text.
*SECLVL Print second-level message text.
*NOSRCDBG Do not generate source level error and debug information.
*SRCDBG Generate source level error and debug information. Produce an event file even if the compiler completes without error.
*NOLSTDBG Do not generate error and debug information.
*LSTDBG Generate a listing view and error and debug information required for the listing view.
Note: You can only use the *NOSRCDBG, *SRCDBG, *NOLSTDBG and *LSTDBG options if you are using the AD/Cycle CoOperative Development Environment/400 product to compile your program. If you specify one or more of these options but | do not have the CODE/400 product installed, the RPG/400 compiler will not continue processing and an error message is issued. For more information on these options, see the CODE Debug Tool User's Guide and Reference, SC09-1622.
GENOPT Specifies the options to use to create the program object: the printing of the intermediate representation of a program (IRP), a cross-reference listing of objects defined in the IRP, an attribute listing from the IRP, and the program template. You can also specify options in the GENOPT parameter to reserve a program patch area, and to improve a program for more efficient running. These results may be useful if a problem occurs when you are trying to run the compiled program. You can specify any or all of the options in any order. Separate the values with a blank. For a description of the GENOPT parameter and the information it provides, see "Compiler Debugging Options" in topic A.2 in Appendix A, "RPG Compiler and Auto Report Program Service Information."
*NOOPTIMIZE Do not process program optimization.
*OPTIMIZE Process program optimization. With *OPTIMIZE, the compiler generates a program for more efficient processing and one that will possibly require less storage. Specifying *OPTIMIZE can substantially increase the time required to create a program. Existing program objects can be optimized with the CL command CHGPGM.
INDENT Specifies whether or not the compiled RPG/400 program's source listing is generated with the indentation of structured operations for enhanced readability. Also specifies the characters that are used to mark the structured operation clauses.
*NONE A listing without indentation will be produced by the compiler.
character-value The source listing is indented for structured operation clauses. Alignment of statements and clauses are marked using the characters you choose. You can choose any character string up to 2 characters in length. If you want to use a blank in your character string, you must enclose it in single quotation marks.
Note: The indentation may not appear as expected if there are errors in the RPG/400 program.
The second set of prompt screens shown in Figure 20 provides more values and keywords that you can enter for the CRTRPGPGM command.
__________________________________________________________________________________ | | | Create RPG/400 Program (CRTRPGPGM) | | | | Type choices, press Enter. | | | | Type conversion options . . . . *NONE____ *NONE, *DATETIME, *VARCHAR... | | + for more values _________ | | SAA flagging . . . . . . . . . . *NOFLAG *NOFLAG, *FLAG | | Print file . . . . . . . . . . . QSYSPRT___ Name | | Library . . . . . . . . . . . *LIBL_____ Name, *LIBL, *CURLIB | | Replace program . . . . . . . . *YES *YES, *NO | | Target release . . . . . . . . . *CURRENT *CURRENT, *PRV, V2R1M0... | | User profile . . . . . . . . . . *USER_ *USER, *OWNER | | Authority . . . . . . . . . . . *LIBCRTAUT Name, *LIBCRTAUT, *ALL... | | Phase trace . . . . . . . . . . *NO_ *NO, *YES | | Intermediate text dump . . . . . *NONE_______________________________________ | | _____ | | Snap dump . . . . . . . . . . . *NONE_______________________________________ | | _____ | | Codelist . . . . . . . . . . . . *NONE_______________________________________ | | _____ | | More... | | F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display | | F24=More keys | | | | | | | |__________________________________________________________________________________| |
Figure 20. Second Set of CRTRPGPGM Prompt Screens
CVTOPT Specifies how the RPG/400 compiler handles date, time, and timestamp database data types, and variable-length data types which are retrieved from externally-described files. See "SAA Data Types" in topic 10.3 for a detailed description of how the RPG/400 compiler supports SAA data types.
*NONE Date, time, timestamp and variable-length database data types are ignored and not accessible in the RPG/400 program. A severity 0, compile-time informational message is issued when a record format contains ignored fields.
*DATETIME Specifies that date, time, and timestamp database data types are to be declared as fixed length character fields and are accessible in the RPG/400 program.
*VARCHAR Specifies that variable-length database data types are to be declared as fixed length character fields and are accessible in the RPG/400 program.
*GRAPHIC Specifies that double-byte character set (DBCS) graphic data types are to be declared as fixed length character fields and are accessible in the RPG/400 program.
Note: Choose both of the parameters *VARCHAR and *GRAPHIC if you want variable-length DBCS graphic data types to be declared in your program.
SAAFLAG Specifies if there will be flagging of specifications not supported by SAA RPG. For more information on SAA flagging, how and why to use it, see "Systems Application Architecture Flagging Messages" in topic 4.1.2.
*NOFLAG No flagging will be performed.
*FLAG Flagging will be performed. Messages will be listed under the heading of SAA Message Summary. No SAA message will be issued for a specification if a message of severity 30 or above is issued for that specification.
PRTFILE Specifies the name of the file where the compiler listing is to be placed, and the library where the file is located. If you specify a file whose record length is less than 132, information will be lost.
QSYSPRT If a file name is not specified, the compiler listing is placed in the IBM-supplied file, QSYSPRT. The file QSYSPRT has a record length of 132.
file-name Enter the name of the file where the compiler listing is to be placed.
*LIBL The system searches the library list to find the library where the file is located.
*CURLIB The current library will be used to find the file. If you have not specified a current library, QGPL will be used.
library-name Enter the name of the library where the file is located.
REPLACE Specifies whether or not a new program object is to be created if a program with the same name already exists in the specified library.
*YES A new program object will be created and any existing program object of the same name in the specified library will be moved to library QRPLOBJ.
*NO A new program object will not be created if a program object of the same name already exists in the specified library.
TGTRLS Specifies the release level of the operating system on which you intend to use the object being created.
You can specify an exact release level in the format VxRxMx, where Vx is the version, Rx is the release, and Mx is the modification level.
Note: To use the object on the target system, you must save the object to the target release level specified on the create command and then restore it on the target system.
*CURRENT The object is to be used on the release of the operating system currently running on your system.
*PRV The object is to be used on the previous release with modification level 0 of the operating system.
release-level Specify the release in the format VxRxMx. The object can be used on a system with the specified release or with any subsequent release of the operating system installed.
Valid values depend on the current version, release, and modification level, and they change with each new release.
USRPRF Specifies the user profile the compiled RPG/400 program runs under. This profile controls which objects can be used by the program (including what authority the program has for each object). If the program already exists, the USRPRF parameter will not be updated to a new profile.
*USER The program runs under the user profile of the program's user.
*OWNER The program runs under the user profiles of both the program's owner and user. The collective sets of object authority in both user profiles are used to find and access objects while the program is running. Any objects that are created during the program are owned by the program's user.
Note: The USRPRF parameter reflects the security requirements of your system. The security facilities available on the AS/400 system are described in detail in the Security Reference and the CL Reference.
AUT Specifies the authority given to users who do not have specific authority to the object, who are not on the authorization list, and whose user group has no specific authority to the object. The authority can be altered for all or for specified users after program creation with the CL commands Grant Object Authority (GRTOBJAUT) or Revoke Object Authority (RVKOBJAUT). For further information on these commands, see the CL Reference.
*LIBCRTAUT The public authority for the object is taken from the CRTAUT keyword of the target library (the library that contains the object). The value is determined when the object is created. If the CRTAUT value for the library changes after the create, the new value will not affect any existing objects.
*CHANGE The public has object operational authority and all the data authorities for the compiled program. Any user can run, debug,change and perform basic functions on the program.
*USE The public can run the compiled program, but cannot debug or change it.
*ALL The public has complete authority for the program.
*EXCLUDE The public cannot use the program.
authorization-list name Name of an authorization list to which the program is added. For a description of the authorization list and how to create it, see the CL Reference.
Note: Use the AUT parameter to reflect the security requirements of your system. The security facilities available are described in detail in the Security Reference manual.
PHSTRC Specifies if information about compiler phases is provided on the listing. See Appendix A, "RPG Compiler and Auto Report Program Service Information" for a detailed explanation of this parameter.
*NO Do not provide information about compiler phases.
*YES Provide information about compiler phases.
ITDUMP This parameter specifies if a dynamic listing of intermediate text for one or more specified phases is to be printed at compile time as each IT record is being built. This parameter also specifies if a flow of the major routine runs in one or more specified phases is to be printed. See Appendix A, "RPG Compiler and Auto Report Program Service Information" for a detailed explanation of this parameter.
*NONE No intermediate text dump is produced.
phase-name Enter the last two characters of phase name. See Appendix A, "RPG Compiler and Auto Report Program Service Information" for a detailed explanation of this parameter.
SNPDUMP Specifies if the major data areas are to be printed after the running of one or more specified phases. See Appendix A, "RPG Compiler and Auto Report Program Service Information" for a detailed explanation of this parameter.
*NONE No snap dump is produced.
phase-name Enter the last two characters of phase name. See Appendix A, "RPG Compiler and Auto Report Program Service Information" for a detailed explanation of this parameter.
CODELIST Specifies if a dynamic listing of the IRP is to be printed during compilation of one or more specified phases of the source program. See Appendix A, "RPG Compiler and Auto Report Program Service Information" for a detailed explanation of this parameter.
*NONE Do not produce a code listing for each of the code generating phases run.
*ALL Produce a code listing for each of the code generating phases run.
phase-name Enter the last two characters of phase name. See Appendix A, "RPG Compiler and Auto Report Program Service Information" for a detailed explanation of this parameter.
The third set of prompt screens shown in Figure 21 provides more values and keywords that you can enter for the CRTRPGPGM command.
__________________________________________________________________________________ | | | Create RPG/400 Program (CRTRPGPGM) | | | | Type choices, press Enter. | | | | Ignore decimal data error . . . *NO_ *NO, *YES | | Allow null values . . . . . . . *NO_ *NO, *YES | | | | | | | | Bottom | | F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display | | F24=More keys | | | | | |__________________________________________________________________________________| |
Figure 21. Third Set of CRTRPGPGM Prompt Screens
IGNDECERR Specifies if decimal data errors detected by the system are ignored by the program.
*NO Do not ignore decimal data errors. When a numeric operation is attempted on a numeric field that contains decimal data that is not valid, a program exception is raised. Decimal data errors will be detected only for fields defined in packed decimal format. For more information on packed decimal format, see Chapter 11, "Communicating with Objects in the System" in topic 11.0.
*YES Ignore decimal data errors. The effect of decimal data errors on processing is not readily predicted. The compiler only generates an error message on the compiler listing to notify the user that this option was specified. When this option is specified, incorrect results that occur while a program is running are the user's responsibility.
ALWNULL Specifies whether an RPG/400 program will accept null values from null-capable fields in an externally described input-only file. A severity 0, compile-time message is issued when a record format contains null-capable fields. See "Null Value Support" in topic 10.3.4 for a detailed description of how the RPG/400 compiler supports null-capable fields.
*NO Specifies that the RPG/400 program will not process null value fields from externally-described files. If you attempt to retrieve a record containing null values, no data in the record is accessible to the RPG/400 program and a data-mapping error occurs.
*YES Specifies that an RPG/400 program will accept null value fields for an externally-described input-only file. When a record containing null values is retrieved from an externally-described input-only file, no data mapping errors occur and the database default values are placed into any fields which contain null values.
3.3 Compiling under the System/38 Environment
4.0You can also compile an RPG/400 source program from the System/38 Environment. You call the compiler with the same commands as you use in the AS/400 system environment (CRTRPGPGM to call up the RPG/400 compiler, and CRTRPTPGM to call up the automatic report function). To compile a program from the System/38 Environment, use the CL command CALL QCL to call up the System/38 Environment before you enter the CRTRPGPGM command. You can also enter System/38 Environment commands from the native environment by library qualifying commands. The QSYS38/CRTRPGPGM command calls the System/38 Environment RPG III compiler.
For more information on the differences between the RPG/400 program in the AS/400 environment and in the System/38 Environment, see Appendix E, "System/38 Environment Option of the RPG Compiler."
For further information about programming in the System/38 Environment, refer to the System/38 RPG III Reference Manual and Programmer's Guide.
4.0 Chapter 4. Error Messages, Testing, and Debugging
This chapter describes error messages you may receive from RPG/400 compiler, explains their meaning, and how you can display and print them. This chapter also describes testing and debugging an RPG/400 program using functions provided by the RPG/400 compiler and OS/400 system.
__________________________ ____________________________________ | OS/400 System | RPG | |__________________________|____________________________________| | ° Test library | ° DEBUG operation code | |__________________________|____________________________________| | ° Breakpoints | ° DUMP operation code | |__________________________|____________________________________| | ° Traces | | |__________________________|____________________________________|
The OS/400 system functions allow you to use CL commands to test programs while protecting your production files, and let you observe and debug operations as a program runs. See the CL Reference for more information on using CL commands.
No special source code is required to use the OS/400 system functions. The RPG/400 compiler functions can be used independently of the OS/400 system functions or in combination with them either to:
° Debug a program
° Produce a formatted dump of indicator settings and the contents of fields, data structures, arrays, and tables.
Special source code is required to use the RPG/400 DEBUG and DUMP operation codes. You can also obtain a formatted dump in response to a run-time message.
A file information data structure and a program status data structure can provide additional debugging information. These data structures are described later in this chapter. Following this is information on exception/error handling.
Subtopics:
- 4.1 Using, Displaying, and Printing Messages
- 4.2 How to Run an RPG/400 Program
- 4.3 Using a Test Library
- 4.4 Using Breakpoints
- 4.5 Using a Trace
- 4.6 Using the DEBUG Operation Codes
- 4.7 Using the RPG/400 Formatted Dump
- 4.8 Exception/Error Handling
4.1 Using, Displaying, and Printing Messages
Subtopics:
- 4.1.1 Using Messages
- 4.1.2 Systems Application Architecture Flagging Messages
- 4.1.3 Displaying and Printing Messages
4.1.1 Using Messages
This manual refers to the messages you receive during compilation and run-time. These messages are displayed on your screen or printed on your compiler listing. This product has no message manuals.
Each message contains a minimum of three parts as illustrated in the following sample message:
______________________________________________________________________________________________________
| |
| |
| |
| |
| A 10 |
| |
| B Message: Syntax of Program-Identification entry is not valid. Defaults to RPGOBJ. |
| |
| C Cause: The Program-Identification entry (positions 75-80) of a control |
| specification has a not valid syntax: the first character is not |
| alphabetic or it is not left-justified, or it contains embedded blanks |
| or special characters. Defaults to RPGOBJ. |
| |
| Recovery: Specify RPGOBJ or a valid entry (positions 75-80) for the |
| Program-Identification option. Recompile. |
| |
| |
| |
|______________________________________________________________________________________________________|
|
A A number indicating the severity of the error. The severity-level value of the RPG/400 compile-time messages does not exceed 50.
Severity Meaning
00 An informational message displayed during entering, compiling, and running. No error has been detected and no corrective action is necessary.
10 A warning message displayed during entering, compiling, and running. This level indicates that an error is detected but is not serious enough to interfere with the running of the program. The results of the operation are assumed to be successful.
20 An error message displayed during compiling. This level indicates an error, but the compiler is attempting a recovery that might yield the desired code. The program may not work as the author intends.
30 A severe error message displayed during compiling. This level indicates that an error too severe for automatic recovery is detected. Compilation is complete, but the program does not run.
40 An abnormal end-of-program or function message displayed during compiling or running. This level indicates an error that forces cancelation of processing. The operation ended either because it could not handle valid data, or because the user canceled it.
50 An abnormal end-of-job message displayed during compiling or running. This level indicates an error that forces cancelation of job. The job ended either because a function failed to perform as required, or because the user canceled it.
99 A user action to be taken during running. This level indicates that some manual action is required of the operator, such as entering a reply, changing diskettes, or changing printer forms.
B The text you see online or on a listing. This text is a brief, generally one-sentence, description of the problem.
C This text is printed on your listing if you specify *SECLVL in your compile-time options. It contains an expanded description of the message and a section detailing the correct user response. The IBM-supplied default for this option is *NOSECLVL.
At run time, you can enter D to obtain an RPG/400 formatted dump, S to obtain system dump, C to cancel, G to continue processing at *GETIN, or F to obtain a RPG/400 full-formatted dump.
4.1.2 Systems Application Architecture Flagging Messages
In addition to the messages described above, the RPG/400 compiler also has a set of messages that flag those RPG/400 compiler features not supported by SAA RPG. These messages are requested with a compiler option, SAAFLAG, described in "CRTRPGPGM Command" in topic 3.2. The default value for this option is *NOFLAG. If you select *FLAG, these messages are printed separately under the heading SAA Message Summary.
The SAA flagging messages are to help the programmer when writing portable code. If you are seeking maximum portability, you should eliminate the flagged codes from your program. A program that has only SAA messages will compile and run correctly on the AS/400 system. SAA messages are informational messages only. Severe error messages may suppress SAA messages.
SAA messages are divided in the same way as the other messages described here. A sample message is:
_______________________________________________________________________________________
| |
| |
| |
| |
| A 0 |
| |
| B Message: SAA RPG does not support numeric fields with more than 15 digits. |
| |
| C Cause: Systems Application Architecture |
| Common Programming |
| Interface RPG does not support numeric fields with more than 15 digits. |
| |
| Recovery: If SAA RPG adherence is required, change the program |
| and recompile. |
| |
| |
| |
|_______________________________________________________________________________________|
|
These messages flag RPG/400 compiler specific functions only.
4.1.3 Displaying and Printing Messages
To display or print particular messages, use the DSPMSGF or DSPMSGD commands. The compile-time messages are stored in a file called QRPGMSG in library QRPG. The run-time messages are stored in a file called QRPGMSGE in library QSYS.
In the System/38 environment, all the compile-time messages are in file QRPG3MSG in library QRPG38. The run-time messages are in file QRPG3MSGE in library QSYS.
Note: If you have any comments or suggestions concerning the messages, please use the Reader Comment Form included with this manual to send them to us.
4.2 How to Run an RPG/400 Program
There are many ways to run an RPG/400 program, depending on how the program is written and who is using the program. See the CL Programmer's Guide for the various ways to run an RPG/400 program. The three most common ways of running an RPG/400 program are through:
° A high-level language CALL statement or operation ° An application-oriented menu ° A user-created command.
The CL statement CALL can be part of a batch job, be entered interactively by a work station user, or be included in a CL program. An example is CALL PAYROLL. PAYROLL is the name of either a CL program or an RPG/400 program that is called and then run. An RPG/400 program can call another program with the CALL operation code. See Chapter 11, "Communicating with Objects in the System."
Another way to run an RPG/400 program is through an application-oriented menu. You can request an application-oriented menu and then select an option that will call the appropriate program. Figure 22 is an example of an application-oriented menu:
__________________________________________________________________________________ | | | | | PAYROLL DEPARTMENT MENU | | | | 1. Inquire into employee master | | | | 2. Change employee master | | | | 3. Add new employee | | | | 4. Return | | | | | | | | Option:__ | | | | | | | | | | | | | | | | | | | | | | | |__________________________________________________________________________________| |
Figure 22. Example of an Application-Oriented Menu
This menu is normally written as a CL program where each option calls a separate RPG/400 program. When an RPG/400 program ends, the system returns control to the calling program or to the user. This could be a work station user, a CL program (such as the menu handling program), or another RPG/400 program.
You can also create a command yourself to run an RPG/400 program by using a command definition. See the CL Programmer's Guide for a description of how to define a command. For example, you can create a PAY command that calls a PAYROLL program. A user-created command can be entered into a batch job, or it can be entered interactively by a workstation user.
Subtopics:
4.2.1 Save-While-Active Support
Application programs that change objects or data may run while the objects or data are being saved. Refer to the Advanced Backup and Recovery Guide for possible programming considerations related to save-while-active support.
4.3 Using a Test Library
The basic concept of testing and debugging is that of a separate testing environment. Programs running in a normal operating environment or in a test environment can read, update, and write records that are in either test or production libraries. To prevent database files in production libraries from being changed unintentionally, you can specify the UPDPROD(*NO) option on the CL command STRDBG (Start Debug).
On the AS/400 system, you can copy production files into the test library or you can create special files for testing in this library. A test copy of a file and its production copy can have the same name if the files are in different libraries. You can use the same file name in the program for either testing or normal processing.
Figure 23 shows an example of using a separate test environment.
Normal Environment _______________________ | | Job | Production Library | ____________ _______ÿ| Production Files |___ | Program 1 | | | | | | . | | |_______________________| | | . | | | | . | | | | Program 5 |___ÿ| | | . | | | | . | | Test Environment | | . | | ________________________ | | Program 10 | | | | | |____________| | | Test Library | | |_______ÿ| Test Files |__| | | |________________________|
Figure 23. Using a Separate Test Environment
For testing, you must place the test library name ahead of the production library name in the library list for the job that contains the program to be tested as shown in Figure 24.
TESTING ENVIRONMENT
___________ | Test | _ÿ| Library | | | | ____________ | |___________| |Library List| | |____________| | |Test Library| | _________ | | | ___________ | | | Production | | |Production | | Program |__ÿ| Library 1 |__|_ÿ| Library 1 | | | | | | | | |_________| | Production | | |___________| | Library 2 | | | | | | QTEMP | | |____________| | ___________ | |Production | |_ÿ| Library 2 | | | |___________|
Figure 24. Testing Environment
For normal program running, the production library should be the only library named in the library list for that job. (That is, the test library should not be named.) See Figure 25 below.
NORMAL ENVIRONMENT
___________ | | ____________ |Production | |Library List| __ÿ| Library 1 | _________ |____________| | | | | | |Production | | |___________| | | | Library 1 | | |Program |__ÿ| | | | | |Production |_| | | | Library 2 | | |_________| | | | ___________ |QTEMP | | | | | | | |Production | |____________| |__ÿ| Library 2 | | | | | |___________|
Figure 25. Normal Environment
No special statements for testing are contained within the program being tested. The same program being tested can be run normally without modifications. All testing functions are specified within the job that contains the program and not within the program.
JOB _________________ |Testing Functions| ____(These functions are specified | | via OS/400 system commands.) |_________________| | | | | | Programs | | | | | | | | | |_________________|
Figure 26. Testing Functions
Testing functions apply only to the job in which they are specified. A program can be used concurrently in two jobs: one job that is in a test environment and another job that is in a normal processing environment.
The OS/400 system testing functions let you interact with a program while it is running so as to observe its processing. These functions include using breakpoints and traces.
4.4 Using Breakpoints
You can use breakpoints to stop your program at a specified point. A breakpoint can be a statement number or a label in your program. If you use a label as a breakpoint rather than a statement number, the label can be:
° On a TAG statement in the program
° Associated with a step in the RPG/400 program cycle. For example, *TOTC indicates the beginning of total calculations, and *TOTL indicates the beginning of total output.
° Associated with a function done by your RPG/400 program. For example, SQRT indicates the square root function.
When a breakpoint is encountered in an interactive job, the system displays the breakpoint at which the program stops and, if requested, the values of program variables. After getting this information (displayed), you can go to a Command Entry Screen and enter CL commands to request other functions (such as displaying or changing a variable, adding a breakpoint, or adding a trace).
When a breakpoint is encountered in a batch job, a breakpoint program can be called. You must create this breakpoint program to handle the breakpoint information.
Subtopics:
4.4.1 Example of Using Breakpoints
Figure 27 shows a source listing of a sample RPG/400 program, DBGPGM, and the CL commands that add breakpoints at statements 1200 and 1500. The value of variable *IN is displayed when the breakpoint at statement 1200 is reached, and the value of variables FLD1 and PART are displayed when the breakpoint at statement 1500 is reached.
CL Commands
STRDBG PGM(EXAMPLES/DBGPGM) ADDBKP STMT(1200) PGMVAR((*IN)) ADDBKP STMT(1500) PGMVAR((FLD1) (PART)) OUTFMT(*HEX)
5763RG1 V3R0M5 940125 IBM RPG/400 QGPL/DBGPGM 01/25/94 13:42:19 Page 2 SEQUENCE IND DO LAST PAGE PROGRAM NUMBER *...1....+....2....+....3....+....4....+....5....+....6....+....7...* USE NUM UPDATE LINE ID S o u r c e L i s t i n g H ***** 100 FTESTX IF F 5 DISK 01/01/94 200 FTESTA UF F 10 DISK 01/01/94 300 ITESTX NS 01 01/01/94 400 I 1 5 PART 01/01/94 500 ITESTA NS 02 01/01/94 600 I 1 5 FLD1 01/01/94 700 ***************************************************** 01/01/94 800 * MAINLINE 01/01/94 900 ***************************************************** 01/01/94 1000 C LOOP TAG 01/01/94 1100 C READ TESTX 66 3 01/01/94 1200 C 66 GOTO ENDPGM 01/01/94 1300 C READ TESTA 67 3 01/01/94 1400 C N67 MOVE PART FLD1 01/01/94 1500 C N67 EXCPTMAST 01/01/94 1600 C N66 GOTO LOOP 01/01/94 1700 C ENDPGM TAG 01/01/94 1800 C SETON LR 1 01/01/94 1900 OTESTA E MAST 01/01/94 2000 O FLD1 5 01/01/94 * * * * * E N D O F S O U R C E * * * * * |
Figure 29. Second Breakpoint Display for DBGPGM
At this point, you can change the value of one of these variables to alter how your program runs. After getting to the Command Entry Screen by pressing F10, you can use the CL command CHGPGMVAR (Change Program Variable) to change the value of a variable.
4.4.2 Considerations for Using Breakpoints
You should know the following characteristics of breakpoints before using them:
° If a breakpoint is part of a conditional statement, that breakpoint request is processed even if the condition is not met.
° If a breakpoint is bypassed by a GOTO operation, that breakpoint request is not processed.
° Some statements that are not processed do not represent a definite position in the logic flow of your program. Avoid putting breakpoints on PLIST, PARM, KLIST, KFLD, and DEFN operations.
° When a breakpoint is requested for a statement, the breakpoint occurs before that statement is run.
° When a breakpoint is requested for a statement that is not processed, such as a TAG operation, the breakpoint is set on the next statement.
° Breakpoint functions are specified using CL commands. You can use CL commands to add breakpoints to programs, display breakpoint information, remove breakpoints from programs and start a program after a breakpoint has been displayed. Refer to the CL Reference for descriptions of these commands and for a further description of breakpoints.
° Input fields not used in your program cannot be specified in the PGMVAR parameter of the debug commands. You can display the entire input or output buffer for a record by using the variable name ZZnnBIN (input buffer) or ZZnnBOUT (output buffer). The nn value is the sequence number corresponding to the order in which the files are defined in your specifications. This number also appears in the cross reference section of the compiler listing. Thus you can display the input buffer for the second file in your program by specifying PGMVAR (ZZ02BIN).
4.5 Using a Trace
You can use a trace to record the statements that are run in a program and the values of the variables used in the statements.
To use a trace, you specify what statements and variables the system should trace. You can also specify that variables be traced only when their values change. You can specify a trace of one statement, a group of statements, or an entire program. You must request a display of the traced information. The display shows the sequence in which the statements were run and, if requested, the values of variables used in the statements. Figure 30 shows the setup of a trace for program statements and their order of processing.
Program Trace ______________ ___________________________________________ | Statement | | Order of Processing Variables | | | | | | 1 _______ | | 1 ___________ÿ _______ | | 2 _______ | | 6 ___________ÿ _______ | | 3 _______ | | 7 ___________ÿ _______ | | 4 _______ | | 8 ___________ÿ _______ | | 5 _______ | | 6 ___________ÿ _______ | | 6 _______ | | 7 ___________ÿ _______ | | 7 _______ | | 2 ___________ÿ _______ | | 8 _______ | | 6 ___________ÿ _______ | | . | | 7 ___________ÿ _______ | | . | | . | | . | | . | | | | | |______________| |___________________________________________|
Figure 30. Program Statements and Order of Processing
Subtopics:
4.5.1 Example of Using a Trace
Figure 27 in topic 4.4.1 shows a portion of a listing of RPG/400 program DBGPGM. The CL command that adds a trace of statements 1000 through 1800 in that program is:
ADDTRC STMT((1000 1800))
Figure 31 is an example of a display of the traced information. The CL command to display this information is:
DSPTRCDTA OUTPUT(*)
__________________________________________________________________________________ | | | Display Trace Data | | | | Statement/ | | Program Instruction Recursion Level Sequence Number | | DBGPGM 1000 1 1 | | DBGPGM 1200 1 2 | | DBGPGM 1300 1 3 | | DBGPGM 1400 1 4 | | DBGPGM 1500 1 5 | | DBGPGM 1600 1 6 | | DBGPGM 1000 1 7 | | DBGPGM 1200 1 8 | | DBGPGM 1800 1 9 | | | | | | | | | | | | | | | | | | Press Enter to continue. | | F3=Exit F12=Cancel | | | | | |__________________________________________________________________________________| |
Figure 31. Trace Data Display for DBGPGM
4.5.2 Considerations for Using a Trace
You should know the following characteristics of traces before using them:
° A conditional statement is recorded in the trace even if the condition is not met.
° Statements bypassed by GOTO operations are not included in the trace.
° Trace functions are specified with CL commands in the job that contains the traced program. These functions include adding trace requests to a program, removing trace requests from a program, removing data collected from previous traces, displaying trace information, and displaying the traces that have been specified for a program.
° You cannot display a variable that is not referenced in your RPG/400 program.
4.6 Using the DEBUG Operation Codes
You can code one or more DEBUG operation codes among your RPG/400 calculations to help you debug a program that is not working properly. Whenever the DEBUG operation is processed, one or two records with debugging information are provided. The first record contains a list of all indicators that are set on at the time the DEBUG operation was encountered. The second record is optional and shows the contents of the result files specified for the DEBUG operation.
The DEBUG operation can be coded at any point or at several points in the calculation specifications. The output records are written whenever the DEBUG operation occurs.
You should know the following characteristics of the DEBUG operation code before using it:
° The DEBUG operation runs (are active) only if position 15 of the control specification contains a 1.
° If the DEBUG operation is conditioned, it occurs only if the condition is met.
° If a DEBUG operation is bypassed by a GOTO operation, the DEBUG operation does not occur.
You can apply the OS/400 system testing and debugging functions to programs that use DEBUG operations; a breakpoint can be on a DEBUG operation, and a DEBUG operation can be traced.
4.7 Using the RPG/400 Formatted Dump
To obtain an RPG/400 formatted dump (printout of storage) for a program while it is running, you can code one or more DUMP operation codes in your calculations, or you can respond to a run-time message with a D or F option. It is also possible to automatically reply to make a dump available. Refer to the "System Reply List" discussion in the CL Programmer's Guide.
The formatted dump includes field contents, data structure contents, array and table contents, the file information data structure, and the program status data structure. The dump is written to the file called QPPGMDMP. (A system abnormal dump is written to the file QPSRVDMP.)
If you respond to an RPG/400 run-time message with an F option, the dump also includes the hexadecimal representation of the open data path (ODP, a data management control block). If position 15 of the control specification contains a 1, the F option also provides a list of compiler-generated fields.
Information from the file information data structure (INFDS) is provided for each file in the program. Not all the information that is contained in the INFDS is printed in the dump. Remember that, to use any information from the INFDS in your program, you must define the INFDS in your program.
The same characteristics as described for the DEBUG operation apply to the DUMP operation.
Figure 32 shows an example of an RPG/400 formatted dump.
___ Note _______________________________________________________________ | | | Only selected pages of an RPG/400 formatted dump are presented below. | | | |________________________________________________________________________|
RPG/400 FORMATTED DUMP Program Status Area: _______________________ Program Name . . . . . . . . . . . . . : QGPL/SAMPLE A | Program Status . . . . . . . . . . . . : 00000 B | Previous Status . . . . . . . . . . . : 00000 C | Statement in Error . . . . . . . . . . : 00000000 D | RPG Routine . . . . . . . . . . . . . : *DETC E | Number of Parameters . . . . . . . . . : 000 | Message Type . . . . . . . . . . . . . : F | MI Statement Number . . . . . . . . . : G | Additional Message Info . . . . . . . : | Program Message Data . . . . . . . . . . . . . : | Status Last File Used . . . . . . . . . . . . : QSYSPRT ______ | Information Last File Status . . . . . . . . . . . : 01235 | | Error in PRTCTL entries occurred in (C G S D). | H | Last File Operation . . . . . . . . . : OPEN I | | Last File Routine . . . . . . . . . . : *INIT | | Last File Statement . . . . . . . . . : *INIT | | Last File Record Name . . . . . . . . : ______| | Job Name . . . . . . . . . . . . . . . : E53 ______ | User Name . . . . . . . . . . . . . . : QPGMR | | Job Number . . . . . . . . . . . . . . : 000811 | | Date Entered System . . . . . . . . . : 092592 | | Date Started . . . . . . . . . . . . . : 092592 | | Time Started . . . . . . . . . . . . . : 111143 | I | Compile Date . . . . . . . . . . . . . : 052592 | | Compile Time . . . . . . . . . . . . . : 111125 | | Compiler Level . . . . . . . . . . . . : 0001 | | Source File . . . . . . . . . . . . . : QRPGSRC | | Library . . . . . . . . . . . . . . : QGPL | | Member . . . . . . . . . . . . . . . . : SAMPLE ______| | _______________________| RPG/400 FORMATTED DUMP |
A Qualified program name and library.
B Current status code.
C Previous status code.
D RPG/400 source statement in error.
E RPG/400 routine in which the exception or error occurred.
F CPF or MCH for a machine exception.
G Machine instruction number.
H Information about the last file used in the program before an exception or error (RPG1235) occurred.
I Program information.
J Error in the file.
K The number of times the RPG/400 compiler requested I/O of the system (not the number of I/O operations requested by the program).
L The open data path is included in the dump if the user responds to an RPG/400 run-time message with an F option.
M A list of compiler-generated fields is also included in the dump if the user responds to an RPG/400 run-time message with an F option and if the program was compiled with a 1 in position 15 of the control specification.
N General indicators 1-99 and their current status (1 is on, 0 is off).
O Beginning of user fields.
P Incorrect zoned field printed in hexadecimal.
Q File information data structures for FILEIN1 and FILEIN2.
R Double-occurrence data structure.
S System date values.
T IGNDECERR(*NO) was specified in the CRTRPGPGM command.
U Program status data area.
V Input buffer for file 02.
W This is the file number. See the cross-reference section of the compiler listing for the corresponding file name. The files are assigned a sequence number corresponding to the order in which they are defined in your specifications. Thus, the file number 03 corresponds to the FILEIN2 file described in this program.
X Output buffer for file 03.
4.8 Exception/Error Handling
5.0The RPG/400 compiler handles two types of exception or errors: program exception or errors and file exception or errors. Some examples of program exception or errors are division by zero, not valid array index, or SQRT of a negative number. Some examples of file exception or errors are undefined record type or a device error.
Figure 33 shows an example of a file information data structure (INFDS) and a file exception/error subroutine. For further information on exception/error handling by the RPG/400 compiler, see the RPG/400 Reference manual.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* F* F* Three files are defined on the file description specifications. F* You want to control the program logic if an exception or error F* occurs on the TRNFIL file or on the MSTFIL file. Therefore, a F* unique INFDS and a INFSR are defined for each file. They are F* not defined for the AUDITFIL file. F* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FTRNFIL OF E K DISK KINFDS FILDS1 F KINFSR ERRRTN FMSTFIL UF E K DISK KINFDS FILDS2 F KINFSR MSTERR FAUDITFILOF E K DISK
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* I* I* The location of the subfields in the file information data I* structures is defined by special keywords in positions 44 I* through 51. To access these predefined subfields, you must I* assign a name to each subfield in positions 53 through 58. I* If an exception or error occurs, you can test the information I* in the data structure to determine, for example, what exception I* or error occurred (*STATUS) and on which operation it occurred I* (*OPCODE). You can then use that information within the file I* exception/error subroutine to determine the action to take. I* IFilenameSqNORiPos1NCCPos2NCCPos3NCC................................* IFILDS1 DS I....................................PFromTo++DField+L1M1FrPlMnZr...* I *FILE FIL1 I *RECORD REC1 I *OPCODE OP1 I *STATUS STS1 I *ROUTINE RTN1 IFILDS2 DS I *FILE FIL2 I *RECORD REC2 I *OPCODE OP2 I *STATUS STS2 I *ROUTINE RTN2
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* On the WRITE operation to the TRNREC record in the TRNFIL file, C* an exception/error indicator is specified in positions 56 and 57. C* This indicator is set on if an exception or error occurs on this C* operation. The ERRRTN subroutine (the file exception or error C* subroutine for the TRNFIL file) is explicitly called by the EXSR C* operation when indicator 71 is on. Because factor 2 of the ENDSR C* operation for the ERRRTN is blank, control returns to the next C* sequential instruction following the EXSR operation after the C* subroutine has run. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C WRITETRNREC 71 C 71 EXSR ERRRTN ________________ C " | Calculations | C* |________________| C* C* No exception/error indicator is specified in positions 56 and 57 C* of the WRITE operation to the AUDITREC record in the AUDITFIL C* file. No exception/error subroutine was defined for this file C* on the file description specifications. Therefore, any exception/ C* errors that occur on this operation to the AUDITFIL file are C* handled by the default RPG default error handler. C* C WRITEAUDITREC ________________ C " | Calculations | C* |________________|
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* No exception/error indicator is specified in positions 56 and 57 C* of the CHAIN operation to the MSTREC record in the MSTFIL file. C* However, a file exception/error subroutine (MSTERR) is defined C* for the file on the file description specifications. Therefore, C* when an exception or error other than no record found occurs on C* the CHAIN operation, RPG passes control to the MSTERR subroutine. C* On the ENDSR operation for this subroutine, factor 2 contains a C* field name. This allows the programmer to alter the return point C* from the subroutine within the subroutine based on the exception C* or error that occurred. The field must contain one of the values C* described under File Exception/Error Subroutine earlier in C* this chapter. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C MSTKEY CHAINMSTREC 61 C 61 GOTO NOTFND C " C " C MSTERR BEGSR ________________ C " | Calculations | C " |________________| C ENDSRRTRPNT C " C " C ERRRTN BEGSR ________________ C " | Calculations | C " |________________| C ENDSR
Figure 33. Example of File Exception/Error Handling
Figure 34 shows an example of a program exception/error subroutine.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* IDsname....NODsExt-file++.............OccrLen+......................* I SDS I *ROUTINE LOC I *STATUS ERR I *PARMS PARMS I *PROGRAM NAME
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C *PSSR BEGSR C ERR COMP 102 20 DIV BY ZERO? C 20 ADD 1 DIVSR C 20 MOVE '*DETC' RETURN 6 C N20 MOVE '*CANCL' RETURN C ENDSRRETURN
Figure 34. Example of *PSSR Subroutine
The program-status data structure is defined on the input specifications. The predefined subfields *STATUS, *ROUTINE, *PARMS, and *PROGRAM are specified, and names are assigned to the subfields.
The *PSSR subroutine is coded on the calculation specifications. If a program exception/error occurs, the RPG/400 compiler passes control to the *PSSR subroutine. The subroutine checks to determine if the exception or error was caused by a divide operation in which the divisor is zero. If it was, indicator 20 is set on, 1 is added to the divisor (DIVSR), and the literal '*DETC'. is moved to the field RETURN. Moving the literal into the RETURN field, which is specified in factor 2 of the ENDSR operation, allows you to control the return point within the subroutine. In this example, control returns to the beginning of the detail calculations routine, unless the exception or error was not a divide by zero. In that case, the literal '*CANCL' is moved into the RETURN field, and the program is ended.
5.0 Chapter 5. General File Considerations
This chapter describes:
° The device-independent and device-dependent characteristics of the RPG/400 program on the AS/400 system
° AS/400 spooling functions
° The extent to which externally described and program-described files are defined in the RPG/400 program
° Level checking functions
° File locking by the RPG/400 program
° Record locking by the RPG/400 program
° Unblocking and blocking records to improve performance
° Sharing an open data path
° General information about the use of externally described files and how this external description can be changed in the RPG/400 program
° Program-described files
° RPG/400 functions that relate specifically to an RPG/400 PRINTER device, SEQ device, and SPECIAL device.
On the AS/400 system, files are made up of members. These files are organized into libraries. The convention for naming files is library-name/file-name.
Subtopics:
- 5.1 Device Independence/Device Dependence
- 5.2 Spooling
- 5.3 Externally Described and Program-Described Files
- 5.4 Level Checking
- 5.5 File Locking by an RPG/400 Program
- 5.6 Record Locking by an RPG/400 Program
- 5.7 Unblocking Input Records and Blocking Output Records
- 5.8 Sharing an Open Data Path
- 5.9 Using the Control Language Command RCLRSC
- 5.10 Specifications for Externally Described Files
- 5.11 Program-Described Files
- 5.12 Printer Files
- 5.13 Sequential File
- 5.14 Special File
5.1 Device Independence/Device Dependence
The key element for all input/output operations is the file. All files used on the system are defined to the OS/400 system. The OS/400 system maintains a description of each file that is accessed by a program when it uses the file.
The OS/400 file descriptions are kept online and serve as the connecting link between a program and the device used for I/O. The data is read from or written to the device when the file is used for processing. In some instances, this type of I/O control allows you to change the type of file (and, in some cases, change the device) used in a program without changing the program.
On the AS/400 system, the file name specified in positions 7 through 14 of the file description specification is used to point to the file, rather than the device name specified in positions 40 through 46. The file name points to the OS/400 file description that contains the specifications for the actual device: The RPG/400 device name in positions 40 through 46 defines the RPG/400 functions that can be processed on the associated file. At compilation time, certain RPG/400 functions are valid only for a specific RPG/400 device name. In this respect, the RPG/400 function is device dependent. One example of device dependency is that the EXFMT operation code is valid only for a WORKSTN device. For another example, assume that the file name FILEY is specified in the RPG/400 program with the SEQ device. The device SEQ is an independent device type. When the program is run, the actual I/O device is specified in the description of FILEY. OS/400 commands can be used to override a parameter in the specified file description or to redirect a file at compilation time or run time. File redirection allows you to specify one file at compilation time and another file at run time:
In the preceding example, the CL command OVRDBF (Override With Database File) allows the program to run with an entirely different device file than was specified at compilation time.
Not all file redirections or overrides are valid. At run time, checking ensures that the specifications within the RPG/400 program are valid for the file being processed. The OS/400 system allows some file redirections even if device specifics are contained in the program. For example, if the RPG/400 device name is PRINTER, and the actual file the program connects to is not a printer, the OS/400 system ignores the RPG/400 print spacing and skipping specifications. There are other file redirections that the OS/400 system does not allow and that cause the program to end. For example, if the RPG/400 device name is WORKSTN and the EXFMT operation is specified in the program, the program is stopped if the actual file the program connects to is not a display or ICF file.
See the Data Management Guide for more detailed information on valid file redirections and file overrides.
5.2 Spooling
Spooling is a system function that puts data into a storage area to wait for processing. The AS/400 system provides for the use of input and output spooling functions. The RPG/400 program is not aware that spooling is being used. The actual physical device from which a file is read or to which a file is written is determined by the spool reader or the spool writer. For more detailed information on spooling, see the Data Management Guide.
Subtopics:
5.2.1 Output Spool
Output spooling is valid for batch or interactive jobs. The description of the file that is specified in the RPG/400 program by the file name contains the specification for spooling. example: QPRINT File override commands can be used at run time to override the spooling options specified in the file description, such as the number of copies to be printed. In addition, AS/400 spooling support allows you to redirect a file after the program has run. You can direct the same printed output to a different device such as a diskette.
5.3 Externally Described and Program-Described Files
All files on the AS/400 system are defined to the OS/400 system. However, the extent to which files can be defined differs:
° An externally described file is described to the OS/400 system at the field level. The description includes information about where the data comes from, such as the database or a specific device, and a description of each field and its attributes.
° A program-described file is described at the field level within the RPG/400 program on input/output specifications. The description of the file to the OS/400 system includes information about where the data comes from and the length of the records in the file.
An externally described file does not have to be redefined in an RPG/400 program on input/output specifications. In a program-described file, the fields and their attributes must be described on input/output specifications.
Externally described files offer the following advantages:
° Less coding in RPG/400 programs. If the same file is used by many programs, the fields can be defined once to the OS/400 system and used by all the programs. This practice eliminates the need to code input and output specifications for RPG/400 programs that use externally described files.
° Less maintenance activity when the file's record format is changed. You can often update programs by changing the file's record format and then recompiling the programs that use the files without changing any coding in the program.
° Improved documentation because programs using the same files use consistent record-format and field names.
If an externally described file (identified by an E in position 19) is specified for the devices SEQ or SPECIAL, the RPG/400 program uses the field descriptions for the file, but the interface to the OS/400 system is as though the file were a program-described file. Externally described files cannot specify device-dependent functions such as forms control.
You can choose to use an externally described file within the program by specifying the file as program-described (F in position 19 of the file description specifications). The compiler does not copy in the external field-level description of the file at compilation time. This approach is used in conversion where existing programs use program-described files and new programs use externally described files to refer to the same file.
Figure 35 shows some typical relationships between an RPG/400 program and files on the AS/400 system.
OS/400 OS/400
______________ ______________
|Field-Level | |Record-Level | OS/400
|Description of| |Description of| ______________
|a File | |a File | |Field-Level |
|______________| |______________| |Description of|
| | | | |a File |
_____| | | |_____ |______________|
| | | | |
1 RPG 2 RPG 3 RPG 4 RPG
____________________ ____________________ ____________________ ____________________
|Externally | | Program-Described | |Program-Described | |Externally |
|Described File | | File (F in position| |File (F in position | |Described File |
|(E in position 19) | | 19) _ The compiler | |19) | |(E in position 19) |
| | | does not copy in | | | | |
| | | field-level | | | | |
| | | description | | | | |
|____________________| |____________________| |____________________| |____________________|
|
1 The RPG/400 program uses the field-level description of a file that is defined to the OS/400 system. An externally described file is identified by an E in position 19 of the file description specifications. At compilation time, the compiler copies in the external field-level description.
2 An externally described file is used as a program-described file in the RPG/400 program. A program-described file is identified by an F in position 19 of the file description specifications. This entry tells the compiler not to copy in the external field-level descriptions. This file does not have to exist at compilation time.
3 A file is described only to the record level to the OS/400 system. The fields in the record are described within the RPG/400 program; therefore, position 19 of the file description specifications must contain an F. This file does not have to exist at compilation time.
4 A file name can be specified for compilation time, and a different file name can be specified for run time. The E in position 19 of the file description specifications indicates that the external description of the file is to be copied in at compilation time. At run time, a file override command can be used so that a different file is accessed by the program. To override a file at run time, you must make sure that record names in both files are the same. The RPG/400 program uses the record-format name on the input/output operations, such as a READ operation where it specifies what record type is expected.
The following example shows the use of a file override at compilation time. Assume that you want to use an externally described file for a TAPE device that the system does not support. You must:
° Define a physical file named FMT1 with one record format that contains the description of each field in the record format. The record format is defined on the data description specifications (DDS). For a tape device, the externally described file should contain only one record format.
° Create the file named FMT1 with a Create Physical File CL command.
° Specify the file name of QTAPE (which is the IBM-supplied device file name for magnetic tape devices) in the RPG/400 program. This identifies the file as externally described (indicated by an E in position 19 of the file description specifications), and specifies the device name SEQ in positions 40 through 46.
° Use an override command-OVRDBF FILE(QTAPE) TOFILE(FMT1)-at compilation time to override the QTAPE file name and use the FMT1 file name. This command causes the compiler to copy in the external description of the FMT1 file, which describes the record format to the RPG/400 compiler.
° Create the RPG/400 program using the CRTRPGPGM command.
° Call the program at run time. The override to file FMT1 should not be in effect while the program is running. Use the CL command DLTOVR (Delete Override).
Note: You may need to use the CL command OVRTAPF before you call the program to provide information necessary for opening the tape file.
5.4 Level Checking
Because RPG/400 programs are dependent on receiving an externally described file whose format agrees with what was copied into the program at compilation time, the system provides a level-check function that ensures that the format is the same.
The RPG/400 program always provides the information required by level checking when an externally described DISK, WORKSTN, or PRINTER file is used. The level-check function can be requested on the create, change, and override file commands. The default on the create file command is to request level checking. Level checking occurs on a record-format basis when the file is opened unless you specify LVLCHK(*NO) when you issue an override command or create a file. If the level-check values do not match, the program is notified of the error. The RPG/400 program then handles the OPEN error as described in "Exception/Error Handling" in topic 4.8.
The RPG/400 program does not provide level checking for program-described files or for files using the devices SEQ or SPECIAL.
For more information on how to specify level checking, see the Data Management Guide.
5.5 File Locking by an RPG/400 Program
The OS/400 system allows a lock state (exclusive, exclusive allow read, shared for update, shared no update, or shared for read) to be placed on a file used during a job. Programs within a job are not affected by file lock states. A file lock state applies only when a program in another job tries to use the file concurrently. The file lock state can be allocated with the CL command ALCOBJ (Allocate Object). For more information on allocating resources and lock states, see the Data Management Guide.
The OS/400 system places the following lock states on database files when it opens the files:
______________ __________________________________________ | File Type | Lock State | |______________|__________________________________________| | Input | Shared for read | |______________|__________________________________________| | Update | Shared for update | |______________|__________________________________________| | Add | Shared for update | |______________|__________________________________________| | Output | Shared for update | |______________|__________________________________________|
The shared-for-read lock state allows another user to open the file with a lock state of shared for read, shared for update, shared no update, or exclusive allow read, but the user cannot specify the exclusive use of the file. The shared-for-update lock state allows another user to open the file with shared-for-read or shared-for-update lock state.
The RPG/400 program places an exclusive-allow-read lock state on device files. Another user can open the file with a shared-for-read lock state.
The lock state placed on the file by the RPG/400 program can be changed if you use the Allocate Object command.
5.6 Record Locking by an RPG/400 Program
When a record is read by a program, it is read in one of two modes: input or update. If a program reads a record for update, a lock is placed on that record. Another program cannot read the same record for update until the first program releases that lock. If a program reads a record for input, no lock is placed on the record. A record that is locked by one program can be read for input by another program.
In RPG/400 programs, you use an update file to read records for update. A record read from a file with a type other than update can be read for inquiry only. By default, any record is read from an update file will be read for update. For update files, you can specify that a record be read for input by using one of the input operations CHAIN, READ, READE, READP, or REDPE and specifying an N in column 53 of the calculation specification.
When a record is locked by an RPG/400 program, that lock remains until one of the following occurs:
° the record is updated.
° the record is deleted.
° another record is read from the file (either for inquiry or update).
° a SETLL or SETGT operation is performed against the file
° an UNLCK operation is performed against the file.
° an output operation defined by an output specification with no field names included is performed against the file.
Note: An output operation that adds a record to a file does not result in a record lock being released.
If your program reads a record for update and that record is locked through another program in your job or through another job, your read operation will wait until the record is unlocked. If the wait time exceeds that specified on the WAITRCD parameter of the file, an exception occurs. If the default error handler is given control when a record lock timeout occurs, an RPG1218 error message will be issued. One of the options listed for this message is to retry the operation on which the timeout occurred. For programs compiled for version 2 (or higher) this will cause the operation on which the timeout occurred to be re-issued, allowing the program to continue essentially as if the record lock timeout had not occurred. Note that if the file has an INFSR specified in which an I/O operation is performed on the file before the default error handler is given control, unexpected results can occur if the input operation that is retried is a sequential operation, since the file cursor may have been modified.
With programs compiled using version 1 of the RPG/400 compiler, the retry option is still displayed, but it is not valid. If a retry is requested for a version 1 program, an additional error message (RPG1918) is issued indicating that a retry is not valid for programs compiled using version 1. In all cases, if control is returned to the program by specifying a return to *GETIN, the RPG STATUS value is set to 1218. If a retry is specified and the subsequent read operation is successful, the STATUS returns as if the record lock and subsequent retry did not occur.
If no changes are required to a locked record, you can release it from its locked state using the UNLCK operation or by processing output operations defined by output specifications with no field names included. These output operations can be processed by EXCPT output, detail output, or total output.
(There are exceptions to these rules when operating under commitment control. See Chapter 6, "Commitment Control" in topic 6.0 for more information.)
5.7 Unblocking Input Records and Blocking Output Records
The RPG/400 compiler unblocks input records and blocks output records to improve run-time performance in SEQ or DISK files if:° The file is an output-only file (O is specified in position 15 of the file description specifications) and contains only one record format if the file is externally described.
° The file is a combined table file. (C is specified in position 15, and T in position 16 of the file description specifications.)
° The file is an input-only file. (I is specified in position 15 of the file description specifications.) It contains only one record format if the file is externally described, and uses only the OPEN, CLOSE, FEOD, and READ operation codes.
The RPG/400 compiler generates object program code to block and unblock records for all SEQ or DISK files that satisfy these conditions. Certain OS/400 system restrictions may prevent blocking and unblocking. In those cases, performance is not improved and the input/output feedback area is updated for each input/output operation.
The contents of positions 60 through 65 of the RECNO option in the file description specifications continuation line may not be valid when the RPG/400 compiler blocks and unblocks records.
The input/output and device-dependent sections of the file information data structure are not updated after each read or write for files in which the records are blocked and unblocked by the RPG/400 compiler. The feedback area is updated each time a block of records is transferred. (See the RPG/400 Reference for more information.)
5.8 Sharing an Open Data Path
An open data path is the path through which all input and output operations for a file are defined. Usually a separate open data path is defined each time a file is opened. If you specify SHARE(*YES) for the file creation or on an override, the first program's open data path for the file is shared by subsequent programs that open the file concurrently. The position of the current record is kept in the open data path for all programs using the file. If you read a record in one program and then read a record in a called program, the record retrieved by the second read depends on whether the open data path is shared. If the open data path is shared, the position of the current record in the called program is determined by the current position in the calling program. If the open data path is not shared, each program has an independent position for the current record.
If your program holds a record lock in a shared file and then calls a second program that reads the shared file for update, you can release the first program's lock by performing a READ operation on the update file by the second program, or by using the UNLCK or the read-no-lock operations.
Sharing an open data path improves performance because the OS/400 system does not have to create a new open data path. However, sharing an open data path can cause problems. For example, an error is signaled in the following cases:
° If a program sharing an open data path attempts file operations other than those specified by the first open (for example, attempting input operations although the first open specified only output operations)
° If a program sharing an open data path for an externally described file tries to use a record format that the first program ignored
° If a program sharing an open data path for a program described file specifies a record length that exceeds the length established by the first open.
When several files in one RPG/400 program are overridden to one shared file at run time, the file opening order is important. In order to control the file opening order, you should use a programmer-controlled open or use a CL program to open the files before calling the RPG/400 program.
If a program shares the open data path for a primary or secondary file, the program must process the detail calculations for the record being processed before calling another program that shares that open data path. Otherwise, if lookahead is used or if the call is at total time, sharing the open data path for a primary or secondary file may cause the called program to read data from the wrong record in the file.
You must make sure that when the shared file is opened for the first time in a job, all of the open options that are required for subsequent opens of the file are specified. If the open options specified for subsequent opens of a shared file are not included in those specified for the first open of a shared file, an error message is sent to the program.
Table 3 details the system open options allowed for each of the open options you can specify.
________________________________________________________________________ | Table 3. System Open Options Allowed with User Open Options | |____________________________________ ___________________________________| | RPG User | System | | Open Options | Open Options | |____________________________________|___________________________________| | INPUT | INPUT | |____________________________________|___________________________________| | OUTPUT | OUTPUT (program created file) | |____________________________________|___________________________________| | UPDATE | INPUT, UPDATE | |____________________________________|___________________________________| | DELETE | DELETE | |____________________________________|___________________________________| | ADD | OUTPUT (existing file) | |____________________________________|___________________________________|
For additional information about sharing an open data path, see the Database Guide.
5.9 Using the Control Language Command RCLRSC
The Reclaim Resources (RCLRSC) CL command is designed for use in the controlling program of an application. It frees the static storage and closes any files that were left open by other programs in the application that are no longer active. This command will not always free program static storage or close all files. Using RCLRSC may close some files but keep their static storage. When this occurs, static storage indicates that these files are open, but their open data path (ODP) does not exist. When I/O is attempted with these files, an error occurs. For additional information, refer to the CL Reference.
5.10 Specifications for Externally Described Files
You can use the DDS to describe files to the OS/400 system. Each record type in an externally described file is identified by a unique record-format name.
The following text describes the special entries that you can use on the file description, input, and output specifications for externally described files. Remember that input and output specifications for externally described files are optional.
Subtopics:
- 5.10.1 File Description Specifications
- 5.10.2 Renaming Record-Format Names
- 5.10.3 Ignoring Record Formats
- 5.10.4 Floating-Point Fields
- 5.10.5 Overriding or Adding RPG/400 Functions to an External Description
- 5.10.6 Output Specifications
5.10.1 File Description Specifications
An E entry in position 19 of the file description specifications identifies an externally described file. The E entry indicates to the compiler that it is to retrieve the external description of the file from the system when the program is compiled.
The information in this external description includes:
° File information, such as file type, and file attributes, such as access method (by key or relative record number)
° Record-format description, which includes the record format name and field descriptions (names, locations, and attributes).
The information the RPG/400 compiler retrieves from the external description is printed on the compiler listing when the program is compiled.
5.10.2 Renaming Record-Format Names
Many of the functions that you can specify for externally described files (such as the CHAIN operation) operate on either a file name or a record-format name. Consequently, each file and record-format name in the program must be a unique symbolic name.
To rename a record-format name, use the RENAME option on the file description specifications continuation line for the externally described file as shown in Figure 36. You cannot specify the RENAME option on the main file description specifications line. The RENAME option is generally used if the program contains two identical record-format names or if the record-format name exceeds eight characters, which is the maximum length allowed in an RPG/400 program.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FITMMSTL IP E K DISK F ITEMFORMAT KRENAMEMSTITM F*
Figure 36. RENAME Option for Record Format Names in an Externally Described File
To rename a record format in an externally described file, use a file description specifications continuation line to specify the RENAME option. (The RENAME option cannot be specified on the main file description line because the external name positions overlap some of the entries on the main file description line.) On the continuation line, enter the external name of the record format, left-adjusted, in positions 19 through 28. Specify K in position 53, RENAME in positions 54 through 59, and the program name for the record format, left-adjusted, in positions 60 through 67. The remaining positions of the continuation line must be blank.
In this example, the record format ITEMFORMAT in the externally described file ITMMSTL is renamed MSTITM for use in this program.
5.10.3 Ignoring Record Formats
If a record format in an externally described file is not to be used in a program, you can use the IGNORE option to make the program run as if the record format did not exist in the file. For logical files, this means that all data associated with that format is inaccessible to the program. Use the IGNORE option on a file description specifications continuation line for the externally described file as shown in Figure 37.
The file must have more than one record format, and not all of them can be ignored; at least one must remain. Except for that requirement, any number of record formats can be ignored for a file.
If a record-format name is specified on a continuation line for the IGNORE option, it cannot be specified on a continuation line for any other option (SFILE, RENAME, or PLIST), or on a continuation line for another IGNORE.
Ignored record-format names appear on the cross-reference listing, but they are flagged as ignored.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FITMMSTL UF E K DISK F NOTUSED KIGNORE F*
Figure 37. IGNORE Option for Record Formats in an Externally Described File
To ignore a record format from an externally described file, use a file description specifications continuation line to specify the IGNORE option. (The IGNORE option cannot be specified on the main file description line because the external name positions overlap some of the entries on the main file description line.) On the continuation line, enter the external name of the record format, left-adjusted, in positions 19 through 28, K in position 53, and IGNORE in positions 54 through 59. The remaining positions of the continuation line must be blank.
In this example, the record format NOTUSED in the externally described file ITMMSTL is ignored.
5.10.4 Floating-Point Fields
The RPG/400 program does not support the use of floating-point fields. If you process an externally described file with floating-point fields, the following happens:
° You cannot access the floating-point fields.
° When you create a new record, the floating-point fields in the record have the value zero.
° When you update existing records, the floating-point fields are unchanged.
° If you attempt to use a floating-point field as a key field, your program receives a compile-time error.
5.10.5 Overriding or Adding RPG/400 Functions to an External Description
You can use the input specifications to override certain information in the external description of an input file or to add RPG/400 functions to the external description. On the input specifications, you can:
° Assign record identifying indicators to record formats as shown in Figure 38.
° Rename a field as shown in Figure 38.
° Assign control level indicators to fields as shown in Figure 38.
° Assign match-field values to fields for matching record processing as shown in Figure 39.
° Assign field indicators as shown in Figure 39.
You cannot use the input specifications to override field locations in an externally described file. The fields in an externally described file are placed in the records in the order in which they are listed in the data description specifications. Also, device-dependent functions such as forms control, are not valid in an RPG/400 program for externally described files.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* IRcdname+....In.....................................................* IMSTR1IEM 01 1 I..............Ext-field+......................Field+L1M1..PlMnZr...* I ITEMNUMB 2 ITEM L1 3 I* IMSTRWHSE 02 I ITEMNUMB ITEM L1 I* I*
Figure 38. Overriding and Adding RPG/400 Functions to an External Description
1 To assign a record identifying indicator to a record in an externally described file, specify the record-format name in positions 7 through 14 of the input specifications and assign a valid record identifying indicator in positions 19 and 20. A typical use of input specifications with externally described files is to assign record identifying indicators.
In this example, record identifying indicator 01 is assigned to the record MSTRITEM and indicator 02 to the record MSTRWHSE.
2 To rename a field in an externally described record, specify the external name of the field, left-adjusted, in positions 21 through 30 of the field-description line. In positions 53 through 58, specify the name that is to be used in the program.
In this example, the field ITEMNUMB in both records is renamed ITEM for this program because ITEMNUMB exceeds the maximum length of six characters that is allowed for an RPG/400 field name.
3 To assign a control-level indicator to a field in an externally described record, specify the name of the field in positions 53 through 58 and specify a control level indicator in positions 59 and 60.
In this example, the ITEM field in both records MSTRITEM and MSTRWHSE is specified to be the L1 control field.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* IFilenameSqNORiPos1NCCPos2NCCPos3NCC................................* IMSTREC 01 1 I....................................PFromTo++DField+L1M1FrPlMnZr...* I CUSTNO M1 1 I* IWKREC 02 I CUSTNO M1 I BALDUE 98 2 I*
Figure 39. Adding RPG/400 Functions to an External Description
1 To assign a match value to a field in an externally described record, specify the record-format name in positions 7 through 14 of the record identification line. On the field-description line specify the name of the field in positions 53 through 58 and assign a match-level value in positions 61 and 62.
In this example, the CUSTNO field in both records MSTREC and WKREC is assigned the match-level value M1.
2 To assign a field indicator to a field in an externally described record, specify the record-format name in positions 7 through 14 of the record identification line. On the field-description line, specify the field name in positions 53 through 58, and specify an indicator in positions 65 through 70.
In this example, the field BALDUE in the record WKREC is tested for zero when it is read into the program. If the field's value is zero, indicator 98 is set on.
5.10.6 Output Specifications
Output specifications are optional for an externally described file. The RPG/400 program supports file operation codes such as WRITE and UPDAT that use the external record-format description to describe the output record without requiring output specifications for the externally described file.
You can use output specification to control when the data is to be written, or to specify selective fields that are to be written. The valid entries for the field-description line for an externally described file are output indicators (positions 23 through 31), field name (positions 32 through 37), and blank after (position 39). Edit words and edit codes for fields written to an externally described file are specified in the DDS for the file. Device-dependent functions such as fetch overflow (position 16) or space/skip (positions 17-22) are not valid in an RPG/400 program for externally described files. The overflow indicator is not valid for externally described files either. For a description of how to specify editing in the DDS, see the DDS Reference.
If output specifications are used for an externally described file, the record-format name is specified in positions 7 through 14 instead of the file name.
If all the fields in an externally described file are to be placed in the output record, enter *ALL in positions 32 through 37 of the field-description line. If *ALL is specified, you cannot specify other field description lines for that record.
If you want to place only certain fields in the output record, enter the field name in positions 32 through 37. The field names you specify in these positions must be the field names defined in the external record description, unless the field was renamed on the input specifications. See Figure 40.
You should know about these considerations for using the output specifications for an externally described file:
° In the output of an update record, only those fields specified in the output field specifications and meeting the conditions specified by the output indicators are placed in the output record to be rewritten. Fields not specified in the output specifications are rewritten using the values that were read. This technique offers a good method of control as opposed to the UPDAT operation code that updates all fields.
° In the creation of a new record, the fields specified in the output field specifications are placed in the record. Fields not specified in the output field specifications or not meeting the conditions specified by the output indicators are written as zeros or blanks depending on the data format specified in the external description.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* OName++++DFBASbSaN01N02N03Excnam....................................* OITMREC D 20 O................N01N02N03Field+YBEnd+PConstant/editword+++++++++...* O *ALL 1 O* O* OSLSREC D 30 O SLSNAM 2 O COMRAT O 15 BONUS O* O*
Figure 40. Output Specifications for an Externally Described File
1 For an update file, all fields in the record are written to the externally described record ITMREC using the current values in the program for all fields in the record.
For the creation of a new record, all fields in the record are written to the externally described record ITMREC using the current values in the program for the fields in the record.
2 To update a record, the fields SLSNAM and COMRAT are written to the externally described record SLSREC when indicator 30 is on. The field BONUS is written to the SLSREC record when indicators 30 and 15 are on. All other fields in the record are written with the values that were read.
To create a new record, the fields SLSNAM and COMRAT are written to the externally described record SLSREC when indicator 30 is on. The field BONUS is written when indicators 30 and 15 are on. All other fields in the record are written as zeros or blanks, depending on whether the field is numeric or character.
5.11 Program-Described Files
Program-described files are files whose records and fields are described on input/output specifications in the program that uses the file.
Figure 41 shows how to specify sequence checking when your input data must contain exactly one record of the first type (01 in positions 15 and 16), followed by at least one record of another type (02 through 04 in positions 15 and 16) in each group of records read. When the specifications shown in Figure 41 are used and two consecutive records of the first type are read, a run-time error occurs.
If each group of input records must contain exactly one record of a particular type, but that record need not be followed by any records of other types, specify no sequence checking (alphabetic entry in positions 15 and 16).
Write operations to a program-described file require a data structure name in the result field.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* IFilenameSqNORiPos1NCCPos2NCCPos3NCC................................* IINPUT 011 10 1 CA I....................................PFromTo++DField+L1M1FrPlMnZr...* I 2 60TYPE I 02NO20 1 CB I 2 11 KEY I 03NO30 1 CC I 2 21 NAME I 04NO40 1 CD I 2 6 NUMBER I*
Figure 41. Input Specifications for Sequence Checking
5.12 Printer Files
The PRINTER file allows you to print the output file. A maximum of eight printer files is allowed per program. You must assign PRINTER as the device name for the file, and each file must have a unique file name. You can use the CL command CRTPRTF (Create Print File) to create a printer file (see the CL Reference for further information on the CRTPRTF command); or you can also use the IBM-supplied file names. See the Data Management Guide for more information on these file names.
The file operation codes that are valid for a PRINTER file are WRITE, OPEN, CLOSE, and FEOD. For a complete description of these operation codes, see the RPG/400 Reference.
PRINTER files can be either externally described or program described. Overflow indicators OA-OG and OV, fetch overflow, space/skip entries, and the PRTCTL option are not allowed for an externally described PRINTER file. See the RPG/400 Reference for the valid output specification entries for an externally described file. See the DDS Reference for information on the DDS for externally described printer files.
For an externally described PRINTER file, you can specify the DDS keyword INDARA. If you try to use this keyword for a program-described PRINTER file, you get a run-time error.
Subtopics:
- 5.12.1 Page Overflow
- 5.12.2 Overflow Indicators
- 5.12.3 Fetch-Overflow Logic
- 5.12.4 PRTCTL (Printer Control) Option
5.12.1 Page Overflow
An important consideration when you use a PRINTER file is page overflow. For an externally described PRINTER file, you are responsible for handling page overflow. Do one of the following:
° Count the number of output lines per page.
° Check for a file exception/error by specifying an indicator in positions 56 and 57 of the calculation specifications that specify the output operation, or by specifying an INFSR that can handle the error. The INFDS has detailed information on the file exception/error. See "Exception/Error Handling" in topic 4.8 for further information on exception and error handling.
° Specify an indicator 01 through 99 as the overflow indicator in positions 33 and 34 of the file description specifications.
° Check INFDS for line number and page overflow. Refer to the RPG/400 Reference for more information.
For either a program-described or an externally described file, you can specify an indicator 01 through 99 in positions 33 and 34 of the file description specifications. This indicator is set on when a line is printed on the overflow line, or the overflow line is reached or passed during a space or skip operation. Use the indicator to condition your response to the overflow condition. The indicator does not condition the RPG/400 overflow logic as an overflow indicator (OA through OG, OV) does. You are responsible for setting the indicator off.
For both program-described and externally described files, the line number and page number are available in the file's INFDS. To access this information, specify an INFDS for the file using a file continuation specification. On the specification, define the line number in positions 367-368 and define the page number in positions 369-372 of the data structure. Both the line number and the page number fields must be defined as binary with no decimal positions. Because the INFDS will be updated after every output operation to the printer file, these fields can be used to determine the current line and page number without having line-count logic in the program.
For a program-described PRINTER file, the following sections on overflow indicators and fetch overflow logic apply.
5.12.2 Overflow Indicators
An overflow indicator (OA through OG, OV) is set on when the last line on a page has been printed or passed. An overflow indicator can be used to specify the lines to be printed on the next page. Overflow indicators can be specified only for program-described PRINTER files and are used primarily to condition the printing of heading lines. An overflow indicator is defined in positions 33 and 34 of the file description specifications and can be used to condition operations in the calculation specifications (positions 9 through 17) and output specifications (positions 23 through 31). If an overflow indicator is not specified, the RPG/400 compiler assigns the first unused overflow indicator to the PRINTER file. Overflow indicators can also be specified as resulting indicators on the calculation specifications (positions 54 through 59).
The RPG/400 compiler sets on an overflow indicator only the first time an overflow condition occurs on a page. An overflow condition exists whenever one of the following occurs:
° A line is printed past the overflow line. ° The overflow line is passed during a space operation. ° The overflow line is passed during a skip operation.
Table 4 shows the results of the presence or absence of an overflow indicator on the file description and output specifications.
The following considerations apply to overflow indicators used on the output specifications:
° Spacing past the overflow line sets the overflow indicator on.
° Skipping past the overflow line to any line on the same page sets the overflow indicator on.
° Skipping past the overflow line to any line on the new page does not set the overflow indicator on unless a skip-to is specified past the specified overflow line.
° A skip to a new page specified on a line not conditioned by an overflow indicator sets the overflow indicator off after the forms advance to a new page.
° If you specify a skip to a new line and the printer is currently on that line, a skip does not occur. The overflow indicator is set to off, unless the line is past the overflow line.
° When an OR line is specified for an output print record, the space and skip entries of the preceding line are used. If they differ from the preceding line, enter space and skip entries on the OR line.
° Control level indicators can be used with an overflow indicator so that each page contains information from only one control group. See Figure 42.
° For conditioning an overflow line, an overflow indicator can appear in either an AND or an OR relationship. For an AND relationship, the overflow indicator must appear on the main specification line for that line to be considered an overflow line. For an OR relationship, the overflow indicator can be specified on either the main specification line or the OR line. Only one overflow indicator can be associated with one group of output indicators. For an OR relationship, only the conditioning indicators on the specification line where an overflow indicator is specified is used for the conditioning of the overflow line.
° If an overflow indicator is used on an AND line, the line is not an overflow line. In this case, the overflow indicator is treated like any other output indicator.
° When the overflow indicator is used in an AND relationship with a record identifying indicator, unusual results are often obtained because the record type might not be the one read when overflow occurred. Therefore, the record identifying indicator is not on, and all lines conditioned by both overflow and record identifying indicators do not print.
° An overflow indicator conditions an exception line (E in position 15), and conditions fields within the exception record.
________________________________________________________________________ | Table 4. Results of the Presence or Absence of an Overflow Indicator | |_______________ _______________ ________________________________________| | File | | | | Description | Output | | | Specifications| Specifications| Action | | Positions | Positions | | | 33-34 | 23-31 | | |_______________|_______________|________________________________________| | No entry | No entry | First unused overflow indicator used | | | | to condition skip to next page at | | | | overflow. | |_______________|_______________|________________________________________| | No entry | Entry | Error at compile time; overflow | | | | indicator dropped from output | | | | specifications. First unused overflow | | | | indicator used to condition skip to | | | | next page at overflow. | |_______________|_______________|________________________________________| | Entry | No entry | Continuous printing; no overflow | | | | recognized. | |_______________|_______________|________________________________________| | Entry | Entry | Processes normal overflow. | |_______________|_______________|________________________________________|
The first part of the following figure is an example of the coding necessary for printing headings on every page: first page, every overflow page, and each new page to be started because of a change in control fields (L2 is on). The first line allows the headings to be printed at the top of a new page (skip to 06) only when an overflow occurs (OA is on and L2 is not on).
The second line allows printing of headings on the new page only at the beginning of a new control group (L2 is on). This way, duplicate headings caused by both L2 and OA being on at the same time do not occur. The second line allows headings to be printed on the first page after the first record is read because the first record always causes a control break (L2 turns on) if control fields are specified on the record.
The second part of the figure is the necessary coding for the printing of certain fields on every page; a skip to 06 is done either on an overflow condition or on a change in control level (L2). The NL2 indicator prevents the line from printing and skipping twice in the same cycle.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* OName++++DFBASbSaN01N02N03Excnam....................................* OPRINT H 306 OANL2 O................N01N02N03Field+YBEnd+PConstant/editword+++++++++...* O OR L2 O 8 'DATE' O 18 'ACCOUNT' O 28 'N A M E' O 46 'BALANCE' O*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* OName++++DFBASbSaN01N02N03Excnam....................................* OPRINT D 306 OANL2 O OR L2 O................N01N02N03Field+YBEnd+PConstant/editword+++++++++...* O ACCT 8 O*
Figure 42. Using Control Level Indicators with an Overflow Indicator
5.12.3 Fetch-Overflow Logic
When there is not enough space left on a page to print the remaining detail, total, exception, and heading lines conditioned by the overflow indicator, the fetch overflow routine can be called. This routine causes an overflow. To determine when to fetch the overflow routine, study all possible overflow situations. By counting lines and spaces, you can calculate what happens if overflow occurs on each detail, total, and exception line.
The fetch-overflow routine allows you to alter the basic RPG/400 overflow logic to prevent printing over the perforation and to let you use as much of the page as possible. During the regular program cycle, the RPG/400 compiler checks only once, immediately after total output, to see if the overflow indicator is on. When the fetch overflow function is specified, the RPG/400 compiler checks overflow on each line for which fetch overflow is specified. See Figure 43.
Specify fetch overflow with an F in position 16 of the output specifications on any detail, total, or exception lines for a PRINTER file. The fetch overflow routine does not automatically cause forms to advance to the next page.
During output, the conditioning indicators on an output line are tested to determine if the line is to be written. If the line is to be written and an F is specified in position 16, the RPG/400 compiler tests to determine if the overflow indicator is on. If the overflow indicator is on, the overflow routine is fetched and the following operations occur:
1. Only the overflow lines for the file with the fetch specified are checked for output.
2. All total lines conditioned by the overflow indicator are written.
3. Forms advance to a new page when a skip to a line number less than the line number the printer is currently on is specified in a line conditioned by an overflow indicator.
4. Heading, detail, and exception lines conditioned by the overflow indicator are written.
5. The line that fetched the overflow routine is written.
6. Any detail and total lines left to be written for that program cycle are written.
Position 16 of each OR line must contain an F if the overflow routine is to be used for each record in the OR relationship. Fetch overflow cannot be used if an overflow indicator is specified in positions 23 through 31 of the same specification line. If this is the case, the overflow routine is not fetched.
Figure 44 shows the use of fetch overflow. A When fetch overflow is not specified, the overflow lines print after total output. No matter when overflow occurs (OA is on), the overflow indicator OA remains on through overflow output time and is set off after heading and detail output time.
B When fetch overflow is specified, the overflow lines are written before the output line for which fetch overflow was specified, if the overflow indicator OA is on. When OA is set on, it remains on until after heading and detail output time. The overflow lines are not written a second time at overflow output time unless overflow is sensed again since the last time the overflow lines were written.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* OName++++DFBASbSaN01N02N03Excnam....................................* OPRINTER H 305 OA O................N01N02N03Field+YBEnd+PConstant/editword+++++++++...* O 15 'EMPLOYEE TOTAL' O TF 1 L1 O EMPLTOT 25 O T 1 L1 O EMPLTOT 35 O T 1 L1 O EMPLTOT 45 O TF 1 L1 O EMPLTOT 55 O T 1 L1 O EMPLTOT 65 O T 1 L1 O EMPLTOT 75 O T 1 L1 O*
Figure 44. Use of Fetch Overflow
The total lines with an F coded in position 16 can fetch the overflow routine. They only do so if overflow is sensed prior to the printing of one of these lines. Before fetch overflow is processed, a check is made to determine whether the overflow indicator is on. If it is on, the overflow routine is fetched, the heading line conditioned by the overflow indicator is printed, and the total operations are processed.
5.12.4 PRTCTL (Printer Control) Option
The PRTCTL (printer control) option allows you to change forms control information and to access the current line value within the program for a program-described PRINTER file.
Specify the PRTCTL option on a file description specifications continuation line for the PRINTER file with the following:
Note: If the file has a share ODP or user-controlled open, the line count value may be incorrect.
__________ _____________________________________________________________ | Position | Entry | |__________|_____________________________________________________________| | 6 | F | |__________|_____________________________________________________________| | 7-52 | Blank if the information is specified on a separate | | | continuation line | |__________|_____________________________________________________________| | 53 | K (indicates a continuation line) | |__________|_____________________________________________________________| | 54-59 | PRTCTL | |__________|_____________________________________________________________| | 60-65 | Name of the data structure used to contain the printer | | | control and line count information | |__________|_____________________________________________________________| | 66-74 | Blank if the information is specified on a separate | | | continuation line. | |__________|_____________________________________________________________|
The data structure specified in positions 60 through 65 of the file description specifications continuation line must be specified on the input specifications and must contain at least the following five subfields specified in the following order:
___________ ____________________________________________________________ | Data | | | Structure | Subfield | | Positions | Contents | |___________|____________________________________________________________| | 1 | A one-position character field that contains the | | | space-before value | |___________|____________________________________________________________| | 2 | A one-position character field that contains the | | | space-after value | |___________|____________________________________________________________| | 3-4 | A two-position character field that contains the | | | skip-before value | |___________|____________________________________________________________| | 5-6 | A two-position character field that contains the | | | skip-after value | |___________|____________________________________________________________| | 7-9 | A three-digit numeric field with zero decimal positions | | | that contains the current line count value. | |___________|____________________________________________________________|
The values contained in the first four subfields of the data structure are the same as those allowed in positions 17 through 22 (space and skip entries) of the output specifications. If the space/skip entries (positions 17 through 22) of the output specifications are blank, and if subfields 1 through 4 are also blank, the default is to space 1 after. If the PRTCTL option is specified, it is used only for the output records that have blanks in positions 17 through 22. You can control the space and skip value (subfields 1 through 4) for the PRINTER file by changing the values in these subfields while the program is running. See Figure 45.
Subfield 5 contains the current line count value. The RPG/400 compiler does not initialize subfield 5 until after the first output line is printed. The RPG/400 compiler then changes subfield 5 after each output operation to the file.
Figure 46 is a processing chart for PRINTER files.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FPRINT O F 132 PRINTER KPRTCTLLINE F*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* IDsname....NODsExt-file++.............OccrLen+......................* ILINE DS I..............Ext-field+............PFromTo++DField+...............* I 1 1 SPBEFR I 2 2 SPAFTR I 3 4 SKBEFR I 5 6 SKAFTR I 7 90CURLIN I*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C 01 CURLIN COMP 10 49 C 01 49 MOVE '3' SPAFTR C* C*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* OName++++DFBASbSaN01N02N03Excnam....................................* OPRINT 01 O................N01N02N03Field+YBEnd+PConstant/editword+++++++++...* O DATA 25 O*
Figure 45. Example of the PRTCTL Option
On the file description specifications, the PRTCTL option is specified for the PRINT file. The name of the associated data structure is LINE.
The LINE data structure is defined on the input specifications as having only those subfields that are predefined for the PRTCTL data structure. The first four subfields in positions 1 through 6 are used to supply space and skip information that is generally specified in positions 17 through 22 of the output specifications. The PRTCTL option allows you to change these specifications within the program.
In this example, the value in the SPAFTR subfield is changed to 3 when the value in the CURLIN (current line count value) subfield is equal to 10. (Assume that indicator 01 was set on as a record identifying indicator.) Valid File Operations:
1. WRITE, OPEN, CLOSE, FEOD
Note: Shaded positions must be blank. Positions without entries are program dependent.
5.13 Sequential File
A sequential (SEQ) device specification, positions 40 through 46 in the file description specification, indicates that the input or output is associated with a sequentially organized file. Refer to Figure 47. The actual device to be associated with the file while running the RPG/400 program can be specified by a OS/400 override command (see the CL Reference for further information), or by the file description that is pointed to by the file name.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FTIMECDS IP E DISK FPAYOTIMEO F 132 SEQ F* F*
Figure 47. SEQ Device
A SEQ device is specified for the PAYOTIME file. When the program is run, you can use a OS/400 override command to specify the actual device (such as printer, tape, or diskette) to be associated with the file while the program is running. For example, diskette can be specified for some program runs while printer can be specified for others. The file description, pointed to by the file name, can specify the actual device, in which case an override command need not be used.
Any sequentially organized file, such as diskette, tape, database, savefile, or printer, can be associated with the SEQ device. If SEQ is specified in an RPG/400 program, no device-dependent functions such as space/skip, or CHAIN can be specified.
Use the SEQ device specifications whenever you write to a tape file. To write variable-length records to a tape file, also use the RCDBLKFMT parameter of either the CL command CRTTAPF or OVRTAPF. (See the CL Reference.) When you use the RCDBLKFMT parameter, the length of each record that your program writes to the tape file is determined by the highest end position specified in positions 40 through 43 of the output specifications for that record. If you do not specify an end position, the RPG/400 compiler calculates the record length from the length of the fields in the record.
Read variable-length tape records as you would read records from any sequentially organized file. Be sure the record length specified on the file description specification accommodates the longest record in the file.
The following figure shows the operation codes allowed for a SEQ file.
______________________________________________________ | File Description | | Specifications Calculation Specifications | | Positions Positions | | 15 16 28-32 | |______________________________________________________| | I P/S CLOSE, FEOD | | | | I F READ, OPEN, CLOSE, | | FEOD | | | | O WRITE, OPEN, CLOSE, | | FEOD | | | |______________________________________________________|
Note: No print control specifications are allowed for a sequential file.
Figure 48. Valid File Operation Codes for a Sequential File
Figure 49 is a processing chart for SEQ files.
Figure 49. Processing Chart for SEQ Files
Valid File Operations:
1. CLOSE, FEOD
2. READ, OPEN, CLOSE, FEOD
3. OPEN, CLOSE, FEOD
4. WRITE, OPEN, CLOSE, FEOD
Note: Shaded positions must be blank. Positions without entries are program dependent.
5.14 Special File
6.0SPECIAL in positions 40 through 46 of the file description specifications allows you to specify an input and/or output device that is not directly supported by the RPG/400 functions. The input and output operations for the file are controlled by a user-written routine. Positions 54 through 59 of the file description specifications line that contains SPECIAL in positions 40 through 46 must contain the name of the user-written routine.
RPG/400 calls this user-written routine to open the file, read and write the records, and close the file. RPG/400 creates a parameter list for use by the user-written routine. The parameter list contains an option code parameter (option), a return status parameter (status), an error-found parameter (error), and a record area parameter (area). This parameter list is accessed by the RPG/400 program and by the user-written routine; it cannot be accessed by the RPG/400 program that contains the SPECIAL file.
The following describes the parameters in this RPG-created parameter list:
° Option: The option parameter is a one-position character field that indicates the action the user-written routine is to process. Depending on the operation being processed on the SPECIAL file (OPEN, CLOSE, READ, WRITE, DELET, UPDAT), one of the following values is passed to the user-written routine from RPG/400:
__________ _____________________________________________________________ | Value | | | Passed | Description | |__________|_____________________________________________________________| | O | Open the file. | |__________|_____________________________________________________________| | C | Close the file. | |__________|_____________________________________________________________| | R | Read a record and place it in the area defined by the area | | | parameter. | |__________|_____________________________________________________________| | W | The RPG/400 program has placed a record in the area defined | | | by the area parameter; the record is to be written out. | |__________|_____________________________________________________________| | D | Delete the record. | |__________|_____________________________________________________________| | U | The record is an update of the last record read. | |__________|_____________________________________________________________|
° Status: The status parameter is a one-position character field that indicates the status of the user-written routine when control is returned to the RPG/400 program. Status must contain one of the following return values when the user-written routine returns control to the RPG/400 program:
__________ _____________________________________________________________ | Return | | | Value | Description | |__________|_____________________________________________________________| | 0 | Normal return. The requested action was processed. | |__________|_____________________________________________________________| | 1 | The input file is at end of file, and no record has been | | | returned. If the file is an output file, this return value | | | is an error. | |__________|_____________________________________________________________| | 2 | The requested action was not processed; error condition | | | exists. | |__________|_____________________________________________________________|
° Error: The error parameter is a five-digit zoned numeric field with zero decimal positions. If the user-written routine detects an error, the error parameter contains an indication or value representing the type of error. The value is placed in the first five positions of location *RECORD in the INFDS when the status parameter contains 2.
° Area: The area parameter is a character field whose length is equal to the record length associated with the SPECIAL file. This field is used to pass the record to or receive the record from the RPG/400 program.
You can add additional parameters to the RPG-created parameter list. Specify PLIST in positions 54 through 59 and the name of the PLIST in positions 60 through 65 of a file description specifications continuation line for the SPECIAL file. See Figure 50. Then use the PLIST operation in the calculation specifications to define the additional parameters.
The user-written routine, the name that is specified in positions 54 through 59 of the file description specifications for the SPECIAL file, must contain an entry parameter list that includes both the RPG-created parameters and the user-specified parameters.
If the SPECIAL file is specified as a primary file, the user-specified parameters must be initialized before the first primary read. You can initialize these parameters with a factor 2 entry on the PARM statements or by the specification of a compile-time array or an array element as a parameter.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FEXCPTN 1 F SPECIAL USERIO F KPLIST SPCL F* F*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C SPCL PLIST C PARM FLD1 C PARM FLD2 C PARM FLD3 C* C*
Figure 50. SPECIAL Device
The file EXCPTN is assigned to the device SPECIAL. The I/O operations for the SPECIAL device are controlled by the user-written routine USERIO. The parameters specified for the programmer-defined PLIST SPCL are added to the end of the RPG-created parameter list for the SPECIAL device. The programmer-specified parameters can be accessed by the user RPG/400 program and the user-written routine; whereas the RPG-created parameter list can be accessed only by internal RPG/400 logic and the user-written routine.
Figure 51 shows the file operation codes that are valid for a SPECIAL file.
______________________________________________________ | File Description | | Specifications Calculation Specifications | | Positions Positions | | 15 16 28-32 | |______________________________________________________| | I P/S CLOSE, FEOD | | | | C P/S WRITE, CLOSE, FEOD | | | | U P/S UPDAT, DELET, CLOSE | | FEOD | | | | O WRITE, OPEN, CLOSE, | | FEOD | | | | I F READ, WRITE, OPEN, | | CLOSE, FEOD | | | | C F READ, WRITE, OPEN, | | CLOSE, FEOD | | | | U F READ, UPDAT, DELET, | | OPEN, CLOSE, FEOD | |______________________________________________________|
Figure 51. Valid File Operations for a SPECIAL File Figure 52 is a processing chart for SPECIAL files.
Figure 52. Processing Chart for SPECIAL Files
Valid File Operations:
1. CLOSE, FEOD
2. WRITE, CLOSE, FEOD
3. UPDAT, DELET, CLOSE, FEOD
4. READ, OPEN, CLOSE, FEOD
5. READ, WRITE, OPEN, CLOSE, FEOD
6. READ, DELET, UPDAT, OPEN, CLOSE, FEOD
7. WRITE, OPEN, CLOSE, FEOD
Notes:
1. Shaded positions must be blank. Positions without entries are program dependent. 2. Positions 54 through 59 must contain the name of the user-written routine that controls the input/output operations for the file.
6.0 Chapter 6. Commitment Control
This chapter describes how to use commitment control to process file operations as a group. With commitment control, you ensure one of two outcomes for the file operations: either all of the file operations are successful or none of the file operations has any effect. In this way, you process a group of operations as a unit.
Subtopics:
6.1 Using Commitment Control
To use commitment control, you do the following:
° Use the CL commands CRTJRN (Create Journal), CRTJRNRCV (Create Journal Receiver) and STRJRNPF (Journal Physical File) to prepare for using commitment control, and the CL commands STRCMTCTL (Start Commitment Control) and ENDCMTCTL (End Commitment Control) to notify the system when you want to start and end commitment control. See the CL Reference for information on these commands.
° Specify commitment control on the file-description specifications of the files you want under commitment control.
° Use the COMIT (Commit) operation code to apply a group of changes to files under commitment control, or use the ROLBK (Roll Back) operation code to eliminate the pending group of changes to files under commitment control.
Subtopics:
- 6.1.1 Starting and Ending Commitment Control
- 6.1.2 Specifying Files for Commitment Control
- 6.1.3 Commitment Control Operations
- 6.1.4 Commitment Control Locks
- 6.1.5 Commitment Control in the Program Cycle
- 6.1.6 Example of Using Commitment Control
6.1.1 Starting and Ending Commitment Control
The CL command STRCMTCTL notifies the system that you want to process files under commitment control.
The LCKLVL (Lock Level) parameter allows you to select the level at which records are locked under commitment control. See "Commitment Control Locks" in topic 6.1.4 and the CL Programmer's Guide for further details on lock levels.
When you complete a group of changes with a COMIT operation, you can specify a label to identify the end of the group. In the event of an abnormal job end, this identification label is written to a file, message queue, or data area so that you know which group of changes is the last group to be completed successfully. You specify this file, message queue, or data area on the STRCMTCTL command.
Before you call any program that processes files specified for commitment control, issue the STRCMTCTL command. If you call a program that opens a file specified for commitment control before you issue the STRCMTCTL command, the opening of the file will fail.
The CL command ENDCMTCTL notifies the system that your routing step has finished processing files under commitment control. See the CL Reference for further information on the STRCMTCTL and ENDCMTCTL commands.
6.1.2 Specifying Files for Commitment Control
On the file-continuation specifications, enter a K in position 53 and the word COMIT in positions 54 through 59. On the file-description specifications, describe the file as having device DISK in positions 40 through 46.
When a program specifies commitment control for a file, the specification applies only to the input and output operations made by this program for this file. Commitment control does not apply to operations other than input and output operations. It does not apply to files that do not have commitment control specified in the program doing the input or output operation.
When more than one program accesses a file as a shared file, all or none of the programs must specify the file to be under commitment control.
6.1.3 Commitment Control Operations
The COMIT (Commit) operation tells the system that you have completed a group of changes to the files under commitment control. The ROLBK (Roll Back) operation eliminates the current group of changes to the files under commitment control. For information on how to specify these operation codes and what each operation does, see the RPG/400 Reference.
If the system fails, it implicitly issues a ROLBK operation. You can check the identity of the last successfully completed group of changes using the label you specify in factor 1 of the COMIT operation code, and the notify-object you specify on the STRCMTCTL command.
At the end of a routing step, or when you issue the ENDCMTCTL command, the OS/400 system issues an implicit ROLBK, which eliminates any changes since the last ROLBK or COMIT operation that you issued. To ensure that all your file operations have effect, issue a COMIT operation before ending a routing step operating under commitment control.
The OPEN operation permits input and output operations to be made to a file and the CLOSE operation stops input and output operations from being made to a file. However, the OPEN and CLOSE operations do not affect the COMIT and ROLBK operations. A COMIT or ROLBK operation affects a file, even after the file has been closed. For example, your program may include the following steps:
1. Issue COMIT (for files already opened under commitment control).
2. Open a file specified for commitment control.
3. Perform some input and output operations to this file.
4. Close the file.
5. Issue ROLBK.
The changes made at step 3 are rolled back by the ROLBK operation at step 5, even though the file has been closed at step 4. The ROLBK operation could be issued from another program in the same routing step.
A program does not have to operate all its files under commitment control, and to do so may adversely affect performance. The COMIT and ROLBK operations have no effect on files that are not under commitment control.
Note: When multiple devices are attached to an application program, and commitment control is in effect for the files this program uses, the COMIT or ROLBK operations continue to work on a file basis and not by device. The database may be updated with partially completed COMIT blocks or changes that other users have completed may be eliminated. It is your responsibility to ensure this does not happen.
6.1.4 Commitment Control Locks
On the STRCMTCTL command, you specify a level of locking, either LCKLVL (*ALL) or LCKLVL (*CHG). When your program is operating under commitment control and has processed an input or output operation on a record in a file under commitment control, the record is locked by commitment control as follows:
° Your program can access the record.
° Another program in your routing step, with this file under commitment control, can read the record. If the file is a shared file, the second program can also update the record.
° Another program in your routing step that does not have this file under commitment control cannot read or update the record.
° Another program in a separate routing step, with this file under commitment control, can read the record if you specified LCKLVL (*CHG), but it cannot read the record if you specified LCKLVL (*ALL). With either lock level, the next program cannot update the record.
° Another program that does not have this file under commitment control and that is not in your routing step can read but not update the record.
° Commitment control locks are different than normal locks, depend on the LCKLVL specified, and can only be released by the COMIT and ROLBK operations.
The COMIT and ROLBK operations release the locks on the records. The UNLCK operation will not release records locked using commitment control. See the CL Reference for details on lock levels.
The number of entries that can be locked under commitment control before the COMIT or ROLBK operations are required may be limited. For more information, see the Advanced Backup and Recovery Guide
Note: The SETLL and SETGT operations lock a record where a read operation (not for update) would lock a record for commitment control.
6.1.5 Commitment Control in the Program Cycle
Commitment control is intended for full procedural files, where the input and output is under your control. Do not use commitment control with primary and secondary files, where input and output is under the control of the RPG/400 program cycle. The following are some of the reasons for this recommendation:
° You cannot issue a COMIT operation for the last total output in your program.
° It is difficult to program within the cycle for recovery from a locked-record condition.
° Level indicators are not reset by the ROLBK operation.
° After a ROLBK operation, processing matching records may produce a sequence error.
6.1.6 Example of Using Commitment Control
7.0The following is an example of the specifications and CL commands for a program operating under commitment control.
To prepare for using commitment control, you issue the following CL commands:
° CRTJRNRCV JRNRCV (RECEIVER)
The above command creates a journal receiver named RECEIVER.
° CRTJRN JRN(JOURNAL) JRNRCV(RECEIVER)
The above command creates a journal named JOURNAL and attaches the journal receiver named RECEIVER.
° STRJRNPF FILE(MASTER) JRN(JOURNAL)
The above command directs journal entries for the file MASTER to the journal JOURNAL.
In your program, you specify COMIT for the file MASTER:.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FMASTER UF E K DISK KCOMIT F*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* In the calculation specifications, use the COMIT operation to C* complete a group of operations. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C KEY CHAINMASTER 50 C N50 UPDATRECORD 99 C N99 COMIT C* C* If an operation within a group fails, use the ROLBK operation C* to eliminate the entire group of operations. C* C 99 ROLBK C*
Figure 53. Example of Using Commitment Control
To operate your program (named REVISE) under commitment control, you issue the commands:
° STRCMTCTL LCKLVL(*ALL)
The above command starts commitment control, with the highest level of locking.
° CALL REVISE
The above command calls your program (named REVISE).
° ENDCMTCTL
The above command ends commitment control, and causes an implicit Roll Back operation.
7.0 Chapter 7. Using DISK Files
Database files, which are associated with the RPG/400 device DISK in positions 40 through 46 of the file description specifications, can be:
° Externally described files, whose fields are described to the OS/400 system through the data description specifications (DDS)
° Program-described files, whose fields are described on input/output specifications in the program that uses the file.
All database files are created by the OS/400 create file commands. See the CL Reference for a description of the OS/400 commands that relate to database files.
Subtopics:
- 7.1 Externally Described Disk Files
- 7.2 Program-Described Disk Files
- 7.3 Methods for Processing Disk Files
- 7.4 Valid File Operations
7.1 Externally Described Disk Files
Externally described DISK files are identified by an E in position 19 of the file description specifications. The E indicates that the compiler is to retrieve the external description of the file from the system when the program is compiled. Therefore, you must create the file before the program is compiled.
The external description for a DISK file includes:
° The record-format specifications that contain a description of the fields in a record
° Access path specifications that describe how the records are to be retrieved.
These specifications result from the DDS for the file and the OS/400 create file command that is used for the file.
Subtopics:
- 7.1.1 Record Format Specifications
- 7.1.2 Access Path
- 7.1.3 Valid Keys for a Record or File
- 7.1.4 Processing Methods for Externally Described DISK Files
7.1.1 Record Format Specifications
The record-format specifications allow you to describe the fields in a record and the location of the fields in a record. The fields are located in the record in the order specified in the DDS. The field description generally includes the field name, the field type (character, binary, zoned decimal, or packed decimal), and the field length (including the number of decimal positions in a numeric field). Instead of specifying the field attributes in the record format for a physical or logical file, you can define them in a field-reference file.
In addition, the DDS keywords can be used to:
° Specify that duplicate key values are not allowed for the file (UNIQUE) ° Specify a text description for a record format or a field (TEXT).
For a complete list of the DDS keywords that are valid for a database file, see the Database Guide.
Figure 54 in topic 7.1.2 shows an example of the DDS for a database file, and Figure 55 in topic 7.1.2 for a field-reference file that defines the attributes for the fields used in the database file. See the DDS Reference for more information on a field-reference file.
7.1.2 Access Path
The description of an externally described file contains the access path that describes how records are to be retrieved from the file. Records can be retrieved based on an arrival sequence (non-keyed) access path or on a keyed-sequence access path.
The arrival sequence access path is based on the order in which the records are stored in the file. Records are added to the file one after another.
For the keyed-sequence access path, the sequence of records in the file is based on the contents of the key field that is defined in the DDS for the file. For example, in the DDS shown in Figure 54, CUST is defined as the key field. The keyed-sequence access path is updated whenever records are added, deleted, or when the contents of a key field change.
For a complete description of the access paths for an externally described database file, see the Database Guide.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* A..........T.Name++++++.Len++TDpB......Functions++++++++++++++++++++* A** LOGICAL CUSMSTL CUSTOMER MASTER FILE A UNIQUE A R CUSREC PFILE(CUSMSTP) A TEXT('Customer Master Record') A CUST A NAME A ADDR A CITY A STATE A ZIP A SRHCOD A CUSTYP A ARBAL A ORDBAL A LSTAMT A LSTDAT A CRDLMT A SLSYR A SLSLYR A K CUST
Figure 54. Example of the Data Description Specifications for a Database File
The sample DDS are for the customer master logical file CUSMSTL. The file contains one record format CUSREC (customer master record). The data for this file is contained in the physical file CUSMSTP, which is identified by the keyword PFILE. The UNIQUE keyword is used to indicate that duplicate key values are not allowed for this file. The CUST field is identified by a K in position 17 of the last line as the key field for this record format.
The fields in this record format are listed in the order they are to appear in the record. The attributes for the fields are obtained from the physical file CUSMSTP. The physical file, in turn, refers to a field-reference file to obtain the attributes for the fields. The field-reference file is shown in Figure 55.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* A..........T.Name++++++RLen++TDpB......Functions++++++++++++++++++++* A**FLDRED DSTREF DISTRIBUTION APPLICATION FIELD REFERENCE A R DSTREF TEXT('Distribution Field Ref') A* COMMON FIELDS USED AS REFERENCE A BASDAT 6 0 EDTCDE(Y) 1 A TEXT('Base Date Field') A* FIELDS USED BY CUSTOMER MASTER FILE A CUST 5 CHECK(MF) 2 A COLHDG('Customer' 'Number') A NAME 20 COLHDG('Customer Name') A ADDR R REFFLD(NAME) 3 A COLHDG('Customer Address') A CITY R REFFLD(NAME) 3 A COLHDG('Customer City') A STATE 2 CHECK(MF) 2 A COLHDG('State') A SRHCOD 6 CHECK(MF) 2 A COLHDG('Search' 'Code') A TEXT('Customer Number Search + A Code') A ZIP 5 0 CHECK(MF) 2 A COLHDG('Zip' 'Code') A CUSTYP 1 0 RANGE(1 5) 4 A COLHDG('Cust' 'Type') A TEXT('Customer Type 1=Gov 2=Sch+ A 3=Bus 4=Pvt 5=Oth') A ARBAL 8 2 COLHDG('Accts Rec' 'Balance') 5 A EDTCDE(J) 6 A ORDBAL R REFFLD(ARBAL) A COLHDG('A/R Amt in' 'Order + A File')
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* A..........T.Name++++++RLen++TDpB......Functions++++++++++++++++++++* A LSTAMT R REFFLD(ARBAL) A COLHDG('Last' 'Amount' 'Paid') A TEXT('Last Amount Paid in A/R') A LSTDAT R REFFLD(BASDAT) A COLHDG('Last' 'Date' 'Paid') A TEXT('Last Date Paid in A/R') A CRDLMT R REFFLD(ARBAL) A COLHDG('Credit' 'Limit') A TEXT('Customer Credit Limit') A SLSYR R+ 2 REFFLD(ARBAL) A COLHDG('Sales' 'This' 'Year') A TEXT('Customer Sales This Year') A SLSLYR R+ 2 REFFLD(ARBAL) A COLHDG('Sales' 'Last' 'Year') A TEXT('Customer Sales Last Year') 7
Figure 55. Example of a Field Reference File
This example of a field-reference file shows the definitions of the fields that are used by the CUSMSTL (customer master logical) file as shown in Figure 54. The field-reference file normally contains the definitions of fields that are used by other files. The following text describes some of the entries for this field-reference file.
1 The BASDAT field is edited by the Y edit code, as indicated by the keyword EDTCDE(Y). If this field is used in an externally described output file for an RPG/400 program, the edit code used is the one specified in this field-reference file; it cannot be overridden in the RPG/400 program. If the field is used in a program-described output file for an RPG/400 program, an edit code must be specified for the field in the output specifications.
2 The CHECK(MF) entry specifies that the field is a mandatory fill field when it is entered from a display work station. Mandatory fill means that all characters for the field must be entered from the display work station.
3 The ADDR and CITY fields share the same attributes that are specified for the NAME field, as indicated by the REFFLD keyword.
4 The RANGE keyword, which is specified for the CUSTYP field, ensures that the only valid numbers that can be entered into this field from a display work station are 1 through 5.
5 The COLHDG keyword provides a column head for the field if it is used by the Interactive Database Utilities (IDU).
6 The ARBAL field is edited by the J edit code, as indicated by the keyword EDTCDE(J).
7 A text description (TEXT keyword) is provided for some fields. The TEXT keyword is used for documentation purposes and appears in various listings.
7.1.3 Valid Keys for a Record or File
For a keyed-sequence access path, you can define one or more fields in the DDS to be used as the key fields for a record format. (These fields must not be floating-point fields.) All record types in a file do not have to have the same key fields. For example, an order header record can have the ORDER field defined as the key field, and the order detail records can have the ORDER and LINE fields defined as the key fields.
The key for a file is determined by the valid keys for the record types in that file. The file's key is determined in the following manner:
° If all record types in a file have the same number of key fields defined in the DDS that are identical in attributes, the key for the file consists of all fields in the key for the record types. (The corresponding fields do not have to have the same name.) For example, if the file has three record types and the key for each record type consists of fields A, B, and C, the file's key consists of fields A, B, and C. That is, the file's key is the same as the records' key.
° If all record types in the file do not have the same key fields, the key for the file consists of the key fields common to all record types. For example, a file has three record types and the key fields are defined as follows:
- REC1 contains key field A. - REC2 contains key fields A and B. - REC3 contains key fields A, B, and C.
The file's key is field A-the key field common to all record types.
° If no key field is common to all record types, there is no key for the file.
In an RPG/400 program, you can specify a search argument on certain file operation codes to identify the record you want to process. The RPG/400 program compares the search argument with the key of the file or record, and processes the specified operation on the record whose key matches the search argument.
Subtopics:
7.1.3.1 Valid Search Arguments
You can specify a search argument in the RPG/400 operations CHAIN, DELET, READE, REDPE, SETGT, and SETLL that specify a file name or a record name.
For an operation to a file name, the maximum number of fields that you can specify in a search argument is equal to the total number of key fields valid for the file's key. For example, if all record types in a file do not contain all of the same key fields, you can use a key list (KLIST) to specify a search argument that is composed only of the number of fields common to all record types in the file. If a file contains three record types, the key fields are defined as follows:
- REC1 contains key field A. - REC2 contains key fields A and B. - REC3 contains key fields A, B, and C.
The search argument can only be a single field with attributes identical to field A because field A is the only key field common to all record types.
For an operation to a record name, the maximum number of fields that you can specify in a search argument is equal to the total number of key fields valid for that record type.
If the search argument consists of one field, you can specify a literal, a field name, or a KLIST name with one KFLD. If the search argument is composed of more than one field (a composite key), you must specify a KLIST with multiple KFLDs.
The attributes of each field in the search argument must be identical to the attributes of the corresponding field in the file or record key. The attributes include the length, the data type (character or numeric), and the number of decimal positions. The attributes are listed in the key-field-information data table of the compiler listing. See the example in Chapter 2, "Entering RPG/400 Specifications."
In all these file operations (CHAIN, DELET, READE, REDPE, SETGT, and SETLL), you can also specify a search argument that contains fewer than the total number of fields valid for the file or record. Such a search argument refers to a partial key.
7.1.3.2 Referring to a Partial Key
The rules for the specification of a search argument that refers to a partial key are as follows:
° The search argument is composed of fields that correspond to the leftmost (high-order) fields of the key for the file or record.
° Only the rightmost fields can be omitted from the key list (KLIST) for a search argument that refers to a partial key. For example, if the total key for a file or record is composed of key fields A, B, and C, the valid search arguments that refer to a partial key are field A, and fields A and B.
° Each field in the search argument must be identical in attributes to the corresponding key field in the file or record. The attributes include the length, data type (character or numeric), the number of decimal positions, and format (for example, packed or zoned).
° A search argument cannot refer to a portion of a key field.
If a search argument refers to a partial key, the file is positioned at the first record that satisfies the search argument or the record retrieved is the first record that satisfies the search argument. For example, the SETGT and SETLL operations position the file at the first record on the access path that satisfies the operation and the search argument. The CHAIN operation retrieves the first record on the access path that satisfies the search argument. The DELET operation deletes the first record on the access path that satisfies the search argument. The READE operation retrieves the next record if the portion of the key of that record (or the record of the specified type) on the access path matches the search argument. The REDPE operation retrieves the prior record if the portion of the key of that record (or the record of the specified type) on the access path matches the search argument. For more information on the above operation codes, see the RPG/400 Reference.
7.1.4 Processing Methods for Externally Described DISK Files
You can process externally described DISK files sequentially by key, randomly by key, randomly by relative record number, sequentially within limits, or consecutively (without a key or relative record number). A K in position 31 of the file description specifications for an externally described file indicates that the file is to be processed by key. If processing is sequential, records are retrieved in key sequence. If processing is random, key values are used to identify the records. A blank in position 31 indicates that the file is processed by relative record number, sequentially (arrival sequence) or randomly. Random or sequential processing is determined by the entries in positions 16 and 28 of the file description specifications and the operation code used on the calculation specifications (for example, CHAIN, SETLL, READ).
7.2 Program-Described Disk Files
Program-described files, which are identified by an F in position 19 of the file description specifications, can be described as indexed files, as sequential files, or as record-address files.
Subtopics:
- 7.2.1 Indexed File
- 7.2.2 Sequential Files
- 7.2.3 Record Address File
- 7.2.4 Externally Described File as Program Described
7.2.1 Indexed File
An indexed file is a program-described DISK file whose access path is built on key values. You must create the access path for an indexed file by using data description specifications.
An indexed file is identified by an I in position 32 of the file description specifications.
The key fields identify the records in an indexed file. You specify the length of the key field in positions 29 and 30, the format of the key field in position 31, and the starting location of the key field in positions 35 through 38 of the file description specifications.
An indexed file can be processed sequentially by key, sequentially within limits, or randomly by key.
Subtopics:
7.2.1.1 Valid Search Arguments
For a program-described file, a search argument must be a single field. For the CHAIN and DELET operations, the search argument must be the same length as the key field that is defined on the file description specifications for the indexed file. For the other file operations, the search argument may be a partial field.
The DDS specifies the fields to be used as a key field. Positions 35 through 38 of the file description specifications specify the starting position of the first key field. The entry in positions 29 and 30 of the file description specifications must specify the total length of the key as defined in the DDS.
Figure 56 and Figure 57 show examples of how to use the DDS to describe the access path for indexed files.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* A..........T.Name++++++.Len++TDpB......Functions++++++++++++++++++++* A R FORMATA PFILE(ORDDTLP) A TEXT('Access Path for Indexed + A File') A FLDA 14 A ORDER 5 0 A FLDB 101 A K ORDER A*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FORDDTLL IP F 118 3PI 15 DISK F*
Figure 56. Using Data Description Specifications to Define the Access Path for an Indexed File
You must use data description specifications to create the access path for a program-described indexed file.
In the DDS for the record format FORMATA for the logical file ORDDTLL, the field ORDER, which is five digits long, is defined as the key field, and is in packed format. The definition of ORDER as the key field establishes the keyed access for this file. Two other fields, FLDA and FLDB, describe the remaining positions in this record as character fields.
The program-described input file ORDDTLL is described on the file description specifications as an indexed file. Positions 29 and 30 must specify the number of positions in the record required for the key field as defined in the DDS: three positions. Positions 35 through 38 specify position 15 as the starting position of the key field in the record. Because the file is defined as program-described by the F in position 19, the RPG/400 compiler does not retrieve the external field-level description of the file at compilation time. Therefore, you must describe the fields in the record on the input specifications.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* A..........T.Name++++++.Len++TDpB......Functions++++++++++++++++++++* A R FORMAT PFILE(ORDDTLP) A TEXT('Access Path for Indexed + A File') A FLDA 14 A ORDER 5 A ITEM 5 A FLDB 96 A K ORDER A K ITEM A*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FORDDTLL IP F 120 10AI 15 DISK F*
Figure 57. (Part 1 of 2). Using Data Description Specifications to Define the Access Path (Composite Key) for an Indexed File
In this example, the data description specifications define two key fields for the record format FORMAT in the logical file ORDDTLL. For the two fields to be used as a composite key for a program described indexed file, the key fields must be contiguous in the record.
On the file description specifications, the length of the key field is defined as 10 in positions 29 and 30 (the combined number of positions required for the ORDER and ITEM fields). The starting position of the key field is described as 15 in positions 37 and 38. The starting position must specify the first position of the first key field.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* IDsname....NODsExt-file++.............OccrLen+......................* IKEY DS I..............Ext-field+............PFromTo++DField+...............* I 1 5 K1 I 6 10 K2 I*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C MOVE ORDER K1 C MOVE ITEM K2 C KEY CHAINORDDTLL 99 C*
Figure 58. (Part 2 of 2). Using Data Description Specifications to Define the Access Path (Composite Key) for an Indexed File
When the DDS specifies a composite key, you must build a search argument in the program to CHAIN to the file. (A KLIST cannot be used for a program-described file.) One way is to create a data structure with subfields equal to the key fields defined in the DDS. Then, in the calculations, set the subfields equal to the value of the key fields, and use the data-structure name as the search argument in the CHAIN operation.
In this example, the MOVE operations set the subfields K1 and K2 equal to the value of ORDER and ITEM, respectively. The data-structure name (KEY) is then used as the search argument in the CHAIN operation.
7.2.2 Sequential Files
Sequential files are files where the order of the records in the file is based on the order the records are placed in the file (that is, in arrival sequence). For example, the tenth record placed in the file occupies the tenth record position.
Sequential files can be processed randomly by relative record number, consecutively, or by a record-address file. You can use either the SETLL or SETGT operation code to set limits on the file.
7.2.3 Record Address File
You can use a record-address file to process another file. A record-address file can contain (1) limits records that are used to process a file sequentially within limits, or (2) relative record numbers that are used to process a file by relative record numbers. The record-address file itself must be processed sequentially.
A record-address file is identified by an R in position 16 of the file description specifications. If the record-address file contains relative record numbers, position 32 must contain a T. The name of the record-address file must also be specified in positions 11 through 18 of the extension specifications, and the name of the file to be processed by the record-address file must be specified in positions 19 through 26 of the extension specifications.
Subtopics:
7.2.3.1 Limits Records
For sequential-within-limits processing, the record-address file contains limits records. A limits record contains the lowest record key and the highest record key of the records in the file to be read.
The format of the limits records in the record-address file is as follows:
° The low key begins in position 1 of the record; the high key immediately follows the low key. No blanks can appear between the keys.
° Each record in the record-address file can contain only one set of limits. The record length must be greater than or equal to twice the length of the record key.
° The low key and the high key in the limits record must be the same length. The length of the keys must be equal to the length of the key field of the file to be processed.
° A blank entry equal in length to the record key field causes the RPG/400 compiler to read the next record in the record-address file.
7.2.3.2 Relative Record Numbers
For relative-record-number processing, the record-address file contains relative record numbers. Each record retrieved from the file being processed is based on a relative record number in the record-address file. A record-address file containing relative record numbers cannot be used for limits processing. Each relative record number in the record-address file is a multi-byte binary field where each field contains a relative record number. You can specify the record-address file length as 4, 3, or blank, depending on the source of the file. When using a record-address file from the AS/400 environment, specify the record-address file length as 4, since each field is 4 bytes in length. When using a record-address file from the System/36 environment, specify the record-address file length as 3, since each field is 3 bytes in length. If you specify the record-address file length as blank, the compiler will check the primary record length at run time and determine whether to treat the record-address file as 3 byte or as 4 byte. A minus 1 (-1 or hexadecimal FFFFFFFF) relative-record-number value stops the use of a relative-record-address file record. End of file occurs when all records from the record-address file have been processed.
7.2.4 Externally Described File as Program Described
A file that is externally described can be treated as a program-described file in an RPG/400 program. Specify an F in position 19 of the file description specifications, and describe the fields in the records on input and/or output specifications. When an F is specified in position 19 of the file description specifications for an externally described file, the compiler does not copy in the external description.
7.3 Methods for Processing Disk Files
The methods of disk file processing include:° Relative-record-number processing ° Consecutive processing ° Sequential-by-key processing ° Random-by-key processing ° Sequential-within-limits processing.
Subtopics:
- 7.3.1 Relative-Record-Number Processing
- 7.3.2 Consecutive Processing
- 7.3.3 Sequential-by-Key Processing
- 7.3.4 Sequential-within-Limits Processing
- 7.3.5 Keyed Processing Examples
7.3.1 Relative-Record-Number Processing
Random input or update processing by relative record number applies to full procedural files only. The desired record is accessed by the CHAIN operation code.
Relative record numbers identify the positions of the records relative to the beginning of the file. For example, the relative record numbers of the first, fifth, and seventh records are 1, 5, and 7, respectively.
For an externally described file, input or update processing by relative record number is determined by a blank in position 31 of the file description specifications and the use of the CHAIN operation code. Output processing by relative record number is determined by a blank in position 31 and the use of the RECNO option on a file description specifications continuation line for the file.
You can use the RECNO option for the file description specifications continuation line to specify a numeric field that contains the relative record number that specifies where a new record is to be added to this file. The RECNO field must be defined as numeric with zero decimal positions. The field length must be large enough to contain the largest record number for the file. A RECNO field must be specified if new records are to be placed in the file by using output specifications or a WRITE operation. When you update or add a record to a file by relative record number, the record must already have a place in the member. For an update, that place can be a valid existing record; for a new record, that place can be a deleted record. You can use the CL command INZPFM to initialize records for use by relative record number. The current relative record number is placed in the RECNO field for all retrieval operations or operations that reposition the file (for example, SETLL, CHAIN, READ).
7.3.2 Consecutive Processing
During consecutive processing, records are read in the order they appear in the file.
For output and input files that do not use random functions (such as SETLL, SETGT, CHAIN, or ADD), the RPG/400 compiler defaults to or operates as though SEQONLY(*YES) had been specified on the CL command OVRDBF (Override with Database File). (The RPG/400 compiler does not operate as though SEQONLY(*YES) had been specified for update files.) SEQONLY(*YES) allows multiple records to be placed in internal data management buffers; the records are then passed to the RPG/400 compiler one at a time on input. If, in the same job, two logical files use the same physical file, and one file is processed consecutively and one is processed for random update, a record could be updated that has already been placed in the buffer that is presented to the program. In this case, when the record is processed from the consecutive file, the record does not reflect the updated data. To prevent this problem, use the CL command OVRDBF and specify the option SEQONLY(*NO), which indicates that you do not want multiple records transferred for a consecutively processed file.
For more information on sequential only processing, see the Database Guide.
7.3.3 Sequential-by-Key Processing
For the sequential-by-key method of processing, records are read from the file in key sequence.
The sequential-by-key method of processing is valid for keyed files used as primary, secondary, or full procedural files.
For output files and for input files that do not use random functions (such as SETLL, SETGT, CHAIN, or ADD) and that have only one record format, the RPG/400 compiler defaults to or operates as though SEQONLY(*YES) had been specified on the CL command OVRDBF. (The RPG/400 compiler does not operate as though SEQONLY(*YES) had been specified for update files.) SEQONLY(*YES) allows multiple records to be placed in internal data management buffers; the records are then passed to the RPG/400 compiler one at a time on input. If, in the same job, two files use the same physical file, and one file is processed sequentially and one is processed for random update, a record could be updated that has already been placed in the buffer that is presented to the program. In this case, when the record is processed from the sequential file, the record does not reflect the updated data. To prevent this problem, use the CL command OVRDBF and specify the option SEQONLY(*NO), which indicates that you do not want multiple records transferred for a sequentially processed file.
For more information on sequential only processing, see the Database Guide.
Figure 59 shows different ways a header record and the detail records associated with the header record can be processed. Part 1 shows an example of the file being read sequentially by key; parts 2 through 4 show examples in which the READ operation code is used; part 5 shows the processing of these records by the matching record technique.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* F* F* In this example, the order header record (ORDHDR) and the order F* detail record (ORDDTL) are contained in the same file (ORDFIL). F* The ORDFIL file is defined as a primary input file and is read F* sequentially by key. In the data description specifications for F* the file, the key for the ORDHDR record is defined as the ORDER F* field, and the key for the ORDDTL record is defined as the ORDER F* field plus the LINE (line number) field, which is a composite key. F* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FORDFILL IP E K DISK
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* I* I* A record-identifying indicator is assigned to each record; these I* record-identifying indicators are used to control processing for I* the different record types. IRcdname+....In.....................................................* IORDHDR 01 I* IORDDTL 02 *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C *IN01 IFEQ '1' C " __________________ C " | Process header | C " |__________________| C END C* C *IN02 IFEQ '1' C " __________________ C " | Process detail | C " |__________________| C END
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* F* F* This example is the same as the previous example except that the F* ORDFIL file is defined as a full-procedural file, and the reading F* of the file is done by the READ operation code. F* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FORDFILL IF E K DISK F*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* I* I* The two records (ORDHDR and ORDDTL) are contained in the same I* file, and a record-identifying indicator is assigned to each I* record. The record-identifying indicators are used to control I* processing for the different record types. No control levels I* or match fields can be specified for a full-procedural file. I* IRcdname+....In.....................................................* IORDHDR 01 I* IORDDTL 02 I* *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* The READ operation code reads a record from the ORDFIL file. An C* end-of-file indicator is specified in positions 58 and 59. If C* the end-of-file indicator 99 is set on by the READ operation, C* the program branches to the EOFEND tag and processes the end-of- C* file routine. The record-identifying indicators control the C* processing of the different record types. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C READ ORDFIL 99 C 99 GOTO EOFEND C* C *IN01 IFEQ '1' C " __________________ C " | Process header | C " |__________________| C END C* C *IN02 IFEQ '1' C " __________________ C " | Process detail | C " |__________________| C END C* C EOFEND TAG C " _____________________ C " | End-of-file routine | C " |_____________________|
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* F* F* This example is similar to the one shown in Part 2 of this figure. F* However, the READ operation code is used to read each record F* (ORDHDR and ORDDTL) instead of reading the file. The program F* logic controls when each READ occurs. No record-identifying F* indicators are needed because the program logic knows which F* record it is working with according to the record format name. F* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FORDFILL IF E K DISK F* *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C " C " C " C READ ORDHDR 99 C 99 GOTO END C " __________________ C " | Process header | C " |__________________| C* C READ ORDDTL 99 C 99 GOTO END C " __________________ C " | Process detail | C " |__________________| C* C END TAG C " C " C "
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* F* F* In this example, the order header records (ORDHDR) are contained F* in the ORDHDRL file, and the order detail records (ORDDTL) are F* contained in the ORDDTLL file. The ORDHDRL is defined as a F* primary input file, and the reading of records from the file is F* controlled by the program cycle. The ORDDTLL file is defined as F* a full-procedural file, and the READE operation is used to read F* records from the file. F* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FORDDTLL IF E K DISK FORDHDRL IP E K DISK F* *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* The ORDER field in the SETLL operation is used to position the C* ORDDTLL file at the first ORDDTL record that has a key equal to C* or greater than the contents of the ORDER field. The ORDER C* field is used as the search argument for the READE operation. C* The READE operation retrieves the next ORDDTL record from the C* file if the key of the record is equal to the search argument C* specified in factor 1. If the key and the search argument are C* not equal, the indicator specified in positions 58 and 59 is C* set on. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C " __________________ C " | Process header | C " |__________________| C " C ORDER SETLLORDDTL 20 C N20 GOTO NONE C LOOP TAG C ORDER READEORDDTL 21 C 21 GOTO ENDFIL C " C " __________________ C " | Process detail | C " |__________________| C " C GOTO LOOP C NONE TAG C " C " C ENDFIL TAG
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* F* F* In this example, the order header records (ORDHDR) are contained F* in the ORDHDRL file, and the order detail records (ORDDTL) are F* contained in the ORDDTLL file. The ORDHDRL is defined as a F* primary input file, and the ORDDTLL file is defined as a F* secondary input file. The order header and order detail records F* are processed as matching record, with the ORDER field in both F* records assigned the match level value of M1. Record-identifying F* indicators 01 and 02 are assigned to the records to control the F* processing for the different record types. F* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FORDHDRL IP E K DISK FORDDTLL IS E K DISK F*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* IRcdname+....In.....................................................* IORDHDR 01 I ORDER M1 IORDDTL 02 I ORDER M1 I* *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C 01NMR " __________________ C 01 MR " | Process header | C 01 MR " |__________________| C* C 02NMR " __________________ C 02 MR " | Process detail | C 02 MR " |__________________|
Figure 59. Processing Order Header and Order Detail Records
7.3.4 Sequential-within-Limits Processing
Sequential-within-limits processing by a record-address file is specified by an L in position 28 of the file description specifications and is valid for a file with a keyed access.
You can specify sequential-within-limits processing for an input or an update file that is designated as a primary, secondary, or full-procedural file. The file can be externally described or program-described (indexed). The file should have keys in ascending sequence.
To process a file sequentially within limits from a record-address file, the program reads:
° A limits record from the record-address file
° Records from the file being processed within limits with keys greater than or equal to the low-record key and less than or equal to the high-record key in the limits record. If the two limits supplied by the record-address file are equal, only the records with the specified key are retrieved.
The program repeats this procedure until the end of the record-address file is reached.
Figure 61 in topic 7.3.5 shows an example of an indexed file being processed sequentially within limits. Figure 62 in topic 7.3.5 shows the same example with externally described files instead of program-described files.
7.3.5 Keyed Processing Examples
Figure 63 shows an example of processing certain records in a group. Figure 64 shows examples of how to process the first record in a file and the last record in a file.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FCHANGE IP E K DISK FMASTER UF E K DISK F*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* IRcdname+....In.....................................................* IMSTREC 01 ICHGREC 02 I*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C 02 ACCT CHAINMSTREC 03 C 02N03 MOVE NEW NAMADR C 02N03 UPDATMSTREC C*
Figure 60. Random Processing of an Externally Described DISK File by Key
The update file MASTER is to be processed by keys. The DDS for each of the externally described files (MASTER and CHANGE) identify the ACCT field as the key field. As each record is read from the primary input file, CHANGE, the account number field (ACCT) is used as the search argument to chain to the corresponding record in the MASTER file. Input specifications are used to assign record-identifying indicators to the records in the CHANGE and MASTER files. The MASTER file contains one record format MSTREC that contains two fields, ACCT and NAMADR (name and address). The CHANGE file contains one record format CHGREC that contains two fields, ACCT and NEW. The data in the NEW field must be moved into the NAMADR field before the MSTREC can be updated.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* F* F* The input file MASTER, which is a program-described file (F in F* position 19), is described as an indexed file to be processed F* by keys. (The access path for an indexed file must be created F* by data description specifications.) F* F* MASTER is processed sequentially within limits (L in position 28) F* by the record address file LIMITS. Each set of limits from the F* record-address file consists of the low and high account numbers F* of the records in the MASTER file to be processed. Because the F* account number key field (ACCT) is eight positions long, each F* set of limits consists of two 8-position keys. F* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FLIMITS IR F 16 8 EDISK FMASTER IP F 64L 8AI 1 DISK FPRINT O F 96 OF PRINTER F*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* E* E* The record-address file name LIMITS must be specified in positions E* 11 through 18 of the extension specifications. The name of the E* file to be processed by the record address file must be specified E* in positions 19 through 26 of the extension specifications. E* E....FromfileTofile++Name++N/rN/tbLenPDSArrnamLenPDSComments++++++++* E LIMITS MASTER E*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* I* I* Input specifications must be used to describe the records in the I* program-described file MASTER. I* IFilenameSqNORiPos1NCCPos2NCCPos3NCC................................* IMASTER NS 01 I....................................PFromTo++DField+L1M1FrPlMnZr...* I 1 8 ACCT I 9 64 NAMADR I*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* O* O* As MASTER is processed within each set of limits, the corres- O* ponding records are printed. Processing of the MASTER file is O* complete when the record-address file LIMITS reaches end of file. O* OName++++DFBASbSaN01N02N03Excnam....................................* OPRINT D 1 01 O................N01N02N03Field+YBEnd+PConstant/editword+++++++++...* O ACCT 8 O NAMADR 70 O*
Figure 61. Processing an Indexed File Sequentially within Limits
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FLIMITS IR F 16 8 EDISK FMASTER IP E L K DISK FPRINT O F 96 OF PRINTER F*
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* IRcdname+....In.....................................................* IMSTREC 01 I*
Figure 62. Processing an Externally Described File Sequentially within Limits
If the program shown in Figure 61 used externally described files, the file description specifications would be coded as shown above. The input specifications are used to assign a record-identifying indicator to the record in the externally described file. The MASTER file contains the record format MSTREC. The external descriptions for the file identify the key fields. These keys should be in ascending sequence.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* This example shows how to retrieve the first record of a group. C* The SETLL operation is used to position the file at the first C* ORDDTL record that has a key equal to or greater than the search C* argument contained in the ORDER field. The READE operation reads C* the next ORDDTL record from the file if the key of the record is C* equal to the search argument (the ORDER field) specified in C* factor 1. If the key is not equal to the search argument, the C* indicator specified in positions 58 and 59 is set on. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C ORDER SETLLORDDTL C ORDER READEORDDTL 22 C 22 GOTO ENDFIL C " C " __________________ C " | Process ORDDTL | C " |__________________| *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* This example shows how to retrieve the last record of a group. C* The SETGT operation is used to position the file at the next C* ORDDTL record that has a key greater than the search argument C* contained in the ORDER field. The REDPE operation reads the next C* prior ORDDTL record from the file if the key of the record is C* equal to the search argument (the ORDER field) specified in C* factor 1. If the key is not equal to the search argument, the C* indicator specified in positions 58 and 59 is set on. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C ORDER SETGTORDDTL C ORDER REDPEORDDTL 22 C 22 GOTO ENDFIL C " C " __________________ C " | Process ORDDTL | C " |__________________| *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* This example shows how to retrieve the last record of the previous C* group. The ORDER field, which contains the key of the current C* group, is used in the SETLL operation to position the file at the C* first ORDDTL record that has a key equal to or greater than the C* search argument contained in the ORDER field. The READP operation C* then reads the prior record. If there is no prior record in the C* file, the program branches to the ENDFIL routine. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C ORDER SETLLORDDTL C READPORDDTL 22 C 22 GOTO ENDFIL C " C " __________________ C " | Process ORDDTL | C " |__________________| *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* This example retrieves the last record of a group. One or more C* records for the group exist in the file. The SETGT operation C* positions the file at the next record that contains a key value C* greater than the search argument contained in the ORDER field. C* For example, if the ORDER field contains a value of 10, SETGT C* positions the file at the record that contains a key value C* greater than 10: C* Keys C* 9 C* 9 C* 10 C* 10 C* SETGT _________ÿ C* 11 C* C* The READP operation then reads the prior record of the ORDDTL C* record format, thus reading the last record of the previous group. C* READP requires an end-of-file indicator in positions 58 and 59; C* therefore, if the beginning of the file is encountered, the halt C* indicator H6 is set on and the program ends abnormally. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C ORDER SETGTORDDTL C READPORDDTL H6 C H6 RETRN C " C " __________________ C " | Process ORDDTL | C " |__________________| *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* Reading the first record of the next group requires the SETGT C* operation to position the file and the READ operation. The ORDER C* field, which contains the key of the current group, is specified C* in factor 1 of the SETGT operation. The READ operation is then C* used to read the first record of the next group. An indicator C* must be specified in positions 58 and 59 of the READ operation to C* test for end of file. This technique can be used if the program C* knows the key value for a group of records or for a specific C* record and wants the next group. SETGT can be used to eliminate C* reading unwanted records that would be bypassed. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C ORDER SETGTORDDTL C READ ORDDTL 22 C 22 GOTO ENDFIL C " C " __________________ C " | Process ORDDTL | C " |__________________|
Figure 63. Processing Certain Records in a Group
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* C* After the file is opened, the first record is retrieved by a C* subsequent READ operation. To access the first record in a file C* after some processing has been done, use the figurative constant C* *LOVAL (assuming ascending key sequence). Set the lower limits C* by using the constant with the SETLL operation. C* Use the READ operation for the next record of the ORDDTL record C* format. If no records exist, end of file occurs, and the C* program branches to the NONE routine. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C *LOVAL SETLLORDDTL C READ ORDDTL 22 C 22 GOTO NONE C " C " __________________ C " | Process ORDDTL | C " |__________________| *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* C* Use the figurative constant *HIVAL (assuming ascending key C* sequence to access the last record in a file. By using *HIVAL C* with a SETGT operation, the file is positioned at the next C* record that has a key field value greater than the value C* specified in factor 1. C* The READP operation reads the next prior record, which in this C* example is the last record in the file. C* CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C *HIVAL SETGTORDDTL C READPORDDTL 22 C 22 GOTO NONE C " C " __________________ C " | Process ORDDTL | C " |__________________|
Figure 64. Processing Certain Records in a File
7.4 Valid File Operations
8.0Figure 65 shows the valid file operation codes allowed for DISK files processed by keys and Figure 66 for DISK files processed by non-keyed methods. The operations shown in these figures are valid for externally described DISK files and program-described DISK files.
Before running your program, you can override a file to another file. In particular, you can override a sequential file in your program to an externally described, keyed file. (The file is processed as a sequential file.) You can also override a keyed file in your program to another keyed file, providing the key fields are compatible. For example, the overriding file must not have a shorter key field than you specified in your program.
________________________________________________________________________ | File-Description Calculation | | Specifications Positions Specifications Positions | |______ ______ _______ ______ _______ ___________________________________| | 15 | 16 | 28(1) | 31(2)| 66 | 28-32 | |______|______|_______|______|_______|___________________________________| | I | P/S | | K/A/P| | CLOSE, FEOD, FORCE | |______|______|_______|______|_______|___________________________________| | I | P/S | | K/A/P| A | WRITE, CLOSE, FEOD, FORCE | |______|______|_______|______|_______|___________________________________| | I | P/S | L | K/A/P| | CLOSE, FEOD, FORCE | |______|______|_______|______|_______|___________________________________| | U | P/S | | K/A/P| | UPDAT, DELET, CLOSE, FEOD, FORCE | |______|______|_______|______|_______|___________________________________| | U | P/S | | K/A/P| A | UPDAT, DELET, WRITE, CLOSE, FEOD, | | | | | | | FORCE | |______|______|_______|______|_______|___________________________________| | U | P/S | L | K/A/P| | UPDAT, CLOSE, FEOD, FORCE | |______|______|_______|______|_______|___________________________________| | I | F | | K/A/P| | READ, READE, REDPE, READP, SETLL, | | | | | | | SETGT, CHAIN, OPEN, CLOSE, FEOD | |______|______|_______|______|_______|___________________________________| | I | F | | K/A/P| A | WRITE, READ, REDPE, READE, READP, | | | | | | | SETLL, SETGT, CHAIN, OPEN, CLOSE, | | | | | | | FEOD | |______|______|_______|______|_______|___________________________________| | I | F | L | K/A/P| | READ, OPEN, CLOSE, FEOD | |______|______|_______|______|_______|___________________________________| | U | F | | K/A/P| | READ, READE, REDPE, READP, SETLL, | | | | | | | SETGT, CHAIN, UPDAT, DELET, OPEN, | | | | | | | CLOSE, FEOD | |______|______|_______|______|_______|___________________________________| | U | F | | K/A/P| A | WRITE, UPDAT, DELET, READ, READE, | | | | | | | REDPE, READP, SETLL, SETGT, | | | | | | | CHAIN, OPEN, CLOSE, FEOD | |______|______|_______|______|_______|___________________________________| | U | F | L | K/A/P| | READ, UPDAT, OPEN, CLOSE, FEOD | |______|______|_______|______|_______|___________________________________| | O | Blank| | K/A/P| A | WRITE (add new records to a | | | | | | | file), OPEN, CLOSE, FEOD | |______|______|_______|______|_______|___________________________________| | O | Blank| | K/A/P| | WRITE (initial load of a new | | | | | | | file)(3), OPEN, CLOSE, FEOD | |______|______|_______|______|_______|___________________________________| | Note: (1)An L must be specified in position 28 to specify | | sequential-within-limits processing by a record-address file for an | | input or an update file. | |________________________________________________________________________| | Note: (2)Externally described files require a K in position 31; | | program-described files require an A or P in position 31 and an I in | | position 32. | |________________________________________________________________________| | Note: (3)An A in position 66 is not required for the initial loading | | of records into a new file. If A is specified in position 66, ADD | | must be specified on the output specifications. The file must have | | been created with the OS/400 CREATE FILE command. | |________________________________________________________________________|
Figure 65. Valid File Operations for Keyed Processing Methods (Random by Key, Sequential by Key, Sequential within Limits)
________________________________________________________________________ | File-Description Calculation | | Specifications Positions Specifications Positions | |____ _________ __________ __________ ____ ______________________________| | 15 | 16 | 31 | 54-59 | 66 | 28-32 | |____|_________|__________|__________|____|______________________________| | I | P/S | Blank | | | CLOSE, FEOD, FORCE | |____|_________|__________|__________|____|______________________________| | I | P/S | Blank | RECNO | | CLOSE, FEOD, FORCE | |____|_________|__________|__________|____|______________________________| | U | P/S | Blank | | | UPDAT, DELET, CLOSE, FEOD, | | | | | | | FORCE | |____|_________|__________|__________|____|______________________________| | U | P/S | Blank | RECNO | | UPDAT, DELET, CLOSE, FEOD, | | | | | | | FORCE | |____|_________|__________|__________|____|______________________________| | I | F | Blank | | | READ, READP, SETLL, SETGT, | | | | | | | CHAIN, OPEN, CLOSE, FEOD | |____|_________|__________|__________|____|______________________________| | I | F | Blank | RECNO | | READ, READP, SETLL, SETGT, | |____|_________|__________|__________|____|______________________________| | U | F | Blank | | | READ, READP, SETLL, SETGT, | | | | | | | CHAIN, UPDAT, DELET, OPEN, | | | | | | | CLOSE, FEOD | |____|_________|__________|__________|____|______________________________| | U | F | Blank | RECNO | | READ, READP, SETLL, SETGT, | | | | | | | CHAIN, UPDAT, DELET, OPEN, | | | | | | | CLOSE, FEOD | |____|_________|__________|__________|____|______________________________| | I | R | A/P/ | | | OPEN, CLOSE, FEOD | | | | Blank(1) | | | | |____|_________|__________|__________|____|______________________________| | I | R | Blank(2) | | | OPEN, CLOSE, FEOD | |____|_________|__________|__________|____|______________________________| | O | Blank | Blank | RECNO | A | WRITE(3) (add records to a | | | | | | | file), OPEN, CLOSE, FEOD | |____|_________|__________|__________|____|______________________________| | O | Blank | Blank | RECNO | | WRITE(4) (initial load of a | | | | | | | new file), OPEN, CLOSE, FEOD | |____|_________|__________|__________|____|______________________________| | O | Blank | Blank | Blank | | WRITE (sequentially load or | | | | | | | extend a file), OPEN, CLOSE, | | | | | | | FEOD | |____|_________|__________|__________|____|______________________________| | Note: (1)If position 31 is blank for a record-address-limits file, | | the format of the keys in the record-address file is the same as the | | format of the keys in the file being processed. | |________________________________________________________________________| | Note: (2)A record-address file containing relative record numbers | | requires a T in position 32. | |________________________________________________________________________| | Note: (3)The RECNO field that contains the relative record number | | must be set prior to the WRITE operation or if ADD is specified on the | | output specifications. | |________________________________________________________________________| | Note: (4)An A in position 66 is not required for the initial loading | | of the records into a new file; however, if A is specified in position | | 66, ADD must be specified on output specifications. The file must | | have been created with the OS/400 CREATE FILE command. | |________________________________________________________________________|
Figure 66. Valid File Operations for Non-keyed Processing Methods (Sequential, Random by Relative Record Number, and Consecutive)
8.0 Chapter 8. Using WORKSTN Files
The WORKSTN file allows an RPG/400 program to communicate interactively with a work-station user or to use the Intersystem Communications Function (ICF) to communicate with other programs. This chapter describes:
° Intersystem Communications Function (ICF) ° Externally described WORKSTN files ° Program-described WORKSTN files ° Multiple-device files.
The chapter also includes a number of examples for using WORKSTN files.
Subtopics:
- 8.1 Intersystem Communications Function
- 8.2 Externally Described WORKSTN Files
- 8.3 Processing WORKSTN Files
- 8.4 Program-Described WORKSTN File
- 8.5 Multiple-Device Files
- 8.6 WORKSTN File Examples
8.1 Intersystem Communications Function
You can use the ICF to write programs that communicate with (send data to and receive data from) other application programs on other systems.
To use the ICF, define a WORKSTN file in your program that refers to an ICF device file. Use either the system supplied file QICDMF or a file created using the OS/400 command CRTICFF.
You code for ICF by using the ICF as a file in your program. The ICF is similar to a display file and it contains the communications formats required for the sending and receiving of data between systems.
For further information on the ICF, refer to the ICF Programmer's Guide.
8.2 Externally Described WORKSTN Files
An RPG/400 WORKSTN file can use an externally described display-device file or ICF device file, which contains file information and a description of the fields in the records to be written.
In addition to the field descriptions (such as field names and attributes), the DDS for a display-device file are used to:
° Format the placement of the record on the screen by specifying the line-number and position-number entries for each field and constant.
° Specify attention functions such as underlining and highlighting fields, reverse image, or a blinking cursor.
° Specify validity checking for data entered at the display work station. Validity-checking functions include detecting fields where data is required, detecting mandatory fill fields, detecting incorrect data types, detecting data for a specific range, checking data for a valid entry, and processing modules 10 or 11 check-digit verification.
° Control screen management functions, such as if fields are to be erased, overlaid, or kept when new data is displayed.
° Associate indicators 01 through 99 with command attention keys or command function keys. If a function key is described as a command function key (CF), both the response indicator and the data record (with any modifications entered on the screen) are returned to the program. If a function key is described as a command attention key (CA), the response indicator is returned to the program but the data record remains unmodified. Therefore, input-only character fields are blank and input-only numeric field are filled with zeros, unless these fields have been initialized otherwise.
° Assign an edit code (EDTCDE) or edit word (EDTWRD) keyword to a field to specify how the field's values are to be displayed.
° Specify subfiles.
A display-device-record format contains three types of fields:
° Input fields. Input fields are passed from the device to the program when the program reads a record. Input fields can be initialized with a default value. If the default value is not changed, the default value is passed to the program. Input fields that are not initialized are displayed as blanks into which the work-station user can enter data.
° Output fields. Output fields are passed from the program to the device when the program writes a record to a display. Output fields can be provided by the program or by the record format in the device file.
° Output/input (both) fields. An output/input field is an output field that can be changed. It becomes an input field if it is changed. Output/input fields are passed from the program when the program writes a record to a display and passed to the program when the program reads a record from the display. Output/input fields are used when the user is to change or update the data that is written to the display from the program.
If you specify the keyword INDARA in the DDS for a WORKSTN file, the RPG/400 program passes indicators to the WORKSTN file in a separate indicator area, and not in the input/output buffer.
For a detailed description of an externally described data-device file and for a list of valid DDS keywords, see the DDS Reference.
Figure 67 in topic 8.2.1 shows an example of the DDS for a display-device file.
Subtopics:
- 8.2.1 Processing an Externally Described WORKSTN File
- 8.2.2 Function Key Indicators on Display Device Files
- 8.2.3 Command Keys on Display Device Files
8.2.1 Processing an Externally Described WORKSTN File
When an externally described WORKSTN file is processed, the OS/400 system transforms data from the program to the format specified for the file and displays the data. When data is passed to the program, the data is transformed to the format used by the program.
The OS/400 system provides device-control information for processing input/output operations for the device. When an input record is requested from the device, the OS/400 system issues the request, and then removes device-control information from the data before passing the data to the program. In addition, the OS/400 system can pass indicators to the program indicating which fields, or if any fields, in the record have been changed.
When the program requests an output operation, it passes the output record to the OS/400 system. The OS/400 system provides the necessary device-control information to display the record. It also adds any constant information specified for the record format when the record is displayed.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* AAN01N02N03T.Name++++++RLen++TDpBLinPosFunctions++++++++++++++++++++* A** ITEM MASTER INQUIRY A REF(DSTREF) 1 A R PROMPT TEXT('Item Prompt Format') A 73N61 OVERLAY 2 A CA01(98 'End of Program') 3 A 1 2'Item Inquiry' A 3 2'Item Number' A ITEM R I 3 15PUTRETAIN 4 A 61 ERRMSG('Invalid Item Number' 61) 5 A R RESPONSE TEXT('Response Format') A OVERLAY 2 A LOCK 6 A 5 2'Description' A DESCRP R 5 15 A 5 37'Price' A PRICE R 5 44 A 7 2'Warehouse Location' 7 A WHSLOC R 7 22 A 9 2'On Hand' A ONHAND R 9 10 A 9 19'Allocated' 8 A ALLOC R 9 30 A 9 40'Available' A AVAIL R 9 51 A*
Figure 67. Example of the Data Description Specifications for a Display Device File
This display device file contains two record formats: PROMPT and RESPONSE.
1 The attributes for the fields in this file are defined in the DSTREF field reference file.
2 The OVERLAY keyword is used so that both record formats can be used on the same display.
3 Function key 1 is associated with indicator 98, which is used by the programmer to end the program.
4 The PUTRETAIN keyword allows the value that is entered in the ITEM field to be kept in the display. In addition, the ITEM field is defined as an input field by the I in position 38. ITEM is the only input field in these record formats. All of the other fields in the record are output fields since position 38 is blank for each of them.
5 The ERRMSG keyword identifies the error message that is displayed if indicator 61 is set on in the program that uses this record format.
6 The LOCK keyword prevents the work-station user from using the keyboard when the RESPONSE record format is initially displayed.
7 The constants such as 'Description', 'Price', and 'Warehouse Location' describe the fields that are written out by the program.
8 The line and position entries identify where the fields or constants are written on the display.
When a record is passed to a program, the fields are arranged in the order in which they are specified in the DDS. The order in which the fields are displayed is based on the display positions (line numbers and position) assigned to the fields in the DDS. The order in which the fields are specified in the DDS and the order in which they appear on the screen need not be the same.
8.2.2 Function Key Indicators on Display Device Files
The function key indicators, KA through KN and KP through KY are valid for a program that contains a display device WORKSTN file if the associated function key is specified in the DDS.
The function key indicators relate to the function keys as follows: function key indicator KA corresponds to function key 1, KB to function key 2 . . . KX to function key 23, and KY to function key 24.
Function keys are specified in the DDS with the CFxx (command function) or CAxx (command attention) keyword. For example, the keyword CF01 allows function key 1 to be used. When you press function key 1, function key indicator KA is set on in the RPG/400 program. If you specify the function key as CF01 (99), both function key indicator KA and indicator 99 are set on in the RPG/400 program. If the work-station user presses a function key that is not specified in the DDS, the OS/400 system informs the user that an incorrect key was pressed.
If the work-station user presses a specified function key, the associated function key indicator in the RPG/400 program is set on when fields are extracted from the record (move fields logic) and all other function key indicators are set off. If a function key is not pressed, all function key indicators are set off at move fields time. The function key indicators are set off if the user presses the Enter key.
8.2.3 Command Keys on Display Device Files
You can specify the command keys Help, Roll Up, Roll Down, Print, Clear, and Home in the DDS for a display device file with the keywords HELP, ROLLUP, ROLLDOWN, PRINT, CLEAR, and HOME.
Command keys can be processed by an RPG/400 program whenever the RPG/400 compiler processes a READ or an EXFMT operation on a record format for which the appropriate keywords are specified in the DDS. When the command keys are in effect and a command key is pressed, the OS/400 system returns control to the RPG/400 program. If a response indicator is specified in the DDS for the command selected, that indicator is set on and all other response indicators that are in effect for the record format and the file are set off.
If a response indicator is not specified in the DDS for a command key, the following happens:
° For the Print key without *PGM specified, the print function is processed.
° For the Roll Up and Roll Down keys used with subfiles, the displayed subfile rolls up or down, within the subfile. If you try to roll beyond the start or end of a subfile, you get a run-time error.
° For the Print Key specified with *PGM, Roll Up and Roll Down keys used without subfiles, and for the Clear, Help, and Home keys, one of the *STATUS values 1121-1126 is set, respectively, and processing continues.
8.3 Processing WORKSTN Files
This section explains the valid file operation codes for a WORKSTN file.
Subtopics:
8.3.1 EXFMT Operation
The EXFMT operation is a combination of a WRITE followed by a READ to the same record format. If you define a WORKSTN file on the file description specifications as a full-procedural (F in position 16) combined file (C in position 15) that uses externally described data (E in position 19) the EXFMT (execute format) operation code can be used to write and read from the display.
8.3.2 READ Operation
The READ operation is valid for a full-procedural combined file or a full-procedural input file that uses externally described data or program-described data. The READ operation retrieves a record from the display. However, a format must exist at the device before any input operations can occur. This requirement can be satisfied on a display device by conditioning an output record with the 1P indicator, by writing the first format to the device from another program, or, if the read is by record-format name, by using the keyword INZRCD on the record description in the DDS.
8.3.3 WRITE Operation
The WRITE operation writes a new record to a display and is valid for a combined file or an output file. Output specifications and the EXCPT operation can also be used to write to a WORKSTN file. See the RPG/400 Reference for a complete description of each of these operation codes.
Figure 68 shows the valid file operation codes for a WORKSTN file.
________________________________________________________________________ | File-Description Calculation | | Specifications Specifications | | Positions Positions | |______ _________ _______________________________________________________| | 15 | 16 | 28-32 | |______|_________|_______________________________________________________| | I | P/S | CLOSE, ACQ, REL, NEXT, POST, FORCE | |______|_________|_______________________________________________________| | I | P/S | WRITE(1), CLOSE, ACQ, REL, NEXT, POST, FORCE | |______|_________|_______________________________________________________| | I | F | READ, OPEN, CLOSE, ACQ, REL, NEXT, POST | |______|_________|_______________________________________________________| | C | F | READ, WRITE(1), EXFMT(2), OPEN, CLOSE, ACQ, REL, | | | | NEXT, POST, UPDAT(3), CHAIN(3), READC(3) | |______|_________|_______________________________________________________| | O | Blank | WRITE(1), OPEN, CLOSE, ACQ, REL, POST | |______|_________|_______________________________________________________| | Note: (1)The WRITE operation is not valid for a program-described | | file used with a format name. | |________________________________________________________________________| | Note: (2)If the EXFMT operation is used, the file must be externally | | described (an E in position 19 of the file description | | specifications). | |________________________________________________________________________| | Note: (3).For subfile record formats, the UPDAT, CHAIN, and READC | | operations are also valid. | |________________________________________________________________________|
Figure 68. Valid File Operation Codes for a WORKSTN File
8.3.4 WORKSTN file
Figure 69 is a processing chart for WORKSTN files.
Figure 69. Processing Chart for WORKSTN Files
Valid File Operations:
1. CLOSE, FORCE
2. WRITE, CLOSE, FORCE
3. READ, OPEN, CLOSE
4. READ, WRITE, EXFMT, OPEN, CLOSE
5. WRITE, OPEN, CLOSE
6. READ, WRITE, OPEN, CLOSE
7. OPEN, CLOSE
8. READC, CHAIN, WRITE, UPDAT, (valid only for record defined as a subfile)
Notes:
1. Shaded positions must be blank, and positions without entries are program dependent. 2. WRITE operations to a program-described file require a data-structure name in the result field; WRITE operations to a program-described file that uses a format name on output specifications are not valid. 3. Subfile processing is valid only for an externally described file.
8.3.5 Subfiles
Subfiles can be specified in the DDS for a display-device file to allow you to handle multiple records of the same type on the display. (See Figure 70.) A subfile is a group of records that is read from or written to a display-device file. For example, a program reads records from a database file and creates a subfile of output records. When the entire subfile has been written, the program sends the entire subfile to the display device in one write operation. The work-station user can change data or enter additional data in the subfile. The program then reads the entire subfile from the display device into the program and processes each record in the subfile individually.
Records that you want to be included in a subfile are specified in the DDS for the file. The number of records that can be included in a subfile must also be specified in the DDS. One file can contain more than one subfile, and up to 12 subfiles can be active concurrently. Two subfiles can be displayed at the same time.
The DDS for a subfile consists of two record formats: a subfile-record format and a subfile control-record format. The subfile-record format contains the field information that is transferred to or from the display file under control of the subfile control-record format. The subfile control-record format causes the physical read, write, or control operations of a subfile to take place. Figure 71 shows an example of the DDS for a subfile-record format, and Figure 72 in topic 8.3.5.1 shows an example of the DDS for a subfile control-record format.
For a description of how to use subfile keywords, see the DDS Reference.
__________________________________________________________________________________ | | | | | Customer Name Search | | | | Search Code _______ | | | | Number Name Address City State | | | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX | | | | | |__________________________________________________________________________________| |
To use a subfile for a display device file in an RPG/400 program, you must specify the SFILE keyword in positions 54 through 59 on a file description specifications continuation line for the WORKSTN file. The SFILE keyword must be specified on a separate continuation line. The WORKSTN file must be an externally described file (E in position 19).
You use positions 60 through 67 of the continuation line to specify the name of the subfile record format (not the control-record format). Positions 47 through 52 must specify the name of the field that contains the relative record number to be used in processing the subfile.
In an RPG/400 program, relative record number processing is defined as part of the SFILE definition. The SFILE definition implies a full-procedural update file with ADD for the subfile. Therefore, the file operations that are valid for the subfile are not dependent on the definition of the main WORKSTN file. That is, the WORKSTN file can be defined as a primary file or a full-procedural file.
Use the CHAIN, READC, UPDAT, or WRITE operation codes with the subfile record format to transfer data between the program and the subfile. Use the READ, WRITE, or EXFMT operation codes with the subfile control-record format to transfer data between the program and the display device or to process subfile control operations.
Subfile processing follows the rules for relative-record-number processing. The RPG/400 program places the relative-record number of any record retrieved by a READC operation into the field named in positions 47 through 52 of the file description specifications SFILE continuation line. This field is also used to specify the record number that the RPG/400 program uses for WRITE operation to the subfile or for output operations that use ADD. The field name specified in positions 47 through 52 must be defined as numeric with zero decimal positions. The field must have enough positions to contain the largest record number for the file. (See the SFLSIZ keyword in the DDS Reference.) The WRITE operation code and the ADD specification on the output specifications require that a relative-record-number field be specified in positions 47 through 52 of the file description specifications SFILE continuation line.
If a WORKSTN file has an associated subfile, all implicit input operations and explicit calculation operations that refer to the file name are processed against the main WORKSTN file. Any operations that specify a record format name that is not designated as a subfile are processed on the main WORKSTN file.
If you press a specified function key during a read of a non-subfile record, subsequent reads of a subfile record will cause the corresponding function key indicator to be set on again, even if the function key indicator has been set off between the reads. This will continue until a non-subfile record is read from the WORKSTN file.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* AAN01N02N03T.Name++++++RLen++TDpBLinPosFunctions++++++++++++++++++++* A** CUSTOMER NAME SEARCH A REF(DSTREF) 1 A R SUBFIL SFL 2 A TEXT('Subfile Record') A CUST R 7 3 A NAME R 7 10 A ADDR R 7 32 3 A CITY R 7 54 A STATE R 7 77 A*
Figure 71. Data Description Specifications for a Subfile Record Format
The data description specifications (DDS) for a subfile record format describe the records in the subfile:
1 The attributes for the fields in the record format are contained in the field reference file DSTREF as specified by the REF keyword.
2 The SFL keyword identifies the record format as a subfile.
3 The line and position entries define the location of the fields on the display.
Subtopics:
8.3.5.1 Use of Subfiles
Some typical ways you can make use of subfiles include:
° Display only. The work-station user reviews the display.
° Display with selection. The user requests more information about one of the items on the display.
° Modification. The user changes one or more of the records.
° Input only, with no validity checking. A subfile is used for a data entry function.
° Input only, with validity checking. A subfile is used for a data entry function, but the records are checked.
° Combination of tasks. A subfile can be used as a display with modification, plus the input of new records.
The following figure shows an example of data description specifications for a subfile control-record format. For an example of using a subfile in an RPG/400 program, see "WORKSTN File Examples" in topic 8.6.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* AAN01N02N03T.Name++++++RLen++TDpBLinPosFunctions++++++++++++++++++++* A R FILCTL SFLCTL(SUBFIL) A N70 SFLCLR A 70 SFLDSPCTL A 71 SFLDSP A SFLSIZ(15) A SFLPAG(15) A TEXT('Subfile Control Record') A OVERLAY A 71 ROLLUP(97 'Continue Search') A CA01(98 'End of Program') A HELP(99 'Help Key') A 1 2'Customer Name Search' A 3 2'Search Code' A SRHCOD R I 3 14PUTRETAIN A 5 2'Number' A 5 10'Name' A 5 32'Address' A 5 54'City' A 5 76'State' A*
Figure 72. Data Description Specifications for a Subfile Control-Record Format
The subfile control-record format defines the attributes of the subfile, the search input field, constants, and function keys. The keywords you can use indicate the following:
° SFLCTL names the associated subfile (SUBFIL).
° SFLCLR indicates when the subfile should be cleared (when indicator 70 is off).
° SFLDSPCTL indicates when to display the subfile control record (when indicator 70 is on).
° SFLDSP indicates when to display the subfile (when indicator 71 is on).
° SFLSIZ indicates the total number of records to be included in the subfile (15).
° SFLPAG indicates the total number of records in a page (15).
° ROLLUP indicates that indicator 97 is set on in the program when the user presses the Roll Up key.
° HELP allows the user to press the Help key for a displayed message that describes the valid function keys.
° PUTRETAIN allows the value that is entered in the SRHCOD field to be kept in the display.
In addition to the control information, the subfile control-record format also defines the constants to be used as column headings for the subfile record format.
8.4 Program-Described WORKSTN File
You can use a program-described WORKSTN file with or without a format name specified on the output specifications. The format name, if specified, refers to the name of a data description specifications record format. This record format describes:
° How the data stream sent from an RPG/400 program is formatted on the screen ° What data is sent ° What ICF functions to perform.
If a format name is used, input and output specifications must be used to describe the input and output records.
You can specify the PASS option on the file description specifications continuation line for a program-described WORKSTN file. Positions 60 through 65 must contain *NOIND. The PASS *NOIND indicates that the RPG/400 program will not additionally pass indicators to data management on output or receive them on input. It is your responsibility to pass indicators by describing them as fields (in the form *INxx, *IN, or *IN,x) in the input or output record. They must be specified in the sequence required by the data description specifications (DDS). You can use the DDS listing to determine this sequence.
Subtopics:
- 8.4.1 Program-Described WORKSTN File with a Format Name
- 8.4.2 Program-Described WORKSTN File without a Format Name
8.4.1 Program-Described WORKSTN File with a Format Name
The following specifications apply to using a format name for a program-described WORKSTN file.
Subtopics:
- 8.4.1.1 Output Specifications
- 8.4.1.2 Input Specifications
- 8.4.1.3 Calculation Specifications
- 8.4.1.4 Additional Considerations
8.4.1.1 Output Specifications
On the output specifications, you must specify the WORKSTN file name in positions 7 through 14. The format name, which is the name of the DDS record format, is specified as a literal or named constant in positions 45 through 54 on the succeeding field description line. K1 through K8 must be specified (right-adjusted) in positions 40 through 43 on the line containing the format name. The K identifies the entry as a length rather than an end position, and the number indicates the length of the format name. For example, if the format name is CUSPMT, the entry in positions 40 through 43 is K6. (Leading zeros following the K are allowed.) The format name cannot be conditioned (indicators in positions 23 through 31 are not valid).
Output fields must be located in the output record in the same order as defined in the DDS; however, the field names do not have to be the same. The end position entries for the fields refer to the end position in the output record passed from the RPG/400 program to data management, and not to the location of the fields on the screen.
To pass indicators on output, do one of the following:
° Specify the keyword INDARA in the DDS for the WORKSTN file. Do not use the PASS *NOIND option on the file specifications continuation line and do not specify the indicators on the output specifications. The program and file use a separate indicator area to pass the indicators.
° Specify the PASS *NOIND option on the file specifications continuation line. Specify the indicators in the output specifications as fields in the form *INxx. The indicator fields must precede other fields in the output record, and they must appear in the order specified by the WORKSTN file DDS. You can determine this order from the DDS listing.
8.4.1.2 Input Specifications
The input specifications describe the record that the RPG/400 program receives from the display or ICF device. The WORKSTN file name must be specified in positions 7 through 14. Input fields must be located in the input record in the same sequence as defined in the DDS; however, the field names do not have to be the same. The field location entries refer to the location of the fields in the input record.
To receive indicators on input, do one of the following:
° Specify the keyword INDARA in the DDS for the WORKSTN file. Do not use the PASS *NOIND option on the file specifications continuation line and do not specify the indicators on the input specifications. The program and file use a separate indicator area to pass the indicators.
° Specify the PASS *NOIND option on the file specifications continuation line. Specify the indicators in the input specifications as fields in the form *INxx. They must appear in the input record in the order specified by the WORKSTN file DDS. You can determine this order from the DDS listing.
A record identifying indicator should be assigned to each record in the file to identify the record that has been read from the WORKSTN file. A hidden field with a default value can be specified in the DDS for the record identification code.
8.4.1.3 Calculation Specifications
The operation code READ is valid for a program-described WORKSTN file that is defined as a combined, full-procedural file. See Figure 68 in topic 8.3.3. The file name must be specified in factor 2 for this operation. A format must exist at the device before any input operations can take place. This requirement can be satisfied on a display device by conditioning an output record with 1P or by writing the first format to the device in another program (for example, in the CL program). The EXFMT operation is not valid for a program-described WORKSTN file. You can also use the EXCPT operation to write to a WORKSTN file.
8.4.1.4 Additional Considerations
When using a format name with a program-described WORKSTN file, you must also consider the following:
° The name specified in positions 45 through 54 of the output specifications is assumed to be the name of a record format in the DDS that was used to create the file.
° If a Kn specification is present for an output record, it must also be used for any other output records for that file. If a Kn specification is not used for all output records to a file, a run-time error will occur.
For an example of using a format name with a program-described display device WORKSTN file, see "Sample Program 6-Program-Described WORKSTN File with a FORMAT Name on Output Specifications" in topic 8.6.6.
8.4.2 Program-Described WORKSTN File without a Format Name
When a record-format name is not used, a program-described display-device file describes a file containing one record-format description with one field. The fields in the record must be described within the program that uses the file.
When you create the display file by using the Create Display File command, the file has the following attributes:
° A variable record length can be specified; therefore, the actual record length must be specified in the using program. (The maximum record length allowed is the screen size minus one.)
° No indicators are passed to or from the program.
° No function key indicators are defined.
° The record is written to the display beginning in position 2 of the first available line.
Subtopics:
8.4.2.1 Input File
For an input file, the input record, which is treated by the OS/400 device support as a single input field, is initialized to blanks when the file is opened. The cursor is positioned at the beginning of the field, which is position 2 on the display.
8.4.2.2 Output File
For an output file, the OS/400 device support treats the output record as a string of characters to be sent to the display. Each output record is written as the next sequential record in the file; that is, each record displayed overlays the previous record displayed.
8.4.2.3 Combined File
For a combined file, the record, which is treated by the OS/400 device support as a single field, appears on the screen and is both the output record and the input record. Device support initializes the input record to blanks, and the cursor is placed in position 2.
For more information on program-described-display-device files, see the Data Management Guide.
8.5 Multiple-Device Files
Any RPG/400 WORKSTN file with at least one of the keywords ID, IND, NUM, or SAVDS specified (on the file specifications continuation line) is a multiple-device file. Through a multiple-device file, your program may access more than one device.
The RPG/400 program accesses devices through program devices, which are symbolic mechanisms for directing operations to an actual device. When you create a file (using the DDS and commands such as the create file commands), you consider such things as which device is associated with a program device, whether or not a file has a requesting program device, which record formats will be used to invite devices to respond to a READ-by-file-name operation, and how long this READ operation will wait for a response. For detailed information on the options and requirements for creating a multiple-device file, see the chapter on display files in the Data Management Guide, and information on ICF files in the ICF Programmer's Guide, and the manuals you are referred to in these two publications.
With multiple-device files, you make particular use of the following operation codes:
° In addition to opening a file, the OPEN operation can acquire (at most) one device for a multiple-device file. You specify which device when you create the file.
° The ACQ (acquire) operation acquires any other devices for your file.
° The REL (release) operation releases a device from the file.
° The WRITE operation, when used with the DDS keyword INVITE, invites a program device to respond to subsequent read-from-invited- program-devices operations. See the section on inviting a program device in the ICF Programmer's Guide and the Data Management Guide.
° The READ operation either processes a read-from-invited-program-devices operation or a read-from-one-program-device operation. When no NEXT operation is in effect, a program-cycle-read or READ-by-file-name operation waits for input from any of the devices that have been invited to respond (read-from-invited-program-device). Other input and output operations, including a READ-by-file-name after a NEXT operation, and a READ-by-format-name, process a read-from-one-program-device operation using the program device indicated in a special field. (The field is named in the ID entry of the file specifications continuation lines.)
This device may be the device used on the last input operation, a device you specify, or the requesting program device. See the sections on reading from invited program devices and on reading from one program device in the ICF Programmer's Guide and the Data Management Guide.
° The NEXT operation specifies which device is to be used in the next READ-by-file-name operation or program-cycle-read operation.
° The POST operation puts information in the INFDS information data structure. The information may be about a specific device or about the file. (The POST operation is not restricted to use with multiple-device files.)
See the RPG/400 Reference for details of the RPG/400 operation codes.
On the file specifications continuation line, you can specify several options to control the processing of multiple-device files.
° The NUM entry indicates the maximum number of devices that can be acquired for a file.
By using a value of 1 for NUM, it is possible to get functions associated with a multiple-device file for a file that has only one device. For example, Figure 107 in topic 8.6.8 illustrates the use of the time-out feature of the READ operation for a multiple-device file.
° The ID entry specifies the name of a field. The field can contain the name of a program device to which some input and output operations are directed.
When a read-from-one-program-device or WRITE operation is issued, the device used for the operation is the device identified by the field specified in the ID entry. This field is initialized to blanks and is updated with the name of the device from which the last successful input operation occurred. It can also be set explicitly by moving a value to it. The ACQ operation code does not affect the value of this field. If there is no entry, the operation is performed against the device from which the last successful input operation occurred. A blank device name is used if a read operation has not yet been performed successfully from a device.
When a read-from-one-program device or WRITE operation is issued with a blank device name, the RPG/400 compiler implicitly uses the device name of the requestor device for the program. If you call an RPG/400 program interactively and acquire an ICF device against which you want to perform one of these operations, you must explicitly move the device name of the ICF device into the field name specified with the ID entry prior to performing the operation. If this is not done, the device name used will either be blank (in which case the interactive requestor device name is used), or the device name used is the one from the last successful input operation. Once you have performed an I/O operation to the ICF device, you do not need to modify the value again unless an input operation completes successfully with a different device.
° The SAVDS entry indicates a data structure that is saved and restored for each device acquired to a file. The IND entry indicates a set of indicators to be saved and restored for each device acquired to a file. Before an input operation, the current set of indicators and data structure are saved. After the input operation, the RPG/400 compiler restores the indicators and data structure for the device associated with the operation. This may be a different set of indicators or data structure than was available before the input operation.
° The INFDS entry specifies the file information data structure for the WORKSTN file. The RPG/400 *STATUS field and the major/minor return code for the I/O operation can be accessed through this data structure. Particularly when ICF is being used, both fields are useful for detecting errors that occurred during I/O operations to multiple-device files.
Note: When specifying these control options, you must code the NUM option before the ID, IND or SAVDS options.
8.6 WORKSTN File Examples
This section illustrates some common work station applications and their RPG/400 coding.
° "Sample Program 1-Inquiry" in topic 8.6.1 is an example of a basic inquiry program that uses the WORKSTN file in the RPG/400 compiler.
° "Sample Program 2-Data Entry with Master Update" in topic 8.6.2 is an example of a data entry with master update program.
° "Sample Program 3-Maintenance" in topic 8.6.3 is an example of a maintenance program.
° "Sample Program 4-WORKSTN Subfile Processing" in topic 8.6.4 is an example of WORKSTN subfile processing.
Subtopics:
- 8.6.1 Sample Program 1-Inquiry
- 8.6.2 Sample Program 2-Data Entry with Master Update
- 8.6.3 Sample Program 3-Maintenance
- 8.6.4 Sample Program 4-WORKSTN Subfile Processing
8.6.1 Sample Program 1-Inquiry
The following figures illustrate a simple inquiry program using the WORKSTN file:
________________________________________________________________________ | Table 5. List of Figures for WORKSTN Inquiry Program | |__________________________ _____________________________________________| | Figure | Contents | |__________________________|_____________________________________________| | Figure 73 below and | DDS for database file and display device | | Figure 74 | file | |__________________________|_____________________________________________| | Figure 75 | File description and calculation | | | specifications | |__________________________|_____________________________________________| | Figure 76 | Prompt screen | |__________________________|_____________________________________________| | Figure 77 | Customer information screen | |__________________________|_____________________________________________|
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* A..........T.Name++++++RLen++TDpB......Functions++++++++++++++++++++* A* CUSTOMER MASTER FILE -- CUSMSTP A R CUSREC A CUST 5 TEXT('CUSTOMER NUMBER') A NAME 20 TEXT('CUSTOMER NAME') A ADDR 20 TEXT('CUSTOMER ADDRESS') A CITY 20 TEXT('CUSTOMER CITY') A STATE 2 TEXT('CUSTOMER STATE') A ZIP 5 0 TEXT('CUSTOMER ZIP CODE') A SRHCOD 3 TEXT('CUSTOMER NAME SEARCH CODE') A CUSTYP 1 TEXT('CUSTOMER TYPE') A ARBAL 10 2 TEXT('ACCOUNTS RECEIVABLE BALANCE') A******************************************************************** A* FILE NAME : CUSMSTL * A* DESCRIPTION: LOGICAL VIEW OF CUSTOMER MASTER FILE (CUSMSTP) * A* BY CUSTOMER NUMBER (CUST) * A******************************************************************** A..........T.Name++++++.Len++TDpB......Functions++++++++++++++++++++* A R CUSREC PFILE(CUSMSTP) A K CUST
Figure 73. DDS for WORKSTN Inquiry-Program File CUSMSTP
The DDS for the database file used by this program describe one record format: CUSREC. The logical file CUSMSTL keyed by customer number is based on the physical file CUSMSTP, as indicated by the PFILE keyword. Each field in the record format is defined in the physical file CUSMSTP.
Note: Normally, the field attributes, such as the number of decimal positions and the data type, are defined in a field-reference file rather than in the DDS for the record format. The attributes are shown on the DDS so you can see what they are.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* A******************************************************************** A* FILE NAME : CUSFMT * A* DESCRIPTION: DISPLAY FILE FOR CUSTOMER MASTER INQUIRY * A******************************************************************** AAN01N02N03T.Name++++++RLen++TDpBLinPosFunctions++++++++++++++++++++* A DSPSIZ(24 80 *DS3) A CHGINPDFT(CS) A CA03(15 'END OF JOB') A PRINT A INDARA A R CUSHDG A OVERLAY A 2 4TIME A DSPATR(HI) A 2 29'Customer Master Inquiry' A DSPATR(HI) A DSPATR(UL) A 2 70DATE A EDTCDE(Y) A DSPATR(HI) A R CUSFTG A 23 20'ENTER - Continue' A DSPATR(HI) A 23 49'F3 - End Job' A DSPATR(HI) A R CUSPMT A OVERLAY A CUST 5A I 10 50DSPATR(HI) A DSPATR(CS) A 99 ERRMSG('Customer Number not Found' A 99) A 10 26'Enter Customer Number:' A DSPATR(HI)
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* AAN01N02N03T.Name++++++RLen++TDpBLinPosFunctions++++++++++++++++++++* A R CUSFLDS A OVERLAY A 8 25'Name' A NAME 20A O 8 35DSPATR(HI) A 10 25'Address' A ADDR 20A O 10 35DSPATR(HI) A 12 25'City' A CITY 20A O 12 35DSPATR(HI) A 14 25'State' A STATE 2A O 14 35DSPATR(HI) A 14 41'Zip Code' A ZIP 5S 0O 14 50DSPATR(HI) A 16 25'A/R Balance' A ARBAL 10Y 2O 16 42DSPATR(HI) A EDTCDE(J) A 6 25'Customer' A CUST 5A O 6 35DSPATR(HI)
Figure 74. DDS for WORKSTN Inquiry-Program Display Device File CUSFMT
The DDS for the display device file CUSFMT to be used by this program specify file level entries and describe four record formats: CUSHDG, CUSFTG, CUSPMT, and CUSFLDS.
The file level entries define the screen size (DSPSIZ), input defaults (CHGINPDFT), command attention key used to end the program, print key (PRINT), and a separate indicator area (INDARA).
The CUSHDG record format contains the constant 'Customer Master Inquiry', which identifies the display. It also contains the keywords TIME and DATE, which will display the current date and time on the screen.
The CUSFTG record format contains the constants 'ENTER - Continue' and 'F3 - End Job', which describe the processing options.
The CUSPMT record format contains the prompt "Enter Customer Number:" and the input field CUST into which the workstation user enters the customer number. Column separators define the input field on the screen where the user is to enter the customer number. The error message "Customer Number not Found" is also included in this record format. This message is displayed if indicator 99 is set on by the program.
The CUSFLDS record format contains the constants 'Name', 'Address', 'City', 'State', 'Zip Code', 'A/R Balance', and 'Customer' that identify the fields to be written out from the program. This record format also describes fields that correspond to these constants. All of these fields are described as output fields because they are filled in by the program; the user does not enter any data into these fields. To enter another customer number, the user presses Enter in response to this record.
In addition to describing the constants, fields and attributes for the screen, the record formats also define the display attributes for the constants and fields and the line numbers and horizontal positions where the constants and fields are to be displayed.
Notice the use of the OVERLAY keyword; the CUSHDG, CUSPMT and CUSFLDS record formats will overlay the CUSFTG record format. The CUSFTG format will remain on the screen when any of the other formats are written to the screen.
Note: Normally, the field attributes are defined in a field-reference file instead of the DDS for a file. However, they are shown here so you can see the field attributes.
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* F******************************************************************** F* PROGRAM ID - CUSTINQ * F* PROGRAM NAME - CUSTOMER MASTER INQUIRY * F******************************************************************** FFilenameIPEAF....RlenLK1AIOvKlocEDevice+......KExit++Entry+A....U1.* FCUSMSTL IF E K DISK FCUSFMT CF E WORKSTN
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++* C *IN15 DOWEQ'0' C* C* WRITE HEADING AND FOOTING EXCEPT IF ERROR HAS OCCURRED C* AND PROMPT FOR CUSTOMER NUMBER C *IN99 CASEQ'0' HEADNG C END C EXFMTCUSPMT C* IF NOT END OF JOB AND VALID CUSTOMER NUMBER C* DISPLAY CUSTOMER INFORMATION C *IN15 IFEQ '0' C CUST CHAINCUSREC 99 C *IN99 IFEQ '0' C EXFMTCUSFLDS C END IF C END IF C END DO C MOVE '1' *INLR C******************************************************************** C* SUBROUTINE - HEADNG * C* PURPOSE - DISPLAY HEADING AND FOOTING * C******************************************************************** C HEADNG BEGSR C WRITECUSFTG C WRITECUSHDG C ENDSR
Figure 75. File Description and Calculation Specifications for WORKSTN Inquiry Program
For this program, only the RPG/400 file description and calculation specifications are required. Input and output specifications are not required because both files are externally described files (as indicated by the E in position 19). Both files are described as full-procedural files, as indicated by the F in position 16, because the I/O operations are controlled by programmer-specified operation codes. In addition, the K in position 31 of the file description specifications for the CUSMSTL file indicates that the file is processed keys.
The DOWEQ operation performs a loop until the user presses F3 to end the job. F3 sets indicator 15 on, as defined in the DDS. If indicator 15 is on, the loop is ended, the LR indicator is turned on, and the program ends.
The CASEQ operation performs subroutine HEADNG, which writes the heading and footings to the screen. Headings and footings will not be written to the screen when an error has occurred.
The EXFMT operation writes the CUSPMT record to the display. This record prompts the user to enter a customer number. If the user enters a customer number and presses Enter, the same EXFMT operation then reads the record back into the program.
If the user does not end the job, the CHAIN operation retrieves a record from the CUSMSTL file. Note that the record format name CUSREC is specified for the CHAIN operation rather than the file name. If the record is not found, indicator 99 is set on and the program loops back to display the CUSPMT record again. The message Customer Number not Found is displayed, the ERRMSG keyword in the DDS is conditioned by indicator 99, and the keyboard is locked. The user must press the Reset key in response to this message to unlock the keyboard. The user can then enter another customer number.
If the CHAIN operation retrieves a record from the CUSMSTL file, the EXFMT operation writes the record CUSFLDS to the display work station. This record contains the customer's name, address information, and accounts receivable balance.
The user then presses Enter, and the program loops back to the EXFMT operation and writes record CUSPMT to the display work station. The user can enter another customer number or end the program.
Figure 76 is the initial display written to the display WORKSTN by the EXFMT.
__________________________________________________________________________________ | | | | | 10:06:31 Customer Master Inquiry 01/25/94 | | | | | | | | | | | | | | | | Enter Customer Number: ___A1 | | | | | | | | | | | | | | | | | | | | | | | | | | ENTER - Continue F3 - End Job | | | | | |__________________________________________________________________________________| |